Hi Riza, At 2025-06-27T20:11:31+0300, Riza Dindir wrote: > Hello, > > I am using groff, and the ms macro package. > > I was wondering what you do to make the groff/ms document source files > to be readable?
Our ms manual has some basic guidance along these lines.
1.1. Basic information
[snip]
... It is a good practice to start each sentence on a new line, or
to put two spaces after sentence‐ending punctuation, so that the
formatter knows where the sentence boundaries are. You can separate
paragraphs with further paragraphing macro calls, or with blank
lines, and you can indent with tabs. When you need one of the
features mentioned earlier, return to this manual.
Our Texinfo manual and roff(7) go into more detail.
roff(7):
Input conventions
Since 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. 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;
see the subsections below. 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). 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 the
input. 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.
> How do you format, and structure your document source?
In groff's man pages I tend to follow the guidance above, plus:
* I put one empty request between sentences.
* I put two empty requests anywhere I expect vertical space in the
output (assuming an infinite page length).
Regards,
Branden
signature.asc
Description: PGP signature
