Re: Generalising @def*

[Gavin Smith]

On Tue, Jan 31, 2023 at 09:42:20PM +0100, Arsen Arsenović wrote:
> 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.

Yes, I agree.

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

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

Yes, we couldn't use @deffn.  I am thinking perhaps just @def which
would be like the \defheaderline macro that you've already discovered
in texinfo.tex.  It would look like

  @macro Defstr{name, package}
  @stindex \name\ @r{[}\package\@r{]}
  @def String, @t{\\*[\name\]}
  @end macro
  
  @newdef defstr = Defstr

The first argument to @def would give the category and the second
the prototype or declaration of the symbol.

One complication is that e.g. @defstr would be a block command,
whereas @defstrx would just be a line command.  A new command @def
for printing the definition line couldn't be a block command as it
wouldn't work for @defstrx.  The same @macro would be used for
both of them.  I imagine that there would be another type of block
like @defblock ... @end defblock which could contain the @def lines,
which would allow the same formatting without the use of @macro.

This would make the two following excerpts equivalent:

  @defstr somename, some package
  @defstrx somename2, some package2
  text here
  @end defstr

and

  @defblock
  @stindex \somename\ @r{[}\package\@r{]}
  @def String, @t{\\*[\somename\]}
  @stindex \somename2\ @r{[}\package2\@r{]}
  @def String, @t{\\*[\somename2\]}
  text here
  @end defblock


This seems to be shaping up into an actionable proposal.

I guess we should consider at the same time if there are other
contexts where users might want to define new block commands.


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

It would be good to find manuals like the groff or gcc manuals which
do things like defining their own @def-style commands and check what
they need.