tmac/groff_tmac.man

   1 .\"                        -*- nroff -*-
   2 .ig /
   3 groff_tmac.5
   4
   5 This file is part of groff, the GNU roff type-setting system.
   6
   7 Copyright (C) 2000 Free Software Foundation, Inc.
   8 written by Bernd Warken <bwarken@mayn.de>
   9
  10 Last update: 17 May 2000
  11
  12 Permission is granted to copy, distribute and/or modify this document
  13 under the terms of the GNU Free Documentation License, Version 1.1 or
  14 any later version published by the Free Software Foundation; with the
  15 Invariant Sections being this .ig-section and AUTHOR, with no
  16 Front-Cover Texts, and with no Back-Cover Texts.
  17
  18 A copy of the Free Documentation License is included as a file called
  19 FDL in the main directory of the groff source package.
  20 ./
  21 .
  22 .\" --------------------------------------------------------------------
  23 .\" Setup
  24 .\" --------------------------------------------------------------------
  25 .
  26 .if n \{\
  27 .  mso tty-char.tty
  28 .  ftr CR R
  29 .  ftr CI I
  30 .  ftr CB B
  31 .\}
  32 .
  33 .\" text lines in macro definitions or bracketed sections \{...\}
  34 .de text
  35 .  if 1 \&\\$*\&
  36 ..
  37 .
  38 .de BIR
  39 .  ie (\\n[.$] < 3) \
  40 .    BI $@
  41 .  el \{\
  42 .    ds @tmp@ \fB\\$1\fP\fI\\$2\fP
  43 .    shift 2
  44 .    text \\*[@tmp@]\fR\\$*\fP
  45 .    rm @tmp@
  46 .  \}
  47 ..
  48 .
  49 .de 'char
  50 .  ds @tmp@ `\f(CB\\$1\fP'
  51 .  shift
  52 .  text \\*[@tmp@]\\$*
  53 .  rm @tmp@
  54 ..
  55 .
  56 .de option
  57 .  ds @tmp@ \f(CB\\$1\fP
  58 .  shift 1
  59 .  text \\*[@tmp@]\\$*
  60 .  rm @tmp@
  61 ..
  62 .
  63 .als shellcommand option
  64 .
  65 .de argument
  66 .  ds @tmp@ \f(CI\\$1\fP
  67 .  shift 1
  68 .  text \\*[@tmp@]\\$*
  69 .  rm @tmp@
  70 ..
  71 .
  72 .de request
  73 .  ds @tmp@ \f(CB\\$1\fP
  74 .  shift 1
  75 .  text \\*[@tmp@]\\$*
  76 .  rm @tmp@
  77 ..
  78 .
  79 .\" --------------------------------------------------------------------
  80 .\" Title
  81 .\" --------------------------------------------------------------------
  82 .TH GROFF_TMAC @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
  83 .SH NAME
  84 groff_tmac \- macro files in the roff typesetting system
  85 .\" --------------------------------------------------------------------
  86 .SH DESCRIPTION
  87 .\" --------------------------------------------------------------------
  88 The
  89 .BR roff (@MAN7EXT@)
  90 type-setting system provides a set of macro packages suitable for
  91 special kinds of documents.  Each macro package stores its macros and
  92 definitions in a file called the package's
  93 .BR "tmac file" .
  94 The name is deduced from
  95 .RB ` T roff
  96 .BR MAC ros'.
  97 .LP
  98 The tmac files are normal roff source documents, except that they
  99 usually contain only definitions and setup commands, but no text.  All
 100 tmac files are kept in a single or a small number of directories, the
 101 .B tmac
 102 directories.
 103 .\" --------------------------------------------------------------------
 104 .SH NAMING
 105 .\" --------------------------------------------------------------------
 106 In classical roff systems, there was a funny naming scheme.
 107 If the name of a macro package started with
 108 .'char m
 109 this letter was omitted, e.g., the macro package for the man pages
 110 .I man
 111 was called
 112 .I an
 113 and its macro file
 114 .I tmac.an
 115 (note that in recent versions of groff this file is called
 116 .I an.tmac
 117 instead).
 118 .LP
 119 By a similar reasoning, macro packages that did not start with an
 120 .'char m
 121 were often referred to by adding an
 122 .'char m ,
 123 e.g., the package corresponding to
 124 .I tmac.doc
 125 was called
 126 .I mdoc
 127 because the command-line for activating it reads
 128 .RS
 129 .LP
 130 .BIR "troff\ \-m" doc .
 131 .RE
 132 .LP
 133 Actual versions of
 134 .BR groff (@MAN1EXT@)
 135 provide both naming schemes for the inflicted macro packages, with and
 136 without the leading
 137 .'char m .
 138 So in
 139 .IR groff ,
 140 the
 141 .I man
 142 macro package may be specified as
 143 .RS
 144 .LP
 145 .BIR "groff\ \-m\ " man ,
 146 .br
 147 .BIR "groff\ \-m" an ,
 148 .br
 149 .BIR "groff\ \-m" man , or
 150 .br
 151 .BIR "groff\ \-m " an .
 152 .RE
 153 .LP
 154 The easiest way to find out which macro packages are available on a
 155 system is to check the contents of the
 156 .I tmac
 157 directories.
 158 For example, a file called
 159 .BI tmac. anything
 160 or
 161 .IB anything .tmac
 162 determines a macro package named
 163 .IR anything .
 164 .LP
 165 In
 166 .IR groff ,
 167 most macro packages are described in man pages called
 168 .BR groff_<name> (@MAN7EXT@),
 169 with a leading
 170 .'char m
 171 for the classical packages.
 172 .\" --------------------------------------------------------------------
 173 .SH INCLUSION
 174 .\" --------------------------------------------------------------------
 175 There are several ways to use a macro package in documents.  At
 176 run-time, the groff option
 177 .option \-m \ \c
 178 .argument name
 179 makes the definitions in the macro file
 180 .IB name .tmac
 181 available as described in the section
 182 .BR NAMING .
 183 If this file isn't found,
 184 .BI tmac. name
 185 will be searched.
 186 .LP
 187 It is also possible to include the macro file into the document by using
 188 the groff requests
 189 .request .so
 190 or
 191 .request .mso .
 192 For
 193 .request .so
 194 the full filename of the macro file must be specified \(em including the
 195 directory where it is kept.
 196 If the macro file is stored in one of the tmac directories it is more
 197 convenient to use
 198 .request .mso
 199 instead because it searches the tmac path for the filename.
 200 Additionally, if the file name to be included has the form
 201 .IB name .tmac
 202 and it isn't found,
 203 .request .mso
 204 will try to open
 205 .BI tmac. name
 206 instead and vice versa.
 207 .LP
 208 Note that in order to resolve the
 209 .request .so
 210 and
 211 .request .mso
 212 requests the roff preprocessor
 213 .shellcommand soelim
 214 must be called if the files to be included needs preprocessing.
 215 This can be done either directly by a pipeline on the command line or by
 216 using the
 217 .option \-s
 218 option of
 219 .shellcommand groff .
 220 .LP
 221 You can also supply the letter
 222 .'char s
 223 in the preprocessor word as described in section
 224 .BR CONVENTION .
 225 .LP
 226 For example, suppose a macro file is stored as
 227 .I @MACRODIR@/macros.tmac
 228 and is used in some document called
 229 .IR docu.roff .
 230 .LP
 231 At run-time, the formatter call for this is
 232 .RS
 233 .LP
 234 .ft CR
 235 .shellcommand "groff\ \-m"
 236 .argument macros
 237 .argument docu.roff
 238 .ft P
 239 .RE
 240 .LP
 241 To include the macro file directly in the document either
 242 .RS
 243 .ft CR
 244 \&\.mso macros.tmac
 245 .ft P
 246 .RE
 247 is used or
 248 .RS
 249 .ft CR
 250 \&\.so @MACRODIR@/macros.tmac
 251 .ft P
 252 .RE
 253 .LP
 254 In both cases, the formatter is called with
 255 .ft CR
 256 .RS
 257 groff\ \-s docu.roff
 258 .RE
 259 .ft P
 260 .
 261 .\" --------------------------------------------------------------------
 262 .SH CONVENTION
 263 .\" --------------------------------------------------------------------
 264 .LP
 265 There is a convention that is supported by many modern roff
 266 type-setters: the
 267 .B preprocessor word
 268 described in the following.
 269 .LP
 270 If the first line in a document is a comment, the first word (after the
 271 comment characters and a blank) constitutes the
 272 .B preprocessor
 273 .BR word .
 274 That means that the letters of this word are interpreted as
 275 abbreviations for those preprocessor commands that should be run
 276 when formatting the document.  Mostly, only the letters corresponding to
 277 the options for the preprocessors are recognized,
 278 .'char e ,
 279 .'char G ,
 280 .'char g ,
 281 .'char p ,
 282 .'char R ,
 283 .'char s , and
 284 .'char t
 285 (see
 286 .BR roff (@MAN7EXT@)).
 287 .LP
 288 Besides being a good reminder for the user, some formatters (like the
 289 .BR man (1)
 290 program) are even able to automatically start the preprocessors
 291 specified in the preprocessor word, but do not bet on this.
 292 .\" --------------------------------------------------------------------
 293 .SH "WRITING A MACRO FILE"
 294 .\" --------------------------------------------------------------------
 295 Writing a groff macro file is easy.  Design a set of macros, strings,
 296 registers, etc.  Store them in a single file.  Documents that use the
 297 macros include this macro file with the
 298 .request .so
 299 request as described in the
 300 .B INCLUSION
 301 section.
 302 .LP
 303 To use the tmac functionality, call the macro file
 304 .IB whatever .tmac
 305 (or
 306 .BI tmac. whatever\c
 307 ) and put it in some directory of the tmac path, cf. section
 308 .BR FILES .
 309 Then documents can include it with the
 310 .request .mso
 311 request or the
 312 .shellcommand "groff\ \-m"
 313 option as described in the
 314 .B INCLUSION
 315 section.
 316 .LP
 317 If your macros might be of general usage contact the groff maintainers
 318 to have them included in the groff
 319 .I contrib
 320 source directory.
 321 .LP
 322 Some general guidelines might be helpful in writing macros.
 323 .IP \(bu 2m
 324 Double all functional backslashes,
 325 .'char \e
 326 ->
 327 .'char \e\e .
 328 .IP \(bu 2m
 329 All printable backslashes must be written as
 330 .'char \ee .
 331 .IP \(bu 2m
 332 Escape all dots,
 333 .'char .
 334 ->
 335 .'char \e. .
 336 .IP \(bu 2m
 337 Make ample use of the non-printable character
 338 .'char \e&
 339 in text parts, esp. before
 340 .'char \e
 341 and at the beginning of a line, but not before a delayed command.
 342 .IP \(bu 2m
 343 Use the character
 344 .'char @
 345 in temporary variable names.
 346 .IP \(bu 2m
 347 Test your macros for text and graphical devices, e.g.,
 348 .I latin1
 349 and
 350 .IR ps .
 351 .\" --------------------------------------------------------------------
 352 .SH FILES
 353 .\" --------------------------------------------------------------------
 354 All macro names must be named
 355 .IB name .tmac
 356 or
 357 .BI tmac. name
 358 to use the tmac mechanism.
 359 .LP
 360 The macro files are kept in the
 361 .B tmac
 362 .BR directories ,
 363 all of which constitute the
 364 .B tmac
 365 .BR path.
 366 .LP
 367 The elements of the search path for macro files are (in that order):
 368 .IP \(bu 4
 369 the directories specified with troff's resp. groff's
 370 .B \-M
 371 command line option
 372 .IP \(bu 4
 373 the directories given in the
 374 .B GROFF_TMAC_PATH
 375 environment variable
 376 .IP \(bu 4
 377 the current directory (only if in unsafe mode using the
 378 .B \-U
 379 command line switch)
 380 .IP \(bu 4
 381 the home directory
 382 .IP \(bu 4
 383 a site-specific (platform-independent) directory, a platform-specific
 384 directory, and the main tmac directory:
 385 .IP "" 6
 386 @LOCALMACRODIR@
 387 .br
 388 @SYSTEMMACRODIR@
 389 .br
 390 @MACRODIR@
 391 .\" --------------------------------------------------------------------
 392 .SH ENVIRONMENT
 393 .\" --------------------------------------------------------------------
 394 .TP
 395 .B GROFF_TMAC_PATH
 396 A colon separated list of additional tmac directories in which to search
 397 for macro files.
 398 See the previous section for a detailed description.
 399 .\" --------------------------------------------------------------------
 400 .SH BUGS
 401 .\" --------------------------------------------------------------------
 402 The groff documentation is in evolution at the moment.  It is possible
 403 that small inconsistencies between different documents exist
 404 temporarily.
 405 .\" --------------------------------------------------------------------
 406 .SH AUTHOR
 407 .\" --------------------------------------------------------------------
 408 This document is part of groff, the GNU roff distribution.  It was
 409 written by Bernd Warken <bwarken@mayn.de>.
 410 .LP
 411 It is distributed under the terms of the FDL (GNU Free Documentation
 412 License) version 1.1 or later.  You should have received a copy of the
 413 FDL on your system, it is also available on-line under
 414 .RS
 415 .LP
 416 .IR <http://www.gnu.org/copyleft/fdl.html> .
 417 .RE
 418 .\" --------------------------------------------------------------------
 419 .SH "SEE ALSO"
 420 .\" --------------------------------------------------------------------
 421 The authoritative source of information for all details of the groff
 422 system is the groff
 423 .BR info (1)
 424 file.
 425 .LP
 426 For a groff overview, see
 427 .BR roff (@MAN7EXT@)
 428 and the file
 429 .I README
 430 in the groff source package.
 431 .LP
 432 The groff tmac macro packages are
 433 .BR groff_man (@MAN7EXT@),
 434 .BR groff_markup (@MAN7EXT@),
 435 .BR groff_mdoc (@MAN7EXT@),
 436 .BR groff_mdoc.samples (@MAN7EXT@),
 437 .BR groff_me (@MAN7EXT@),
 438 .BR groff_mm (@MAN7EXT@),
 439 .BR groff_mmroff (@MAN7EXT@),
 440 and
 441 .BR groff_ms (@MAN7EXT@).
 442 .LP
 443 The groff language is described in
 444 .BR groff (@MAN7EXT@)
 445 and the formatters in
 446 .BR groff (@MAN1EXT@),
 447 .BR troff (@MAN1EXT@).
 448 .LP
 449 The Filesystem Hierarchy Standard (FHS) is available at
 450 .BR http://www.pathname.com/fhs/ .