UTMAC 7
NAME
utmac: A troff macro set
DESCRIPTION
The U troff macros — utmac — 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):
- uh: Made with humanities in mind. It use marginal notes instead of footnotes.
- ul: A macro to write letters and short texts.
- um: Translate a utmac document to manpage with nroff.
- ut: Translate an utmac document to a flat text file (such as README files) with nroff.
- us: Made for technical documentation. It uses a common layout, reminiscent of the old troff ms.
- uw: Translate an utmac document to the markdown wiki format.
- ux: Translate an utmac document to xml. This macro must be used with the postxml(1) post-processor.
Additionnaly, some configuration can be achieved by loading the following macros:
- u-en: English localization (default).
- u-fr: French localization.
- u-apolline: Use the Porchez Typofonderie Apolline font.
- u-libertine: Use the linux libertine font.
- u-biolinum: Use the linux biolinum font.
- u-biollib: Use a mix of Linux Libertine and Biolinum.
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.
Most macros have two letters; the first one define the gender of the macro: metaDatas, Register, Heading, Summary, Paragraph, Typographic, Notes, Links, Keywords, AppendiX. Include macros are an exception: they are named EPS and PDF.
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.
- DA author name: Define author metadata.
- DI Identifier: Define identifier (RCS Id...).
- DK list of keywords: Define keywords metadata.
- DS subject of the text: Define subject metadata.
- DT title of the text: Define title metadata.
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
- RV num: If num=1, use a recto-verso layout. Default is 0.
- RI num: If num=1, replace references by Idem when needed. Default is 1.
- RH num: If num=1, print help message. Help message inform about orphans, widows, blank at the bottom of pages, note diverted to next page, and multiple definition of anchor keyword. Default is 1.
- RL [fr|en]: Set language of file. Use this macro to localize some string and to respect local typographic standard if you want to override the default which should be defined by the macro in the UTMAC environment variable.
- RO num: If num=1, replace some part of a reference (issuer, city and date) by op. cit. if the same reference has appeared in the text. Default is 1.
- RP num: If num=1, print page number. Default is 1.
- RN num: If num=1, print reference in a note, if num=0, the reference is printed directly in the text, by using the PQ macro. Default is 1.
Heading macros
These macro are used to print headings and to record them for a summary or a table of contents.
- H1 Title of the book: Book heading.
- H2 Title of the chapter: Chapter heading.
- H3 Title of the paragraph: Paragraph heading.
- H4 Subheading: Subheading.
- H0 Temporary title: Temporary heading, printed in the header or in the footer of the current page. This heading is not recorded in the table of content.
- H* Margin title: Heading printed in header or footer of the following pages, and in the current ones if H0 is not set for this page. This heading is not recorded in the table of content.
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.
- S2: Print a summary of chapter headings. The summary is printed on a new page.
- S3: Print a summary of paragraph headings. The summary is printed on the actual page.
- S4: Print a summary of subheading. The summary is printed on the actual page.
- S*: Print the whole table of content as a summary.
Paragraph macros
- PB: Left indent (extended) pargraph. Usefull to begin some sort of lists.
- PC: Centered paragraph.
- PP: Justified paragraph.
- PQ: Quote paragraph.
- PI [bullet]: List paragraph. Default bullet is usually an emdash (\(em).
- PL: Left align paragraph.
- PR: Right align paragraph.
- PX: Example paragraph. Text is not filled.
Note macros
- NS no: Start a numbered note. The default is to print a number before the note, but if an argument is given, no number will be printed. To insert a number reference to the note in the text, use the * string, say insert: \** where you want the number to appear.
- NT: Print a note on top of the others, or in the flow of the text, depending of the macro used.
- NB: Print a note in the bottom of the page, or in the flow of the text, depending of the macro used.
- NE: End NS, NT or NB.
Include macros
These macros are used to include an encapsulated postscript document or a pdf one. These documents are often images, which can be produced with the convert command from ImageMagick for eps files and ps2pdf for pdf files:
convert image.jpg image.eps ps2pdf −dEPSCrop image.eps image.pdf
- EPS file.eps [l|c|r|indent] [width] [height]: Include an eps file.
- PDF file.pdf [l|c|r|indent] [width] [height]: Include a pdf file.
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
- LK keyword: Insert an anchor named keyword for internal links. Does not print anything.
- LL keyword stringafter stringbefore: Insert a link to the anchor keyword. The text to link is defined by the LT macro — if it is not defined, the url is printed, surrounded by stringbefore and stringafter.
- LM email stringafter stringbefore: Insert a link to an email address. The text to link is defined by the LT macro — if it is not defined, the url is printed, surrounded by stringbefore and stringafter.
- LT text stringafter stringbefore: Define text as the replacement text for the following link. It is printed surrounded by stringbefore and stringafter.
- LU url stringafter stringbefore: Insert a link to an url. The text to link is defined by the LT macro — if it is not defined, the url is printed, surrounded by stringbefore and stringafter.
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:
- KA acronym: Index an acronym.
- KN name: Index a name.
- KO object: Index an object.
- KT title: Index the title of a book (references are automatically indexed using it).
- KW word: Index a word.
Appendix macros
- XB [bibliography]: Print a bibliography. If bibliography is omitted, Utmac will use the $REFER environment variable. The bibliography begins with the H3 macro. Utmac try to sort the bibliography using urefer -i option, but this doesn’t give correct result on some bibliography list. For a perfect result, you should sort your bibliography with sortbib. See u-ref(7).
- XI: Print the existing indexes. To index something, use an keyword macro. Each index begin with the H3 macro.
- XT: Print a table of content. The table begin with the H3 macro.
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:
- B: Bold font.
- I: Italic font.
- C: Small Capital font.
- A: Acronym font (capital to small capital).
- U: Superscript font (upper).
- L: Dowscript font (lower).
- F: Final font (glyphs that might only appear at the end of a line).
- M: Monospace font.
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 isc license.
AUTHOR
Pierre-Jean Fichet.