rethinking @def*

[Patrice Dumas]

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.


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).
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.
   * for the other @-commands, the argument is considered to be
     metasyntactic variable (in code as per rule 1)).

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 [].
Alternatively, it could be:

 @defspec foobar @r{@code{(}}var [from to [inc]]@r{@code{)}} body@dots{}

The parentheses will be non slanted, typewriter font, the remaining
will be slanted and typewriter, including [].


 @defun apply function &rest arguments

could be rewritten:

 @defun apply function @r{@strong{&rest}} arguments

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.


 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})

does not need to be rewritten.
Formatting would be: int and float will not be slanted, in typewriter,
same for parentheses. 'foo' and 'bar' would be slanted typewriter.


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


-- 
Pat