docidx_plugin_apiref(3tcl)

✨ NAME ✨

okay bestie, welcome to the docidx_plugin_apiref(3tcl) page from the Documentation tools manual. It is literally the docidx plugin API reference. 💖

docidx_plugin_apiref — docidx plugin API reference

---

📜 SYNOPSIS 📜

dt_fmap symfname

dt_format

dt_read file

dt_source file

ex_cappend text

ex_cget varname

ex_cis cname

ex_cname

ex_cpop cname

ex_cpush cname

ex_cset varname value

ex_lb ?newbracket?

ex_rb ?newbracket?

idx_initialize

idx_listvariables

idx_numpasses

idx_postprocess text

idx_setup n

idx_shutdown

idx_varset varname text

fmt_plain_text text

---

💬 DESCRIPTION 💬

This document is intended for plugin writers, i.e. developers wishing to write an index formatting engine for some output format X. 🛠️

It specifies the interaction between the doctools::idx package and its plugins, i.e. the interface any index formatting engine has to comply with.

This document deals with version 1 of the interface. 👑

A reader who is on the other hand more interested in the markup language itself should start with the docidx language introduction and proceed from there to the formal specifications, i.e. the docidx language syntax and the docidx language command reference. 📚

---

🌈 OVERVIEW 🌈

The API for an index formatting engine consists of two major sections.

On the one side we have a set of commands through which the plugin is able to query the frontend. These commands are provided by the frontend and linked into the plugin interpreter. Please see section FRONTEND COMMANDS for their detailed specification. 🫶

And on the other side the plugin has to provide its own set of commands which will then be called by the frontend in a specific sequence while processing input. They, again, fall into two categories, management and formatting. Please see section PLUGIN COMMANDS and its subsections for their detailed specification. ✨

---

👑 FRONTEND COMMANDS 👑

This section specifies the set of commands through which a plugin, also known as an index formatting engine, is able to query the frontend. These commands are provided by the frontend and linked into the plugin interpreter. 💅

I.e. an index formatting engine can assume that all of the following commands are present when any of its own commands (as specified in section PLUGIN COMMANDS) are executed. 🫡

Beyond that it can also assume that it has full access to its own safe interpreter and thus is not able to damage the other parts of the processor, nor can it damage the filesystem. It is however able to either kill or hang the whole process, by exiting, or running an infinite loop. 💀

Coming back to the imported commands, all the commands with prefix dt_ provide limited access to specific parts of the frontend, whereas the commands with prefix ex_ provide access to the state of the textutil::expander object which does the main parsing of the input within the frontend.

bestie, ngl, these commands should not be [used] except under very special circumstances. 🚨

• dt_fmap symfname — Query command. It returns the actual pathname to use in the output in place of the symbolic filename symfname. It will return the unchanged input if no mapping was established for symfname. The required mappings are established with the method map of a frontend, as explained in section OBJECT METHODS of the documentation for the package doctools::idx. 🗺️
• dt_format — Query command. It returns the name of the format associated with the index formatting engine. 🎀
• dt_read file — Controlled filesystem access. Returns contents of file for whatever use desired by the plugin. Only files which are either in the same directory as the file containing the engine, or below it, can be loaded. Trying to load a file outside of this directory causes an error. 🚫
• dt_source file — Controlled filesystem access. This command allows the index formatting engine to load additional Tcl code it may need. Only files which are either in the same directory as the file containing the engine, or below it, can be loaded. Trying to load a file outside of this directory causes an error. 📦
• ex_cappend text — Appends a string to the output in the current context. This command should rarely be used by macros or application code. ✍️
• ex_cget varname — Retrieves the value of variable varname, defined in the current context. 🔍
• ex_cis cname — Determines whether or not the name of the current context is cname. 🤔
• ex_cname — Returns the name of the current context. 🏷️
• ex_cpop cname — Pops a context from the context stack, returning all accumulated output in that context. The context must be named cname, or an error results. 💥
• ex_cpush cname — Pushes a context named cname onto the context stack. The context must be popped by cpop before expansion ends or an error results. 🫠
• ex_cset varname value — Sets variable varname to value in the current context. ✨
• ex_lb ?newbracket? — Returns the current value of the left macro expansion bracket; this is for use as or within a macro, when the bracket needs to be included in the output text. If newbracket is specified, it becomes the new bracket, and is returned. ⬅️
• ex_rb ?newbracket? — Returns the current value of the right macro expansion bracket; this is for use as or within a macro, when the bracket needs to be included in the output text. If newbracket is specified, it becomes the new bracket, and is returned. ➡️

✨ PLUGIN COMMANDS ✨

okay bestie, so listen up — the plugin has to bring its own lil command squad, and the frontend calls those commands in a very specific order while it's processing input. They split into two categories: management and formatting. Their expected names, signatures, and responsibilities? All right here in the next two subsections. 💅

🛠️ MANAGEMENT COMMANDS 🛠️

So the management commands a plugin has to hand over are what the frontend uses to:

1. initialize and shutdown the plugin
2. determine the number of passes it has to make over the input
3. initialize and shutdown each pass
4. query and initialize engine parameters

After the plugin has been loaded and the frontend commands are established, the commands get called in this exact sequence:

idx_numpasses -> n
idx_listvariables -> vars

idx_varset var1 value1
idx_varset var2 value2
...
idx_varset varK valueK
idx_initialize
idx_setup 1
...
idx_setup 2
...
...
idx_setup n
...
idx_postprocess
idx_shutdown
...

Which means: first we figure out how many passes there are and what engine parameters are available, then the parameters get set. That second bit? Optional, bestie. slay 💖

Then the plugin gets initialized, the specified number of passes run, the final result goes through a global post-processing step, and finally the plugin shuts down again. And guess what? More conversions can follow after that, restarting the whole sequence at idx_varset. 🔁

During each pass — like, right after the idx_setup calls — the frontend processes the input and calls the formatting commands whenever it bumps into markup. So the order of those formatting commands is totally decided by the grammar of the docidx markup language, exactly as the docidx language syntax specification says. 📜

Another way to vibe-check the sequence:

• First some basic parameters are determined.
• Then everything starting at the first idx_varset to idx_shutdown forms a run, the formatting of a single input. Each run can be followed by more.
• Embedded within each run we have one or more passes, each starting with idx_setup and going until either the next idx_setup or idx_postprocess is reached.

If more than one pass is required to perform the formatting only the output of the last pass is relevant. The output of all the previous, preparatory passes is ignored.

Here's the full rundown of the commands, their names, signatures, and what they're responsible for:

• idx_initialize — Initialization/Shutdown. This one gets called at the very start of every conversion run, first command of the run. And no, a run is not a pass — it can actually have multiple passes. It's in charge of initializing the plugin's general state, beyond whatever initialization happened during load. No return value expected, and anything you return gets ignored. 🙈
• idx_listvariables — Initialization/Shutdown and Engine parameters. This is the second command called after the plugin code loads, so right after idx_numpasses. It has to return a list with the names of the parameters the frontend can set to configure the engine. That list can be empty, no pressure. ✨
• idx_numpasses — Initialization/Shutdown and Pass management. First command after the plugin code loads, periodt. No other engine command gets called before it. It returns the number of passes this engine needs to fully process the input document. That value has to be an integer greater or equal to one. No zerosies. 🔢
• idx_postprocess text — Initialization/Shutdown. Called right after the last pass in a run. Its argument is the result of the conversion from that pass. It exists so the engine can do any global modifications to the generated document. If no post-processing is needed for a specific format, the command just returns the argument. Expected to return a value — the final formatted result of the input. 💅
• idx_setup n — Initialization/Shutdown and Pass management. This runs at the beginning of each pass over the input in a run. Its argument is the number of the pass that just began, and passes count from 1 upward. It sets up the plugin's internal state for that specific pass. No return value expected, and any return gets ignored. 🛠️
• idx_shutdown — Initialization/Shutdown. Called at the end of every conversion run, and it's the last command in that run. It has to clean up all the run-specific state in the plugin. After it runs, the engine has to be in a state where another run can start without any fear that info from the last run leaks into the new one. No return value expected, and any return gets ignored. 🧼
• idx_varset varname text — Engine parameters. The frontend calls this to set an engine parameter to a particular value. varname says which parameter to change, and text is the value to set. If varname is unknown, the command has to throw an error. Only the names returned by idx_listvariables count as known. And the values of all engine parameters have to persist between passes and runs. No cap. 💾

🎀 FORMATTING COMMANDS 🎀

The formatting commands are the ones that actually format stuff for the output format. They cover all the markup commands of the docidx markup language except lb, rb, vset, include, and comment. Those exceptions get handled by the frontend and never even reach the plugin. In exchange, the plugin has to provide a command for formatting plain text — the stuff with no markup in the input at all. 🎀

So basically, every one of the five markup commands listed in the docidx language command reference that isn't in that exception list has a matching formatting command. That formatting command takes the same arguments as the markup command, and its name is just the markup command's name with the prefix fmt_ slapped on the front. ✨

All of these commands are supposed to format their input somehow according to the semantics in the command reference, and return whatever part of that they think is necessary as their result. That result then gets added to the output. 💖

To avoid just copy-pasting the entire command reference, we're not listing any of those commands here. Instead, bestie, go check the docidx language command reference for their signatures and descriptions. The only exception is the plain text formatter, because it has no equivalent markup command. 🙈

Unlike the management commands, the calling sequence of formatting commands isn't super rigid. It's determined by the grammar of the docidx markup language, exactly as the docidx language syntax specification lays out. 🦋

• fmt_plain_text text — No associated markup command. Called by the frontend for any plain text it finds in the input. It has to do any and all special processing required for plain text. The formatted text is expected as the command's result, and it gets added to the output. If no special processing is required, it just returns its argument without changing anything. 💅

🐛 BUGS, IDEAS, FEEDBACK 💡

Okay so real talk: this document and the package it describes will definitely have bugs and other problems. Please report them in the category doctools of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Also, if you have ideas for enhancements for either the package and/or the documentation, send those too. We love ideas. 💡

When you're proposing code changes, please give us unified diffs — that means the output of diff -u. Periodt.

Also note: attachments are strongly preferred over inlined patches. To attach something, go to the Edit form of the ticket right after you create it, then hit the left-most button in the secondary navigation bar. 🫶

👀 SEE ALSO 👀

docidx_intro, docidx_lang_cmdref, docidx_lang_faq, docidx_lang_intro, docidx_lang_syntax, doctools::idx

🔑 KEYWORDS 🔑

formatting engine, index, index formatter, keywords, markup, plugin, semantic markup

📂 CATEGORY 📂

Documentation tools

📜 COPYRIGHT 📜

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

okay bestie that's the whole part 2, and the footer is giving tcllib version 1.0 for docidx_plugin_apiref(3tcl) — no date, just vibes. 💖