latex index

Indexes in LaTeX

The packages provide components for generating LaTeX indices of named entities.

There are two packages related to indexing:

• xsl/latex/librend.xsl: This inserts \index[INDEX]{\GetTranslation{ENTITY}} into the main text, apparatus entries and footnotes. The ENTITY will only be the key or reference to the entity, which is used as a translation key.
• xsl/latex/libindex.xsl: This is used to generate translations of entity keys or references to real entries.

Using only keys in the \index macros, has severals benefits:

• Linguistic variation is eliminated.
• It's very readable and nice!
• The sort order in the index can easily be determined by an XSLT function.
• The index gets translatable.

imakeidx is used as the LaTeX indexing package.

The nice \GetTranslation macro comes from the translations package. It is not expanded until \printindex is called. The .idx and .ind files only contain keys.

Prepared for All Kinds of Indixes

Many types of indices can be generated. Number of types depends of the types of entities encoded.

There templates in xsl/latex/librend.xsl for indexing entities of type encoded by several means:

• person: from <persName ...> or <rs type="person" ...>
• place: from <placeName ...> or <rs type="place" ...>
• org: from <orgName ...> or <rs type="org" ...>
• event: from <eventName ...> or <rs type="event" ...>
• ANY: from <rs type="ANY" ...> where ANY is an arbitrary number of arbitrary index kinds, i.e. anything you use a rs/@type will go to an index.

The modes text:text, app:reading-text, and note:editorial from xsl/latex/librend.xsl which is responsible for generating LaTeX \index[...]{...} calls, has public visiblity and can thus be adapted by a downstream package for special needs.

The named template rend:latex-header-index from xsl/latex/librend.xsl will call \makeindex for all kinds of indexes.

Flexible Printout

There is a template named rend:print-indices in xsl/latex/librend.xsl, which will print out every index, even all the ANY ones.

If you want less, just write a particular call to printindex into your tex file:

\printindex[person]
\printindex[place]

Note the singular!

Note, that \printindex from imakeidx will only print an index, if there are entries in it.

Translations

xsl/latex/libindex.xsl can be called on the TEI source file as context item and it will print out a translation every time an entity is referenced. The duplicates will not be a problem, since the keys/references are used as translation keys and the translations is always the same as it is taken from the register file.

There is a nice named template called index:translation-package-filecontents which called from included in the XSLT code generating the TeX header. It will insert a filecontents environment with a package of translations, which will be written to i18n-index.sty by the TeX engine.

Overall Code

For using these components, only a few lines of XSLT are required:

  <xsl:use-package
    name="https://scdh.zivgitlabpages.uni-muenster.de/tei-processing/transform/xsl/latex/libindex.xsl"
    package-version="1.0.0">
    <xsl:accept component="template" names="index:translation-package-filecontents"
      visibility="final"/>
  </xsl:use-package>
  
  <!-- librend will probably be used indirectly via libtext -->
  
  <xsl:template match="TEI">
	<xsl:call-template name="my-latex-header"/>
	...
	<xsl:call-template name="rend:latex-header-index"/>
	<xsl:call-template name="index:translation-package-filecontents"/>
	...
	\begin{document}
	....
	\end{document}
  
	<xsl:call-template name="rend:print-indices"/>
  
  </xsl:template>

This is essentially only 3 lines related to index: the 3 xsl:call-template directives.

Have a look into xsl/projects/alea/latex/prose.xsl for an usage example.

@ref vs. @key

When you use @ref to reference an entity (be it from your local registry file or a remote registry), chances are good, that you do not have to touch the XSLT code. This is because the value type of @ref is a tei:pointer, i.e., an URL, which can be dereferences by generic code.

When you use @key, then you will have to override the index:from-key-attribute function.

  <xsl:use-package
    name="https://scdh.zivgitlabpages.uni-muenster.de/tei-processing/transform/xsl/latex/libindex.xsl"
    package-version="1.0.0">
    <xsl:accept component="template" names="index:translation-package-filecontents"
      visibility="final"/>
	<xsl:override>
		<xsl:function  name="index:from-key-attribute" as="map(xs:string, node()*)" visibility="public">
			<xsl:param name="key" as="xs:string"/>
			<xsl:param name="index" as="xs:string"/>
			<xsl:param name="context" as="attribute()"/>
			<!-- your implementation -->
		</xsl:function>
	</xsl:override>
  </xsl:use-package>

It returns a map which maps keys indentifying the entities to nodes representing them. Note, that a @key attribute may contain multiple keys. Since @key's "form will depend entirely on practice within a given project", there is no generic implementation of this function. See TEI reference of att:canonical.

Tweaking the Entries

From the de-referenced entity is passed through the mode index:languages to get translations, possibly in different languages.

For a person entity, the name from the first occurrence of person/persName per language is used as the entry text. Similar for the other index kinds.