Hi, Alex!
At 2022-03-14T15:05:49+0100, Alejandro Colomar (man-pages) wrote:
> Always start sentences after '.' in a new line.
> That's already covered by "semantic newlines" (see above),
> but it's especially important in this case because
> groff(1) prints (at least) 2 spaces after '.' normally,
> but if you write it this way it doesn't.
>
> BTW, Branden,
> I CCd you because I didn't find this documented in groff(7),
> or at least I couldn't find it.
> I tried /\.[^ [a-z]] and also keywords like period, point or dot,
> but no luck.
> Is it documented anywhere?
It used to be one of those things everybody just "knew" about writing in
*roff--back when people hung on Brian Kernighan's every word[1]--but
over the years the knowledge has atrophied.
The groff 1.22.4 Texinfo manual has the following. I believe this
material is adapted from Eric Allman's paper "Writing Papers with NROFF
using -me".
[[
3 Tutorial for Macro Users
**************************
Most users tend to use a macro package to format their papers. This
means that the whole breadth of 'groff' is not necessary for most
people. This chapter covers the material needed to efficiently use a
macro package.
[...]
* 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.
]]
This advice, in the context of macro package usage, is scoped too
narrowly. The manual has a later section which makes the point again.
[[
5.1.6 Input Conventions
-----------------------
Since 'gtroff' does filling automatically, it is traditional in 'groff'
not to try and type things in as nicely formatted paragraphs. These are
some conventions commonly used when typing 'gtroff' text:
* Break lines after punctuation, particularly at the end of a
sentence and in other logical places. Keep separate phrases on
lines by themselves, as entire phrases are often added or deleted
when editing.
* Try to keep lines less than 40-60 characters, to allow space for
inserting more text.
* Do not try to do any formatting in a WYSIWYG manner (i.e., don't
try using spaces to get proper indentation).
]]
I have written new material for groff's Texinfo manual in the
forthcoming 1.23.0 release. The above section is significantly expanded
and, happily for skeptics of GNU Texinfo, ported to a man page as well.
The roff(7) page bears the fruit of much labor, including the following.
[[
Input conventions
Since troff fills text automatically, it is common practice in
roff languages to not attempt careful visual composition of text
in input files: it is the esthetic appeal of the formatted output
that 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.
• Break input lines after sentence‐ending punctuation to
ease their recognition. It is frequently convenient to
break after colons and semicolons as well, as these
typically precede independent clauses. Consider breaking
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 input lines by
themselves. In filled text, spaces and newlines are
interchangeable; place breaks where it aids your purpose.
• Set your text editor’s line length to 72 characters or
fewer; see the subsections below. This limit, combined
with the previous advice regarding breaking around
punctuation, 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 attempt to format the input in a WYSIWYG manner
(i.e., don’t try using spaces to get proper indentation or
align columns of a table).
• Comment your document. It is never too soon to apply
comments to record information of use to future document
maintainers (including your future self). The \" escape
sequence causes 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.
]]
This point about beginning sentences only on new input lines _is_
missing from groff_man_style(7). As noted in the groff 1.22.4 NEWS
file:
o ... groff_man(7) has been expanded and largely rewritten ... to be
more helpful and accessible to man page writers who may never read any
other groff documentation.
groff_man_style(7) is now fulfilling this role, since a quick reference
for experienced man page writers remains desirable. (I avoid letting
the two drift out of sync by generating both from an m4 master
document.)
I've been dithering over writing a new introductory section just for
groff_man_style(7) to present an example of a partial man page and use
it to explain typesetting terms that are inescapable even in the reduced
domain of man pages: breaking, filling, adjustment, hyphenation, and the
notorious matter of supplementary inter-sentence space.
As you will have observed, when I write in a hurry, I write a lot. The
foregoing notional material needs to be written well, and that means
taking the time to cook the fat off.
Regards,
Branden
[1] https://rhodesmill.org/brandon/2012/one-sentence-per-line/
Attachment:
signature.asc
Description: PGP signature
