File: groff.info,  Node: Basics,  Next: Common Features,  Prev: Tutorial_for_Macro_Users.php">Tutorial for Macro Users,  Up: Tutorial_for_Macro_Users.php">Tutorial for Macro Users

3.1 Basics
==========

Let us first survey some basic concepts necessary to use a macro package
fruitfully.(1)  (*note Basics-Footnote-1::) References are made
throughout to more detailed information.

   GNU 'troff' 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 escape sequences), which tell GNU 'troff' how to format
the output.  *Note Formatter Instructions::.

   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 (_not_ tabs).  *Note
Invoking Requests::.

   The primary function of GNU 'troff' is to collect words from input
lines, fill output lines with those words, adjust the line to the
right-hand margin by widening spaces, 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 force a break, starting a new output line.  Some
requests cause a break automatically, as do (normally) blank input lines
and input lines beginning with a space or tab.

   Not all input lines are text lines--words to be formatted.  Some are
control lines that tell a macro package (or GNU 'troff' directly) how to
format the text.  Control lines start with a dot ('.') or an apostrophe
(''') as the first character, and can be followed by a macro call.

   The 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 GNU 'troff'.

   * First, keep the input lines short.  Short input lines are easier to
     edit, and GNU 'troff' 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.  GNU 'troff' recognizes characters that usually end
     a sentence, and inserts inter-sentence space accordingly.

   * Do not hyphenate words at the end of lines--GNU 'troff' 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".

   We offer further advice in *note Input Conventions::.

   GNU 'troff' permits alteration of the distance between lines of text.
This is termed vertical spacing and is expressed in the same units as
the type size--the point.  The default is 10-point type on 12-point
spacing.  To get double-spaced text you would set the vertical spacing
to 24 points.  Some, but not all, macro packages expose a macro or
register to configure the vertical spacing.

   A number of requests allow you to change the way the output is
arranged on the page, sometimes called the layout of the output page.
Most macro packages don't supply macros for performing these (at least
not without performing other actions besides), as they are such basic
operations.  The macro packages for writing man pages, 'man' and 'mdoc',
don't encourage explicit use of these requests at all.

   The request '.sp N' leaves N lines of blank space.  N can be omitted
(skipping 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 *note Measurements::).

   If you seek precision in spacing, be advised when using a macro
package that it might not honor 'sp' requests as you expect; it can use
a formatter feature called no-space mode to prevent excess space from
accumulating.  Macro packages typically offer registers to control
spacing between paragraphs, before section headings, and around displays
(discussed below); use these facilities preferentially.  *Note
Manipulating Spacing::.

   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 GNU 'troff' to center zero more lines, in
other words, stop centering.

   GNU 'troff' also offers the 'rj' request for right-aligning text.  It
works analogously to 'ce' and is convenient for setting epigraphs.

   The 'bp' request starts a new page; this necessarily implies an
ordinary (line) break.

   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'.  If you invoke them with the apostrophe ''', the no-break control
character, the (initial) break they normally perform is suppressed.
''br' does nothing.