Utroff.org

Utmac manual

Name

utmac : macro set for heirloom troff.

Description

The U troff macrosutmac — is a set of troff macros which uses the typographic features of Heirloom Troff. Bibliography, indexes, table of content and summaries can be automatically inserted. Utmac informs about orphans, widows and blanks at the bottom of page, and provides macros to help the user to fix them manually. Utmac can produce terminal output, high quality 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.

Files

User macro files

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

Locale macro files

Utmac use the UTMAC environment variable to load a locale macro. The file @MACDIR@/u-locale is an example of such a macro, you should copy and edit it to suit your needs.

Internal macro files

The following macros files are internally used by utmac :

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, inline macros, and utmac tests macro.

All macros have two letters; the first one define the gender of the macro (metaDatas, Register, Utmac tests, Heading, Summary, Paragraph, Typographic, Notes, inLine, 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 macro 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

Utmac tests macro

To adapt the content of the document to the macro which is used, utmac provide a simple test macro :

The following macro are testable : uh, um, ut, us, uw, ux, u-ref, u-grind, u-idx, u-en, u-fr, u-apolline, u-libertine, u-locale.

For example, here is how to write a special heading for the um and ux macros :

.US um .H2 UTMAC 7 \" Manual page heading
.US ux .H2 UTMAC(7) \" Xml heading
.US ! um .US ! ux .H2 Utmac manual page \" Default heading

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

Inline macros

Inline macros add semantic information to the source and the final document, define links and anchors, and — for some of them — index words.

To deal with all these situations, inline macro have two usage :

The following example first index a name (LN macro), and next print (LP) a link to an url (LU) address :

The
.LN Pierre-Jean Fichet
author of \*Iutmac\*R share them on a
.LP website .
.LU http://utroff.org

The following inline macro are defined :

Appendix macros

Fonts

To access a font with utmac, you must use a string instead of the troff \f and .fp commands. This is needed to avoid to know which font will use utmac at which moment : the string has a different meaning depending of the context. So, to insert a single letter font, you should write \*I, a two letter font \*(BI, and a more than two letter font \*[BIC]. Strings are defined as follow :

Naming conventions

Utmac use some convention to name macro, strings, and number register. Internally, files are divided in modules, and the naming conventions are as follow :

Externally, all macro only contain uppercase letter and is never longer than three letters.

So, utmac reserve the following names :

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
.\" 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\*P 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\*P" thought \*CAlice\*P, "\*Iwithout
pictures or conversations?\*P\**"
.\" 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

Environment

Files

The following files are installed on the directory @MACDIR@ : @BIN@

See also

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

License

Utmac macros and this manual page are distributed under a two clause BSD license.

Help and bugs

Don’t hesitate to ask questions at help at utroff dot org. Please, send bugs and patches at help at utroff dot org.

Author

Pierre-Jean Fichet.