An introduction to groff (and man page) input and concepts

[G. Branden Robinson]

Hi folks,

In looking at linux-man@ list traffic over the past few days I've seen
issues of *roff language syntax come up repeatedly.  To help shed some
light on things I thought I'd share some documentation I've been working
on for the past several months.

This is an 11-page document, extracted from the Texinfo manual in
groff's Git repository, written as a user's guide, not a technical
reference.  That means that it is a little more conversational and
discursive, and provides more examples, than man pages often are and do.
Nonetheless, I am stickler for precision and strive never to make
inaccurate claims, even for pedagogical purposes[1].

The primary audience is probably Michael Kerrisk, Alejandro Colomar, and
anyone who's interested in how man pages are actually parsed.

If you seek actual _definitions_ of terms the way *roff systems use
them, such as:

        word
        filling
        sentence
        end-of-sentence character
        escape sequence
        hyphenation
        break / breaking
        adjust / adjustment
        request
        control character
        no-break control character
        control line
        text line
        macro
        interpolation
        macro file
        macro package

...then this document might be for you as well.

The final two subsections ("Input Encodings" and "Input Conventions")
are based on material by Trent Fisher and Werner Lemberg, and they have
been in the groff Texinfo manual in approximately this form for a long
time.  The material before that is some of the fruit of my efforts to
teach myself *roff systems over the past few years.

It has been my intention to adapt this material for the beginning of the
groff_man_style(7) page but I have not yet done so.  I welcome
suggestions on what should be added or dropped to make it suitable for
such a purpose.  While not duplicating documentation is ordinarily a
high priority, man pages compel an exception for me; there's a lot about
roff systems and groff in particular that a man page writer does not
need to know, and which for page portability reasons, we discourage them
from employing in man pages if they do know about it.

But there are some basics that I think would benefit many man page
writers to know, and they are presented here.

As ever, I welcome feedback and follow-up questions.

Regards,
Branden

[1] In my view, a footnote is an ideal place to clarify, to the reader
    and to yourself, that you have had to speak approximately.

groff_input_intro.pdf
Description: Adobe PDF document

signature.asc
Description: PGP signature