doctools::idx(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

🦋 doctools::idx — the docidx index-processing page 🦋

okay so bestie, you just opened the doctools::idx(n) page, straight out of the Documentation tools manual, and I am so glad you're here 💖 This is part 1, so buckle up and don't go anywhere.

✨ NAME ✨

doctools::idx — docidx — Processing indices 👑

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require doctools::idx ?1.2.1?

::doctools::idx::new objectName ?-option value ...?

::doctools::idx::help

::doctools::idx::search path

objectName method ?arg arg ...?

objectName configure

objectName configure option

objectName configure -option value...

objectName cget -option

objectName destroy

objectName format text

objectName map symbolic actual

objectName parameters

objectName search path

objectName setparam name value

objectName warnings

💅 DESCRIPTION 💅

So this package hands you a class for making objects that can process and convert text written in the docidx markup language into literally any output format X — as long as a formatting engine exists for it. no cap. ✨

If you're the reader who's actually curious about the markup language itself, bestie, start with the docidx language introduction and then vibe your way forward into the formal specs, aka the docidx language syntax and the docidx language command reference 📚

But if you're the reader who wants to write her own formatting engine for some format — meaning you're a plugin writer — then reading and fully understanding the docidx plugin API reference is an absolute necessity. Like, non-negotiable. That document spells out the interaction between this package and its plugins (the formatting engines) in full detail, and you will need it. periodt. 💯

🌈 PUBLIC API 🌈

🎀 PACKAGE COMMANDS 🎀

  • ::doctools::idx::new objectName ?-option value ...? — this creates a brand-new docidx object with an associated Tcl command whose name is objectName. That object command gets explained in full detail down in the sections OBJECT COMMAND and OBJECT METHODS, so keep scrolling. The object command is created under the current namespace if objectName is not fully qualified, and in the specified namespace otherwise. And the options plus their values that come after the name of the object? Those set the initial configuration of the object, slay. ✨
  • ::doctools::idx::help — a convenience command for applications that want to give their user a short description of the available formatting commands and what they mean. It returns a string containing a standard help text 🫶
  • ::doctools::idx::search path — whenever an object created by this package has to map the name of a format to the file containing the code for its formatting engine, it goes looking for that file in a bunch of directories stored in a list (peep the FORMAT MAPPING section for the whole explanation). This list doesn't just hold three default directories declared by the package itself — it's also extensible by the user of the package, and this command is how you do it. Give it a path to an existing and readable directory and it will prepend that directory to the list of directories to search. Which means: the path you added last gets searched through first. 🌀 An error will be thrown if the path either doesn't exist, isn't a directory, or isn't readable. 🙈

🧚 OBJECT COMMAND 🧚

Every single command created by ::doctools::idx::new has this general form, and you use it to invoke all kinds of operations on its docidx converter object:

  • objectName method ?arg arg ...? — the method method and its arg'uments decide the exact behavior of the command. The detailed specs live in the OBJECT METHODS section. go look 👀

👑 OBJECT METHODS 👑

objectName configure

Called with no arguments at all, this method returns a list of all known options and their current values. the whole roster 💖

objectName configure option

Called with a single argument, this method behaves exactly like the method cget and returns the value of the option specified by said argument.

objectName configure -option value...

Called with an even number of arguments, at least two, this method reconfigures the specified options of the object and sets them to the associated values 🔧 The legal options are described in the OBJECT CONFIGURATION section.

objectName cget -option

This method expects a legal configuration option as its argument and returns the current value of that option for the object the method was invoked for. The legal configuration options are described in the OBJECT CONFIGURATION section 💅

objectName destroy

This method destroys the object it is invoked for. bye bestie 👋💀

objectName format text

This method runs text through the configured formatting engine and returns the generated string as its result. An error will be thrown if no -format was configured for the object. The method assumes that the text is in docidx format as specified in the companion document docidx_fmt. Errors will be thrown otherwise. ⚠️

objectName map symbolic actual

This method adds one entry to the per-object mapping from symbolic filenames to the actual uris. The object just stores this mapping and makes it available to the configured formatting engine through the command dt_fmap. That command is described in more detail in the docidx plugin API reference, which specifies the interaction between the objects created by this package and index formatting engines 🔗

objectName parameters

This method returns a list containing the names of all engine parameters provided by the configured formatting engine. It returns an empty list if the object isn't yet configured for a specific format 🍓

objectName search path

This method extends the per-object list of paths searched for index formatting engines. Peep also the command ::doctools::idx::search for how to extend the per-package list of paths. Heads up: the path entered last will be searched first. More details live in the FORMAT MAPPING section 🌀

objectName setparam name value

This method sets the named engine parameter to the specified value. It will throw an error if the object is either not yet configured for a specific format, or if the formatting engine for the configured format doesn't provide a parameter with the given name. You can grab the list of parameters provided by the configured formatting engine through the method parameters 🙈

objectName warnings

This method returns a list containing all the warnings generated by the configured formatting engine during the last invocation of the method format 😭 (iconic, honestly)

💜 OBJECT CONFIGURATION 💜

All docidx objects understand these configuration options:

  • -file file — the argument of this option is stored in the object and made available to the configured formatting engine through the command dt_file. That command is described in more detail in the companion document docidx_api, which specifies the API between the object and formatting engines. The default value of this option is the empty string. The configured formatting engine should interpret the value as the name of the file containing the document which is currently processed 📄
  • -format text — the argument of this option specifies the format to generate and, by implication, the formatting engine to use when converting text via the method format. Its default value is the empty string. The method format cannot be used if this option is not set to a valid value at least once. 🚨 The package will immediately try to map the given name to a file containing the code for a formatting engine generating that format. An error will be thrown if this mapping fails — and in that case, a previously configured format is left untouched, so you're not left stranded. The FORMAT MAPPING section explains in detail how the package and object look for engine implementations 💅

🌟 FORMAT MAPPING 🌟

The package and object perform this algorithm when trying to map a format name foo to a file containing an implementation of a formatting engine for foo:

  1. If foo is the name of an existing file, then this file is directly taken as the implementation. done and dusted ✨
  2. If not, the list of per-object search paths is searched. For each directory in the list, the package checks if that directory contains a file "idx.foo". If yes, then that file is taken as the implementation. Note that this list of paths is initially empty and can be extended through the object method search 🎀
  3. If not, the list of package paths is searched. For each directory in the list, the package checks if that directory contains a file "idx.foo". If yes, then that file is taken as the implementation. This list of paths can be extended through the command ::doctools::idx::search. It contains initially one path: the subdirectory "mpformats" of the directory the package itself is located in. In other words, if the package implementation "docidx.tcl" is installed in the directory /usr/local/lib/tcllib/doctools, then it will by default search the directory /usr/local/lib/tcllib/doctools/mpformats for format implementations 👑
  4. The mapping fails. 💀

🌈 PREDEFINED ENGINES 🌈

okay bestie, this package comes with a whole closet of ready-to-wear formatting engines, one for each format it supports 💅 and some of them even take engine parameters — those ones are getting called out loudly, no subtlety, you'll see them.

💻 html

This engine spits out HTML markup, for web browsers and whatever else wants to eat HTML. It supports three parameters, and yes they're all getting the spotlight:

  • footer — the value has to be valid, self-contained HTML markup for the body section of an HTML document. Default value is the empty string "". It gets dropped into the generated output right before the </body> tag, i.e. it closes out the body of the generated HTML.

Basically: this is your moment to sneak boilerplate footer markup into the generated document 🎀

  • header — same deal, the value has to be valid, self-contained HTML markup for the body section of an HTML document. Default value is the empty string "". It gets inserted into the generated output just after the <body> tag, kicking off the body of the generated HTML.

So use it to insert boilerplate header markup into the generated document ✨

  • meta — the value has to be valid, self-contained HTML markup for the header section of an HTML document. Default is the empty string "". It's inserted into the generated output just after the <head> tag, starting the header section of the generated HTML.

This one's for boilerplate meta data markup — stylesheet references, standard meta keywords, that whole vibe 🦋

🧪 latex

Generates output that's suitable for the latex text processor, aka the thing that came out of the TeX world. very academic of it 💜

📋 list

This engine pulls the version, section and title of the manpage out of the document. Which means you can use it to build a directory listing for a whole set of manpages. iconic behaviour honestly 👑

🖊️ markdown

Generates Markdown markup. that's it, that's the whole engine, and we love her for it 🌸

📜 nroff

Generates nroff output, for processing by nroff or groff. What you get are standard man pages, exactly the kind everybody in the unix world knows and loves. periodt 💅

🕳️ null

Generates no output at all. Like, zero. Nothing. Which is genuinely useful if all you want to do is validate some input — vibe check the file, get no output back, perfect 🔥

📐 tmml

Generates TMML markup as specified by Joe English. The Tcl Manpage Markup Language is a derivate of XML. yes bestie, XML-adjacent, handle with care ✨

🌐 wiki

Generates Wiki markup as understood by Jean Claude Wippler's wikit application. 🧚

🐛 BUGS, IDEAS, FEEDBACK 🐛

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems 😭 that's just how it is. So please, please report them, in the category doctools of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist. And while you're there, report any ideas for enhancements you may have for either the package and/or the documentation too 🫶

When you're proposing code changes, please provide unified diffs, i.e. the output of diff -u. fr fr, that's the format.

Also note: attachments are strongly preferred over inlined patches. You can make an attachment by going to the Edit form of the ticket immediately after it's created, and then using the left-most button in the secondary navigation bar. iykyk 💖

👀 SEE ALSO 👀

  • docidx_intro
  • docidx_lang_cmdref
  • docidx_lang_intro
  • docidx_lang_syntax
  • docidx_plugin_apiref

🔑 KEYWORDS 🔑

HTML, TMML, conversion, docidx, documentation, index, keyword index, latex, manpage, markdown, markup, nroff, wiki

📁 CATEGORY 📁

Documentation tools

Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>

okay that's the whole page bestie, you made it to the end 🎉 this was doctools::idx(n) from tcllib 1.2.1 — go forth and index those keywords, you absolute main character 💖✨👑

📦 where this page comes from