diff options
Diffstat (limited to 'contrib/groff/tmac/groff_tmac.man')
| -rw-r--r-- | contrib/groff/tmac/groff_tmac.man | 420 |
1 files changed, 420 insertions, 0 deletions
diff --git a/contrib/groff/tmac/groff_tmac.man b/contrib/groff/tmac/groff_tmac.man new file mode 100644 index 000000000000..9e1f8e057826 --- /dev/null +++ b/contrib/groff/tmac/groff_tmac.man @@ -0,0 +1,420 @@ +.\" -*- nroff -*- +.ig / +groff_tmac.5 + +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2000 Free Software Foundation, Inc. +written by Bernd Warken <bwarken@mayn.de> + +Last update: 17 May 2000 + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being this .ig-section and AUTHOR, with no +Front-Cover Texts, and with no Back-Cover Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +./ +. +.\" -------------------------------------------------------------------- +.\" Setup +.\" -------------------------------------------------------------------- +. +.if n \{\ +. mso tmac.tty-char +. ftr CR R +. ftr CI I +. ftr CB B +.\} +. +.\" text lines in macro definitions or bracketed sections \{...\} +.de text +. if 1 \&\\$*\& +.. +. +.de BIR +. ie (\\n[.$] < 3) \ +. BI $@ +. el \{\ +. ds @tmp@ \fB\\$1\fP\fI\\$2\fP +. shift 2 +. text \\*[@tmp@]\fR\\$*\fP +. rm @tmp@ +. \} +.. +. +.de 'char +. ds @tmp@ `\f(CB\\$1\fP' +. shift +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.de option +. ds @tmp@ \f(CB\\$1\fP +. shift 1 +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.als shellcommand option +. +.de argument +. ds @tmp@ \f(CI\\$1\fP +. shift 1 +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.de request +. ds @tmp@ \f(CB\\$1\fP +. shift 1 +. text \\*[@tmp@]\\$* +. rm @tmp@ +.. +. +.\" -------------------------------------------------------------------- +.\" Title +.\" -------------------------------------------------------------------- +.TH GROFF_TMAC @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +groff_tmac \- macro files in the roff typesetting system +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +.\" -------------------------------------------------------------------- +The +.BR roff (@MAN7EXT@) +type-setting system provides a set of macro packages suitable for +special kinds of documents. Each macro package stores its macros and +definitions in a file called the package's +.BR "tmac file" . +The name is deduced from +.RB ` T roff +.BR MAC ros'. +.LP +The tmac files are normal roff source documents, except that they +usually contain only definitions and setup commands, but no text. All +tmac files are kept in a single or a small number of directories, the +.B tmac +directories. +.\" -------------------------------------------------------------------- +.SH NAMING +.\" -------------------------------------------------------------------- +In classical roff systems, there was a funny naming scheme. +If the name of a macro package started with +.'char m +this letter was omitted, e.g., the macro package for the man pages +.I man +was called +.I an +and its macro file +.IR tmac.an . +.LP +By a similar reasoning, macro packages that did not start with an +.'char m +were often referred to by adding an +.'char m , + e.g., the package corresponding to +.I tmac.doc +was called +.I mdoc +because the command-line for activating it reads +.RS +.LP +.BIR "troff\ \-m" doc . +.RE +.LP +Actual versions of +.BR groff (@MAN1EXT@) +provide both naming schemes for the inflicted macro packages, with and +without the leading +.'char m . +So in +.IR groff , +the +.I man +macro package may be specified as +.RS +.LP +.BIR "groff\ \-m\ " man , +.br +.BIR "groff\ \-m" an , +.br +.BIR "groff\ \-m" man , or +.br +.BIR "groff\ \-m " an . +.RE +.LP +The easiest way to find out which macro packages are available on a +system is to check the content of the +.I tmac +directories. +For example, a file called +.BI tmac. anything +determines a macro package named +.IR anything . +.LP +In +.IR groff , +most macro packages are described in man pages called +.BR groff_<name> (@MAN7EXT@), +with a leading +.'char m +for the classical packages. +.\" -------------------------------------------------------------------- +.SH INCLUSION +.\" -------------------------------------------------------------------- +There are several ways to use a macro package in documents. At +run-time, the groff option +.option \-m \ \c +.argument name +makes the definitions in the macro file +.BI tmac. name +available as described in the section +.BR NAMING . +.LP +It is also possible to include the macro file into the document by using +the groff requests +.request .so +or +.request .mso . +For +.request .so +the full filename of the macro file must be specified \(em including the +directory where it is kept. +If the macro file is stored in one of the tmac directories it is more +convenient to use +.request .mso +instead because it additionally searches the tmac path for the filename. +.LP +Note that in order to resolve the +.request .so +and +.request .mso +requests the roff preprocessor +.shellcommand soelim +must be called. This can be done either directly by a pipeline on the +command line or by using the +.option \-s +option of +.shellcommand groff . +.LP +You can also supply the letter +.'char s +in the preprocessor word as described in section +.BR CONVENTION . +.LP +For example, suppose a macro file is stored as +.I /usr/share/groff/tmac/tmac.macros +and is used in some document called +.IR docu.roff . +.LP +At run-time, the formatter call for this is +.RS +.LP +.ft CR +.shellcommand "groff\ \-m" +.argument macros +.argument docu.roff +.ft P +.RE +.LP +To include the macro file directly in the document either +.RS +.ft CR +\&\.mso tmac.macros +.ft P +.RE +is used or +.RS +.ft CR +\&\.so /usr/share/groff/tmac/tmac.macros +.ft P +.RE +.LP +In both cases, the formatter is called with +.ft CR +.RS +groff\ \-s docu.roff +.RE +.ft P +. +.\" -------------------------------------------------------------------- +.SH CONVENTION +.\" -------------------------------------------------------------------- +.LP +There is a convention that is supported by many modern roff +type-setters: the +.B preprocessor word +described in the following. +.LP +If the first line in a document is a comment, the first word (after the +comment characters and a blank) constitutes the +.B preprocessor +.BR word . +That means that the letters of this word are interpreted as +abbreviations for those preprocessor commands that should be run +when formatting the document. Mostly, only the letters corresponding to +the options for the preprocessors are recognized, +.'char e , +.'char G , +.'char g , +.'char p , +.'char R , +.'char s , and +.'char t +(see +.BR roff (@MAN7EXT@)). +.LP +Besides being a good reminder for the user, some formatters (like the +.BR man (1) +program) are even able to automatically start the preprocessors +specified in the preprocessor word, but do not bet on this. +.\" -------------------------------------------------------------------- +.SH "WRITING A MACRO FILE" +.\" -------------------------------------------------------------------- +Writing a groff macro file is easy. Design a set of macros, strings, +registers, etc. Store them in a single file. Documents that use the +macros include this macro file with the +.request .so +request as described in the +.B INCLUSION +section. +.LP +To use the tmac functionality, call the macro file +.BI tmac. whatever +and put it in some directory of the tmac path, cf. section +.BR FILES . +Then documents can include it with the +.request .mso +request or the +.shellcommand "groff\ \-m" +option as described in the +.B INCLUSION +section. +.LP +If your macros might be of general usage contact the groff maintainers +to have them included in the groff +.I contrib +source directory. +.LP +Some general guidelines might be helpful in writing macros. +.IP \(bu 2m +Double all functional backslashes, +.'char \e +-> +.'char \e\e . +.IP \(bu 2m +All printable backslashes must be written as +.'char \ee . +.IP \(bu 2m +Escape all dots, +.'char . +-> +.'char \e. . +.IP \(bu 2m +Make ample use of the non-printable character +.'char \e& +in text parts, esp. before +.'char \e +and at the beginning of a line, but not before a delayed command. +.IP \(bu 2m +Use the character +.'char @ +in temporary variable names. +.IP \(bu 2m +Test your macros for text and graphical devices, e.g., +.I latin1 +and +.IR ps . +.\" -------------------------------------------------------------------- +.SH FILES +.\" -------------------------------------------------------------------- +All macro names that want to use the tmac mechanism must be named +according to the form +.BIR tmac. name . +.LP +The macro files are kept in the +.B tmac +.BR directories , +all of which constitue the +.B tmac +.BR path. +In accordance with the Filesystem Hierarchy Standard (FHS), the standard +tmac directory location for groff is +.IR /usr/share/groff/tmac , +a local installation will use +.IR /usr/local/share/groff/tmac . +Older systems used a subdirectory of +.IR /usr/lib . +Independently of the default tmac path, the tmac path actually used by a +document can always be set by a shell environment variable, cf. section +.BR ENVIRONMENT . +.\" -------------------------------------------------------------------- +.SH ENVIRONMENT +.\" -------------------------------------------------------------------- +.TP +.B GROFF_TMAC_PATH +A colon separated list of tmac directories in which to search for macro +files, the +.B tmac +.BR path . +If unset a default path is used as is outlined in the +.B FILES +section. +.\" -------------------------------------------------------------------- +.SH BUGS +.\" -------------------------------------------------------------------- +The groff documentation is in evolution at the moment. It is possible +that small inconsistencies between different documents exist +temporarily. +.\" -------------------------------------------------------------------- +.SH AUTHOR +.\" -------------------------------------------------------------------- +This document is part of groff, the GNU roff distribution. It was +written by Bernd Warken <bwarken@mayn.de>. +.LP +It is distributed under the terms of the FDL (GNU Free Documentation +License) version 1.1 or later. You should have received a copy of the +FDL on your system, it is also available on-line under +.RS +.LP +.IR <http://www.gnu.org/copyleft/fdl.html> . +.RE +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +The authoritative source of information for all details of the groff +system is the groff +.BR info (1) +file. +.LP +For a groff overview, see +.BR roff (@MAN7EXT@) +and the file +.I README +in the groff source package. +.LP +The groff tmac macro packages are +.BR groff_man (@MAN7EXT@), +.BR groff_markup (@MAN7EXT@), +.BR groff_mdoc (@MAN7EXT@), +.BR groff_mdoc.samples (@MAN7EXT@), +.BR groff_me (@MAN7EXT@), +.BR groff_mm (@MAN7EXT@), +.BR groff_mmroff (@MAN7EXT@), +.BR groff_ms (@MAN7EXT@), +.BR groff_msafer (@MAN7EXT@). +.LP +The groff language is described in +.BR groff (@MAN7EXT@) +and the formatters in +.BR groff (@MAN1EXT@), +.BR troff (@MAN1EXT@). +.LP +The Filesystem Hierarchy Standard (FHS) is available at +.BR http://www.pathname.com/fhs/ . + |