Add a document index

[henrikt-ma]

Despite recent work on styling the HTML, my colleagues still refuse to use it in their daily work due to the lack of document search. The PDF document, on the other hand, can be searched with varying degree of success depending on choice of PDF reader. Still, many of the most important terms to search for have so many occurrences in the text that it is hard even for a good document search function to guid the reader to the most important places in the document.

With this PR, I'd like to explore the possibility to address this by adding a document index. To start with, I plan to cover these categories of terms:

• Definitions
• Anything with a \firstuse{…}
• Keywords
• Built-in types (Real, StateSelect, …)
• Core language functions (sin, fill, …)
• Annotations (Inline, Dialog, …), but not their member names to avoid index clutter
• Built-in attributes (start, stateSelect, …)
• Language constructs (start value, when-clause, …)
• Mathematical concepts (just a few to start with: hybrid DAE, initialization problem, …)
• Terms defined in the glossary (partial flattening, modification, …)
• Misc: deprecated, quality of implementation, translation, simulator (or remove uses)
• … (other proposals are welcome!)

Then, I plan to somehow make the index easily accessible (ideally more accessible than listed at the end of the table of contents) when reading the HTML, so that it can act as some sort of replacement for a document search function.

[HansOlsson]

Note that another search possibility would be as described in:
#2404 (assuming it works).

[henrikt-ma]

Note that another search possibility would be as described in:
#2404 (assuming it works).

Yes, that's definitely a related issue worth mention. I think there are good use cases for both ways of searching the document. If we are talking about some more sophisticated global document search where we can add search markup similar to the index terms – allowing search to produce intelligent results for things like "Real", "der", or "+" – then I think it could work well for the HTML versions. The PDF, however, would still benefit from an old-school document index.

[henrikt-ma]

I think we need to be more consistent:

base clock partition
clocked, 219
continuous-time, 219
base-clock partition, 210

What you see is related to #2713, but to avoid getting a dependency on #2713 being fixed in general, I'll resolve this particular case as part of this PR in favor of base-clock partition.

[henrikt-ma]

class, 41
class, 80
class tree, 63
class type, 69, 72

To me, these are different enough that I find it natural to not have them all under class.

[henrikt-ma]

Clock, 209
event, 212
…

Fixed. These are now grouped under either Clock, clock, or clocked.

[henrikt-ma]

A second concern is how much we want to reference non-first use. I would like if connector referred to chapter 9; and even had it as main reference.

OK, I've now use a non-normative mention of connector as the main entry. Seems a bit strange, so please verify that this is what you meant.

[henrikt-ma]

Having addressed or responded to all review comments, made a grouping sweep through the index myself, and not having any ideas for how to make the HTML index more accessible without attacking the LaTeXML XSLT files, I am now removing the Draft state to indicate that I don't plan to add anything substantial unless requested by reviewers.

[HansOlsson]

A second concern is how much we want to reference non-first use. I would like if connector referred to chapter 9; and even had it as main reference.

OK, I've now use a non-normative mention of connector as the main entry. Seems a bit strange, so please verify that this is what you meant.

Well, that entire chapter is about connections and connector so I think it's fine to reference a use in the non-normative introduction.

[HansOlsson]

Seems ok in general.
There are some minor details that we can improve later, but better to have it in place.

[HansOlsson]

Could now merge except for the conflicts.

[henrikt-ma]

Could now merge except for the conflicts.

Ready.