doctoc_plugin_apiref(n)

🌸 NAME 🌸

doctoc_plugin_apiref — aka the doctoc plugin API reference, bestie. Yes, the manual name is literally doctoc_plugin_apiref(n) and it's here to hand you the entire interface spec. 💖

---

✨ 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?

toc_initialize

toc_listvariables

toc_numpasses

toc_postprocess text

toc_setup n

toc_shutdown

toc_varset varname text

fmt_plain_text text

---

💅 DESCRIPTION 💅

okay so this doc? it's for plugin writers, meaning developers who wanna write a toc formatting engine for some output format X. That's the whole audience. If that's you, hi, welcome, you're the main character. 👑

It lays out the interaction between the doctools::toc package and its plugins — like, the interface any toc formatting engine has to comply with. No skipping steps, fr fr.

This document deals with version 1 of the interface. That's the version. Periodt.

Now if you're the other kind of reader — the one who's more into the markup language itself — you should start with the doctoc language introduction and then proceed from there to the formal specifications, i.e. the doctoc language syntax and the doctoc language command reference. Different journey, equally valid. 🦋

---

🌈 OVERVIEW 🌈

The API for a toc formatting engine splits into two major sections. Two. Iconic duo energy.

On one side, there's a set of commands the plugin uses to query the frontend. These commands are provided by the frontend and linked into the plugin interpreter. Their full spec lives in the section FRONTEND COMMANDS. Go look, it's right there.

And on the other side, the plugin has to provide its own set of commands, which the frontend then calls in a specific sequence while processing input. Those ones, again, fall into two categories: management and formatting. Their detailed spec is in section PLUGIN COMMANDS and its subsections. 💫

---

🎀 FRONTEND COMMANDS 🎀

This section specifies the set of commands through which a plugin — also known as a toc formatting engine, same thing, different outfit — can query the frontend. These commands are provided by the frontend and linked into the plugin interpreter.

Translation: a toc formatting engine can assume that all of the following commands are present whenever any of its own commands (as specified in section PLUGIN COMMANDS) get executed. No vibe check needed, they're there.

Beyond that, it can also assume it has full access to its own safe interpreter, which means it cannot damage the other parts of the processor, nor can it damage the filesystem. 🛡️

But listen — it is able to either kill or hang the whole process, by exiting, or by running an infinite loop. So, you know. Be normal about it. 😭

Coming back to the imported commands: all the commands with the prefix dt_ provide limited access to specific parts of the frontend, whereas the commands with the prefix ex_ provide access to the state of the textutil::expander object which does the main parsing of the input within the frontend. These ones should not be [used] except under very special circumstances. Like, truly special. You'll know. 🙈

---

dt_fmap symfname

Query command. It returns the actual pathname to use in the output in place of the symbolic filename symfname. And if no mapping was established for symfname, it just returns the input unchanged. No drama.

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::toc. 🗺️

---

dt_format

Query command. It returns the name of the format associated with the toc formatting engine. That's it. Short and slay. ✨

---

dt_read file

Controlled filesystem access. Returns the contents of file for whatever use the plugin desires. Go wild (within limits).

⚠️ 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. Respect the boundary, bestie. 🚧

---

dt_source file

Controlled filesystem access. This command lets the toc formatting engine load additional Tcl code it may need. Very "let me just grab my stuff" of it.

⚠️ Same rule as before: 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. Like, it's there, but it's giving "emergency only". 💀

---

ex_cget varname

Retrieves the value of variable varname, defined in the current context. Simple. Clean. 🍓

---

ex_cis cname

Determines whether or not the name of the current context is cname. Yes/no energy. 🎯

---

ex_cname

Returns the name of the current context. That's the whole job. 👑

---

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. Don't get cute with it. 😤

---

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. Push it, pop it, that's the cycle. 🌸

---

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. Swap and go. 🦋

---

ex_rb ?newbracket?

Returns the current value of the right macro expansion bracket. Same deal as its left-side twin: 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. 🎀

---

and that's the frontend commands fully served, no crumbs left… but hold on, the plugin's own commands are still coming. There's more. 👀

✨ PLUGIN COMMANDS ✨

Okay bestie, so the plugin is not just sitting there looking cute — it has to bring its own set of commands, and the frontend will call them in a very specific order while it's chewing through input. These commands split into two flavors: management and formatting. Their expected names, signatures, and jobs are right below in the next two subsections. 🫶

💅 MANAGEMENT COMMANDS 💅

These are the ones 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

Once the plugin is loaded and the frontend commands are established, the calls go like this:

toc_numpasses -> n
toc_listvariables -> vars

toc_varset var1 value1
toc_varset var2 value2
...
toc_varset varK valueK
toc_initialize
toc_setup 1
...
toc_setup 2
...
...
toc_setup n
...
toc_postprocess
toc_shutdown
...

So first: number of passes and the set of available engine parameters. Then calls setting those parameters. That second part? Optional, bestie. Not mandatory. 😌

After that, the plugin is initialized, the specified number of passes run, the final result goes through a global post-processing step, and finally the plugin is shut down. This can be followed by more conversions, restarting the sequence at toc_varset. 🔁

During each pass — like, after the toc_setup calls — the frontend processes the input and calls the formatting commands as markup is encountered. That means the order of formatting commands is determined by the grammar of the doctoc markup language, as specified in the doctoc language syntax specification. 📚

Another way to look at the sequence:

• First some basic parameters are determined.
• Then everything starting at the first toc_varset to toc_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 toc_setup and going until either the next toc_setup or toc_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. 🗑️

Now the commands in detail, with names, signatures, and responsibilities:

toc_initialize

Initialization/Shutdown. This one is called at the beginning of every conversion run, as the first command of that run. Important: a run is not a pass, bestie — it may consist of multiple passes. It has to initialize the general state of the plugin, beyond the initialization done during the load. No return value is expected, and any returned value is ignored. 🙈

toc_listvariables

Initialization/Shutdown and Engine parameters. This second command is called after the plugin code has been loaded, i.e. immediately after toc_numpasses. It has to return a list containing the names of the parameters the frontend can set to configure the engine. This list can be empty. 🫙

toc_numpasses

Initialization/Shutdown and Pass management. First command called after the plugin code has been loaded. No other command of the engine will be called before it. It has to return the number of passes this engine requires to fully process the input document. This value has to be an integer number greater or equal to one. 1️⃣

toc_postprocess text

Initialization/Shutdown. Called immediately after the last pass in a run. Its argument is the result of the conversion generated by that pass. It is provided to allow the engine to perform any global modifications of the generated document. If no post-processing is required for a specific format, the command has to just return the argument. Expected to return a value — the final result of formatting the input. 💖

toc_setup n

Initialization/Shutdown and Pass management. Called at the beginning of each pass over the input in a run. Its argument is the number of the pass which has begun. Passes are counted from 1 upward. The command has to set up the internal state of the plugin for this particular pass. No return value is expected, and any returned value is ignored. 🛠️

toc_shutdown

Initialization/Shutdown. Called at the end of every conversion run. It is the last command called in a run. It has to clean up of all the run-specific state in the plugin. After the call, the engine has to be in a state which allows the initiation of another run without fear that information from the last run is leaked into this new run. No return value is expected, and any returned value is ignored. 🧼

toc_varset varname text

Engine parameters. This command is called by the frontend to set an engine parameter to a particular value. The parameter to change is specified by varname, the value to set in text.

The command has to throw an error if an unknown varname is used. Only the names returned by toc_listvariables have to be considered as known. 🚨

The values of all engine parameters have to persist between passes and runs. 💾

🌈 FORMATTING COMMANDS 🌈

The formatting commands have to implement the formatting for the output format, for all the markup commands of the doctoc markup language, except lb, rb, vset, include, and comment. These exceptions are processed by the frontend and are never seen by the plugin. In return, a command for the formatting of plain text has to be provided — something which has no markup in the input at all. 🪄

This means that each of the five markup commands specified in the doctoc language command reference and outside of the set of exceptions listed above has an equivalent formatting command which takes the same arguments as the markup command and whose name is the name of the markup command with the prefix fmt_ added to it. ✨

All commands are expected to format their input in some way per the semantics specified in the command reference and to return whatever part of this that they deem necessary as their result, which will be added to the output. 💫

To avoid essentially duplicating the command reference, we do not list any of the commands here and simply refer the reader to the doctoc language command reference for their signature and description. The sole exception is the plain text formatter, which has no equivalent markup command. 📖

The calling sequence of formatting commands is not as rigid as for the management commands, but determined by the grammar of the doctoc markup language, as specified in the doctoc language syntax specification. 🦋

fmt_plain_text text

No associated markup command.

Called by the frontend for any plain text encountered in the input. It has to perform any and all special processing required for plain text.

The formatted text is expected as the result of the command, and added to the output. If no special processing is required, it has to simply return its argument without change. 🍓

😭 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: 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 👀

• doctoc_intro
• doctoc_lang_cmdref
• doctoc_lang_faq
• doctoc_lang_intro
• doctoc_lang_syntax
• doctools::toc

🔑 KEYWORDS 🔑

• formatting engine
• markup
• plugin
• semantic markup
• table of contents
• toc
• toc formatter

🗂️ CATEGORY 🗂️

Documentation tools

📜 COPYRIGHT 📜

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

---

That’s the whole vibe, bestie. This was tcllib 1.0, page doctoc_plugin_apiref(n) — go forth and plugin-format like the icon you are. 💅✨