doctoc_lang_syntax(n)

🎀 doctoc_lang_syntax(n) — the doctoc language syntax, bestie edition 🎀

okay so you found the manual page called doctoc_lang_syntax(n) and it lives in the Documentation tools section of the manual. she's a whole reference doc, no cap. let's get into it 💖

---

✨ NAME ✨

doctoc_lang_syntax — doctoc language syntax. that's it, that's the name, she's literal 💅

---

🌸 DESCRIPTION 🌸

so this document is the formal specification of the syntax of the doctoc markup language, version 1.1, written in Backus-Naur-Form. it's giving reference material, and it's meant to complement the doctoc language command reference — like, they're besties, they hold hands 🤝

real talk though: if you're a beginner, read the much more informally written doctoc language introduction first before you try to understand either this document or the command reference. this one is highkey not the vibe for a first date, okay? do yourself a favor 🫶

---

🦋 FUNDAMENTALS 🦋

in the broadest terms possible, the doctoc markup language is like SGML and similar languages. a document written in this language consists primarily of markup commands, with text embedded into it at some places. so it's commands with little text sprinkles, not text with little command sprinkles. noted ✨

each markup command is just a Tcl command surrounded by a matching pair of [ and ]. which commands are available, and their arguments, i.e. syntax — all of that is specified in the doctoc language command reference. not here. go read that one for the deets 📚

in this document we specify first the lexeme, and then the syntax, i.e. how we can mix text and markup commands with each other. lexemes first, then the mixing. order matters bestie 🧚

---

💜 LEXICAL DEFINITIONS 💜

so in the syntax rules listed in the next section:

1. <TEXT> stands for all text except markup commands.
2. Any XXX stands for the markup command [xxx] including its arguments. each markup command is a Tcl command surrounded by a matching pair of [ and ]. inside of these delimiters the usual rules for a Tcl command apply with regard to word quotation, nested commands, continuation lines, etc.
3. <WHITE> stands for all text consisting only of spaces, newlines, tabulators and the comment markup command.

---

🌈 SYNTAX 🌈

the rules listed here specify only the syntax of doctoc documents. the lexical level of the language was covered in the previous section, so don't come for me if you skipped it 🙈

regarding the syntax of the (E)BNF itself

1. The construct { X } stands for zero or more occurrences of X.
2. The construct [ X ] stands for zero or one occurrence of X.

the syntax

toc       = defs
            TOC_BEGIN
            contents
            TOC_END
            { <WHITE> }

defs      = { INCLUDE | VSET | <WHITE> }
contents  = { defs entry } [ defs ]

entry     = ITEM | division

division  = DIVISION_START
            contents
            DIVISION_END

like, look at her go 👑 that's the whole grammar, and yes she is iconic for it.

---

💀 BUGS, IDEAS, FEEDBACK 💀

this document, and the package it describes, will undoubtedly contain bugs and other problems. not me being honest about it but here we are 😭

please report such in the category doctools of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. please also report any ideas for enhancements you may have for either package and/or documentation. we love ideas, fr fr 💖

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. attachments can be made 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. do it that way, bestie, it's the move ✨

---

🍓 SEE ALSO 🍓

• doctoc_intro
• doctoc_lang_cmdref
• doctoc_lang_faq
• doctoc_lang_intro

go read these too, they're the friend group 🌸

---

⭐ KEYWORDS ⭐

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

---

👑 CATEGORY 👑

Documentation tools

---

💅 COPYRIGHT 💅

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

---

and that's the whole page, periodt 💖 this one shipped as part of tcllib, version 1.0, for the manual page doctoc_lang_syntax(n) — mwah, take care of her, she's documentation royalty 🫶✨