doctools_plugin_apiref(n)

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

💖 doctools_plugin_apiref 💖

doctools plugin API reference — from the Documentation tools manual, section n. Bestie, this is the whole ✨vibe guide✨ for anyone writing a doctools formatting engine. Grab a snack, we're going deep. 🫶

🌸 NAME 🌸

doctools_plugin_apiref — the doctools plugin API reference, aka the map of every command your plugin can call and every command your plugin has to answer. 🗺️💅

✨ SYNOPSIS ✨

dt_copyright

dt_file

dt_mainfile

dt_fileid

dt_fmap symfname

dt_format

dt_imgdata key extensions

dt_imgdst key extensions

dt_imgsrc key extensions

dt_lnesting

dt_module

dt_read file

dt_source file

dt_user

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?

fmt_initialize

fmt_listvariables

fmt_numpasses

fmt_postprocess text

fmt_setup n

fmt_shutdown

fmt_varset varname text

fmt_plain_text text

🦋 DESCRIPTION 🦋

Okay so listen — this doc is literally for plugin writers. That's you if you're a developer who wants to build a doctools formatting engine for some output format X. (Yes, X is a placeholder, it's giving mysterious on purpose. 🕵️‍♀️)

It lays out the exact interaction between the doctools package and its plugins. In other words: the interface any doctools formatting engine has to comply with. No skipping, no freestyling. 👑

Heads up: this document is about version 1 of the interface. Periodt.

And if you're actually more of a markup language girlie than a plugin girlie? Start with the doctools language introduction and go from there into the formal specs — that's the doctools language syntax and the doctools language command reference. Slay. 💜

🌈 OVERVIEW 🌈

The API for a doctools formatting engine splits into two major sections, and honestly, it's giving two-sided friendship bracelet. 🎀

On one side, there's a set of commands your plugin can use to query the frontend. The frontend provides these and links them straight into the plugin interpreter. All the details live in the FRONTEND COMMANDS section below.

On the other side, your plugin has to provide its own set of commands, which the frontend then calls in a specific sequence while it's processing input. Those split into two categories again:

  • management — the admin, the organizer, the girl with the clipboard 📋
  • formatting — the one who actually makes it pretty 💅

Go check out the PLUGIN COMMANDS section and its subsections for all of that.

👑 FRONTEND COMMANDS 👑

This section specifies the set of commands through which a plugin — also known as a doctools formatting engine — can query the frontend. The frontend provides these commands, and they get linked into the plugin interpreter.

So basically: a doctools formatting engine can assume that all of the following commands are present whenever any of its own commands (the ones in PLUGIN COMMANDS) get executed. Every single one. No cap. ✅

Beyond that, it can also assume it has full access to its own safe interpreter, which means it's not able to damage the other parts of the processor, and it also can't damage the filesystem. Protected. 🛡️✨

⚠️ BUT — and this is the important part — it is able to either kill or hang the whole process, by exiting, or by running an infinite loop. So like… with great power, bestie. 💀

Coming back to the imported commands: everything with the dt_ prefix gives you limited access to specific parts of the frontend, whereas everything with the ex_ prefix gives you access to the state of the textutil::expander object, which is the thing doing the main parsing of the input inside the frontend.

🚨 These ex_ commands should not be used except under very special circumstances. Like, very very special. 🙈

🔎 dt_ commands (query the frontend, bestie)

  • dt_copyright — Query command. Returns a string with the copyright info the doctools processor was configured with. The option that matters here is -copyright. 📜
  • dt_file — Query command. Returns the full path of the file containing the input currently being processed by the engine. Fair warning: this may be an included file. 🗂️
  • dt_mainfile — Query command. Returns the full path of the toplevel file containing the input currently processed by the engine. The main character file, if you will. 👑
  • dt_fileid — Query command. Returns the name of the file containing the input currently processed by the engine — no path, no extension. Just the name, clean. ✨
  • dt_fmap symfname — Query command. Returns the actual pathname to use in the output, in place of the symbolic filename symfname. If no mapping was established for symfname, it just hands you back the input unchanged. The mappings themselves are set up with the map method of a frontend, as explained in the OBJECT METHODS section of the docs for the doctools package. 🔁
  • dt_format — Query command. Returns the name of the format associated with the doctools formatting engine. 🎨
  • dt_imgdata key extensions — Query command. Access to the image map. It looks for an image recorded under key and having the specified extensions. If a matching image is found, its data comes back as the result. If not? Empty string. 🖼️
  • dt_imgdst key extensions — Query command. Access to the image map. Looks for an image recorded under key with the specified extensions. If a match is found, you get its destination path in the output as the result. Otherwise, empty string. 📤
  • dt_imgsrc key extensions — Query command. Access to the image map. Looks for an image recorded under key with the specified extensions. If a match is found, you get its origin path as the result. Otherwise, empty string. 📥
  • dt_lnesting — Query command. Returns the number of lists currently open. Stacked lists? We been knew. 📚
  • dt_module — Query command. Returns the name of the module the input currently being processed belongs to. 🧩
  • dt_read file — Controlled filesystem access. Returns the contents of file, for whatever use your plugin desires. Only files that 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 that directory causes an error. Do not test it, bestie, it's not gonna go well.
  • dt_source file — Controlled filesystem access. This one lets the doctools formatting engine load extra Tcl code it might need. Same rule as above: only files either in the same directory as the file containing the engine, or below it, can be loaded.
🚫 Trying to load a file outside of that directory causes an error. Same energy. Same consequences.
  • dt_user — Query command. Returns the name of the current user, as known to the Tcl interpreter that the frontend controlling the formatting engine lives in. 🧑‍💻

🙈 ex_ commands (the textutil::expander state, handle with care)

  • ex_cappend text — Appends a string to the output in the current context. This command should rarely be used by macros or application code. Rarely. Like, blink-and-you'll-miss-it rarely. 😬
  • ex_cget varname — Retrieves the value of the variable varname, defined in the current context. 🎣
  • 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 it. That's the command. 🏷️
  • ex_cpop cname — Pops a context off the context stack, returning all the accumulated output in that context. The context must be named cname, or an error results. No sneaky mismatched names. ❌
  • 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. Don't leave it hanging, that's rude. 🙅‍♀️
  • ex_cset varname value — Sets the variable varname to value in the current context. ✍️
  • ex_lb ?newbracket? — Returns the current value of the left macro expansion bracket. Use this 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 that is what gets returned. 🔧
  • ex_rb ?newbracket? — Returns the current value of the right macro expansion bracket. Same deal: for use as, or within, a macro when the bracket needs to appear in the output text. If newbracket is specified, it becomes the new bracket, and it gets returned. 🔨

…and bestie, we are not done yet. Part 2 is coming. Stay tuned. 💖

💖 PLUGIN COMMANDS 💖

okay bestie, so the plugin has to provide its own little set of commands, and the frontend is gonna call them in a very specific sequence while it's processing input. no cap. 🫶

They fall into two categories: management and formatting. Their expected names, signatures, and responsibilities are specified in the following two subsections. ✨

✨ MANAGEMENT COMMANDS ✨

The management commands a plugin has to provide are used by the frontend 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 will be called in the following sequence:

fmt_numpasses -> n
fmt_listvariables -> vars

fmt_varset var1 value1
fmt_varset var2 value2
...
fmt_varset varK valueK
fmt_initialize
fmt_setup 1
...
fmt_setup 2
...
...
fmt_setup n
...
fmt_postprocess
fmt_shutdown
...

I.e. first the number of passes and the set of available engine parameters is established, followed by calls setting the parameters. That second part is optional. 👑

After that the plugin is initialized, the specified number of passes executed, the final result run through a global post processing step and at last the plugin is shutdown again. This can be followed by more conversions, restarting the sequence at fmt_varset. 🔁

In each of the passes, i.e. after the calls of fmt_setup, the frontend will process the input and call the formatting commands as markup is encountered. This means that the sequence of formatting commands is determined by the grammar of the doctools markup language, as specified in the doctools language syntax specification. 📜

A different way of looking at the sequence is:

  • First some basic parameters are determined.
  • Then everything starting at the first fmt_varset to fmt_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 fmt_setup and going until either the next fmt_setup or fmt_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. 💀

The commands, their names, signatures, and responsibilities are, in detail:

  • fmt_initialize — Initialization/Shutdown. This command is called at the beginning of every conversion run, as the first command of that run. Note that a run is not a pass, but 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. 🧼
  • fmt_listvariables — Initialization/Shutdown and Engine parameters. Second command is called after the plugin code has been loaded, i.e. immediately after fmt_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. 📋
  • fmt_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. 🔢
  • fmt_postprocess text — Initialization/Shutdown. This command is 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. 🎀
  • fmt_setup n — Initialization/Shutdown and Pass management. This command is 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. ⚙️
  • fmt_shutdown — Initialization/Shutdown. This command is 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. 🧹
  • fmt_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 fmt_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 doctools 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 49 markup commands specified in the doctools 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 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 command here and simply refer the reader to the doctools 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 doctools markup language, as specified in the doctools 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 👀

doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax

🔑 KEYWORDS 🔑

document, formatter, formatting engine, manpage, markup, semantic markup

📂 CATEGORY 📂

Documentation tools

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

and that's the whole vibe, bestie — signed off from tcllib 1.1, page doctools_plugin_apiref(n) 💖✨🎀

📦 where this page comes from