doctools::idx(n)

doctools::idx 💖

okay bestie, so this is doctools::idx(n) — a Tcl documentation-tools manual page, and it's literally the blueprint for holding keyword indices. It's a whole package. Sit down, grab a strawberry drink 🍓, and let's get into it. This page is long so it comes in parts — part 1 starts right here.

---

✨ NAME ✨

doctools::idx — holding keyword indices 💅

---

✨ SYNOPSIS ✨

package require doctools::idx ?2.1?

package require Tcl 8.5 9

package require doctools::idx::structure

package require snit

::doctools::idx objectName

objectName method ?arg arg ...?

objectName destroy

objectName key add name

objectName key remove name

objectName key references name

objectName keys

objectName reference add type key name label

objectName reference remove name

objectName reference label name

objectName reference keys name

objectName reference type name

objectName references

objectName title

objectName title text

objectName label

objectName label text

objectName importer

objectName importer object

objectName exporter

objectName exporter object

objectName deserialize = data ?format?

objectName deserialize += data ?format?

objectName serialize ?format?

---

✨ DESCRIPTION ✨

So this package hands you a class whose whole job is to hold keyword indices and let you poke at them programmatically. That's it. That's the vibe. 🫶

This thing is one of the three public pillars that keyword-index management stands on. The other two pillars are, in no particular order of iconicness:

1. Exporting keyword indices, and
2. Importing keyword indices

Wanna know about the Concepts of keyword indices and all their little parts? Go read the same-named section (it's down below, don't worry, we got you 💜). Wanna know about the data structure that encodes keyword indices as values? That's the Keyword index serialization format section, bestie. And real talk: that is the only format this class knows about directly. Any conversion from or to literally any other format? Handled by export and import manager objects. You can attach those to a container, but you absolutely do not have to — it's purely a convenience. No pressure. 🦋

---

✨ CONCEPTS ✨

Here's the whole mental model, broken all the way down:

1. A keyword index is made of a (possibly empty) set of keywords.
2. Every keyword in that set is identified by its name.
3. Every keyword has a (possibly empty) set of references.
4. A single reference can be associated with more than one keyword.
5. But a reference that isn't associated with at least one keyword? Not possible. Can't happen. Doesn't exist. Periodt. 💀
6. Every reference is identified by its target, which you specify as either a url or a symbolic filename — depends on the type of the reference (url, or manpage).
7. The type of a reference (url, or manpage) depends only on the reference itself. Not on which keywords it's hanging out with. It's independent, it's got main character energy. 👑
8. On top of a type, every reference also has a descriptive label. And that label also depends only on the reference itself, not on the keywords it's associated with. Same deal.

a few notes 📝

1. Manpage references are meant to point at the documents the index is made for. Their target is a symbolic file name identifying the document, and export plugins may swap the symbolic name for an actual file name — if one was specified.
2. Url references, on the other hand, are meant for links to anything else, like websites. Their target is an url.
3. url and manpage references share a namespace for their identifiers, and lowkey that should be zero problem — because manpage identifiers are symbolic filenames, and symbolic filenames should never look like urls, which is what url reference identifiers are. So like, they're not gonna collide. 🌸

---

✨ API ✨

PACKAGE COMMANDS

• ::doctools::idx objectName — this command makes a brand new container object, and it comes with a Tcl command whose name is objectName. That object command is explained in full detail in the sections Object command and Object methods (they're right below, keep scrolling 💅). The object command gets created under the current namespace if objectName isn't fully qualified, and in the specified namespace otherwise.

OBJECT COMMAND

Every single object created by the ::doctools::idx command has this general form:

• objectName method ?arg arg ...? — the method method plus its arg'uments decide exactly what the command does. See the Object methods section for the detailed specs. 👑

OBJECT METHODS

• objectName destroy — destroys the object it's invoked for. bye bestie 💀
• objectName key add name — adds the keyword name to the index. If that keyword is already known, nothing happens. The result of the method is the empty string.
• objectName key remove name — removes the keyword name from the index. If the keyword is already gone, nothing happens. Any references for whom this keyword was the last association get removed too. The result of the method is the empty string.
• objectName key references name — returns a list containing the names of all references associated with the keyword name. An error is thrown if the keyword is not known to the index. The order of the references in the list is undefined — do not count on it, bestie.
• objectName keys — returns a list containing the names of all keywords known to the index. The order of the keywords in the list is undefined. Same warning. 🙈
• objectName reference add type key name label — adds the reference name to the index and associates it with the keyword key. The other two arguments hold the type and label of the reference, respectively. The type has to match the stored information if the reference already exists — meaning this information is immutable once the reference is known. The only way to change it is to delete and recreate the reference. The label, though, gets automatically updated to the value of the argument, overwriting anything stored before. If the reference already exists it's simply associated with the key. And if that's already true too, nothing happens — but the label still gets updated to the new value. The result of the method is the empty string.

The type argument has to be one of manpage or url.

• objectName reference remove name — the reference name is removed from the index. All associations with keywords are released, and the relevant reference labels are removed too. The result of the method is the empty string.
• objectName reference label name — returns the label associated with the reference name. An error is thrown if the reference isn't known. 🚨
• objectName reference keys name — returns a list containing the names of all keywords associated with the reference name. An error is thrown if the reference isn't known to the index. The order of the keywords in the list is undefined.
• objectName reference type name — returns the type of the reference name. An error is thrown if the reference isn't known to the index.
• objectName references — returns a list containing the names of all references known to the index. The order of the references in the list is undefined. you know the drill ✨
• objectName title — returns the currently defined title of the keyword index.
• objectName title text — sets the title of the keyword index to text, and returns it as the result of the command.
• objectName label — returns the currently defined label of the keyword index.
• objectName label text — sets the label of the keyword index to text, and returns it as the result of the command.
• objectName importer — returns the import manager object currently attached to the container, if any.
• objectName importer object — attaches object as import manager to the container, and returns it as the result of the command. Important: the object is not put into ownership of the container. I.e., destroying the container will not destroy the object. It's a situationship, not a commitment. 😭

It's expected that object provides a method named import text which takes a text and a format name, and returns the canonical serialization of the keyword index contained in the text, assuming the given format.

• objectName exporter — returns the export manager object currently attached to the container, if any.
• objectName exporter object — attaches object as export manager to the container, and returns it as the result of the command. Same deal as above: the object is not put into ownership of the container. Destroying the container will not destroy the object.

It's expected that object provides a method named export object which takes the container and a format name, and returns a text encoding the keyword index stored in the container, in the given format. It's further expected that the object will use the container's serialize method to obtain the serialization of the keyword index, and generate the text from that.

• objectName deserialize = data ?format? — this method replaces the contents of the index object with the index contained in data. If no format was specified, it's assumed to be the regular serialization of a keyword index.

Otherwise, the object will use the attached import manager to convert the data from the specified format into a serialization it can handle. In that case, an error will be thrown if the container has no import manager attached to it.

The result of the method is the empty string.

• objectName deserialize += data ?format? — behaves like deserialize = in its essentials, except that it merges the keyword index in data into its contents instead of replacing them. The method will throw an error if merging isn't possible — i.e., if it would produce an invalid index. In that case, the existing content is left unchanged. 🫶

The result of the method is the empty string.

• objectName serialize ?format? — returns the keyword index contained in the object. If no format is specified, the returned result is the canonical serialization of its contents.

Otherwise, the object will use the attached export manager to convert the data to the specified format. In that case, an error will be thrown if the container has no export manager attached to it.

---

okay and that's where part 1 ends bestie, don't go anywhere — there's more coming 💜

✨ KEYWORD INDEX SERIALIZATION FORMAT ✨

okay so this is the tea on how the doctools v2 packages serialize keyword indices as immutable values for transport, comparison, etc. 💅

We gotta distinguish between regular and canonical serializations. A keyword index can have more than one regular serialization, but only exactly one of them will be canonical. no cap.

---

regular serialization 💅

1. An index serialization is a nested Tcl dictionary. 🫶
2. This dictionary holds a single key, doctools::idx, and its value. This value holds the contents of the index. ✨
3. The contents of the index are a Tcl dictionary holding the title of the index, a label, and the keywords and references. The relevant keys and their values are:

• title — The value is a string containing the title of the index. 👑
• label — The value is a string containing a label for the index. 🏷️
• keywords — The value is a Tcl dictionary, using the keywords known to the index as keys. The associated values are lists containing the identifiers of the references associated with that particular keyword.

Any reference identifier used in these lists has to exist as a key in the references dictionary, see the next item for its definition. 🚨

• references — The value is a Tcl dictionary, using the identifiers for the references known to the index as keys. The associated values are 2-element lists containing the type and label of the reference, in this order.

Any key here has to be associated with at least one keyword, i.e. occur in at least one of the reference lists which are the values in the keywords dictionary, see previous item for its definition. 🚨

4. The type of a reference can be one of two values,

• manpage — The identifier of the reference is interpreted as symbolic file name, referring to one of the documents the index was made for. 📄
• url — The identifier of the reference is interpreted as an url, referring to some external location, like a website, etc. 🌐

---

canonical serialization 👑

The canonical serialization of a keyword index has the format as specified in the previous item, and then additionally satisfies the constraints below, which make it unique among all the possible serializations of the keyword index. it's giving the one 💅

1. The keys found in all the nested Tcl dictionaries are sorted in ascending dictionary order, as generated by Tcl's builtin command lsort -increasing -dict. 🔤
2. The references listed for each keyword of the index, if any, are listed in ascending dictionary order of their labels, as generated by Tcl's builtin command lsort -increasing -dict. 🔤

---

🐛 BUGS, IDEAS, FEEDBACK 🐛

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category doctools of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. bestie we wanna hear u 🫶

When proposing code changes, please provide unified diffs, i.e the output of diff -u. 📝

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. ✨

---

🔑 KEYWORDS 🔑

HTML, TMML, conversion, docidx markup, documentation, formatting, generation, index, json, keyword index, latex, manpage, markup, nroff, parsing, plugin, reference, tcler's wiki, text, url, wiki

---

📂 CATEGORY 📂

Documentation tools 📚

---

©️ COPYRIGHT ©️

Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net> 💖

---

okay bestie that's the whole page! This footer is tcllib 2.1, doctools::idx(n) — no date in the footer, so that's the whole vibe 😭 love u, bye! 💅✨