Mom -- Graphics and floats

Back to Table of Contents | Next: Page headers/footers, pagination

# Graphics and floats

- Introduction to inserting images and graphics
- Image conversion and file processing
  - PDF
  - EPS
- The PDF_IMAGE macro
- The PSPIC macro
- Introduction to floats
- The FLOAT macro
  - Using tbl with FLOAT

## Introduction to inserting images and graphics

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.

### Image conversion and file processing

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.

#### PDF

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

#### EPS

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

### PDF_IMAGE

Macro: PDF_IMAGE `[ -L | -C | -R | -I <indent> ] \
<pdf image> <width> <height> \
[ SCALE <factor> ] [ ADJUST +|-<vertical adjustment> ]`

• `<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

Macro: PSPIC `[ -L | -R | -I <n> ] <file> [ width [ height ] ]`

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.

### From groff_tmac

`<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

## Introduction to floats

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.

### FLOAT

Macro: FLOAT `[ FORCE ] [ ADJUST +|-<amount> ] | <anything>`

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.

#### Using tbl with 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