Gavin Smith <gavinsmith0...@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
