Macro: .DA [@dots{

(optional) Print the current date, or the arguments to the macro if any, on the title page (if specified) and in the footers. This is the default for nroff.

Macro: .ND [@dots{

(optional) Print the current date, or the arguments to the macro if any, on the title page (if specified) but not in the footers. This is the default for troff.

Macro: .TL

Specifies the document title. groff collects text following the .TL macro into the title, until reaching the author name or abstract.

Macro: .AU

Specifies the author's name, which appears on the line (or lines) immediately following. You can specify multiple authors as follows:

.AU John Doe .AI University of West Bumblefuzz .AU Martha Buck .AI Monolithic Corporation ...

Macro: .AI

Specifies the author's institution. You can specify multiple institutions in the same way that you specify multiple authors.

Macro: .AB [@code{no

Begins the abstract. The default is to print the word ABSTRACT, centered and in italics, above the text of the abstract. The word no as an optional argument suppresses this heading.

Macro: .AE

End the abstract.

The following is example mark-up for a title page.

.RP .TL The Inevitability of Code Bloat in Commercial and Free Software .AU J. Random Luser .AI University of West Bumblefuzz .AB This report examines the long-term growth of the code bases in two large, popular software packages; the free Emacs and the commercial Microsoft Word. While differences appear in the type or order of features added, due to the different methodologies used, the results are the same in the end. .PP The free software approach is shown to be superior in that while free software can become as bloated as commercial offerings, free software tends to have fewer serious bugs and the added features are in line with user demand. .AE ... the rest of the paper follows ...

4.3.5 Body text

This section describes macros used to mark up the body of your document. Examples include paragraphs, sections, and other groups.

4.3.5.1 Paragraphs
4.3.5.2 Headings
4.3.5.3 Highlighting
4.3.5.4 Lists
4.3.5.5 Indents
4.3.5.6 Tab Stops
4.3.5.7 Displays and keeps
4.3.5.8 Tables, figures, equations, and references
4.3.5.9 An example multi-page table
4.3.5.10 Footnotes

4.3.5.1 Paragraphs

The following paragraph types are available.

Macro: .PP

Sets a paragraph with an initial indent.

Macro: .LP

Sets a paragraph with no initial indent.

Macro: .QP

Sets a paragraph that is indented at both left and right margins. The effect is identical to the HTML <BLOCKQUOTE> element. The next paragraph or heading returns margins to normal.

Macro: .XP

Sets a paragraph whose lines are indented, except for the first line. This is a Berkeley extension.

The following markup uses all four paragraph macros.

.NH 2 Cases used in the study .LP The following software and versions were considered for this report. .PP For commercial software, we chose .B "Microsoft Word for Windows" , starting with version 1.0 through the current version (Word 2000). .PP For free software, we chose .B Emacs , from its first appearance as a standalone editor through the current version (v20). See [Bloggs 2002] for details. .QP Franklin's Law applied to software: software expands to outgrow both RAM and disk space over time. .LP Bibliography: .XP Bloggs, Joseph R., .I "Everyone's a Critic" , Underground Press, March 2002. A definitive work that answers all questions and criticisms about the quality and usability of free software.

4.3.5.2 Headings

Use headings to create a hierarchical structure for your document. The `ms' macros print headings in bold, using the same font family and point size as the body text.

The following describes the heading macros:

Macro: .NH {curr-level

Macro: .NH @t{S

Numbered heading. The argument is either a numeric argument to indicate the level of the heading, or the letter S followed by numeric arguments to set the heading level explicitly.

If you specify heading levels out of sequence, such as invoking `.NH 3' after `.NH 1', groff prints a warning on standard error.

Macro: .SH

Unnumbered subheading.

4.3.5.3 Highlighting

The `ms' macros provide a variety of methods to highlight or emphasize text:

Macro: .B [{txt

Sets its first argument in bold type. If you specify a second argument, groff prints it in the previous font after the bold text, with no intervening space (this allows you to set punctuation after the highlighted text without highlighting the punctuation). Similarly, it prints the third argument (if any) in the previous font before the first argument. For example,

.B foo ) (

prints (foo).

If you give this macro no arguments, groff prints all text following in bold until the next highlighting, paragraph, or heading macro.

Macro: .R [{txt

Sets its first argument in roman (or regular) type. It operates similarly to the B macro otherwise.

Macro: .I [{txt

Sets its first argument in italic type. It operates similarly to the B macro otherwise.

Macro: .CW [{txt

Sets its first argument in a constant width face. It operates similarly to the B macro otherwise.

Macro: .BI [{txt

Sets its first argument in bold italic type. It operates similarly to the B macro otherwise.

Macro: .BX [{txt

Prints its argument and draws a box around it. If you want to box a string that contains spaces, use a digit-width space (\0).

Macro: .UL [{txt

Prints its first argument with an underline. If you specify a second argument, groff prints it in the previous font after the underlined text, with no intervening space.

Macro: .LG

Prints all text following in larger type (two points larger than the current point size) until the next font size, highlighting, paragraph, or heading macro. You can specify this macro multiple times to enlarge the point size as needed.

Macro: .SM

Prints all text following in smaller type (two points smaller than the current point size) until the next type size, highlighting, paragraph, or heading macro. You can specify this macro multiple times to reduce the point size as needed.

Macro: .NL

Prints all text following in the normal point size (that is, the value of the PS register).

4.3.5.4 Lists

The .IP macro handles duties for all lists.

Macro: .IP [{marker

The marker is usually a bullet glyph (\[bu]) for unordered lists, a number (or auto-incrementing number register) for numbered lists, or a word or phrase for indented (glossary-style) lists.

The width specifies the indent for the body of each list item; its default unit is `n'. Once specified, the indent remains the same for all list items in the document until specified again.

The following is an example of a bulleted list.

A bulleted list: .IP \[bu] 2 lawyers .IP \[bu] guns .IP \[bu] money

Produces:

A bulleted list: o lawyers o guns o money

The following is an example of a numbered list.

.nr step 1 1 A numbered list: .IP \n[step] 3 lawyers .IP \n+[step] guns .IP \n+[step] money

Produces:

A numbered list: 1. lawyers 2. guns 3. money

Note the use of the auto-incrementing number register in this example.

The following is an example of a glossary-style list.

A glossary-style list: .IP lawyers 0.4i Two or more attorneys. .IP guns Firearms, preferably large-caliber. .IP money Gotta pay for those lawyers and guns!

Produces:

A glossary-style list: lawyers Two or more attorneys. guns Firearms, preferably large-caliber. money Gotta pay for those lawyers and guns!

In the last example, the IP macro places the definition on the same line as the term if it has enough space; otherwise, it breaks to the next line and starts the definition below the term. This may or may not be the effect you want, especially if some of the definitions break and some do not. The following examples show two possible ways to force a break.

The first workaround uses the br request to force a break after printing the term or label.

A glossary-style list: .IP lawyers 0.4i Two or more attorneys. .IP guns .br Firearms, preferably large-caliber. .IP money Gotta pay for those lawyers and guns!

The second workaround uses the \p escape to force the break. Note the space following the escape; this is important. If you omit the space, groff prints the first word on the same line as the term or label (if it fits) then breaks the line.

A glossary-style list: .IP lawyers 0.4i Two or more attorneys. .IP guns \p Firearms, preferably large-caliber. .IP money Gotta pay for those lawyers and guns!

To set nested lists, use the RS and RE macros. See section 4.3.5.5 Indents, for more information.

For example:

.IP \[bu] 2 Lawyers: .RS .IP \[bu] Dewey, .IP \[bu] Cheatham, .IP \[bu] and Howe. .RE .IP \[bu] Guns

Produces:

o Lawyers: o Dewey, o Cheatham, o and Howe. o Guns

4.3.5.5 Indents

In many situations, you may need to indent a section of text while still wrapping and filling. See section 4.3.5.4 Lists, for an example of nested lists.

Macro: .RS

Macro: .RE

These macros begin and end an indented section. The PI register controls the amount of indent, allowing the indented text to line up under hanging and indented paragraphs.

See section 4.3.5.7 Displays and keeps, for macros to indent and turn off filling.

4.3.5.6 Tab Stops

Use the ta request to define tab stops as needed. See section 5.11 Tabs and Fields.

Macro: .TA

Use this macro to reset the tab stops to the default for `ms' (every 5n). You can redefine the TA macro to create a different set of default tab stops.

4.3.5.7 Displays and keeps

Use displays to show text-based examples or figures (such as code listings).

Displays turn off filling, so lines of code are displayed as-is without inserting br requests in between each line. Displays can be kept on a single page, or allowed to break across pages.

Macro: .DS @t{L

Macro: .LD

Macro: .DE

Left-justified display. The `.DS L' call generates a page break, if necessary, to keep the entire display on one page. The LD macro allows the display to break across pages. The DE macro ends the display.

Macro: .DS @t{I

Macro: .ID

Macro: .DE

Indents the display as defined by the DI register. The `.DS I' call generates a page break, if necessary, to keep the entire display on one page. The ID macro allows the display to break across pages. The DE macro ends the display.

Macro: .DS @t{B

Macro: .BD

Macro: .DE

Sets a block-centered display: the entire display is left-justified, but indented so that the longest line in the display is centered on the page. The `.DS B' call generates a page break, if necessary, to keep the entire display on one page. The BD macro allows the display to break across pages. The DE macro ends the display.

Macro: .DS @t{C

Macro: .CD

Macro: .DE

Sets a centered display: each line in the display is centered. The `.DS C' call generates a page break, if necessary, to keep the entire display on one page. The CD macro allows the display to break across pages. The DE macro ends the display.

Macro: .DS @t{R

Macro: .RD

Macro: .DE

Right-justifies each line in the display. The `.DS R' call generates a page break, if necessary, to keep the entire display on one page. The RD macro allows the display to break across pages. The DE macro ends the display.

On occasion, you may want to keep other text together on a page. For example, you may want to keep two paragraphs together, or a paragraph that refers to a table (or list, or other item) immediately following. The `ms' macros provide the KS and KE macros for this purpose.

Macro: .KS

Macro: .KE

The KS macro begins a block of text to be kept on a single page, and the KE macro ends the block.

Macro: .KF

Macro: .KE

Specifies a floating keep; if the keep cannot fit on the current page, groff holds the contents of the keep and allows text following the keep (in the source file) to fill in the remainder of the current page. When the page breaks, whether by an explicit bp request or by reaching the end of the page, groff prints the floating keep at the top of the new page. This is useful for printing large graphics or tables that do not need to appear exactly where specified.

You can also use the ne request to force a page break if there is not enough vertical space remaining on the page.

Use the following macros to draw a box around a section of text (such as a display).

Macro: .B1

Macro: .B2

Marks the beginning and ending of text that is to have a box drawn around it. The B1 macro begins the box; the B2 macro ends it. Text in the box is automatically placed in a diversion (keep).

4.3.5.8 Tables, figures, equations, and references

The `ms' macros support the standard groff preprocessors: tbl, pic, eqn, and refer. You mark text meant for preprocessors by enclosing it in pairs of tags as follows.

Macro: .TS [@code{H

Macro: .TE

Denotes a table, to be processed by the tbl preprocessor. The optional argument H to TS instructs groff to create a running header with the information up to the TH macro. groff prints the header at the beginning of the table; if the table runs onto another page, groff prints the header on the next page as well.

Macro: .PS

Macro: .PE

Denotes a graphic, to be processed by the pic preprocessor. You can create a pic file by hand, using the AT&T pic manual available on the Web as a reference, or by using a graphics program such as xfig.