Re: rethinking @def*

[Gavin Smith]

@def* commands could do with a lot of development, as seen in the TODO
file.

On Tue, Jul 26, 2022 at 11:57:12AM +0200, Patrice Dumas wrote:
> Hello,
> 
> As I try to implement @def* commands better in LaTeX output, I have read
> the TeX code and the manual in more detail, and I have come to the
> conclusion that the design of the @def* 'argument' handling is flawed.
> To me there are two flaws.  The first one is that the semantic context
> of @def* 'argument' formatting is not well defined.  The second one is
> that TeX imposes specific and inconsistent formatting (sometime
> weird) to the writer.  In particular, argument is considered as
> (slanted) text and not code, metasyntactical variables in argument are
> put in typewriter font, parentheses and [] are considered as normal (non
> slanted) text, specially marked code in argument is non slanted, and
> presented as a 'trick' to have the argument formatted as code, and & and
> the following word are bold non slanted.
> 
> I think that this is wrong to impose such formatting that is not based
> on the semantic of the @def* 'argument', and in most cases is not
> consistent with the normal semantic meaning and formatting of the
> @-commands such as @var or @code.
> 
> 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".


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

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

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

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

> The formatting would derive naturally from the semantics.  That proposal
> corresponds better to the (b) option in the excerpt from the manual.
> Normally, with such rules, the documentation should also be easier to
> write and understand.
> 
> 
> Some examples on how to get the previous or more consistent results:
> 
>  @defspec foobar (var [from to [inc]]) body@dots{}
> 
> 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?

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

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

> 
>  @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
> 
> does not need to be rewritten.

Yes, that would be the ideal input format.

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

> 
>  @deftypefn stacks private push (@var{s}:in out stack; @var{n}:in integer)
> 
> does not need to be rewritten (but I am not sure, I do not know Ada).
> Formatting would be: s and n slanted typewriter, the remaining not
> slanted, but typewriter.

That sounds OK.