| Back to Table of Contents | Next: Page headers/footers, pagination |
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.
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.
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 convert, which is simple and effective.
Assuming a jpg image, conversion to PDF is done like this:
convert <image>.jpg <image>.pdf
Any image type supported by convert may be converted this
way.
Mom files containing PDF images must be processed using
groff’s pdf driver. Use of
pdfmom
is strongly recommended, which natively invokes the pdf driver.
pdfmom doc.mom > doc.pdf
Assuming a jpg image, conversion to EPS is done like this:
convert <image>.jpg <image>.eps
Any image type supported by convert 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.
Mom files containing EPS images must be processed using
groff’s postscript driver. Use of
pdfmom,
which can be told to use the postscript driver, is strongly
recommended.
pdfmom -Tps doc.mom > doc.pdf
• <indent>, <width>, <height> and <vertical adjustment> require a unit of measure
Unlike PSPIC, which it resembles, PDF_IMAGE requires that the pdf image’s dimensions (the bounding box, see below) be supplied each time it’s called.
The first optional argument tells mom how to align the image
horizontally, with -L, -C, and -R
standing for left, centre and right respectively. If you need more
precise placement, the -I argument allows you to give an
indent from the left margin. Thus, to indent a PDF image 6
picas
from the left margin
.PDF_IMAGE -I 6P <remaining arguments>
If you omit the first argument, the image will be centred.
<pdf image> must be in PDF format, with a .pdf extension. If it is not, mom will abort with a message. See here for instructions on converting image formats to PDF.
<width> and <height> are the
dimensions of the image’s bounding box. The most reliable way
of getting the bounding box is with the utility, pdfinfo:
pdfinfo <image.pdf> | grep "Page *size"
This will spit out a line that looks like this:
Page size: width x height pts
pts means
points,
therefore the unit of measure appended to <width>
and <height> must be p.
The optional SCALE argument allows you to scale the image
by <factor>. The factor is a percentage of the
image’s original dimensions, thus
SCALE 50
scales the image to 50 percent of its original size. No percent
sign or unit of measure should be appended.
The final optional argument is the vertical adjustment to apply to the image. A plus value raises the image within the space allotted for it; a negative value lowers it. The value must have a unit of measure appended.
Remember that mom files with embedded PDF images must be processed
with
pdfmom doc.mom > doc.pdf
Note: Mom automatically applies shimming after PDF_IMAGE. See SHIM for a discussion of shimming, and how to disable it.
Additional note: Mom treats single, discrete images inserted into a document with PDF_IMAGE somewhat like floats, 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 running text. ADJUST is ignored whenever an image is deferred, and a message is printed to stderr advising you where the deferment has taken place.
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.
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 SCALE and ADJUST, which are missing), its behaviour is slightly different.
man groff_tmac contains the documentation for PSPIC, but I’ll repeat it here with a few modifications for clarity.
<file> is the name of the file containing the image; width and height 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 units of measure attached; the default unit of measure is i. PSPIC will scale the graphic uniformly in the x and y directions so that it is no more than width wide and height high. By default, the graphic will be horizontally centred. The -L and -R options cause the graphic to be left-aligned and right-aligned, respectively. The -I option causes the graphic to be indented by <n>; the default unit of measure is m (ems).
It is not necessary to pass PSPIC the <width> and <height> 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 gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox <image file>.pdf 2>&1 \ | grep "%%BoundingBox" | cut -d " " -f4,5 The two digits returned are in points, therefore the unit of measure p must be appended to them.
Because PSPIC lacks the ADJUST option offered by PDF_IMAGE a certain amount of manual tweaking of the vertical placement of the image will probably be required, typically by using the ALD and RLD macros.
Additionally, EPS images inserted into running text will almost certainly disrupt the baseline placement of running text. In order to get mom back on track after invoking .PSPIC, I strongly recommend using the SHIM macro so that the bottom margin of running text falls where it should. Please note that with PDF_IMAGE, this is not necessary.
Remember that mom files with embedded EPS images must be processed
with
pdfmom -Tps doc.mom > doc.pdf
Images and graphics (including those created with tbl and pic) 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 running text.
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.
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.
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.
A key distinction between a float and a QUOTE or BLOCKQUOTE 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.
Floats always deposit a break before they begin, which means the line beforehand will not be filled. Floats, therefore, cannot be inserted in the middle of a paragraph without studying the output file and determining where to break or spread the line before the float.
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, shimmed, unless shimming has been disabled with .NO_SHIM. This usually results in a small amount of extra whitespace after the float. The ADJUST argument to FLOAT allows you to fine-tune the vertical centering.
If you’d like more space around a float, you must add it manually, for example with ALD or SPACE.
Note: FLOAT is intended for use with the document processing macros only.
To begin a float, simply invoke .FLOAT and follow it with whatever you want the float to contain. When you’re done, invoke .FLOAT OFF (or QUIT, END, X, etc).
The optional FORCE argument instructs mom to output the float exactly where it occurs in the input file. With FORCE, 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.
The ADJUST argument tells mom to raise (+) or lower (-) the float within the space allotted to it by the specified amount. <amount> must have a unit of measure appended. ADJUST 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 SHIM for a discussion of automatic shimming.
ADJUST is ignored whenever a float is deferred to the following page.
Note: Floats use no-fill mode, with each input line beginning at the left margin. If this is not what you want, you must specify the preferred horizontal alignment within the float (eg CENTER or RIGHT).
Furthermore, if you want text filled, you must specify .QUAD L|R|C or .JUSTIFY—again, within the float.
Unboxed tables created with tbl (see man tbl(1)) may be put in a float with the usual start and end macros, .TS and .TE.
Boxed tables don’t play nice with FLOAT, and require that you
pass the argument BOXED to .TS, otherwise mom
cannot guarantee the vertical spacing of the float will be
as described.
.FLOAT
.TS BOXED
<tbl commands>
.TE
.FLOAT OFF
You may put text (or anything else you like) above or below the
table; mom will ensure the float is spaced correctly.
| Back to Table of Contents | Top | Next: Page headers/footers, pagination |