Re: rethinking @def*

[Gavin Smith]

On Sun, Jul 31, 2022 at 10:42:02AM +0200, pertusus@free.fr wrote:
> > The manual suggests marking variables in @deftype like
> > 
> >  @deftypefn {Library Function} int foobar @
> >     (int @var{foo}, float @var{bar})
> > 
> > However, there's an alternative that is not documented, which is to
> > mark the types instead, and not the variables:
> > 
> >  @deftypefn {Library Function} int foobar @
> >      (@code{int} foo, @code{float} bar)
> > 
> > This usage is just as simple as the first.  (@t could replace @code here.)
> 
> As simple, but, in my opinion, less logical, for two reasons.  The
> first is that the argument is code, so marking code is redundant.  The
> second one is that what is special are the metasyntactic variables, and
> with that setup they are not marked as such.

I can see that it looks wrong to put @code inside what looks like computer
code already.

>  There is another reason,
> but you probably are not convinced, as I have stated that argument many
> times now, is that semantically, the @deftyp* arguments have no reason
> to be metasyntactic variables, as the @deftype* arguments are a mixture
> of types and metasyntactic variables.
> 
> > For example, it would cause commas and other
> > characters to be output as non-slanted in @deftypefn.
> 
> I do not think that this is very important.  For parentheses and
> brackets, there is a visible effect, for other symbols, much less.
> But this is not a very important argument in my opinion.  What matters
> is to get it right in the default case iin term of semantics, and
> documenting how to mark differently.

Whether commas are slanted or not is an important difference, and doesn't
just apply to commas.  Macro languages could use arbitrary separators.

In this message:

https://lists.gnu.org/archive/html/bug-texinfo/2003-11/msg00058.html

it was apostrophes that were literal.  

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.

It could be just about any type of text that should be unslanted,
depending on the programming language.  In a language with named
function arguments, default arguments may be unslanted.  For example,
in the R language.

https://stat.ethz.ch/R-manual/R-devel/library/stats/html/wilcox.test.html

shows the following prototype:


wilcox.test(x, y = NULL,
            alternative = c("two.sided", "less", "greater"),
            mu = 0, paired = FALSE, exact = NULL, correct = TRUE,
            conf.int = FALSE, conf.level = 0.95,
            tol.root = 1e-4, digits.rank = Inf, ...)

(An example of this being used is

wilcox.test(4:2, 3:1, paired=TRUE)

Here x has the value 4:2, y has the value 3:1, and paired has the value
TRUE.)

If we changed @deftypefn to output as unslanted code by
default, then it would be tempting to use @deftypefn like

@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{}})

to avoid slanting the default values.  (Here @deftypefun uses
a default category, and the {} after the @deftypefun specifies an
empty type.)  (@w could also be used in this example to avoid infelicitous
line breaks.)

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.

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 also feel that the second usage above is to be preferred due to the
> > treatment of @var{} on a @def* line, in that it outputs parameter
> > names in a slanted roman, non-typewriter font, which matches the
> 
> I thought that we agreed that all the @def* arguments were considered as
> code?  Even if the arguments part of @deftype* @-commands line is
> slanted (with metasyntactic variables semantics), it seems to me that
> it should be code too.  Could simply be
> 
> "In contrast with @defun, the argument is not considered metasyntactic
> variable, as it mixes types and metasyntactic variables.  Therefore,
> with @deftypefun, all the meta-syntactic variables should be marked with
> @var."

That's a fine explanation.

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

Use of a roman font could be thought as part of the style of the
formatting, and not the semantics of the language.  (We could decide
whether sequences like --, --- should be ligaturised, but I expect
we could implement whatever we decided, even if a roman font was used.)

In the message from Werner in 2003:

https://lists.gnu.org/archive/html/bug-texinfo/2003-11/msg00058.html

there was a complaint that the recent change to slanted typewriter had made
arguments less distinctive, which led to the change being reverted.

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