dtplite(1)

💖 NAME 💖

dtplite — 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 🦋

okay so, the app this whole page is about is dtplite, and she's the successor to the extremely simple mpexpand. She got influenced in her functionality by the dtp doctools processor, and the result is she's way more powerful than mpexpand but honestly just as easy to use. And definitely easier than dtp with its whole myriad of subcommands and options — like, dtp is giving "30 tabs open and none of them are the right one", no offense. 😭

And just so we're clear — dtplite is built on the package doctools, same as those other two processors. Bestie family reunion. 🫶

🌸 USE CASES 🌸

dtplite was written with these three use cases in mind, and she ate every single one:

1. Validation of a single document — like, 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., so you can proofread the formatting before committing to the whole thing. iykyk.
2. Generation of the formatted documentation for a single package — that's all the manpages, plus a table of contents and an index of keywords. the whole package. she does it. 💅
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. queen behavior, honestly. 👑

Beyond all of that, we also want to make use of the customization features provided by the HTML formatter. It's not the only format the application should be able to generate, but we anticipate it to be the most commonly used one, and it's one of the few that actually provides customization hooks. not everyone has them, and that's fine, we're not judging. 🎀

We allow the caller to specify a header string, a footer string, a stylesheet, and data for a bar of navigation links at the top of the generated document. All of these can be set as long as the formatting engine provides an appropriate engine parameter (see the OPTIONS section, bestie). But the last two? They have internal processing that makes them specific to HTML. so, heads up. 🙈

💅 COMMAND LINE 💅

dtplite -o output ?options? format inputfile

This is the form for use case [1]. The options get explained later, down in the OPTIONS section, don't worry.

• path output (in) — this argument says where to write the generated document. It can be the path to a file, a path to a directory, or just -. And that last value? It makes the application write the generated document straight to stdout. ✨
  • If the output does not exist, then [file dirname $output] has to exist and must be a writable directory. The generated document gets written to a file in that directory, and the name of that file is derived from the inputfile, the format, and the value given to the -ext option (if it's present). got it? got it. 🫶
• path|handle format (in) — this one says which formatting engine to use when processing the input, and therefore what the format of the generated document is gonna be. See the FORMATS section for the possibilities the application recognizes.
• path inputfile (in) — the path to the file to process. It has to exist, must be readable, and must be written in doctools format. no exceptions, bestie.

dtplite validate inputfile

This is the 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 any other options is just not necessary, and we leave it out. it's giving minimalist. 🎀

dtplite -o output ?options? format inputdirectory

This is the form for use case [2]. It differs from the use case [1] form because the input documents get specified through a directory instead of a file. All the other arguments are identical — except 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. she goes digging. 🔍

dtplite -merge -o output ?options? format inputdirectory

This is the form for use case [3]. The only difference from the use case [2] form is the extra option -merge. that's it. one little flag. 💅

Each such call will merge the generated documents coming from processing the input documents under inputdirectory or any of its subdirectories into the files under output. This way it's possible to incrementally build the unified documentation for any number of packages. And ngl, note that it's necessary to run through all the packages twice to get fully correct cross-references (for formats that support them). twice. I said what I said. 😭

👑 OPTIONS 👑

This section describes all the options available to the user of the application — with the exception of -o and -merge, because those two already got described up in the COMMAND LINE section. no repeats, we're efficient here. ✨

• -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, and each usage adds an additional pattern to the list of exclusions. stack 'em up. 🎀
• -ext string — if the name of an output file has to be derived from the name of an input file, it uses the name of the format as the extension by default. This option here overrides that, forcing it to use string as the file extension. It is ignored if the name of the output file is fully specified through the -o option. When used multiple times, only the last definition is relevant. one at a time, bestie.
• -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 assigns 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 the -nav option below), then the HTML generated for them gets 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 generates a piece of HTML code declaring the file as the stylesheet for the generated document, and assigns 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 gets copied into the output directory, and the generated HTML refers to the copy — to make the result more self-contained. When processing an input file, we have no location to copy the stylesheet to, so it just references it as specified. different vibes, different handling. 🦋
  • 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
• -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 just like for the -prenav and -postnav options — see below. 👇
• -nav label url
• -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 gets appended to whatever data we got from the -header option, before it's 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's assumed to be relative to the main files (TOC and Keyword index), and will be transformed for all the others so they still link properly. she adjusts. she's thoughtful like that. 🫶
• -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 gets appended to whatever data we got from the -header option, before it's 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. (yes, it's the mirror of -prenav. iconic.) 👑
  • The url can be relative. In that case it's assumed to be relative to the main files (TOC and Keyword index), and will be transformed for all the others so they still link properly.

🌈 FORMATS 🌈

At first, the format argument gets 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 that path does not exist. so it checks the filesystem first. she's thorough. 🔍

⚠️ Note a limitation: if treating the format as a path to the tcl script implementing the engine was successful, 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. so like, implement all three, bestie, or it's over. 😭

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

• nroff — the processor generates *roff output, the standard format for unix manpages. old school, still slaying. 💅
• 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 customization of the output. she's the special one. ✨
• tmml — the processor spits out TMML, aka the Tcl Manpage Markup Language, which is a whole derivative of XML. yes bestie, XML's cousin 💅
• latex — the processor gives you LaTeX output. science-y queen ✨
• wiki — the processor gives you Wiki markup, exactly the kind that wikit understands. iykyk 📝
• list — the processor just pulls out the info that manpage_begin provides. this one is internal, lowkey the backbone 🦋 it extracts the meta data that both the table of contents and the keyword index get derived from.
• null — the processor generates literally nothing. this is equivalent to validate. iconic minimalism, no cap 💀

---

📁 DIRECTORY STRUCTURES 📁

okay so in this section we're describing the directory structures the application makes under output when it processes all the documents in an inputdirectory. in other words? this is only relevant to use cases [2] and [3]. periodt.

🎀 [2] — one set of input docs

here's the directory structure you get when processing a single set of input documents. the file extension used is for output in HTML, but that's not actually relevant to the structure — it was just used so the file names would be proper. cute, right? 🌸

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

and the last line in that example? that's the document generated for a file FOO located at:

inputdirectory/path/to/FOO

🧚 [3] — merging many packages

now when you're merging many packages into one unified set of documents, the generated directory structure gets a bit deeper, bestie:

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

each of the directories FOO1, ... holds the documents generated for the package FOO1, ... and follows the structure shown for use case [2]. the only exception? there's no per-package index. noted. 👑

the files .toc, .idx, and .xrf contain the internal status of the whole output, and they'll be read and updated by the next invokation. their contents will not be documented. > remove these files when all packages wanted for the output have been processed, i.e. when the output is complete. don't leave them lying around like old receipts 💀

the files .tocdoc and .idxdoc are intermediate files in doctoc and docidx markup, respectively, containing the main table of contents and keyword index for the set of documents before their conversion to the chosen output format. they're left in place — i.e. not deleted — to serve as demonstrations of doctoc and docidx markup. little show-and-tell moment, we love that 🌈

---

😭 BUGS, IDEAS, FEEDBACK 😭

this document, and the package it describes, will undoubtedly contain bugs and other problems. no cap, that's just how it is. please report such in the category doctools of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. and please also report any ideas for enhancements you may 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. this is not optional, bestie, it's the vibe check.

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. left-most button, remember it 💅

---

👀 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! 🫶 this one came to you from tcllib, version 1.0.5, and it's the dtplite(1) manual — go forth and process those docs, you absolute main character 👑✨