Re: @defblock and @defline in texi2any

[Patrice Dumas]

On Mon, Feb 27, 2023 at 10:14:17PM +0000, Gavin Smith wrote:
> 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.

I do not fully understand why there would be anchors/id associated to
@defline if they cannot be the target of references/menu entry/node
directions, and are not a location for an index entry either.

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

It seems to me that the index entries should be associated to the next
or previous @defline, not necessarily to the first one.  For example in

@defblock
@defline Funnyction odd (bob, job)
@fdindex argle
@deflinex Funoid argle (bargle, jargle)
@fdindex jargle
description
here
@end defblock

It seems to me that the index entry corresponding to '@fdindex jargle'
should be associated to @deflinex Funoid and not to @defline Funnyction,
while '@fdindex argle' could be associated to @defline Funnyction (which
could mean have the anchor moved to before @defline Funnyction).

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

I do not see what is different from regular @macro definition except for
the formal arguments to be separated by spaces.  I do not see
an interest to use a different way to pass formal args.  But maybe the
difference you want is for the arguments of the call to be separated by
spaces/braced, for example here

@defbuiltin {My builtin} a remaining, arg

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

I see no advantage of forcing the linemacro to be called at the
beginning of a line.  To me the only difference should be that the
arguments are obtained like @def* lines, but the remaining (definition
of macro in particular) should be the same as for regular @macro.

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

Having a macro call similar to @def* line would probably be ok to
implement.  It would not be the same as a true @def argument, the
@-commands would not be considered as such, only braces would be checked
to verify that they are balanced, and @ would protect an end of line
(like what is done for the parsing of user-defined macro call).

However, I am not fully convinced that it is such a good idea, as the
@def* syntax is quite different from the remaining of Texinfo.  Adding
more of this syntax is not necessarily good.

Maybe and intermediary solution would be to accept protection in {} in
the special macro call such that implicit quoting of , can be done
easily, and the first level {} would be removed.  So, for example with a
definition like 

  @linemacro defbuiltinx {symbol, rest}

the macro could be called as

@defbuiltinx{My builtin, a {remaining, arg}}

@defbuiltinx { {Some, other}, {remaining, ....} }

This is not perfect, as this forces to have double {} to get braced
arguments in the final output.

This is also most likely a difficulty in what you propose.  For example
for

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

For @byindex, \symbol\ should not be in braces.  But on the @defline
line it may need to.  Therefore a call like

@defbuiltin {My, symbol} and, rest

would lead to
@byindex My, symbol
@defline Builtin My, symbol and, rest
which is ok for @byindex, but not for @defline.  If the call is like

@defbuiltin {{My, symbol}} and, rest

It would lead to
@byindex {My, symbol}
@defline Builtin {My, symbol} and, rest
which is ok for @defline but not for @byindex.

So, it is not clear that all the situations are handled.

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

I did not get that part.

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

There is no point in doing something different in this area, in my
opinion.

-- 
Pat