groff: Input Conventions
5.1.10 Input Conventions
------------------------
Since GNU 'troff' fills text automatically, it is common practice in the
'roff' language 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 (⇒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.(1)
(⇒Input Conventions-Footnote-1) 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,
tab, or newline characters and don't end a sentence.
* In filled text lines, use '\&' before '.' and ''' if they are
preceded by space, so that reflowing the input doesn'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.
* 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 GNU 'troff' 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
Info Catalog
groff: Input Encodings
groff: Text