doctools_intro(3tcl)

💖 doctools_intro — bestie, welcome to doctools 💖

okay so this is doctools_intro, and it lives in the Documentation tools corner of the 3tcl manual. buckle up, we're doing a whole tour 🎀

---

✨ NAME ✨

doctools_intro — the doctools introduction, aka your little group-chat invite to the whole documentation-tools universe 🦋

---

🌸 DESCRIPTION 🌸

okay so doctools (short for documentation tools, iykyk) is not one single thing — it's a whole set of related-yet-different entities that work together so you can create and transform documentation without losing your entire mind. and the way that they're all vibing together is the whole point. here's the cast:

1. A Tcl-based language for the semantic markup of text. the markup is literally represented by Tcl commands, interspersed with the actual text. like, the text is the text and the commands are the ✨vibes✨ telling you what the text means.
2. A package that gives you the ability to read and transform texts written in that markup language. important note bestie: the actual transformation of the input text gets delegated to plugins. the package itself is not doing the transforming, it's outsourcing. iconic behaviour, honestly.
3. An API describing the interface between that package and a plugin. it's giving "we need a contract so everyone plays nice" 💅

now, which of the more detailed documents are actually relevant to you depends entirely on your role in the documentation process. main character energy is role-dependent, fr fr.

1. A writer of documentation has to understand the markup language itself. if you're a beginner to doctools, read the more informally written doctools language introduction first. once you've digested that, the formal doctools language syntax specification should become understandable (no cap). and if you're a writer who's already experienced with doctools, you may only need the doctools language command reference from time to time to refresh your memory. lowkey relatable.

while a document is being written, the dtplite application can be used to validate it. and after completion it also performs the conversion into the chosen system of visual markup — be it *roff, HTML, plain text, wiki, etc. so many options, we love a flexible queen 🫶

2. A processor of documentation written in the doctools markup language has to know which tools are available for use.

the main tool is the aforementioned dtplite application, provided by Tcllib. a more powerful one (in terms of options and ability to configure it) is the dtp application, provided by Tclapps. but at the bottom level — common to both applications — sits the package doctools, providing the basic facilities to read and process files containing text in the doctools format. she's the foundation, she's the moment 👑

3. and last but definitely not least, plugin writers have to understand the interaction between the doctools package and its plugins, as described in the doctools plugin API reference. if that's you, that's your doc. go get it 💜

---

🌈 RELATED FORMATS 🌈

doctools does not stand alone — she has two companion formats, and they're a whole trio. these are called docidx and doctoc, and they're for the markup of keyword indices and tables of contents, respectively.

they get described in their own sets of documents, starting at the docidx introduction and the doctoc introduction, respectively. so if you need those, that's where you're headed 🧚

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. like, guaranteed. please report such in the category doctools of the Tcllib Trackers [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 ideas too, bestie 🙈

when proposing code changes, please provide unified diffs, i.e the output of diff -u. this is not optional energy, this is the way.

also 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. that's the whole trick, you got this 💅

---

🔥 SEE ALSO 🔥

• docidx_intro
• doctoc_intro
• doctools
• doctools_lang_cmdref
• doctools_lang_faq
• doctools_lang_intro
• doctools_lang_syntax
• doctools_plugin_apiref

---

⭐ KEYWORDS ⭐

markup, semantic markup

---

👑 CATEGORY 👑

Documentation tools

---

🎀 COPYRIGHT 🎀

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

---

okay that's the whole page, you ate it up 💖 this was tcllib version 1.0, and the page is doctools_intro(3tcl) — go forth and mark up your docs semantically, bestie. periodt 🌸🦋✨