Re: rethinking @def*

[Gavin Smith]

On Wed, Jul 27, 2022 at 11:29:20AM +0200, pertusus@free.fr wrote:
> Hello,
> 
> I looked at the libc manual and the @deftype* formatting indeed looks
> wrong.  The function type is in upright @code, which looks good,
> but types within the function call are in slanted roman, and
> metasyntactic variables are in slanted typewriter.  It seems very
> strange.  I am actually very surprised that nobody complained.  Also,
> it is somewhat strange that after the change in 2003, similar change was
> not followed up on the argument.

I think it would be better for types not to be slanted by default as we
are using slant to indicate parameters.  (Perhaps slanted types should
be used where the type is a parameter, as in a C++ template.)

> Upright parenthese and brackets tend to look better, though.  To me it
> would be more logical to use typewriter upright parenthese and brackets,
> but we could keep roman upright parenthese and brackets for backward
> compatibility.

The problem is that square brackets could be "metasyntactic": not part
of the syntax of the programming language.  Ideally we shouldn't break the
kinds of usages that Werner posted showing different uses of square brackets.

One idea is to use typewriter parentheses and roman upright square brackets,
although this is becoming more complicated.

There are also commas; should they be in a typewriter font too?  And there
may be other separator characters depending on the syntax of the programming
language.

Another idea is to make all characters typewriter by default except
for parameter names, which would be slanted roman.  Any metasyntactic
characters would need to be wrapped in @r{...} by the document author.

> My current proposal would be
> * @var is not in typewriter anymore, even if in code context (@code,
>   @example, @def* line).  If people really want slanted typewriter,
>   they should use @code{@slanted{}} or to be sure not to be affected
>   by the current font style: @r{@code{@slanted{}}}

@var could be useful to use inside code, for example in a usage like
"macros of the form @code{AC_@var{foo}}" when discussing autoconf macros.
Changing this to slanted roman wouldn't be an improvement.

In fact, I don't see why @var shouldn't always be slanted typewriter.
We'd have to research whether this would be appropriate, but I'd
expect that nearly all uses of @var refer to "computer code".

There is inconsistency in the handling of the -- and --- ligatures
depending on whether @var is in code.  This was one of the reasons that
led to the change in 2003:
https://lists.gnu.org/archive/html/bug-texinfo/2003-10/msg00020.html

Ligatures happen automatically in TeX and are a property of the font.

Using slanted typewriter for @var would avoid the need for this workaround,
documented in the manual:

     In the extremely unusual case when an argument name contains ‘--’,
     or another character sequence which is treated specially (*note
     Conventions::), use ‘@code’ around the special characters.  This
     avoids the conversion to typographic en-dashes and em-dashes.

I said in another mail that ideally there would be consistency
in the font for parameters between the definition line and the
definition body.  Using slanted typewriter everywhere for @var would
achieve this.

Using @var on a @deffn line might not do anything if it is in slanted
typewriter anyway, and it would only have an effect in @deftypefn.  (Likewise
for other typed/untyped commands.)

(Incidentally, the manual is unclear on this:

     For example, here is a definition:

          @deffn Command forward-char nchars
          Move point forward @var{nchars} characters.
          @end deffn

     This shows a rather terse definition for a “command” named
     ‘forward-char’ with one argument, NCHARS.

     ‘@deffn’ prints argument names such as NCHARS in slanted type in
     the printed output, because we think of these names as
     metasyntactic variables—they stand for the actual argument values.
     Within the text of the description, however, write an argument name
     explicitly with ‘@var’ to refer to the value of the argument.  In
     the example above, we used ‘@var{nchars}’ in this way.

You can't tell from this whether the typesetting used for nchars is the
same in both locations.  The word "however" links two facts that don't
contrast as the first is about the output and the second about the input.
I know you were reviewing the manual for this kind of thing.)

However, there is a distinction in Info output, where @var puts its
argument in all caps, but this style isn't used by default.  So here's
another idea: in Info output, don't use all caps for the output of @var
if the @var was on a definition line (although maybe that's too disruptive
and not necessary to worry about just now).

> * @def* argument semantics is different for @deftype* and other @def*
>   @deftype* argument is code.  Not slanted, but typewritter.  @var should
>     be used which will lead to upper case in Info, unless something else is
>     used, like @Var{} in the groff manual, which uses @r{@slanted{...}}
>     (though it would be better in my opinion, to use @inline conditionnals
>     to use @var except for Info).
>   other @def* argument is code and metasyntactic variables in term of
>     semantics, slanted, but not upper cased in Info.  Users can use
>     @var explicitely, in that case, in Info the the argument will be upper
>     cased.

I agree with the @deftype* and other @def* distinction, except there is
a problem with slanting all the line including non-alphanumeric characters,
such as commas and brackets.  We may have difficulty parsing this and
accomodating the syntax of many different programming languages.
(However, it would be possible for documents to use @deftype* even
if they didn't have types to avoid parts of the line being formatted
as if they were parameters, if this is undesirable.)

There's an inconsistency between @deftype* and other @def* as
to whether parameters are output in upper case in Info when the
recommended syntax is used.  In typeless @def*, there is no upper
case by default because @var is not necessary to mark paramenters.
However, with @deftype*, the output looks like (from libc manual):

-- Function: int fclose (FILE *STREAM)

     This function causes STREAM to be closed...

Changing this to

-- Function: int fclose (FILE *stream)

     This function causes STREAM to be closed...

might not be bad, although could be undesired by authors.  Anyway, it might
not be important to fix the inconsistency here, as often @deffn and
@deftypefn won't be used together in a manual.


> * in @def* arguments, parentheses/brackets are upright in the default case.
>   For the font there are two possibilities (Gavin?)
>   - typewritter. More logical. Not backward compatible (though it is not
>     typewritter currently probably by chance, because of implementation
>     details)
>   - roman. Backward compatible but less logical.
> 
>   The parentheses font should only matter for manuals such as groff
>   where parentheses/brackes as meta syntactic delimiter and as language
>   delimiters are distinguished.

To be fair, the typewriter font *is* "backwards compatible" with most
documents in that it represents the authors' intentions, and would be an
improvement.  For example, at

https://www.gnu.org/software/libc/manual/html_node/Closing-Streams.html

there is

int fclose (FILE *stream)

which has the HTML code

<em>int</em> <strong>fclose</strong> <em>(FILE *<var>stream</var>)</em>

The effect of <em> is to slant the types, which is unnecessary.  Using
a typewriter font here would be much better.

I say go for the typewriter font on @def* lines.  It's only
inappropriate in a small minority of usage, while the current font
usage is inappropriate for a large majority of usage.

I find it quite confusing and am not sure I fully understand the issues yet.
I feel I am all over the place in this email.  Hopefully it is not too
muddled and sheds some light.