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
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
|
<?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>Mom -- Version 2.0 notes</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="intro.html#top">Next: Introduction to mom</a></td>
</tr>
</table>
<h1 class="docs">Version 2.0 notes</h1>
<div style="width: 70%; margin: auto;">
<ol style="margin-left: -1em;">
<li><a href="#prefatory">Prefatory comments</a></li>
<li><a href="#differences">Differences between 2.0 and 1.x</a>
<ul class="no-enumerator" style="padding-left: 0">
<li><a href="#pdf-support">2.1 PDF support</a>
<ul class="no-enumerator" style="padding-left: 1em">
<li><a href="#mom-pdf">2.1.1 The manual, <span class="book-title">Producing PDFs with groff and mom</span></a></li>
<li><a href="#pdf-image">2.1.2 PDF_IMAGE</a></li>
</ul></li>
<li><a href="#covers">2.2 Covers</a></li>
<li><a href="#headings">2.3 Headings</a></li>
<li><a href="#margin-notes">2.4 Margin notes</a></li>
<li><a href="#floats">2.5 Floats</a></li>
<li><a href="#table-of-contents">2.5 Tables of contents</a></li>
</ul></li>
<li><a href="#v2.1-changes">Version 2.1 changes</a></li>
<li><a href="#v2.2-changes">Version 2.2 changes</a></li>
<li><a href="#v2.5-changes">Version 2.5 changes</a></li>
<li><a href="#pdfmom">The <strong>pdfmom</strong> wrapper around groff</a></li>
<li><a href="#install-font">The <strong>install-font.sh</strong> script</a></li>
</ol>
</div>
<div class="rule-medium"><hr/></div>
<h2 id="prefatory" class="docs">1. Prefatory comments</h2>
<p>
Version 2.0 comes about as a result of Deri James’
contribution of <strong>gropdf</strong> to <strong>groff</strong>,
and his subsequent work integrating the device with
<strong>mom</strong>.
</p>
<p>
Whereas the 1.x releases were oriented toward PostScript output,
2.0 focuses on PDF output, a bias reflected throughout this
documentation. Users are strongly encouraged to process their files
with
<a href="#pdfmom"><strong>pdfmom</strong></a>,
a wrapper around <strong>groff -Tpdf</strong>, in order to take
full advantage of all PDF has to offer.
</p>
<p>
While portions of mom have been rewritten, and new features
introduced, 2.0 is backwardly compatible with 1.x releases. Changes
are either transparent, or accompanied by notifications on stderr.
</p>
<p>
The implementation of nested heads has been completely rethought,
as has the manner of styling of them. There are no limits on
how deep the nesting can go. The 1.x macros <kbd>HEAD</kbd>,
<kbd>SUBHEAD</kbd>, and <kbd>SUBSUBHEAD</kbd> may still be used, but
must be re-designed with the new <kbd>HEADING_STYLE</kbd> macro
if their 1.x defaults are not desired.
</p>
<p>
In conjunction with the changes to nested heads, Table of Contents
generation has also been rethought. Greater flexibility in the
inclusion of toc entry numbering been added. Like nested heads,
there’s a new macro <kbd>TOC_ENTRY_STYLE</kbd> that permits
styling of each level in the toc hierarchy separately. The default
overall layout has also been significantly improved, achieving a
level of typographical elegance formerly lacking. Best of all, the
Table of Contents can now be repositioned to the correct spot at the
top of a document from within the mom source file.
</p>
<p>
When mom files are processed with <strong>pdfmom</strong>, a PDF
outline for the Contents panel of PDF viewers is automatically
generated. In addition, entries in the Table of Contents
are clickable links when a document is viewed at the screen.
<strong>pdfmom</strong> also permits setting a document’s
papersize within the source file without the corresponding need for
<kbd>-P-p<papersize></kbd> on the command line.
</p>
<p>
Lastly, while not strictly part of mom, a bash script,
<strong>install-font.sh</strong>, has been posted at the
<a href="https://www.schaffter.ca/mom/">mom site</a>.
The script significantly eases the installation of new
groff families and fonts, with conversion to .pfa
and .t42 being performed by <strong>fontforge</strong>.
</p>
<h2 id="differences" class="docs">2. Differences between v2.0 and v1.x</h2>
<h3 id="pdf-support" class="docs">2.1. PDF support</h3>
<p>
PDF support has been added, with features including the automatic
generation of PDF outlines, embedding of images in PDF format (via
the
<a href="images.html#pdf-image">PDF_IMAGE</a>
macro) and PDF linking (internal and external).
</p>
<h4 id="mom-pdf" class="docs">2.1.1. Producing PDFs with groff and mom</h4>
<p>
A manual in PDF format,
<span class="book-title">Producing PDFs with groff and mom</span>,
has been added to the documentation. The file,
<strong>mom-pdf.pdf</strong> can be found in
<br/>
<span class="pre-in-pp">
/usr/local/share/doc/groff-<version>/pdf/
</span>
or
<br/>
<span class="pre-in-pp">
/usr/share/doc/groff-base/pdf/
</span>
or at
<br/>
<span class="pre-in-pp">
<a href="http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf">http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf</a>
</span>
PDF usage, and all associated macros except
<a href="#pdf-image">PDF_IMAGE</a>,
are fully explained in the manual, which should be considered an
integral part of the present documentation. In addition, the mom
source file for the manual can be found in
<br/>
<span class="pre-in-pp">
/usr/local/share/doc/groff-<version>/examples/mom
</span>
or
<br/>
<span class="pre-in-pp">
/usr/share/doc/groff-base/examples/mom/
</span>
and provides an excellent demonstration of mom usage.
</p>
<h4 id="pdf-image" class="docs">2.1.2. PDF_IMAGE</h4>
<p>
A new macro for embedding PDF images has been added,
<a href="images.html#pdf-image">PDF_IMAGE</a>.
</p>
<p>
PDF_IMAGE functions similarly to PSPIC and accepts the same
arguments. Differences in implementation are that PDF_IMAGE
requires the image dimensions (the bounding box) to be supplied.
Instructions for getting the bounding box are included in the
documentation entry for PDF_IMAGE. Two additional options,
<kbd>SCALE</kbd> and <kbd>ADJUST</kbd>, allow scaling of the image
and optical centering.
</p>
<h3 id="covers" class="docs">2.2. Covers</h3>
<p>
Arguments to
<a href="cover.html#cover">COVER</a>
and
<a href="cover.html#doc-cover">DOC_COVER</a>
may now be given in any order.
</p>
<h3 id="headings" class="docs">2.3. Headings</h3>
<p>
The 1.x macros HEAD, SUBHEAD, SUBSUBHEAD, are now deprecated and
have been replaced by the single macro
<a href="docelement.html#heading">HEADING <kbd><n></kbd></a>,
where <kbd><n></kbd> is the heading level. The deprecated
macros may still be used, and conform in style to their original
defaults; they are, however, wrappers around HEADING levels 1
– 3. Both the wrappers and HEADING itself can take a
<kbd>NAMED <id></kbd> argument, specifying a PDF link
destination.
</p>
<p>
Styling of headings is managed by the single macro <a
href="docelement.html#heading">HEADING_STYLE <n></a> where
<kbd><n></kbd> conforms to a heading level. The control
macros for HEAD, SUBHEAD and SUBSUBHEAD have been removed. Users
wishing to style the wrappers must use HEADING_STYLE.
</p>
<p>
PARAHEAD is no longer valid. Paragraph heads in 2.0 are created
by passing the <kbd>PARAHEAD</kbd> argument to HEADING. Mom
will abort with an informational message whenever she encounters
<kbd>.PARAHEAD</kbd>.
</p>
<h3 id="margin-notes" class="docs">2.4. Margin notes</h3>
<p>
The macro for setting margin note parameters,
<a href="docelement.html#mn-init">MN_INIT</a>,
has been re-written such that each parameter now has the form
<kbd><PARAMETER> <value></kbd>. This differs
from 1.x where parameters were entered without a preceding
<kbd><PARAMETER></kbd> flag. Parameters may be entered in any
order. Any that are skipped are set to default values. Documents
created with 1.x will have to have their <kbd>MN_INIT</kbd> updated
accordingly.
</p>
<h3 id="floats" class="docs">2.5. Floats</h3>
<p>
A
<a href="images.html#floats-intro">FLOAT</a>
macro has been added, which functions similarly to the <kbd>ms</kbd>
macros’ <kbd>.KF/.KE</kbd>, i.e., the contents of the float are
output immediately if there’s room on the page, otherwise
normal text processing continues and the contents are output at the
top of the next page. An <kbd>ADJUST</kbd> argument to FLOAT allows
for optical centering.
</p>
<h3 id="table-of-contents" class="docs">2.6. Tables of contents</h3>
<p>
The default look of the Table of Contents has been overhauled to
produce a more typographically pleasing result. All control macros
for TOC title and entry styles have been removed, replaced by
<a href="tables-of-contents.html#toc-title-style">TOC_TITLE_STYLE</a>
and
<a href="tables-of-contents.html#toc-title-style">TOC_ENTRY_STYLE <kbd><n></kbd></a>
where <kbd><n></kbd> corresponds to a heading level. Both
macros permit setting any or all of the style parameters for TOC
titles (i.e. chapters or major sections/divisions of a collated
document) and TOC entries (nested heading levels) at once.
Documents created with 1.x that contain TOCs will need to have their
TOC style updated if the new defaults are unsatisfactory.
</p>
<p>
Two new TOC control macros have been added,
<a href="tables-of-contents.html#space-toc-items">SPACE_TOC_ITEMS</a>
and
<a href="tables-of-contents.html#auto-relocate-toc">AUTO_RELOCATE_TOC</a>.
SPACE_TOC_ITEMS groups TOC entry levels and separates them with a
discrete amount of whitespace. This leads to improved legibility,
and is highly recommended even though it is not mom’s
default. AUTO_RELOCATE_TOC intelligently repositions the Table
of Contents to the top of a document when the mom source file is
processed with
<a href="pdfmom">pdfmom</a>.
</p>
<h2 id="v2.1-changes" class="docs">3. Version 2.1 changes</h2>
<p> Version 2.1 adds these features: </p> <ul style="margin-top: -.5em; width: 90%">
<li>expansion of cover, docheader, page header, and heading
control macros to permit caps, smallcaps, color, and
underscoring</li>
<li>the ability to style every element appearing in docheaders and
automatically-generated cover/title pages separately</li>
<li>macros to place images on cover/title pages</li>
<li>a new macro COVERTEXT that allows adding text (e.g. an
Abstract) to automatically-generated cover/title pages or to
create cover/title pages entirely by hand</li>
<li>separate indent control macros for QUOTES and BLOCKQUOTES</li>
<li>pseudo-smallcaps, including a control macro to choose the
size, weight, and width of the small caps</li>
<li>new <element>_STYLE macros that allow setting
parameters for <element> with a single macro using
keyword/value pairs</li>
</ul>
<p>
The following changes have been made:
</p>
<ul style="margin-top: -.5em; width: 90%">
<li>MISC_AUTOLEAD (including COVER_MISC_AUTOLEAD and
DOC_COVER_MISC_AUTOLEAD) has been replaced in favour of MISC_LEAD,
which takes an absolute leading value rather than one derived
from the point size.</li>
<li>COVER_UNDERLINE and DOC_COVER_UNDERLINE have been
removed in favour of COVER_DOCTYPE_UNDERLINE and
DOC_COVER_DOCTYPE_UNDERLINE.</li>
<li>DOCTYPE NAMED <kbd><string></kbd> no longer accepts a
<kbd>color</kbd> argument; setting the colour for
<kbd><string></kbd> is accomplished with DOCTYPE_COLOR
<kbd><color></kbd>. In addition, the string now has a
complete set of control macros.</li>
<li>Default underscoring of the DOCTYPE NAMED string has been
removed, both in the docheader and on cover/title pages.</li>
<li>No cover/title page data persists, however formatting for the
elements on them does.</li>
</ul>
<h2 id="v2.2-changes" class="docs">4. Version 2.2 changes</h2>
<p>
Version 2.2 adds these features:
</p>
<ul style="margin-top: -.5em; width: 90%">
<li>flex-spacing, an alternative to mom’s default shimming
policy; flex-spacing balances vertical whitespace on the page by
distributing any excess equally at sensible points so that running
text always fills the page to the bottom margin (see
<a href="docprocessing.html#vertical-whitespace-management">
vertical whitespace management</a>)
</li>
<li>improvements to auto-labelling, such that it is now possible
to link symbolically to auto-labelled preprocessor material and
PDF images (note that you must be running groff 1.22.4 or higher
for this feature)
</li>
</ul>
<h2 id="v2.5-changes" class="docs">5. Version 2.5 changes</h2>
<p>
Version 2.5 adds shaded backgrounds and frames that span pages
appropriately when necessary, and a macro to set page or slide
background colour.
</p>
<h2 id="pdfmom" class="docs">6. pdfmom</h2>
<p>
Deri James has provided <strong>pdfmom</strong>, a wrapper around
groff that processes mom source files with all the PDF bells and
whistles. Its use is highly recommended. 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>.
A significant convenience of pdfmom is that it can, with the
<kbd>-Tps</kbd> flag, be used to pass processing over to Keith
Marshall’s <strong>pdfroff</strong>. This is useful when
processing files that contain PostScript images embedded with
<a href="images.html#pspic">PSPIC</a>.
pdfmom, without the flag, uses groff’s PDF device
(<strong>gropdf</strong>), which only recognizes PDF images that
have been embedded with
<a href="images.html#pdf-image">PDF_IMAGE</a>.
</p>
<h2 id="install-font" class="docs">7. install-font.sh</h2>
<p>
A bash script, <strong>install-font.sh</strong>, has been posted at the
<a href="http://www.schaffter.ca/mom/mom-01.html">mom site</a>.
There’s nothing mom-specific about the script, and it is not
an official part of groff.
</p>
<p>
Installing groff fonts is a multi-step procedure, which, while not
difficult, can be a nuisance. install-font.sh takes
care of all the details, including converting fonts to formats
acceptable to <strong>grops</strong> and <strong>gropdf</strong>,
creating and installing the groff fonts in the appropriate
directories, updating the download files, and installing the
original fonts in a system-wide directory, if desired.
</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: 20%; text-align: center;"><a href="#top">Top</a></td>
<td style="width: 46%; text-align: right;"><a href="intro.html">Next: Introduction to mom</a></td>
</tr>
</table>
</div>
<div class="bottom-spacer"><br/></div>
</body>
</html>
|
