doctoc_lang_intro(3tcl)

💖 NAME 💖

doctoc_lang_intro — it's the doctoc language introduction, bestie. Manual section 3tcl, and it lives under the Documentation tools umbrella. 🎀

---

🌸 DESCRIPTION 🌸

Okay so. This doc is an informal intro to version 1.1 of the doctoc markup language, and it teaches you by throwing a whole bunch of examples at you. Read it and you'll be ready to handle the two halves of the actual formal spec — that's the doctoc language syntax specification and the doctoc language command reference. Slay. 💅

🧚 FUNDAMENTALS 🧚

So doctoc markup is kinda similar to doctools markup if you squint really hard, but there's one big difference, and it's the whole vibe:

A table of contents is basically only markup commands. No plain text sprinkled between them — except whitespace. That's it. That's the tea. 🍓

Every markup command is a Tcl command, wrapped in a matching pair of [ and ]. Inside those delimiters, all the usual Tcl command rules apply — word quotation, nested commands, continuation lines, the whole thing. I.e.

... [division_start {Appendix 1}] ...

... [item thefile \
        label {file description}] ...

🦋 BASIC STRUCTURE 🦋

The absolute most simple doc you can write in doctoc is:

[toc_begin GROUPTITLE TITLE]
[toc_end]

And this right here tells you the whole deal: every doctoc document has only one part, and in it we list items and divisions. Periodt.

You're free to mix them however you want. This is a change from version 1 of the language, which did not let you mix — back then you had to pick either a series of items or a series of divisions. Not both. Tragic, honestly. 😭

Next two sections? We go through the commands for each of these two possibilities.

🌈 ITEMS 🌈

Use the item command to put an item into a table of contents. It's basically a reference to a section, subsection, etc., inside the document (or set of documents) that this table of contents is for. The command takes three arguments: a symbolic name for the file the item is for, plus two bits of text to label the item and describe the referenced section. ✨

Why symbolic names? To preserve the convertibility of this format to any output format, bestie. The actual name of any file gets inserted by whichever formatting engine does the conversion, based on a mapping from symbolic names to actual names that you hand to the engine. iykyk.

Here's a made-up example, a table of contents for this very document:

[toc_begin Doctoc {Language Introduction}]
[item 1 DESCRIPTION]
[item 1.1 {Basic structure}]
[item 1.2 Items]
[item 1.3 Divisions]
[item 2 {FURTHER READING}]
[toc_end]

💜 DIVISIONS 💜

One thing to notice in that last example: the referenced sections actually had a nested structure, and we expressed that in the item labels by using a common prefix for everything nested under section 1. Cute, but we can do better.

doctoc makes that structure more explicit with divisions. Instead of a series of plain items, you use a series of divisions for the major references, and then you drop the nested items inside them. 💅

And of course, instead of nested items you can use divisions again — so you can nest as deep as your heart desires. 🌀

A division is marked by two commands instead of one: one to start it, one to close the last opened division.

• division_start — opens a new division. Takes one or two arguments: the title of the division, and the symbolic name of the file it refers to. That second one is optional. If the symbolic filename is there, then the section title should link to the referenced document — assuming the output format supports links at all.
• division_end — closes the last opened and not-yet-closed division.

With that, we can recast the previous example like this:

[toc_begin Doctoc {Language Introduction}]
[division_start DESCRIPTION]
[item 1 {Basic structure}]
[item 2 Items]
[item 3 Divisions]
[division_end]
[division_start {FURTHER READING}]
[division_end]
[toc_end]

Or, to demonstrate deeper nesting:

[toc_begin Doctoc {Language Introduction}]
[division_start DESCRIPTION]
[division_start {Basic structure}]
[item 1 Do]
[item 2 Re]
[division_end]
[division_start Items]
[item a Fi]
[item b Fo]
[item c Fa]
[division_end]
[division_start Divisions]
[item 1 Sub]
[item 1 Zero]
[division_end]
[division_end]
[division_start {FURTHER READING}]
[division_end]
[toc_end]

And do not forget — you can freely mix items and divisions, and you can absolutely have empty divisions:

[toc_begin Doctoc {Language Introduction}]
[item 1 Do]
[division_start DESCRIPTION]
[division_start {Basic structure}]
[item 2 Re]
[division_end]
[item a Fi]
[division_start Items]
[item b Fo]
[item c Fa]
[division_end]
[division_start Divisions]
[division_end]
[division_end]
[division_start {FURTHER READING}]
[division_end]
[toc_end]

⭐ ADVANCED STRUCTURE ⭐

Okay so in all the previous examples we fudged it a little regarding what markup is actually allowed before the toc_begin command that opens the document. 🙈

Turns out it's not just whitespace. The two templating commands include and vset are also allowed, so a writer can set and/or import configuration settings relevant to the table of contents. I.e. you can write:

[include FILE]
[vset VAR VALUE]
[toc_begin GROUPTITLE TITLE]
...
[toc_end]

Even more important: these two commands are allowed anywhere a markup command is allowed, with no regard for any other structure.

[toc_begin GROUPTITLE TITLE]
[include FILE]
[vset VAR VALUE]
...
[toc_end]

The one restriction include has to obey: the contents of the included file must be valid at the place of the inclusion. I.e. a file included before toc_begin may contain only the templating commands vset and include; a file included in a division may contain only items or divisions commands, etc. No sneaking nonsense in, okay? 👑

🔥 ESCAPES 🔥

Beyond the 6 commands we've shown so far, there are two more. But their job isn't marking up toc structure — it's inserting characters, namely [ and ]. Those commands are lb and rb respectively, and we need them because using [ and ] to bracket markup commands makes it impossible to directly use [ and ] inside text. Big brain problems require big brain solutions. 💀

Here's our example of using them — it's the source of the last sentence in the previous paragraph, with a little highlighting added:

...
These commands, [cmd lb] and [cmd lb] respectively, are required
because our use of [lb] and [rb] to bracket markup commands makes it
impossible to directly use [lb] and [rb] within the text.
...

---

🌟 FURTHER READING 🌟

Now that you've digested this, you (the reader, assumed to be a writer of documentation) should be fortified enough to understand the formal doctoc language syntax specification too. From here on out, the doctoc language command reference is also gonna be your detailed spec and your cheat sheet for every available command and its syntax. 🫶

Also, if you want to validate a document while you're writing it, go get familiar with Tclapps' ultra-configurable dtp. Highly recommend.

On the other hand — doctoc is perfectly suited for automatic generation from doctools documents, and that's exactly the route Tcllib's easy and simple dtplite takes: it creates a table of contents for a set of documents behind the scenes, no writer effort required. Main character behavior, honestly. 👑

💀 BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report them in the category doctools of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist. Also please report any ideas for enhancements you may have for either the package and/or the documentation. We wanna hear it. ✨

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. You can make attachments 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. 🌸

🦋 SEE ALSO 🦋

• doctoc_intro
• doctoc_lang_cmdref
• doctoc_lang_syntax

🎀 KEYWORDS 🎀

doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup, semantic markup

💖 CATEGORY 💖

Documentation tools

🌈 COPYRIGHT 🌈

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

---

And that's the whole thing, bestie — this was tcllib 1.0, doctoc_lang_intro(3tcl), and honestly? It ate. Go write some tables of contents. 💅✨