Penguin
Recent Changes
Blame: groff_tmac(5)
EditPageHistoryDiffInfoLikePages
Annotated edit history of groff_tmac(5) version 4, including all changes. View license author blame.
Rev Author # Line
1 perry 1 GROFF_TMAC
2 !!!GROFF_TMAC
3 NAME
4 DESCRIPTION
5 NAMING
6 INCLUSION
7 CONVENTION
8 WRITING A MACRO FILE
9 FILES
10 ENVIRONMENT
11 BUGS
12 AUTHOR
13 SEE ALSO
14 ----
15 !!NAME
16
17
18 groff_tmac - macro files in the roff typesetting system
19 !!DESCRIPTION
20
21
22 The roff(7) type-setting system provides a set of
23 macro packages suitable for special kinds of documents. Each
24 macro package stores its macros and definitions in a file
25 called the package's __tmac file__. The name is deduced
26 from `__T__roff __MAC__ros'.
27
28
29 The tmac files are normal roff source documents, except that
30 they usually contain only definitions and setup commands,
31 but no text. All tmac files are kept in a single or a small
32 number of directories, the __tmac__
33 directories.
34 !!NAMING
35
36
37 In classical roff systems, there was a funny naming scheme.
38 If the name of a macro package started with `m' this letter
39 was omitted, e.g., the macro package for the man pages
40 ''man'' was called ''an'' and its macro file
41 ''tmac.an'' (note that in recent versions of groff this
42 file is called ''an.tmac'' instead).
43
44
45 By a similar reasoning, macro packages that did not start
46 with an `m' were often referred to by adding an `m', e.g.,
47 the package corresponding to ''tmac.doc'' was called
48 ''mdoc'' because the command-line for activating it
49 reads
50
51
52 __troff -m__''doc''.
53
54
55 Actual versions of groff(1) provide both naming
56 schemes for the inflicted macro packages, with and without
57 the leading `m'. So in ''groff'', the ''man'' macro
58 package may be specified as
59
60
61 __groff -m__ ''man'',__
62 groff -m__''an'',__
63 groff -m__''man'', or__
64 groff -m__ ''an''.
65
66
67 The easiest way to find out which macro packages are
68 available on a system is to check the contents of the
69 ''tmac'' directories. For example, a file called
70 __tmac.__''anything'' or ''anything''__.tmac__
71 determines a macro package named
72 ''anything''.
73
74
75 In ''groff'', most macro packages are described in man
4 perry 76 pages called groff_(7), with a leading
1 perry 77 `m' for the classical packages.
78 !!INCLUSION
79
80
81 There are several ways to use a macro package in documents.
82 At run-time, the groff option -m name makes the definitions
83 in the macro file ''name''__.tmac__ available as
84 described in the section __NAMING__. If this file isn't
85 found, __tmac.__''name'' will be
86 searched.
87
88
89 It is also possible to include the macro file into the
90 document by using the groff requests .so or .mso. For .so
91 the full filename of the macro file must be specified --
92 including the directory where it is kept. If the macro file
93 is stored in one of the tmac directories it is more
94 convenient to use .mso instead because it searches the tmac
95 path for the filename. Additionally, if the file name to be
96 included has the form ''name''__.tmac__ and it isn't
97 found, .mso will try to open __tmac.__''name'' instead
98 and vice versa.
99
100
101 Note that in order to resolve the .so and .mso requests the
102 roff preprocessor soelim must be called if the files to be
103 included needs preprocessing. This can be done either
104 directly by a pipeline on the command line or by using the
105 -s option of groff.
106
107
108 You can also supply the letter `s' in the preprocessor word
109 as described in section __CONVENTION__.
110
111
112 For example, suppose a macro file is stored as
113 ''/usr/share/groff/1.17.2/tmac/macros.tmac'' and is used
114 in some document called ''docu.roff''.
115
116
117 At run-time, the formatter call for this is
118
119
120 groff -m macros docu.roff
121
122
123 To include the macro file directly in the document
124 either
125
126
127 .mso macros.tmac
128
129
130 is used or
131
132
133 .so
134 /usr/share/groff/1.17.2/tmac/macros.tmac
135
136
137 In both cases, the formatter is called with
138
139
140 groff -s docu.roff
141 !!CONVENTION
142
143
144 There is a convention that is supported by many modern roff
145 type-setters: the __preprocessor word__ described in the
146 following.
147
148
149 If the first line in a document is a comment, the first word
150 (after the comment characters and a blank) constitutes the
151 __preprocessor word__. That means that the letters of
152 this word are interpreted as abbreviations for those
153 preprocessor commands that should be run when formatting the
154 document. Mostly, only the letters corresponding to the
155 options for the preprocessors are recognized, `e', `G', `g',
156 `p', `R', `s', and `t' (see roff(7)).
157
158
159 Besides being a good reminder for the user, some formatters
160 (like the man(1) program) are even able to
161 automatically start the preprocessors specified in the
162 preprocessor word, but do not bet on this.
163 !!WRITING A MACRO FILE
164
165
166 Writing a groff macro file is easy. Design a set of macros,
167 strings, registers, etc. Store them in a single file.
168 Documents that use the macros include this macro file with
169 the .so request as described in the __INCLUSION__
170 section.
171
172
173 To use the tmac functionality, call the macro file
174 ''whatever''__.tmac__ (or __tmac.__''whatever'')
175 and put it in some directory of the tmac path, cf. section
176 __FILES__. Then documents can include it with the .mso
177 request or the groff -m option as described in the
178 __INCLUSION__ section.
179
180
181 If your macros might be of general usage contact the groff
182 maintainers to have them included in the groff
183 ''contrib'' source directory.
184
185
186 Some general guidelines might be helpful in writing
187 macros.
188
189
190 Double all functional backslashes, `' -
191
192
193 All printable backslashes must be written as
194 `e'.
195
196
197 Escape all dots, `.' -
198
199
200 Make ample use of the non-printable character `
201
202
203 Use the character `@' in temporary variable
204 names.
205
206
207 Test your macros for text and graphical devices, e.g.,
208 ''latin1'' and ''ps''.
209 !!FILES
210
211
212 All macro names must be named ''name''__.tmac__ or
213 __tmac.__''name'' to use the tmac
214 mechanism.
215
216
217 The macro files are kept in the __tmac directories__, all
218 of which constitute the __tmac path.__
219
220
221 The elements of the search path for macro files are (in that
222 order):
223
224
225 the directories specified with troff's resp. groff's
226 __-M__ command line option
227
228
229 the directories given in the __GROFF_TMAC_PATH__
230 environment variable
231
232
233 the current directory (only if in unsafe mode using the
234 __-U__ command line switch)
235
236
237 the home directory
238
239
240 a site-specific (platform-independent) directory, a
241 platform-specific directory, and the main tmac
242 directory:
243
244
245 /usr/share/groff/site-tmac
246 /usr/lib/groff/site-tmac
247 /usr/share/groff/1.17.2/tmac
248 !!ENVIRONMENT
249
250
251 __GROFF_TMAC_PATH__
252
253
254 A colon separated list of additional tmac directories in
255 which to search for macro files. See the previous section
256 for a detailed description.
257 !!BUGS
258
259
260 The groff documentation is in evolution at the moment. It is
261 possible that small inconsistencies between different
262 documents exist temporarily.
263 !!AUTHOR
264
265
266 This document is part of groff, the GNU roff distribution.
267 It was written by Bernd Warken
268
269
270 It is distributed under the terms of the FDL (GNU Free
271 Documentation License) version 1.1 or later. You should have
272 received a copy of the FDL on your system, it is also
273 available on-line under
274
275
276 ''''.
277 !!SEE ALSO
278
279
280 The authoritative source of information for all details of
281 the groff system is the groff info(1)
282 file.
283
284
285 For a groff overview, see roff(7) and the file
286 ''README'' in the groff source package.
287
288
4 perry 289 The groff tmac macro packages are groff_man(7),
290 groff_mwww(7), __groff_mdoc__(7),
291 groff_mdoc.samples(7), __groff_me__(7),
292 groff_mm(7), __groff_mmroff__(7), and
293 groff_ms(7).
1 perry 294
295
296 The groff language is described in groff(7) and the
297 formatters in groff(1), troff(1).
298
299
300 The Filesystem Hierarchy Standard (FHS) is available at
301 __http://www.pathname.com/fhs/__.
302 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.