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
