[groff] [UTMAC] Layout and Typography

[Pierre-Jean]

Hello alls,

As promised, here is my first article about Utmac. The goal is
not to convince you to use utmac, but simply to discuss about
writing macros for troff.

Today, I’ll discuss about typography and layout. Utmac aims to
produce beautiful documents, and I tried to respect some of the
good practices in that matter.

# Vertical alignment
--------------------

All lines are placed on a strict vertical grid. For that purpose,
in Utmac, the only unit of all vertical movements is the line
height (v in heirloom troff). Marginal notes, recto and verso,
odd and even pages should all end up being aligned.

# Paragraph at once adjustment
------------------------------

Utmac uses the paragraph at once adjustment of Heirloom Troff.
But it also uses a less known algorithm, developped for PdfTex,
and included in Heirloom Troff, which slightly adjusts the size
of glyphs to optimize the adjustment. That behaviour is
configured with the letadj command. Its arguments are: minimum
interglyph size, minimum glyph size, width of word that can be
expanded, maximum interglyph size and maximum glyph size. I found
that adjusting by 1% give the best results – but Heirloom Troff’s
adjustment algorithm is not exemplar.

    .letadj 99 99 15 101 101


# Hanging characters
--------------------

The alignment is visually adjusted by allowing some characters to
exceed lightly their normal position at the end of the line. That
is called "hanging characters". Heirloom troff provides the rhang
macro for that purpose: if font is used and char is at the end of
the line, the line size is increased by size, which is 1/1000 of
an em.

    .rhang font char size


# Widows and orphans
--------------------

Each time Utmac begins a paragraph, it checks its position on the
page, and prints a warning if he discovers a widow, an orphan, or
an empty bottom line. To remove these glytches, the macro TI and
TD can be used to increase and decrease the size of a paragraph.
Amongst other things, TI and TD internally use the letadj
command.

    .\" increase a paragraph
    .letadj 100 100 15 102 102
    .\" decrease a paragraph
    .letadj 98 98 15 100 100


# Typographic details
---------------------

In french, most punctuation marks are preceded by some space.
Utmac uses localization files to define them. For example u-fr
contains:

    .char : \~:
    .char ? \|?


# Fixed layout
--------------

As a result of that care to typographic details, Utmac’s layout
is not configurable. I believe Mom fills the need of
configurability, and I also believe Troff is easy enough to
encourage people to hack or write macros. Nonetheless, since a
single layout can’t satisfy all needs, Utmac comes with three
different ones:

  - uh, for humanities, that I used to write my philosophy
    thesis.  It uses marginal notes so the pages are not broken
    by bottom ones.
  - us, uses a common layout similar to the one used by ms.
  - ul, to write cover letters and curriculum vitae. It also uses
    marginal notes, but instead of populating them at the top of
    the page, they are displayed at the side of the text calling
    them.

On my next mail, I’ll write about paragraph at once adjustment.