3. Tutorial for Macro Users

Most users tend to use a macro package to format their papers. This means that the whole breadth of groff is not necessary for most people. This chapter covers the material needed to efficiently use a macro package.

3.1 Basics
3.2 Common Features

3.1 Basics

This section covers some of the basic concepts necessary to understand how to use a macro package.(3) References are made throughout to more detailed information, if desired.

gtroff reads an input file prepared by the user and outputs a formatted document suitable for publication or framing. The input consists of text, or words to be printed, and embedded commands (requests and escapes), which tell gtroff how to format the output. For more detail on this, see 5.6 Embedded Commands.

The word argument is used in this chapter to mean a word or number which appears on the same line as a request, and which modifies the meaning of that request. For example, the request

.sp

spaces one line, but

.sp 4

spaces four lines. The number 4 is an argument to the sp request which says to space four lines instead of one. Arguments are separated from the request and from each other by spaces. More details on this can be found in 5.6.1.1 Request Arguments.

The primary function of gtroff is to collect words from input lines, fill output lines with those words, justify the right-hand margin by inserting extra spaces in the line, and output the result. For example, the input:

Now is the time for all good men to come to the aid of their party. Four score and seven years ago,...

will be read, packed onto output lines, and justified to produce:

Now is the time for all good men to come to the aid of their party. Four score and seven years ago,...

Sometimes a new output line should be started even though the current line is not yet full; for example, at the end of a paragraph. To do this it is possible to cause a break, which starts a new output line. Some requests cause a break automatically, as do blank input lines and input lines beginning with a space.

Not all input lines are text to be formatted. Some of the input lines are requests which describe how to format the text. Requests always have a period (`.') or an apostrophe (`'') as the first character of the input line.

The text formatter also does more complex things, such as automatically numbering pages, skipping over page boundaries, putting footnotes in the correct place, and so forth.

Here are a few hints for preparing text for input to gtroff. First, keep the input lines short. Short input lines are easier to edit, and gtroff will pack words onto longer lines anyhow. In keeping with this, it is helpful to begin a new line after every period, comma, or phrase, since common corrections are to add or delete sentences or phrases. Secondly, do not hyphenate words at the end of lines -- gtroff is smart enough to hyphenate words for the user as needed, but is not smart enough to take hyphens out and join a word back together. Also, words such as "mother-in-law" should not be broken over a line, since then a space can occur where not wanted, such as "mother- in-law".

gtroff will double space output text automatically if you use the request `.ls 2'. Single spaced mode can be reactivated by typing `.ls 1'.

A number of requests allow to change the way the output looks, sometimes called the layout of the output page. Most of these requests adjust the placing of white space (blank lines or spaces).

The `.bp' request starts a new page, causing a line break.

The request `.sp N' leaves N lines of blank space. N can be omitted (meaning skip a single line) or can be of the form Ni (for N inches) or Nc (for N centimeters). For example, the input:

.sp 1.5i My thoughts on the subject .sp

leaves one and a half inches of space, followed by the line "My thoughts on the subject", followed by a single blank line.

Text lines can be centered by using the ce request. The line after ce is centered (horizontally) on the page. To center more than one line, use `.ce N' (where N is the number of lines to center), followed by the N lines. To center many lines without counting them, type:

.ce 1000 lines to center .ce 0

The `.ce 0' request tells groff to center zero more lines, in other words, stop centering.

All of these requests cause a break; that is, they always start a new line. To start a new line without performing any other action, use br.

3.2 Common Features

gtroff provides very low level operations for formatting a document. There are many common routine operations which are done in all documents. These common operations are written into macros and collected into a macro package.

All macro packages provide certain common capabilities which fall into the following categories.

3.2.1 Paragraphs
3.2.2 Sections and Chapters
3.2.3 Headers and Footers
3.2.4 Page Layout
3.2.5 Displays
3.2.6 Footnotes and Annotations
3.2.7 Table of Contents
3.2.8 Indices
3.2.9 Paper Formats
3.2.10 Multiple Columns
3.2.11 Font and Size Changes
3.2.12 Predefined Strings
3.2.13 Preprocessor Support
3.2.14 Configuration and Customization

3.2.1 Paragraphs

One of the most common and most used capability is starting a paragraph. There are a number of different types of paragraphs, any of which can be initiated with macros supplied by the macro package. Normally, paragraphs start with a blank line and the first line indented, like the text in this manual. There are also block style paragraphs, which omit the indentation:

Some men look at constitutions with sanctimonious reverence, and deem them like the ark of the covenant, too sacred to be touched.

And there are also indented paragraphs which begin with a tag or label at the margin and the remaining text indented.

one This is the first paragraph. Notice how the first line of the resulting paragraph lines up with the other lines in the paragraph. longlabel This paragraph had a long label. The first character of text on the first line will not line up with the text on second and subsequent lines, although they will line up with each other.

A variation of this is a bulleted list.

3.2.2 Sections and Chapters

Most macro packages supply some form of section headers. The simplest kind is simply the heading on a line by itself in bold type. Others supply automatically numbered section heading or different heading styles at different levels. Some, more sophisticated, macro packages supply macros for starting chapters and appendices.

3.2.3 Headers and Footers

Every macro package gives some way to manipulate the headers and footers (or titles) on each page. Some packages will allow for different ones on the even and odd pages (for material printed in a book form).

The titles are called three-part titles, that is, there is a left-justified part, a centered part, and a right-justified part. An automatically generated page number may be put in any of these fields with the `%' character (see 5.15 Page Layout, for more details).

3.2.4 Page Layout

Most macro packages let the user specify top and bottom margins and other details about the appearance of the printed pages.

3.2.5 Displays

Displays are sections of text to be set off from the body of the paper. Major quotes, tables, and figures are types of displays, as are all the examples used in this document.

Major quotes are quotes which are several lines long, and hence are set in from the rest of the text without quote marks around them.

A list is an indented, single spaced, unfilled display. Lists should be used when the material to be printed should not be filled and justified like normal text, such as columns of figures or the examples used in this paper.

A keep is a display of lines which are kept on a single page if possible. An example for a keep might be a diagram. Keeps differ from lists in that lists may be broken over a page boundary whereas keeps will not.

Floating keeps move relative to the text. Hence, they are good for things which will be referred to by name, such as "See figure 3". A floating keep will appear at the bottom of the current page if it will fit; otherwise, it will appear at the top of the next page. Meanwhile, the surrounding text will `flow' around the keep, thus leaving now blank areas.

3.2.6 Footnotes and Annotations

There are a number of requests to save text for later printing.

Footnotes are printed at the bottom of the current page.

Delayed text is very similar to a footnote except that it is printed when called for explicitly. This allows a list of references to appear (for example) at the end of each chapter, as is the convention in some disciplines.

Most macro packages which supply this functionality also supply a means of automatically numbering either type of annotation.

3.2.7 Table of Contents

Tables of contents are a type of delayed text having a tag (usually the page number) attached to each entry after a row of dots. The table accumulates throughout the paper until printed, usually after the paper has ended. Many macro packages will provide the ability to have several tables of contents (i.e. one standard one, one for tables, etc).

3.2.8 Indices

While some macro packages will use the term index, none actually provide that functionality. The facilities they call indices are actually more appropriate for tables of contents.

3.2.9 Paper Formats

Some macro packages provide stock formats for various kinds of documents. Many of them provide a common format for the title and opening pages of a technical paper. The `mm' macros in particular provide formats for letters and memoranda.

3.2.10 Multiple Columns

Some macro packages (but not `man') provide the ability to have two or more columns on a page.

3.2.11 Font and Size Changes

The built-in font and size functions are not always intuitive, so all macro packages provide macros to make these operations simpler.

3.2.12 Predefined Strings

Most macro packages provide various predefined strings for a variety of uses; examples are sub- and superscripts, printable dates, quotes and various special characters.

3.2.13 Preprocessor Support

All macro packages provide support for the various preprocessors.

3.2.14 Configuration and Customization

Some macro packages provide means of customizing many of the details of how the package behaves. This ranges from setting the default type size to changing the appearance of section headers.