doctools::toc(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

doctools::toc — holding tables of contents 💖

🌸 SYNOPSIS 🌸

Okay bestie, here's the vibe check on how you summon this thing:

package require doctools::toc ?2?

package require Tcl 8.5 9

package require doctools::toc::structure

package require struct::tree

package require snit

::doctools::toc objectName

objectName method ?arg arg ...?

objectName destroy

objectName + reference id label docid desc

objectName + division id label ?docid?

objectName remove id

objectName up id

objectName next id

objectName prev id

objectName child id label ?...?

objectName element ?...?

objectName children id

objectName type id

objectName full-label id

objectName elabel id ?newlabel?

objectName description id ?newdesc?

objectName document id ?newdocid?

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 💖

This package gives you a class to contain and programmatically manipulate tables of contents. Like, it's the main character of ToC handling, no cap.

It's one of the three public pillars that the management of tables of contents resides on. The other two pillars are:

  1. Exporting tables of contents, and
  2. Importing tables of contents

For the tea on the Concepts of tables of contents, and their parts, see the same-named section. For the data structure used to encode tables of contents as values, see the section ToC serialization format. That's literally the only format this class knows about directly. Conversions from and to any other format are handled by export and import manager objects. You can attach them to a container if you want, but you don't have to — it's merely a convenience, bestie. 🫶

🧚 CONCEPTS 🧚

  1. A table of contents is made of a (possibly empty) list of elements. Periodt.
  2. Every element in that list is identified by its label.
  3. Every element is either a reference or a division.
  4. Every reference has an associated document, identified by a symbolic id, plus a textual description.
  5. Every division may have an associated document, identified by a symbolic id.
  6. Every division consists of a (possibly empty) list of elements, and each element follows the rules in item 2 and above.

✨ A few notes ✨

  1. Those rules above build up a tree of elements, with references as the leaf nodes and divisions as the inner nodes, and every element is one entry in the whole table of contents.
  2. The identifying labels of any element E are unique within their division (or toc), and the full label of any element E is the list of labels for all nodes on the unique path from the root of the tree to E, including E.

🎀 API 🎀

alright bestie, vibes established, concepts understood — now we get to the actual commands. this is the part where you stop reading and start typing 💅

✨ PACKAGE COMMANDS ✨

  • ::doctools::toc objectName — this is the spawner, the origin story, the main character generator 🫶 it creates a brand-new container object, and that container gets its very own associated Tcl command, and that command is named objectName. the whole personality of that object command is explained in full detail in the sections Object command and Object methods (scroll, bestie, they're right there). also important: if objectName is not fully qualified, the object command gets created under the current namespace — and if it is fully qualified, it goes in the namespace you specified. no cap ✨

🦋 OBJECT COMMAND 🦋

every single object that ::doctools::toc makes follows this exact general form:

objectName method ?arg arg ...?

so like, the method is the method, and its arguments are what decides the exact behavior of the command. the full specs live in the Object methods section, so keep reading 👇

👑 OBJECT METHODS 👑

this is the good part. the whole menu. every method, no skips 🔥

  • objectName destroy — destroys the object it's invoked on. that's it. it's gone. rip to that object 💀
  • objectName + reference id label docid desc — yes the method name literally starts with a +, we love a quirky icon 😌 this adds a new reference element to the table of contents, and it goes under the element you specify via its handle id. important vibe check: that parent element has to be a division element, or the root — anything else and it throws an error, periodt. the new element is externally identified by its label, and that label has to be unique within the parent element — again, error otherwise, no exceptions 🚫. since it's a reference element it refers to a document identified by the symbolic docid. and listen: that reference must not be the empty string, error thrown otherwise. beyond the label, the element also carries a longer descriptive string, handed over via desc. the result of the method is the handle (id) of the new element 🎀
  • objectName + division id label ?docid? — same energy, different element: adds a new division element to the table of contents, under the element specified via its handle id. that parent has to be a division element, or the root, error otherwise. the new element is externally identified by its label, which has to be unique within the parent element — yep, error otherwise. as a division element it can refer to a document identified by the symbolic docid, but it's also totally allowed to choose not to 🦋 the result of the method is the handle (id) of the new element.
  • objectName remove id — removes the element identified by the handle id from the table of contents. if that element is a division, all of its children get removed too (they go down with the ship, sorry 😭). one thing though: the root element/division of the table of contents cannot be removed — only its children can. the result of the method is the empty string.
  • objectName up id — returns the handle of the parent of the element identified by its handle id. or the empty string if id referred to the root element. that's it, that's the whole method ⬆️
  • objectName next id — returns the handle of the right sibling of the element identified by its handle id. if the element has no right sibling, you get the handle of the parent instead. and if id referred to the root element, you get the empty string. ➡️
  • objectName prev id — same as next but the other direction: returns the handle of the left sibling of the element identified by its handle id, or the handle of the parent if the element has no left sibling, or the empty string if id referred to the root element. ⬅️
  • objectName child id label ?...? — returns the handle of a child of the element identified by its handle id. the child itself is identified by a series of labels 🧚
  • objectName element ?...? — returns the handle of the element identified by a series of labels, starting all the way from the root of the table of contents. cute detail: the series of labels is allowed to be empty, and in that case you just get the handle of the root element back. 🌸
  • objectName children id — returns a list containing the handles of all children of the element identified by the handle id, from first to last, in that order. order matters bestie, don't sleep on it 👑
  • objectName type id — returns the type of the element. it's either reference or division. two options, no in-between 💅
  • objectName full-label id — this method is the complement of the method element — it goes the other way around, converting the handle id of an element into a list of labels that fully identify the element within the whole table of contents 🔄
  • objectName elabel id ?newlabel? — queries and/or changes the label of the element identified by the handle id. if the argument newlabel is present, the label gets changed to that value. regardless of any of that, the result of the method is the current value of the label. if the label is changed, the new label has to be unique within the containing division, or an error gets thrown 🚫. also, if the id refers to the root element of the table of contents, then using this method is equivalent to using the method label — i.e. you're accessing the global label for the whole table. two roads, same destination ✨
  • objectName description id ?newdesc? — queries and/or changes the description of the element identified by the handle id. if the argument newdesc is present, the description gets changed to that value. regardless of that, the result of the method is the current value of the description. one big rule though: the element this method operates on has to be a reference element — otherwise, error, and we throw it 😤
  • objectName document id ?newdocid? — queries and/or changes the document reference of the element identified by the handle id. if the argument newdocid is present, that value becomes the new document reference. regardless of that, the result of the method is the current value of the document reference. now here's the tea: setting the reference to the empty string means unsetting it, and that's allowed only for division elements 🍓. conversely, if the result comes back as the empty string, then the element has no document reference — and that can happen only for division elements. symmetrical, iconic, we love to see it.
  • objectName title — returns the currently defined title of the table of contents. just the title, nothing else 🎀
  • objectName title text — sets the title of the table of contents to text, and returns it as the result of the command. sets and returns, efficient queen 👑
  • objectName label — returns the currently defined label of the table of contents.
  • objectName label text — sets the label of the table of contents to text, and returns it as the result of the command. same energy as title text 💜
  • objectName importer — returns the import manager object currently attached to the container — if any. if there isn't one, you get nothing, don't be dramatic 🙈
  • objectName importer object — attaches object as import manager to the container, and returns it as the result of the command. ⚠️ big note: the object is not put into ownership of the container. i.e., destroying the container will not destroy the object. it's attached, not adopted. it is expected that object provides a method named import text which takes a text and a format name, and returns the canonical serialization of the table of contents contained in the text, assuming the given format 🧚
  • objectName exporter — returns the export manager object currently attached to the container — if any. same deal as importer, if there's none, there's none 🌈
  • objectName exporter object — attaches object as export manager to the container, and returns it as the result of the command. ⚠️ same warning, bestie: the object is not put into ownership of the container. i.e., destruction of the container will not destroy the object. it is expected that object provides a method named export object which takes the container and a format name, and returns a text encoding the table of contents stored in the container, in the given format. it is further expected that the object will use the container's method serialize to obtain the serialization of the table of contents from which to generate the text 🔥 (yes, that's a whole lot of expectations, but the exporters know what they signed up for)
  • objectName deserialize = data ?format? — note the = sitting right there in the method name, it's giving assignment 😌 this method replaces the contents of the table object with the table contained in data. if no format was specified, it's assumed to be the regular serialization of a table of contents. otherwise the object will use the attached import manager to convert the data from the specified format into a serialization it can actually handle. and in that case, an error gets thrown if the container has no import manager attached to it 🚫. the result of the method is the empty string.
  • objectName deserialize += data ?format? — the += twin 🫶 behaves like deserialize = in its essentials, except that instead of replacing, it merges the table of contents in data into its contents. the method will throw an error if merging is not possible, i.e. if it would produce an invalid table — and in that case, the existing content is left unchanged. no half-merges, no mess, we respect that. the result of the method is the empty string.
  • objectName serialize ?format? — returns the table of contents contained in the object. if you don't specify a format, 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 — and in that case, an error will be thrown if the container has no export manager attached to it. 💀
ok that was a LOT of methods but look at you, still here, still reading. certified doc girlie behavior honestly 🎀

✨ TOC SERIALIZATION FORMAT ✨

Okay bestie, here's the tea on how the doctools v2 packages serialize tables of contents as immutable values for transport, comparison, etc. 💖 We're talking regular vs canonical serializations. A table of contents may have more than one regular serialization, but only exactly one of them will be canonical. No cap. 🧚

regular serialization

  1. [1] The serialization of any table of contents is a nested Tcl dictionary. ✨
  2. [2] This dictionary holds a single key, doctools::toc, and its value. This value holds the contents of the table of contents. 🔑
  3. [3] The contents of the table of contents are a Tcl dictionary holding the title of the table of contents, a label, and its elements. The relevant keys and their values are:
    • title — The value is a string containing the title of the table of contents. 👑
    • label — The value is a string containing a label for the table of contents. 🏷️
    • items — The value is a Tcl list holding the elements of the table, in the order they are to be shown. 🎀

Each element is a Tcl list holding the type of the item, and its description, in this order. An alternative description would be that it is a Tcl dictionary holding a single key, the item type, mapped to the item description. 💅

The two legal item types and their descriptions are:

  • reference — This item describes a single entry in the table of contents, referencing a single document. To this end its value is a Tcl dictionary containing an id for the referenced document, a label, and a longer textual description which can be associated with the entry. The relevant keys and their values are:
    • id — The value is a string containing the id of the document associated with the entry. 🔗
    • label — The value is a string containing a label for this entry. This string also identifies the entry, and no two entries (references and divisions) in the containing list are allowed to have the same label. 🚫
    • desc — The value is a string containing a longer description for this entry. 📝
  • division — This item describes a group of entries in the table of contents, inducing a hierarchy of entries. To this end its value is a Tcl dictionary containing a label for the group, an optional id to a document for the whole group, and the list of entries in the group. The relevant keys and their values are:
    • id — The value is a string containing the id of the document associated with the whole group. This key is optional. 🫶
    • label — The value is a string containing a label for the group. This string also identifies the entry, and no two entries (references and divisions) in the containing list are allowed to have the same label. 🚫
    • items — The value is a Tcl list holding the elements of the group, in the order they are to be shown. This list has the same structure as the value for the keyword items used to describe the whole table of contents, see above. This closes the recusrive definition of the structure, with divisions holding the same type of elements as the whole table of contents, including other divisions. 🔁

canonical serialization

The canonical serialization of a table of contents 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 this table of contents. ✨

  1. [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. 🔤

🐛 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 [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. 💌

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, doctoc markup, documentation, formatting, generation, json, latex, markup, nroff, parsing, plugin, reference, table, table of contents, tcler's wiki, text, wiki

📂 CATEGORY 📂

Documentation tools

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

And that's the whole vibe, bestie. This page comes from tcllib version 2, manual page doctools::toc(3tcl). No date in the footer, just iconic energy. Stay slay. 💅✨

📦 where this page comes from