doctools(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 doctools — the manual page, bestie edition 💖

okay so this is doctools(n), from the Documentation tools section of your friendly neighbourhood manual. It's giving "I turn your fancy markup into literally any format you want" energy, and honestly? Obsessed.

✨ SYNOPSIS ✨

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

No cap, that's the whole vibe check right there. 🦋

🌸 DESCRIPTION 🌸

Okay so bestie, here's the tea. This package hands you a class — like, an actual class — that makes objects. And those objects? They process and convert text written in the doctools markup language into any output format X for which a formatting engine is available. Any X. The world is your oyster, fr fr. 💅

If you're the kind of reader who's here for the markup language itself, you should start with the doctools language introduction and then just… proceed from there into the formal specs, i.e. the doctools language syntax and the doctools language command reference. That's the whole roadmap. Go off. 🗺️✨

But if you, on the other hand, are the kind of reader who wants 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 "eh I'll skim it later." Because that document specifies, in detail, the interaction between this package and its plugins, i.e. the formatting engines. That's the contract. That's the whole relationship. 🤝💖

tl;dr: markup-language girlies start at the introduction, plugin-writer girlies start at the plugin API reference. Both of you are valid and both of you are eating. 🍓

✨ more parts coming, don't you dare leave ✨

🫶 PUBLIC API 🫶

Okay bestie, this is the part where the package shows you its actual buttons. Let's go 💅

🎀 PACKAGE COMMANDS 🎀

  • ::doctools::new objectName ?option value...? — this is the glow-up command, fr fr. It makes a brand new doctools object, and that object comes with its own little Tcl command named objectName. That object command is fully explained in the OBJECT COMMAND and OBJECT METHODS sections below, so don't panic. ✨

Where does this object command live? If objectName is not fully qualified, it gets created under the current namespace. If it is fully qualified, it goes in the namespace you specified. No cap.

And the options + values that come after the object name? Those set up the object's initial configuration. It's giving "build-a-bear but for converters" 🧸

  • ::doctools::help — a little convenience command for apps that wanna give their users a quick rundown of the available formatting commands and what they mean. It returns a string with a standard help text. Super handy, lowkey iconic. 💖
  • ::doctools::search path — so here's the tea 🍓: whenever an object from this package has to map a format name to the file holding the code for its formatting engine, it searches for that file in a bunch of directories stored in a list. (More on that in FORMAT MAPPING, keep reading.)

That list isn't just three default directories declared by the package itself — it's also extensible by the user of the package, and this command is how you extend it. When you hand it a path to an existing, readable directory, it prepends that directory to the search list. Which means: the path you added last gets searched through first. Order matters, bestie. 👑

An error will be thrown if the path either does not exist, is not a directory, or is not readable. No sneaky fake paths, okay? 😭

🦋 OBJECT COMMAND 🦋

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

objectName method ?arg arg ...?
  • objectName method ?arg arg ...? — the method and its arguments decide exactly what the command does. The OBJECT METHODS section has the full specs, so go look. 💜

✨ OBJECT METHODS ✨

  • objectName configure — call it with zero arguments and it hands you a list of all known options and their current values. A full vibe check of your config. 📋
  • objectName configure option — call it with a single argument and it acts just like cget: it returns the value of the option you named. 🎯
  • objectName configure -option value... — call it with an even number of arguments (at least two) and it reconfigures the options you specified, setting them to their matching values. The legal options live in the OBJECT CONFIGURATION section. Glow-up your object, periodt. 💅
  • objectName cget -option — expects a legal configuration option as its argument and returns that option's current value for the object the method was invoked on. The legal config options are described in OBJECT CONFIGURATION. 🌸
  • objectName destroy — poof. 💀 This method destroys the object it's invoked for. Gone. Not coming back.
  • objectName format text — runs your text through the configured formatting engine and returns the generated string as its result. If no -format was configured for the object, it throws an error. 🙈

It assumes the text is in doctools format as specified in the companion document doctools_fmt. If it isn't? Errors will be thrown. So format your input correctly, bestie, or the vibes will be off. 😭

  • objectName map symbolic actual — this one adds a single entry to the per-object mapping from symbolic filenames to the actual uris. The object just stores that 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 how the objects from this package and doctools formatting engines talk to each other. 🗺️
  • objectName parameters — returns a list containing the names of all the engine parameters provided by the configured formatting engine. If the object isn't configured for a specific format yet, you get an empty list back. No format, no params, that's the rule. 🎀
  • objectName search path — extends the per-object list of paths searched for doctools formatting engines. Peep the command ::doctools::search if you wanna extend the per-package list instead. Heads up: the path entered last gets searched first. More details in FORMAT MAPPING. 🔍
  • objectName setparam name value — sets the named engine parameter to the specified value. It will 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 that name. You can grab the list of parameters the configured engine provides via the parameters method. 🔧
  • objectName warnings — returns a list containing all the warnings generated by the configured formatting engine during the last invocation of the format method. Yes bestie, the receipts. 🧾

👑 OBJECT CONFIGURATION 👑

Every doctools object understands these configuration options. All of them. No skips. 💖

  • -file file — the argument of this option is 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.

Default value: the empty string.

The configured formatting engine should interpret the value as the name of the file containing the document currently being processed. 📄

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

Okay so real talk: -file and -ibase look similar but they are very different. The value of -file is used by some engines to generate proper relative references between output documents (HTML). So that one is a destination path. -ibase, on the other hand, is used to resolve relative include paths — so it deals with source paths. Two totally different lanes, don't mix them up. 🛣️

Default value: the empty string.

  • -module text — the argument of this option is 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.

Default value: the empty string.

The configured formatting engine should interpret the value as the name of the module that the file containing the currently processed document belongs to. 📦

  • -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 format method. Its default value is the empty string. And heads up: the format method can't be used if this option was never set to a valid value at least once. 🚫

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 gets thrown. And in that case, a previously configured format is left untouched. (So no, a bad format name won't nuke your old setup. Phew. 😮‍💨)

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

  • -deprecated boolean — this option is 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. Default value is FALSE. In other words, no warnings will be generated by default. 🙅
  • -copyright text — the argument of this option is 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.

Default value: the empty string.

The configured formatting engine should interpret the value as a copyright assignment for the document currently being processed, or for the package described by it.

This information must be used if and only if the engine is unable to find any copyright assignments within the document itself. Those in-document ones are specified by the formatting command copyright, described in more detail in the companion document doctools_fmt, which specifies the doctools format itself. So like, fallback only, bestie. 💜

🌈 FORMAT MAPPING 🌈

The package and the object run this algorithm when they try to map a format name foo to a file containing an implementation of a formatting engine for foo. Watch the order, it's a whole journey:

  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 "fmt.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. 🧺

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

This list of paths can be extended through the command ::doctools::search. It initially contains one path: the subdirectory "mpformats" of the directory the package itself is located in. In other words, if the package implementation doctools.tcl is installed in the directory /usr/local/lib/tcllib/doctools, then by default it will search the directory /usr/local/lib/tcllib/doctools/mpformats for format implementations. 🗂️

  1. The mapping fails. 💀 That's it, that's the ending. No file for you.

✨ PREDEFINED ENGINES ✨

okay bestie so the package ships with a whole wardrobe of ready-to-go engines, one per format, and some of them let you pass parameters. we're gonna walk through all of them, parameters and everything, no skips 💅

🌐 html

this one generates HTML markup — perfect for web browsers and honestly anything browser-adjacent. it takes four parameters, and yes we're doing all four:

  • footer — has to be valid, self-contained HTML markup for the body section of an HTML document. default is the empty string. it gets dropped into the generated output right before the closing </body> tag, i.e. it shuts the body of the generated HTML. vibe: use it to slide some boilerplate footer markup into the doc. 🎀
  • header — also valid, self-contained HTML markup for the body section of an HTML document. default is the empty string. this one lands in the generated output right after the opening <body> tag, i.e. it kicks off the body of the generated HTML. vibe: boilerplate header markup, inserted. ✨
  • meta — valid, self-contained HTML markup for the header section of an HTML document. default is the empty string. inserted into the generated output right after the opening <head> tag, i.e. it starts the header section of the generated HTML. vibe: boilerplate meta-data markup — stylesheet references, standard meta keywords, all of that. 🦋
  • xref — this one has to be a list of triples giving cross-reference info. the engine uses it to create extra hyperlinks. each triple is a list holding a pattern, a symbolic filename, and a fragment reference, in exactly that order. heads up: if a pattern shows up more than once, the last occurrence of that pattern is the one that wins. 🙈

the engine hits up the xref database whenever it bumps into specific commands, and it makes a link if the relevant text matches one of the patterns. no match → no link, periodt. the link points to the uri file#fragment from the relevant triple, after the symbolic file name gets converted into the actual uri via dt_fmap (peep the doctools plugin API reference for that one). that file-to-uri mapping was built by calls to the map method of the doctools object (see the OBJECT METHODS section).

these are the formatting commands that consult the xref database:

  • cmd word — looks for the patterns sa,word and word, in that order. if that flops, it converts word to all lowercase and tries again.
  • syscmd word — looks for the patterns sa,word and word, in that order. if that flops, it converts word to all lowercase and tries again.
  • term word — looks for the patterns kw,word, sa,word and word, in that order. if that flops, it converts word to all lowercase and tries again.
  • package word — looks for the patterns sa,word, kw,word and word, in that order. if that flops, it converts word to all lowercase and tries again.
  • see_also word... — for each word handed to the command, it looks for the patterns sa,word and word, in that order. if that flops, it converts word to all lowercase and tries again.
  • keywords word... — for each word handed to the command, it looks for the patterns kw,word and word, in that order. if that flops, it converts word to all lowercase and tries again.

🧪 latex

generates output that's suitable for the latex text processor — you know, the one that comes straight out of the TeX world. academic queen behavior honestly 📚

📋 list

this one pulls the version, section and title of the manpage out of the document. so basically it's the girl you call when you wanna generate a directory listing for a whole set of manpages. organized. 💅

📜 nroff

generates nroff output, for processing by nroff or groff. the result is your standard man pages, exactly like the unix world knows and loves them. classic, iconic, no notes. 👑

🍓 markdown

generates Markdown markup. it takes two parameters:

  • header — has to be valid, self-contained markdown markup for the body section of a markdown document. default is the empty string. it gets inserted into the generated output right before the table of contents. vibe: boilerplate header markup, but make it markdown. 🎀
  • xref — has to be a list of triples specifying cross-reference info.

the full deets on the expected syntax and how the engine uses it internally are explained above, under the html engine. same energy, different format. ✨

🕳️ null

generates literally no output at all. zero. nada. use it when you just wanna validate some input and don't need the receipts. 💀

🧚 tmml

generates TMML markup as specified by Joe English. the Tcl Manpage Markup Language is a derivate of XML. fancy. 🫶

🌈 wiki

generates Wiki markup as understood by Jean Claude Wippler's wikit application. wiki wiki, bestie. ✨

🐛 BUGS, IDEAS, FEEDBACK 🐛

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. like, it's software, it's giving mortal. 😭

please report them in the category doctools of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. also please send any ideas for enhancements you might have for either the package and/or the documentation. we want them, fr fr. 🫶

if you're proposing code changes, please provide unified diffs — that's the output of diff -u. no cap.

also note: attachments are strongly preferred over inlined patches. to attach something, go to the Edit form of the ticket immediately after creating it, and then use 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>

okay that's the whole page bestie, we ate and left no crumbs 💖 this was doctools(n) from tcllib, version 1.6.1 — go forth and convert some docs, ily, mwah 🎀✨🦋

📦 where this page comes from