Re: @defblock and @defline in texi2any

[Gavin Smith]

On Thu, Feb 23, 2023 at 11:50:35AM +0100, Arsen Arsenović wrote:
> I like this.  I think that tables are quite ergonomic, and so having
> @defblocks look like them should be okay.
> 
> > The next step is to get copiable anchors to work in HTML.  I imagine
> > there should always be a copiable anchor even if there is no index
> > entry, as the definition line is a kind of heading.  Then if there
> > are further index entries, like
> 
> This sounds doable, though I'm a bit worried about what happens if an
> index is added?  I'm thinking it's probably best to always have ids on
> these elements, and never have them depend on indices, so that they
> remain stable (but, of course, one or more indices should still work as
> intended, it's just that none of them should be "promoted" to be the id=
> of the entry itself).

That sounds right.

> >     @defcodeindex fy
> >     @defcodeindex fd
> >
> >     @defblock
> >     @fyindex odd
> >     @defline Funnyction odd (bob, job)
> >     @fdindex argle
> >     @deflinex Funoid argle (bargle, jargle)
> >     description
> >     here
> >     @end defblock
> >
> > the index entries would all refer to the first line.
> 
> This is also something that we should implement for @item[x], so that
> the syntax is not inconsistent.  Current committed practice is for all
> index entries to precede the @item as well as all @itemx, and
> interleaving them like this fails.

If we want to be able to generate this input by some kind of macro
then we need the interleaving to work.

(By the way, one reason we should only use @defline and not some
combination of @defline and @deflinex is so we can generate these
lines with a single macro, not with two macros.)

> I think it's valuable to be able to "abstract" the raw definition lines
> behind a common command, so that we don't have the previous problem of
> repeating frequently used categories, or having to explicitly index
> definitions (like the GCC @defbuiltin example I wrote about recently).
> Did you intend this to be done via macros?

Yes, but we hadn't worked out a good way of doing it.  It seems that
all we really need is a new kind of macro, e.g. @linemacro to define
a new line command with arguments separated by spaces:

    @linemacro defbuiltin symbol rest
    @deffn Builtin \symbol\ \rest\
    @end linemacro

    @linemacro defbuiltinx symbol rest
    @deffnx Builtin \symbol\ \rest\
    @end linemacro

The rule would be that a macro defined with @linemacro was used at the
beginning of a line, absorbed a whole line of input, and produced a whole
number of lines of output.  This seems simple to understand and to
implement in TeX.

Patrice, what do you think of the possibility of such a macro facility
in texi2any?

Separating the macro arguments by spaces rather than commas allows
matching the usage of the symbol in the programming language in question
more closely.  (If spaces are needed in macro arguments, then the
arguments can be surrounded in braces, as is already done for @def*
commands.)

A macro so defined would always take the rest of the line as an argument,
so we avoid the apparent possibility of doing

    @macro defbuiltin {}
    @deffn Builtin
    @end macro

which fails due to technical reasons of the implementation of @macro
in texinfo.tex (any line following the macro usage is treated by TeX as
part of a new line).

If we could add such a macro facility, then it could be used alongside
the new @defblock and @defline for all the purposes we've had in mind, I
believe.  For example:

    @defcodeindex by
    
    @linemacro defbuiltin symbol rest
    @byindex \symbol\
    @defline Builtin \symbol\ \rest\
    @end linemacro

Also, I feel that Texinfo code written with this proposal would be fairly
easy to understand and the purpose and function of @linemacro would be
apparent from reading examples.

(We could also consider if there is a better syntax for variables in
the macro body than \arg\, although it may be better to keep consistency
with @macro in this area.)

I will remove the abortive implementation of "@newdef" from texinfo.tex
and work on this when I have time.