Re: rethinking @def*

[Gavin Smith]

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 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 we have been discussing, the user needs to be have control over what
styles of font are used for various characters on a definition line.
I expect that we should document the current treatment of
[, ], (, and ) and how to override the default output of these (e.g. by
using commands like @r, @code or @t).

I am concerned that if @deffn is output as slanted by default, and
@deftypefn is not, then this overshadows the essential difference
between these commands.  For example, it would cause commas and other
characters to be output as non-slanted in @deftypefn.  This would
confuse any explanation we wanted to give on how to specify the formatting
of commas or other characters.

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

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.

Perhaps it's something I should have thought about sooner - it could have
been the discussion on syntactic versus metasyntactic characters that
changed my thinking.

Sorry to add to the volume of mail on this topic.  I'm planning on reading
through previous mail again to see if there's anything I missed.

> To have upright [ in \textsl{\texttt, I had to do somewhat complex code.
> I'll try to contact embrac maintainer to report what I had to do.
> 
> -- 
> Pat