doctoc_lang_cmdref(n)

💖 doctoc_lang_cmdref — the doctoc language command reference 💖

okay bestie, welcome to doctoc_lang_cmdref(n), living in the Documentation tools section of the manual. this is the whole entire command reference for doctoc markup language, version 1. pull up a chair, grab a strawberry 🍓, we're doing this.

---

✨ SYNOPSIS ✨

comment plaintext

division_end

division_start text ?symfile?

include filename

item file text desc

lb

rb

toc_begin text title

toc_end

vset varname value

vset varname

---

🌸 DESCRIPTION 🌸

so this doc is the reference, and what it does is lay out both the names and the syntax of literally every single command that together make up the doctoc markup language, version 1. periodt. 💅

because it's a reference and not a vibe-y tutorial, the commands are listed in alphabetical order and the descriptions are kept relatively short. no fluff, all facts, iykyk.

if you're a beginner, bestie, please do yourself a favour and read the much more informally written doctoc language introduction first. this page is the cheat sheet, not the lesson. 🫶

---

👑 COMMANDS 👑

• comment plaintext — Toc markup. the argument text gets marked up as a comment that stands outside the actual text of the document. main use case is free-form text. it's giving side-quest energy. ✨
• division_end — Toc structure. this one closes the division that was opened by the last division_begin command coming before it, as long as that division hasn't been closed yet. last-in, first-out, no cap.
• division_start text ?symfile? — Toc structure. opens a division in the table of contents. its counterpart is division_end. together they let a user give a table of contents some extra structure. 🦋
  • the title of the new division is provided by the argument text.
  • if the symbolic filename symfile is present, then the section title should link to the referenced document — but only if links are supported by the output format. no promises otherwise, bestie.
• include filename — Templating. the contents of the named file get interpreted as text written in the doctoc markup and processed right in the place of the include command. the markup in that file has to be self-contained. it is not possible for a markup command to cross the file boundaries. so no starting a command in one file and finishing it in another. that's a hard no. 💀
• item file text desc — Toc structure. adds an individual element to the table of contents. each such element refers to a document. the document is specified through the symbolic name file. the text argument is used to label the reference, whereas desc provides a short descriptive text of that document.
  • the symbolic names are what preserve the convertibility of this format to any output format. the actual name of the file gets inserted by the chosen formatting engine when it converts the input — and that's based on a mapping from symbolic to actual names given to the engine. so like, you write the nickname, the engine writes the government name. 💅
• lb — Text. this command is replaced with a left bracket. use it in free-form text. it's required to avoid interpretation of a left bracket as the start of a markup command. its usage is restricted to the arguments of other markup commands. tiny but mighty. 🎀
• rb — Text. this command is replaced with a right bracket. use it in free-form text. required to avoid interpretation of a right bracket as the end of a markup command. its usage is restricted to the arguments of other commands. the matching set, we love symmetry. ✨
• toc_begin text title — Document structure. the command to start a table of contents. the arguments are a label for the whole group of documents the index refers to (text) and the overall title text for the index (title), without markup.
  • that label is often the name of the package (or extension) that the documents belong to. iconic.
• toc_end — Document structure. the command to end a table of contents. anything in the document coming after this command is in error. 🚨 like, do not pass go.
• vset varname value — Templating. in this form the command sets the named document variable to the specified value. it does not generate output — i.e. the command is replaced by the empty string. sneaky, invisible, powerful.
• vset varname — Templating. in this form the command is replaced by the value of the named document variable. that's it, that's the whole trick. 🧚

---

😭 BUGS, IDEAS, FEEDBACK 😭

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. like, it's software, bestie. 💀

please report such things in the category doctools of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. and please also report any ideas for enhancements you may have for either the package and/or the documentation. we want the glow-up, we need your input. 🫶

when proposing code changes, please provide unified diffs, i.e. the output of diff -u. that's the format. that's the assignment. ✨

also note — and this is important — attachments are strongly preferred over inlined patches. you can make an attachment 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. okay? okay. 💖

---

🌈 SEE ALSO 🌈

• doctoc_intro
• doctoc_lang_faq
• doctoc_lang_intro
• doctoc_lang_syntax

the whole friend group, go say hi. 🦋

---

⭐ KEYWORDS ⭐

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

---

🎀 CATEGORY 🎀

Documentation tools

---

💜 COPYRIGHT 💜

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

---

and that's the whole page, bestie! 🥳 this was doctoc_lang_cmdref(n) from tcllib, version 1.0, filed under Documentation tools — thanks for reading all the way to the end, you're literally the main character. mwah. 💅💖✨