UTMAC 7

NAME

utmac: macro set for heirloom troff.

DESCRIPTION

The U troff macrosutmac — is a set of troff macros aiming to produce beautiful documents easily. Bibliography, indexes, table of content and summaries can be automatically inserted. Utmac informs about orphans, widows and empty lines at the bottom of page. Utmac can produce pdf files, ReStructuredText files, plain text file, and clean xml files — and so, with some xsl stylesheet, flat open document texts (fodt) and html files.

Utmac is made to be used with neatroff to produce postscript and pdf files. To produce plain text files, manual pages, and xml files, groff -k -Tutf8 -M@MACDIR@ can be used instead.

FILES

User macro files

The following macro files can be used by the user (called with the -m option of troff):

Additionnaly, some configuration can be achieved by loading the following macros:

MACROS

An utmac document should be structured in four parts: metadatas, definition of some register, content, and appendix. The content can contain header macros, summary macros, paragraph macros, typographic macros, note macros, include macros, links macros, keywords macros.

All macros have two letters; the first one define the gender of the macro: metaDatas, Register, Heading, Summary, Paragraph, Typographic, Notes, Include, Links, Keywords, AppendiX.

Metadata macros

These macro are used to populate the metadatas of the final file (pdf, xml, or html). They must be inserted in the first page of the document — their natural place being the first lines of the file.

Register macros to define format and layout

Some number register are used by utmac to make or not some actions. Set to 1, the action is done, set to 0, the action is not done. The following macro can be used to define the state of this number register. The name of the macro is also the name of the number register. For example, .RV 1 acts like .nr RV 1. This is usefull to format a document from the command line:

troff −rRV=1 −muh file

Heading macros

These macro are used to print headings and to record them for a summary or a table of contents.

Summaries macros

To print a summary, two or three pass of troff are needed: the first one to record the summary, the second one to print it, and a third one might be necessary to adjust the page number if the summary is longer than one page.

Paragraph macros

Typographic macros

Note macros

Include macros

These macros are used to include an encapsulated postscript document. These documents are often images, which can be produced with the convert command from ImageMagick:

convert image.jpg image.eps

Link macros

Link macros are used to insert links in a document. If a link macro is preceded by the LT macro it will use the arguments of LT as a replacement text for the link. Otherwise, the link is printed.

This will print the url followed by a dot:
.LU http://utroff.org .
While this will print «link» followed by a dot:
.LT link ». «
.LU http://utroff.org

Keyword macros

Keyword macros add semantic information to the source and the final document and index them. They do not print anything. The following keyword macros are defined:

Appendix macros

FONTS

In utmac, fonts are defined by a single uppercase letter string. As in the xml style, these strings must enclose the text and can be embedded:

Roman \*Iitalic, \*Bbolditalic\*B\*I, roman.

So, in an utmac document, you must avoid the raw troff \f and .fp commands.

Font strings are defined as follow:

EXAMPLE

The following example is a fully commented simple utmac document. As a summary is inserted, two pass of troff are needed. If the summary is longer than one page, a third pass of troff would be needed to handle correctly the page references, but this is not the case in this short example. So, this document can be build using these commands:

troff −muh alice.tr > /dev/null
troff −muh alice.tr | dpost | ps2pdf − alice.pdf
.\" Start example
.\" Use recto verso
.RV
.\" Define metadatas
.DA Lewis Carroll
.DT Alice’s adventures in wonderland and Through the looking glass
.DK alice nabuchodonosor jabberwocky
.\" Build first page
.H0 Lewis Carroll
.H1 Alice’s adventures
.\" Insert a summary of chapter headings
.S2
.\" First chapter heading
.H2 Alice’s adventures in wonderland
.\" A short exergue
.NT
All in the golden afternoon
Full leisurly we glide
.NE
.\" First paragraph
.H3 Down the rabbitt hole
.\" Some text with font definitions, and a note appeal
.PP
\*CAlice\*C was beginning to be very tired of sitting by her
sister on the bank, and of having nothing to do: once or
twice she had peeped into the book her sister was reading,
but it had no pictures or conversations in it, "\*Iand what
is the use of a book\*I" thought \*CAlice\*C, "\*Iwithout
pictures or conversations?\*I\**"
.\" A note
.NS
Yes, what is the use of such a book?
.NE
.\" Some other chapters and paragraphs...
.H3 The pool of tears
.H2 Through the looking glass
.\" Table of content
.XT
.\" Stop example

SEE ALSO

utmac-hack(7), u-ref(7), postxml(1), idx(1), refer(1).

LICENSE

Utmac macros and this manual page are distributed under the ics license.

AUTHOR

Pierre-Jean Fichet.