Difference between revisions of "Documentation/DevGuide/AppendixB/Special Markups"

Revision as of 23:19, 14 June 2014

These markup tags are evaluated by the XSL processor that generates a layout version of the documentation, that is, into HTML or XHTML. These tags have to be well formed and in pairs with exactly the same upper and lowercase, as well.

To accentuate identifiers in the generated documentation and generate hyperlinks automatically when building the cross-reference table and checking consistency, all identifiers have to be marked up. Additionally, it is important for proofreading, because a single-word method name cannot be distinguished by a verb. Identifiers have to be excluded from re-editing by the proofreading editor.

The following markups are used:

<atom>

This markup is used for identifiers of atomar types, such as long, short, and string. If a sequence or array of the type is referred to, add the attribute dim with the number of bracket-pairs representing the number of dimensions.

Example:

 <atom>long</atom>

For an example of sequences, see <type>.

<type>

This markup is used for identifiers of interfaces, services, typedefs, structs, exceptions, enums and constants-groups. If a sequence or array of the type is referred to, add the attribute dim with the number of bracket-pairs representing the number of dimensions.

Example:

  <nowiki><type scope="com::sun::star::uno">XInterface</type>
 <type dim="[][]">PropertyValue</type></nowiki>

<member>

This markup substitutes the deprecated method, field and property markups, and is used for fields of structs and exceptions, properties in service specifications and methods of interfaces.

Example:

 <member scope="com::sun::star::uno">XInterface::queryInterface()</member>

<const>

This markup is used for symbolic constant identifiers of constant groups and enums.

Example:

 <const scope="...">ParagraphAdjust::LEFT</const>

<TRUE/>, <FALSE/>

These markups represent the atomic constant for the boolean values TRUE and FALSE.

Example:

 @returns
 <TRUE/> if the number is valid, otherwise <FALSE/>.

<NULL/>

This markup represents the atomic constant for a NULL value.

<void/>

This markup represents the atomic type void. This is identical to <atom>void</atom>.

<code>

This markup is used for inline code.

Example:

Use <code>queryInterface( NULL )</code> for:

 <listing>
  This markup is used for multiple line code examples.
  Example:
  @example StarBASIC
  <listing>
  aCmp = StarDesktop.loadComponentFromURL( ... )
  if ( isnull(aCmp) )
  ....
  endif
  </listing>