indexing elements in the LaTeX namespace

[FrankMittelbach]

General disclaimer: all of the tag names and often also the underlying structures are still subject to discussion and are not meant to be final.

Indexing

There are 7 tags in the LaTeX namespace related to theindex environment

Examples

• Index entries can be nested (up to 3 levels in LaTeX).
• Each level has a "term" and may or may not have "references"
• There can be special reference as in "see ..." or "see also ...."

animal, vi, 5–7
   insect, 32
   mammal
      cat, 26, see also specific cats
      mouse, 17
animalism, see animal

mammal, 17, 26

tiger, 31

• Index entries can also be grouped with a group heading
• If subdivided there may be introductory text following the group heading
• The group heading may not show text but could be simply a visual separation of some sort

     Symbols
@ sign, 2

        B
box, 21
    dimensions of, 33
    parameters, 5

       D
dimensions
    figure, 17
    rule
        height, 12
	width, 3
    table, 9

In dictionaries you often find a further structure looking something like this:

habitual Am. adj. (adv. ~ly) 1. gewohneitsmäßig ~ criminal Gewohnheitsverbrecher 2. gewohnt, ständig, üblich. habitualness Gewohneitsmäßigkeit. habituate (sich) gewöhnen. ...

habitude 1. Wesen, Neigung, Veranlagung. 2. (An)Gewohnheit

• Here the 3 entries habitual, habitualness, and habituate are toplevel entries but grouped together (and separate from the next entry abitude).
• The first of the 3, i.e., habitual has a subentry ~ criminal.

---

• The whole index typically has a document level heading
• In addition it may or may not have introductory text prior to the index entries.

Neither is shown in the examples above.

Tags in the name space

The tags are (for now):

• <index> enclosing the overall structure
• <index-head> heading for the whole index
• <index-subdivsion> encloses a larger group of index entries (typically with a heading in front)
• <index-subdivision-head> heading for group of related index entries, e.g., "Symbols" or starting with "A" or ...
• <index-entry> single index entry
• <index-term> enclosing each index term
• <index-group> group of closely releated index entries (found in dictionary settings, see example above)

This is more or less a minimal set in the sense that some parts in the index are determined by their order without adding an additional tag, e.g., while <LI> in lists contains two parts both tagged (<Lbl> and <LBody>) we only tag <index-term> but not the reference(s) that are following, because an <index-term>is required and all that can follow up to either </index-entry> or another <index-entry> (denoting a sub entry) are such references.

This could be made explicit at the cost of more tags in the pdf.

Formal syntax

 {index}              ::=  <index>
                             [ {index title} ] [ {general text} ]  {index body}
                           </index>

 {index title}        ::=  <index-head> {general text} </index-head>


 {index body}         ::=  {index subdivision}* | {index entries}

 {index entries}      ::=  ( {index entry} | {index group} )+

 {index group}        ::=  <index-group>  {index entry}+  </index-group> 
			    

 {index subdivision}  ::=  <index-subdivision>
                              {index subheading} [ {general text} ] {index entries}
			   </index-subdivision>

 {index subheading}   ::=  <index-subdivision-head>  {general text}  </index-subdivision-head>


 {index entry}        ::=  <index-entry>
                             {index term} {index references}
                                |
                             {index term} [ {index references} ] {index entry}*
                           </index-entry>

 {index term}         ::=  <index-term>  {general text}  </index-term>
 {index references}   ::=  ???

Notes

• {index title} probably needs more structure
• {index references} could just be {general text} but one could also describe its structure more formally
• Most technical indexes will not have {index group}s but typical dictionaries do, which is why {index entries} offers the alternative.
• Standard LaTeX index processors and the standard set of commands only support nexted index entries up to 3 levels. For some indexes one could do with more and it is trivial to extend the LaTeX code to support this, which is why I have not put an explicit limit on to the nesting level.
• The above structure means that an index is heavily structured (similar to TOCs). However, no simpler structure does capture the aspects of indexes well that are needed for properly accessing the data and navigating within it.

Role-mapping

tbd

[car222222]

More generally, for the huge scope of "index" presented here (which includes pretty much any structured, itemised, keyed listing), rather than:

{index references} ::= ???

there is a needs for something less specific, such as:

{information} ::= ???

And then indeed its structure, and the type of data it contains, will vary hugely for different "types of indexed material".

For example, in an "extremely simple page index", its content model will be simply:

{information} ::=

Whereas in a sophisticated dictionary, thesaurus, glossary, handbook, manual, etc., it will have a very sophisticated/complex structure model with a lot of substructures and specialised data-types.

[FrankMittelbach]

Maybe it is better to call it {index information}, but is is an intermediate part in the BNF-like description, so it doesn't show anywhere, ie it is not part of the namespace. But because it is a placeholder it should not be just be {information}, if by the end of the day you stick the various structures together.

And remember, the intend is to describe the LaTeX document model (including its standard extension) and in that respect you have to balance between covering what is actually there (out of the box) what could be done (given that LaTeX can be extended in arbitrary ways and the provide more structure) and what is useful in a general model that describes most use cases.

[car222222]

Yes, I was not really suggesting a name, and I need to spend some time to better understand your chosen notation.

Part of my trouble is that my mind sometimes fails to distinguish between {} and <> ! Let alone remembering the meaning of either (is
this not where you swapped from the standard
BNF usage?).

[car222222]

I had not realised that the "standard LaTeX model" covered complex listings such as those in dictionaries.

[FrankMittelbach]

Not sure the is a single standard for BNF, probably there is. Knuth uses <...> for placeholders but since that is really needed here to denote namespace tags, I settled on {...} for placeholders. See #6 for a summary of the syntax I use.

[FrankMittelbach]

Ross Moore (@ozross) suggested to use TOCand TOCIfor role mapping and I think that he is right in that being the best possible choice into the standard PDF tagset.