Re: Instructions for minimal documents
Hi Oliver, At 2023-11-21T15:06:37+0100, Oliver Corff via wrote: > Dear Branden, > > you got me immediately on this one. Please accept my sincerest > apologies, the production environment here still is based on 1.22.4. No apologies necessary; as a Debian user since the 1990s I know how long it can take for stable releases to percolate into production environments. Though the all-time winner in groff's case is probably Mac OS X, which clung to groff 1.19 for well over a decade, snarling and spitting at later releases because they used GPLv3. > I'll take a new tour of the 1.23.0 man pages. You might also consider checking out documentation from the bleeding edge. https://www.dropbox.com/sh/17ftu3z31couf07/AAC_9kq0ZA-Ra2ZhmZFWlLuva?dl=0 Regards, Branden signature.asc Description: PGP signature
Re: Instructions for minimal documents
Dear Branden, you got me immediately on this one. Please accept my sincerest apologies, the production environment here still is based on 1.22.4. I'll take a new tour of the 1.23.0 man pages. Best regards, Oliver. On 21/11/2023 14:51, G. Branden Robinson wrote: Hi Oliver, At 2023-11-21T13:37:13+0100, Oliver Corff via wrote: 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. Before digging into the details of your message, can you confirm if you're using the version of the groff_mm(7) man page from 1.22.4, 1.23.0, or Git? I ask because I've done a lot of work on the page, some if it in the areas you've expressed frustration with. For example: Description The GNU implementation of the mm macro package is part of the groff document formatting system. The mm package is suitable for the composition of letters, memoranda, reports, and books. Call an mm macro at the beginning of a document to initialize the package. A simple mm document might use only P for paragraphing. Set numbered and unnumbered section headings with H and HU, respectively. Change the style of the typeface with B, I, and R; you can alternate styles with BI, BR, IB, IR, RB, and RI. Several nestable list types are available via AL, BL, BVL, DL, ML, RL, and VL; each of these begins a list, to which LI adds an item and LE ends the (nested) list. Customized list arrangements are supported by LB. DS and DF start static and floating displays, respectively; either is terminated with DE. [...] Document styles groff mm offers three different frameworks for document organization. COVER/COVEND is a flexible means of preparing any document requiring a cover page. LT/LO aids preparation of typical Anglophone correspondence (business letters, for example). The MT memorandum type mechanism implements a group of formal styles historically used by AT&T Bell Laboratories. Your document can select at most one of these approaches; when used, each disables the others. [...] Regards, Branden -- Dr. Oliver Corff Wittelsbacherstr. 5A 10707 Berlin G E R M A N Y Tel.: +49-30-85727260 Mail:oliver.co...@email.de
Re: Instructions for minimal documents
Hi Oliver, At 2023-11-21T13:37:13+0100, Oliver Corff via wrote: > 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. Before digging into the details of your message, can you confirm if you're using the version of the groff_mm(7) man page from 1.22.4, 1.23.0, or Git? I ask because I've done a lot of work on the page, some if it in the areas you've expressed frustration with. For example: Description The GNU implementation of the mm macro package is part of the groff document formatting system. The mm package is suitable for the composition of letters, memoranda, reports, and books. Call an mm macro at the beginning of a document to initialize the package. A simple mm document might use only P for paragraphing. Set numbered and unnumbered section headings with H and HU, respectively. Change the style of the typeface with B, I, and R; you can alternate styles with BI, BR, IB, IR, RB, and RI. Several nestable list types are available via AL, BL, BVL, DL, ML, RL, and VL; each of these begins a list, to which LI adds an item and LE ends the (nested) list. Customized list arrangements are supported by LB. DS and DF start static and floating displays, respectively; either is terminated with DE. [...] Document styles groff mm offers three different frameworks for document organization. COVER/COVEND is a flexible means of preparing any document requiring a cover page. LT/LO aids preparation of typical Anglophone correspondence (business letters, for example). The MT memorandum type mechanism implements a group of formal styles historically used by AT&T Bell Laboratories. Your document can select at most one of these approaches; when used, each disables the others. [...] Regards, Branden signature.asc Description: PGP signature
Instructions for minimal documents
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
