doctools::toc::structure(n)

💖 doctools::toc::structure 💖

okay bestie so picture this: it's a manual page, it's section n of the Documentation tools manual, and it's literally just doctools::toc::structure — the Doctoc serialization utilities. yes that's the whole name. slay.

---

✨ 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 this package hands you the commands for messing with the serializations of tables of contents — the kind the doctools system v2 manages, and the kind that's specified over in the section ToC serialization format. 💅

ngl it's an internal package of doctools. it's not out here for the general public, it's for the higher-level packages that handle tables of contents and convert them into and out of all the other formats, like documents written using doctoc markup. iykyk.

---

👑 API 👑

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

okay so this one verifies that whatever's inside serial is a valid regular serialization of a table of contents. if it's not? it throws an error, periodt. and if it is valid, the result of the command is the empty string. 🫶

and listen, if you pass the canonvar argument, it gets read 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. its value is a boolean:

• True — the serialization isn't just valid, it's also canonical ✨
• False — it's valid, but non-canonical 😭

for the full spec of regular vs canonical serializations, go check the section ToC serialization format.

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

same energy as above but stricter, bestie. this one verifies that the content of serial is a valid canonical serialization of a table of contents, and it throws an error if that's not the case. result is the empty string. 💅

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

💜 ::doctools::toc::structure canonicalize serial

this command assumes the content of serial is a valid regular serialization of a table of contents, and it will throw an error if that's not the case. no cap.

then it converts the input into the canonical serialization of the contained table of contents and returns that as its result. and if the input was already canonical? it comes back unchanged. iconic behavior honestly. 🎀

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

💜 ::doctools::toc::structure print serial

this one assumes the argument serial contains a valid regular serialization of a table of contents, and it returns a string holding that table in a human readable form. 🦋

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

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

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

this accepts the regular serializations of two tables of contents and uses them to create their union. the result is the canonical serialization of this unified table of contents. 🌈

Title and label of the resulting table are taken from the table contained in serialb.

the whole table and its divisions get merged recursively, in the same manner:

1. All reference elements which occur in both divisions (identified by their label) are unified with document id's and descriptions taken from the second table.
2. All division elements which occur in both divisions (identified by their label) are unified with the optional document id taken from the second table, if any, or from the first if none is in the second. The elements in the division are merged recursively using the same algorithm as described in this list.
3. Type conflicts between elements — i.e. finding two elements with the same label but different types — result in a merge error. 💀
4. All elements found in the second division but not in the first are added to the end of the list of elements in the merge result.

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

---

🧚 TOC SERIALIZATION FORMAT 🧚

here we specify the format the doctools v2 packages use to serialize tables of contents as immutable values for transport, comparison, etc. ⭐

we distinguish between regular and canonical serializations. a table of contents may have more than one regular serialization, but only exactly one of them will be canonical. the way that math works out is lowkey beautiful.

🌸 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. This 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 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 items 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. 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 🐛

ok so real talk bestie, this doc — and honestly the whole package it's describing — will have bugs. like, guaranteed. it's giving "software, babes". no cap. so if you find something cursed in there, pls pls pls report it 💖

• head over to the doctools category in the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist
• got a genius idea for making the package better? or the docs better? or both?? 👑 drop that in too, ideas are literally always welcome

---

💅 if you're proposing code changes

ok so when you send in code changes, bestie, send them as unified diffs. that means the output of:

diff -u

periodt. that's the format. don't be mysterious about it 🙈

⭐ also important: attachments are strongly preferred over inlined patches. fr fr. you can attach stuff by going to the Edit form of the ticket right after you create it, then clicking the left-most button in the secondary navigation bar. that's the one. the left-most one. iykyk 🎀

---

🔑 KEYWORDS 🔑

the vibe words for this page, bestie:

• deserialization
• doctoc
• doctools
• serialization

---

📁 CATEGORY 📁

Documentation tools — that's the little folder this whole thing lives in ✨

---

©️ COPYRIGHT ©️

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

like, respect the icon who wrote it, okay? 👑

---

and that's a wrap on doctools::toc::structure(n) 💜 this came to you from the tcllib girlies, version 0.2 — slay, go forth, and may your TOCs deserialize flawlessly 🦋🌸