metaonly module xdc.tools.cdoc.Markup
index URL

XDCspec doc markup language examples

This module demonstrates the features of XDCspec doc and gives usage examples for the XDCspec doc markup language. View the source text of this .xdc file for details on how to use these examples. [ more ... ]
XDCscript usage meta-domain sourced in xdc/tools/cdoc/Markup.xdc
var Markup = xdc.useModule('xdc.tools.cdoc.Markup');
 
DETAILS
This module demonstrates the features of XDCspec doc and gives usage examples for the XDCspec doc markup language. View the source text of this .xdc file for details on how to use these examples.
HEADINGS
Major headings can be inserted into the document using the following syntax:
    @tag(headingText)
The available tags are:
@a(headingText)
Add a heading to the end ("a" for "after") of the details section.
@b(headingText)
Add a heading to the start ("b" for "before") of the details section.
Since XDCtools 3.05, @a and @b tags can accept space characters in headings. Prior to this, heading text could contain no spaces.
PARAGRAPH FORMATTING
Paragraphs can be marked in several different styles using the following syntax:
 @p(style)
  paragraph text here...

  another paragraph...
 @p
The available paragraph styles are:
@p(text) or @p
Plain text -- this is the default.
@p(code)
Fragments of source code or pseudo-code. Paragraphs of this type are rendered in a fixed-width font.
@p(html)
HTML markup. Paragraphs of this type are copied directly into the XDCspec doc output, with no interpretation.
CHARACTER FORMATTING
LIST TYPES
Lists in several styles can be created using the syntax:
 @p(style)
  - first list item
    continued...
  - second list item
 @p
The available list styles are bulleted list, numbered list, and definition list, and they look like this:
  • The blist bulleted list style is an unnumbered, unordered list
  • Rendered using the HTML <UL> element.
  1. The nlist numbered list style is an ordered, numbered list
  2. Rendered using the HTML <OL> element.
Definition List
The dlist definition list style has a minor heading for each item in the list
Rendering
Rendered using the HTML <DL> element.
CDOC HYPERLINKS
HTML hyperlinks between XDCspec doc pages can be inserted using the inline keyword. link takes as a parameter the name of an XDCspec element, and optionally some additional formatting text. The XDCspec element can name a package, a module or interface, or a declaration within a module or interface. The general syntax is:
    {@link [pkgName.][modName][#decl][suffText] [altText]}
where:
pkgName
is the name of a package.
modName
is the name of a module or interface within the package.
decl
is the name of a declaration within the module or interface, for example a function or config parameter. Note that decl is delimited by a '#' character to distinguish it from the name of a package, module or interface.
suffText
is text to be appended to the text of the link. For example, '()' might be appended to denote a void function. The suffix text must contain no spaces.
altText
is alternate text to be used instead of the XDCspec name of the link target.
Write this: To reference this:
{@link pkgName} a package
{@link pkgName.moduleName} a module
{@link moduleName} a module in the same package
{@link pkgName.moduleName#declName} a decl in a module
{@link moduleName#declName} a decl in the same package
{@link #declName} a decl in the same module
{@link #declName(arg1,arg2)} a function with explicit args given in suffText
{@link #declName defined here} a decl with the explicit link text "defined here"
Examples are:
Example.AStruct
xdc.tools.cdoc.Example
a struct with alternate text
SEE
Example.aStruct
EXTERNAL HTML LINKS
Documentation can also include HTML hyperlinks to web sites, using the syntax:
    {@link http://serverName/pathName[#anchor] [altText]}
The URL must include a resource type, typically "http:" or "ftp:".
Examples are:
http://ti.com
Texas Instruments
LINKING TO OTHER DOCUMENTATION FILES
It is possible to deliver other documentation files along with a package, and link to it from XDCspec doc. The documentation files must be placed in a subdirectory of the package with the name 'doc-files'. Hyperlinks to files in this directory are created using the syntax:
    {@link ./doc-files/filename[#anchor] [altText]}
    {@link pkgDir/doc-files/fileName[#anchor] [altText]}
The file name is specified using the same syntax as the xdc.findFile() function. That is, filenames within the current package must begin with "./". Links to files in other packages must use the fully qualified package name, with slashes ('/') instead of dots ('.') in the name.
Write this: To reference this:
{@link ./doc-files/filename } a file in the current package
{@link pkgDir/doc-files/filename } a file in another package
Examples are:
./doc-files/example.html
xdc/tools/cdoc/doc-files/example.html
LINKING TO DOXYGEN DOCUMENTATION
It is possible to link to Doxygen documentation. Hyperlinks to are created using the syntax:
    {@link doxy(name)}
In and SEE section use:
    doxy(name)
To link to: Use: Example:
File filePrefix.fileSuffix doxy(Engine.h)
Function functionName() doxy(Engine_open())
#define #defineName doxy(#Engine_GTNAME)
Struct structName doxy(IALG_Fxns)
Struct field structName::structField doxy(IALG_Fxns::algAlloc)
Enum enumName doxy(IALG_MemAttrs)
Enumerator enumName::enumerator doxy(IALG_MemAttrs::IALG_PERSIST)
Typedef ::typedefName doxy(::Engine_Handle)
Variable #variableName doxy(#Engine_ATTRS)
See xdc.tools.cdoc usage for how to specify the location of the Doxygen files.
generated on Tue, 24 Aug 2010 15:39:20 GMT