tedoc -- Source code documentation tool for SciTECO
|
tedoc.tes |
[-C] [--] output template sources... |
tedoc is a tool for extracting documentation from SciTECO macros and C/C++ code. It is used to document SciTECO’s internal commands as well as macro packages. It processes special SciTECO comment blocks from the sources, generating troff man-page markup and inserts them into a man-page template at the position of the TEDOC pseudo-request. The result is written to an output file. tedoc can thus be understood as a troff preprocessor.
|
-C |
Instruct tedoc to extract C/C++ comments instead of SciTECO comments. The C comments begin with “/*$” and end with “*/”. The SciTECO comments in contrast begin with “!*$” and end with “*!”. | ||
|
output |
The resulting man-page file. |
template
A man-page template, i.e. a man-page with the TEDOC request.
sources...
An arbitrary number of source code files to scan through. The comments are extracted in document order, ie. from the first comment in the first source file to the last comment in the last source file specified.
The tedoc source code comments support a small but powerful semantic markup for documenting SciTECO commands and macros:
|
• |
Comments start with “!*$” (or “/*$” in C/C++ mode). | ||
|
• |
The first line (immediately after the starting comment) may contain topic keywords for SciTECO’s online help system that will point to the beginning of the section generated for this tedoc comment. This generates SCITECO_TOPIC macro calls defined in sciteco.tmac (see grosciteco.tes(1). | ||
|
• |
All lines until first empty line are syntax descriptions. | ||
|
• |
Text followed by “--” is a short description. | ||
|
• |
Variable values and characters of syntactic significance should be detected automatically. | ||
|
• |
Alternatives are denoted by “|”. | ||
|
• |
Every line is an alternative (e.g. different calling forms of the same command or macro). | ||
|
• |
Return values may be specified after “->”. | ||
|
• |
The remaining text is the verbose command description. |
•
|
“<name>” denotes a variable from the syntax description. | |||
|
• |
Empty lines introduce paragraphs. | ||
|
• |
Lines beginning with “-” are unordered lists. | ||
|
• |
Lines beginning with numbers and dot (“1.”, “2.”, etc.) are ordered lists. | ||
|
• |
These transformations are only preprocessing, so that troff requests, macros and escapes may also be used freely. |
SciTECO invocation and help on its environment variables:
sciteco(1)
A GNU roff post-processor for rendering troff
markup into “womanpages” for SciTECO’s online help system — also documents special troff macros in sciteco.tmac: grosciteco.tes(1)
The GNU roff “man” macros for writing man pages:
groff_man(7)
This manpage and the SciTECO program was written by Robin Haberkorn.