Hope you don't mind, but I went ahead and made some improvements to the AsciiDoctor backend for indexterms. Here's a summary:
Per our previous discussions, I added support for the following attributes for sorting terms:
primary-sortas - Sort the primary entry
secondary-sortas - Sort the secondary entry
tertiary-sortas - Sort the tertiary entry
These three attributes map to data-primary-sortas, data-secondary-sortas, and data-tertiary-sortas, respectively, in HTMLBook.
Additionally, I've preserved support for the legacy sortas attribute. The way it works now is that if none of the other three above attributes are supplied, sortas will be applied to the deepest-level term in the indexterm. So, for example, in:
((("1", "2", sortas="two")))
The sortas attribute is applied to the secondary entry of "2". The resulting HTMLBook is:
I eliminated any special logic around the range attribute. Users are welcome to add things like range="startofrange" and range="endofrange" to indexterms in AsciiDoc, but the backend ignores them, because the HTMLBook toolchain doesn't need them. All it needs is an id on the start-of-range indexterm and a corresponding startref on the end-of-range indexterm. In other words, if you do this:
First paragraph((("two paras", id="twoparas")))
Second paragraph(((startref="twoparas")))
That's all you need. I think this is much simpler from the indexer's perspective, as it's one less attribute to worry about.
Important note: putting primary/secondary/tertiary entries on the end-of-range indexterm is optional, but if you do, they must exactly match those on the start-of-range indexterm. I recommend that indexers skip adding primary/secondary/tertiary entries on end-of-range indexterms, as again it's one less thing to worry about.
I also did some general refactoring to streamline the code a bit and hopefully make it easier to maintain moving forward.
Could you review and merge/deploy if it looks good? Also, if there's any documentation that needs to be updated, could you help update that as well? Let me know if you have any questions/concerns.
Hi @sarahs,
Hope you don't mind, but I went ahead and made some improvements to the AsciiDoctor backend for indexterms. Here's a summary:
Per our previous discussions, I added support for the following attributes for sorting terms:
primary-sortas- Sort the primary entrysecondary-sortas- Sort the secondary entrytertiary-sortas- Sort the tertiary entryThese three attributes map to
data-primary-sortas,data-secondary-sortas, anddata-tertiary-sortas, respectively, in HTMLBook.Additionally, I've preserved support for the legacy
sortasattribute. The way it works now is that if none of the other three above attributes are supplied,sortaswill be applied to the deepest-level term in the indexterm. So, for example, in:The sortas attribute is applied to the secondary entry of "2". The resulting HTMLBook is:
rangeattribute. Users are welcome to add things likerange="startofrange"andrange="endofrange"to indexterms in AsciiDoc, but the backend ignores them, because the HTMLBook toolchain doesn't need them. All it needs is anidon the start-of-range indexterm and a correspondingstartrefon the end-of-range indexterm. In other words, if you do this:That's all you need. I think this is much simpler from the indexer's perspective, as it's one less attribute to worry about.
Important note: putting primary/secondary/tertiary entries on the end-of-range indexterm is optional, but if you do, they must exactly match those on the start-of-range indexterm. I recommend that indexers skip adding primary/secondary/tertiary entries on end-of-range indexterms, as again it's one less thing to worry about.
Could you review and merge/deploy if it looks good? Also, if there's any documentation that needs to be updated, could you help update that as well? Let me know if you have any questions/concerns.
Thanks, Sanders