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
