Re: Generalising @def*

[Arsen Arsenović]

Evening Gavin,

Gavin Smith <gavinsmith0123@gmail.com> writes:

> 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

Consider also a language like Poke, which does not have the usual
type-name-args syntax, instead opting for ``fun name = (args) type:
{...}'' for functions, and similarly, ``method name = (args) type:
{...}'' for methods.  It makes me think that this command should somehow
(perhaps via a macro-like body) describe the format of the "definition
line".

It is very important for language documentation, I feel, to establish
typesetting convention that is close to what the language looks like.

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

This seems reasonable to me.

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

Ah!  I see you've thought about that too.  This might be nicer than my
original thought of simply attaching a body below the @newdef.  I'm
curious, what would the definition of Defstr look like?  Especially
considering @deffn already has some meaning, which might be
inappropriate for some cases (like the Poke example above).

In texinfo.tex, there appears to be a helper for defining header lines,
which is probably desirable to expose in some capacity for use in
combination with @newdef, though it should not impose much restriction
on the format, probably.

As an example, I wrote this documentation recently:

  @deftypefun String_Tokenizer strtok (string @var{a})
  Creates a new tokenizer for the string @var{a}, initially on the zero
  position.
  @end deftypefun

which renders as:

   -- Function: String_Tokenizer strtok (string A)
       Creates a new tokenizer for the string A, initially on the zero
       position.

... but, in the Poke language, that ought to be:

   -- Function: fun strtok = (string A) String_Tokenizer:
       Creates a new tokenizer for the string A, initially on the zero
       position.

... with appropriately shuffled formatting.  Something like this might
do the trick:

  @macro Pokefunheader{category, type, name, args}
  @defheaderline {\category\} @code{fun @b{\name\} = \args\ \type\:}
  @end macro

  @newdef pokefun = Pokefunheader, Poke Function, fn

... bar my possibly failed attempts to use macros correctly.

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

I like the direction here.  I posted just a few quick remarks, and I
haven't had proper opportunity to consider options for the syntax, or
what would fall into the variables that need to be abstracted for the
general case to work, though, so my thoughts are incomplete.

Thanks, have a great night.
-- 
Arsen Arsenović

signature.asc
Description: PGP signature