Next: , Previous: Tutorial for Macro Users, Up: Tutorial for Macro Users


3.1 Basics

This section covers some of the basic concepts necessary to understand how to use a macro package.1 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 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 (no tabs). More details on this can be found in Request and Macro 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, etc.

is 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, etc.

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 normally do blank input lines and input lines beginning with a space.

Not all input lines are text to be formatted. Some 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.

gtroff double-spaces output text automatically if you use the request ‘.ls 2. Reactivate single-spaced mode by typing ‘.ls 1.2

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 whitespace (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 (more measurement units are available, see Measurements).

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.


Footnotes

[1] This section is derived from Writing Papers with nroff using -me by Eric P. Allman.

[2] If you need finer granularity of the vertical space, use the pvs request (see Changing Type Sizes).