Re: rethinking @def*

[Gavin Smith]

On Tue, Jul 26, 2022 at 04:58:10PM +0000, Werner LEMBERG wrote:
> The only way to introduce a new behaviour for a broken function 'bar'
> is to implement a new function 'bar2', declaring the old function
> 'bar' as obsolete.  I think that exactly such an approach is
> appropriate for texinfo functions/macros that haven't changed for
> decades.

There have been changes to @def formatting in the past.  There is a
ChangeLog entry

2003-11-23  Karl Berry  <karl@gnu.org>

        * doc/texinfo.tex: doc fix for multitable.
        * util/gendocs.sh: docbook support, from Simon Josefsson.

        * doc/texinfo.tex (\defttsl): new font.
        (\df): set ttsl too.
        (\deffngeneral,\deftypefngeneral,\deftypecvgeneral,
         \deftypheader): call \ampdefunargs or \normaldefunargs.
        (\normaldefunargs): new macro, typesetting defun
         args in ttsl (instead of sl).
        (\ampdefunargs): treat & specially and then call \normaldefunargs.
        (\defname): typeset defun name in tt (instead of bf).

        * doc/texinfo.tex: uniformly comment out eol with {% at macro
        starts.

There are also some comments in texinfo.tex which likely come from the
same time:

    % defun fonts. We use typewriter by default (used to be bold) because:
    % . we're printing identifiers, they should be in tt in principle.
    % . in languages with many accents, such as Czech or French, it's
    %   common to leave accents off identifiers.  The result looks ok in
    %   tt, but exceedingly strange in rm.
    % . we don't want -- and --- to be treated as ligatures.
    % . this still does not fix the ?` and !` ligatures, but so far no
    %   one has made identifiers using them :).


% Print arguments in slanted roman (not ttsl), inconsistently with using
% tt for the name.  This is because literal text is sometimes needed in
% the argument list (groff manual), and ttsl and tt are not very
% distinguishable.  Prevent hyphenation at `-' chars.
%
\def\defunargs#1{%

There was some discussion around this, see this message and others:

https://lists.gnu.org/archive/html/bug-texinfo/2003-10/msg00020.html
> I propose to make the @def... commands do an implicit @code, more or
> less.  The principal change would be the names being printed in
> typewriter (and typewriter slanted for arguments, I guess).  We'd get
> ligature suppression for free, then.
> 
> This seems more logical than the roman fonts (bold and slanted) now
> being used, although the roman fonts are prettier and take less space.


A more recent change was in 2015 where there was a slight change to the
size of the font.  This change was also mentioned in the NEWS file:

2015-09-20  Gavin Smith  <gavinsmith0123@gmail.com>

        * doc/texinfo.tex (\requireopenindexfile): Use \immediate before 
        \openout.
        (\df): Also define a \defsl font in addition to \defttsl, so we get
        parameters in @deffn lines the same size as the name of the function.   

        (\domakedefun): Comment changed.

It's not the case that we have to preserve exactly the same output image
for a given input.  There can be minor changes.  Obviously, this needs
to done with concern for how it's being used.

It's possible that there is history I'm missing here, although in principle
it shouldn't really matter, as long as we check what existing Texinfo
manuals are doing and make sure not to break them.

The comment from 2003 said that the groff manual needed Roman type in
@def* line output.  Examples from the groff manual would be one of the
first things I would look at, and this might help to move this conversation
forward more than discussions of abstract principles of backwards
compatibility.