Generalising @def*

[Gavin Smith]

On Thu, Dec 15, 2022 at 09:17:43PM +0000, Gavin Smith wrote:
> I've commited a change for an experimental feature to allow this.  This
> is in texinfo.tex version 2022-12-15.20 (in git).
> 
> Example code:
> 
>     \input texinfo
>     
>     @defcodeindex xy
>     
>     
>     @defun Foo (bar)@useindex{xy}
>     foobar
>     @end defun
>     
>     @printindex xy
>     
>     @bye
> 
> This puts the index entry in the 'xy' index rather than the
> 'fn' index.
> 
> This has not been implemented in texi2any at all and the syntax, name
> of the @useindex command, etc. could all change, or the feature might
> not be implemented at all if there is no use for it.  Please experiment
> and report what would be useful.

I'm still not really happy with this syntax.  @useindex should occur
at the end of the line, which is not very obvious, and it's not clear
what happens to whitespace before or after it.

The @useindex syntax above is a kind of "named argument" or HTML-style
attribute.  The only precedent for this in Texinfo may be the in-index
commands, like @sortas.  However, the index commands are pretty complicated
to implement with interactions with @subentry, so may be a special case
that shouldn't be generalised.

(@caption also provides a sort of named argument to the @float command
(in an XML-like syntax it would be like <float caption="...">),
but @float is a block command, whereas additional named arguments
or attributes need to be on the line, to allow them to be passed
differently to e.g. @deffn and @deffnx in a single block.)

I wonder if it would be better to make it simply a different command,
like

  @defunext xy, Foo (bar)

which takes an extra argument.  This might be more in line with existing
Texinfo syntax.  (But would double the number of @def* commands, which
are already very numerous.)

This would be fine provided we didn't need to add more
arguments in the future...  So perhaps we need new commands
which are as general as they can possibly be.

We should also resolve the question, at last, of how users should create
their own def command, which is something that several people have wanted
to do in the past.  Using @macro for this isn't really good enough, as it's
hard for the user to use properly.

We could have arguments saying whether the definition line should
be in a typewriter font (like @deftypefn) or a slanted roman font
(like @deffn) by default; and whether there is a type before the
indexed symbol (like @deftypefn).

Imaginary use case:

  @newdef defbuiltin = typed, tt, Built-in Function, fn

which would define @defbuiltin, @defbuiltinx and @end defbuiltin.

Imaginary syntax:

  @newdef COMMAND = (typed|untyped), (tt|slanted), CATEGORY, INDEX

Maybe also an argument for the font style of the indexed symbol itself?

There could be behind the scenes commands like @def making @defbuiltin
equivalent to '@def defbuiltin, typed, tt, Built-in Function, fn'.

There may be other possibilities, such as using @macro in some way, e.g.
using a @macro definition to define a new definition command.

The groff manual does things like

  @macro Defstr{name, package}
  @deffn String @t{\\*[\name\]}
  @stindex \name\ @r{[}\package\@r{]}
  @c
  @end macro

which puts the text "package" in the index, even though it doesn't
actually appear in the text of the @deffn line itself.  Hence, using
a @macro would provide more flexibility.  Maybe a macro could be
"blessed" into a definition command somehow?

  @newdef defstr = Defstr

providing @defstr, @defstrx and @end defstr.  The @Defstr would provide
the printing of the definition line and indexing and the new commands would
take care of the indented block.

Such macros could take advantage of new @def command(s) that didn't make
index entries.

Comments and ideas sought.  I hope we can come up with a good and practical
plan that will serve all relevant use cases now and in the future.