1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<?xml version="1.0" encoding="utf-8"?>
<!--
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (peter@schaffter.ca).
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.
A copy of the Free Documentation License is included as a file called
FDL in the main directory of the groff source package.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8"/>
<title>Using mom</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
</head>
<body style="background-color: #f5faff;">
<!-- ==================================================================== -->
<div id="top" class="page">
<!-- Navigation links -->
<table style="width: 100%;">
<tr>
<td><a href="toc.html">Back to Table of Contents</a></td>
<td style="text-align: right;"><a href="typesetting.html#top">Next: The typesetting macros</a></td>
</tr>
</table>
<h1 id="using" class="docs">Using mom</h1>
<div style="text-align: left; margin-left: 33%">
<ul class="no-enumerator" style="margin-left: -2.5em;">
<li><a href="#using-intro">Introduction</a></li>
<li><a href="#using-macros">How to input mom’s macros</a></li>
<li><a href="#viewing">Processing and viewing documents</a>
<ul>
<li class="item"><a href="#pdf">Mom and PDF</a></li>
<li class="item"><a href="#pdfmom">pdfmom</a></li>
</ul></li>
<li><a href="#previewing">Automatic previewing of documents</a></li>
</ul>
</div>
<div class="rule-short" style="margin-top: 18px;"><hr/></div>
<h2 id="using-intro" class="docs">Introduction</h2>
<p>
As explained in the section
<a href="intro.html#top">What is mom?</a>,
mom can be used in two ways: for straightforward typesetting or for
document processing. The difference between the two is that in
straightforward typesetting, every macro is a literal instruction
that determines precisely how text following it will look. Document
processing, on the other hand, uses markup tags (e.g. <kbd>.PP</kbd>
for paragraphs, <kbd>.HEADING</kbd> for different levels of heads,
<kbd>.FOOTNOTE</kbd> for footnotes, etc.) that perform typesetting
operations automatically.
</p>
<p>
You tell mom that you want to use the document processing macros
with the
<a href="docprocessing.html#start">START</a>
macro. After START, mom determines the appearance of
text following the markup tags automatically, although you, the
user, can easily change how the tags are interpreted.
</p>
<h2 id="using-macros" class="docs">How to input mom’s macros</h2>
<p>
Regardless of whether you’re preparing a term paper or making a
flyer for your lost dog, the following apply.
</p>
<ol style="margin-top: -.5em; margin-bottom: -.5em;">
<li>
You need a good text editor for inputting mom files.
<br/>
<span style="display: block; margin-top: .25em; margin-bottom: .5em;">
I cannot recommend highly enough that you use an editor that
lets you write syntax highlighting rules for mom’s
macros and
<a href="definitions.html#inlines">inline escapes</a>.
Simply colourizing macros and inlines to half-intensity can be
enough to make text stand out clearly from formatting commands.
Mom herself comes with a complete set of syntax highlighting
rules for the vim editor. A number of freely available editors
come with groff syntax highlighting rules, which are sufficient
for mom files, though not as colourful or complete as the vim
rules that ship with mom.
</span>
</li>
<li>
Macros begin with a period (dot) at the left margin of your text
editor’s screen, and must be entered in upper case (capital)
letters.
</li>
<li>
Macro
<a href="definitions.html#arguments">arguments</a>
are separated from the macro itself by spaces. Multiple
arguments to the same macro are separated from each
other by spaces. Any number of spaces may be used.
</li>
<li>
Arguments to a macro must appear on the same line as the
macro.
<br/>
<span style="display: block; margin-top: .25em; margin-bottom: .5em;">
If the argument list is very long, you may use the
backslash character (<kbd>\</kbd>) to break the line visually.
From groff’s point of view, the backslash and newline are
invisible. Thus, for example,
<span class="pre" style="margin-bottom: -2.25em">
.HEADING_STYLE 1 FAMILY Garamond FONT B SIZE +2
</span>
and
<span class="pre" style="margin-bottom: -2.25em">
.HEADING_STYLE 1 \
FAMILY Garamond \
FONT B \
SIZE +2
</span>
</span>
are exactly equivalent.
</li>
<li>
Any argument (except a
<a href="definitions.html#stringargument">string argument</a>)
that is not a digit must be entered in upper case
(capital) letters.
</li>
<li>
Any argument that requires a plus or minus sign must
have the plus or minus sign prepended to the argument
with no intervening space (e.g. <kbd>+2</kbd>).
</li>
<li>
Any argument that requires a
<a href="definitions.html#unitofmeasure">unit of measure</a>
must have the unit appended directly to the argument, with no
intervening space (e.g. <kbd>.5i</kbd>).
</li>
<li>
<a href="definitions.html#stringargument">String arguments</a>,
in the sense of this manual, must be surrounded by double-quotes
(e.g. <kbd>"text"</kbd>). Multiple
string arguments are separated from each other by spaces (with
each argument surrounded by double-quotes).
<br/>
<span style="display: block; margin-top: .25em; margin-bottom: .5em;">
If a string argument becomes
uncomfortably long, you may break it into two or more lines
with the backslash character.
<span class="pre">
.SUBTITLE "An In-Depth Consideration of the \
Implications of Forty-Two as the Answer to Life, \
The Universe, and Everything"
</span>
</span>
</li>
</ol>
<div class="box-tip">
<p class="tip">
<span class="tip">Tip:</span>
It’s important that your documents be easy to read and
understand in a text editor. One way to achieve this is to group
macros that serve a similar purpose together, and separate them from
other groups of macros with a comment line. In groff, that’s
done with <kbd>\#</kbd> (backslash-pound) or <kbd>.\"</kbd>
(period-backslash-doublequote) on a line by itself. Either
instructs groff to ignore the remainder of the line, which may or
may not contain text. Consider the following, which is a template
for starting the chapter of a book.
<br/>
<span class="pre-in-pp">
\# Reference/meta-data
.TITLE "My Pulitzer Novel"
.AUTHOR "Joe Blow"
.CHAPTER 1
\# Template
.DOCTYPE CHAPTER
.PRINTSTYLE TYPESET
\# Type style
.FAM P
.PT_SIZE 10
.LS 12
\#
.START
</span>
You may also, if you wish, add a comment to the end of a line with
<kbd>\"</kbd> (no period), like this:
<br/>
<span class="pre-in-pp">
.FAMILY P \" Maybe Garamond instead?
</span>
</p>
</div>
<h2 id="viewing" class="docs">Processing and viewing documents</h2>
<p>
The most basic command-line usage for processing a file formatted
with the mom macros is
<br/>
<span class="pre-in-pp">
groff -mom filename.mom > filename.ps
</span>
which processes the .mom file and dumps the output into a
viewable/printable PostScript file.
</p>
<h3 id="pdf" class="docs">Mom and PDF</h3>
<p>
Adobe’s Portable Document Format (PDF) has largely supplanted
PostScript, of which it is a subset, as the standard for typeset
documents. While printed versions of documents in either format
will be identical, PDF documents, when viewed at the screen, may
also contain clickable links and a number of other special features.
</p>
<p>
As of version 2.0, mom supports full PDF integration. The creation
and processing of mom files into PostScript documents remains
unchanged from 1.x, but the expected and recommended format of final
documents is now PDF.
</p>
<p>
The manual,
<a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>,
explains and demonstrates the PDF-specific macros that are available
in mom, as well as the use of <strong>pdfmom</strong>, the
recommended way to process mom files.
</p>
<h4 id="pdfmom" class="docs">pdfmom</h4>
<p>
Groff provides more than one way to generate PDF documents,
but when processing files formatted with the mom macros,
<strong>pdfmom</strong> is the recommended and most robust way to do
it:
<br/>
<span class="pre-in-pp">
pdfmom filename.mom > filename.pdf
</span>
<strong>pdfmom</strong> is a wrapper around groff, and accepts all
groff’s command-line options as listed in the groff manpage.
Full usage is explained in the manual,
<a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>.
</p>
<p>
PDF links in a document, including linked entries in the
Table of Contents, are identified by colour. When printing
documents with links, you will most likely not want the link
text coloured. The groff option, <kbd>-c</kbd>, disables colour
throughout a document; thus, when preparing a document for printing,
you should use:
<br/>
<span class="pre-in-pp">
pdfmom -c filename.mom > filename.pdf
</span>
<strong>pdfmom</strong> tends to produce large files. You may
reduce their size by piping them through ps2pdf:
<br/>
<span class="pre-in-pp">
pdfmom -c filename.mom | ps2pdf - filename.pdf
</span>
Be aware, though, that files piped through ps2pdf will lose some pdf
metadata, notably the document window title set with PDF_TITLE.
</p>
<h2 id="previewing" class="docs">Automatic previewing of documents</h2>
<p>
Most PDF viewers have a “Watch File” option, which
automatically updates a displayed document whenever there’s
a change. This is useful when preparing documents that require
judgment calls. I recommend creating a keymapping in your
text editor that both saves the mom file and processes it with
<strong>pdfmom</strong>. The displayed PDF then automatically
reflects whatever changes you save to the mom file.
</p>
<div class="rule-long"><hr/></div>
<!-- Navigation links -->
<table style="width: 100%; margin-top: 12px;">
<tr>
<td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
<td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
<td style="width: 33%; text-align: right;"><a href="typesetting.html#top">Next: The typesetting macros</a></td>
</tr>
</table>
</div>
<div class="bottom-spacer"><br/></div>
</body>
</html>
|
