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
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
|
<?xml version="1.0" encoding="utf-8"?>
<!--
This file is part of groff, the GNU roff type-setting system.
Copyright (C) 2004, 2005, 2006, 2009, 2010,
2011, 2012, 2013 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 the
Invariant Sections being this comment section, 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 -- Graphics and floats</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="headfootpage.html#top">Next: Page headers/footers, pagination</a></td>
</tr>
</table>
<h1 class="docs">Graphics and floats</h1>
<div style="width: 55%; margin: auto;">
<ul class="no-enumerator" style="margin-left: -1em;">
<li><a href="#images-intro">Introduction to inserting images and graphics</a>
<li><a href="#converting">Image conversion and file processing</a>
<ul style="margin-left: -.5em; list-style-type: disc;">
<li><a href="#pdf">PDF</a></li>
<li><a href="#eps">EPS</a></li>
</ul></li>
<li><a href="#pdf-image">The PDF_IMAGE macro</a></li>
<li><a href="#pspic">The PSPIC macro</a></li>
<li><a href="#floats-intro">Introduction to floats</a></li>
<li><a href="#float">The FLOAT macro</a>
<ul style="margin-left: -.5em; list-style-type: disc;">
<li><a href="#tbl-with-float">Using tbl with FLOAT</a></li>
</ul></li>
</ul>
</div>
<div class="rule-medium"><hr/></div>
<h2 id="images-intro" class="docs">Introduction to inserting images and graphics</h2>
<p>
In order to include images in mom documents, the images must be in
either PDF (.pdf) or EPS (.eps) format. Each format requires its own
macro, but both take the same arguments, and in the same order.
</p>
<p>
Please note that there are differences in the way the files
containing PDF and EPS images must be processed, hence documents may
not contain a mix.
</p>
<h3 id=converting class="docs">Image conversion and file processing</h3>
<p>
When your image files are not in PDF or EPS format—jpgs,
for example—you must convert them before including them in
a mom document. Any utility for converting images may used. The
ImageMagick suite of programmes, present on most GNU/Linux
systems, contains <b>convert</b>, which is simple and effective.
</p>
<h4 id="pdf" class="docs">PDF</h4>
<p>
Assuming a jpg image, conversion to PDF is done like this:
<br/>
<span class="pre-in-pp">
convert <image>.jpg <image>.pdf
</span>
Any image type supported by <b>convert</b> may be converted this
way.
</p>
<p>
Mom files containing PDF images must be processed using
groff’s pdf driver. Use of
<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
is strongly recommended, which natively invokes the pdf driver.
<br/>
<span class="pre-in-pp">
pdfmom doc.mom > doc.pdf
</span>
</p>
<h4 id="eps" class="docs">EPS</h4>
<p>
Assuming a jpg image, conversion to EPS is done like this:
<br/>
<span class="pre-in-pp">
convert <image>.jpg <image>.eps
</span>
Any image type supported by <b>convert</b> may be converted this
way. There have been reports of trouble with PostScript level 2
images, so don’t save your images in this format.
</p>
<p>
Mom files containing EPS images must be processed using
groff’s postscript driver. Use of
<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
which can be told to use the postscript driver, is strongly
recommended.
<br/>
<span class="pre-in-pp">
pdfmom -Tps doc.mom > doc.pdf
</span>
</p>
<!-- -PDF_IMAGE- -->
<div class="macro-id-overline">
<h3 id="pdf-image" class= "macro-id">PDF_IMAGE</h3>
</div>
<div class="box-macro-args">
Macro: <b>PDF_IMAGE</b> <kbd class="macro-args">[ -L | -C | -R | -I <indent> ] \
<br/>
<pdf image> <width> <height> \
<br/>
[ SCALE <factor> ] [ ADJUST +|-<vertical adjustment> ]</kbd>
</div>
<p class="requires">
• <span style="font-style: normal">
<kbd><indent></kbd>,
<kbd><width></kbd>,
<kbd><height></kbd></span>
and
<span style="font-style: normal">
<kbd><vertical adjustment></kbd></span>
require a
<a href="definitions.html#unitofmeasure">unit of measure</a>
</p>
<p>
Unlike
<a href="#pspic">PSPIC</a>,
which it resembles, PDF_IMAGE requires that the pdf image’s
dimensions (the bounding box,
<a href="#bounding-box">see below</a>)
be supplied each time it’s called.
</p>
<p>
The first optional argument tells mom how to align the image
horizontally, with <kbd>-L</kbd>, <kbd>-C</kbd>, and <kbd>-R</kbd>
standing for left, centre and right respectively. If you need more
precise placement, the <kbd>-I</kbd> argument allows you to give an
indent from the left margin. Thus, to indent a PDF image 6
<a href="definitions.html#picaspoints">picas</a>
from the left margin
<br/>
<span class="pre-in-pp">
.PDF_IMAGE -I 6P <remaining arguments>
</span>
If you omit the first argument, the image will be centred.
</p>
<p>
<kbd><pdf image></kbd> must be in PDF format, with a .pdf
extension. If it is not, mom will abort with a message. See <a
href="#pdf">here</a> for instructions on converting image formats to
PDF.
</p>
<p id="bounding-box">
<kbd><width></kbd> and <kbd><height></kbd> are the
dimensions of the image’s bounding box. The most reliable way
of getting the bounding box is with the utility, <strong>pdfinfo</strong>:
<br/>
<span class="pre-in-pp">
pdfinfo <image.pdf> | grep "Page *size"
</span>
This will spit out a line that looks like this:
<br/>
<span class="pre-in-pp">
Page size: width x height pts
</span>
<kbd>pts</kbd> means
<a href="definitions.html#picaspoints">points</a>,
therefore the unit of measure appended to <kbd><width></kbd>
and <kbd><height></kbd> must be <kbd>p</kbd>.
</p>
<p>
The optional <kbd>SCALE</kbd> argument allows you to scale the image
by <kbd><factor></kbd>. The factor is a percentage of the
image’s original dimensions, thus
<br/>
<span class="pre-in-pp">
SCALE 50
</span>
scales the image to 50 percent of its original size. No percent
sign or unit of measure should be appended.
</p>
<p>
The final optional argument is the vertical adjustment to apply to
the image. A plus value raises the image
<span style="font-style: italic">within the space allotted for it</span>;
a negative value lowers it. The value must have a unit of measure
appended.
</p>
<p>
Remember that mom files with embedded PDF images must be processed
with
<br/>
<span class="pre-in-pp">
pdfmom doc.mom > doc.pdf
</span>
</p>
<div class="box-tip">
<p class="tip-top">
<span class="note">Note:</span>
Mom automatically applies shimming after PDF_IMAGE. See
<a href="docprocessing.html#shim">SHIM</a>
for a discussion of shimming, and how to disable it.
<p>
<p>
<span class="note">Additional note:</span>
Mom treats single, discrete images inserted into a document with
PDF_IMAGE somewhat like
<a href="#floats-intro">floats</a>,
which is to say that if an image doesn’t fit on the output
page, she will defer it to the top of the next page while continuing
to process
<a href="definitions.html#running">running text</a>.
<kbd>ADJUST</kbd> is ignored whenever an image is deferred, and a
message is printed to stderr advising you where the deferment has
taken place.
</p>
<p class="tip-bottom">
However, if more than one image does not fit on the output page,
mom defers only the first; the remainder are silently ignored.
Therefore, if you insert several images close together in the text,
it is highly recommended that you wrap the images in floats, which
do not have this restriction.
</p>
</div>
<!-- -PSPIC- -->
<div class="macro-id-overline">
<h3 id="pspic" class= "macro-id">PSPIC</h3>
</div>
<div class="box-macro-args">
Macro: <b>PSPIC</b> <kbd class="macro-args">[ -L | -R | -I <n> ] <file> [ width [ height ] ]</kbd>
</div>
<p>
PSPIC is not actually part of mom, but rather a macro included with
every groff installation. Although its arguments are identical to
PDF_IMAGE (except for <kbd>SCALE</kbd> and <kbd>ADJUST</kbd>, which
are missing), its behaviour is slightly different.
</p>
<p>
<kbd>man groff_tmac</kbd> contains the documentation for PSPIC, but
I’ll repeat it here with a few modifications for clarity.
</p>
<div class="examples-container">
<h3 id="groff-tmac" class="docs" style="margin-top: .5em;">From <span style="text-transform: none">groff_tmac</span></h3>
<p style="margin-top: .5em; margin-bottom: .5em;">
<kbd><file></kbd> is the name of the file containing the
image; <kbd>width</kbd> and <kbd>height</kbd> give the desired
width and height of the image as you wish it to appear within the
document. The width and height arguments may have
<a href="definitions.html#unitofmeasure">units of measure</a>
attached; the default unit of measure is
<kbd>i</kbd>. PSPIC will scale the graphic
uniformly in the x and y directions so that it is no more than
<kbd>width</kbd> wide and <kbd>height</kbd> high. By default, the
graphic will be horizontally centred. The <kbd>-L</kbd> and
<kbd>-R</kbd> options cause the graphic to be left-aligned and
right-aligned, respectively. The <kbd>-I</kbd> option causes
the graphic to be indented by <kbd><n></kbd>; the default unit of
measure is <kbd>m</kbd>
(<a href="definitions.html#em">ems</a>).
</p>
</div>
<p>
It is not necessary to pass PSPIC the
<kbd><width></kbd> and <kbd><height></kbd> arguments unless
you are scaling the image, in which case you will most likely need
the original dimensions of the EPS image’s bounding box.
These can be found with
<span class="pre-in-pp">
gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox <image file>.pdf 2>&1 \
| grep "%%BoundingBox" | cut -d " " -f4,5
</span>
The two digits returned are in
<a href="definitions.html#picaspoints">points</a>,
therefore the
<a href="definitions.html#unitofmeasure">unit of measure</a>
<kbd>p</kbd> must be appended to them.
</p>
<p>
Because PSPIC lacks the <kbd>ADJUST</kbd> option offered by
<a href="#pdf-image">PDF_IMAGE</a>
a certain amount of manual tweaking of the vertical placement of the
image will probably be required, typically by using the
<a href="typesetting.html#ald">ALD</a>
and
<a href="typesetting.html#rld">RLD</a>
macros.
</p>
<p>
Additionally, EPS images inserted into
<a href="definitions.html#running">running text</a>
will almost certainly disrupt the baseline placement of running
text. In order to get mom back on track after
invoking <kbd>.PSPIC</kbd>, I strongly recommend using the
<a href="docprocessing.html#shim">SHIM</a>
macro so that the bottom margin of running text falls where it
should. Please note that with PDF_IMAGE, this is not necessary.
</p>
<p>
Remember that mom files with embedded EPS images must be processed
with
<br/>
<span class="pre-in-pp">
pdfmom -Tps doc.mom > doc.pdf
</span>
</p>
<div class="rule-medium"><hr/></div>
<h2 id="floats-intro" class="docs">Introduction to floats</h2>
<p>
Images and graphics (including those created with
<strong>tbl</strong> and <strong>pic</strong>) sometimes do not
fit on the output page of a PDF or PostScript document at the
place they’re inserted in the input file. It’s
necessary, therefore, to defer them to the next page while carrying
on with
<a href="definitions.html#running">running text</a>.
</p>
<p>
Whenever you need this functionality (tables, for example, generally
need only appear near related text, not at a precise location), mom
provides the FLOAT macro.
</p>
<p>
Floats are usually used for images and graphics, but can contain
anything you like, including text. Whatever’s in the
float will be kept together as a block, output immediately if
there’s room, or deferred to the top of the next output page
when there isn’t; running text continues to the bottom of the
previous page without interruption.
</p>
<p>
In the case of a float that doesn’t fit being followed by
one that does, the second is output in position and the first is
deferred. In the case of two or more that don’t fit, they are
output in order on the next page.
</p>
<p>
A key distinction between a float and a
<a href="docelement.html#quote">QUOTE</a>
or
<a href="docelement.html#blockquote">BLOCKQUOTE</a>
is that while a float keeps everything together and defers output if
necessary, quotes and blockquotes are output immediately, and may
start on one page and finish on the next.
</p>
<p>
Floats always deposit a break before they begin, which means the
line beforehand will not be
<a href="definitions.html#filled">filled</a>.
Floats, therefore, cannot be inserted in the middle of a paragraph
without studying the output file and determining where to break or
<a href="typesetting.html#spread">spread</a>
the line before the float.
</p>
<p id="float-spacing">
Floats begin on the baseline immediately below the running text
preceding them. No additional whitespace surrounds them, above or
below. Running text below a float is, however,
<a href="docprocessing.html#shim">shimmed</a>,
unless shimming has been disabled with <kbd>.NO_SHIM</kbd>. This
usually results in a small amount of extra whitespace after the
float. The <kbd>ADJUST</kbd> argument to FLOAT allows you to
fine-tune the vertical centering.
</p>
<p>
If you’d like more space around a float, you must add it
manually, for example with
<a href="typesetting.html#ald">ALD</a>
or
<a href="typesetting.html#space">SPACE</a>.
</p>
<!-- -FLOAT- -->
<div class="macro-id-overline">
<h3 id="float" class= "macro-id">FLOAT</h3>
</div>
<div class="box-macro-args">
Macro: <b>FLOAT</b> <kbd class="macro-args">[ FORCE ] [ ADJUST +|-<amount> ] | <anything></kbd>
</div>
<div class="box-tip">
<p class="tip">
<span class="note">Note:</span>
FLOAT is intended for use with the document processing macros only.
</p>
</div>
<p style="margin-top: -.5em">
To begin a float, simply invoke <kbd>.FLOAT</kbd> and follow it with
whatever you want the float to contain. When you’re done,
invoke <kbd>.FLOAT OFF</kbd> (or <kbd>QUIT, END, X</kbd>, etc).
</p>
<p>
The optional <kbd>FORCE</kbd> argument instructs mom to output
the float exactly where it occurs in the input file. With
<kbd>FORCE</kbd>, mom immediately breaks to a new page to output
the float if it does not fit on the current page. While this is
somewhat contrary to the notion of floats (ie that running text
should continue to fill the page), there are circumstances where it
may be desirable.
</p>
<p>
The <kbd>ADJUST</kbd> argument tells mom to raise
(<kbd>+</kbd>) or lower (<kbd>-</kbd>) the float <i>within the space
allotted to it</i> by the specified amount.
<kbd><amount></kbd> must have a
<a href="definitions.html#unitofmeasure">unit of measure</a>
appended. <kbd>ADJUST</kbd> gives you precise control over
the vertical centering of floats, allowing you to compensate for
unequal spacing that may result of from the automatic shimming of
floats (or the absence thereof). See
<a href="docprocessing.html#shim">SHIM</a>
for a discussion of automatic shimming.
</p>
<p>
<kbd>ADJUST</kbd> is ignored whenever a float is deferred to
the following page.
</p>
<div class="box-tip">
<p class="tip-top">
<span class="note">Note:</span>
Floats use
<a href="definitions.html#filled">no-fill mode</a>,
with each input line beginning at the left margin. If this is not
what you want, you must specify the preferred horizontal alignment
<i>within the float</i> (eg
<a href="typesetting.html#lrc">CENTER</a>
or
<a href="typesetting.html#lrc">RIGHT</a>).
</p>
<p class="tip-bottom">
Furthermore, if you want text
<a href="definitions.html#filled">filled</a>,
you must specify
<a href="typesetting.html#quad"><kbd>.QUAD L|R|C</kbd></a>
or
<a href="typesetting.html#justify"><kbd>.JUSTIFY</kbd></a>—again,
within the float.
</p>
</div>
<h4 id="tbl-with-float" class="docs">Using tbl with FLOAT</h4>
<p>
Unboxed tables created with <strong>tbl</strong> (see <kbd>man
tbl(1)</kbd>) may be put in a float with the usual start and end
macros, <kbd>.TS</kbd> and <kbd>.TE</kbd>.
</p>
<p>
Boxed tables don’t play nice with FLOAT, and require that you
pass the argument <kbd>BOXED</kbd> to <kbd>.TS</kbd>, otherwise mom
cannot guarantee the vertical spacing of the float will be
<a href="#float-spacing">as described</a>.
<br/>
<span class="pre-in-pp">
.FLOAT
.TS BOXED
<tbl commands>
.TE
.FLOAT OFF
</span>
You may put text (or anything else you like) above or below the
table; mom will ensure the float is spaced correctly.
</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="headfootpage.html">Next: Page headers/footers, pagination</a></td>
</tr>
</table>
</div>
<div class="bottom-spacer"><br/></div>
</body>
</html>
<!-- vim: fileencoding=utf-8: nomodified: -->
|
