doctools2idx_introduction(n)

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

💖 doctools2idx_introduction — DocTools, but make it keyword indices 💖

okay so bestie, welcome to doctools2idx_introduction(n), a page from the Documentation tools manual. this is your lil orientation tour of the whole keyword-index universe and honestly? it's giving main character energy. let's get into it ✨

🌸 NAME 🌸

doctools2idx_introduction — DocTools, and specifically: Keyword indices. that's the whole vibe 🎀

🦋 DESCRIPTION 🦋

so docidx — short for documentation indices, iykyk — is not one thing, it's a whole set of related-but-different entities that work together so you can easily create and transform keyword indices for documentation. it's a little squad 🫶

here's the squad:

  1. A tcl based language for the semantic markup of a keyword index. the markup is represented by Tcl commands. beginners should start with the docidx language introduction. the formal spec is split over two documents — one dealing with the docidx language syntax, the other a docidx language command reference. two docs, one language, slay.
  2. A set of packages for the programmatic manipulation of keyword indices in memory, plus their conversion between various formats, reading and writing. and yes, the markup language mentioned above is one of the formats which can be both read from and written to. iconic behaviour.
  3. The system for the conversion of indices is based on a plugin mechanism — and for this we have two APIs describing the interface between the packages above and the import/export plugins.

which of the more detailed documents are actually relevant to you depends on your role in the documentation process. pick your fighter:

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

while a document is 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. no cap, it just does it for you.

  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. at the bottom level, common to both applications, however, we find the three packages providing the basic facilities to handle keyword indices, i.e. import from textual formats, programmatic manipulation in memory, and export to textual formats. these are:

  • doctools::idx — Programmatic manipulation of keyword indices in memory.
  • doctools::idx::import — Import of keyword indices from various textual formats. the set of supported formats is extensible through plugin packages.
  • doctools::idx::export — Export of keyword indices to various textual formats. the set of supported formats is extensible through plugin packages.

see also the section Package Overview for an overview of the dependencies between these and other, supporting packages. 👑

  1. At last, but not least, plugin writers have to understand the interaction between the import and export packages and their plugins. these APIs are described in the documentation for the two relevant packages, i.e.
    • doctools::idx::import
    • doctools::idx::export

plot twist: the docidx format does not stand alone. it has two companion formats, called doctoc and doctools, and they're intended for the markup of tables of contents and of general documentation, respectively. they're described in their own sets of documents, starting at the DocTools - Tables Of Contents and the DocTools - General, respectively. a lil format family reunion 🧚

✨ PACKAGE OVERVIEW ✨

okay bestie, this diagram is the moment. look at it. feel it. i'm keeping it exactly as-is because it's literally art 🖼️

                                                  ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
                                                 ~~                   |               ~~
                              doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
                                      |                               |                       |
                      +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
                      |               |                         |     |    |                  |               |                       |               |
              struct::map             =                         |     |    |                  =       doctools::include       struct::map      fileutil::paths
                                      |                         |     |    |                  |
                              doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
                                      docidx                    |     |    |                  docidx, json
                                      json                      |     |    |                  |           \
                                      html                      |     |    |          doctools::idx::parse \
                                      nroff                     |     |    |                  |             \
                                      wiki                      |     |    |  +---------------+              json
                                      text                      |     |    |  |               |
                                                              doctools::idx::structure        |
                                                                                              |
                                                                                      +-------+---------------+
                                                                                      |                       |
                        doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat
                              |                                                                               |
                        doctools::text  doctools::nroff::man_macros                                           =
                                                                                                              |
                                                                                                      doctools::msgcat::idx::<*>
                                                                                                              c, en, de, fr
                                                                                                              (fr == en for now)
                      ~~      Interoperable objects, without actual package dependencies
                      --      Package dependency, higher requires lower package
                      =       Dynamic dependency through plugin system
                      <*>     Multiple packages following the given form of naming.

and for the record, here's the legend decoded one more time, because it matters:

  • ~~ — Interoperable objects, without actual package dependencies
  • -- — Package dependency, higher requires lower package
  • = — Dynamic dependency through plugin system
  • <*> — Multiple packages following the given form of naming.

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. not me being honest about it. 😭 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 the package and/or the documentation. we want the glow-up suggestions 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.

👑 SEE ALSO 👑

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

🍓 KEYWORDS 🍓

conversion, formatting, index, keyword index, markup, parsing, plugin, semantic markup

🎀 CATEGORY 🎀

Documentation tools

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

and that's the whole page, bestie. this one shipped as tcllib 2.0, dated doctools2idx_introduction(n) — go forth and index those keywords. periodt. 💅✨

📦 where this page comes from