doctools(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

doctools(3tcl) — welcome to the Documentation tools manual page, bestie. This is part 1, and it's lowkey giving iconic Unix manual energy. 💅✨

🎀 NAME 🎀

doctools — doctools — Processing documents.

No cap, that's literally the name line: doctools - doctools - Processing documents. She said it twice because she's that girl. 👑

✨ SYNOPSIS ✨

Okay so here's the whole vibe check for how you call this thing. Copy-paste these exactly, because Tcl does not play about syntax, fr fr:

package require Tcl 8.5 9

package require doctools ?1.6.1?

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

::doctools::help

::doctools::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

That's the whole menu, bestie. Every command, every placeholder, every ?arg arg ...? — we are not skipping a single crumb. 🍓

💖 DESCRIPTION 💖

This package is literally serving a class, bestie. It creates objects that can process and convert text written in the doctools markup language into any output format X — yes, any format X — as long as a formatting engine is available for it. That's the assignment. That's the whole point. Slay. 🔥

If you're a reader who is obsessed with the markup language itself, start with the doctools language introduction and then proceed from there to the formal specifications, i.e. the doctools language syntax and the doctools language command reference. That's the path. Don't skip steps, iykyk. 💅

If, on the other hand, you're the reader who wishes to write her own formatting engine for some format — i.e. you're a plugin writer — then reading and understanding the doctools plugin API reference is an absolute necessity. Not optional. Not a suggestion. It is required, because that document specifies the interaction between this package and its plugins, i.e. the formatting engines, in detail. Periodt. 👑💜

🌸 PUBLIC API 🌸

Okay bestie, this is the part where we meet the actual commands you get to call. Grab a snack. 🍓

💅 PACKAGE COMMANDS

These are the top-level commands the package hands you the second you load it. Three of them. That's it. Iconic minimalism.

  • ::doctools::new objectName ?option value...? — this one makes you a brand-new doctools object, and it comes with its very own Tcl command whose name is objectName. Like, the object is a command, the command is the object, it's giving main character energy. That whole object command situation is explained in full detail down in OBJECT COMMAND and OBJECT METHODS, so don't worry, we're getting there. Now the namespace tea: if objectName isn't fully qualified, the object command gets created under the current namespace — but if it is fully qualified, it lands in whatever namespace you specified. Your call, bestie.

And the option value pairs that come after the object name? Those set the initial configuration of the object. So you can skip the whole "configure it later" arc and just set the vibe upfront. ✨

  • ::doctools::help — this is the convenience-queen command. It's for apps that wanna hand their users a lil short description of the available formatting commands and what they mean. It returns a string containing a standard help text. Boom. Done. 🎀
  • ::doctools::search path — so here's the thing. Whenever an object made by this package needs to map the name of a format to the file that contains the code for its formatting engine, it goes looking through a bunch of directories stored in a list. If you want the full lore on that, go read FORMAT MAPPING.

That list isn't just three default directories declared by the package itself (though yeah, it has those too) — it's also extensible by you, the user of the package, and this command is literally how you do that. When you hand it a path to a directory that exists and is readable, it will prepend that directory to the list of directories to search. Which means: the path you added last gets searched first. LIFO behavior, no cap. 💅

And if the path doesn't exist, or isn't a directory, or isn't readable? Error. Thrown. Immediately. The package does not play. 😭

👑 OBJECT COMMAND

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

objectName method ?arg arg ...?

The method and its arg'uments decide the exact behavior of the command. The detailed specs live in OBJECT METHODS, right below. Keep scrolling, we're so close. 🦋

✨ OBJECT METHODS ✨

Here's the whole menu of methods. Every one of them is called on your objectName. Let's go one by one, because I love being thorough.

  • objectName configure — called with no arguments at all? It returns a list of all the known options and their current values. A little config snapshot. 📸
  • objectName configure option — called with a single argument? It behaves exactly like the cget method, and returns the value of the option you named in said argument.
  • objectName configure -option value... — called with an even number of arguments, at least two? Now it reconfigures the options you named, setting them to the associated values. This is the glow-up method.

The legal options are described in OBJECT CONFIGURATION, so hold that thought.

  • objectName cget -option — this one expects a legal configuration option as its argument, and it returns the current value of that option, for the object you invoked the method on. Simple. Clean. Slay.

Again: legal configuration options = OBJECT CONFIGURATION.

  • objectName destroy — destroys the object it's invoked for. That's it. That's the method. Rip bozo 🕊️
  • objectName format text — runs text through the configured formatting engine and returns the generated string as its result. BUT — and this is important — an error will be thrown if no -format was configured for the object. So configure your format first, bestie, don't be chaotic.

This method assumes text is in doctools format as specified in the companion document doctools_fmt. If it isn't? Errors. Thrown. Otherwise. 💀

  • objectName map symbolic actual — 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 doctools plugin API reference, which spells out the whole interaction between the objects this package creates and doctools formatting engines. 🫶
  • objectName parameters — returns a list containing the names of all engine parameters provided by the configured formatting engine. And if the object isn't yet configured for a specific format? It returns an empty list. No format, no params, no drama. 🌸
  • objectName search path — this extends the per-object list of paths searched for doctools formatting engines. (Compare and contrast with ::doctools::search, which extends the per-package list — different list, same energy.) Note that the path entered last will be searched first. For more details, see FORMAT MAPPING.
  • objectName setparam name value — sets the named engine parameter to the specified value. It will throw an error if either:
    • the object is not yet configured for a specific format, or
    • the formatting engine for the configured format does not provide a parameter with the given name.

And if you wanna know what parameters the configured formatting engine does provide, just hit up the parameters method. Teamwork. 💖

  • objectName warnings — returns a list containing all the warnings generated by the configured formatting engine during the last invocation of the format method. Receipts! 🧾

💜 OBJECT CONFIGURATION

All doctools objects understand these configuration options. Every. Single. One. Let's get into it.

  • -file file — the argument gets stored in the object and made available to the configured formatting engine through the commands dt_file and dt_mainfile. Those commands are described in more detail in the companion document doctools_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.

  • -ibase file — the argument gets stored in the object and used as the base path for resolution of relative include paths. If this option isn't set (empty string), the value of -file is used instead.

Now, listen, because this trips people up: -file and -ibase look similar but they are actually very different. The value of -file is used by some engines for generating proper relative references between output documents (HTML). As such, that's a destination path. The -ibase, on the other hand, is used to resolve relative include paths, and as such it deals with source paths. One goes out, one comes in. Not the same thing, bestie. 🦋

The default value of this option is the empty string.

  • -module text — the argument gets stored in the object and made available to the configured formatting engine through the command dt_module. That command is described in more detail in the companion document doctools_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 module the file containing the document currently processed belongs to.

  • -format text — the argument specifies the format to generate, and by implication, the formatting engine to use when converting text via the format method. Its default value is the empty string. And heads up: the format method cannot be used if this option is not set to a valid value at least once. So like. Set it. 😭

The package will immediately try to map the given name to a file containing the code for a formatting engine generating that format. If that mapping fails, an error will be thrown — but good news, in that case a previously configured format is left untouched. No collateral damage. ✨

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

  • -deprecated boolean — this one's a boolean flag. The object will generate warnings if this flag is set and the text given to the format method contains the deprecated markup command strong. Its default value is FALSE — in other words, no warnings will be generated. Silence is golden. 🤫
  • -copyright text — the argument gets stored in the object and made available to the configured formatting engine through the command dt_copyright. That command is described in more detail in the companion document doctools_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 a copyright assignment for the document currently processed, or the package described by it.

And this is a must-use-if-and-only-if situation: this information must be used if and only if the engine is unable to find any copyright assignments within the document itself. Such assignments are specified by the formatting command copyright, which is described in more detail in the companion document doctools_fmt, which specifies the doctools format itself. So: fallback only. No stealing credit. 👑

🌈 FORMAT MAPPING 🌈

The package and object will perform the following algorithm when trying to map a format name foo to a file containing an implementation of a formatting engine for foo. Follow along, it's a four-step journey.

  1. If foo is the name of an existing file, then this file is directly taken as the implementation. Shortest path wins. ⭐
  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 "fmt.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.

  1. If not, the list of package paths is searched. For each directory in the list, the package checks if that directory contains a file "fmt.foo". If yes, then that file is taken as the implementation.

This list of paths can be extended through the command ::doctools::search. It contains initially one path: the subdirectory "mpformats" of the directory the package itself is located in. In other words — and here's a concrete example, bestie, because examples eat every time — if the package implementation "doctools.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. 📂

  1. The mapping fails. That's it. That's the ending. 💀

✨ PREDEFINED ENGINES ✨

Okay so bestie, the package comes with a whole squad of predefined engines for these formats 👑. Some of them have parameters, and we’re gonna spill all the tea on those too, no cap. 💅

🌸 html 🌸

This engine generates HTML markup, for processing by web browsers and the like. It’s giving web-ready. It supports four 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. This can be used 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. This can be used 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. This can be used to insert boilerplate meta data markup into the generated document, like references to a stylesheet, standard meta keywords, etc. 💖
  • xref — The value for this parameter has to be a list of triples specifying cross-reference information. This information is used by the engine to create more hyperlinks. Each triple is a list containing a pattern, symbolic filename and fragment reference, in this order. If a pattern is specified multiple times the last occurrence of the pattern will be used. 🔥

The engine will consult the xref database when encountering specific commands and will create a link if the relevant text matches one of the patterns. No link will be created if no match was found. The link will go to the uri file#fragment listed in the relevant triple, after conversion of the symbolic file name to the actual uri via dt_fmap (see the doctools plugin API reference). This file-to-uri mapping was build by calls to the method map of the doctools object (See section OBJECT METHODS). 👑

The following formatting commands will consult the xref database:

  • cmd word — The command will look for the patterns sa,word, and word, in this order. If this fails if it will convert word to all lowercase and try again. 🦋
  • syscmd word — The command will look for the patterns sa,word, and word, in this order. If this fails if it will convert word to all lowercase and try again. 🦋
  • term word — The command will look for the patterns kw,word, sa,word, and word, in this order. If this fails if it will convert word to all lowercase and try again. 🌸
  • package word — The command will look for the patterns sa,word, kw,word, and word, in this order. If this fails if it will convert word to all lowercase and try again. 🌈
  • see_also word... — The command will look for the patterns sa,word, and word, in this order, for each word given to the command. If this fails if it will convert word to all lowercase and try again. 💜
  • keywords word... — The command will look for the patterns kw,word, and word, in this order, for each word given to the command. If this fails if it will convert word to all lowercase and try again. 💜

🧚 latex 🧚

This engine generates output suitable for the latex text processor coming out of the TeX world. It’s giving academic baddie energy. 📚✨

🍓 list 🍓

This engine 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. Perfect for when you need the receipts. 🧾

🌈 nroff 🌈

This engine generates nroff output, for processing by nroff, or groff. The result will be standard man pages as they are known in the unix world. Old school but iconic. 💅

🌸 markdown 🌸

This engine generates Markdown markup. It supports two parameters:

  • header — The value for this parameter has to be valid selfcontained markdown markup for the body section of a markdown document. The default value is the empty string. The value is inserted into the generated output just before the table of contents. This can be used to insert boilerplate header markup into the generated document. 🎀
  • xref — The value for this parameter has to be a list of triples specifying cross-reference information. The full details of expected syntax and engine-internal use are explained above for the html engine. 👑

💀 null 💀

This engine generates no output at all. This can be used if one just wants to validate some input. Literally the silent treatment, but make it useful. 🙈

🦋 tmml 🦋

This engine generates TMML markup as specified by Joe English. The Tcl Manpage Markup Language is a derivate of XML. Fancy, no cap. ✨

👑 wiki 👑

This engine generates Wiki markup as understood by Jean Claude Wippler’s wikit application. Wiki vibes only. 🌐

💖 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. We wanna hear it all, bestie. 🫶

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. That’s the move. 💅

🌟 SEE ALSO 🌟

  • doctools_intro
  • doctools_lang_cmdref
  • doctools_lang_intro
  • doctools_lang_syntax
  • doctools_plugin_apiref

🔥 KEYWORDS 🔥

HTML, TMML, conversion, documentation, manpage, markdown, markup, nroff

🎀 CATEGORY 🎀

Documentation tools

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

💖 brought to you by tcllib 1.6.1, doctools(3tcl), and all the good vibes. Stay slaying, bestie. ✨

📦 where this page comes from