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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sun, Jul 18, 2021 at 08:53:22AM +1000:
> 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.

Me too.

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

Wait, if those style rules would take a long time to write down,
i venture to respectfully make an uneducated guess: they are
overengineered and ought to be simpler.

Here is my style rule for marking up macro names in manual pages:

 1. When displaying source code examples (one or more complete lines)
    in any formal language (programming or markup language), include
    all the syntax elements required by the language, such that the
    examples can be copied into a program or document as-is.
    For roff(7) requests and macros, that implies including the
    control character; usually ".", rarely "'", very rarely
    something else when .cc is in use.

 2. In all other situations, use mdoc(7) .Ic or man(7) .B to
    mark up the macro or request, but do not include the dot.
    The reason is that the dot is not part of the request or
    macro name but a separate syntactic element, witnessed by
    the fact that it can sometimes be a different character
    as explained above.  Also, in some macro languages, for
    example mdoc(7), macros can appear without any control
    character when not at the beginning of the line, for example

      .Nm rm Fl dfiPRrv Ar

    Putting dots before the .Fl and .Ar would be invalid syntax.

That's it for manual pages (and in other languages supporting
markup).

In ASCII text documents, for example in email as you see above,
i generally use the dot before request and macro names as some kind
of a poor man's markup.


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

No, word boundaries are not POSIX regex.

The BSD form is

  [[:<:]]P[[:>:]]

The SVR4 form is

  \<P\>

But nowadays, most BSD systems support both variants.
When typing interactively, i tend to use the SVR4 form.
I can't imagine why...

Yours,
  Ingo