doctools_intro(n)

🌸 doctools_intro(n) — the vibe check 🌸

okay bestie, welcome to doctools_intro, aka the front door of the doctools manual. this is a n page (that's Tcl manual, for the uninitiated) and it's literally just here to point you at the right place depending on who you are. sit down, hydrate, let's go 💖

---

✨ NAME ✨

doctools_intro — doctools introduction. that's it, that's the name, she's simple and she knows it 💅

---

🦋 DESCRIPTION 🦋

so doctools (short for documentation tools, obviously) is a whole little squad of related-but-different entities that team up to make documentation easy to create and easy to transform. and when I say squad, I mean these three:

1. A Tcl based language for the semantic markup of text. the markup is represented by Tcl commands sprinkled in between the actual text, like glitter on a birthday card ✨
2. A package that gives you the ability to read and transform texts written in that markup language. important note though — and don't skip this — the actual transformation of the input text is delegated to plugins. the package is not doing the transforming itself, she's outsourcing, she's got a team for that 🫶
3. An API that describes the interface between the package above and a plugin. that's the contract, the group chat rules, the "here's how we talk to each other" doc.

which of the more detailed documents is actually relevant to you depends entirely on your role in the documentation process. so let's do a vibe check per role:

1. you're a writer of documentation 📝 — you gotta 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. and if you're already experienced with doctools? you probably only need the doctools language command reference from time to time, to refresh your memory, bestie.

while a document is being written, the dtplite application can be used to validate it. and after completion, that same dtplite 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. you're a processor of documentation written in the doctools markup language — you have 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 the 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 holding everyone up 💅

3. you're a plugin writer — last but not least (never least), you have to understand the interaction between the doctools package and its plugins, as described in the doctools plugin API reference.

---

🌈 RELATED FORMATS 🌈

doctools does not stand alone. she has two companion formats, and they're iconic in their own right:

• docidx — for the markup of keyword indices
• doctoc — for the markup of tables of contents

they're described in their own sets of documents, starting at the docidx introduction and the doctoc introduction, respectively. go say hi 🎀

---

💀 BUGS, IDEAS, FEEDBACK 💀

not me having to tell you this, but: this document, and the package it describes, will undoubtedly contain bugs and other problems. it's giving "we're all human". please report such 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 — feedback is a love language 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. iykyk 💅

---

👑 SEE ALSO 👑

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

the whole friend group, go read them all 💖

---

⭐ KEYWORDS ⭐

markup, semantic markup

---

🧚 CATEGORY 🧚

Documentation tools

---

💜 COPYRIGHT 💜

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

---

and that's the page, bestie 🦋 this was doctools_intro(n) from tcllib, version 1.0 — thanks for reading, you ate, no cap ✨🎀