1    /* 
     2     *  Copyright (c) 2008 Texas Instruments and others.
     3     *  All rights reserved. This program and the accompanying materials
     4     *  are made available under the terms of the Eclipse Public License v1.0
     5     *  which accompanies this distribution, and is available at
     6     *  http://www.eclipse.org/legal/epl-v10.html
     7     * 
     8     *  Contributors:
     9     *      Texas Instruments - initial implementation
    10     * 
    11     * */
    12    package xdc.tools.cdoc;
    13    
    14    /*!
    15     * XDCspec doc markup language examples
    16     *
    17     * This module demonstrates the features of XDCspec doc and gives usage
    18     * examples for the XDCspec doc markup language. View the source text of this
    19     * .xdc file for details on how to use these examples.
    20     * 
    21     * @a(HEADINGS)
    22     * Major headings can be inserted into the document using the following
    23     * syntax:
    24     * @p(code)
    25     *    @@tag(headingText)
    26     * @p
    27     *
    28     * The available tags are:
    29     * @p(dlist)
    30     *    - `@@a(headingText)`
    31     *      Add a heading to the end ("a" for "after") of the details section.
    32     *    - `@@b(headingText)`
    33     *      Add a heading to the start ("b" for "before") of the details section.
    34     * @p
    35     *
    36     * Since XDCtools 3.05, @@a and @@b tags can accept space characters in headings.
    37     * Prior to this, heading text could contain no spaces.
    38     *
    39     * @a(PARAGRAPH FORMATTING)
    40     * Paragraphs can be marked in several different styles using the
    41     * following syntax:
    42     * @p(code)
    43     * @@p(style)
    44     *  paragraph text here...
    45     *
    46     *  another paragraph...
    47     * @@p
    48     * @p
    49     *
    50     * The available paragraph styles are:
    51     * @p(dlist)
    52     *    - `@@p(text) or @@p`
    53     *       Plain text -- this is the default.
    54     *    - `@@p(code)`
    55     *       Fragments of source code or pseudo-code. Paragraphs of this
    56     *       type are rendered in a fixed-width font.
    57     *    - `@@p(html)`
    58     *       HTML markup. Paragraphs of this type are copied directly into the
    59     *       XDCspec doc output, with no interpretation.
    60     * @p
    61     *
    62     * @a(CHARACTER FORMATTING)
    63     *
    64     * @a(LIST TYPES)
    65     * Lists in several styles can be created using the syntax:
    66     * @p(code)
    67     * @@p(style)
    68     *  - first list item
    69     *    continued...
    70     *  - second list item
    71     * @@p
    72     * @p
    73     * The available list styles are bulleted list, numbered list, and
    74     * definition list, and they look like this:
    75     * @p(blist)
    76     *    -  The `blist` bulleted list style is an unnumbered, unordered list
    77     *    -  Rendered using the HTML `<UL>` element.
    78     * @p
    79     * @p(nlist)
    80     *    - The `nlist` numbered list style is an ordered, numbered list
    81     *    - Rendered using the HTML `<OL>` element.
    82     * @p
    83     * @p(dlist)
    84     *    - `Definition List`
    85     *       The `dlist` definition list style has a minor heading for
    86     *       each item in the list
    87     *    - `Rendering`
    88     *       Rendered using the HTML `<DL>` element.
    89     * @p
    90     *
    91     * @a(CDOC HYPERLINKS)
    92     * HTML hyperlinks between XDCspec doc pages can be inserted using the
    93     * `{@link}` inline keyword. `link` takes as a parameter the name of an XDCspec
    94     * element, and optionally some additional formatting text. The
    95     * XDCspec element can name a package, a module or interface, or a
    96     * declaration within a module or interface. The general syntax is:
    97     * @p(code)
    98     *    {@@link [pkgName.][modName][#decl][suffText] [altText]}
    99     * @p
   100     * where:
   101     * @p(dlist)
   102     *    - `pkgName`
   103     *       is the name of a package.
   104     *    - `modName`
   105     *       is the name of a module or interface within the package.
   106     *    - `decl`
   107     *       is the name of a declaration within the module or interface,
   108     *       for example a function or config parameter.
   109     *       Note that `decl` is delimited by a '`#`' character to distinguish
   110     *       it from the name of a package, module or interface.
   111     *    - `suffText`
   112     *       is text to be appended to the text of the link. For example, '`()`'
   113     *       might be appended to denote a void function. The suffix text must
   114     *       contain no spaces.
   115     *    - `altText`
   116     *       is alternate text to be used instead of the XDCspec name of the
   117     *       link target.
   118     * @p
   119     * 
   120     * @p(html)
   121     * <table cellSpacing="2" cellPadding="2" width="100%" border="1">
   122     *   <tbody>
   123     *   <tr>
   124     *     <th><B>Write this:</B></th>
   125     *     <th><B>To reference this:</B></th></tr>
   126     *   <tr>
   127     *     <td>{@@link <i>pkgName</i>}</td>
   128     *     <td>a package</td></tr>
   129     *   <tr>
   130     *     <td>{@@link <i>pkgName</i>.<i>moduleName</i>}</td>
   131     *     <td>a module</td></tr>
   132     *   <tr>
   133     *     <td>{@@link <i>moduleName</i>}</td>
   134     *     <td>a module in the same package</td></tr>
   135     *   <tr>
   136     *     <td>{@@link <i>pkgName</i>.<i>moduleName</i>#<i>declName</i>}</td>
   137     *     <td>a decl in a module</td></tr>
   138     *   <tr>
   139     *     <td>{@@link <i>moduleName</i>#<i>declName</i>}</td>
   140     *     <td>a decl in the same package</td></tr>
   141     *   <tr>
   142     *     <td>{@@link #<i>declName</i>}</td>
   143     *     <td>a decl in the same module</td></tr>
   144     *   <tr>
   145     *     <td>{@@link #<i>declName</i>(<i>arg1</i>,<i>arg2</i>)}</td>
   146     *     <td>a function with explicit args given in <i>suffText</i></td></tr>
   147     *   <tr>
   148     *     <td>{@@link #<i>declName</i> defined here}</td>
   149     *     <td>a decl with the explicit link text "defined here"</td></tr>
   150     *   </tbody>
   151     * </table>
   152     * @p
   153     *
   154     * Examples are:
   155     * @p(dlist)
   156     *    - {@link Example#AStruct}
   157     *    - {@link xdc.tools.cdoc.Example}
   158     *    - {@link Example#AStruct a struct with alternate text}
   159     * @p
   160     *
   161     * @see Example#AStruct
   162     *
   163     * @a(EXTERNAL HTML LINKS)
   164     * Documentation can also include HTML hyperlinks to web sites, using
   165     * the syntax:
   166     * @p(code)
   167     *    {@@link http://serverName/pathName[#anchor] [altText]}
   168     * @p
   169     * The URL must include a resource type, typically "http:" or "ftp:".
   170     *
   171     * Examples are:
   172     * @p(dlist)
   173     *    - {@link http://ti.com}
   174     *    - {@link http://ti.com Texas Instruments}
   175     * @p
   176     *
   177     * @a(LINKING TO OTHER DOCUMENTATION FILES)
   178     * It is possible to deliver other documentation files along with a
   179     * package, and link to it from XDCspec doc. The documentation files must
   180     * be placed in a subdirectory of the package with the name `'doc-files'`.
   181     * Hyperlinks to files in this directory are created using the syntax:
   182     * @p(code)
   183     *    {@@link ./doc-files/filename[#anchor] [altText]}
   184     *    {@@link pkgDir/doc-files/fileName[#anchor] [altText]}
   185     * @p
   186     *
   187     * The file name is specified using the same syntax as the `xdc.findFile()`
   188     * function. That is, filenames within the current package must begin with "./".
   189     * Links to files in other packages must use the fully qualified package name,
   190     * with slashes ('/') instead of dots ('.') in the name.
   191     *
   192     * @p(html)
   193     * <table cellSpacing="2" cellPadding="2" border="1">
   194     *   <tbody>
   195     *   <tr>
   196     *     <th><B>Write this:</B></th>
   197     *     <th><B>To reference this:</B></th></tr>
   198     *   <tr>
   199     *     <td>{@@link ./doc-files/<i>filename</i> }</td>
   200     *     <td>a file in the current package</td></tr>
   201     *   <tr>
   202     *     <td>{@@link <i>pkgDir</i>/doc-files/<i>filename</i> }</td>
   203     *     <td>a file in another package</td></tr>
   204     *   </tbody>
   205     * </table>
   206     * @p
   207     *
   208     * Examples are:
   209     * @p(dlist)
   210     *    - {@link ./doc-files/example.html}
   211     *    - {@link xdc/tools/cdoc/doc-files/example.html}
   212     * @p
   213     *
   214     * @a(LINKING TO DOXYGEN DOCUMENTATION)
   215     * It is possible to link to Doxygen documentation.
   216     * Hyperlinks to are created using the syntax:
   217     * @p(code)
   218     *    {@@link doxy(name)}
   219     * @p
   220     * In a SEE section use:
   221     * @p(code)
   222     *    doxy(name)
   223     * @p
   224     *
   225     * @p(html)
   226     * <table cellSpacing="2" cellPadding="2" border="1">
   227     *   <tbody>
   228     *   <tr>
   229     *     <th><B>To link to:</B></th>
   230     *     <th><B>Use:</B></th>
   231     *     <th><B>Example:</B></th></tr>
   232     *   <tr>
   233     *     <td>File</td>
   234     *     <td><i>filePrefix</i><B>.</B><i>fileSuffix</i></td>
   235     *     <td>doxy(Engine.h)</td></tr>
   236     *     <td>Function</td>
   237     *     <td><i>functionName</i><B>()</B></td>
   238     *     <td>doxy(Engine_open())</td></tr>
   239     *     <td>#define</td>
   240     *     <td><B>#</B><i>defineName</i></td>
   241     *     <td>doxy(#Engine_GTNAME)</td></tr>
   242     *     <td>Struct</td>
   243     *     <td><i>structName</i></td>
   244     *     <td>doxy(IALG_Fxns)</td></tr>
   245     *     <td>Struct field</td>
   246     *     <td><i>structName</i><B>::</B><i>structField</i></td>
   247     *     <td>doxy(IALG_Fxns::algAlloc)</td></tr>
   248     *     <td>Enum</td>
   249     *     <td><i>enumName</i></td>
   250     *     <td>doxy(IALG_MemAttrs)</td></tr>
   251     *     <td>Enumerator</td>
   252     *     <td><i>enumName</i><B>::</B><i>enumerator</i></td>
   253     *     <td>doxy(IALG_MemAttrs::IALG_PERSIST)</td></tr>
   254     *     <td>Typedef</td>
   255     *     <td><B>::</B><i>typedefName</i></td>
   256     *     <td>doxy(::Engine_Handle)</td></tr>
   257     *     <td>Variable</td>
   258     *     <td><B>#</B><i>variableName</i></td>
   259     *     <td>doxy(#Engine_ATTRS)</td></tr>
   260     *   </tbody>
   261     * </table>
   262     * @p
   263     *
   264     * See xdc.tools.cdoc usage for how to specify the location of the Doxygen files.
   265     *
   266     */
   267    metaonly module Markup {
   268    }
   269    /*
   270     *  @(#) xdc.tools.cdoc; 1, 0, 0,371; 3-20-2014 17:06:48; /db/ztree/library/trees/xdc/xdc-A32x/src/packages/
   271     */
   272