Dear All,
while experimenting with the mm macro package for the first time I
noticed that from the very start it did not behave exactly as expected
--- which was entirely due to my lacking of understanding of some basics.
Starting a text without any macro yields just a page flooded with text
--- no headers/footers, margins etc. even though I invoked the -mm
package. Luckily, I remembered from somewhere that page setup is
triggered by at least one of .P or similar commands. Finally, it took
several experiments to find out how to properly use the title setup
macros, and in which logical order the macros have to be used. Take for
example, a look at groff_mm and check the .MT macro which must be issued
after the .TL and .AU macros; however, while plausible, this is not
mentioned anywhere.
In the same document, .COVER gives an overview in which order the
elements have to appear, there is also miscellaneous information under
the explanations to .AU ("AU must not appear before TL."), and under TL:
"All text up to the next AU is included in the title."
In contrast to mm and me, the mom man page _starts_ with an introduction
to proper document setup (or at least a pointer to that documentation).
For groff_me, the information how to set up a document is delivered on
p. 13 of 18 (see meintro.ps,; no such information in the manpage).
groff_ms at least has a section "Usage" at the very beginning, this is
very close to what I hope to see; however, the newcomer stumbles upon
"The simplest documents can begin with a paragraph macro and consist of
text separated by paragraph macros or even blank lines." The paragraph
macros are covered as a subsection to "Usage" but quite late. Why not
state a minimal working example like
.\" Minimal working example
.PP
Your text here is presented as a well-formed document.
.\" End
right here?
A good number of manpages I am familiar with have a section "Example"
(see e.g. grep(1)) or "Examples" (see e.g. find(1)).
Wouldn't it be helpful to prepend the alphabetical macro references in
groff_ms, groff_mm and groff_me by a short section labelled "Minimal
page setup"? I think this would significantly lower the entry barrier to
first-time users, because after that it becomes much easier to check the
alphabetical reference: you can now search for what you need, and not
for what you miss.
Basically, the structure of the existing manpages can be left as-is,
with the insertion of a minimum working example near the very beginning
of the respective man page.
Best regards,
Oliver.
--
Dr. Oliver Corff
Wittelsbacherstr. 5A
10707 Berlin
G E R M A N Y
Tel.: +49-30-85727260
Mail:oliver.co...@email.de
