doctools:...port::json(3tcl)

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

💖 doctools:...port::json(3tcl) 💖

okay so you clicked into doctools:...port::json(3tcl) — that's the Documentation tools manual, section 3tcl — and bestie, we are gonna get you fluent in this. it's a JSON export plugin, it's lowkey iconic, and it's the first half of a two-parter so buckle up. 🦋

✨ NAME ✨

doctools::toc::export::json — the JSON export plugin. that's it, that's the whole name. periodt. 💅

🎀 SYNOPSIS 🎀

package require Tcl 8.5 9

package require doctools::toc::export::json ?0.2?

package require textutil::adjust

export serial configuration

🌸 DESCRIPTION 🌸

okay so this package implements the doctools table of contents export plugin for the generation of JSON markup. it's giving "I turn your ToC into JSON," and it does exactly that. no cap. ✨

ngl, this is an internal package of doctools — it's meant for the higher level management packages that handle tables of contents, especially doctools::toc::export, the export manager. so it's the backstage crew, not the main character. 🙈

and like — yes, technically you could use it straight from a regular interpreter. the manual says it's "possible", but only with contortions, and it is not recommended. 💀 so pls don't. the proper way to use this functionality is through the package doctools::toc::export and the export manager objects it provides. that's the vibe check you should actually pass. 🫶

💜 API 💜

the API provided by this package satisfies the specification of the doctoc export plugin API version 2. so it's compliant, it's well-behaved, it ate. 👑

  • export serial configuration — this command takes the canonical serialization of a table of contents (as specified down in the section ToC serialization format), and it's contained in serial; plus the configuration, which is a dictionary; and it generates JSON markup encoding the table. the created string then gets returned as the result of the command. so: in goes serial + config, out comes JSON. 💖

🌈 JSON NOTATION OF TABLES OF CONTENTS 🌈

so the JSON format used for tables of contents is a direct translation of the ToC serialization format, and the mapping is chef's kiss simple: Tcl dictionaries → JSON objects, Tcl lists → JSON arrays. that's the whole vibe. 🧚

for example, this Tcl serialization:

doctools::toc {
    items {
        {reference {
      desc {DocTools - Tables of Contents}
       id introduction.man
       label doctools::toc::introduction
  }}
  {division {
       id processing.man
       items {
           {reference {
          desc {doctoc serialization utilities}
          id structure.man
          label doctools::toc::structure
      }}
      {reference {
          desc {Parsing text in doctoc format}
          id parse.man
          label doctools::toc::parse
      }}
       }
             label Processing
        }}
    }
    label {Table of Contents}
    title TOC
}

is equivalent to this JSON string:

{
    "doctools::toc" : {
        "items" : [{
            "reference" : {
                "desc"  : "DocTools - Tables of Contents",
                "id"    : "introduction.man",
                "label" : "doctools::toc::introduction"
            }
        },{
            "division" : {
                "id"    : "processing.man",
                "items" : [{
                    "reference" : {
                        "desc"  : "doctoc serialization utilities",
                        "id"    : "structure.man",
                        "label" : "doctools::toc::structure"
                    }
                },{
                    "reference" : {
                        "desc"  : "Parsing text in doctoc format",
                        "id"    : "parse.man",
                        "label" : "doctools::toc::parse"
                    }
                }],
                "label" : "Processing"
            }
        }],
        "label" : "Table of Contents",
        "title" : "TOC"
    }
}

like. look at it. the glow-up is real. 💅✨

🎀 CONFIGURATION 🎀

the JSON export plugin recognizes the following configuration variables, and it changes its behaviour as they specify. so you get to steer the vibe. 🌸

  • boolean indented — if this flag is set, the plugin will break the generated JSON code across lines and indent it according to its inner structure, with each key of a dictionary on a separate line. if this flag is not set (that's the default), the whole JSON object gets written on a single line, with minimum spacing between all elements. so: pretty vs. compact, pick your fighter. 🦋
  • boolean aligned — if this flag is set, the generator makes sure the values for the keys in a dictionary are vertically aligned with each other, for a nice table effect. to make that work, this also implies that indented is set — so it's a package deal, no solo acts. if this flag is not set (the default), the output is formatted as per the value of indented, without trying to align the values for dictionary keys. 🫶
heads up bestie: this plugin ignores the standard configuration variables user, format, file, and map — and their values too. it's just not listening to those. 🙈

👑 TOC SERIALIZATION FORMAT 👑

here's where we specify the format used by the doctools v2 packages to serialize tables of contents as immutable values for transport, comparison, etc. so it's the canonical lore. 📜

we distinguish between regular and canonical serializations. while a table of contents may have more than one regular serialization, only exactly one of them will be canonical. main character energy, but make it unique. 👑

💜 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. so no duplicate labels, fr fr. 🙅
    • 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. same rule as above, it's giving consistent. 💅
    • 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 recursive definition of the structure, with divisions holding the same type of elements as the whole table of contents — including other divisions. so it's turtles all the way down. 🐢✨

🦋 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. it's the one. the chosen 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.

💀 BUGS, IDEAS, FEEDBACK 💀

Okay bestie, real talk. This doc? And the whole package it's describing? They will undoubtedly contain bugs and other problems. Like, it's not a vibe, it's just how software is. 😭

So if you find something cursed, please report it in the category doctools of the Tcllib Trackers over at http://core.tcl.tk/tcllib/reportlist. And not just bugs — if you have ideas for enhancements for either the package and/or the documentation, send those too. We want them. Fr fr. 🫶

When proposing code changes, please provide unified diffs, i.e the output of diff -u. No screenshots of your editor, no vibes-only descriptions. The diff. That's the assignment. ✨

Also — and this is important, so pay attention — attachments are strongly preferred over inlined patches. Like, strongly. 💅

How do you attach stuff? Easy: go to the Edit form of the ticket right after you create it, then use the left-most button in the secondary navigation bar. That's the one. That's the button. You got this. 🎀

🔑 KEYWORDS 🔑

Here's the tag cloud, bestie, so you can find this page again:

  • JSON
  • doctools
  • export
  • serialization
  • table of contents
  • toc

📚 CATEGORY 📚

Text formatter plugin

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

And that's a wrap on part 2, my love 🦋💜 This gorgeous little page came to you from tcllib, version 0.2, and it's the doctools::...port::json manual — that's doctools json export energy, section 3tcl, the plugin corner of the docs. Go forth and serialize those tables of contents, queen. Periodt. 👑🌸

📦 where this page comes from