Re: rethinking @def*

[pertusus]

On Sun, Jul 31, 2022 at 02:38:17PM +0100, Gavin Smith wrote:
> 
> It could be tempting to use @deftype* for a case like this, if
> @deftype* is not slanted, even though there are no types.
> 
> In fact, I agree with making @deftype* not slanted, and we should
> also allow in the documentation that this could be used even when
> there are no types.
> 
> @deftypefun {} wilcox.test (@var{x}, @var{y} = NULL,@
>   @var{alternative} = c("two.sided", "less", "greater"),@
>   @var{mu} = 0, @var{paired} = FALSE, @var{exact} = NULL, @var{correct} = 
> TRUE,@
>   @var{conf.int} = FALSE, @var{conf.level} = 0.95,@
>   @var{tol.root} = 1e-4, @var{digits.rank} = Inf, @var{@dots{}})
> 
> It's not clear how @defun would be used for this example without specifying
> fonts styles explicity with excessive use of @code{...} or @r{@code{...}}.
> 
> I know you said that this was an abuse of @deftype*, but if we documented
> that
> 
> @deffun func arguments
> 
> was equivalent to
> 
> @deftypefun {} func @var{arguments}
> 
> then this should be quite clear.  This is not an equivalence that currently
> exists but we could try to make it exist if we agree.

I think that we can make it logical by not insisting, in the @deftype* 
documentation, on the type before the name, but on the idea that this is
for calls with no specific semantics of the arguments.  We could say
something like 

"originally for typed languages, where types and
metasyntactical variables are mixed, hence the name, but it applies to
named arguments where identifier are mixed with meta syntactical
variables, or even to functions which argument are not meta syntactical
variables only".

"It is possible to specify a type for the function, before the
function name, or leave it empty, in that case tere is no type for
the whole function".

> When we document the use of @var on a def line, we should allow both
> for literal substitution of arguments in the text of the definition line, as
> in the groff manual, and merely for marking parameter names.  The following
> C function declaration should show what I mean:
> 
> int foo (int a, int b)
> 
> This is called like "foo (3, 4)", not like "int foo (int 3, int 4)".
> 
> The example from R above is also in the same category as marking variable
> names.

I do not really get the point, but I do not think that it is important.

> > > output of @var outside this line, which could be used in the body of
> > > the definition following the definition line to refer to an argument.
> > > Granted, the output of @var could be changed to slanted typewriter
> > > everywhere to get consistency, but this is an extra change to Texinfo
> > > which somebody has already expressed opposition to.
> > 
> > To me, and based on the printed outputs, having @var slanted and
> > typewriter in @def* line, and slanted roman in the text is not a
> > problem.  The difference between slanted typewriter and slanted roman is
> > not so important, and even if the difference was more marked, it would
> > not be an issue, as @def* function calls are code and general text is
> > not.  It is also the current formatting.
> 
> I feel that changing the default for (typeless) @deffn from slanted
> roman to slanted typewriter is too much of a change.  We could still
> clear up the semantic mess around @def* commands that you noticed without
> changing this font style.

I agree.  I would have preferred to got to typewriter here too, as code,
but it can be backward compatible too, and, as you say a matter of
style.  We should say that it is unreliable, however, something like

"considered as in @var, and formatted slanted.  It should be code, so
it would have been logical to format it in a typewriter font too,
consistently with the @def* name, but we follow the previous stylistic choice
of being in roman font, which has the advantage of being more similar
to the formatting of @var in main text.  You should not rely upon a
specific formatting, however, if you want to be sure that the arguments
are formatted in roman slanted, you should mark them with
@r{@slanted{}}, or if you want to have the same formatting than @var in
main text (which would be different from slanted in Info), use
@r{@var{}}."

> Changing the output for @deftype* only, and not typeless @def*, would
> be less disruptive and reduce the risk of breaking documents.
> 
> > > The only difference between @deftypefn and @deffn, as far as the Texinfo
> > > processors would be concerned, would be that @deftypefn had an extra
> > > "data-type" argument before the "name".  The formatting of the arguments
> > > would be the same.
> > 
> > Again, to me the samantics are different, which makes a different
> > formatting not only correct, but even better in my opinion.  In
> > texi2any, the additional code to distinguish those two cases is very
> > small.  I do not believe that in Texinfo TeX it would be especially hard
> > either, though I can not really judge.
> 
> I've got a different proposal now for the difference between
> @deftypefn and @deffn (described above).

Ok.

-- 
Pat