TextIndex: Simple syntax for creating indexes in Markdown and text documents

3 months ago 1

This is the documentation for TextIndex, a simple syntax for creating indexes (in the end-of-a-book sense) in Markdown or other text documents. Its purpose is to help with producing scholarly content online and in digital and printed books. It was created by Matt Gemmell. The syntax examples in this documented were created with FigureMark.

The TextIndex git repository is on github, and is made available under the GPL-3.0 license.

To view an example of TextIndex’s output, see the index of this document itself.

Feature requests, bug reports, and general discussion are welcomed; you can use the issue tracker here.

Purpose

While working on my pandoc-based Markdown publishing system, I became aware that the creation of indexes (in the end-of-a-book sense) from plain text documents such as Markdown files was a convoluted process, often involving intermediate markup formats or external files.

My aim was to provide a documented-integrated 80% solution, allowing the annotation of terms for inclusion in a generated index, including many of the subtleties and formatting conventions of professionally-produced manual indexes. The result is TextIndex.

Its formatting is primarily of the flush-and-hang (indented) style, and tries to follow many of the principles described in the indexing guide of the Chicago Manual of Style, within the constraints of simplicity.

Note that TextIndex can generate hyperlinked reference-ID-based indexes for non-paginated formats such as HTML or ePub ebooks, and also true page-number-based indexes for paginated formats such as print and PDF, making it useful in online and digital contexts too (even though indexes are less commonly found outside the printed or printable realm).

Setup and Usage

The TextIndex git repository is on github, containing an implementation of TextIndex in Python 3 as a package. There are no external dependencies.

The repository includes example files, and a demonstration Python script showing how to load a text file, process it within TextIndex, and save the resulting converted output in a new file. In particular, it accepts an optional -v flag to enable verbose output, showing in (substantial) detail how TextIndex is parsing each document.

For those not using Python, TextIndex is a very simple markup format, and implementation of a parser should be straightforward in any language supporting regular expressions.

Integrating TextIndex

Due to similarities in syntax, TextIndex should run before any “bracketed spans” processor in your document-conversion pipeline, and also before any Markdown-conversion. If you are using FigureMark (as this documentation itself does), TextIndex needs to run after FigureMark, again due to potentially overlapping syntax.

Note that if your use of TextIndex and FigureMark together is in the context of Publish (my pandoc-based Markdown publishing system), these matters are already taken care of for you.

Rationale

It can be argued, perhaps, that the ubiquitous availability of text-searching functions for digital publications, and the presence of a table of contents in ebooks and printed matter, make an index unnecessary. Such an argument misunderstands the nature and purpose of a (well-prepared) index.

An index, in its simplest form, is a way to look up a term and find where it occurs in the work, but this is also its least valuable property. Indexes provide a structured insight into the text, showing not just what’s there, but what’s important and how those things relate to one another. Certain references are primary definitions or core concepts; others are mere mentions. Identical terms can refer to different things, and require disambiguation. Some concepts are naturally contained within others, some are best substituted for another entirely, and almost all queries are enhanced by the presence of illuminating additional or contrasting references.

Like asides, footnotes, appendices and so on, an index is an opportunity not only to guide the reader’s journey with the text and aid their understanding, but also to convey a great deal of additional context and unifying clarity than is possible in a necessarily linear overall work. Indexes are not required for every text, by any means, but for those which can benefit from them, the enhancement is substantial.

The majority of the work required when preparing an index is knowing the text intimately enough to do so — and as the author of a work, you’ve already done that part. The two remaining tasks are to assemble an appropriate index from (and of) the text, and to format that index for the reader’s use. TextIndex will help you considerably with both.

Glossary

For those unfamiliar with the terminology associated with indexes, a brief list of terms follows.

Cross-reference The indication to refer to an alternate term or entry in an index. There are two types: “see” references, which redirect the reader entirely to the alternate term; and “see also”, which offer additional information to consider. Entry Each discrete item within an index. Entries have headings, and may have sub-entries, glosses, locators, and cross-references. Flush-and-hang The index-formatting convention whereby sub-entries are indented under their parent term. Also known as indented. Contrast with run-in. Gloss (noun) An explanation, paraphrase, or interpretation of a potentially unfamiliar term, symbol, etc. (verb) To provide such an explanation. The ⌘ key on Mac keyboards is usually glossed as Command. Index The alphabetical list, usually at the end of a published work, of its terms and concepts of relevance, complete with references to where those items are discussed in the text. Contrast with table of contents. Locator Within an entry, any of the identifiers (most often page-numbers) in the primary text at which discussion of the entry’s topic can be found. Locators can refer to page-numbers, paragraphs, sections, verses, footnote numbers, or any other unique subdivision or identifier within the text. Locators can be either separate (e.g a single page-number), or continuing — also called inclusive — if they span a range (e.g. pages 2–5). Passim (Latin: scattered) Suffix used after continuing locators to indicate that the topic is discussed or mentioned only intermittently within the given range, rather than being the primary focus of that entire portion of the text. Run-in The index-formatting convention whereby items (such as locators, cross-references, and sub-entries) are directly appended to the entry they apply to, with suitable punctuation to avoid ambiguity. Table of contents The list, usually at the beginning of a published work, of all of the primary (and sometimes secondary, and so on) sections in a text; often consisting of at least the chapter headings, and shown in order of appearance. Contrast with index.

Documentation

TextIndex is extremely simple in syntax, adequate in functionality, easy to understand, and efficient to use. Let’s begin with some examples.

Entries and Headings

Terms and concepts are inserted into the index as entries, by annotating them in the text with index marks. Index marks in TextIndex take the form of {…} braces whose content begins with a ^ caret symbol, immediately following the text of the term to be inserted; this text is called the heading of the entry.

In this example, both “firmware” and “key combinations” will become top-level entries, and references will be added to those entries for the marks’ locations in the document. As shown, headings can either be wrapped in […] square brackets, or can be implicit; i.e. a sequence of non-whitespace characters immediately preceding the index mark.

If the bracketed text isn’t suitable as an index heading for the entry, the heading can be overridden by specifying it as the first element after the ^ symbol, inside of the braces. This also allows for standalone index marks, without either bracketed text or a non-whitespace sequence preceding them, as long as the heading is provided inside the mark.

If the heading override itself contains whitespace, it must be wrapped in plain single- or double-quotes. When specifying such headings within the index mark’s braces, the characters >, | (pipe), ~ (tilde), and […] must not be used in raw form, but can be included as their HTML entity equivalents

Sub-headings

Headings can also be specified hierarchically with the > symbol inside an index mark, to create sub-entries. Index etiquette strongly advises that at most one sub-level be used, but TextIndex supports arbitrary nesting if required. Any portions of the path containing whitespace must each be individually wrapped in quotes.

If the bracketed (or preceding, implicitly-associated) text is suitable as a heading, but the heading requires to be a sub-item of another entry, the final part of the nested sequence can be omitted, and the bracketed or preceding text will be used in its place. The final > must still be included, to avoid the mark being interpreted as a reference for the parent entry instead.

It’s not necessary to create index marks for each level of an index’s entries; just create the actual references you require, and TextIndex will fill-in the hierarchy automatically as needed. It is common that some top-level entries may not have their own references in the text; some might only have sub-items, in which case they won’t have their own dedicated index marks, and will instead only be mentioned in other marks subordinate to them. This is valid and expected.

A mark without a preceding or overridden heading is a syntax error. TextIndex will emit a warning, and the mark will be left untouched in the text.

Emphasis and Expansion

It will often be necessary to emphasise headings, such that they render in italics; for example when mentioning the titles of certain works and periodicals, naval vessels, foreign-language terms, and so on according to your chosen style. To accommodate this, Markdown (single-underscore) emphasis is supported in headings at all levels, and in mark-preceding headings whether bracketed or not. The corresponding entries in the index will be shown in italics (or rather, be wrapped in <em>…</em> tags), but will of course be sorted as if the emphasis is not present.

Another common scenario is creating an entry with a heading which expands (adds to) the text it refers to, usually to clarify or disambiguate a term. For example, the term “London” in a work about novelists might require the entry “London, England (city)”, or “London, John Griffith ‘Jack’ (novelist)”.

Since such entries would otherwise require an index mark in which the bare term would have to be inconveniently duplicated, the * wildcard character at any level of a mark’s internal heading path will be replaced with the mark’s preceding implicit or bracketed heading. The inserted text will be stripped of any Markdown emphasis, which can be recreated if required within the overridden and expanded heading inside the mark. If you also wish the inserted text to be converted to lowercase (as is common for index entries), use a ** double-asterisk instead.

Fig. 4Emphasised and expanded headings

The wildcard feature, because it strips Markdown emphasis, is also very useful when an important term is first introduced in a text, where it will tend to be emphasised on that occasion only. Using a wildcard heading override makes it unnecessary to duplicate the heading just to remove the emphasis from its index entry.

There is an additional type of wildcard which can also help you to avoid re-typing lengthy headings (and heading-paths) in order to create an additional reference to those headings: the prefix wildcard. It takes two forms: *^ or *^-, and when encountered, TextIndex will perform a prefix-search of all index entries so far for the mark’s preceding (bracketed or implicit) heading; i.e. it will find existing entries (any any level) which start with the preceding label. If a match is found, the relevant entry’s full heading-path will be inserted if the *^ wildcard was used, or just the entry’s own heading if the *^- form was used.

In the example above, both marks would create references to the same entry, assuming that no other entries had headings which began with “Churchill”.

For an alternative way to avoid re-typing headings and paths, see the aliases section below.

Sorting

Entries are sorted alphabetically in the index to facilitate easy searching, therefore those beginning with an article (such “The”, “A”, or “An”) should usually have their headings inverted. For example, the entry for “The Professor and the Madman” would have the heading “Professor and the Madman, The”. TextIndex does not attempt to enforce this format – there are too many variants, and indeed the rules differ for each language – but it is nevertheless good etiquette.

There are also scenarios where alphabetical sorting of the heading, even if inverted, is undesirable, so TextIndex allows providing a sort key for a given entry. Sort keys are prefixed with a ~ tilde character, must be quoted if they contain whitespace, and are placed within a mark and after any heading or references.

Sort keys are also useful when conventionalising terms with diacritics, originating in languages other than that which the work is written in.

References and Locators

Any index mark will create a location reference – called a locator – for its heading in the index, with the locator hyperlinked back to the location of the reference in the text (except in print, of course). You can think of locators as the actual page-numbers (or reference-ID numbers, for non-paginated formats) beside an index entry: whenever you add an index mark for a given heading at a certain place in the document, the page-number of that place is added to the heading’s entry in the index.

References to a single location are called separate locators, but sometimes a term is discussed in detail on a contiguous sequence of sections in the text, which would be more usefully expressed in the index as a range of locations. Such a range is called a continuing locator, and will be of the form 2–5, for example.

To mark a range of locations as being relevant to a topic, create a normal index mark at the beginning of the range, and then add a closing mark at the end of the range. Closing marks have the same heading (and heading-path, if appropriate) as the opening mark, and additionally have a / forward-slash as the final character before the mark’s closing brace.

Closing marks always apply to the most recent locator for the same heading’s entry, and any existing closing location will be updated if subsequent such marks are encountered. This convenience has the beneficial side-effect of preventing the creation of references which both span a range of locations, and also individually identify some of those spanned locations for the same heading, which is considered aesthetically and stylistically undesirable.

Supplying a closing mark for a non-existent reference is of course a syntax error; a warning will be emitted, and the mark will be left untouched in the text.

Locator Emphasis

It is common for one particular locator within an entry to be more significant than the others, or to be distinct in some way. The semantics depend on the work itself and the preferences of the index’s creator, but common scenarios including wanting to emphasise locators for a term’s definition (as opposed to discussion), or locators for the primary reference in some sense, or locators corresponding to images or other media. This practice is called locator emphasis.

Using an ! exclamation-mark as the final character within an index mark’s braces will cause the locator (whether separate or continuing) for the corresponding reference in an index entry to gain emphasis, via <em> tags. Note that this pertains to the locator itself (page-number, or reference-ID number), rather than the entry’s heading.

The example above will add a reference to the “combo” heading in the index, creating it if necessary, whose locator has emphasis. Due to the use of a wildcard, the heading itself will not be emphasised in the index, but will remain so in the text.

Locator emphasis cannot be used in closing marks for continuing locators (i.e. locators which are a range of locations, rather than a single, separate location), since this would conflict with the requirement that the final character within a closing mark’s braces must be a forward-slash. To endow a continuing locator with emphasis, do so in its opening mark instead.

For the reader’s benefit, remember to mention what your chosen semantics are for emphasised locators, ideally in a key just prior to the index itself.

Locator Suffixes

Locators in an index entry sometimes have appended text, called a suffix. For example, a separate (single) locator may have the suffix “n.1” to indicate that the reference is specifically to the first footnote at that location, rather than to the body of text. A continuing (range) locator may also have a suffix, for example “passim” to indicate that the entry’s topic is discussed only intermittently within the range, rather than being the focus of the entire passage. To accommodate this, TextIndex allows specifying a suffix in both ordinary and closing marks.

Suffixes are specified via […] square brackets within an index mark, and should come after any label/path or references (and before a sort key, if one is provided).

In the index, suffixes are appended to the reference’s locator within its entry, separated from the locators by a space. In the case of continuing locators with both an opening suffix and a closing one, the two are joined in order, separated by a space. Note again that suffixes, like locator emphasis, pertain to a reference’s locators themselves, rather than to the heading of that reference’s entry.

Cross-references

An entry only has reason to exist in an index if it has at least one reference in the text, or at least one sub-entry, or at least one cross-reference.

Cross-references refer the reader to another entry in the index, and they fall into two types, each of which has different semantics:

A “see” reference (also just generically called a cross-reference) redirects the reader; its semantics are “see this instead”.
A “see also” reference (also called an additional reference, or also-reference) offers the reader more or related information; its semantic are “see this too”.

See-references are specified after any heading path within an index mark, and are prefixed with the | pipe character (it may be helpful to think of it as “or” in this context, which will be familiar to programmers). The usual rules apply for specifying a hierarachy with >, using quotes if whitespace is present at any level, and Markdown single-underscore emphasis is respect. Furthermore, multiple cross-references can be specified by separating them with a ; semicolon.

The example above would create the (top-level) entry “destructive operation” if necessary, and add a “see”-type cross-reference to it, specifically to the “of functions” sub-entry within the (top-level) “safety” entry. In the rendered index, this would cause the “destructive operations” entry to read: “See safety: of functions”.

Within the index, see-references do not include the locator for where they were marked in the text, so they can occur anywhere. For this reason, if an index mark contains a see-reference, any further syntax within the mark which would affect locators (i.e. a suffix, or locator emphasis) will be ignored, and a warning emitted.

The second type of cross-reference, as mentioned previously, is an also-reference. These are specified in the same way as see-references, but with the addition of a prefixed + plus symbol (think of it as “also”). Also-references can be intermixed with see-references in an index mark, separated by semicolons as usual, and like see-references more than one can be provided.

The above example will cause the top-level “risk” entry to read: “See ergonomics. See also safety”.

By convention, see-references are always run-in (i.e. shown immediately after the entry’s heading and any locators, on the same line in the index), but also-references are slightly different. If an entry with also-references has no sub-entries, the also-references will be run-in, just like a see-reference. However, if the entry does have sub-entries, its own also-references will be _appended to the list of sub-entries, since semantically this makes the most sense: its also-references are logically subordinate to an entry’s explicit sub-headings.

Note that if a mark contains only the “also” type of cross-reference, the mark’s own location in the text will be recorded as a reference as usual, and any locator suffix or locator emphasis will be respected. However, if any cross-reference within a mark is of the “see” type, the mark’s own location will not be recorded as a reference for its heading. You can, of course, use multiple index marks to add suitable references and cross-references to the same entry whenever you wish.

Finally, while the inclusion of a cross-reference should usually imply the target reference’s existence, this is not enforced; TextIndex does not create the target entries of either type of cross-reference under any circumstances. This detail permits for generic cross-references, which refer to a type of heading rather than to several individual and specific headings.

For example, a generic also-reference for the “dog” heading might read “See also individual breed names”. It is conventional to render such generic references in italics, which you can achieve with Markdown underscore emphasis if desired.

Aliases

One of the purposes of an index is to gather together many discrete references to a topic throughout a work. In practice, this means that you will often find yourself creating index marks for the same heading, or sometimes cross-references to the same heading, at different places in the text. When these headings are lengthy, or when they are the headings for sub-entries, this can lead to the considerable inconvenience of re-typing (or copying and pasting) long heading-paths for commonly-encountered topics.

To ameliorate this annoyance, TextIndex allows the use of aliases wherever a heading or heading-path is accepted within a mark: i.e. as the mark’s own heading, or in either type of cross-reference. Aliases must be defined before they are used, and this is achieved by appending the alias’ name to a heading or heading-path within an index mark, prefixed with a # hash symbol, as shown below.

Fig. 13Defining and using aliases

The example above shows an alias first being defined, and then used. Without the alias, the second index mark would have had to reproduce the entire "Apple (company)">"OS platforms" heading path for its see-also cross-reference.

When defining an alias, the alias’ name must be appended after the final portion of the mark’s internal heading (if present), and thus if that heading is quoted — as in the example above — the alias must be after the closing quotation mark. The alias will apply to the entire path, not just the portion to which its name is appended when being defined. Alias names consist of uppercase or lowercase letters, digits, or the dash or underscore characters. Note that aliases can only be defined upon the heading portion of an index mark; they cannot be defined upon a cross-reference (though they can freely be used in that context once defined, as shown above).

In the situation where an index mark has no internal heading (instead having a preceding bracketed or implicit heading), the alias name will be the first element after the ^ caret symbol within the mark’s braces, which presents an ambiguity: is such a mark the definition of a new alias (for the top-level heading specified in the preceding bracketed or implicit text), or is it an attempt to use an existing alias? TextIndex resolves this in a pragmatic way: if the alias exists, it will be used; and if it does not exist, it will be created (and will be available thereafter). In both cases, a reference will be generated in the index for the relevant heading.

When using (already-defined) aliases, the alias name (prefixed with #) can go anywhere in a mark’s internal heading, or any of its cross-references, outside of quotations marks. The alias will be expanded in place to its full path, so it’s possible to use aliases for partial paths if required. Also, heading paths which define a new alias, and alse use other aliases within their paths, are permitted; i.e. paths which are expanded by aliases can themselves be defined as further aliases, if desired.

Alias names should of course be unique, but can be sub-strings of each other if needed. When resolving alias names, TextIndex requires an exact match, to avoid spurious prefix-matching.

Unreferenced aliases

As a perceptive reader, you will perhaps have realised that the behaviour of the alias feature also raises a problem, pertaining to cross-references. Consider the following very common scenario: at a particular point in the text of your document, you want to create a reference for an entry in the index, and also to cross-reference that entry to something else. This is of course trivial, and can be done at any time. But what if the entry that is the target of the cross-reference (the other thing to see, or to see also) doesn’t exist in the index yet because it hasn’t yet occurred in the document? This is also fine, because TextIndex doesn’t constrain cross-references to pre-existing entries, or indeed to any entries at all. So what’s the problem?

Consider, now, that the target entry of the cross-reference has a heading that’s long and complicated, or has a nested path, or both; something that’s a pain to type, or to go and copy and paste. Perhaps your document will even require many of these cross-references before the actual heading they target is ever mentioned in the document. Because aliases must be created before they can be used, and because the creation of an alias occurs whilst creating an actual reference to its heading in the index, there would seem to be no good way to avoid having to laboriously include the full, un-aliased cross-reference every time it’s needed, until the first actual reference to that heading occurs in the text — at which point an alias can be created, and used thereafter. TextIndex provides a solution to this problem: unreferenced aliases.

An unreferenced alias is an index mark which defines an alias without creating an entry reference in the index to the mark’s location; think of it as a pre-definition, getting an alias ready for use. Its syntax is the same as for normal (referenced) aliases, except that a ## double-hash is used as a prefix.

The above example first defines an unreferenced alias, and then uses it as a see-reference, without creating the actual entry which the alias refers to.

Note that since unreferenced aliases by definition do not create references (and thus don’t have locators in any index entry), any remaining syntax within such an index mark will be discarded. Existing aliases can also be redefined at any time, if necessary, by defining them again as unreferenced aliases.

Order of elements within index marks

The order of elements within index marks is significant, and while most elements are optional, an exemplary order is presented below for reference.

Any preceding heading, either bracketed or implicit.
The opening brace and caret: {^
Any heading-path and/or heading override, suitably quoted, optionally with alias definition or invocation. Literal (non-alias) heading paths may use an * asterisk wildcard to insert the mark-preceding, if available. Markdown _…_ underscore emphasis is supported.
Optional cross-references: a | pipe character, then ; semicolon-separated (and suitably quoted) cross-reference paths/headings/aliases. Also-refs are additionally prefixed with a + plus character.
Optional locator suffix, within […] square brackets.
Optional sort key, suitably quoted, prefixed with a ~ tilde character.
Optional final signifier: either a / forward-slash for a closing mark, or an ! exclamation-mark for locator emphasis (but not both).
The closing brace: }

After the heading path or alias, whitespace is accepted (and recommended) between the mark’s optional internal elements, except that the final signifier must always immediately precede the mark’s closing brace. A comprehensive, if contrived, example follows.

The index mark in the example will:

Create a reference from the “example text” sub-entry within the “foo” top-level entry (creating those if necessary), leading to the mark’s location in the text.
Define the alias “#demo” for the path to that entry.
Add cross-references to the entry; a see-reference to the “bar” top-level entry, and an also-reference to the “fiz” sub-entry within the “baz” top-level entry.
Apply the “whiz” suffix to the mark’s reference locator.
Sort the entry as if its heading were “z”.
Apply emphasis to the mark’s reference locator.

In this way, all of the relevant information about a given reference is encoded in the text and at the location of the reference itself. Thus, all of the index-related decisions pertaining to a reference are made while maximum context is available, instead of after the fact and at a distance.

Controlling which content to process

By default, all index marks in a document are processed, but there may be occasions when you want to prevent TextIndex from processing certain parts of your document (for example, if you’re using other types of markup with similar syntax, which could be mistaken for index marks). To accommodate this scenario, there are two special index marks which disable or enable processing from that point onwards. An example is shown below.

Fig. 16Disabling and re-enabling TextIndex processing

Note that any index marks within a region for which processing is disabled will remain untouched in the text.

You can have as many such marks as needed. Any redundant disabling marks encountered when processing is already disabled, or enabling marks encountered when processing is already enabled, will have no effect (but will remain untouched in the text if processing is currently disabled).

The index directive

Index marks, already described, define how an index is constructed, but they do not insert the actual index into the text; this is instead accomplished with an index directive. An index directive is a simple braced string, containing at a minimum the word “index”.

The index directive will be replaced by the actual index, after the entire document has been processed (so, an index directive can be placed anywhere, and the resulting index will still be complete). Multiple index directives can be specified within the same document, if desired. There are three optional parameters which can be specified within any such directive, to customise the resulting index. Their order within the directive doesn’t matter. They’re shown below with their default values.

The parameters behave as follows:

see specifies the label prepended to see-type cross-references in the index.
also specifies the label prepended to also-type cross-references in the index.
prefix specifies the prefix for the (numeric) reference IDs created within the text at the locations of index marks, which the linked locators in the index lead to.

Since these parameters are specified within the index directive itself, different values can be used for each index directive in the document if required.

Styling the output

An index is output as a hierarchical HTML description list, i.e. nested <dl> blocks, containing <dt> and <dd> pairs. Suitable CSS classes are added for styling purposes, and example CSS is included in the project repository. Some particulars are noteworthy:

Top-level entries are visually split into sections by letter, separated by a <dt> of class group-separator. These separators can, of course, be collapsed or otherwise modified via CSS.
Each index mark in the text is replaced by a corresponding <span>, with an id allowing it to be uniquely targeted from its locator in the index.
Locators in the index are links (<a> tags) of class locator, and they possess two data attributes of interest:
- data-index-id is the numeric id of the targeted span in the text.
- data-index-id-elided is the same id, but potentially elided: if this locator is the end of a continuing (range) locator, the number may be start-truncated for better readability. For example, the range 103–109 can be written elided as 103–9. Numbers in the “teens” (ending in 10-19) are a special case: the penultimate ‘1’ is preserved for better readability.

As described, locators are reference-ID links, and in non-paginated output formats like HTML or ePub, the numbers are simply sequential references with no other structural meaning. The following CSS will show those reference-IDs as the locators in the index:

In paginated formats, however, and in particular those which support CSS Paged Media, true page-numbers can be used as locators instead. To do so, and assuming that the page-counter in your print CSS is called page, just ensure that the stylesheet for your paginated output formats includes this CSS instead:

Because TextIndex cannot know in advance how your Markdown-to-HTML-to-print pipeline will paginate your document (nor how it will render, based on your CSS and other content), it is impossible to pre-determine page-numbers for locators when TextIndex processes your content. For this reason, it cannot elide (or otherwise reformat or influence) the final page-numbers, which are provided by whatever rendering engine ultimately performs the pagination.

For the same reason, TextIndex cannot de-duplicate any potential identical page-numbers within a single index entry, if their index marks happen to be close enough together to end up on the same page. This can readily be resolved by removing any duplicate index marks within the same section of the text.

Index

Below you can find an example index, for this documentation itself, generated using TextIndex. It is intended primarily to demonstrate functionality and output, rather than strictly adhering to exemplary indexing etiquette.

A brief examination should make some of the benefits of indexes more apparent, as well as offering a very rough suggested approach to the task of indexing. You can also view the Markdown source of this document, annotated for TextIndex.

N.B. Locators with emphasis are primary references.

alias, global. See alias: unreferenced redefinition of. See alias: unreferenced unreferenced, ^ (caret). See index marks Chicago Manual of Style, cross-reference, , creation of locators for, , generic, CSS (for output), example of, diacritics (sorting of). See index: sorting disabling processing. See processing of marks, enabling or disabling elision. See locator: elision of emphasis. See index marks: emphasis (of headings); locator: emphasis of escaping (of special characters in headings). See index marks: headings: characters prohibited in ! (exclamation mark). See locator: emphasis of FigureMark, use of with TextIndex, finding (an entry). See wildcards: prefix search flush-and-hang, in TextIndex formatting, / (forward slash). See locator: emphasis of gloss (definition), glossary (of terms), # (hash). See alias index, challenges when creating, entries, sub-. See index marks: headings: hierarchical headings. See index marks: headings inserting into document. See index directive nature and purpose of, of this document, sorting, index directive, parameters, index marks, closing. See locator: continuing emphasis (of headings), emphasis (of locators). See locator: emphasis of headings, bracketed, characters prohibited in, expansion. See wildcards hierarchical, , , implicit, order. See index: sorting overridden, order of elements within, syntax errors, , toggling processing. See processing of marks, enabling or disabling whitespace within, locator, , continuing, elision of, , emphasis of, inclusive. See locator: continuing suffix, macro (text). See alias # (number symbol). See alias output verbosity of. See TextIndex: verbosity of output output, styling of (generated HTML), override. See index marks: headings page-numbers. See locator de-duplication of, obtaining in paginated formats, predetermination of, ranges of. See locator: continuing passim, | (pipe). See cross-reference + (plus). See cross-reference # (pound symbol). See alias primary reference. See reference: primary processing of marks, enabling or disabling, protecting passages from mark interpretation. See processing of marks, enabling or disabling raw content. See processing of marks, enabling or disabling reference. See locator cross-. See cross-reference ID prefix, customising. See index directive: parameters primary, ‘see’-type. See cross-reference ‘see also’-type. See cross-reference run-in, style of cross-references. See cross-reference search. See wildcards: prefix search ‘see’-label, customising. See index directive: parameters ‘see also’-label, customising. See index directive: parameters ; (semicolon). See cross-reference setup. See TextIndex: usage of shortcut. See alias sort key. See index: sorting […] (square brackets). See locator: suffix suffix. See locator: suffix table of contents, . See also index TextIndex, code repository, integrating with, markup. See index marks purpose of, rationale for, syntax. See index marks syntax errors. See index marks: syntax errors usage of, verbosity of output, verbose (output mode). See TextIndex: verbosity of output vertical bar. See cross-reference wildcards, alternative. See aliases prefix search,

Thank you for reading this document. Feel free to contact me with any other questions or remarks.

Read Entire Article