groff: Basics
3.1 Basics
==========
This section covers some of the basic concepts necessary to understand
how to use a macro package.(1) (⇒Basics-Footnote-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
that 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 that 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' packs words onto longer lines anyhow.
* In keeping with this, it is helpful to begin a new line after every
comma or phrase, since common corrections are to add or delete
sentences or phrases.
* End each sentence with two spaces - or better, start each sentence
on a new line. 'gtroff' recognizes characters that usually end a
sentence, and inserts sentence space accordingly.
* Do not hyphenate words at the end of lines - 'gtroff' is smart
enough to hyphenate words 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' double-spaces output text automatically if you use the
request '.ls 2'. Reactivate single-spaced mode by typing '.ls 1'.(2)
(⇒Basics-Footnote-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'.
Info Catalog
groff: Tutorial for Macro Users
groff: Tutorial for Macro Users
groff: Common Features