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

[G. Branden Robinson]

Hi, Nate!

At 2021-07-31T15:22:09-0500, Nate Bargmann wrote:
> 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.

Terrific!

> (Of course, my Debian Bullseye systems lack groff_man_style(7) as they
> still have groff 1.22.4 installed).

Yes, regrettable.

> 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.

Oh, darn.  Well, that's good to know.  It tells me I need to vary my
approach for the introductory section I'll eventually add to the page.

> 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?

Yup.

> 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?

I think you're right.  The zeroth argument to a font alternation macro
is not going to typeset itself.  So we should count from one.

I have not touched groff_mm(7) very much; there is much about it that is
inconsistent with the way I've restyled most of other pages.

I knew when I got involved with groff documentation that I'd likely be
here for years.  :)

Regards,
Branden

signature.asc
Description: PGP signature