Documentation language

Next: Invoking d4c&b  Prev: Generic documentation comments

Text alone is obviously not sufficient to write effective documentation. I choose texinfo as the underlying language for d4c&b because texinfo is an existing language for writing documentation, is reasonably readable, and not tied to any particular display implementation. You can learn more about texinfo from inside emacs info, or from the html version of `texinfo.texi', converted to HTML by d4c&b itself.

Naturally d4c&b is not a texinfo clone. Some texinfo commands don't make sense in d4c&b, while some commands have different syntax and/or semantics, and there are few new commands. The previous chapter discussed the meaning of @top and @chapter in d4c&b, and that their text may be omitted to specify the default section.

The next sections discuss the most important differences between d4c&b and texinfo.

Referencing

The ability to cross reference is undoubtedly d4c&b most important feature. However, d4c&b @ref has different syntax and semantics. A `@ref' may reference any element that can be auto documented, and directories, files, topics, chapters, sections, subsection, etc. can be referenced as well.

@ref format

Unlike texinfo @ref, d4c&b version takes one or two arguments. The first is an element, the second is the reference text. (with only one argument, it serves as both). Here are some examples.

referencing a Source Output
@top @ref{Documentation for C++ and Beyond} Documentation for C++ and Beyond
@chapter @ref{Generic documentation comments} Generic documentation comments
@section @ref{Documenting elements} Documenting elements
@ref{Documenting elements,elements} elements
directory @ref{texi} texi
file @ref{src/libgen/spaces.h} src/libgen/spaces.h
@ref{src/libgen/spaces.h,spaces} spaces
class @ref{StringIterator} StringIterator
method @ref{StringIterator::abort} StringIterator::abort
member @ref{StringIterator::str} StringIterator::str

@ref special considerations

Reference element is simple text, not texinfo code. For example, the reference to 
@section The @code{@@subsection} Command
is `@ref{The @subsection Command}'. The sole exception is @value{...}, which remains a texinfo command.

Reference text is texinfo code - for example `@ref{@top, The @@top command}'.

When reference target contains a `,', you need to quote it. For example, `@ref{Indicating Definitions@, Commands@, etc.}', is a single argument reference.

To keep references to ``C++'' templates and overloaded functions simple, commas inside balanced pairs of `()' or `<>' don't start the second argument. For example, both `@ref{f(int,int)}' and `@ref{X<T,U>}' are single argument references.

Other texinfo references

d4c&b supports @pxref and @xref, which are just shorthands for `See @ref{...}'.

Referencing arbitrary locations

A reference to an arbitrary location is possible as well. A `@node' line acts as the reference target. For example

@node lets go here

...

@ref{lets go here}

Referencing elements in other directories

In some cases a referenced element is in a different directory than that of the reference. In that case a directory may be given explicitly, enclosed in parenthesis in front of the reference [1]. A directory may be relative to the source file it is in or start from the top of the documentation hierarchy.

In fact, the source for the last example is @ref{(src/libgen)StringIterator::str}.

There are two ways to tell d4c&b to search automatically in other directories. One is by the -I command line argument, the other with a @refs directive.

Resolving ambiguities

If more than one element matches a reference, d4c&b tries to rank the elements. An element in the same file is better than elements in other files, and an element in the same directory is better than an element in another directory [2]. If the highest rank has two or more elements, d4c&b issues an error message listing all alternatives.

You need to choose one of them and either add the appropriate directory name (See Referencing elements in other directories), or if the two references are in the same directory, be more specific and specify a file name as well. For example, @ref{(src/libgen/str_itr.h)StringIterator::str}

In some cases, d4c&b will prefer some elements over others. A top or chapter are better than a section with the same name, and a @node is better than the any of them Such conflicts should not exist in documentation written for d4c&b, but are common in existing texinfo files.

Sectioning commands

d4c&b supports @section, @subsection, ... in any d4c&b comment, but they probably make more sense in a chapter or a top level entry.

Enhanced commands

@multitable extensions

  1. @multitable additional setup options

    @multitable @border
    Make table frame visible.

    @multitable @center
    Align items in center of table cells.

    @multitable @colalign{cols}
    Align columns as given by cols. cols is a list of `left',`right',`center' or `none'. Columns beyond list use alignment of last the column.

    @multitable @rowalign{row}
    Align rows as given by row. row is one of `top',`bottom' or `center'.

  2. @multitable Header and Caption

    A multitable may contain a caption and a header.

    source result 
    @multitable
@caption example table
@header name @tab   description
@item   f    @tab   function
@item   v    @tab   variables
@end multitable
    example table
    name description
    f function
    v variables

  3. Tabs as cells separators

    In d4c&b, one or more tabs (`\t') are the same as a @tab.

  4. Nested Multitables

    Nested multitables are supported.

@enumerate settings

To enumerate in Roman numbers, use `@i' or `@I'.

source result 
@enumerate @i
@item first
@item second
@end enumerate
  1. first
  2. second

When nesting simple lists, use `@nested' to obtain full numbering in the nested list.

source result 
@enumerate
@item first
@enumerate @nested
@item nested 1
@item nested 2
@end enumerate
@item second
@end enumerate
  1. first

    1.1  nested 1
    1.2  nested 2
  2. second

simple itemize

An @itemize line does not require an itemization character.

source result 
@itemize
@item first
@item second
@end itemize
  • first
  • second

@center section

In d4c&b, several lines may be centered with one @center command

@center
text

more text
@end center
produces

text

more text

Relaxing @end ...

In d4c&b, you may write `@end' instead of `@end table', `@end enumerate' etc. d4c&b will automatically determine which @end it is.

Two notable exceptions are `@end ignore' and `@end cartouche'.

Math modes

There are 3 related methods to incorporated mathematical equations with your text. @eqn is for small, inline equations, while @math or TTH (inside a `@tex $$ ... $$ @end tex' section) are for bigger equations.

Note, however, that TTH is not under the GPL and requires an additional license for commercial usage.

The texinfo manual has very little to say about the @math command. d4c&b math commands support a subset of latex equation language, where the texinfo escape character `@' replaces latex `\'.

Since native support for mathematical formulas does not yet exist in Netscape, one has to fake it one way or the other. The result is not always pleasing to the eyes, especially in big and complex formulas. I hope the situation will improve when Netscape has native support for MathML tags.

@eqn command

The @eqn command supports only a small number of basic operations (described below), but combined with Greek symbols and other d4c&b commands it is nevertheless quite useful.

 
d4c&b source Output
subscript @eqn{a_k} ak
superscript @eqn{a^k} ak
prime @eqn{x'} x¢
@eqn{x''} x²
You may group elements together with a pair of `{}'. For example, `@eqn{a_{k,i}}' generates ak,i. To insert a special character, quote it using a `@'. For example `@eqn{a@_i}' generates a_i.

@math command

@math is more powerful than @eqn, but the result (at least in HTML) will usually appear separated from the text around it.

The various features of the @math command are shown in the examples below. You might want to read WebEQ 2.0 documentation, and have a look at the TTH output as well.

@smallmath command

The @smallmath command supports the same capabilities as @math, but will generate an inline equation just like @eqn.

@math examples

Subscripts and Superscripts

code equation
x_i xi
x^2 x2
x_3^2
x2
3

Sums, Unions, Integrals

source equation
@sum x å x

@sum_{i=0}^n x_i
n
å
i=0		xi

@bigcap_i x_i
 
Ç
i 		xi

@int_{-@infty}^{+@infty} f(x) dx
ó
õ		+¥

-¥		 f(x) dx

@mathop{MAX}_i x_i
 
MAX
i 		xi

Placement

source equation
x @over y
x
y

x @atop y
x
y

Parenthesis

source equation
(x @over y)
æ
ç
è
x
y
ö
÷
ø

@left(x @over y @right)
æ
ç
è
x
y
ö
÷
ø

@left [ x @over y @right ]
é
ê
ë
x
y
ù
ú
û

@left { x @over y @right }
ì
í
î
x
y
ü
ý
þ

@left @lfloor x @over y @right @rfloor
ê
ê
ë
x
y
ú
ú
û

@left @lceil x @over y @right @rceil
é
ê
ê
x
y
ù
ú
ú

@left @frac{x}{y} @right|_{x=0}
x
y
 ú
ú
ú


x=0

d(x) = @left @{ 0 if x<=0 @atop 1 if x>0 @right
d(x) =
ì
í
î
 0 if x £ 0
1 if x > 0

Arrays

source equation
@array{ 1 & 0 @@ 0 & 1 }
1 0
0 1

Math functions

source equation
@cos(2@pi{}x) cos(2px)

@func{id}(x) id(x)

@sqrt{x + y}
  ____
Öx + y
 

@sqrt{x @over y}
  æ
 æ 
Ö   
x
y

Overhead bar

source equation
@bar x
_
x
 

@bar x+y
_
x
 		+y

@bar{x+y}
____
x+y
 

@bar{@bar{x+y}}
_____
____
x+y
 
 

Classical examples

source equation
x = {-b @pm @sqrt{b^2 - 4ac} @over 2a}

x =
-b ±   ________
Öb2 - 4ac
 
2a

@chi^2 = @sum_{i=1}^N
   @left (y_i - (a + b x_i)
   @over @sigma_i@right)^2
c2 =
N
å
i=1
æ
ç
è
yi - (a + b xi)
si
ö
÷
ø
2


Math convenience shorthands

@eqn and @math support several convenient shorthands.

source shorthand for symbol
* @times ×
|| @lor Ú
&& @land Ù
<= @leq £
>= @gte ³
!= @neq ¹
== @equiv º
source shorthand for symbol
-> @rightarrow ®
<- @leftarrow ¬
<--> @leftrightarrow «
<==> @iff Û
~ @sim ~
~= @simeq @
~~ @approx »

Greek symbols

@sum å
@prod Õ
@cup È
@cap Ç
@bigcup È
@bigcap Ç
@land Ù
@lor Ú
@neg Ø
@pm ±
@exists $
@forall "
@emptyset Æ
@leftarrow ¬
@rightarrow ®
@uparrow ­
@downarrow ¯
@leftrightarrow «
@Leftrightarrow @iff Û
@Rightarrow @implies Þ
@dash ¾
@vert ½
@lfloor ë
@rfloor û
@lceil é
@rceil ù
@result ®
@expansion Þ
@equiv º
@approx »
@sim ~
@simeq @
@infty ¥
@leq £
@gte ³
@neq ¹
@exclamdown ¡
@questiondown ¿
@in Î
@notin Ï
@times ×
@subset Ì
@subseteq Í
@nsubset @not @subseteq Ë
@supset É
@supseteq Ê
@propto µ
@aleph À
@Im Á
@Re Â
@nabla Ñ
@partial
@perp ^

Index commands

There is no need to define new indices with a @defindex. A new index will be created automatically.

When you use a new index, it is best to define it's full name with an IndexName configuration option.

Index entries are placed by default in a global index (located at the top of the documentation tree). You can add to the local indices by adding a `./' after the `@'. For example, the following line adds an entry to the local concepts index,

@./cindexl index, local

@menu command

d4c&b supports a simplified @menu command. A menu entry may have one of the two forms

@menu
* Generic documentation comments::
* Documentation language:: Language
@end menu
The text after `*' is like the first argument of a @ref, while text after the `::', if given, is like the second.

@image command

You can insert an image from a file with the @image command.

d4c&b @image is slightly different from texinfo's @image,

For example,

@uref{http://sourceforge.net,
@image{http://sourceforge.net/sflogo.php?group_id=13427,88,31,
            SourceForge Logo, border="0"}}

New texinfo commands

@refs

A `@refs dir1 dir2 ...' directive adds directories to d4c&b search path, just like an -I.

Unfortunately, this applies not only to that file but globally.

@alignedexample

@alignedexample is probably harder to explain than to use. I found texinfo @example inadequate when I wanted to place texinfo commands inside an @example. For example

@example
  @code{aaa}        @code{xxxx}
  bbbbb             yy
@end example
produces,

  aaa        xxxx
  bbbbb             yy
The other case was when I tried to draw basic text diagrams, and add some arrows to it. Aligned example is similar to @example, but keeps the original indentation as best as it can. For the example above, it will generate the expected output,

  aaa          xxxx
  bbbbb        yy
Another example from FileEntries::FileElement

@alignedexample

             AutoComment
                @uparrow
             Element
                @uparrow
         ----------------          
        @uparrow         @uparrow 
    ClassElement       Variable
        @uparrow         @uparrow
         ----------------
                @uparrow
           ClassVariable
@end
which produces,

                                 
             AutoComment         
                ­                
             Element             
                ­                
         ----------------        
        ­                ­       
    ClassElement       Variable  
        ­                ­       
         ----------------        
                ­                
           ClassVariable

As-is texinfo commands

d4c&b supports the following texinfo commands in their original form

TTH output for math examples

1. This is in accordance with texinfo syntax for menu references (See Other Info Files)

2. see Ranking of references in a ``C++'' class for additional criteria that applies to ``C++'' files