docidx_intro(3tcl)

💖 docidx_intro — docidx introduction 💖

okay bestie, so this is docidx_intro, living in the 3tcl manual, and it's basically the welcome mat for the whole docidx universe. come sit, we're doing lore today 🫶

---

✨ NAME ✨

docidx_intro — docidx introduction

---

🌸 DESCRIPTION 🌸

so docidx is short for documentation tables of contents (yes, the name is doing a lot, we love that for it 💅). and it's not, like, one thing — it's a whole set of related, yet different entities that work together so you can easily create and transform keyword-based indices for documentation. the little squad is:

1. A tcl based language for the semantic markup of a keyword index. the markup is represented by Tcl commands. slay.
2. A package that gives you the ability to read and transform texts written in that markup language. big important note: the actual transformation of the input text is delegated to plugins. it's giving project manager energy, honestly.
3. An API describing the interface between the package above and a plugin.

which of the more detailed docs is actually relevant to you depends on your role in the documentation process, bestie. it's a vibe check, essentially:

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

while a document is being written, the dtp 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. the simpler dtplite application makes internal use of docidx when handling directories of documentation, automatically generating a proper keyword index for them. iconic behaviour, truly.

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

the main tool is the aforementioned dtp application provided by Tcllib. the simpler dtplite does not expose docidx to the user. but at the bottom level, common to both applications, sits the package doctoools::idx — wait, that's literally how it's spelled in the source, so that's what I'm giving you, character for character 🫠 — providing the basic facilities to read and process files containing text in the docidx format.

3. And at last, but not least 👑, plugin writers have to understand the interaction between the doctools::idx package and its plugins, as described in the docidx plugin API reference.

---

🦋 RELATED FORMATS 🦋

docidx does not stand alone, bestie — it has two companion formats. they're called doctoc and doctools, and they're for the markup of tables of contents and general documentation, respectively. each one is described in its own set of documents, starting at the doctoc introduction and the doctools introduction, respectively. found family, honestly 💜

---

😭 BUGS, IDEAS, FEEDBACK 😭

so. this document, and the package it describes, will undoubtedly contain bugs and other problems. I know. tragic. 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 — we want them, 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. go off, you got this 🎀

---

💅 SEE ALSO 💅

• docidx_lang_cmdref
• docidx_lang_faq
• docidx_lang_intro
• docidx_lang_syntax
• docidx_plugin_apiref
• doctoc_intro
• doctools::idx
• doctools_intro

---

⭐ KEYWORDS ⭐

index, keyword index, 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 docidx_intro(3tcl) from tcllib, version 1.0 — mwah, go read the rest of the family, they're all waiting for you 🦋✨💜