| 1 |
.TH groff_tmac 5 "2026-04-22" "groff 1.24.1" |
| 2 |
.SH Name |
| 3 |
groff_tmac \- macro files in the GNU |
| 4 |
.I roff |
| 5 |
typesetting system |
| 6 |
. |
| 7 |
. |
| 8 |
.\" ==================================================================== |
| 9 |
.\" Legal Terms |
| 10 |
.\" ==================================================================== |
| 11 |
.\" |
| 12 |
.\" Copyright 2000-2024 Free Software Foundation, Inc. |
| 13 |
.\" |
| 14 |
.\" This file is part of groff, the GNU roff typesetting system. |
| 15 |
.\" |
| 16 |
.\" Permission is granted to copy, distribute and/or modify this |
| 17 |
.\" document under the terms of the GNU Free Documentation License, |
| 18 |
.\" Version 1.3 or any later version published by the Free Software |
| 19 |
.\" Foundation; with no Invariant Sections, with no Front-Cover Texts, |
| 20 |
.\" and with no Back-Cover Texts. |
| 21 |
.\" |
| 22 |
.\" A copy of the Free Documentation License is included as a file |
| 23 |
.\" called FDL in the main directory of the groff source package. |
| 24 |
.\" |
| 25 |
.\" A copy of the GNU Free Documentation License is also available in this |
| 26 |
.\" Debian package as /usr/share/doc/groff/copyright. |
| 27 |
. |
| 28 |
. |
| 29 |
.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). |
| 30 |
.do nr *groff_groff_tmac_5_man_C \n[.cp] |
| 31 |
.cp 0 |
| 32 |
. |
| 33 |
.\" Define fallback for groff 1.23's MR macro if the system lacks it. |
| 34 |
.nr do-fallback 0 |
| 35 |
.if !\n(.f .nr do-fallback 1 \" mandoc |
| 36 |
.if \n(.g .if !d MR .nr do-fallback 1 \" older groff |
| 37 |
.if !\n(.g .nr do-fallback 1 \" non-groff *roff |
| 38 |
.if \n[do-fallback] \{\ |
| 39 |
. de MR |
| 40 |
. ie \\n(.$=1 \ |
| 41 |
. I \%\\$1 |
| 42 |
. el \ |
| 43 |
. IR \%\\$1 (\\$2)\\$3 |
| 44 |
. . |
| 45 |
.\} |
| 46 |
.rr do-fallback |
| 47 |
. |
| 48 |
.\" This man page employs an unusual character. |
| 49 |
.if !c \[u2717] .char \[u2717] X |
| 50 |
. |
| 51 |
. |
| 52 |
.\" TODO: Consider parallelizing with our Texinfo node "Macro Packages". |
| 53 |
.\" ==================================================================== |
| 54 |
.SH Description |
| 55 |
.\" ==================================================================== |
| 56 |
. |
| 57 |
Definitions of macros, |
| 58 |
strings, |
| 59 |
and registers for use in a |
| 60 |
.MR roff 7 |
| 61 |
document can be collected into |
| 62 |
.IR "macro files" , |
| 63 |
.I roff |
| 64 |
input files designed to produce no output themselves but instead ease |
| 65 |
the preparation of other |
| 66 |
.I roff |
| 67 |
documents. |
| 68 |
. |
| 69 |
There is no syntactical difference between a macro file and any other |
| 70 |
.I roff |
| 71 |
document; |
| 72 |
only its purpose distinguishes it. |
| 73 |
. |
| 74 |
When a macro file is installed at a standard location, |
| 75 |
named according to a certain convention, |
| 76 |
and suitable for use by a general audience, |
| 77 |
it is termed a |
| 78 |
.IR "macro package" . |
| 79 |
. |
| 80 |
The \[lq]tmac\[rq] name originated in early Unix culture as an |
| 81 |
abbreviation of |
| 82 |
.RI \[lq] troff \" generic |
| 83 |
macros\[rq]. |
| 84 |
. |
| 85 |
. |
| 86 |
.P |
| 87 |
Macro packages can be loaded by supplying the |
| 88 |
.B \-m |
| 89 |
option to |
| 90 |
.MR \%troff 1 |
| 91 |
or a |
| 92 |
.I groff |
| 93 |
front end. |
| 94 |
. |
| 95 |
A macro file's name must have the form |
| 96 |
.RI name .tmac |
| 97 |
(or |
| 98 |
.IR tmac. name) |
| 99 |
and be placed in a |
| 100 |
.RI \[lq] tmac |
| 101 |
directory\[rq] to be loadable with the |
| 102 |
.RB \[lq] \-m |
| 103 |
.IR name \[rq] |
| 104 |
option. |
| 105 |
. |
| 106 |
Section \[lq]Environment\[rq] of |
| 107 |
.MR \%troff 1 |
| 108 |
lists these directories. |
| 109 |
. |
| 110 |
Alternatively, |
| 111 |
a |
| 112 |
.I groff |
| 113 |
document requiring a macro file can load it with the |
| 114 |
.B mso |
| 115 |
(\[lq]macro source\[rq]) request. |
| 116 |
. |
| 117 |
. |
| 118 |
.P |
| 119 |
Macro files are named for their most noteworthy application, |
| 120 |
but a macro file need not define any macros. |
| 121 |
. |
| 122 |
It can restrict itself to defining registers and strings or invoking |
| 123 |
other |
| 124 |
.I groff |
| 125 |
requests. |
| 126 |
. |
| 127 |
It can even be empty. |
| 128 |
. |
| 129 |
. |
| 130 |
.P |
| 131 |
Encode macro files in |
| 132 |
ISO\~646:1991\~IRV (US-ASCII) |
| 133 |
or ISO\~Latin-1 (8859-1). |
| 134 |
. |
| 135 |
To prepare for a future |
| 136 |
.I groff |
| 137 |
release supporting UTF-8 input, |
| 138 |
restrict files to ISO 646 codes. |
| 139 |
. |
| 140 |
. |
| 141 |
.MR \%soelim 1 |
| 142 |
by design does not interpret |
| 143 |
.B mso |
| 144 |
requests, |
| 145 |
and the encodings used by documents employing a macro file can vary. |
| 146 |
. |
| 147 |
. |
| 148 |
.\" ==================================================================== |
| 149 |
.SH "Macro packages" |
| 150 |
.\" ==================================================================== |
| 151 |
. |
| 152 |
Some macro packages |
| 153 |
(\[lq]major\[rq] or \[lq]full-service\[rq]) |
| 154 |
assume responsibility for page layout |
| 155 |
and other critical functions; |
| 156 |
others |
| 157 |
(\[lq]supplemental\[rq] or \[lq]auxiliary\[rq]) |
| 158 |
do not. |
| 159 |
. |
| 160 |
GNU |
| 161 |
.I roff |
| 162 |
provides most major macro packages found in AT&T and BSD Unix systems, |
| 163 |
an additional full-service package, |
| 164 |
and many supplemental packages. |
| 165 |
. |
| 166 |
Multiple full-service macro packages cannot be used by the same |
| 167 |
document. |
| 168 |
. |
| 169 |
Auxiliary packages can, |
| 170 |
in general, |
| 171 |
be freely combined, |
| 172 |
though attention to their use of the |
| 173 |
.I groff |
| 174 |
language name spaces for identifiers |
| 175 |
(particularly registers, |
| 176 |
macros, |
| 177 |
strings, |
| 178 |
and diversions) |
| 179 |
should be paid. |
| 180 |
. |
| 181 |
Name space management challenged AT&T |
| 182 |
.I troff \" AT&T |
| 183 |
users; |
| 184 |
GNU |
| 185 |
.IR troff 's \" GNU |
| 186 |
support for arbitrarily long identifiers affords few excuses for name |
| 187 |
collisions, |
| 188 |
apart from attempts at compatibility with the demands of historical |
| 189 |
documents. |
| 190 |
. |
| 191 |
. |
| 192 |
.\" ==================================================================== |
| 193 |
.SS "Man pages" |
| 194 |
.\" ==================================================================== |
| 195 |
. |
| 196 |
Two full-service macro packages are specialized for formatting Unix |
| 197 |
reference manuals; |
| 198 |
they do not support features like footnotes or multiple columnation. |
| 199 |
. |
| 200 |
.TP 9n \" "mandoc" + 2n + hand-tuned for PDF |
| 201 |
.I an |
| 202 |
constructs man pages in a format introduced by Seventh Edition Unix |
| 203 |
(1979). |
| 204 |
. |
| 205 |
Its macro interface is small, |
| 206 |
and the package widely used; |
| 207 |
see |
| 208 |
.MR groff_man 7 . |
| 209 |
. |
| 210 |
. |
| 211 |
.TP |
| 212 |
.I doc |
| 213 |
constructs man pages in a format introduced by 4.3BSD-Reno (1990). |
| 214 |
. |
| 215 |
It provides many more features than |
| 216 |
.IR an , |
| 217 |
but is also larger, |
| 218 |
more complex, |
| 219 |
and not as widely adopted; |
| 220 |
see |
| 221 |
.MR groff_mdoc 7 . |
| 222 |
. |
| 223 |
. |
| 224 |
.P |
| 225 |
Because readers of man pages often do not know in advance which macros |
| 226 |
are used to format a given document, |
| 227 |
a wrapper is available. |
| 228 |
. |
| 229 |
. |
| 230 |
.TP 9n \" "mandoc" + 2n + hand-tuned for PDF |
| 231 |
.I \%andoc |
| 232 |
recognizes a document's use of |
| 233 |
.I an |
| 234 |
or |
| 235 |
.I doc |
| 236 |
and loads the corresponding macro package. |
| 237 |
. |
| 238 |
Multiple man pages, |
| 239 |
in either format, |
| 240 |
can be handled; |
| 241 |
.I \%andoc |
| 242 |
reloads each macro package as necessary. |
| 243 |
. |
| 244 |
. |
| 245 |
.\" ==================================================================== |
| 246 |
.SS "General full-service packages" |
| 247 |
.\" ==================================================================== |
| 248 |
. |
| 249 |
The following packages each support composition of documents of any |
| 250 |
kind, |
| 251 |
from single-page memos to lengthy monographs. |
| 252 |
. |
| 253 |
They are similar in functionality; |
| 254 |
select one that suits your taste. |
| 255 |
. |
| 256 |
. |
| 257 |
.TP |
| 258 |
.I me |
| 259 |
originates in 2BSD (1978); |
| 260 |
see |
| 261 |
.MR groff_me 7 . |
| 262 |
. |
| 263 |
. |
| 264 |
.TP |
| 265 |
.I mm |
| 266 |
originates in Programmer's Workbench (PWB) Unix 1.0 (1977); |
| 267 |
see |
| 268 |
.MR groff_mm 7 . |
| 269 |
. |
| 270 |
. |
| 271 |
.TP |
| 272 |
.I mom |
| 273 |
was contributed to |
| 274 |
.I groff |
| 275 |
in 2002, |
| 276 |
and freely exercises its many extended features. |
| 277 |
. |
| 278 |
See |
| 279 |
.MR groff_mom 7 . |
| 280 |
. |
| 281 |
. |
| 282 |
.TP |
| 283 |
.I ms |
| 284 |
originates in Sixth Edition Unix (1975); |
| 285 |
see |
| 286 |
.MR groff_ms 7 . |
| 287 |
. |
| 288 |
. |
| 289 |
.\" ==================================================================== |
| 290 |
.SS "Localization packages" |
| 291 |
.\" ==================================================================== |
| 292 |
. |
| 293 |
For Western languages, |
| 294 |
an auxiliary package for localization |
| 295 |
sets the hyphenation mode and loads hyphenation patterns |
| 296 |
and exceptions. |
| 297 |
. |
| 298 |
Localization files can also adjust the date format and provide |
| 299 |
translations of strings used by some of the full-service macro packages; |
| 300 |
alter the input encoding |
| 301 |
(see the next section); |
| 302 |
and change the amount of supplemental inter-sentence space. |
| 303 |
. |
| 304 |
For Eastern languages, |
| 305 |
the localization file defines character classes and sets flags on them. |
| 306 |
. |
| 307 |
By default, |
| 308 |
.I troffrc |
| 309 |
loads the localization file for English. |
| 310 |
. |
| 311 |
. |
| 312 |
.TP |
| 313 |
.I trans |
| 314 |
loads localized strings used by various macro packages after their |
| 315 |
localized forms have been prepared by a localization macro file. |
| 316 |
. |
| 317 |
. |
| 318 |
.P |
| 319 |
.I groff |
| 320 |
provides the following localization files. |
| 321 |
. |
| 322 |
. |
| 323 |
.TP |
| 324 |
.I cs |
| 325 |
Czech; |
| 326 |
localizes |
| 327 |
.IR man , |
| 328 |
.IR me , |
| 329 |
.IR mm , |
| 330 |
.IR mom , |
| 331 |
and |
| 332 |
.IR ms . |
| 333 |
. |
| 334 |
Sets the input encoding to Latin-2 by loading |
| 335 |
.IR latin2.tmac . |
| 336 |
. |
| 337 |
. |
| 338 |
.TP |
| 339 |
.I de |
| 340 |
.TQ |
| 341 |
.I den |
| 342 |
German; |
| 343 |
localizes |
| 344 |
.IR man , |
| 345 |
.IR me , |
| 346 |
.IR mm , |
| 347 |
.IR mom , |
| 348 |
and |
| 349 |
.IR ms . |
| 350 |
. |
| 351 |
Sets the input encoding to Latin-1 by loading |
| 352 |
.IR latin1.tmac . |
| 353 |
. |
| 354 |
. |
| 355 |
.IP |
| 356 |
.I de.tmac |
| 357 |
selects hyphenation patterns for traditional orthography, |
| 358 |
and |
| 359 |
.I den.tmac |
| 360 |
does the same for the new orthography |
| 361 |
(\[lq]Recht\%schreib\%reform\[rq]). |
| 362 |
. |
| 363 |
. |
| 364 |
.TP |
| 365 |
.I en |
| 366 |
English. |
| 367 |
. |
| 368 |
Sets the input encoding to Latin-1 by loading |
| 369 |
.IR latin1.tmac . |
| 370 |
. |
| 371 |
. |
| 372 |
.TP |
| 373 |
.I es |
| 374 |
Spanish; |
| 375 |
localizes |
| 376 |
.IR man , |
| 377 |
.IR me , |
| 378 |
.IR mm , |
| 379 |
.IR mom , |
| 380 |
and |
| 381 |
.IR ms . |
| 382 |
. |
| 383 |
Sets the input encoding to Latin-9 by loading |
| 384 |
.IR latin9.tmac . |
| 385 |
. |
| 386 |
. |
| 387 |
.TP |
| 388 |
.I fr |
| 389 |
French; |
| 390 |
localizes |
| 391 |
.IR man , |
| 392 |
.IR me , |
| 393 |
.IR mm , |
| 394 |
.IR mom , |
| 395 |
and |
| 396 |
.IR ms . |
| 397 |
. |
| 398 |
Sets the input encoding to Latin-9 by loading |
| 399 |
.IR latin9.tmac . |
| 400 |
. |
| 401 |
. |
| 402 |
.TP |
| 403 |
.I it |
| 404 |
Italian; |
| 405 |
localizes |
| 406 |
.IR man , |
| 407 |
.IR me , |
| 408 |
.IR mm , |
| 409 |
.IR mom , |
| 410 |
and |
| 411 |
.IR ms . |
| 412 |
. |
| 413 |
Sets the input encoding to Latin-1 by loading |
| 414 |
.IR latin1.tmac . |
| 415 |
. |
| 416 |
. |
| 417 |
.TP |
| 418 |
.I ja |
| 419 |
Japanese. |
| 420 |
. |
| 421 |
. |
| 422 |
.TP |
| 423 |
.I pl |
| 424 |
Polish; |
| 425 |
localizes |
| 426 |
.IR man , |
| 427 |
.IR me , |
| 428 |
.IR mm , |
| 429 |
.IR mom , |
| 430 |
and |
| 431 |
.IR ms . |
| 432 |
. |
| 433 |
Sets the input encoding to Latin-2 by loading |
| 434 |
.IR latin2.tmac . |
| 435 |
. |
| 436 |
. |
| 437 |
.TP |
| 438 |
.I ru |
| 439 |
Russian; |
| 440 |
localizes |
| 441 |
.IR man , |
| 442 |
.IR me , |
| 443 |
.IR mm , |
| 444 |
.IR mom , |
| 445 |
and |
| 446 |
.IR ms . |
| 447 |
. |
| 448 |
Sets the input encoding to KOI8-R by loading |
| 449 |
.IR koi8-r.tmac . |
| 450 |
. |
| 451 |
. |
| 452 |
.TP |
| 453 |
.I sv |
| 454 |
Swedish; |
| 455 |
localizes |
| 456 |
.IR man , |
| 457 |
.IR me , |
| 458 |
.IR mm , |
| 459 |
.IR mom , |
| 460 |
and |
| 461 |
.IR ms . |
| 462 |
. |
| 463 |
Sets the input encoding to Latin-1 by loading |
| 464 |
.IR latin1.tmac . |
| 465 |
. |
| 466 |
Some of the localization of the |
| 467 |
.I mm |
| 468 |
package is handled separately; |
| 469 |
see |
| 470 |
.MR groff_mmse 7 |
| 471 |
(only in Swedish locales). |
| 472 |
. |
| 473 |
. |
| 474 |
.TP |
| 475 |
.I zh |
| 476 |
Chinese. |
| 477 |
. |
| 478 |
. |
| 479 |
.\" ==================================================================== |
| 480 |
.SS "Input encodings" |
| 481 |
.\" ==================================================================== |
| 482 |
. |
| 483 |
Localization influences automatic hyphenation |
| 484 |
in two distinct but related respects. |
| 485 |
A macro file specific to a character coding identifies |
| 486 |
which character codes correspond to letters expected |
| 487 |
in the language's hyphenation pattern files |
| 488 |
and sets up case equivalences for those letters. |
| 489 |
A language's macro file determines which of these letters |
| 490 |
are equivalent to other letters for hyphenation purposes. |
| 491 |
. |
| 492 |
. |
| 493 |
.P |
| 494 |
For example, |
| 495 |
in English, |
| 496 |
the letter \[lq]\[n a~]\[rq] occurs in loan words. |
| 497 |
The |
| 498 |
.I \%latin1.tmac |
| 499 |
and |
| 500 |
.I \%latin9.tmac |
| 501 |
macro files define a hyphenation code for \[lq]\[n a~]\[rq] |
| 502 |
and make \[lq]\[N a~]\[rq] equivalent to it. |
| 503 |
The English localization file |
| 504 |
.I \%en.tmac |
| 505 |
furthermore makes \[lq]\[n a~]\[rq] equivalent to \[lq]n\[rq]. |
| 506 |
In Spanish |
| 507 |
.RI \%( es.tmac ), |
| 508 |
however, |
| 509 |
\[lq]\[n a~]\[rq] and \[lq]n\[rq] are |
| 510 |
.I not |
| 511 |
equivalent. |
| 512 |
The language localization file |
| 513 |
.\" (@pxref{Manipulating Hyphenation}) |
| 514 |
loads an appropriate encoding localization file; |
| 515 |
a document need not do so directly. |
| 516 |
. |
| 517 |
. |
| 518 |
.TP 8n \" "latin1" + 2n |
| 519 |
.I latin1 |
| 520 |
.TQ |
| 521 |
.I latin2 |
| 522 |
.TQ |
| 523 |
.I latin5 |
| 524 |
.TQ |
| 525 |
.I latin9 |
| 526 |
support the ISO\~Latin-1, |
| 527 |
Latin-2, |
| 528 |
Latin-5, |
| 529 |
and |
| 530 |
Latin-9 encodings |
| 531 |
(8859-1, |
| 532 |
8859-2, |
| 533 |
8859-9, |
| 534 |
and |
| 535 |
8859-15, |
| 536 |
respectively). |
| 537 |
. |
| 538 |
. |
| 539 |
.TP |
| 540 |
.I koi8\-r |
| 541 |
supports the KOI8-R encoding. |
| 542 |
. |
| 543 |
KOI8-R code points in the range 0x80\[en]0x9F are not valid input to GNU |
| 544 |
.IR troff ; \" GNU |
| 545 |
see section \[lq]Identifiers\[rq] in |
| 546 |
.MR groff 7 . |
| 547 |
. |
| 548 |
This should be no impediment to practical documents, |
| 549 |
as these KOI8-R code points do not encode letters, |
| 550 |
but box-drawing symbols and characters that are better obtained via |
| 551 |
special character escape sequences; |
| 552 |
see |
| 553 |
.MR groff_char 7 . |
| 554 |
. |
| 555 |
. |
| 556 |
.\" ==================================================================== |
| 557 |
.SS "General auxiliary packages" |
| 558 |
.\" ==================================================================== |
| 559 |
. |
| 560 |
The macro packages in this section are not intended for stand-alone |
| 561 |
use, |
| 562 |
but can add functionality to any other macro package or to plain |
| 563 |
(\[lq]raw\[rq]) |
| 564 |
.I groff |
| 565 |
documents. |
| 566 |
. |
| 567 |
. |
| 568 |
.\" TODO: |
| 569 |
.\" devtag |
| 570 |
.\" europs |
| 571 |
.\" psatk |
| 572 |
.\" psfig |
| 573 |
.TP 11n \" "papersize" + 2n |
| 574 |
.I 62bit |
| 575 |
provides macros for addition, |
| 576 |
multiplication, |
| 577 |
and division of 62-bit integers |
| 578 |
(allowing safe multiplication of signed 31-bit integers, |
| 579 |
for example). |
| 580 |
. |
| 581 |
. |
| 582 |
.br |
| 583 |
.ne 4v |
| 584 |
.TP |
| 585 |
.I hdtbl |
| 586 |
allows the generation of tables using a syntax similar to the HTML table |
| 587 |
model. |
| 588 |
. |
| 589 |
This Heidelberger table macro package is not a preprocessor, |
| 590 |
which can be useful if the contents of table entries are determined by |
| 591 |
macro calls or string interpolations. |
| 592 |
. |
| 593 |
Compare to |
| 594 |
.MR \%tbl 1 . |
| 595 |
. |
| 596 |
It works only with the |
| 597 |
.B ps |
| 598 |
and |
| 599 |
.B pdf |
| 600 |
output devices. |
| 601 |
. |
| 602 |
See |
| 603 |
.MR groff_hdtbl 7 . |
| 604 |
. |
| 605 |
. |
| 606 |
.TP |
| 607 |
.I papersize |
| 608 |
enables the paper format to be set on the command line with the |
| 609 |
.RB \[lq] \-d |
| 610 |
.BI \%paper= fmt\c |
| 611 |
\[rq] |
| 612 |
option to |
| 613 |
.IR \%troff . |
| 614 |
. |
| 615 |
Valid |
| 616 |
.IR fmt s |
| 617 |
are the ISO and DIN formats |
| 618 |
.RB \[lq] A0 \[en] A6 \[rq], |
| 619 |
.RB \[lq] B0 \[en] B6 \[rq], |
| 620 |
.RB \[lq] C0 \[en] C6 \[rq], |
| 621 |
and |
| 622 |
.RB \[lq] D0 \[en] D6 \[rq]; |
| 623 |
.\" XXX: src/libs/libgroff/paper.cpp also supports [ABCD]7. |
| 624 |
the U.S.\& formats |
| 625 |
.RB \%\[lq] letter \[rq], |
| 626 |
.RB \%\[lq] legal \[rq], |
| 627 |
.RB \%\[lq] tabloid \[rq], |
| 628 |
.RB \%\[lq] ledger \[rq], |
| 629 |
.RB \%\[lq] statement \[rq], |
| 630 |
and |
| 631 |
.RB \%\[lq] executive \[rq]; |
| 632 |
and the envelope formats |
| 633 |
.RB \%\[lq] com10 \[rq], |
| 634 |
.RB \%\[lq] monarch \[rq], |
| 635 |
and |
| 636 |
.RB \%\[lq] DL \[rq]. |
| 637 |
. |
| 638 |
All formats, |
| 639 |
even those for envelopes, |
| 640 |
are in portrait orientation: |
| 641 |
the longer measurement is vertical. |
| 642 |
. |
| 643 |
Appending \[lq]l\[rq] (ell) to any of these denotes landscape |
| 644 |
orientation instead. |
| 645 |
. |
| 646 |
This macro file assumes one-inch horizontal margins, |
| 647 |
and sets registers recognized by the |
| 648 |
.I groff |
| 649 |
.IR man , |
| 650 |
.IR mdoc , |
| 651 |
.IR mm , |
| 652 |
.IR mom , |
| 653 |
and |
| 654 |
.I ms |
| 655 |
packages to configure them accordingly. |
| 656 |
. |
| 657 |
If you want different margins, |
| 658 |
you will need to use those packages' facilities, |
| 659 |
or |
| 660 |
.I \%troff |
| 661 |
.B ll |
| 662 |
and/or |
| 663 |
.B po |
| 664 |
requests, |
| 665 |
to adjust them. |
| 666 |
. |
| 667 |
An output device typically requires command-line options |
| 668 |
.B \-p |
| 669 |
and |
| 670 |
.B \-l |
| 671 |
to override the paper dimensions and orientation, |
| 672 |
respectively, |
| 673 |
defined in its |
| 674 |
.I DESC |
| 675 |
file; |
| 676 |
see subsection \[lq]Paper format\[rq] |
| 677 |
of |
| 678 |
.MR groff 1 . |
| 679 |
. |
| 680 |
This macro file is normally loaded at startup by the |
| 681 |
.I troffrc |
| 682 |
file when formatting for a typesetter |
| 683 |
(but not a terminal). |
| 684 |
. |
| 685 |
. |
| 686 |
.TP |
| 687 |
.I pdfpic |
| 688 |
provides a single macro, |
| 689 |
.BR \%PDFPIC , |
| 690 |
that operates in two modes. |
| 691 |
. |
| 692 |
If it is not used with |
| 693 |
.IR gropdf , |
| 694 |
the given |
| 695 |
.I file |
| 696 |
must be a PDF; |
| 697 |
.B \%PDFPIC |
| 698 |
then relies on the external program |
| 699 |
.MR pdftops 1 |
| 700 |
to convert the PDF to an encapsulated PostScript (EPS) file |
| 701 |
and calls the |
| 702 |
.B PSPIC |
| 703 |
macro with which it shares an interface. |
| 704 |
. |
| 705 |
If output is to a PDF document, |
| 706 |
.B \%PDFPIC |
| 707 |
uses the |
| 708 |
.RB \[lq] "pdf: \%pdfpic" \[rq] |
| 709 |
device extension command |
| 710 |
(see |
| 711 |
.MR gropdf 1 ); |
| 712 |
the given |
| 713 |
.I file |
| 714 |
can then be a PDF or any graphic file format supported by |
| 715 |
.IR gropdf . |
| 716 |
. |
| 717 |
. |
| 718 |
.IP |
| 719 |
Since |
| 720 |
.B \%PDFPIC |
| 721 |
needs to discover the width and height of the image |
| 722 |
(to check if sufficient room exists to place it on the page), |
| 723 |
it has dependencies on external programs as shown below. |
| 724 |
. |
| 725 |
. |
| 726 |
.IP |
| 727 |
.TS |
| 728 |
allbox center; |
| 729 |
Cb Ci Ci Ci |
| 730 |
Li C C C. |
| 731 |
\& pdfinfo\fR(1) file\fR(1) identify\fR(1) |
| 732 |
\&.pdf \[OK] \[OK] \[OK] |
| 733 |
\&.jpg \[u2717] \[OK] \[OK] |
| 734 |
\&.jp2 \[u2717] \[u2717] \[OK] |
| 735 |
\fRother \[u2717] \[u2717] \[OK] |
| 736 |
.TE |
| 737 |
. |
| 738 |
. |
| 739 |
.IP |
| 740 |
To include image formats such as PNG, |
| 741 |
PAM, |
| 742 |
and GIF, |
| 743 |
.I gropdf |
| 744 |
relies upon PerlMagick modules to embed the graphic. |
| 745 |
. |
| 746 |
They are not needed for the types listed in the table above. |
| 747 |
. |
| 748 |
. |
| 749 |
.IP |
| 750 |
If the required programs are not available, |
| 751 |
.I file |
| 752 |
is treated as a PDF; |
| 753 |
failure is likely if it is not one. |
| 754 |
. |
| 755 |
. |
| 756 |
.TP |
| 757 |
.I pic |
| 758 |
supplies definitions of the macros |
| 759 |
.BR PS , |
| 760 |
.BR PE , |
| 761 |
.BR PF , |
| 762 |
and |
| 763 |
.BR PY , |
| 764 |
used with the |
| 765 |
.MR \%pic 1 |
| 766 |
preprocessor. |
| 767 |
. |
| 768 |
They center each picture. |
| 769 |
. |
| 770 |
Use it if your document does not use a full-service macro package, |
| 771 |
or that package does not supply working |
| 772 |
.I pic |
| 773 |
macro definitions. |
| 774 |
. |
| 775 |
Except for |
| 776 |
.I man |
| 777 |
and |
| 778 |
.IR mdoc , |
| 779 |
those provided with |
| 780 |
.I groff |
| 781 |
already do so |
| 782 |
(exception: |
| 783 |
.I mm |
| 784 |
employs the name |
| 785 |
.B PF |
| 786 |
for a different purpose). |
| 787 |
. |
| 788 |
. |
| 789 |
.TP |
| 790 |
.I pspic |
| 791 |
provides a macro, |
| 792 |
.BR PSPIC , |
| 793 |
that includes a PostScript graphic in a document. |
| 794 |
. |
| 795 |
The |
| 796 |
.BR ps , |
| 797 |
.BR dvi , |
| 798 |
.BR html , |
| 799 |
and |
| 800 |
.B xhtml |
| 801 |
output devices support such inclusions; |
| 802 |
for all other drivers, |
| 803 |
the image is replaced with a rectangular border of the same size. |
| 804 |
. |
| 805 |
.I pspic.tmac |
| 806 |
is loaded at startup by the |
| 807 |
.I troffrc |
| 808 |
file. |
| 809 |
. |
| 810 |
. |
| 811 |
.br |
| 812 |
.ne 3v |
| 813 |
.IP |
| 814 |
Its syntax is as follows. |
| 815 |
.RS |
| 816 |
.IP |
| 817 |
\&\fB.PSPIC\fP \ |
| 818 |
[\fB\-L\fP\|\ |
| 819 |
|\|\fB\-R\fP\|\ |
| 820 |
|\|\fB\-C\fP\|\ |
| 821 |
|\|\fB\-I\fP\~\fIn\fP] \ |
| 822 |
\fI\|file\fP [\fIwidth\fP [\,\fIheight\/\fP]] |
| 823 |
.RE |
| 824 |
. |
| 825 |
. |
| 826 |
.IP |
| 827 |
.I file |
| 828 |
is the name of the PostScript file; |
| 829 |
.I width |
| 830 |
and |
| 831 |
.I height |
| 832 |
give the desired width and height of the image. |
| 833 |
. |
| 834 |
If neither a |
| 835 |
.I width |
| 836 |
nor a |
| 837 |
.I height |
| 838 |
argument is specified, |
| 839 |
the image's natural width |
| 840 |
(as given in the file's bounding box) |
| 841 |
or the current line length is used as the width, |
| 842 |
whatever is smaller. |
| 843 |
. |
| 844 |
The |
| 845 |
.I width |
| 846 |
and |
| 847 |
.I height |
| 848 |
arguments may have scaling units attached; |
| 849 |
the default scaling unit |
| 850 |
.RB is\~ i . |
| 851 |
. |
| 852 |
.B PSPIC |
| 853 |
scales the graphic uniformly in the horizontal and vertical directions |
| 854 |
so that it is no more than |
| 855 |
.I width |
| 856 |
wide |
| 857 |
and |
| 858 |
.I height |
| 859 |
high. |
| 860 |
. |
| 861 |
Option |
| 862 |
.B \-C |
| 863 |
centers the graphic horizontally; |
| 864 |
this is the default. |
| 865 |
. |
| 866 |
.B \-L |
| 867 |
and |
| 868 |
.B \-R |
| 869 |
left- and right-align the graphic, |
| 870 |
respectively. |
| 871 |
. |
| 872 |
.B \-I |
| 873 |
indents the graphic |
| 874 |
.RI by\~ n |
| 875 |
(with a default scaling unit |
| 876 |
.RB of\~ m ). |
| 877 |
. |
| 878 |
. |
| 879 |
.IP |
| 880 |
To use |
| 881 |
.B PSPIC |
| 882 |
within a diversion, |
| 883 |
we recommend extending it with the following code, |
| 884 |
assuring that the diversion's width completely covers the image's width. |
| 885 |
. |
| 886 |
. |
| 887 |
.RS |
| 888 |
.IP |
| 889 |
.EX |
| 890 |
\&.am PSPIC |
| 891 |
\&.\~\~vpt 0 |
| 892 |
\&\[rs]h\[aq](\[rs]\[rs]n[ps\-offset]u + \[rs]\[rs]n[ps\-deswid]u)\[aq] |
| 893 |
\&.\~\~sp \-1 |
| 894 |
\&.\~\~vpt 1 |
| 895 |
\&.. |
| 896 |
.EE |
| 897 |
.RE |
| 898 |
. |
| 899 |
. |
| 900 |
.IP |
| 901 |
Failure to load |
| 902 |
.BR PSPIC 's |
| 903 |
image argument is not an error. |
| 904 |
. |
| 905 |
(The |
| 906 |
.B psbb |
| 907 |
request does issue an error diagnostic.) |
| 908 |
. |
| 909 |
To make such a failure fatal, |
| 910 |
append to the |
| 911 |
.B pspic*error\-hook |
| 912 |
macro. |
| 913 |
. |
| 914 |
. |
| 915 |
.RS |
| 916 |
.IP |
| 917 |
.EX |
| 918 |
\&.am pspic*error\-hook |
| 919 |
\&.\~\~ab |
| 920 |
\&.. |
| 921 |
.EE |
| 922 |
.RE |
| 923 |
. |
| 924 |
. |
| 925 |
.TP |
| 926 |
.I ptx |
| 927 |
provides a macro, |
| 928 |
.BR xx , |
| 929 |
to format permuted index entries as produced by the GNU |
| 930 |
.MR ptx 1 |
| 931 |
program. |
| 932 |
. |
| 933 |
If your formatting needs differ, |
| 934 |
copy the macro into your document and adapt it. |
| 935 |
. |
| 936 |
. |
| 937 |
.TP |
| 938 |
.I rfc1345 |
| 939 |
defines special character escape sequences named for the glyph mnemonics |
| 940 |
specified in RFC\~1345 and the digraph table of the Vim text editor. |
| 941 |
. |
| 942 |
See |
| 943 |
.MR groff_rfc1345 7 . |
| 944 |
. |
| 945 |
. |
| 946 |
.TP |
| 947 |
.I sboxes |
| 948 |
offers an interface to the |
| 949 |
.RB \[lq] "pdf: background" \[rq] |
| 950 |
device extension command supported by |
| 951 |
.MR gropdf 1 . |
| 952 |
. |
| 953 |
Using this package, |
| 954 |
.I groff ms |
| 955 |
documents can draw colored rectangles beneath any output. |
| 956 |
. |
| 957 |
.RS |
| 958 |
.TP |
| 959 |
.BI \%.BOXSTART\~SHADED\~ color\~\c |
| 960 |
.BI \%OUTLINED\~ color\~\c |
| 961 |
.BI \%INDENT\~ size\~\c |
| 962 |
.BI \%WEIGHT\~ size |
| 963 |
begins a box, |
| 964 |
where the argument after |
| 965 |
.B \%SHADED |
| 966 |
gives the fill color and that after |
| 967 |
.B \%OUTLINED |
| 968 |
the border color. |
| 969 |
. |
| 970 |
Omit the former to get a borderless filled box and the latter for a |
| 971 |
border with no fill. |
| 972 |
. |
| 973 |
The specified |
| 974 |
.B \%WEIGHT |
| 975 |
is used if the box is |
| 976 |
.BR \%OUTLINED . |
| 977 |
. |
| 978 |
. |
| 979 |
.IP |
| 980 |
.B \%INDENT |
| 981 |
precedes a value that leaves a gap between the border and the contents |
| 982 |
inside the box. |
| 983 |
. |
| 984 |
. |
| 985 |
.IP |
| 986 |
Each |
| 987 |
.I color |
| 988 |
must be a defined |
| 989 |
.I groff |
| 990 |
color name, |
| 991 |
and each |
| 992 |
.I size |
| 993 |
a valid |
| 994 |
.I groff |
| 995 |
numeric expression. |
| 996 |
. |
| 997 |
The keyword/value pairs can be specified in any order. |
| 998 |
.RE |
| 999 |
. |
| 1000 |
. |
| 1001 |
.IP |
| 1002 |
Boxes can be stacked, |
| 1003 |
so you can start a box within another box; |
| 1004 |
usually the later boxes would be smaller than the containing box, |
| 1005 |
but this is not enforced. |
| 1006 |
. |
| 1007 |
When using |
| 1008 |
.BR \%BOXSTART , |
| 1009 |
the left position is the current indent minus the |
| 1010 |
.B \%INDENT |
| 1011 |
in the command, |
| 1012 |
and the right position is the left position |
| 1013 |
(calculated above) |
| 1014 |
plus the current line length and twice the indent. |
| 1015 |
. |
| 1016 |
. |
| 1017 |
.RS |
| 1018 |
.TP |
| 1019 |
.B \%.BOXSTOP |
| 1020 |
takes no parameters. |
| 1021 |
. |
| 1022 |
It closes the most recently started box at the current vertical position |
| 1023 |
after adding its |
| 1024 |
.B \%INDENT |
| 1025 |
spacing. |
| 1026 |
.RE |
| 1027 |
. |
| 1028 |
. |
| 1029 |
.IP |
| 1030 |
Your |
| 1031 |
.I groff |
| 1032 |
documents can conditionally exercise the |
| 1033 |
.I sboxes |
| 1034 |
macros. |
| 1035 |
. |
| 1036 |
The register |
| 1037 |
.B \%GSBOX |
| 1038 |
is defined if the package is loaded, |
| 1039 |
and interpolates a true value if the |
| 1040 |
.B pdf |
| 1041 |
output device is in use. |
| 1042 |
. |
| 1043 |
. |
| 1044 |
.IP |
| 1045 |
.I sboxes |
| 1046 |
furthermore hooks into the |
| 1047 |
.MR groff_ms 7 |
| 1048 |
package to receive notifications when footnotes are growing, |
| 1049 |
so that it can close boxes on a page before footnotes are printed. |
| 1050 |
. |
| 1051 |
When that condition obtains, |
| 1052 |
.I sboxes |
| 1053 |
will close open boxes two points |
| 1054 |
above the footnote separator and re-open them on the next page. |
| 1055 |
. |
| 1056 |
(This amount probably will not match the box's |
| 1057 |
.BR \%INDENT .) |
| 1058 |
. |
| 1059 |
. |
| 1060 |
.IP |
| 1061 |
See |
| 1062 |
.UR file:///usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%msboxes\:.pdf |
| 1063 |
\[lq]Using PDF boxes with |
| 1064 |
.I groff |
| 1065 |
and the |
| 1066 |
.I ms |
| 1067 |
macros\[rq] |
| 1068 |
.UE |
| 1069 |
for a demonstration. |
| 1070 |
. |
| 1071 |
. |
| 1072 |
.TP |
| 1073 |
.I trace |
| 1074 |
aids the debugging of |
| 1075 |
.I groff |
| 1076 |
documents by tracing macro calls. |
| 1077 |
. |
| 1078 |
See |
| 1079 |
.MR groff_trace 7 . |
| 1080 |
. |
| 1081 |
. |
| 1082 |
.TP |
| 1083 |
.I www |
| 1084 |
defines macros corresponding to HTML elements. |
| 1085 |
. |
| 1086 |
See |
| 1087 |
.MR groff_www 7 . |
| 1088 |
. |
| 1089 |
. |
| 1090 |
.\" ==================================================================== |
| 1091 |
.SH Naming |
| 1092 |
.\" ==================================================================== |
| 1093 |
. |
| 1094 |
AT&T |
| 1095 |
.I nroff \" AT&T |
| 1096 |
and |
| 1097 |
.I troff \" AT&T |
| 1098 |
were implemented before the conventions of the modern C |
| 1099 |
.MR getopt 3 |
| 1100 |
call evolved, |
| 1101 |
and used a naming scheme for macro packages that looks oddly terse to |
| 1102 |
modern eyes. |
| 1103 |
. |
| 1104 |
The formatter's |
| 1105 |
.B \-m |
| 1106 |
option was the main means of loading a macro package, |
| 1107 |
and its argument had to follow immediately without intervening space. |
| 1108 |
This looked like a long option name preceded by a single minus\[em]a |
| 1109 |
sensation in the computer stone age. |
| 1110 |
. |
| 1111 |
Macro packages therefore came to be known by names that started with the |
| 1112 |
letter \[lq]m\[rq], |
| 1113 |
which was omitted from the name of the macro file as stored on disk. |
| 1114 |
. |
| 1115 |
For example, |
| 1116 |
the manuscript macro package was stored as |
| 1117 |
.I tmac.s |
| 1118 |
and loaded with the option |
| 1119 |
.BR \-ms . |
| 1120 |
. |
| 1121 |
It has since become conventional in operating systems to use a suffixed |
| 1122 |
file name extension to suggest a file type or format, |
| 1123 |
thus we see |
| 1124 |
.I roff |
| 1125 |
documents with names ending in |
| 1126 |
.IR .man , |
| 1127 |
.IR .me , |
| 1128 |
and so on. |
| 1129 |
. |
| 1130 |
. |
| 1131 |
.br |
| 1132 |
.ne 2v |
| 1133 |
.P |
| 1134 |
.I groff |
| 1135 |
commands permit space between an option and its argument. |
| 1136 |
. |
| 1137 |
The syntax |
| 1138 |
.RB \[lq] "groff \-m s" \[rq] |
| 1139 |
makes the macro file name more clear but may surprise users familiar |
| 1140 |
with the original convention, |
| 1141 |
unaware that the package's \[lq]real\[rq] name was \[lq]s\[rq] all |
| 1142 |
along. |
| 1143 |
. |
| 1144 |
For such packages of long pedigree, |
| 1145 |
.I groff |
| 1146 |
accommodates different users' expectations by supplying wrapper macro |
| 1147 |
files that load the desired file with |
| 1148 |
.B mso |
| 1149 |
requests. |
| 1150 |
. |
| 1151 |
Thus, |
| 1152 |
all of |
| 1153 |
.RB \[lq] "groff \-m s" \[rq], |
| 1154 |
.RB \[lq] "groff \-m ms" \[rq], |
| 1155 |
.RB \[lq] "groff \-ms" \[rq], |
| 1156 |
and |
| 1157 |
.RB \[lq] "groff \-mms" \[rq] |
| 1158 |
serve to load the manuscript macros. |
| 1159 |
. |
| 1160 |
. |
| 1161 |
.\" ==================================================================== |
| 1162 |
.SH Inclusion |
| 1163 |
.\" ==================================================================== |
| 1164 |
. |
| 1165 |
The traditional method of employing a macro package is to specify the |
| 1166 |
.RB \[lq] \-m |
| 1167 |
.IR package \[rq] |
| 1168 |
option to the formatter, |
| 1169 |
which then reads |
| 1170 |
.IR package 's |
| 1171 |
macro file prior to any input. |
| 1172 |
. |
| 1173 |
Historically, |
| 1174 |
.I package |
| 1175 |
was sought in a file named |
| 1176 |
.IR tmac. package |
| 1177 |
(that is, |
| 1178 |
with a |
| 1179 |
.RB \[lq] tmac.\& \[rq] |
| 1180 |
prefix). |
| 1181 |
. |
| 1182 |
GNU |
| 1183 |
.I troff \" GNU |
| 1184 |
searches for |
| 1185 |
.RI package .tmac |
| 1186 |
in the macro path; |
| 1187 |
if not found, |
| 1188 |
it looks for |
| 1189 |
.IR tmac. package |
| 1190 |
instead, |
| 1191 |
and vice versa. |
| 1192 |
. |
| 1193 |
. |
| 1194 |
.P |
| 1195 |
Alternatively, |
| 1196 |
one could include a macro file with the request |
| 1197 |
.RB \[lq] so |
| 1198 |
.IR file-name \[rq]; |
| 1199 |
the argument is resolved as |
| 1200 |
.MR fopen 3 |
| 1201 |
would, |
| 1202 |
from the current working directory of the formatter. |
| 1203 |
. |
| 1204 |
This approach was inadequate to locate macro packages, |
| 1205 |
since systems stored them in varying locations. |
| 1206 |
. |
| 1207 |
GNU |
| 1208 |
.I troff \" GNU |
| 1209 |
offers an improved feature in the similar request |
| 1210 |
.RB \[lq] mso |
| 1211 |
.IR package-file-name \[rq], |
| 1212 |
which searches the macro path for |
| 1213 |
.IR package-file-name . |
| 1214 |
. |
| 1215 |
Because its argument is a file name, |
| 1216 |
its |
| 1217 |
.RB \[lq] .tmac \[rq] |
| 1218 |
component must be included for the file to be found. |
| 1219 |
. |
| 1220 |
. |
| 1221 |
.P |
| 1222 |
If a sourced file requires preprocessing, |
| 1223 |
for example if it includes |
| 1224 |
.I tbl \" generic |
| 1225 |
tables |
| 1226 |
or |
| 1227 |
.I eqn \" generic |
| 1228 |
equations, |
| 1229 |
the preprocessor |
| 1230 |
.MR \%soelim 1 |
| 1231 |
must be used. |
| 1232 |
. |
| 1233 |
This can be achieved with a pipeline or by specifying the |
| 1234 |
.B \-s |
| 1235 |
option to |
| 1236 |
.MR groff 1 . |
| 1237 |
. |
| 1238 |
.MR man 1 |
| 1239 |
librarian programs typically run |
| 1240 |
.I \%soelim |
| 1241 |
automatically. |
| 1242 |
. |
| 1243 |
(As a rule, |
| 1244 |
macro packages themselves do not require preprocessing.) |
| 1245 |
. |
| 1246 |
. |
| 1247 |
.ig |
| 1248 |
.\" ==================================================================== |
| 1249 |
.SH Convention |
| 1250 |
.\" ==================================================================== |
| 1251 |
. |
| 1252 |
.\" This section does not fit into the framework of this document. |
| 1253 |
. |
| 1254 |
There is a convention that is supported by many modern roff |
| 1255 |
typesetters and |
| 1256 |
.MR man 1 |
| 1257 |
programs, the |
| 1258 |
.I preprocessor word |
| 1259 |
described in the following. |
| 1260 |
. |
| 1261 |
.P |
| 1262 |
If the first line in a document is a comment, the first word (after the |
| 1263 |
comment characters and a blank) constitutes the |
| 1264 |
.B preprocessor |
| 1265 |
.BR word . |
| 1266 |
That means that the letters of this word are interpreted as |
| 1267 |
abbreviations for those preprocessor commands that should be run |
| 1268 |
when formatting the document. |
| 1269 |
. |
| 1270 |
Mostly, only the letters corresponding to the options for the |
| 1271 |
preprocessors are recognized, |
| 1272 |
\[oq]e\[cq] |
| 1273 |
(for |
| 1274 |
.IR eqn ), |
| 1275 |
.\" \[oq]G\[cq], |
| 1276 |
.\" \[oq]g\[cq], |
| 1277 |
\[oq]p\[cq] |
| 1278 |
(for |
| 1279 |
.IR pic ), |
| 1280 |
\[oq]R\[cq] |
| 1281 |
(for |
| 1282 |
.IR refer ), |
| 1283 |
\[oq]s\[cq] |
| 1284 |
(for |
| 1285 |
.IR soelim ), |
| 1286 |
and |
| 1287 |
\[oq]t\[cq] |
| 1288 |
(for |
| 1289 |
.IR tbl ). |
| 1290 |
(see |
| 1291 |
.MR roff 7 ). |
| 1292 |
. |
| 1293 |
. |
| 1294 |
.P |
| 1295 |
Besides being a good reminder for the user, some formatters (like the |
| 1296 |
.MR man 1 |
| 1297 |
program) are even able to automatically start the preprocessors |
| 1298 |
specified in the preprocessor word, but do not bet on this. |
| 1299 |
. |
| 1300 |
. |
| 1301 |
.P |
| 1302 |
The |
| 1303 |
.I man |
| 1304 |
program handles some preprocessors automatically, such that in |
| 1305 |
man\~pages only the following characters should be used: |
| 1306 |
\[oq]e\[cq], \[oq]p\[cq], and \[oq]t\[cq]. |
| 1307 |
. |
| 1308 |
. |
| 1309 |
.. |
| 1310 |
.\" XXX: The next section requires significant revision. |
| 1311 |
.\" ==================================================================== |
| 1312 |
.SH "Writing macros" |
| 1313 |
.\" ==================================================================== |
| 1314 |
. |
| 1315 |
A |
| 1316 |
.MR roff 7 |
| 1317 |
document is a text file that is enriched by predefined formatting |
| 1318 |
constructs, such as requests, escape sequences, strings, numeric |
| 1319 |
registers, and macros from a macro package. |
| 1320 |
. |
| 1321 |
.MR roff 7 |
| 1322 |
describes these elements. |
| 1323 |
. |
| 1324 |
. |
| 1325 |
.P |
| 1326 |
To give a document a personal style, it is most useful to extend the |
| 1327 |
existing elements by defining some macros for repeating tasks; the best |
| 1328 |
place for this is near the beginning of the document or in a separate |
| 1329 |
file. |
| 1330 |
. |
| 1331 |
. |
| 1332 |
.P |
| 1333 |
Macros without arguments are just like strings. |
| 1334 |
. |
| 1335 |
But the full power of macros occurs when arguments are passed with a |
| 1336 |
macro call. |
| 1337 |
. |
| 1338 |
Within the macro definition, the arguments are available as the escape |
| 1339 |
sequences |
| 1340 |
.BR \[rs]$1 , |
| 1341 |
\&.\|.\|., |
| 1342 |
.BR \[rs]$9 , |
| 1343 |
.BR \[rs]$[ .\|.\|. ] , |
| 1344 |
.BR \[rs]$* , |
| 1345 |
and |
| 1346 |
.BR \[rs]$@ , |
| 1347 |
the name under which the macro was called is in |
| 1348 |
.BR \[rs]$0 , |
| 1349 |
and the number of arguments is in register |
| 1350 |
.BR \[rs]n[.$] ; |
| 1351 |
see |
| 1352 |
.MR groff 7 . |
| 1353 |
. |
| 1354 |
. |
| 1355 |
.\" ==================================================================== |
| 1356 |
.SS "Drafting macros" |
| 1357 |
.\" ==================================================================== |
| 1358 |
. |
| 1359 |
One approach temporarily disables escape sequences |
| 1360 |
by bracketing a macro definition with |
| 1361 |
.B eo |
| 1362 |
and |
| 1363 |
.B ec |
| 1364 |
requests. |
| 1365 |
. |
| 1366 |
. |
| 1367 |
.IP |
| 1368 |
.RS |
| 1369 |
.ds @1 \[rs]f[I]\[rs]$0\[rs]f[]\" |
| 1370 |
.ds @2 arguments:\" |
| 1371 |
.EX |
| 1372 |
\&.eo |
| 1373 |
\&.ds midpart was called with the following |
| 1374 |
\&.de print_args |
| 1375 |
\&\*[@1]\~\[rs]*[midpart]\~\[rs]n[.$]\~\*[@2] \[rs]$* |
| 1376 |
\&.. |
| 1377 |
\&.ec |
| 1378 |
.EE |
| 1379 |
.rm @1 |
| 1380 |
.rm @2 |
| 1381 |
.RE |
| 1382 |
. |
| 1383 |
. |
| 1384 |
.P |
| 1385 |
The above procedure has limitations; |
| 1386 |
it is unsuitable for a macro that requires certain interpolations at the |
| 1387 |
time it is defined, |
| 1388 |
or for indirect definitions of identifiers. |
| 1389 |
. |
| 1390 |
See section \[lq]Copy mode\[rq] of |
| 1391 |
.MR groff 7 . |
| 1392 |
. |
| 1393 |
In such cases, |
| 1394 |
you might define and test the macro with the escape character doubled |
| 1395 |
before escape sequences that are interpreted even in copy mode, |
| 1396 |
then bracket it with |
| 1397 |
.B eo |
| 1398 |
and |
| 1399 |
.B ec |
| 1400 |
requests, |
| 1401 |
un-double the escape characters, |
| 1402 |
then test again. |
| 1403 |
. |
| 1404 |
. |
| 1405 |
.\" ==================================================================== |
| 1406 |
.SS "Tips for macro definitions" |
| 1407 |
.\" ==================================================================== |
| 1408 |
. |
| 1409 |
.IP \(bu 3n |
| 1410 |
Use only control lines in macro definitions; |
| 1411 |
that is, |
| 1412 |
start every input line with a control character. |
| 1413 |
. |
| 1414 |
.IR groff 's |
| 1415 |
.B nop |
| 1416 |
request makes use of text lines unnecessary. |
| 1417 |
. |
| 1418 |
. |
| 1419 |
.RS |
| 1420 |
.IP |
| 1421 |
.EX |
| 1422 |
\&.de Text |
| 1423 |
\&. if (\[rs]\[rs]n[.$] == 0) \[rs] |
| 1424 |
\&. return |
| 1425 |
\&. nop \[rs]&\[rs]\[rs]$*\[rs]& |
| 1426 |
\&.. |
| 1427 |
.EE |
| 1428 |
.RE |
| 1429 |
. |
| 1430 |
. |
| 1431 |
.IP \(bu |
| 1432 |
Write a comment macro that works in both draft and non-draft modes; |
| 1433 |
since the escape character is disabled in draft mode, |
| 1434 |
trouble might occur when comment escape sequences are used. |
| 1435 |
. |
| 1436 |
.\" XXX: We need the vees. |
| 1437 |
.ig |
| 1438 |
For example, |
| 1439 |
the following macro ignores its arguments, |
| 1440 |
so calling it is a harmless |
| 1441 |
(if somewhat busy) |
| 1442 |
null operation. |
| 1443 |
.. |
| 1444 |
. |
| 1445 |
.RS |
| 1446 |
.IP |
| 1447 |
.EX |
| 1448 |
\&.de c |
| 1449 |
\&.. |
| 1450 |
\&.c This is my comment. |
| 1451 |
.EE |
| 1452 |
.RE |
| 1453 |
. |
| 1454 |
. |
| 1455 |
.IP \(bu |
| 1456 |
Comment lengthy macro definitions. |
| 1457 |
. |
| 1458 |
. |
| 1459 |
.IP \(bu |
| 1460 |
Use empty requests, |
| 1461 |
and indentation after control characters, |
| 1462 |
to clarify a macro's structure. |
| 1463 |
. |
| 1464 |
. |
| 1465 |
.\" ==================================================================== |
| 1466 |
.SH Authors |
| 1467 |
.\" ==================================================================== |
| 1468 |
. |
| 1469 |
This document was written by |
| 1470 |
.MT wl@\:gnu\:.org |
| 1471 |
Werner Lemberg |
| 1472 |
.ME |
| 1473 |
and |
| 1474 |
.MT g.branden\:.robinson@\:gmail\:.com |
| 1475 |
G.\& Branden Robinson |
| 1476 |
.ME . |
| 1477 |
. |
| 1478 |
. |
| 1479 |
.\" ==================================================================== |
| 1480 |
.SH "See also" |
| 1481 |
.\" ==================================================================== |
| 1482 |
. |
| 1483 |
.IR "Groff: The GNU Implementation of troff" , |
| 1484 |
by Trent A.\& Fisher and Werner Lemberg, |
| 1485 |
is the primary |
| 1486 |
.I groff |
| 1487 |
manual. |
| 1488 |
. |
| 1489 |
You can browse it interactively with \[lq]info groff\[rq]. |
| 1490 |
. |
| 1491 |
. |
| 1492 |
.TP 18n "groff_rfc1345(7)" + 2n |
| 1493 |
.MR groff 1 |
| 1494 |
is an overview of the |
| 1495 |
.I groff |
| 1496 |
system. |
| 1497 |
. |
| 1498 |
. |
| 1499 |
.TP |
| 1500 |
.MR groff_man 7 , |
| 1501 |
.TQ |
| 1502 |
.MR groff_mdoc 7 , |
| 1503 |
.TQ |
| 1504 |
.MR groff_me 7 , |
| 1505 |
.TQ |
| 1506 |
.MR groff_mm 7 , |
| 1507 |
.TQ |
| 1508 |
.MR groff_mom 7 , |
| 1509 |
.TQ |
| 1510 |
.MR groff_ms 7 , |
| 1511 |
.TQ |
| 1512 |
.MR groff_rfc1345 7 , |
| 1513 |
.TQ |
| 1514 |
.MR groff_trace 7 , |
| 1515 |
.TQ |
| 1516 |
and |
| 1517 |
.TQ |
| 1518 |
.MR groff_www 7 |
| 1519 |
are |
| 1520 |
.I groff |
| 1521 |
macro packages. |
| 1522 |
. |
| 1523 |
. |
| 1524 |
.TP |
| 1525 |
.MR groff 7 |
| 1526 |
summarizes the language recognized by GNU |
| 1527 |
.IR troff . \" GNU |
| 1528 |
. |
| 1529 |
. |
| 1530 |
.TP |
| 1531 |
.MR \%troff 1 |
| 1532 |
documents the default macro file search path. |
| 1533 |
. |
| 1534 |
. |
| 1535 |
.\" Restore compatibility mode (for, e.g., Solaris 10/11). |
| 1536 |
.cp \n[*groff_groff_tmac_5_man_C] |
| 1537 |
.do rr *groff_groff_tmac_5_man_C |
| 1538 |
. |
| 1539 |
. |
| 1540 |
.\" Local Variables: |
| 1541 |
.\" fill-column: 72 |
| 1542 |
.\" mode: nroff |
| 1543 |
.\" End: |
| 1544 |
.\" vim: set filetype=groff textwidth=72: |