5.1.11 Input Conventions

Since a roff formatter fills text automatically, its experienced users tend to avoid visual composition of text in input files: the esthetic appeal of the formatted output is what matters. Therefore, roff input should be arranged such that it is easy for authors and maintainers to compose and develop the document, understand the syntax of roff requests, macro calls, and preprocessor languages used, and predict the behavior of the formatter. Several traditions have accrued in service of these goals.

• Follow sentence endings in the input with newlines to ease their recognition (see Sentences). It is frequently convenient to end text lines after colons and semicolons as well, as these typically precede independent clauses. Consider doing so after commas; they often occur in lists that become easy to scan when itemized by line, or constitute supplements to the sentence that are added, deleted, or updated to clarify it. Parenthetical and quoted phrases are also good candidates for placement on text lines by themselves.
• Set your text editor’s line length to 72 characters or fewer.³⁹ This limit, combined with the previous item of advice, makes it less common that an input line will wrap in your text editor, and thus will help you perceive excessively long constructions in your text. Recall that natural languages originate in speech, not writing, and that punctuation is correlated with pauses for breathing and changes in prosody.
• Use \& after ‘!’, ‘?’, and ‘.’ if they are followed by space or newline characters and don’t end a sentence.
• In filled text lines, use \& before ‘.’ and ‘'’ if they are preceded by space, so that revisions to the input don’t turn them into control lines.
• Do not use spaces to perform indentation or align columns of a table. Leading spaces are reliable when text is not being filled. (Exception: when laying out a table with GNU tbl, specifying the nospaces region option causes the program to ignore spaces at the boundaries of table cells.)
• Comment your document. It is never too soon to apply comments to record information of use to future document maintainers (including your future self). We thus introduce another escape sequence, \", which causes the formatter to ignore the remainder of the input line.
• Use the empty request—a control character followed immediately by a newline—to visually manage separation of material in input files. Many of the groff project’s own documents use an empty request between sentences, after macro definitions, and where a break is expected, and two empty requests between paragraphs or other requests or macro calls that will introduce vertical space into the document.

  You can combine the empty request with the comment escape sequence to include whole-line comments in your document, and even “comment out” sections of it.

We conclude this section with an example sufficiently long to illustrate most of the above suggestions in practice. For the purpose of fitting the example between the margins of this manual with the font used for its typeset version, we have shortened the input line length to 56 columns. As before, an arrow → indicates a tab character.

.\"   nroff this_file.roff | less
.\"   groff -T ps this_file.roff > this_file.ps
→The theory of relativity is intimately connected with
the theory of space and time.
.
I shall therefore begin with a brief investigation of
the origin of our ideas of space and time,
although in doing so I know that I introduce a
controversial subject.  \" remainder of paragraph elided
.
.

→The experiences of an individual appear to us arranged
in a series of events;
in this series the single events which we remember
appear to be ordered according to the criterion of
\[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped
which cannot be analysed further.
.
There exists,
therefore,
for the individual,
an I-time,
or subjective time.
.
This itself is not measurable.
.
I can,
indeed,
associate numbers with the events,
in such a way that the greater number is associated with
the later event than with an earlier one;
but the nature of this association may be quite
arbitrary.
.
This association I can define by means of a clock by
comparing the order of events furnished by the clock
with the order of a given series of events.
.
We understand by a clock something which provides a
series of events which can be counted,
and which has other properties of which we shall speak
later.
.\" Albert Einstein, _The Meaning of Relativity_, 1922