On Thu, Mar 14, 2024 at 11:36:49PM +0100, Patrice Dumas wrote:
> > I didn't really know what this part meant:
> >
> > Index entries and comments that are given before an @code{@@item}
> > including the first, are automatically moved (internally) to after the
> > @code{@@item}, so the output is as expected. Historically this has
> > been a common practice.
> >
> > Methinks comments don't affect the output so moving them is irrelevant.
> > I thought this could be rewritten to something like
> >
> > Index entries that occur immediately before an @code{@@item}
> > are associated with the @code{@@item}.
>
> Even though the information given on comments is relevant, I agree that
> it is expected and does not need to be mentionned. I also agree with
> avoiding to mention some implementation details.
I've committed this.
>
> There is also some text in @node Other Customization Variables
> TREE_TRANSFORMATIONS description that provides a similar information
> that you may consider changing:
>
> @item move_index_entries_after_items
> In @code{@@enumerate} and @code{@@itemize}, move index entries
> appearing just before an @code{@@item} to just after the
> @code{@@item}. Comment lines between index entries are moved too. As
> mentioned, this is always done for HTML and DocBook output.
This is more of an internal setting that happens to be documented in the
manual. It's possible that the user would never want to set this.
