Re: @defblock and @defline in texi2any

[Arsen Arsenović]

Patrice Dumas <pertusus@free.fr> writes:

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

Yes - I agree they should associate with the next definition.  I was
getting at adjusting tables to also be able to handle this kind of
interleaving; currently

  @table @code
  @cindex foo
  @item foo
  @cindex foo2
  @itemx foo2
  
  foos!
  @end table

produces the wrong result (texi2any takes the @cindex foo2 as item text
rather than as something associated with the @itemx).  If we introduce
the interleaving above, we should also support it here properly (but, we
might still choose to bubble to the first item, to immitate the
index-first-item-second practice we established, which is also
potentially something to do for @[fv]table).

(side note - while testing the example above, I noticed that makeinfo
d6678a7d0fe739aa010717b4bd0515e6256510f0 seems to be unable to read
stdin properly - investigating later, posting so that I do not forget.
try pasting the above into makeinfo --html -o - -, then into a file, I
get:
You found a bug: Non empty last input at the end
Additional information:
context_stack: ()
Died at /usr/share/texinfo/Texinfo/ParserNonXS.pm line 6847.)

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

AFAIU (and I haven't finished my TeXbook read, so, grain of salt etc),
something like

  @macro foo {}
  @cindex
  @end macro

  @foo a b c

... would (in texinfo.tex) fail to produce an index, since the macro
invocation terminates the line and 'a b c' is treated as a new line.
This actually appears to be a discrepancy between texi2any and
texinfo.tex currently.

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

I believe the intention here was a generalization of that syntax, which
is why the proposal involves similar syntax.

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

+1.  I'm of the opinion that this can only introduce confusion.

-- 
Arsen Arsenović

signature.asc
Description: PGP signature