Re: groff_mm(7)'s use of periods before macro names is inconsistent.

[G. Branden Robinson]

Hi, Kurt!

At 2021-07-17T17:43:15-0400, T. Kurt Bond wrote:
> In the list of macros in groff_mm(7) the macro names in the headings
> of paragraphs in the "Macros" section are never specified with a
> leading period.  In similar cases in groff_ms(7) and groff_man(7)  the
> periods are always used.  Also, in the text of paragraphs
> groff_mm(7)'s use of periods before macro names is inconsistent:
> sometimes it uses them, and sometimes it does not.  You can see this
> in the paragraph for GETST, where in the body refers to ".SETR" with
> the period, and to "GETST" and "INITR" without the period.

I agree that this sort of inconsistency is not good.

It turns out that I have a set of style rules regarding references to
register, macro, string, and request names, and these rules differ in
some details depending on whether they're being presented in a man page
or someplace else.  There is a method to my madness but (1) I'm sure I
haven't been completely consistent despite my meticulous efforts and (2)
despite having been at the task off and on for 4+ years now, I haven't
gotten all of groff's man pages to the point where I'm happy with all of
them.

However, to set down those style rules and submit them for consideration
and argument right now would take time and attention away from the
instant issue, which I think is simpler and easier.

Until very recently groff_mm(7) has received little of my attention at
all, because I had no experience with the package and the page  was
large enough to seem unmasterable from it.  I think over time you'll
find it improving in this respect, among others.

> This has a practical consequence: it is much harder to find all
> mentions of a macro name when the leading period is omitted.  For
> instance, you can easily find the one occurrence of the "P" macro in
> groff_mm(7) where it is specified with a leading period, but finding
> all the other occurrences of the "P" macro are hard, because searching
> finds the "P"s in the middle of other macro names and in the body
> text.

You're probably using less(1), right?  This situation is remediable by
knowing the zero-width word boundary matching operators, \< and \>.

If I want to find "P" as a word by itself in a man page, whether
surrounded by whitespace or abutting one or both ends of a display line,
I can use

        \<P\>

to find all such instances.

> So, does anybody think this warrants changing the man page to match
> the other macro package man pages?  If no-one else has plans for
> changing the mm man page I could produce a diff...

I sure don't mind assistance on the man page front, but I think the
above trick is regex knowledge that everyone should have.  It's a shame
it doesn't appear in regex(7)--is it truly not POSIX?!  In any case,
every regex engine I commonly use supports it: regular grep ("egrep"
too), Vim, less, and (GNU) sed.

Regards,
Branden

signature.asc
Description: PGP signature