Re: rethinking @def*

[pertusus]

On Wed, Jul 27, 2022 at 01:32:50PM +0100, Gavin Smith wrote:
> On Wed, Jul 27, 2022 at 11:29:20AM +0200, pertusus@free.fr wrote:
> > Hello,
> > 
> 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.)

Agreed.

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

I think that this is too complicated, and parentheses can also be
"metasyntactic", to show groupings of parameters.

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

It seems to me that separator characters should in general be upright
and in code.  But I do not think that we should handle automatically
many special cases, if a user want a specific presentation, she can use
explicit @-commands formatting.  So I would propose that, with the
exception of parentheses and brackets, we leave the other separators in
the same font as the surrounding text.  And document what the user can
do with font changing @-commands to change that.

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

If @var can be in code, slanted typewriter is probably better.  It seems
to me to be similar with one of my proposals, if the parentheses and
brackets are always upright.

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

Ok.

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

That's indeed another way to do it.  I do not have an opinion on that.

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

I don't think that we should do that, unless there is are user asking
for it.  In the groff manual a macro is used for that, seems ok to me
to leave it to the manual writers to do that kind of specific
formatting.

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

As I said above, let's have a rule for brackets and parentheses, but for
other separators, lets leave it to the writers to set their fonts as
they see fit, in line with the semantics of each language.

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

I would not do that.  It breaks the semantics of the Texinfo language.
A better workaround would to use @r{@code{...}}, in my opinion.

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

It seems to me that, for now, leaving the options for the user to use
an explicit @var{} on @def* (non @deftyp*) or not, allows to leave both
options open.  On @deftype*, we could document that if a user wants to
have non uppercased parameters in Info, she can use a macro like

@macro lcvar{input}
@inlinefmtifelse{info, /input/, @var{/input/}}
@end macro

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

The main issue is that it is not backward compatible for a manual like
the groff manual in which the distinction is important.  But if it is
your decision, let it be.

Note that the package I plan to use for LaTeX, embrac, uses the
surrounding font (in slanted typewriter, the parenthesis will be upright
typewriter), which is consistent with typewriter parenthesis in the
case that seems to be favoured of having typewriter for all the @def*
arguments.

Another option would be to say explicitly that it is format dependant,
and that the only guarantee is that braces and parentheses are upright,
and if the user want a specific font he should set it especially, with
@r{, @r{@code{, @r{@slanted{ or @r{@code{@slanted{.

I tried to find anything on the web to have upright parentheses for HTML
with CSS, but did not find anything.  So it could even be documented
that even having upright parentheses and brackets depends on the format,
such that an explicit formatting is needed to have the same output in
every output format.


I will do the LaTeX formatting in line with what I have understood
should be implemented and see if it looks good/similar for some manuals.
I will look at the result in the texinfo, groff, libc and elisp manuals.

-- 
Pat