diff options
Diffstat (limited to 'nx-X11/extras/ogl-sample/main/doc/man/mangl/README')
| -rw-r--r-- | nx-X11/extras/ogl-sample/main/doc/man/mangl/README | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/nx-X11/extras/ogl-sample/main/doc/man/mangl/README b/nx-X11/extras/ogl-sample/main/doc/man/mangl/README new file mode 100644 index 000000000..3a49cdc14 --- /dev/null +++ b/nx-X11/extras/ogl-sample/main/doc/man/mangl/README @@ -0,0 +1,93 @@ +This directory has GL man pages. + +./style gives some style guidelines. + +./template is a template that can be used as a starting point + when writing new man pages. + +./standard contains man page source and a Makefile for making + various targets using nroff and troff. The suffix + for man page source in this directory is '.gl'. + +Two awk scripts and m4 are run over GL man page source before it is +processed in the same way that standard man pages are. This allows +a writer to avoid most annoying troff'isms. + Several macros are provided to simplify man page writing. These +are: + +_header(name,desc) + Gives the name of the command to be used at the + top and bottom of the man page and in the _cmnd macro + (below). Also give the one line description of the + command. + +_names(base,regexp) +_names(base,regexp,noheader) + Generates the 'C SPECIFICATIONS' for all forms of + a command with the indicated base name and an + extension matching the given regular expression. + This is done by using the name and expression to search the + known GL commands. A function header is generated for + each matching command. The second form of the command, + with a third argument (any argument will do) suppresses + the generation of the 'C SPECIFICATION' section heading + for the matched names (useful when a single man page + describes diverse commands). + +_cmnd Without an argument, generates the correctly prefixed and +_cmnd(arg) capitalized base command name. Use \& (troff zero-width + space) to separate it from immediately following letters, + digits, underscores or parentheses. With an argument, it + generates the prefixed command name (currently the argument + is not matched against the known GL commands). + The command is automatically emboldened. + +_param<i> Generates the italicized <i>th parameter to the command. +_param<i>(n) Without an argument, it gets the <i>th argument to forms + of the command matching the last _names() invocation. + With an argument, gives the <i>th argument to forms of + the command matching the nth _names() invocation. + +_eqnparam<i> Same as _param, but does not italicize, and can therefore +_eqnparam<i>(n) be used in equations. + +_phead(param) Used when generating a parameter description of 'param'. + Parameter description immediately follows. + +_const(arg) Generates a prefixed and emboldened GL constant 'arg'. +_econst(arg) Same as _const but for use inside equations. + +_hex(arg) Generates "0x'arg'". + +_C_ Comment; everything following up to and including the next + newline is ignored + +_define define an M4 macro. See the M4 man page. Most of the + M4 macros having common names that could clash with words + in the text have been undefined or redefined to have + underscores preceeding their names. Be sure to use _C_ + (or M4's 'dnl') at the end of a macro definition to + avoid extraneous newlines in the troff source. + +If '_filters' is defined before the use of '_header' (see the template +for an example that is commented out) then the processed text is run +through the shell commands given in '_filters' just before being sent to +troff. Useful when tables or equations appear in the text. + +Two standard macros may be redefined in special situations. '_basename' +is the base command name. Normally it is set to the filename of the +man page being generated, sans suffix, and appears in the banner on +every page of the man page. 'gl' is automatically prepended to this +name. '_samething' is the message to be printed when there are +multiple commands under the same heading. See the template for +commented out examples. + +Troff macro names .BR and .BP appear in various manpages. These are +placeholders for .br and .bp macros that were added for the Addison +Wesley publication, but are not valid for other printings. Since these +macros are not defined anywhere, they are ignored by troff/nroff. + +A final and important note: the file MUST begin with an '_' +(probably as in '_header' or '_define(_filters,...)_C_) or +the aforementioned processing will not be applied and you will +be obliged to use the frightful standard man page troff constructs. |