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 tmac.tty-char
  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 .IR tmac.an .
 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 content of the
 153 .I tmac
 154 directories.
 155 For example, a file called
 156 .BI tmac. anything
 157 determines a macro package named
 158 .IR anything .
 159 .LP
 160 In
 161 .IR groff ,
 162 most macro packages are described in man pages called
 163 .BR groff_<name> (@MAN7EXT@),
 164 with a leading
 165 .'char m
 166 for the classical packages.
 167 .\" --------------------------------------------------------------------
 168 .SH INCLUSION
 169 .\" --------------------------------------------------------------------
 170 There are several ways to use a macro package in documents.  At
 171 run-time, the groff option
 172 .option \-m \ \c
 173 .argument name
 174 makes the definitions in the macro file
 175 .BI tmac. name
 176 available as described in the section
 177 .BR NAMING .
 178 .LP
 179 It is also possible to include the macro file into the document by using
 180 the groff requests
 181 .request .so
 182 or
 183 .request .mso .
 184 For
 185 .request .so
 186 the full filename of the macro file must be specified \(em including the
 187 directory where it is kept.
 188 If the macro file is stored in one of the tmac directories it is more
 189 convenient to use
 190 .request .mso
 191 instead because it additionally searches the tmac path for the filename.
 192 .LP
 193 Note that in order to resolve the
 194 .request .so
 195 and
 196 .request .mso
 197 requests the roff preprocessor
 198 .shellcommand soelim
 199 must be called.  This can be done either directly by a pipeline on the
 200 command line or by using the
 201 .option \-s
 202 option of
 203 .shellcommand groff .
 204 .LP
 205 You can also supply the letter
 206 .'char s
 207 in the preprocessor word as described in section
 208 .BR CONVENTION .
 209 .LP
 210 For example, suppose a macro file is stored as
 211 .I /usr/share/groff/tmac/tmac.macros
 212 and is used in some document called
 213 .IR docu.roff .
 214 .LP
 215 At run-time, the formatter call for this is
 216 .RS
 217 .LP
 218 .ft CR
 219 .shellcommand "groff\ \-m"
 220 .argument macros
 221 .argument docu.roff
 222 .ft P
 223 .RE
 224 .LP
 225 To include the macro file directly in the document either
 226 .RS
 227 .ft CR
 228 \&\.mso tmac.macros
 229 .ft P
 230 .RE
 231 is used or
 232 .RS
 233 .ft CR
 234 \&\.so /usr/share/groff/tmac/tmac.macros
 235 .ft P
 236 .RE
 237 .LP
 238 In both cases, the formatter is called with
 239 .ft CR
 240 .RS
 241 groff\ \-s docu.roff
 242 .RE
 243 .ft P
 244 .
 245 .\" --------------------------------------------------------------------
 246 .SH CONVENTION
 247 .\" --------------------------------------------------------------------
 248 .LP
 249 There is a convention that is supported by many modern roff
 250 type-setters: the
 251 .B preprocessor word
 252 described in the following.
 253 .LP
 254 If the first line in a document is a comment, the first word (after the
 255 comment characters and a blank) constitutes the
 256 .B preprocessor
 257 .BR word .
 258 That means that the letters of this word are interpreted as
 259 abbreviations for those preprocessor commands that should be run
 260 when formatting the document.  Mostly, only the letters corresponding to
 261 the options for the preprocessors are recognized,
 262 .'char e ,
 263 .'char G ,
 264 .'char g ,
 265 .'char p ,
 266 .'char R ,
 267 .'char s , and
 268 .'char t
 269 (see
 270 .BR roff (@MAN7EXT@)).
 271 .LP
 272 Besides being a good reminder for the user, some formatters (like the
 273 .BR man (1)
 274 program) are even able to automatically start the preprocessors
 275 specified in the preprocessor word, but do not bet on this.
 276 .\" --------------------------------------------------------------------
 277 .SH "WRITING A MACRO FILE"
 278 .\" --------------------------------------------------------------------
 279 Writing a groff macro file is easy.  Design a set of macros, strings,
 280 registers, etc.  Store them in a single file.  Documents that use the
 281 macros include this macro file with the
 282 .request .so
 283 request as described in the
 284 .B INCLUSION
 285 section.
 286 .LP
 287 To use the tmac functionality, call the macro file
 288 .BI tmac. whatever
 289 and put it in some directory of the tmac path, cf. section
 290 .BR FILES .
 291 Then documents can include it with the
 292 .request .mso
 293 request or the
 294 .shellcommand "groff\ \-m"
 295 option as described in the
 296 .B INCLUSION
 297 section.
 298 .LP
 299 If your macros might be of general usage contact the groff maintainers
 300 to have them included in the groff
 301 .I contrib
 302 source directory.
 303 .LP
 304 Some general guidelines might be helpful in writing macros.
 305 .IP \(bu 2m
 306 Double all functional backslashes,
 307 .'char \e
 308 ->
 309 .'char \e\e .
 310 .IP \(bu 2m
 311 All printable backslashes must be written as
 312 .'char \ee .
 313 .IP \(bu 2m
 314 Escape all dots,
 315 .'char .
 316 ->
 317 .'char \e. .
 318 .IP \(bu 2m
 319 Make ample use of the non-printable character
 320 .'char \e&
 321 in text parts, esp. before
 322 .'char \e
 323 and at the beginning of a line, but not before a delayed command.
 324 .IP \(bu 2m
 325 Use the character
 326 .'char @
 327 in temporary variable names.
 328 .IP \(bu 2m
 329 Test your macros for text and graphical devices, e.g.,
 330 .I latin1
 331 and
 332 .IR ps .
 333 .\" --------------------------------------------------------------------
 334 .SH FILES
 335 .\" --------------------------------------------------------------------
 336 All macro names that want to use the tmac mechanism must be named
 337 according to the form
 338 .BIR tmac. name .
 339 .LP
 340 The macro files are kept in the
 341 .B tmac
 342 .BR directories ,
 343 all of which constitue the
 344 .B tmac
 345 .BR path.
 346 In accordance with the Filesystem Hierarchy Standard (FHS), the standard
 347 tmac directory location for groff is
 348 .IR /usr/share/groff/tmac ,
 349 a local installation will use
 350 .IR /usr/local/share/groff/tmac .
 351 Older systems used a subdirectory of
 352 .IR /usr/lib .
 353 Independently of the default tmac path, the tmac path actually used by a
 354 document can always be set by a shell environment variable, cf. section
 355 .BR ENVIRONMENT .
 356 .\" --------------------------------------------------------------------
 357 .SH ENVIRONMENT
 358 .\" --------------------------------------------------------------------
 359 .TP
 360 .B GROFF_TMAC_PATH
 361 A colon separated list of tmac directories in which to search for macro
 362 files, the
 363 .B tmac
 364 .BR path .
 365 If unset a default path is used as is outlined in the
 366 .B FILES
 367 section.
 368 .\" --------------------------------------------------------------------
 369 .SH BUGS
 370 .\" --------------------------------------------------------------------
 371 The groff documentation is in evolution at the moment.  It is possible
 372 that small inconsistencies between different documents exist
 373 temporarily.
 374 .\" --------------------------------------------------------------------
 375 .SH AUTHOR
 376 .\" --------------------------------------------------------------------
 377 This document is part of groff, the GNU roff distribution.  It was
 378 written by Bernd Warken <bwarken@mayn.de>.
 379 .LP
 380 It is distributed under the terms of the FDL (GNU Free Documentation
 381 License) version 1.1 or later.  You should have received a copy of the
 382 FDL on your system, it is also available on-line under
 383 .RS
 384 .LP
 385 .IR <http://www.gnu.org/copyleft/fdl.html> .
 386 .RE
 387 .\" --------------------------------------------------------------------
 388 .SH "SEE ALSO"
 389 .\" --------------------------------------------------------------------
 390 The authoritative source of information for all details of the groff
 391 system is the groff
 392 .BR info (1)
 393 file.
 394 .LP
 395 For a groff overview, see
 396 .BR roff (@MAN7EXT@)
 397 and the file
 398 .I README
 399 in the groff source package.
 400 .LP
 401 The groff tmac macro packages are
 402 .BR groff_man (@MAN7EXT@),
 403 .BR groff_markup (@MAN7EXT@),
 404 .BR groff_mdoc (@MAN7EXT@),
 405 .BR groff_mdoc.samples (@MAN7EXT@),
 406 .BR groff_me (@MAN7EXT@),
 407 .BR groff_mm (@MAN7EXT@),
 408 .BR groff_mmroff (@MAN7EXT@),
 409 .BR groff_ms (@MAN7EXT@),
 410 .BR groff_msafer (@MAN7EXT@).
 411 .LP
 412 The groff language is described in
 413 .BR groff (@MAN7EXT@)
 414 and the formatters in
 415 .BR groff (@MAN1EXT@),
 416 .BR troff (@MAN1EXT@).
 417 .LP
 418 The Filesystem Hierarchy Standard (FHS) is available at
 419 .BR http://www.pathname.com/fhs/ .
 420