doctools::...:structure(3tcl)

🎀 doctools::...:structure 🎀

okay bestie, gather round, because this is the manual page for doctools::...:structure from the Documentation tools crew, and it's a whole vibe. it's a <pink>3tcl</pink> page, it's long, and this is part 1 of 2, so hydrate and lock in 💖

---

✨ NAME ✨

doctools::toc::structure — Doctoc serialization utilities 🦋

---

✨ SYNOPSIS ✨

package require doctools::toc::structure ?0.2?

package require Tcl 8.5 9

package require logger

package require snit

::doctools::toc::structure verify serial ?canonvar?

::doctools::toc::structure verify-as-canonical serial

::doctools::toc::structure canonicalize serial

::doctools::toc::structure print serial

::doctools::toc::structure merge seriala serialb

---

✨ DESCRIPTION ✨

so basically 💅 this package hands you commands for messing with the serializations of tables of contents — the ones managed by the doctools system v2, and spelled out in the ToC serialization format section down below. no cap.

and listen — this is an internal package of doctools. it exists for the higher-level packages that deal with tables of contents and convert them in and out of all sorts of other formats, like documents written with doctoc markup. so if you're just out here living your best life, this is probably not the one you reach for directly, iykyk 🌸

---

✨ API ✨

• ::doctools::toc::structure verify serial ?canonvar? — this one does a vibe check on serial ✨ it makes sure the content is a valid regular serialization of a table of contents, and if it's not? it throws an error, periodt. if everything's good, the result of the command is the empty string.

now if you also pass the argument canonvar, it gets treated as the name of a variable in the calling context. that variable gets written to if and only if serial is a valid regular serialization. the value written is a boolean: True means the serialization isn't just valid, it's also canonical. False means it's valid but not canonical.

for the full spec of regular vs canonical serializations, go peek at the ToC serialization format section 🫶

• ::doctools::toc::structure verify-as-canonical serial — same energy but stricter 💅 this command verifies that the content of serial is a valid canonical serialization of a table of contents, and throws an error if it isn't. result is the empty string.

for the spec of canonical serializations, see the ToC serialization format section.

• ::doctools::toc::structure canonicalize serial — this one assumes the content of serial is a valid regular serialization of a table of contents, and it will throw an error if that assumption is a lie 😭

then it converts the input into the canonical serialization of the table of contents inside it and returns that as its result. and if the input was already canonical? it just hands it back unchanged, no notes. iconic.

for the spec of regular and canonical serializations, see the ToC serialization format section.

• ::doctools::toc::structure print serial — this one assumes the argument serial holds a valid regular serialization of a table of contents, and it returns a string with that table in a human readable form 🌈

heads up bestie: the exact format of that human-readable form is not specified, and you absolutely cannot rely on it for parsing or any other machine-based activities. it's for eyeballs only, fr fr.

for the spec of regular serializations, see the ToC serialization format section.

• ::doctools::toc::structure merge seriala serialb — takes the regular serializations of two tables of contents and uses them to build their union. the result is the canonical serialization of that unified table of contents. slay.

the title and label of the resulting table come from the table inside serialb.

the whole table and its divisions get merged recursively, same algorithm all the way down:

1. all reference elements that show up in both divisions (matched up by their label) are unified, with the document ids and descriptions taken from the second table.
2. all division elements that show up in both divisions (again matched by their label) are unified, with the optional document id taken from the second table if it's there, or from the first if the second doesn't have one. the elements inside the division get merged recursively using the very same algorithm described in this list 🌀
3. type conflicts between elements — like finding two elements with the same label but different types — result in a merge error. no merging your way out of that one 💀
4. all elements found in the second division but not in the first get added to the end of the list of elements in the merge result.

for the spec of regular and canonical serializations, see the ToC serialization format section.

---

✨ TOC SERIALIZATION FORMAT ✨

here's where we spell out the format the doctools v2 packages use to serialize tables of contents as immutable values — for transport, comparison, all of that 🎀

we keep two flavors apart: regular and canonical serializations. a table of contents can have more than one regular serialization, but exactly one of them is canonical. one. singular. main character energy only 👑

🌸 regular serialization 🌸

1. the serialization of any table of contents is a nested Tcl dictionary.
2. this dictionary holds a single key, doctools::toc, and its value. that value holds the contents of the table of contents.
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 that order. another way to say it: it's 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 that end its value is a Tcl dictionary containing an id for the referenced document, a label, and a longer textual description that 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 that 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 items 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. and that right there closes the recursive definition of the structure ✨ — divisions hold the same type of elements as the whole table of contents, including other divisions. it's turtles all the way down bestie 🐢

🌸 canonical serialization 🌸

the canonical serialization of a table of contents has the format 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. one of 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.

---

okay that's the format, and we're not done yet — there's more page coming, so don't go anywhere bestie 🫶

🐛 BUGS, IDEAS, FEEDBACK 💌

okay bestie, real talk: this document and the package it describes will undoubtedly contain bugs and other problems. like, it's software, it's giving humble, not perfect. 🙈

so if you find something cursed, please report it in the category doctools of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. 🫶

and if you've got ideas for enhancements for either the package and/or the documentation? please also send those in. we want them fr fr. ✨

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

💀 also note: attachments are strongly preferred over inlined patches. no cap. you can attach stuff 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. it's giving "the button is right there" energy.

---

🔑 KEYWORDS

• deserialization
• doctoc
• doctools
• serialization

---

🗂️ CATEGORY

Documentation tools

---

©️ COPYRIGHT

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

---

and that's a wrap on this one, bestie 🎀 this was doctools::...:structure(3tcl) from tcllib, version 0.2 — go forth and serialize your tables of contents responsibly 💅✨