Re: rethinking @def*

[pertusus]

On Fri, Jul 29, 2022 at 11:18:20PM +0100, Gavin Smith wrote:
> On Fri, Jul 29, 2022 at 10:54:35PM +0200, pertusus@free.fr wrote:
> > This looks good to me for now, and maybe the TeX output will change
> > in after @def* are considered as code, and @deftype* are not slanted
> > anymore.
> 
> I'm having second thoughts about @deftype* not being slanted any more,
> I'm afraid.

The proposed difference is not only non slanted, but typewriter and non
slanted, and for other @def*, typewriter and slanted.

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

>  This would
> confuse any explanation we wanted to give on how to specify the formatting
> of commas or other characters.

I do not think so.  If the setup is logical, the explanation will not be
difficult, even if it means partially different explanations for
@deftype* and other @def* commands.

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

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

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

-- 
Pat