Re: rethinking @def*

[pertusus]

On Tue, Jul 26, 2022 at 09:14:49PM +0100, Gavin Smith wrote:
> On Tue, Jul 26, 2022 at 08:27:35PM +0100, Gavin Smith wrote:
> 
> Here's the first thing I looked at from the groff manual and it raises
> some issues:

The actual code is:
@defmac @t{.TH} title section [@r{@slanted{extra1}} [@r{@slanted{extra2}} 
[@r{@slanted{extra3}}]]]

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

Indeed, it uses @slanted.

> 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 that respect, the groff manual is actually different from other
manuals, as @slanted is used explictly, according to a comment, for
Info, to avoid all caps as you describe below.  But at the same time, it
ensures that the TeX output is @slanted and not typewriter+slanted
in the definition line.

But all this is different from the default formatting, and probably from
most manuals, I guess?

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

For that, it seems to me that is is really expected, in the groff manual
that the square bracket are not slanted, which is not what I proposed.

-- 
Pat