xml2rfc
xml2rfc copied to clipboard
ietf-tools
Generate a more compact index
The current method for constructing an index uses <xref> elements underneath, which generates an extremely verbose index if you choose to use that feature. Take this example (this link won't work forever, sorry, but here is an archive), which shows just how bad this can get.
A more compact version of the same index might uses symbols in place of the words.
On 2022-08-17, at 16:40, John L @.***> wrote:
Assuming you don't plan to print it out, why is this a problem?
Some of us actually look at indexes and click on things (did it just yesterday for the C++ standard). Doing this in a forest of noise is unnecessarily hard.
Grüße, Carsten
Looks to me like the fix is to combine repeated items, e.g. Section 1, Paragraph 3; Section 2, Paragraph 1; Section 2, Paragraph 3; Section 2, Paragraph 3; Section 2, Paragraph 3; Section 2, Paragraph 6, Item 1; Section 2, Paragraph 6, Item 2; Section 2, Paragraph 6, Item 3; Section 2, Paragraph 6, Item 9; Section 2, Paragraph 6, Item 10; turns into [Section 1, Paragraph 3]; [Section 2, Paragraph 1, 3, 6.1, 6.2, 6.3, 6.9, 6.10]
On 2022-08-17, at 18:21, John L @.***> wrote:
[Section 1, Paragraph 3]; [Section 2, Paragraph 1, 3, 6.1, 6.2, 6.3, 6.9, 6.10]
[§ 1: ¶ 3]; [§ 2: ¶ 1, 3, 6.1, 6.2, 6.3, 6.9, 6.10]
Now we are talking :-)
Grüße, Carsten
[§ 1: ¶ 3]; [§ 2: ¶ 1, 3, 6.1, 6.2, 6.3, 6.9, 6.10]
I can give that a spin. Note that we have three levels of nesting here, which will make it a little more challenging to present, but a single layer of collapse might help.
OK, so it turns out that Carsten's (or maybe it was John's) suggestion is still a good one, but not one that I'm likely to get around to. It's a little tricky to manage. Is there any reason that an optional feature like this would be undesirable?
I took a look at implementing the merging idea, which is a good one. That is an entirely different part of the process.
My limited understanding is that the generation of links in the index occurs in the preptool. Basically, in step 1 the preptool populates an index with a bunch of <xref> elements, then the index is rendered using fairly normal <xref> rendering rules maybe with a few tweaks. This pull request only affects the rendering of those links into text or HTML. A separate change would be needed to change the content of those links. That might happen, but it can do so separately.
FWIW; the index should not be part of the prepped document.
On the contrary, the point of prepping is to get a document ready to render and the index definitely belongs there. Same as the table of contents. We can have a meta-argument about what the scope of the preptool should be, but this is what it is now.
the point of prepping is to get a document ready to render
Nope. That's how it's used by xml2rfc right now, but that has absolutely nothing to do what the preptool was designed for. Putting the Toc, the authors section and the index here is simply an abuse for how xml2rfc works internally.
I agree with @reschke. The way that the preptool works currently leaks its internal business everywhere.