Re: @defblock and @defline in texi2any

[Arsen Arsenović]

Hi Gavin,

Sorry for the late reply - I'm slowly coming out of the busy season now
:-)

Thanks for your work on this.

Gavin Smith <gavinsmith0123@gmail.com> writes:

> On Sat, Feb 11, 2023 at 08:16:18PM +0000, Gavin Smith wrote:
>> OK, I know that dynamically updating command lists or handling
>> command macro expansion can add a lot of complexity to texi2any.
>> The next step now is probably to add @defblock to texi2any.
>
> (switching to bug-texinfo which is a more appropriate mailing list)
>
> I've added a basic implementation of this.
>
> The input can look like
>
>     @defblock
>     @defline Funnyction odd (bob, job)
>     @deflinex Funoid argle (bargle, jargle)
>     description
>     here
>     @end defblock
>
> The output is as you would expect and I've tested this basic case
> with Info, LaTeX, DocBook, HTML and Texinfo-XML formats.  There are
> no index entries made by default.

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

>     @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.  I had half a patch to fix that last
year, but I'm unsure where that is by this point, but the transform
should be simple enough either way (ideally, we should support both
styles, and have them result in the same parse, I think).

> It's similar to copiable anchors in @table, and would be
> implemented in a similar way.  (For example, with a function like
> 'relate_index_entries_to_table_items_in_tree' in Texinfo/Common.pm
> to set 'entry_associated_element' for the index commands, and use
> this in Texinfo/Convert/HTML.pm in '_prepare_index_entries' or other
> functions.)
>
> Does this all sound okay?

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?

I also saw that you were concerned about the OOP documentation
facilities, but this approach appears to be general enough to handle
those too.  Am I missing something?

> Then we could add tests involving the new commands.  It may not
> be necessary to have both @defline and @deflinex.
>
>> I still don't think that
>> 
>> @defMac{macro1, (arg1@comma{} arg2)}
>> 
>> is a very good syntax, though.  Maybe we could come back to this.
>> 

Thanks again, have a lovely day.
-- 
Arsen Arsenović

signature.asc
Description: PGP signature