Documentation Macros

From Open Watcom

Contents 1 Introduction 2 General Macros 2.1 Paragraphs 2.2 Comments 2.3 Numbered lists 3 Documenting C Library functions

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