doctools::toc(n)

💖 doctools::toc(n) — Documentation tools 💖

okay bestie, sit DOWN, because we're about to talk about the page that handles tables of contents and it's honestly a whole vibe 🎀

---

✨ NAME ✨

doctools::toc — doctoc — Processing tables of contents 📖

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require doctools::toc ?1.3.1?

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

::doctools::toc::help

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

---

🦋 DESCRIPTION 🦋

So like, what IS this package? It hands you a class for making objects, and those objects are little machines that take text written in the doctoc markup language and convert it into any output format X — literally any format, as long as there's a formatting engine available for it. Slay. 💅

If you're the reader who actually wants to know the markup language itself, bestie, start with the doctoc language introduction and then keep going from there into the formal specs, aka the doctoc language syntax and the doctoc language command reference. That's your path. 🫶

But if you're the reader who wants to write her own formatting engine for some format — i.e. you're a plugin writer — then reading and understanding the doctoc plugin API reference is an absolute necessity, no cap. That document spells out, in detail, the whole interaction between this package and its plugins, aka the formatting engines. Don't skip it, it's giving required reading. 📚

---

👑 PUBLIC API 👑

🌈 PACKAGE COMMANDS 🌈

• ::doctools::toc::new objectName ?-option value ...? — This command creates a brand new doctoc object, and it comes with a Tcl command attached whose name is objectName. That object command is explained in full detail over in the sections OBJECT COMMAND and OBJECT METHODS. The object command gets created under the current namespace if objectName isn't fully qualified, and inside the specified namespace if it is. The options and their values that come after the name of the object set the initial configuration of the object. ✨
• ::doctools::toc::help — A lil convenience command for apps that wanna give their user a short description of the available formatting commands and what they mean. It returns a string holding a standard help text. Easy peasy. 💖
• ::doctools::toc::search path — Whenever an object made by this package needs to map the name of a format to the file containing the code for its formatting engine, it searches for that file in a bunch of directories kept in a list. The FORMAT MAPPING section explains this more. 🗺️

This 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 do it. Give it a path to an existing, readable directory and it prepends that directory to the search list. Which means: the path you added last is the one that gets searched first. Last in, first searched, iconic behaviour. 👑

An error gets thrown if the path doesn't exist, isn't a directory, or isn't readable. No exceptions, bestie. 💀

🎀 OBJECT COMMAND 🎀

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

• objectName method ?arg arg ...? — The method method plus its arguments decide the exact behaviour of the command. Detailed specs live in the OBJECT METHODS section. 🌸

💜 OBJECT METHODS 💜

• objectName configure — Called with no arguments at all, this method returns a list of every known option and its current value. The whole roster. 📋
• objectName configure option — Called with a single argument, this method behaves just like the cget method and returns the value of the option named by that argument. 🫶
• objectName configure -option value... — Called with an even number of arguments, at least two, this method reconfigures the specified options of the object, setting them to the associated values. The legal options are described in the OBJECT CONFIGURATION section. ✨
• objectName cget -option — This method expects a legal configuration option as its argument and returns the current value of that option for the object the method was invoked on. Legal configuration options are described in the OBJECT CONFIGURATION section. 💅
• objectName destroy — This method destroys the object it was invoked for. Poof. Gone. 🦋
• objectName format text — This method runs text through the configured formatting engine and returns the generated string as its result. An error gets thrown if no -format was configured for the object. 🚨

The method assumes the text is in doctoc format as specified in the companion document doctoc_fmt. Otherwise? Errors get thrown. So format it right or catch hands. 😭

• objectName map symbolic actual — This method 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 doctoc plugin API reference, which specifies the interaction between the objects created by this package and toc formatting engines. 🗂️
• objectName parameters — This method returns a list containing the names of all engine parameters provided by the configured formatting engine. If the object isn't configured for a specific format yet, it returns an empty list. Nothin' but vibes and emptiness. 🍓
• objectName search path — This method extends the per-object list of paths searched for toc formatting engines. (See also the command ::doctools::toc::search for how to extend the per-package list of paths.) Heads up: the path entered last will be searched first. For more details, see the FORMAT MAPPING section. 🔍
• objectName setparam name value — This method sets the named engine parameter to the specified value. It throws 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 the given name. You can grab the list of parameters the configured formatting engine provides through the parameters method. 🌟
• objectName warnings — This method returns a list containing every warning that was generated by the configured formatting engine during the last invocation of the format method. Read your warnings, bestie, they're telling you something. 🙈

---

🌟 OBJECT CONFIGURATION 🌟

All doctoc objects understand these configuration options, periodt:

• -file file — The argument of this option gets stored in the object and made available to the configured formatting engine through the command dt_file. That command is described in more detail in the companion document doctoc_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 currently being processed.

• -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. The format method cannot be used if this option is not 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. An error gets thrown if this mapping fails. In that case, a previously configured format is left untouched — so no harm done to your old setup. 🛟

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

---

🗺️ FORMAT MAPPING 🗺️

When the package and object try to map a format name foo to a file containing an implementation of a formatting engine for foo, here's the algorithm they run, step by step:

1. If foo is the name of an existing file, then that file is directly taken as the implementation. ✨
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 "toc.foo". If yes, that file is taken as the implementation. 🔍

Note that this list of paths starts out empty and can be extended through the object method search.

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

This list of paths can be extended through the command ::doctools::toc::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 "doctoc.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. 🏠

4. The mapping fails. 💀

ngl, if you made it all the way to step 4, the engine is simply not there. That's the whole mood of a failed mapping.

---

and that's part 1 bestie!! don't go anywhere, more is literally coming, this page is long and we're only getting started 🫶✨

✨ PREDEFINED ENGINES ✨

okay bestie, so this package ships with a whole lil roster of predefined formatting engines for the formats below. Some of them take engine parameters, and we are gonna call those out loud, no cap.

• html — this one spits out HTML markup, ready for web browsers and the like. It supports three parameters:
  • footer — the value for this parameter has to be valid selfcontained HTML markup for the body section of a HTML document. Default value is the empty string. It gets inserted into the generated output just before the </body> tag, closing the body of the generated HTML. Use it 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. Default value is the empty string. It gets inserted into the generated output just after the <body> tag, starting the body of the generated HTML. Use it 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. Default value is the empty string. It gets inserted into the generated output just after the <head> tag, starting the header section of the generated HTML. Use it to insert boilerplate meta data markup into the generated document, like references to a stylesheet, standard meta keywords, etc.
• latex — this engine generates output suitable for the latex text processor coming out of the TeX world.
• 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.
• markdown — this engine generates Markdown markup.
• 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.
• null — this engine generates no outout at all. This can be used if one just wants to validate some input.
• tmml — this engine generates TMML markup as specified by Joe English. The Tcl Manpage Markup Language is a derivate of XML.
• wiki — this engine generates Wiki markup as understood by Jean Claude Wippler's wikit application.

---

😭 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 at 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_intro
• doctoc_lang_syntax
• doctoc_plugin_apiref

---

💅 KEYWORDS 💅

• HTML
• TMML
• conversion
• doctoc
• documentation
• latex
• manpage
• markdown
• markup
• nroff
• table of contents
• toc
• wiki

---

🌈 CATEGORY 🌈

Documentation tools

---

👑 COPYRIGHT 👑

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

---

okay that's the whole vibe, bestie. this page is from tcllib, version 1.3.1, for doctools::toc(n), and the date is whatever the footer stamped — mwah 💖✨