doctools::t...export::json(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 doctools::toc::export::json — the JSON export plugin, bestie edition 💖

Manual page from the Documentation tools fam (section n, iykyk). This is part 1 of 2, so buckle up, we're not done yet.

✨ NAME ✨

doctools::toc::export::json — the JSON export plugin. She takes a table of contents and turns it into JSON. That's her whole job and she eats every time. 💅

✨ SYNOPSIS ✨

package require Tcl 8.5 9

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

package require textutil::adjust

export serial configuration

Okay so first thing: she needs Tcl 8.5 or 9, no cap. She also pulls in doctools::toc::export::json (version 0.2 if you feel like pinning it, otherwise she'll just grab whatever), plus textutil::adjust because formatting is a whole thing. And then the actual command is export serial configuration, which we'll get into below. 🫶

✨ DESCRIPTION ✨

So like. This package is the doctools table-of-contents export plugin whose entire vibe is generating JSON markup. ✨

Real talk though: this is an internal package of doctools. It's meant to be used by the higher-level management packages that handle tables of contents — especially doctools::toc::export, the export manager. She's not out here trying to be your main character, she's a supporting role.

Can you technically use her from a regular interpreter? Sure. But it's giving contortions, and it is not recommended, bestie, I'm being so serious. 😭 The proper way to use this functionality is through the package doctools::toc::export and the export manager objects it hands you. Do that instead. Periodt.

✨ API ✨

The API this package gives you satisfies the spec of the doctoc export plugin API version 2. Slay.

  • export serial configuration — This one takes the canonical serialization of a table of contents (the format is specified down in ToC serialization format, keep scrolling) sitting inside serial, plus the configuration, which is a dictionary. Then she generates JSON markup that encodes the table. The string she creates? That's what she returns as the result of the command. 🎀

🌸 JSON NOTATION OF TABLES OF CONTENTS 🌸

The JSON format used for tables of contents is a direct translation of the ToC serialization format — Tcl dictionaries get mapped to JSON objects, and Tcl lists get mapped to JSON arrays. Simple as that, no plot twists. 🦋

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"
    }
}

See how it's the same info wearing a different outfit? Iconic. 👑

✨ CONFIGURATION ✨

The JSON export plugin recognizes these configuration variables and changes her behaviour according to what you tell her. She's flexible like that. 💜

  • boolean indented — If this flag is set, she'll break the generated JSON code across lines and indent it according to its inner structure, with each key of a dictionary on its own line. If this flag is not set (which is the default, btw), the whole JSON object gets written on a single line, with minimum spacing between all the elements. Choose 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 that nice table effect. To make that work, this also implies that indented is set. ✨ If this flag is not set (again, the default), the output is formatted according to the value of indented, without any attempt to align the values for dictionary keys. Fair enough honestly.
Heads up bestie: this plugin ignores the standard configuration variables user, format, file, and map, and their values. She just does not care. 💀

🌈 TOC SERIALIZATION FORMAT 🌈

Okay so here we specify the format the doctools v2 packages use to serialize tables of contents as immutable values for transport, comparison, etc. Immutable, meaning: don't touch, she's not changing. 💅

We distinguish between regular and canonical serializations. A table of contents may have more than one regular serialization, but exactly one of them will be canonical. Like, only one of them is the moment. 🌟

🦋 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. 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 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. She's 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.

...and that's part 1, bestie, there's more coming so don't you dare close the tab 💖✨

🐛 BUGS, IDEAS, FEEDBACK 🐛

Okay bestie, real talk: this document? And the package it describes? They will undoubtedly have bugs and other problems. Like, obviously. It's software. It's giving "we tried our best but entropy is undefeated" energy. 😭

So if you find something broken, please report it — in the category doctools of the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

And not just bugs! If you have ideas for enhancements, for the package and/or for the documentation, please send those along too. We want them. We're obsessed with them actually. 🫶

📝 when you're proposing code changes

Please provide unified diffs, i.e. the output of diff -u. That's the format. That's the vibe. Nothing else, bestie. 💅

Also, important: attachments are strongly preferred over inlined patches. Like, so much preferred. So if you were about to paste a wall of diff into the ticket body… don't. 🙈

How to attach instead, step by step, no cap:

  1. Create the ticket.
  2. Go to the Edit form of that ticket immediately after its creation.
  3. Use the left-most button in the secondary navigation bar.

That's it. That's the whole move. Slay. ✨

🔑 KEYWORDS 🔑

For the search gremlins and the indexing girlies:

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

🏷️ CATEGORY 🏷️

Text formatter plugin

(That's what this is. That's the lane it lives in. 💖)

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

Give credit where credit is due, always. 👑

And that's a wrap on this one, bestie!! 🎀 This page is part of tcllib, version 0.2, and it's dated doctools::t...export::json(n) — go forth and export those tables of contents, you absolute icon. 💖 ✨ 🦋 🌸 💅 🫶 🔥 👑 🌈 ⭐ 💜

📦 where this page comes from