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.
@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@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@section The @code{@@subsection} Commandis
@value{...}
, which remains a texinfo command.
Reference text is texinfo code - for example
When reference target contains a `,', you need to quote it. For example,
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.
@node lets go here ... @ref{lets go here}
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.
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.
chapter
or a top level entry.
@multitable
extensions
@multitable @border
@multitable @center
@multitable @colalign{cols}
@multitable @rowalign{row}
@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 |
|
In d4c&b, one or more tabs (`\t') are the same as a @tab.
Nested multitables are supported.
source | result |
---|---|
@enumerate @i @item first @item second @end enumerate |
|
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 |
|
source | result |
---|---|
@itemize @item first @item second @end itemize |
|
@center
command
@center text more text @end centerproduces
more text
@end ...
@end
it is.
Two notable exceptions are `@end ignore' and `@end cartouche'.
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 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} | |
superscript | @eqn{a^k} | |
prime | @eqn{x'} | |
@eqn{x''} |
@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 supports the same capabilities as @math
, but will generate an inline equation just like @eqn
.
code | equation | ||
---|---|---|---|
x_i | xi | ||
x^2 | x2 | ||
x_3^2 |
|
source | equation | ||||||
---|---|---|---|---|---|---|---|
@sum x | å x
| ||||||
@sum_{i=0}^n x_i |
| ||||||
@bigcap_i x_i |
| ||||||
@int_{-@infty}^{+@infty} f(x) dx |
| ||||||
@mathop{MAX}_i x_i |
|
source | equation | |
---|---|---|
x @over y |
| |
x @atop y |
|
source | equation | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
(x @over y) |
| |||||||||
@left(x @over y @right) |
| |||||||||
@left [ x @over y @right ] |
| |||||||||
@left { x @over y @right } |
| |||||||||
@left @lfloor x @over y @right @rfloor |
| |||||||||
@left @lceil x @over y @right @rceil |
| |||||||||
@left @frac{x}{y} @right|_{x=0} |
| |||||||||
d(x) = @left @{ 0 if x<=0 @atop 1 if x>0 @right |
|
source | equation | ||||||
---|---|---|---|---|---|---|---|
@array{ 1 & 0 @@ 0 & 1 } |
|
source | equation | |||||
---|---|---|---|---|---|---|
@cos(2@pi{}x) | cos (2px)
| |||||
@func{id}(x) | id (x)
| |||||
@sqrt{x + y} |
| |||||
@sqrt{x @over y} |
|
source | equation | ||||
---|---|---|---|---|---|
@bar x |
| ||||
@bar x+y |
| ||||
@bar{x+y} |
| ||||
@bar{@bar{x+y}} |
|
source | equation | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
x = {-b @pm @sqrt{b^2 - 4ac} @over 2a}
|
| |||||||||||||
@chi^2 = @sum_{i=1}^N |
|
@eqn
and @math
support several convenient shorthands.
|
|
|
|
|
|
|
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 * Generic documentation comments:: * Documentation language:: Language @end menuThe text after `*' is like the first argument of a @ref, while text after the `::', if given, is like the second.
d4c&b @image
is slightly different from texinfo's @image
,
IMG
command.
@uref{http://sourceforge.net, @image{http://sourceforge.net/sflogo.php?group_id=13427,88,31, SourceForge Logo, border="0"}}
Unfortunately, this applies not only to that file but globally.
@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 exampleproduces,
The other case was when I tried to draw basic text diagrams, and add some arrows to it. Aligned example is similar toaaa
xxxx
bbbbb yy
@example
, but keeps the original indentation as best as it can. For the example above, it will generate the expected output,
Another example from FileEntries::FileElementaaa
xxxx
bbbbb yy
which produces,
@alignedexample AutoComment @uparrow Element @uparrow ---------------- @uparrow @uparrow ClassElement Variable @uparrow @uparrow ---------------- @uparrow ClassVariable @end
AutoComment Element ---------------- ClassElement Variable ---------------- ClassVariable |
@multitable
)
However @smalllisp and @lisp are not supported. In texinfo mode they are the same as @smallexample
and @example
.
@set and @clear
However @ifset and @ifclear are supported only in texinfo mode.
2. see Ranking of references in a ``C++'' class for additional criteria that applies to ``C++'' files