Re: @defblock and @defline in texi2any

[Arsen Arsenović]

Gavin Smith <gavinsmith0123@gmail.com> writes:

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

This proposal seems reasonable to me, at least from a user-facing
standpoint (though I've not read Patrices responses yet).

> (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 agree that it's probably best to stay consistent.

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

signature.asc
Description: PGP signature