Re: rethinking @def*

[Patrice Dumas]

On Tue, Jul 26, 2022 at 01:53:35PM +0100, Gavin Smith wrote:
> > 
> > There is one mention in the manual that gives some semantic meaning to
> > the whole @def* 'argument', it is "we think of these names as metasyntactic
> > variables".  But in other places, the argument is not metasyntactic
> > variables, simply slanted and the documentation can be convoluted and
> > vague for some cases.  Here is an example (admitedly the worst case):
> > 
> >  Since in typed languages, the actual names of the arguments are typically
> >  scattered among data type names and keywords, Texinfo cannot find them 
> > without
> >  help. You can either (a) write everything as straight text, and it will be 
> > printed
> >  in slanted type; (b) use @var for the variable names, which will uppercase 
> > the
> >  variable names in Info and use the slanted typewriter font in printed 
> > output;
> >  (c) use @var for the variable names and @code for the type names and 
> > keywords,
> >  which will be dutifully obeyed.
> > 
> > As can be seen here, the semantic is lost (printed in slanted type),
> > @var is used as a markup and leads to non consistent formatting for a
> > metasyntactical variable, @code will be "dutifully obeyed" which
> > does not say much and actually @code puts the argument in code context
> > (-- are kept as is), in typewriter and not slanted.
> 
> I don't follow what you mean by "the semantic is lost".

Above, the @def* 'argument' is reported to be semantically
metasyntactic variables "we think of these names as metasyntactic
variables".  But here, it is not the case anymore, it becomes
"it will be printed in slanted type", that's why I say that the
semantics are lost, it has become purely formatting.  That is logical,
because in @deftype*, the 'argument' is a mix of metasyntactic
variables and regular code identifiers.  What I propose is to
be clearer that there is no semantic interpretation of @deftype*
'argument' (except that it is code).

> > Here is a proposal:
> > 1) consider that @def* argument is always, semantically, code.  It
> >    is code because functions, methods, types ... arguments are code.
> >    As a consequence, @code should not have any effect on the formatting,
> >    but could still be used to mark text (redundantly).
> 
> This would probably be a good idea.  There's usually not much use for
> non-code text in @def* lines, apart from a possible category.

Note that I do not propose to change the formatting of the category on
the @def* line, only of the 'argument'.

> I checked the output of the following four usages with texinfo.tex:
> 
> @deftypefn {Library Function} int foobar @
> (int foo, float bar)
> ...
> @end deftypefn
> 
> @deftypefn {Library Function} int foobar @
> (int @var{foo}, float @var{bar})
> ...
> @end deftypefn
> 
> @deftypefn {Library Function} @code{int} foobar @
> (@code{int} @var{foo}, @code{float} @var{bar})
> ...
> @end deftypefn
> 
> @deftypefn {Library Function} int foobar @
> @code{(int @var{foo}, float @var{bar})}
> ...
> @end deftypefn
> 
> and only the last one uses a fixed width font consistently, including for
> '(', ',' and ')'.
> 
> Ideally, the second option here should have good results and the first
> one should only fail to mark the parameters 'foo' and 'bar'.

Agreed.

> > 2) distinguish @deftypefn (and @deftypefun), @deftypevr (and
> >    @deftypevar), @deftypeop and @deftypemethod argument semantic
> >    from other @def* argument semantic.
> >    * for @deftype* @-commands, the argument has no semantic
> >      (other than being code), bacause plain code and metasyntactic
> >      variables (in code) are mixed.
> 
> I don't know what you mean by "no semantic".  "Semantic" is an adjective,
> not a noun.

maybe I mean "no semantic interpretation", or "no semantic meaning",
or maybe "no semantics", or more precisely "no additional semantics,
other than being in code".  (in french, sémantique is both a noun and an
adjective...).

> >    * for the other @-commands, the argument is considered to be
> >      metasyntactic variable (in code as per rule 1)).
> > 
> 
> @var should used to wrap function arguments or parameters.  This is a more
> straightforward definition than whatever "metasyntactic variables"
> are.  @var can be used for metasyntactic variables too, if they occur
> elsewhere outside the context of a @def* line.
> 
> I'm not sure what you mean by the "other @-commands"; is it just @var or
> are there other commands you had in mind?

Actually , what I meant was
    * for the other @def* @-commands, the argument is considered to be
      metasyntactic variable (in code as per rule 1)).

If I understand you correctly, but I may be misinterpreting, you would
propose something even simpler and somewhat less backward incompatible,
that there is no semantics other than being in code for all the @def*
'argument', such that @var{} would need to be explicitly set.  So for
example

 @defspec foobar (var [from to [inc]]) body@dots{}
would need to be rewritten as
 @defspec foobar (@var{var} [@var{from} @var{too} [@var{inc}]]) @var{body} 
@dots{}

But I may be misinterpreting what you meant.

> > could be rewritten as:
> > 
> >  @defspec foobar @r{(}var [from to [inc]]@r{)} body@dots{}
> > 
> > The parentheses will be non slanted, roman font, the remaining
> > will be slanted and typewriter, including [].
> 
> What would be the point of having Roman font parentheses, as the parentheses
> are part of the syntax of the computer language?

No point, I thought that it was what Texinfo TeX does, but maybe the
parentheses are typewriter.

> >  @defun apply function &rest arguments
> > 
> > could be rewritten:
> > 
> >  @defun apply function @r{@strong{&rest}} arguments
> 
> That's probably ok apart from the @strong which isn't to be encouraged.  If
> anything is marked strong, it should be the symbol being defined, 'apply'.
> Leaving &rest as-is may also be OK as this may mirror how the function is
> defined in the Lisp language.

Ok.

> > Formatting of 'arguments' will be slanted typewriter, '&rest' in bold roman.
> > Alternatively, it could be rewritten as:
> > 
> >  @defun apply function @strong{&rest} arguments
> > 
> > and '&rest' would be in slanted bold typewriter, which is not always
> > much different from normal (non bold) slanted typewriter, depending on
> > the font.
> 
> Side issue but slanted bold typewriter is likely not available as a font
> and font commands in Texinfo don't (usually?) nest, so @strong would switch
> to a bold Roman font regardless of the current style.

Ok.  I think that in LaTeX it could be slanted bold typewriter, at least 
in some fonts, but we do not need to specify that precisely anyway.

> > Formatting would be: int and float will not be slanted, in typewriter,
> > same for parentheses. 'foo' and 'bar' would be slanted typewriter.
> 
> I'd add that 'foobar' could optionally be in bold typewriter, if such a
> font is available.

foobar is not in the 'argument' part of the @deftype*, it is the name.
It could be bold typewriter, why not, but I think that it is not
an issue, as there is no inconsistencies nor ill defined semantics.
We could still change the formatting.

-- 
Pat