diff options
Diffstat (limited to 'upstream/fedora-rawhide/man5/groff_tmac.5')
| -rw-r--r-- | upstream/fedora-rawhide/man5/groff_tmac.5 | 1474 |
1 files changed, 1474 insertions, 0 deletions
diff --git a/upstream/fedora-rawhide/man5/groff_tmac.5 b/upstream/fedora-rawhide/man5/groff_tmac.5 new file mode 100644 index 00000000..bde81235 --- /dev/null +++ b/upstream/fedora-rawhide/man5/groff_tmac.5 @@ -0,0 +1,1474 @@ +.TH groff_tmac 5 "24 January 2024" "groff 1.23.0" +.SH Name +groff_tmac \- macro files in the GNU +.I roff +typesetting system +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 2000-2022 Free Software Foundation, Inc. +.\" +.\" This file is part of groff, the GNU roff typesetting system. +.\" +.\" Permission is granted to copy, distribute and/or modify this +.\" document under the terms of the GNU Free Documentation License, +.\" Version 1.3 or any later version published by the Free Software +.\" Foundation; with no Invariant Sections, 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. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_tmac_5_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" TODO: Consider parallelizing with our Texinfo node "Macro Packages". +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +Definitions of macros, +strings, +and registers for use in a +.MR roff 7 +document can be collected into +.IR "macro files" , +.I roff +input files designed to produce no output themselves but instead ease +the preparation of other +.I roff +documents. +. +There is no syntactical difference between a macro file and any other +.I roff +document; +only its purpose distinguishes it. +. +When a macro file is installed at a standard location, +named according to a certain convention, +and suitable for use by a general audience, +it is termed a +.IR "macro package" . +. +Macro packages can be loaded by supplying the +.B \-m +option to +.MR \%troff 1 +or a +.I groff +front end. +. +. +.P +Each macro package stores its macro, +string, +and register definitions in one or more +.I tmac +files. +. +This name originated in early Unix culture as an abbreviation of +.RI \[lq] troff \" generic +macros\[rq]. +. +. +.P +A macro file must have a name in the form +.RI name .tmac +(or +.IR tmac. name) +and be placed in a +.RI \[lq] tmac +directory\[rq] to be loadable with the +.BI \-m name +option. +. +Section \[lq]Environment\[rq] of +.MR \%troff 1 +lists these directories. +. +Alternatively, +a +.I groff +document requiring a macro file can load it with the +.B mso +(\[lq]macro source\[rq]) request. +. +. +.P +Like any other +.I roff +document, +a macro file can use the +.RB \[lq] so \[rq] +request (\[lq]source\[rq]) to load further files relative to its own +location. +. +. +.P +Macro files are named for their most noteworthy application, +but a macro file need not define any macros. +. +It can restrict itself to defining registers and strings or invoking +other +.I groff +requests. +. +It can even be empty. +. +. +.\" ==================================================================== +.SH "Macro packages" +.\" ==================================================================== +. +Macro packages come in two varieties; +those which assume responsibility for page layout and other critical +functions +(\[lq]major\[rq] or \[lq]full-service\[rq]) +and those which do not +(\[lq]supplemental\[rq] or \[lq]auxiliary\[rq]). +. +GNU +.I roff +provides most major macro packages found in AT&T and BSD Unix systems, +an additional full-service package, +and many supplemental packages. +. +Multiple full-service macro packages cannot be used by the same +document. +. +Auxiliary packages can generally be freely combined, +though attention to their use of the +.I groff +language name spaces for identifiers +(particularly registers, +macros, +strings, +and diversions) +should be paid. +. +Name space management was a significant challenge in AT&T +.IR troff ; +.IR groff 's +support for arbitrarily long identifiers affords few excuses for name +collisions, +apart from attempts at compatibility with the demands of historical +documents. +. +. +.\" ==================================================================== +.SS "Man pages" +.\" ==================================================================== +. +.TP +.I an +.TQ +.I man +.I an +is used to compose man pages in the format originating in Version\~7 +Unix (1979). +. +It has a small macro interface and is widely used; +see +.MR groff_man 7 . +. +. +.TP +.I doc +.TQ +.I mdoc +.I doc +is used to compose man pages in the format originating in 4.3BSD-Reno +(1990). +. +It provides many more features than +.IR an , +but is also larger, +more complex, +and not as widely adopted; +see +.MR groff_mdoc 7 . +. +. +.P +Because readers of man pages often do not know in advance which macros +are used to format a given document, +a wrapper is available. +. +. +.TP +.I \%andoc +.TQ +.I mandoc +This macro file, +specific to +.IR groff , +recognizes whether a document uses +.I man +or +.I mdoc +format and loads the corresponding macro package. +. +Multiple man pages, +in either format, +can be handled; +.I \%andoc +reloads each macro package as necessary. +. +. +.\" ==================================================================== +.SS "Full-service packages" +.\" ==================================================================== +. +The packages in this section provide a complete set of macros for +writing documents of any kind, up to whole books. +. +They are similar in functionality; it is a matter of taste which one +to use. +. +. +.TP +.I me +The classical +.I me +macro package; see +.MR groff_me 7 . +. +. +.TP +.I mm +The semi-classical +.I mm +macro package; see +.MR groff_mm 7 . +. +. +.TP +.I mom +The +.I mom +macro package, only available in groff. +. +As this was not based on other packages, it was freely designed as +quite a nice, modern macro package. +. +See +.MR groff_mom 7 . +. +. +.TP +.I ms +The classical +.I ms +macro package; see +.MR groff_ms 7 . +. +. +.\" ==================================================================== +.SS "Localization packages" +.\" ==================================================================== +. +For Western languages, +the localization file sets the hyphenation mode and loads hyphenation +patterns and exceptions. +. +Localization files can also adjust the date format and provide +translations of strings used by some of the full-service macro packages; +alter the input encoding +(see the next section); +and change the amount of additional inter-sentence space. +. +For Eastern languages, +the localization file defines character classes and sets flags on them. +. +By default, +.I troffrc +loads the localization file for English. +. +. +.TP +.I trans +loads localized strings used by various macro packages after their +localized forms have been prepared by a localization macro file. +. +. +.P +.I groff +provides the following localization files. +. +. +.TP +.I cs +Czech; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-2 by loading +.IR latin2.tmac . +. +. +.TP +.I de +.TQ +.I den +German; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-1 by loading +.IR latin1.tmac . +. +. +.IP +.I de.tmac +selects hyphenation patterns for traditional orthography, +and +.I den.tmac +does the same for the new orthography +(\[lq]Recht\%schreib\%reform\[rq]). +. +. +.TP +.I en +English. +. +. +.TP +.I fr +French; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-9 by loading +.IR latin9.tmac . +. +. +.TP +.I it +Italian; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +. +.TP +.I ja +Japanese. +. +. +.TP +.I sv +Swedish; +localizes +.IR man , +.IR me , +.IR mm , +.IR mom , +and +.IR ms . +. +Sets the input encoding to Latin-1 by loading +.IR latin1.tmac . +. +Some of the localization of the +.I mm +package is handled separately; +see +.MR groff_mmse 7 . +. +. +.TP +.I zh +Chinese. +. +. +.\" ==================================================================== +.SS "Input encodings" +.\" ==================================================================== +. +.TP +.I latin1 +.TQ +.I latin2 +.TQ +.I latin5 +.TQ +.I latin9 +are various ISO\~8859 input encodings supported by +.IR groff . +. +On systems using ISO character encodings, +.I groff +loads +.I latin1.tmac +automatically at startup. +. +A document that uses Latin-2, +Latin-5, +or Latin-9 +can specify one of these alternative encodings. +. +. +.TP +.I cp1047 +provides support for EBCDIC-based systems. +. +On those platforms, +.I groff +loads +.I cp1047.tmac +automatically at startup. +. +. +.P +Because different input character codes constitute valid GNU +.I troff \" GNU +input on ISO and EBCDIC systems, +the +.I latin +macro files cannot be used on EBCDIC systems, +and +.I cp1047 +cannot be used on ISO systems. +. +. +.\" ==================================================================== +.SS "Auxiliary packages" +.\" ==================================================================== +. +The macro packages in this section are not intended for stand-alone +use, +but can add functionality to any other macro package or to plain +(\[lq]raw\[rq]) +.I groff +documents. +. +. +.\" TODO: +.\" a4 +.\" devtag +.\" doc-old +.\" europs +.\" psatk +.\" psfig +.TP +.I 62bit +provides macros for addition, +multiplication, +and division of 62-bit integers +(allowing safe multiplication of signed 31-bit integers, +for example). +. +. +.TP +.I hdtbl +allows the generation of tables using a syntax similar to the HTML table +model. +. +This Heidelberger table macro package is not a preprocessor, +which can be useful if the contents of table entries are determined by +macro calls or string interpolations. +. +Compare to +.MR \%tbl 1 . +. +It works only with the +.B ps +and +.B pdf +output devices. +. +See +.MR groff_hdtbl 7 . +. +. +.TP +.I papersize +enables the paper format to be set on the command line by giving a +.RB \[lq] \-d +.BI \%paper= format\c +\[rq] +option to +.IR \%troff . +. +Possible values for +.I format +are the ISO and DIN formats +.RB \[lq] A0 \[en] A6 \[rq], +.RB \[lq] B0 \[en] B6 \[rq], +.RB \[lq] C0 \[en] C6 \[rq], +and +.RB \[lq] D0 \[en] D6 \[rq]; +.\" XXX: src/libs/libgroff/paper.cpp also supports [ABCD]7. +the U.S.\& formats +.RB \%\[lq] letter \[rq], +.RB \%\[lq] legal \[rq], +.RB \%\[lq] tabloid \[rq], +.RB \%\[lq] ledger \[rq], +.RB \%\[lq] statement \[rq], +and +.RB \%\[lq] executive \[rq]; +and the envelope formats +.RB \%\[lq] com10 \[rq], +.RB \%\[lq] monarch \[rq], +and +.RB \%\[lq] DL \[rq]. +. +All formats, +even those for envelopes, +are in portrait orientation: +the length measurement is vertical. +. +Appending \[lq]l\[rq] (ell) to any of these denotes landscape +orientation instead. +. +This macro file assumes one-inch horizontal margins, +and sets registers recognized by the +.I groff +.IR man , +.IR mdoc , +.IR mm , +.IR mom , +and +.I ms +packages to configure them accordingly. +. +If you want different margins, +you will need to use those packages' facilities, +or +.I \%troff +.B ll +and/or +.B po +requests to adjust them. +. +An output device typically requires command-line options +.B \-p +and +.B \-l +to override the paper dimensions and orientation, +respectively, +defined in its +.I DESC +file; +see subsection \[lq]Paper format\[rq] +of +.MR groff 1 . +. +This macro file is normally loaded at startup by the +.I troffrc +file when formatting for a typesetting device +(but not a terminal). +. +. +.TP +.I pdfpic +provides a single macro, +.BR PDFPIC , +to include a PDF graphic in a document using features of the +.B pdf +output driver. +. +For other output devices, +.B PDFPIC +calls +.BR PSPIC , +with which it shares an interface +(see below). +. +This macro file is normally loaded at startup by the +.I troffrc +file. +. +. +.TP +.I pic +supplies definitions of the macros +.BR PS , +.BR PE , +and +.BR PF , +usable with the +.MR \%pic 1 +preprocessor. +. +They center each picture. +. +Use it if your document does not use a full-service macro package, +or that package does not supply working +.I pic +macro definitions. +. +Except for +.I man +and +.IR mdoc , +those provided with +.I groff +already do so +(exception: +.I mm +employs the name +.B PF +for a different purpose). +. +. +.TP +.I pspic +provides a macro, +.BR PSPIC , +that includes a PostScript graphic in a document. +. +The +.BR ps , +.BR dvi , +.BR html , +and +.B xhtml +output devices support such inclusions; +for all other drivers, +the image is replaced with a rectangular border of the same size. +. +.I pspic.tmac +is loaded at startup by the +.I troffrc +file. +. +. +.IP +Its syntax is as follows. +.RS +.IP +\&\fB.PSPIC\fP \ +[\fB\-L\fP\|\ +|\|\fB\-R\fP\|\ +|\|\fB\-C\fP\|\ +|\|\fB\-I\fP\~\fIn\fP] \ +\fI\|file\fP [\fIwidth\fP [\,\fIheight\/\fP]] +.RE +. +. +.IP +.I file +is the name of the PostScript file; +.I width +and +.I height +give the desired width and height of the image. +. +If neither a +.I width +nor a +.I height +argument is specified, +the image's natural width +(as given in the file's bounding box) +or the current line length is used as the width, +whatever is smaller. +. +The +.I width +and +.I height +arguments may have scaling units attached; +the default scaling unit +.RB is\~ i . +. +.B PSPIC +scales the graphic uniformly in the horizontal and vertical directions +so that it is no more than +.I width +wide +and +.I height +high. +. +Option +.B \-C +centers the graphic horizontally; +this is the default. +. +.B \-L +and +.B \-R +left- and right-align the graphic, +respectively. +. +.B \-I +indents the graphic +.RI by\~ n +(with a default scaling unit +.RB of\~ m ). +. +. +.IP +To use +.B PSPIC +within a diversion, +we recommend extending it with the following code, +assuring that the diversion's width completely covers the image's width. +. +. +.RS +.IP +.EX +\&.am PSPIC +\&.\~\~vpt 0 +\&\[rs]h\[aq](\[rs]\[rs]n[ps\-offset]u + \[rs]\[rs]n[ps\-deswid]u)\[aq] +\&.\~\~sp \-1 +\&.\~\~vpt 1 +\&.. +.EE +.RE +. +. +.IP +Failure to load +.BR PSPIC 's +image argument is not an error. +. +(The +.B psbb +request does issue an error diagnostic.) +. +To make such a failure fatal, +append to the +.B pspic*error\-hook +macro. +. +. +.RS +.IP +.EX +\&.am pspic*error\-hook +\&.\~\~ab +\&.. +.EE +.RE +. +. +.TP +.I ptx +provides a macro, +.BR xx , +to format permuted index entries as produced by the GNU +.MR ptx 1 +program. +. +If your formatting needs differ, +copy the macro into your document and adapt it to your needs. +. +. +.TP +.I rfc1345 +defines special character escape sequences named for the glyph mnemonics +specified in RFC\~1345 and the digraph table of the Vim text editor. +. +See +.MR groff_rfc1345 7 . +. +. +.TP +.I sboxes +offers an interface to the +.RB \[lq] "pdf: background" \[rq] +device control command supported by +.MR gropdf 1 . +. +Using this package, +.I groff ms +documents can draw colored rectangles beneath any output. +. +.RS +.TP +.BI \%.BOXSTART\~SHADED\~ color\~\c +.BI \%OUTLINED\~ color\~\c +.BI \%INDENT\~ size\~\c +.BI \%WEIGHT\~ size +begins a box, +where the argument after +.B \%SHADED +gives the fill color and that after +.B \%OUTLINED +the border color. +. +Omit the former to get a borderless filled box and the latter for a +border with no fill. +. +The specified +.B \%WEIGHT +is used if the box is +.BR \%OUTLINED . +. +. +.IP +.B \%INDENT +precedes a value which leaves a gap between the border and the contents +inside the box. +. +. +.IP +Each +.I color +must be a defined +.I groff +color name, +and each +.I size +a valid +.I groff +numeric expression. +. +The keyword/value pairs can be specified in any order. +.RE +. +. +.IP +Boxes can be stacked, +so you can start a box within another box; +usually the later boxes would be smaller than the containing box, +but this is not enforced. +. +When using +.BR \%BOXSTART , +the left position is the current indent minus the +.B \%INDENT +in the command, +and the right position is the left position +(calculated above) +plus the current line length and twice the indent. +. +. +.RS +.TP +.B \%.BOXSTOP +takes no parameters. +. +It closes the most recently started box at the current vertical position +after adding its +.B \%INDENT +spacing. +.RE +. +. +.IP +Your +.I groff +documents can conditionally exercise the +.I sboxes +macros. +. +The register +.B \%GSBOX +is defined if the package is loaded, +and interpolates a true value if the +.B pdf +output device is in use. +. +. +.IP +.I sboxes +furthermore hooks into the +.MR groff_ms 7 +package to receive notifications when footnotes are growing, +so that it can close boxes on a page before footnotes are printed. +. +When that condition obtains, +.I sboxes +will close open boxes two points +above the footnote separator and re-open them on the next page. +. +(This amount probably will not match the box's +.BR \%INDENT .) +. +. +.IP +See +.UR file:///usr/\:\%share/\:\%doc/\:\%groff/\:\%msboxes\:.pdf +\[lq]Using PDF boxes with +.I groff +and the +.I ms +macros\[rq] +.UE +for a demonstration. +. +. +.TP +.I trace +aids the debugging of +.I groff +documents by tracing macro calls. +. +See +.MR groff_trace 7 . +. +. +.TP +.I www +defines macros corresponding to HTML elements. +. +See +.MR groff_www 7 . +. +. +.\" ==================================================================== +.SH Naming +.\" ==================================================================== +. +AT&T +.I nroff \" AT&T +and +.I troff \" AT&T +were implemented before the conventions of the modern C +.MR getopt 3 +call evolved, +and used a naming scheme for macro packages that looks odd to modern +eyes. +. +Macro packages were typically loaded using the +.B \-m +option to the formatter; +when directly followed by its argument without an intervening space, +this looked like a long option preceded by a single minus\[em]a +sensation in the computer stone age. +. +Macro packages therefore came to be known by names that started with the +letter \[lq]m\[rq], +which was omitted from the name of the macro file as stored on disk. +. +For example, +the manuscript macro package was stored as +.I tmac.s +and loaded with the option +.BR \-ms . +. +. +.P +.I groff +commands permit space between an option and its argument. +. +The syntax +.RB \[lq] "groff \-m s" \[rq] +makes the macro file name more clear but may surprise users familiar +with the original convention, +unaware that the package's \[lq]real\[rq] name was \[lq]s\[rq] all +along. +. +For such packages of long pedigree, +.I groff +accommodates different users' expectations by supplying wrapper macro +files that load the desired file with +.B mso +requests. +. +Thus, +all of +.RB \[lq] "groff \-m s" \[rq], +.RB \[lq] "groff \-m ms" \[rq], +.RB \[lq] "groff \-ms" \[rq], +and +.RB \[lq] "groff \-mms" \[rq] +serve to load the manuscript macros. +. +. +.P +Wrappers are not provided for packages of more recent vintage, +like +.IR www.tmac . +. +. +.P +As noted in passing above, +AT&T +.I troff \" AT&T +named macro files in the form +.IR tmac. name. +. +It has since become conventional in operating systems to use a suffixed +file name extension to suggest a file type or format. +. +. +.\" ==================================================================== +.SH Inclusion +.\" ==================================================================== +. +The traditional method of employing a macro package is to specify the +.B \-m +.I package +option to the formatter, +which then reads +.IR package 's +macro file prior to any input files. +. +Historically, +.I package +was sought in a file named +.IR tmac. package +(that is, +with a +.RB \[lq] tmac.\& \[rq] +prefix). +. +GNU +.I troff \" GNU +searches for +.RI package .tmac +in the macro path; +if not found, +it looks for +.IR tmac. package +instead, +and vice versa. +. +. +.P +Alternatively, +one could include a macro file by using the request +.RB \[lq] .so +.IR file-name \[rq] +in the document; +.I file-name +is resolved relative to the location of the input document. +. +GNU +.I troff \" GNU +offers an improved feature in the similar request +.RB \[lq] mso +.IR package-file-name \[rq], +which searches the macro path for +.IR package-file-name . +. +Because its argument is a file name, +its +.RB \[lq] .tmac \[rq] +component must be included for the file to be found; +however, +as a convenience, +if opening it fails, +.B mso +strips any such suffix and tries again with a +.RB \[lq] tmac.\& \[rq] +prefix, +and vice versa. +. +. +.P +If a sourced file requires preprocessing, +for example if it includes +.I tbl \" generic +tables +or +.I eqn \" generic +equations, +the preprocessor +.MR \%soelim 1 +must be used. +. +This can be achieved with a pipeline or, +in +.IR groff , +by specifying +the +.B \-s +option to the formatter +(or front end). +. +.MR man 1 +librarian programs generally call +.I \%soelim +automatically. +. +(Macro packages themselves generally do not require preprocessing.) +. +. +.ig +.\" ==================================================================== +.SH Convention +.\" ==================================================================== +. +.\" This section does not fit into the framework of this document. +. +There is a convention that is supported by many modern roff +typesetters and +.MR man 1 +programs, the +.I preprocessor word +described in the following. +. +.P +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, +\[oq]e\[cq] +(for +.IR eqn ), +.\" \[oq]G\[cq], +.\" \[oq]g\[cq], +\[oq]p\[cq] +(for +.IR pic ), +\[oq]R\[cq] +(for +.IR refer ), +\[oq]s\[cq] +(for +.IR soelim ), +and +\[oq]t\[cq] +(for +.IR tbl ). +(see +.MR roff 7 ). +. +. +.P +Besides being a good reminder for the user, some formatters (like the +.MR man 1 +program) are even able to automatically start the preprocessors +specified in the preprocessor word, but do not bet on this. +. +. +.P +The +.I man +program handles some preprocessors automatically, such that in +man\~pages only the following characters should be used: +\[oq]e\[cq], \[oq]p\[cq], and \[oq]t\[cq]. +. +. +.. +.\" ==================================================================== +.SH "Writing macros" +.\" ==================================================================== +. +A +.MR roff 7 +document is a text file that is enriched by predefined formatting +constructs, such as requests, escape sequences, strings, numeric +registers, and macros from a macro package. +. +These elements are described in +.MR roff 7 . +. +. +.P +To give a document a personal style, it is most useful to extend the +existing elements by defining some macros for repeating tasks; the best +place for this is near the beginning of the document or in a separate +file. +. +. +.P +Macros without arguments are just like strings. +. +But the full power of macros occurs when arguments are passed with a +macro call. +. +Within the macro definition, the arguments are available as the escape +sequences +.BR \[rs]$1 , +\&.\|.\|., +.BR \[rs]$9 , +.BR \[rs]$[ .\|.\|. ] , +.BR \[rs]$* , +and +.BR \[rs]$@ , +the name under which the macro was called is in +.BR \[rs]$0 , +and the number of arguments is in register +.BR \[rs]n[.$] ; +see +.MR groff 7 . +. +. +.\" ==================================================================== +.SS "Draft mode" +.\" ==================================================================== +. +Writing groff macros is easy when the escaping mechanism is temporarily +disabled. +. +In groff, this is done by enclosing the macro definition(s) within a +pair of +.B .eo +and +.B .ec +requests. +. +Then the body in the macro definition is just like a normal part of +the document \[em] text enhanced by calls of requests, macros, +strings, registers, etc. +. +For example, the code above can be written in a simpler way by +. +. +.IP +.ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\" +.ds @2 arguments:\" +.EX +\&.eo +\&.ds midpart was called with the following +\&.de print_args +\&\*[@1]\ \[rs]*[midpart]\ \[rs]n[.$]\ \*[@2] +\&\[rs]$* +\&.. +\&.ec +.EE +.rm @1 +.rm @2 +. +. +.P +Unfortunately, draft mode cannot be used universally. +. +Although it is good enough for defining normal macros, draft mode +fails with advanced applications, such as indirectly defined +strings, registers, etc. +. +An optimal way is to define and test all macros in draft mode and then +do the backslash doubling as a final step; do not forget to remove the +.I .eo +request. +. +. +.\" ==================================================================== +.SS "Tips for macro definitions" +.\" ==================================================================== +. +.IP \(bu +Start every line with a dot, for example, by using the groff request +.B .nop +for text lines, or write your own macro that handles also text lines +with a leading dot. +. +.RS +.IP +.EX +\&.de Text +\&.\ \ if (\[rs]\[rs]n[.$] == 0)\ \[rs] +\&.\ \ \ \ return +\&.\ \ nop\ \[rs])\[rs]\[rs]$*\[rs]) +\&.. +.EE +.RE +. +.IP \(bu +Write a comment macro that works both for copy and draft modes; +since the escape character is off in draft mode, +trouble might occur when comment escape sequences are used. +. +For example, the following macro just ignores its arguments, so it +acts like a comment line: +. +.RS +.IP +.EX +\&.de\ c +\&.. +\&.c\ This\ is\ like\ a\ comment\ line. +.EE +.RE +. +.IP \(bu +In long macro definitions, make ample use of comment lines or +almost-empty lines (this is, lines which have a leading dot +and nothing else) for a better structuring. +. +.IP \(bu +To increase readability, use groff's indentation facility for +requests and macro calls (arbitrary whitespace after the leading dot). +. +. +.\" ==================================================================== +.SS Diversions +.\" ==================================================================== +. +Diversions can be used to implement quite advanced programming +constructs. +. +They are comparable to pointers to large data structures in the +C\~programming language, but their usage is quite different. +. +. +.P +In their simplest form, diversions are multi-line strings, but +diversions get their power when used dynamically within macros. +. +The (formatted) information stored in a diversion can be retrieved by +calling the diversion just like a macro. +. +. +.P +Most of the problems arising with diversions can be avoided if you +remember that diversions always store complete lines. +. +Using diversions when the line buffer has not been flushed produces +strange results; not knowing this, many people get desperate about +diversions. +. +To ensure that a diversion works, add line breaks at the right +places. +. +To be safe, enclose everything that has to do with diversions within +a pair of line breaks; for example, by explicitly using +.B .br +requests. +. +This rule should be applied to diversion definition, both inside and +outside, and to all calls of diversions. +. +This is a bit of overkill, but it works nicely. +. +. +.P +(If you really need diversions which should ignore the current partial +line, use environments to save the current partial line and/\:or use the +.B .box +request.) +. +. +.P +The most powerful feature using diversions is to start a diversion +within a macro definition and end it within another macro. +. +Then everything between each call of this macro pair is stored within +the diversion and can be manipulated from within the macros. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +This document was written by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME , +.MT wl@\:gnu\:.org +Werner Lemberg +.ME , +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.LP +The +.UR https://\:wiki\:.linuxfoundation\:.org/\:lsb/\:fhs +Filesystem Hierarchy Standard +.UE +is maintained by the Linux Foundation. +. +. +.TP +.MR groff 1 +is an overview of the +.I groff +system. +. +. +.TP +.MR groff_man 7 , +.TQ +.MR groff_mdoc 7 , +.TQ +.MR groff_me 7 , +.TQ +.MR groff_mm 7 , +.TQ +.MR groff_mom 7 , +.TQ +.MR groff_ms 7 , +.TQ +.MR groff_rfc1345 7 , +.TQ +.MR groff_trace 7 , +\~and +.TQ +.MR groff_www 7 +are +.I groff +macro packages. +. +. +.TP +.MR groff 7 +summarizes the language recognized by GNU +.IR troff . \" GNU +. +. +.TP +.MR troff 1 +documents the default macro file search path. +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_tmac_5_man_C] +.do rr *groff_groff_tmac_5_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |