Re: rethinking @def*

[Gavin Smith]

On Tue, Jul 26, 2022 at 08:27:35PM +0100, Gavin Smith wrote:

> The comment from 2003 said that the groff manual needed Roman type in
> @def* line output.  Examples from the groff manual would be one of the
> first things I would look at, and this might help to move this conversation
> forward more than discussions of abstract principles of backwards
> compatibility.
> 

Here's the first thing I looked at from the groff manual and it raises
some issues:

@defmac .TH title section [@var{extra1} [@var{extra2} [@var{extra3}]]]
Set the title of the man page to @var{title} and the section to
@var{section}, which must have a value between 1 and@tie{}8.  The value
of @var{section} may also have a string appended, e.g.@: @samp{.pm}, to
indicate a specific subsection of the man pages.

Both @var{title} and @var{section} are positioned at the left and right
in the header line (with @var{section} in parentheses immediately
appended to @var{title}.  @var{extra1} is positioned in the middle of
the footer line.  @var{extra2} is positioned at the left in the footer
line (or at the left on even pages and at the right on odd pages if
double-sided printing is active).  @var{extra3} is centered in the
header line. 
@end defmac

I adapted this from the groff sources to avoid use of user-defined
macros.  Processing this shows a difference between where @var isn't
used (slanted roman) and where @var is used (slanted typewriter).

(The groff manual itself doesn't have this discrepancy because it
didn't use @var.)

However, in the body of the definition, @var produces slanted roman
only.  It would be sensible to use the same font in both the definition
line and the definition body to refer to the parameters.  Hence,
I'd argue that @var producing slanted typewriter in the definition
line is a mistake, and it should produce slanted roman instead.

In Info output, you get

 -- Macro: .TH title section [EXTRA1 [EXTRA2 [EXTRA3]]]
     Set the title of the man page to TITLE and the section to SECTION,
     which must have a value between 1 and 8.  The value of SECTION may
     also have a string appended, e.g. ‘.pm’, to indicate a specific
     subsection of the man pages.

     Both TITLE and SECTION are positioned at the left and right in the
     header line (with SECTION in parentheses immediately appended to
     TITLE.  EXTRA1 is positioned in the middle of the footer line.
     EXTRA2 is positioned at the left in the footer line (or at the left
     on even pages and at the right on odd pages if double-sided
     printing is active).  EXTRA3 is centered in the header line.

which isn't great: Use of all caps should be consistent for macro
parameters.  In the real groff manual, which didn't use @var in the
@def line, it is:

 -- Macro: .TH title section [extra1 [extra2 [extra3]]]
     Set the title of the man page to TITLE and the section to SECTION,
     which must have a value between 1 and 8.  The value of SECTION may
     also have a string appended, e.g. '.pm', to indicate a specific
     subsection of the man pages.

     Both TITLE and SECTION are positioned at the left and right in the
     header line (with SECTION in parentheses immediately appended to
     TITLE.  EXTRA1 is positioned in the middle of the footer line.
     EXTRA2 is positioned at the left in the footer line (or at the left
     on even pages and at the right on odd pages if double-sided
     printing is active).  EXTRA3 is centered in the header line.

which is not too bad - readers can recognize the convention being
used here, lower case in the def line, all caps in the def body.

What would certainly be an unacceptable change to make in Texinfo would
be to give the def line the @var style by default in all output formats,
yielding, in Info

 -- Macro: .TH TITLE SECTION [EXTRA1 [EXTRA2 [EXTRA3]]]

as this muddies the distinction between the macro name (all caps)
and the macro parameters.

All of these kinds of details would have to be checked for any
proposed change.

This also shows the use of square brackets as not part of the language,
but showing optional arguments, as Patrice mentioned.