doctools::idx(3tcl)

💖 doctools::idx — the manual page, but make it slay 💖

okay bestie, welcome to doctools::idx, a member of the Documentation tools family, and yes it's 3tcl flavored. this is docidx — Processing indices, and we're gonna get through it together, no cap. 🦋

---

✨ NAME ✨

doctools::idx — a.k.a. docidx, a.k.a. the thing that processes 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

look at that lineup. it's giving main character energy fr fr. 💅

---

🎀 DESCRIPTION 🎀

so this package hands you a whole class — like, an actual class, we're being fancy — that makes objects. and those objects can process and convert text written in the docidx markup language into literally any output format X that has a formatting engine available for it. any format. sky's the limit. 🌈

now, if you're the reader who's here for the markup language itself, you should start with the docidx language introduction and then vibe your way onward to the formal specifications, aka the docidx language syntax and the docidx language command reference. that's the reading order, trust. ✨

but if you're the reader who wants to write her own formatting engine for some format — i.e. you're a plugin writer — then bestie, reading and understanding the docidx plugin API reference is an absolute necessity. it's not optional, it's not a suggestion, it's the whole entire lore. 📖 that document spells out, in detail, how this package and its plugins (the formatting engines, duh) talk to each other.

---

💜 PUBLIC API 💜

🫶 PACKAGE COMMANDS 🫶

• ::doctools::idx::new objectName ?-option value ...? — this makes a brand new docidx object, and that object comes with its very own Tcl command whose name is objectName. the full tea on that object command lives in the sections OBJECT COMMAND and OBJECT METHODS, so go read those if you want the deep dive. as for where it gets created: if objectName isn't fully qualified, the object command gets made under the current namespace; if it is fully qualified, it goes in the namespace you specified. also, any options and values you tack on after the object's name set the object's initial configuration. 💖
• ::doctools::idx::help — the convenience command of the group. it's for apps that wanna show their user a lil short description of the available formatting commands and what they mean. it returns a string with a standard help text inside. cute, useful, iconic. ✨
• ::doctools::idx::search path — whenever an object made by this package has to map a format name to the file that holds the code for its formatting engine, it goes hunting through a bunch of directories kept in a list. more on that in FORMAT MAPPING, ok? 👀

this list doesn't just have three default directories that the package declares for itself — it's also extensible by the user of the package, and this command is how you do the extending. give it a path to an existing, readable directory and it will prepend that directory to the search list. heads up: that means the path you added last is the one searched through first. ✨

and an error gets thrown if the path doesn't exist, isn't a directory, or isn't readable. no exceptions. 🙈

🌟 OBJECT COMMAND 🌟

every single command created by ::doctools::idx::new has this general shape, and you use it to invoke all sorts of operations on its docidx converter object.

• objectName method ?arg arg ...? — the method and its arg'uments are what decide the exact behavior of the command. for the full detailed specifications, go see the OBJECT METHODS section. 💅

🦋 OBJECT METHODS 🦋

• objectName configure — call it with no arguments at all and it hands you a list of all known options and their current values. a full inventory, basically. 📋
• objectName configure option — call it with a single argument and it behaves just like the method cget, returning the value of the option named by that argument. same energy, different name. 💖
• objectName configure -option value... — call it with an even number of arguments (at least two, bestie, minimum) and it reconfigures the specified options of the object, setting each one to its associated value.

the legal options are described in the section OBJECT CONFIGURATION. 👑

• objectName cget -option — this one wants a legal configuration option as its argument, and it'll return the current value of that option for the object the method was invoked on. one option in, one value out. 🎀

the legal configuration options are described in section OBJECT CONFIGURATION.

• objectName destroy — destroys the object it's invoked for. 💀 that's it, that's the method. rip bozo.
• objectName format text — runs the text through the configured formatting engine and returns the generated string as its result. and if there's no -format configured on the object? error. thrown. no format, no party. 😭

this method assumes the text is in docidx format exactly as specified in the companion document docidx_fmt. if it isn't, errors get thrown. so, y'know, format your text properly. ✨

• objectName map symbolic actual — adds one entry to the per-object mapping from symbolic filenames to the actual uris. the object literally 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. iykyk. 🗺️
• objectName parameters — returns a list containing the names of all engine parameters provided by the configured formatting engine. if the object isn't configured for a specific format yet, you get an empty list. so like, it's not mad, it's just empty. 🙈
• objectName search path — extends the per-object list of paths searched for index formatting engines. (also peep the command ::doctools::idx::search if you wanna extend the per-package list of paths instead.) important: the path entered last will be searched first. more details over in FORMAT MAPPING. 🔍
• objectName setparam name value — sets the named engine parameter to the specified value. it'll throw an error if the object isn't configured for a specific format yet, or if the formatting engine for the configured format doesn't provide a parameter with the given name. and if you wanna know which parameters are on offer? grab the list through the method parameters. 🎛️
• objectName warnings — returns a list containing all the warnings which the configured formatting engine generated during the last invocation of the method format. receipts, basically. 🧾

---

💅 OBJECT CONFIGURATION 💅

every docidx object understands these configuration options, no exceptions:

• -file file — the argument of this option gets 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 read the value as the name of the file containing the document currently being 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. and real talk: the method format cannot be used if this option hasn't been set to a valid value at least once. so set it. 💅

the package will immediately try to map the given name to a file containing the code for a formatting engine that generates that format. if that mapping fails, an error is thrown. and in that case, a previously configured format is left untouched — so at least nothing gets wrecked. 🫶

the section FORMAT MAPPING explains in detail how the package and object look for engine implementations. go look. 👀

---

🔥 FORMAT MAPPING 🔥

when the package and object try to map a format name foo to a file containing an implementation of a formatting engine for foo, here's the exact algorithm they run through:

1. if foo is the name of an existing file, then that file is directly taken as the implementation. easiest win ever. ⭐
2. if not, the list of per-object search paths gets searched. for each directory in the list, the package checks whether that directory contains a file "idx.foo". if yes, 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 gets searched. for each directory in the list, the package checks whether that directory contains a file "idx.foo". if yes, 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 — and this is the example, bestie, pay attention — if the package implementation "docidx.tcl" is installed in the directory /usr/local/lib/tcllib/doctools, then by default it'll search the directory /usr/local/lib/tcllib/doctools/mpformats for format implementations. 📂✨

4. the mapping fails. 💀

ok that's the end of part 1! don't go anywhere, there's more coming — part 2 is right behind this one. 🎀

✨ PREDEFINED ENGINES ✨

okay so bestie, this package comes with predefined formatting engines for the following formats, and some of them support engine parameters — those are gonna be highlighted like the main characters they are 👑. periodt.

• html — generates HTML markup, for processing by web browsers and the like 🌐. This engine supports three parameters:
  • footer — the value for this parameter has to be valid selfcontained HTML markup for the body section of a HTML document. The default value is the empty string. The value is inserted into the generated output just before the </body> tag, closing the body of the generated HTML. You can use this to insert boilerplate footer markup into the generated document. 💖
  • header — the value for this parameter has to be valid selfcontained HTML markup for the body section of a HTML document. The default value is the empty string. The value is inserted into the generated output just after the <body> tag, starting the body of the generated HTML. You can use this to insert boilerplate header markup into the generated document. ✨
  • meta — the value for this parameter has to be valid selfcontained HTML markup for the header section of a HTML document. The default value is the empty string. The value is inserted into the generated output just after the <head> tag, starting the header section of the generated HTML. You can use this to insert boilerplate meta data markup into the generated document, like references to a stylesheet, standard meta keywords, etc. 🎀
• latex — generates output suitable for the latex text processor coming out of the TeX world 📚.
• list — retrieves version, section and title of the manpage from the document. As such it can be used to generate a directory listing for a set of manpages 📂.
• markdown — generates Markdown markup 📝.
• nroff — generates nroff output, for processing by nroff, or groff. The result will be standard man pages as they are known in the unix world 📜.
• null — generates no output at all. This can be used if one just wants to validate some input ✅.
• tmml — generates TMML markup as specified by Joe English. The Tcl Manpage Markup Language is a derivate of XML 🧬.
• wiki — generates Wiki markup as understood by Jean Claude Wippler's wikit application 📖.

---

🐛 BUGS, IDEAS, FEEDBACK 💌

This document, and the package it describes, will undoubtedly contain bugs and other problems. 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 package and/or documentation.

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
• 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 ©️

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

---

and that's the whole vibe, bestie 💅 — source/version: tcllib 1.2.1, page: doctools::idx(3tcl). no date in the footer, so we're just gonna vibe with that. mwah 🫶