Documentation Macros

From Open Watcom

Jump to: navigation, search

Contents

Introduction

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.

General Macros

Paragraphs

.np

Starts a new paragragh.

Comments

.* This is a script comment
:CMT This is a GML comment

Numbered lists

.autopoint
.point
This is point 1.
.point
This is point 2.
.endpoint

Will produce something like:

  1. This is point 1.
  2. 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:

functinit
for initializing variables, no parameters
funct_xx
for setting function type and classification, one or two parameters
functgen
for preparing title and classifcation text, no parameters
functend
for resetting font to default, no parameters
classt
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.

funct
normal, sets &func
funct_
_version, sets &_func
funct_f
far version, sets &ffunc
funct_w
wide version, sets &wfunc
funct_fw
far wide version, sets &fwfunc
funct_m
multibyte version, sets &mfunc
funct_fm
far multibyte version, sets &fmfunc
funct_u
unicode version, sets &ufunc
functm
double math version, sets &mathfunc
functm_f
float math version, sets &fmathfunc
functm_l
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
Personal tools