NAME

tedoc -- Source code documentation tool for SciTECO

SYNOPSIS

DESCRIPTION

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.

OPTIONS

-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, i.e. from the first comment in the first source file to the last comment in the last source file specified.

TEDOC COMMENTS

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.

SEE ALSO

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)

AUTHOR

This manpage and the SciTECO program was written by Robin Haberkorn.