Where the back-ends differ

Four back-ends ship: LaTeX (and the PDF it typesets), HTML, EPUB and Typst. The marking syntax means the same thing in all of them. What the indexes can do differs, because the tools underneath them do.

EPUB and HTML build the same index out of the same document nodes, so every row below that says “in HTML” is true of EPUB too. The two places EPUB parts company with HTML — a book is one Pandoc process there, and its locators are sequence numbers with no pages behind them — are on the EPUB page. Typst orders and groups its entries the way HTML does and prints them with page numbers; the Typst page describes it.

  1. No level ceiling in HTML or Typst. Sub-entries nest as deep as you write them. The three-level ceiling described on Sub-entry levels is makeindex’s limit, not the extension’s.
  2. The one-entry warning is LaTeX-only. A term marked two different ways reaches the LaTeX index tool as one entry the extension had to compose, so the extension says it did. An HTML or Typst index prints the locator and the cross-reference together on one entry by itself, with nothing to compose, so the warning would name a decision that format never has to make.
  3. Sorting is the extension’s own in HTML and Typst. Top-level entries are ranked into letter groups first; inside a group, and at every level below the top, the order folds ASCII uppercase to lowercase and then compares character codes, breaking a tie by character code, over an entry’s sort key where it has one. In LaTeX the order is makeindex’s. Neither collates accented or non-Latin text the way a language would, which is what sort keys are for.
  4. Locators are numbered links in HTML, in the order the marks are written, where LaTeX gives page numbers. Typst gives page numbers too, ordered as makeindex orders them, by kind of numbering and then by number, and each one links to its page.
  5. Cross-reference targets are hyperlinked in HTML when the target names an entry in the same index, and are plain text otherwise. In the LaTeX and Typst indexes a target is always plain text.
  6. A cross-reference carries no locator in any of the four back-ends. The see also limitation described on Cross-references is the same in all of them.
  7. The principal mention is emphasized everywhere, but by different means: the LaTeX back-end wraps the page number in a command you can redefine, the HTML back-end marks the link with a class and a <strong>, and the Typst back-end sets the page number in bold.
  8. A page range is a page range only in LaTeX and Typst. makeindex prints one span of pages, 12--15, and so does Typst, 12–15; HTML has no pages, so a range there is one numbered link at the opening mark. Each back-end prints one locator where you wrote two marks, which is what the syntax means. Typst prints only the ranges you write: marks on pages 3, 4 and 5 print 3, 4, 5, where makeindex folds three or more pages in a row into a range. makeindex also folds a page just after a range into it: a range on pages 2 and 3 and a mark on page 4 print 2--4 there and 2–3, 4 in Typst.
  9. The extension’s own words are settable in HTML, EPUB and Typst, and its punctuation in HTML and EPUB. The Symbols group heading, the see and see also in front of a cross-reference, and the punctuation inside an entry are the extension’s rather than yours, and index-labels: — keys symbols, see, see-also, separator and xref-separator, written at a document’s top level or inside one indexes: entry, the nearer setting winning key by key — sets them for the HTML and EPUB indexes. The Typst index reads the three word keys and neither separator key: it always prints a comma before a locator and a semicolon between two cross-references. index-labels: reaches the LaTeX back-end nowhere: that one emits \see and \seealso, whose two words babel supplies from your document’s lang:. There is no third word to set there — a LaTeX index has no letter groups at all, so it prints no Symbols heading for symbols: to override. Neither separator key reaches it either: what stands between a term and its page numbers there is makeindex’s own delimiter, and what stands between two cross-references is written into the LaTeX this extension emits — in two places, the command it defines for a term carrying both kinds and the join it writes when a term’s targets ride the encapsulation channel instead.
  10. All four back-ends follow lang:, and share nothing else about it. Every back-end picks its own words from your document’s language, and that language is the whole of what they have in common: LaTeX asks babel, HTML, EPUB and Typst read a table this extension ships. Two consequences follow. The languages covered are not the same — babel covers hundreds, this extension covers Spanish, French, German and Italian, and German only in part, so a document in a language babel knows and this table does not gets a localized LaTeX PDF and an English HTML, EPUB or Typst index. And index-labels: is read by the HTML, EPUB and Typst back-ends alone, so a word you set there changes those indexes and never the LaTeX PDF, where babel’s word stands. Setting a word for all four means writing index-labels: for HTML, EPUB and Typst and redefining \seename or \alsoname for LaTeX.