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

[Nate Bargmann]

Hi Branden and all.

I took the bait and looked up the linux-man mailing list archive and
from there found the link to graff_man(7) and from it groff_man_style(7)
on man7.org (the linux-man project page.  Great resource by the
linux-man project, BTW).  I think the effort with groff_man_style(7) is
outstanding and it would have helped me years ago from jumping around
three or four man pages and interpolating/interpreting good practice for
such documentation.  The link is likely one I'll include in my meager
README.man-pages for the hamlib project.  (Of course, my Debian Bullseye
systems lack groff_man_style(7) as they still have groff 1.22.4
installed).

Regarding the PDF you attached from the Groff manual, I do think that
would still be rather dense reading for anyone without the background in
groff_man_style(7) and is for advanced man page authors/maintainers.

Now, a slight tangent.  I think you would agree that consistency in the
man page corpus is a difficult but worthy goal.  At the very least there
should be consistency in the corpus on a per-project basis and even this
is difficult over time as files are touched by various authors.

In groff_man_style(7) the .BI, .BR, etc. macros are described as setting
their odd arguments to the first style and their second argument to the
second style and so on on an odd/even alternating basis.

However, I was reading groff_mm(7) recently and noticed that the
description for its .IB macro reads as follows:

       IB [italic‐text [bold‐text [italic‐text [...]]]
              Italic‐bold.  Even arguments are printed in italic,  odd in 
              bold‐face.  See I.

Do you see the disparity?

I think it is natural in the case of most people to assume as
groff_man_style(7) that macro arguments are odd/even alternating while
groff_mm(7) states even/odd alternating.  Hmmm.  I attribute the wording
in groff_mm(7) to be related in terms of 0 based indexing whereas most
documenters--not programmers per se--are more familiar with 1 based
indexing.

Thoughts?

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: https://www.n0nb.us
Projects: https://github.com/N0NB
GPG fingerprint: 82D6 4F6B 0E67 CD41 F689 BBA6 FB2C 5130 D55A 8819

signature.asc
Description: PGP signature