SYNOPSIS
DESCRIPTION
OPTIONS
SPECIAL TROFF MACROS
EXAMPLES
BUGS
SEE ALSO
AUTHOR
NAME
grosciteco −− GNU roff post-processor for SciTECO
SYNOPSIS
|
grosciteco.tes |
[-t tec_output] [--] text_output input |
DESCRIPTION
grosciteco is a post-processor for GNU roff which works similar to groff’s grotty post-processor and driver. Similarily, grosciteco is a plain-text formatter — but since it lays out the document itself and is written in the SciTECO language, it will generate an additional SciTECO macro that can be executed to style the plain-text document.
The plain-text document will usually have the extension “woman” and the accompanying SciTECO macro will have the extension “woman.tec”. Both files combined are called womanpage since they are commonly SciTECO-formatted man pages.
Furthermore, womanpages can be indexed by search terms (called topics). A per-file topic index is generated as part of the “woman.tec” output file. Users of grosciteco can define topics in troff markup using the SCITECO_TOPIC troff macro defined in the “sciteco.tmac” macro package. This macro package should always be loaded when processing troff documents which are going to be post-processed by grosciteco.
Preparing a womanpage for display is usually performed automatically by SciTECO’s “woman.tes” lexer definition whenever you open a “*.woman” file in SciTECO. womanpages are recommended to be installed into a special directory in SciTECO’s standard library. The SciTECO command ? provides an online help feature which gives fast access to properly-installed womanpages. It builds a global topic index of all womanpages installed in the $SCITECOPATH/women directory. grosciteco is thus a central component in providing SciTECO’s help system, in documenting internal commands, the SciTECO standard library macros and third-party macro packages. The generation of womanpages at compile-time means that no troff is required by end users to browse documentation within SciTECO.
OPTIONS
-t tec_output
The SciTECO script that when executed after loading text_output into a Scintilla view, styles that document. It can be thought of as representing meta-information for text_output. In order to cooperate with the “woman” lexer and SciTECO’s ? command, its file name should be text_output.tec, e.g. “great-macro.woman.tec”. This is also the default when omitted.
text_output
The plain-text output file, e.g. “great-macro.woman”.
|
input |
The input file is in troff’s device-independant output format. |
SPECIAL TROFF MACROS
troff
documents should be processed with the
“sciteco.tmac” macro package that also ships
with SciTECO. It tweaks formatting for display in
SciTECO (assuming that the lexer system for
womanpages is in place) and provides the following
troff macros that can be called by documentation
authors:
.SCITECO_TOPIC topics...
Defines one or more topics in SciTECO’s help system. Every topic must be in its own macro argument. A topic can be looked up in SciTECO using the ?topic$ command, but in case of topic collisions, SciTECO will modify the topic name to keep it unique. The ? (question mark) command will jump to the position that corresponds to the macro call in troff markup. Topics can and should only consist of printable characters, so escape characters should be written in their up-caret notation (e.g. “ˆ[” instead of escape). SciTECO expands control characters to their printabel form when looking up terms.
.SCITECO_TT [line length]
Marks the beginning of an area that must be formatted in a monospaced font. grosciteco has only limited support for Troff font styles and the font family used depends on the SciTECO UI used to show the womanpage. Since line drawing commands assume a TTY-like output device, SCITECO_TT should precede those sections of text (including the tbl macro TS). An optional temporary line length may also be specified which is especially useful for tables.
.SCITECO_TT_END [SP]
Marks the end of an area that must be formatted in a monospaced font. The optional SP keyword may be specified to skip one line vertically (via troff’s .sp request).
.SCITECO_STARTSTYLING
Marks the beginning of a block for manual Scintilla styling.
.SCITECO_SETSTYLING style
Assign the given Scintilla style number to the block beginning with .SCITECO_STARTSTYLING. This style must have been configured in a custom macro.
These public macros will be ignored if “sciteco.tmac” is not loaded, so it is safe to use them in man pages that are also installed into the system.
Note that “sciteco.tmac” is not installed into the standard GNU roff macro search directories, but into SciTECO data directory at “/usr/local/share/sciteco”. It must thus be moved or linked manually into one of the search paths, or the data dir must be added to the search paths. Alternatively, you may also add it to the groff command line with the -M option.
EXAMPLES
The following UNIX shell commands will generate the womanpage for a SciTECO macro package with a man page called great-macro.tes(7sciteco):
groff -Z -Kutf-8 -Tutf8 -man
-M/usr/local/share/sciteco -msciteco \
great-macro.tes.7sciteco
>great-macro.tes.7sciteco.intermediate
grosciteco.tes great-macro.tes.7sciteco.woman
great-macro.tes.7sciteco.woman.tec \
great-macro.tes.7sciteco.intermediate
The resulting files should be installed to /usr/local/share/sciteco/lib/women (or wherever $SCITECOPATH points to at runtime) to make the files accessible in SciTECO’s online-help system.
BUGS
grosciteco is quite slow, although this is a SciTECO issue.
The pic(1) preprocessor is poorly supported and diacritics may not be rendered properly.
SEE ALSO
SciTECO invocation and help on its environment variables:
sciteco(1)
Language reference including additional information on the ? command:
sciteco(7)
A documentation tool generating man-page markup:
tedoc.tes(1)
The GNU roff front end program:
groff(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.
| * |
|