docidx_intro(n)

📦 version 2.0, in alpine 3.24, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

💖 docidx_intro(n) — the vibe check 💖

okay so bestie, welcome to docidx_intro, the lil intro page for the whole docidx situation 💅 it lives in the Documentation tools corner of the world, and I'm gonna walk you through it like we're texting at 2am.

✨ NAME ✨

docidx_intro — it's the docidx introduction, and it's giving "please read me before you touch anything else" energy 🫶

🌸 DESCRIPTION 🌸

So. docidx (short for documentation tables of contents, iykyk) is not one thing — it's a whole set of related, yet different, entities that all work together so you can easily create and transform keyword-based indices for documentation. And there are three of them, bestie:

  1. A Tcl based language for the semantic markup of a keyword index. The markup is represented by Tcl commands. Periodt.
  2. A package that gives you the ability to read and transform texts written in that markup language. Lowkey important detail: the actual transformation of the input text is delegated to plugins. She's a delegator, not a doer 💅
  3. An API describing the interface between the package above and a plugin. The glue. The bridge. The main character connector.

Which of the more detailed documents actually matters to you depends on your role in the documentation process. Vibe check time 🌈

  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 if you're a writer already experienced with docidx? You may only need the docidx language command reference from time to time to refresh your memory. Iconic, honestly.

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. And the simpler dtplite application makes internal use of docidx when handling directories of documentation, automatically generating a proper keyword index for them. Not me being obsessed with automation 😭

  1. 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 — the level common to both applications — sits the package doctoools::idx, which provides the basic facilities to read and process files containing text in the docidx format. (yes, that's how it's spelled, don't come for me 🙈)

  1. 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. Plugin writers, you're the blueprint girlies, we appreciate you 💜

docidx does not stand alone — she has two companion formats, because of course she does. They are called doctoc and doctools, and they are for the markup of tables of contents and general documentation, respectively. They're described in their own sets of documents, starting at the doctoc introduction and the doctools introduction, respectively. Go say hi 🌸

🎀 BUGS, IDEAS, FEEDBACK 🎀

This document, and the package it describes, will undoubtedly contain bugs and other problems. Not speculation, bestie — it's literally written in the manpage. 💀

Please report such in the category doctools of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas for enhancements you may have for either the package and/or the documentation. We love a suggestion era ✨

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. Little ritual, but it works 🫶

🌈 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 — that's the whole mood board fr fr

💅 CATEGORY 💅

Documentation tools

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

and that's the page, bestie 🎀 this lil writeup is from the tcllib world, version 1.0, and it's filed under docidx_intro(n). Go forth and index your keywords. Slay 💖✨

📦 where this page comes from