From Open Watcom
←Older revision | Newer revision→
This page does not provide complete or authoritative GML documentation. It is meant to explain certain non-obvious techniques and primarily document GML macros that were created specifically for the Open Watcom documentation.
For general GML introduction and reference, see the WATCOM Script/GML Tutorial and Reference Manual. Keep in mind that many Open Watcom documents use specialized macros expressly designed to simplify and streamline the task of writing tool and library documentation. Examining existing documents in PostScript/PDF or online help form and comparing them against their corresponding GML source is an excellent way of learning GML.
Starts a new paragragh.
.* This is a script comment :CMT This is a GML comment
.autopoint .point This is point 1. .point This is point 2. .endpoint
Will produce something like:
- This is point 1.
- This is point 2.
Documenting C Library functions
The C Library Reference book uses a set of macros that ease preparation of the documentation. While documenting the new Safer C Library extension, some of these macros were found lacking. Existing macros used a simple heuristic to guess function type (far, wide, multibyte, etc.), as well as function classification (ANSI, POSIX, TR 24731, WATCOM, etc.) based on function name. A new set was therefore created, which accepts function type and class as parameters -- no more guessing required. Affected files are located under docs/doc/lr/src.
When adding a new function to the C Library Reference, it needs to be entered in two important files: libfuns.gml and liblist7.gml.
In libfuns.gml the function name is listed next to the corresponding *.gml file and the "system" (DOS, WIN32, QNX, etc.). The "system" allows us to create different versions of the C Library Reference, each containing specific subset of library functions. An example for wctomb_s and _fwctombs_s follows:
.fnc wctomb_s wctomb_s.gml DOS WIN32 .fnc _fwctomb_s wctomb_s.gml DOS WIN32
In liblist7.gml the function is listed next to the supported operating systems (DOS16, WIN31, OS232, LINUX, etc.):
.sys wctomb_s DOS16 DOS32 WIN16 WIN386 WIN32 QNX16 QNX32 OS216 OS216MT OS216DL OS232 NET32 .sys _fwctomb_s DOS16 DOS32 WIN16 WIN386 WIN32 OS216 OS216MT OS216DL OS232
Any new *.gml files also have to be added to the makefile dependancy list in docs/mif/depends.mif.
The new macros in file cmanmac.gml are:
- for initializing variables, no parameters
- for setting function type and classification, one or two parameters
- for preparing title and classifcation text, no parameters
- for resetting font to default, no parameters
- for output of classification text, no parameters
The funct_xx macros come in several variants: each requires the functionname and the classification (defaults to WATCOM if omitted); each also sets a variable which can be used later in the text.
- normal, sets &func
- _version, sets &_func
- far version, sets &ffunc
- wide version, sets &wfunc
- far wide version, sets &fwfunc
- multibyte version, sets &mfunc
- far multibyte version, sets &fmfunc
- unicode version, sets &ufunc
- double math version, sets &mathfunc
- float math version, sets &fmathfunc
- long double math version, sets &lmathfunc
Additionally, &function gets the raw name of the first funct_xx function name.
At least one of the funct_xx should be present. The title is constructed from all present functionnames.
Now the example from wctomb_s.gml:
.functinit .funct_w wcsrtombs_s TR 24731 .funct_fw _fwcsrtombs_s .functgen #define __STDC_WANT_LIB_EXT1__ 1 errno_t wcsrtombs_s( size_t * restrict retval, char * restrict dst, rsize_t dstmax, const wchar_t ** restrict src, rsize_t len, mbstate_t * restrict ps); .ixfunc2 '&Wide' &wfunc .ixfunc2 '&Multibyte' &wfunc errno_t _fwcsrtombs_s( size_t __far * restrict retval, char __far * restrict dst, rsize_t dstmax, const wchar_t __far * __far * restrict src, rsize_t len, mbstate_t __far * restrict ps); .ixfunc2 '&Wide' &fwfunc .ixfunc2 '&Multibyte' &fwfunc .functend ..........here come constraints, description, return values, example .classt .system