man/groff_tmac.man

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