xerif

h1. Index Markup

{{toc}}

h2. Word

Transpect-tex provides four methods to encode an index. They can be combined with each other.

h3. (1) Word-Index 

Obviously, the native Word Index feature is supported. With the @\f@ switch, you can specify the index type.

!index.png!

The index listing is generated based upon the marked index entries in the main text. The Word feature _Insert index_ in the ribbon entitled _References_ shall be used only for your own control. It is removed during the process.

If you create an index listing with Word, it does not initially contain index entries that have a certain index type with "\ f".

But here are instructions on how to create an index listing for [[Indexverzeichnis-Typ| index entries with type]].

h3. (2) Encode index entries via character style

You can markup phrases with a specific character style to encode them as index entry. During the conversion, an index entry is created from a phrase which has the character style (@[a-z]{1,3}_index_mark@). Index entries that are already encoded with the Word index feature are ignored and not encoded twice.

h3. (3) List of index search terms

You can create a list of index search terms at the end of the document. During the conversion the converter searches for matches in the content and creates an index entry for each match. There are specific requirements on the list of index search terms. Each entry must have the paragraph style @[a-z]{1,3}_index_list@ and needs to be placed in a separate paragraph. Index entries that are already encoded via Word index feature (1) or character style (2) are ignored and not encoded twice. You can also use the character style @[a-z]{1,3}_index_name@ to mark only a part of the index search term, e.g. for John Doe, _Doe_ can be marked so that an index entry is also created for the phrase _Mr Doe_.

h3. (4) Static index

If you do not want to automatically search for entries in the text in the index, you can also insert a static index. You need to insert a list of index entries that yield the @index_static@ style. Page numbers in the form of @entry 144, 156, 192@ are linked to the page, i.e. you have to make sure that the page reference is correct!

h3. Index-Headings and Placement of Indices

You can mark individual index headings with a paragraph format (Regex: @[a-z]{1,3}_index_heading@). The index is rendered where the heading is in the document. Do not forget to add the index type suffix to the style name if you have multiple indices in your document.

With concordance lists and static registers, the heading must placed above the index and have the paragraph style @[a-z]{1,3}_index_heading@. Otherwise it won't be possible to assign the index heading to the list of index entries. For indexes with a specific type (e.g. person, location, subject etc), the type must be added to the paragraph style, e.g. @ [a-z] {1,3} _index_heading_person@. If there is no index heading, a standard text is inserted (e.g. _Index_) and the index is inserted at the end of the document.

h2. Hub XML

All four variants can be combined to create an index. In the hub format, index entries are given a @remap@ attribute in the text, which they assign to a specific index: 

<pre><code class="xml">

<indexterm remap="e" type="person">

  <primary>John Doe</primary>

  <secondary>Great writers of Anytown</secondary>

</indexterm></code></pre>

For each index, an @<index>@ element is generated. The @<index>@ is either placed at the position of the index heading or – if not present – at the end of the document.

<pre><code class="xml">

<index type="person" remap="e">

  <title role="tsindexheadingperson">John Doe</title>

</index>

</code></pre>

In the case of static indexes, it is assumed that the heading is always above the list of index entries. The type of index can also be specified here via an index type suffix in the paragraph style. Page numbers will be linked to the page later. 

A @.x_ind@ file is generated for static indexes during the XML conversion. In the case of dynamic indexes in the text, this must first be generated via @index.sh@. See below [[Index # call-up-the-index-script]].

<pre><code class="xml">

<index remap="c" type="location">

  <title role="tsindexheadinglocation">Ortsregister</title>

  <indexdiv>

    <title>B</title>

    <indexentry>

      <primaryie>Bertelé, <xref xlink:href="page-93"/>, <xref xlink:href="page-94"/></primaryie>

    </indexentry>

    <!-- (…) -->

  </indexdiv>

</index>

</code></pre>

h2. TeX

h3. Markup of multiple Indices 

We use the LaTeX package  "index":https://mirror.dogado.de/tex-archive/macros/latex/contrib/index/index.pdf for the creation of indices and Xindy to render the index.

h4. Declaration of indices of different types

The index package allows to declare multiple indices. They are declared with @\(re)newindex@ commands:

<pre><code class="text">

\newindex{<typ>}{<endung rohindex>}{<endung fertiger index>}{<Überschrift>}

</code></pre>

To ensure the invocation of the @index.sh@ script is working properly, the file extension of the non-default index types must be entitled @<typ>_idx@ (raw index) and @<typ>_ind@ (finished index).

The default index has the label @default@ assigned. Its heading can be overwritten:

<pre><code class="text">

\renewindex{default}{idx}{ind}{Personenregister}

</code></pre>

Index entries were marked in this way:

<pre><code class="text">

\index{<Lemma>}

</code></pre>

The index listing will be rendered in place of the @\printindex@ instruction.

<pre><code class="text">

\printindex

</code></pre>

Concerning multiple indices, each index has an individual letter as identifier. 

<pre><code class="text">

\newindex{l}{l_idx}{l_ind}{Locations}

</code></pre>

In these sample we define a location index that is identified by the letter "@l@".

<pre><code class="text">

\index[l]{<Term>}

</code></pre>

With @\printindex[l]@, the location index is rendered.

<pre><code class="text">

\printindex[l]

</code></pre>

h4. Invocation of the index script

You can pass the index identifier (e.g. letter) to specify which index should be generated. If you omit the optional argument, the main index will be generated.

<pre><code class="text">

./index.sh <tex-Dateiname ohne Endung>

</code></pre>

Passing the letter @l@ to the index script collects all index terms of this type and creates the location index.

<pre><code class="text">

./index.sh <tex-filename without extension (basename)> l

</code></pre>

The script needs to run for each index to be created.

h3. Index rendering

h4. Index rendering with TeX

Index terms are encoded with @\index[<typ>]{<Lemma>}@ in TeX.

<pre><code class="xml">

lualatex <tex-Dateiname>.tex      %% initial tex run, collect headings

lualatex <tex-Dateiname>.tex      %% create toc

lualatex <tex-Dateiname>.tex      %% for safety reasons

./index.sh <tex-Dateiname>        %% run index script for main index

./index.sh <tex-Dateiname> <type> %% run index script for index with type of <index>

lualatex  <tex-Dateiname>.tex     %% render index

lualatex  <tex-Dateiname>.tex     %% include index in ToC

lualatex  <tex-Dateiname>.tex     %% for safety reasons

</code></pre>

h4. Static index files

Are named @<basename>.<type>_ind@ and are generated in case of static indices.

With static indexes the @index.sh@ *must not be invoked*, otherwise the @*_ind@ files would be overwritten! All other steps are the same; @\(re)newindex{}{}{}{}@ must also be used here.