dtplite(n)

✨ NAME ✨

okay so this is the dtplite(n) page, bestie, and it's literally about one thing:

dtplite — the Lightweight DocTools Markup Processor 🎀

---

🌸 SYNOPSIS 🌸

dtplite -o output ?options? format inputfile

dtplite validate inputfile

dtplite -o output ?options? format inputdirectory

dtplite -merge -o output ?options? format inputdirectory

---

💖 DESCRIPTION 💖

So the app this whole doc is about, dtplite, is the successor to the extremely simple mpexpand. Its functionality was influenced by the dtp doctools processor, and the way it's so much more powerful than mpexpand yet still just as easy to use? Iconic. It's definitely easier than dtp with its myriad of subcommands and options. no cap. 💅

dtplite is based upon the package doctools, same as the other two processors. 🦋

🧚 USE CASES 🧚

dtplite was written with these three use cases in mind, periodt:

1. Validation of a single document, i.e. checking that it was written in valid doctools format. This mode can also be used to get a preliminary version of the formatted output for a single document, for display in a browser, nroff, etc., allowing proofreading of the formatting. 👀
2. Generation of the formatted documentation for a single package, i.e. all the manpages, plus a table of contents and an index of keywords. 📚
3. An extension of the previous mode of operation, a method for the easy generation of one documentation tree for several packages, and especially of a unified table of contents and keyword index. 🗂️

Beyond the above we also want to make use of the customization features provided by the HTML formatter. It is not the only format the application should be able to generate, but we anticipate it to be the most commonly used, and it is one of the few which do provide customization hooks. ✨

We allow the caller to specify a header string, footer string, a stylesheet, and data for a bar of navigation links at the top of the generated document. While all can be set as long as the formatting engine provides an appropriate engine parameter (See section OPTIONS) the last two have internal processing which make them specific to HTML. 🎀

👑 COMMAND LINE 👑

dtplite -o output ?options? format inputfile

This is the form for use case [1]. The options will be explained later, in section OPTIONS. lowkey just hold that thought 🫶

• path output (in) — this argument says where to write the generated document. It can be the path to a file or directory, or -. That last value makes the application write the generated documented to stdout. 💅 If the output does not exist then [file dirname $output] has to exist and must be a writable directory. The generated document will be written to a file in that directory, and the name of that file will be derived from the inputfile, the format, and the value given to option -ext (if present).
• (path|handle) format (in) — this argument says which formatting engine to use when processing the input, and thus the format of the generated document. See section FORMATS for the possibilities recognized by the application.
• path inputfile (in) — this argument is the path to the file to process. It has to exist, must be readable, and written in doctools format. no shortcuts here bestie 🙈

dtplite validate inputfile

This is a simpler form for use case [1]. The "validate" format generates no output at all, only syntax checks are performed. So specifying an output file or other options isn't necessary and gets left out entirely. it's giving minimalism ✨

dtplite -o output ?options? format inputdirectory

This is the form for use case [2]. It differs from the form for use case [1] by having the input documents specified through a directory instead of a file. The other arguments are identical, except for output, which now has to be the path to an existing and writable directory. 📁

The input documents are all files in inputdirectory or any of its subdirectories which were recognized by fileutil::fileType as containing text in doctools format.

dtplite -merge -o output ?options? format inputdirectory

This is the form for use case [3]. The only difference to the form for use case [2] is the additional option -merge. 🔥

Each such call will merge the generated documents coming from processing the input documents under inputdirectory or any of its subdirectories to the files under output. In this manner it is possible to incrementally build the unified documentation for any number of packages. Note that it is necessary to run through all the packages twice to get fully correct cross-references (for formats supporting them). yep, twice, don't skip it 🫠

---

💅 OPTIONS 💅

This section describes all the options available to the user of the application, with the exception of the options -o and -merge. Those two were described already, in section COMMAND LINE. iykyk 💜

• -exclude string — this option specifies an exclude (glob) pattern. Any files identified as manpages to process which match the exclude pattern are ignored. The option can be provided multiple times, each usage adding an additional pattern to the list of exclusions. bye bye unwanted files 👋
• -ext string — if the name of an output file has to be derived from the name of an input file it will use the name of the format as the extension by default. This option here will override this however, forcing it to use string as the file extension. This option is ignored if the name of the output file is fully specified through option -o. When used multiple times only the last definition is relevant. 👑
• -header file — this option can be used if and only if the selected format provides an engine parameter named "header". It takes the contents of the specified file and assign them to that parameter, for whatever use by the engine. The HTML engine will insert the text just after the tag <body>. If navigation buttons are present (see option -nav below), then the HTML generated for them is appended to the header data originating here before the final assignment to the parameter. When used multiple times only the last definition is relevant.
• -footer file — like -header, except that: any navigation buttons are ignored, the corresponding required engine parameter is named "footer", and the data is inserted just before the tag </body>. When used multiple times only the last definition is relevant.
• -style file — this option can be used if and only if the selected format provides an engine parameter named "meta". When specified it will generate a piece of HTML code declaring the file as the stylesheet for the generated document and assign that to the parameter. The HTML engine will insert this into the document, just after the tag <head>. 🎨 When processing an input directory the stylesheet file is copied into the output directory and the generated HTML will refer to the copy, to make the result more self-contained. When processing an input file we have no location to copy the stylesheet to and so just reference it as specified. When used multiple times only the last definition is relevant.
• -toc path — this option specifies a doctoc file to use for the table of contents instead of generating our own. 📖 When used multiple times only the last definition is relevant.
• -pre+toc label path|text — this option specifies additional doctoc files (or texts) to use in the navigation bar. Positioning and handling of multiple uses is like for options -prenav and -postnav, see below. ⬅️
• -post+toc label path|text — this option specifies additional doctoc files (or texts) to use in the navigation bar. Positioning and handling of multiple uses is like for options -prenav and -postnav, see below. ➡️
• -nav label url — use this option to specify a navigation button with label to display and the url to link to. This option can be used if and only if the selected format provides an engine parameter named "header". The HTML generated for this is appended to whatever data we got from option -header before it is inserted into the generated documents. 🧭 When used multiple times all definitions are collected and a navigation bar is created, with the first definition shown at the left edge and the last definition to the right. The url can be relative. In that case it is assumed to be relative to the main files (TOC and Keyword index), and will be transformed for all others to still link properly. slay 🔗
• -prenav label url — use this option to specify a navigation button with label to display and the url to link to. This option can be used if and only if the selected format provides an engine parameter named "header". The HTML generated for this is appended to whatever data we got from option -header before it is inserted into the generated documents. When used multiple times all definitions are collected and a navigation bar is created, with the first definition shown at the left edge and the last definition to the right. The url can be relative. In that case it is assumed to be relative to the main files (TOC and Keyword index), and will be transformed for all others to still link properly. 💫
• -postnav label url — use this option to specify a navigation button with label to display and the url to link to. This option can be used if and only if the selected format provides an engine parameter named "header". The HTML generated for this is appended to whatever data we got from option -header before it is inserted into the generated documents. When used multiple times all definitions are collected and a navigation bar is created, with the last definition shown at the right edge and the first definition to the left. The url can be relative. In that case it is assumed to be relative to the main files (TOC and Keyword index), and will be transformed for all others to still link properly. 🌈

---

🌟 FORMATS 🌟

At first the format argument will be treated as a path to a tcl file containing the code for the requested formatting engine. The argument will be treated as the name of one of the predefined formats listed below if and only if the path does not exist. fr fr 🔍

Note a limitation: If treating the format as path to the tcl script implementing the engine was sucessful, then this script has to implement not only the engine API for doctools, i.e. doctools_api, but for doctoc_api and docidx_api as well. Otherwise the generation of a table of contents and of a keyword index will fail. 😭

List of predefined formats, i.e. as provided by the package doctools:

• nroff — the processor generates *roff output, the standard format for unix manpages. 💀 iconic
• html — the processor generates HTML output, for usage in and display by web browsers. This engine is currently the only one providing the various engine parameters required for the additional customaization of the output. 👑
• tmml — out comes TMML, aka the Tcl Manpage Markup Language, which is basically XML's cooler cousin 🦋.
• latex — you get LaTeX output, slay for all the academic besties ✨.
• wiki — generates Wiki markup, the exact flavor that wikit understands. periodt 📝.
• list — this one just yoinks out the info that manpage_begin gave us. It's the internal format the tool uses to pull the meta data that both the table of contents and the keyword index are built from. iykyk 🔍.
• null — no output at all, bestie. Zero. Nothing. Which lowkey makes it exactly the same as validate 💀.

---

📁 DIRECTORY STRUCTURES 📁

okay so this section is all about the directory trees the app creates under output when you're processing every doc in an inputdirectory. In other words: this only matters for use cases [2] and [3], so don't stress if that's not you 💅.

[2] — here's the structure you get when you process a single set of input documents. The file extension in the example is for HTML output, but ngl that's not actually relevant to the structure — it was just used so the file names would look proper.

output/
    toc.html
    index.html
    files/
        path/to/FOO.html

That last line in the example is the document generated for a file FOO located at

inputdirectory/path/to/FOO

[3] — when you're merging a whole bunch of packages into one unified set of documents, the generated structure goes a lil deeper:

output
    .toc
    .idx
    .tocdoc
    .idxdoc
    .xrf
    toc.html
    index.html
    FOO1/
        ...
    FOO2/
        toc.html
        files/
            path/to/BAR.html

Each of those directories FOO1, ... holds the documents generated for the package FOO1, ... and follows the exact structure shown for use case [2]. The one and only exception? There's no per-package index. that's it, that's the tea ☕.

The files ".toc", ".idx", and ".xrf" are holding the internal status of the whole output, and they'll be read and updated by the next invocation. Their contents are not documented, so don't come for me asking what's inside 🙈. Remove these files once all the packages you wanted in the output have been processed — i.e. when the output is complete. that's your green flag to delete 🗑️.

The files ".tocdoc" and ".idxdoc" are intermediate files in doctoc and docidx markup respectively. They contain the main table of contents and the keyword index for the set of documents, before those get converted into whatever output format you picked. They're left in place — not deleted — so they can serve as demonstrations of doctoc and docidx markup. iconic behavior honestly 👑.

---

💀 BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. no cap, nothing is perfect 😭. Please report them in the category doctools of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. Also please report any ideas for enhancements you might have for either the package and/or the documentation. we want them fr fr 🫶.

When proposing code changes, please provide unified diffs, i.e. the output of diff -u. do it for the culture ✨.

Also note further that attachments are strongly preferred over inlined patches. You can make an attachment by going to the Edit form of the ticket right after creating it, and then using the left-most button in the secondary navigation bar. lowkey specific but okay bestie, we ball 🎀.

---

👀 SEE ALSO 👀

• docidx introduction
• doctoc introduction
• doctools introduction

---

🔑 KEYWORDS 🔑

HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff

---

🌸 CATEGORY 🌸

Documentation tools

---

💖 COPYRIGHT 💖

Copyright (c) 2004-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's the whole page, bestie, we ate and left no crumbs 🍓✨ this one came from the tcllib crew, version 1.0.5, and it's the dtplite(n) page. mwah, go read a manpage 💅🦋