tepam...c_gen(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

okay bestie, gather round, this is tepam::doc_gen — the TEPAM DOC Generation reference manual 💅✨ and fr fr it's the whole thing, no skips, no cuts.

💖 SYNOPSIS 💖

package require Tcl 8.5 9

package require tepam 0.5

package require tepam::doc_gen ?0.1.3?

tepam::doc_gen::generate     ?-format     format?     ?-style     style?
?-header_footer? ?-dest_file dest_file? name

tepam::doc_gen::patch ?-format format? ?-style  style?  ?-search_pattern
search_pattern?    ?-src_string   src_string   |   -src_file   src_file?
?-dest_file dest_file? ?name?

🦋 DESCRIPTION 🦋

so this package generates documentation for TEPAM procedures — and by "TEPAM procedures" we mean the ones you declared with tepam::procedure, iykyk 🫶. The docs come out in that classic UNIX document style, using these sections: Name, Synopsis, Description, Arguments and Example. TEPAM Doc Gen supports a bunch of document formats, and lowkey if you need more, extra formats can be added when necessary 💁♀️.

The TEPAM Doc Gen package gives you these commands:

tepam::doc_gen::generate ?-format format? ?-style style? ?-header_footer? ?-dest_file dest_file? name — this one generates the documentation for a specified procedure (name) in one of the supported formats (TXT, HTML, POD (Perl Doc), DT (TclLib DocTool), or a custom specific format of your own). The format goes in format. The flag -header_footer adds header and footer to the documentation file. If dest_file is specified, the documentation is stored in a file — and yes, the file header and footer get added automatically in that case — and the file name is returned. Otherwise, generate returns the documentation string instead. bestie, one of these two, not both 💫
tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern search_pattern? ?-src_string src_string | -src_file src_file? ?-dest_file dest_file? ?name? — this one inserts procedure documentations into an existing master document, at the locations indicated by insertion placeholders that match the pattern of search_pattern. The existing master document comes either as data via the argument src_string, or via a file src_file. If no destination file is defined (dest_file), patch returns the final document. Otherwise the document is stored in the specified file, and it returns the number of insertion placeholders that could be handled successfully 🔥.

By default, any insertion placeholders of the master document get handled. But if you define the argument name, the documentation insertion gets restricted to a particular procedure. cute right?

🎀 ARGUMENTS 🎀

-format format — specifies the documentation format. TEPAM Doc Gen supports these formats:
- TXT — Text format (default)
- HTML
- POD — Perl Plain Old Documentation format (PerlPOD)
- DT — TclLib DocTool format

The section ADDING SUPPORT FOR NEW DOCUMENT FORMATS shows how support for additional formats can be added 👑

-style style — documentation is by default generated in Tcl style (like command arg1 arg2 ...). You can get C-style documentation by setting this argument to 'C' (like command(arg1,arg2,...)). pick your fighter 💅
-dest_file dest_file — if dest_file is defined, the documentation gets written into the specified destination file. Otherwise the documentation string is returned by the commands generate and patch 🫶
name / name — this is the name of the procedure for which the documentation has to be generated. It's a mandatory argument for generate, but an optional argument for patch. noted bestie 📝
-header_footer — generate adds the file header and footer to the generated procedure documentation only if a file is generated. By selecting the flag -header_footer, the header and footer are also generated if the documentation is returned as a string by generate ✨
-src_string src_string | -src_file src_file — patch inserts procedure documentations into an existing document that is either provided as a string to the argument src_string or as a file src_file. One of these two arguments needs to be specified. no skipping, fr fr
-search_pattern search_pattern — the argument search_pattern defines the documentation insertion placeholder used in a document. It's a regular expression accepted by regexp and it needs to contain a parenthesized sub-expression that contains the procedure name for which the documentation needs to be inserted 👀

The default insertion placeholder pattern is \{!(.*?)!\}, which means the procedure name will be embedded between {! and !}. The section EXAMPLES contains a custom insertion placeholder pattern example 🌈

👑 PREDEFINED DOCUMENT FORMATS 👑

TEPAM Doc Gen pre-defines the following document formats:

🌸 TXT - TEXT FORMAT 🌸

The documentation will be generated in a simple text format if this format is selected. The format can be customized via the following variable:

tepam::doc_gen::Option(TXT,MaxLineLength)
- Default: 80
- This variable defines the line wrapping limit (character position) 📏

💜 HTML - HTML FORMAT 💜

TEPAM Doc Gen generates CSS styled HTML files. The HTML documentation can be customized via the following variable:

tepam::doc_gen::Option(HTML,CssFile)
- Default: "tepam_doc_stylesheet.css"
- This variable specifies the CSS stylesheet file that is referred by the generated HTML files 🎨

The CSS stylesheet can be customized to change the documentation formatting. A good starting point to create a customized CSS stylesheet is to use the CSS file provided by the TEPAM Doc Gen example/demo. The HTML documentation uses the following CSS class styles:

h1.tepam_page_title — Document page title. Only used by generate if a file is created or if the header and footer are built (flag -header_footer selected).
div.tepam_command_help — Documentation container. The entire procedure documentation is placed inside this container.
p.tepam_section_title — Section title (e.g. Name, Synopsis, Description, ...)
p.tepam_sub_section_title — Sub-section title (used to separate the documentation of multiple sub-procedures)
p.tepam_name — Name section
p.tepam_synopsis — Synopsis section
p.tepam_description — Single description paragraph
ul.tepam_description_list — Item of a HTML bulleted/unordered list inside the description section
dt.tepam_argument — Item of a HTML description list used to list the procedure arguments
p.tepam_argument_description — Argument description paragraph
p.tepam_argument_attribute — Argument attribute line
pre.tepam_example — Example section

🧚 POD - PERL DOCUMENT FORMAT 🧚

The documentation is generated in the Perl Plain Old Documentation format (PerlPOD) if this format is selected.

⭐ DT - TCLLIB DOCTOOLS FORMAT ⭐

The documentation is generated in the Tcllib DocTools format if this format is selected.

more coming bestie, don't go anywhere 💖

✨ ADDING SUPPORT FOR NEW DOCUMENT FORMATS ✨

okay so bestie, you wanna teach doc_gen a whole new language? 💅 You totally can — you just define a little squad of procedures inside the tepam::doc_gen namespace, and each one of them is responsible for spitting out one specific piece of the document. That's it. That's the whole vibe. 🫶

The listing down here is your map, fr fr — all those tokens point at the different document generation procedures:

                    <01>
               <03> <20s>   NAME<20e>
                    <30s>       message_box - Displays text in a message box<30e>
                    <20s>   SYNOPSYS<20e>
                    <40s>       message_box [-mtype <mtype>] <text><40e>
                    <20s>   DESCRIPTION<20e>
                    <21s>     message_box<21e>
                    <54s>       message_box [-mtype <mtype>] <text><54e>
                    <50s>       This procedure allows displaying a text in an message box. The following
                                message types are supported:<50e>
               <51> <53s>       * Info<53e>
                    <53s>       * Warning<53e>
                    <53s>       * Error<53e>                                           <52>
                    <50s>       If the text parameter is use multiple times the different texts are
                                concatenated to create the message text.<50e>
                    <20s>   ARGUMENTS<20e>
               <60> <62s>       [-mtype <mtype>]<62e>
               <63> <65s>          Message type<65e>
                    <66s>          Default: "Warning"<66e>
                    <66s>          Multiple: yes<66e>
                    <66s>          Choices: Info, Warning, Error<66e>                  <64>
                    <62s>       <text><62e>
               <63> <65s>          One or multiple text lines to display<65e>
                    <66s>          Type: string<66e>
                    <66s>          Multiple: yes<66e>                                  <64><61>
                    <20s>   EXAMPLE<20e>
               <70> <72s>       message_box "Please save first the document"<72e>
                    <73s>       -> 1<73e>                                              <71><04>
                    <02>

🌸 The two flavors of doc generation procedures

There are 2 types, and honestly they're giving very different energies:

Content generation procedures (like <40s>...<40e>) — these ones build actual document content out of the text you hand them as an argument. See in the listing how each of these has two tokens? Yeah, that's the glow-up: one token marks where the generated content starts, the other marks where it ends. 💖
Control generation procedures (like <03>) — these ones generate control constructs, like the prolog code and epilog code for lists, sections, whatever. And the iconic part? they take no argument at all. Zero. Nada. Main character behavior. 👑

🎀 The procedure set you gotta define

To support a shiny new document format, you need this whole lineup. No skipping, bestie, they all matter:

01 - gen($Format,Header) {Text} — only gets called if doc_gen is generating a file, or if it's called with the flag ?-header_footer?. It creates the file header. The parameter it gets is the procedure name that the documentation is being generated for. ✨
02 - gen($Format,Footer) {Text} — same deal, only called if doc_gen generates a file or if it's called with the flag ?-header_footer?. It creates the file footer.
03 - gen($Format,Begin) {} — generates the documentation prolog (the preamble). 🦋
04 - gen($Format,End) {} — generates the documentation epilog.
20 - gen($Format,SectionTitle) {Text} — generates a section title (think Name, Synopsis, Description, ...). The raw title text comes in as the parameter.
21 - gen($Format,SubSectionTitle) {Text} — generates a sub-section title. Sub-sections come into play when a single documentation is generated for multiple sub-commands, so you need something separating them. The raw title text is the parameter.
30 - gen($Format,Name) {Text} — generates the name section, without the title. The raw section text is the parameter.
40 - gen($Format,Synopsis) {Text} — generates the synopsis section, without the title. The section text you get as parameter is already pre-formatted (the argument strings get generated by gen($Format,ArgumentString)).
50 - gen($Format,Description) {Text} — generates a description paragraph. Raw paragraph text in, parameter style.
51 - gen($Format,DescriptionListBegin) {} — generates the prolog of a bulleted/unordered list inside the description section. Usually this prolog is the start code of a list structure.
52 - gen($Format,DescriptionListEnd) {} — generates the epilog of a bulleted/unordered list inside the description section. Usually the end code of a list structure.
53 - gen($Format,DescriptionListItem) {Text} — generates a text item inside a bulleted/unordered description list. The raw item text is the parameter.
54 - gen($Format,DescriptionSynopsis) {Text} — generates the synopsis line at the beginning of the description section. It's totally allowed to return an empty string if no synopsis line is wanted at that spot. 🫶

Some formats (hi, Tcl DocTools 👋) require the synopsis line to live inside the description section, so they can then automatically build the synopsis section from it. The section text you get as parameter is pre-formatted (the argument strings come from gen($Format,ArgumentString)).

60 - gen($Format,ArgumentListBegin) {} — generates the prolog of the argument list (that's the definition/non-bulleted kind of list). Usually the start code of a definition list.
61 - gen($Format,ArgumentListEnd) {} — generates the epilog of the argument list. Usually the end string of a list structure.
62 - gen($Format,ArgumentListItem) {Name IsOptional IsNamed Type} — generates an argument item line inside the argument list. It's allowed to lean on gen($Format,ArgumentDetailBegin), since the parameters are literally identical. 😌
63 - gen($Format,ArgumentDetailBegin) {} — generates the argument details prolog (preamble).
64 - gen($Format,ArgumentDetailEnd) {} — generates the argument details epilog.
65 - gen($Format,ArgumentDescription) {Text} — generates the argument description (a single paragraph).
66 - gen($Format,ArgumentAttribute) {Text} — generates a single argument attribute string. This one gets called individually for each attribute, so it's doing the most, one at a time. 💅
70 - gen($Format,ExampleBegin) {} — generates the example section prolog (preamble).
71 - gen($Format,ExampleEnd) {} — generates the example section epilog.
72 - gen($Format,ExampleCommandLine) {Text} — generates a single command line inside the example section. Gets called for each individual command line. 🍓
73 - gen($Format,ExampleResultLine) {Text} — generates a command result line.
80 - gen($Format,ArgumentString) {Name IsOptional IsNamed Type} — generates the part of the command line or the synopsis that's specific to one argument. Whatever string it generates has to show whether an argument is optional, named, and whether it's a flag. 🧚

These are the parameters it gets:

Name — name of the argument.
IsOptional — if true (=1) the argument is optional, and the generated string should say so (for example by putting the argument into brackets {[]} or into question marks '?'):

gen(TXT,ArgumentString) mtype 1 0 string -> "[mtype]"

IsNamed — if true (=1) the argument is a named argument (an option). In that case the generated string should contain the argument/option name, followed by the argument itself:

gen(TXT,ArgumentString) mtype 0 1 string -> "-mtype <mtype>"

And yep, named arguments can be optional too:

gen(TXT,ArgumentString) mtype 1 1 string -> "[-mtype <mtype>]"

Type — tells you what type the argument is. If the type is set to none, the argument is a flag, and the generated string has to indicate that. Example:

gen(TXT,ArgumentString) close 1 1 none -> "[-close]"

💖 TEPAM::DOC_GEN::GENERATE 💖

okay bestie, the cutest way to explore this whole package is literally to just... generate the docs for the command that generates docs. meta much? iconic. So:

This example spits out the documentation for tepam::doc_gen::generate in text format — which is the default format, no cap:

tepam::doc_gen::generate tepam::doc_gen::generate

And this one? HTML, because we're fancy now:

tepam::doc_gen::generate -format HTML tepam::doc_gen::generate

The flag ?header_footer? also adds the file header and footer, so the whole thing is wrapped up nice:

tepam::doc_gen::generate -format HTML -header_footer tepam::doc_gen::generate

You can send the documentation straight into a file too — and when you do that, the file header and footer get generated automatically, no extra work from you:

tepam::doc_gen::generate -format HTML -dest_file doc_gen.html tepam::doc_gen::generate

🫶 heads up bestie: the generated HTML file points at a CSS stylesheet file (default: tepam_doc_stylesheet.css). For the HTML to actually look right, that stylesheet file has to be copied into the directory where your generated HTML file lives. Don't forget it or it's giving naked HTML energy. 💀

The Tcl DOC Tools format can also be used as an intermediate format to generate other formats — HTML, for example:

# Generate the documentation in Tcl Doc Tool format
set dt [tepam::doc_gen::generate -format DT -header_footer tepam::doc_gen::generate]
# Create a new doc tools object (HTML format)
package require doctools
::doctools::new myDoc -format html
# Open the HTML file, and write the HTML formatted documentation
set fHtml [open doc_gen.dt.html w]
puts $fHtml [myDoc format $dt]
close $fHtml

🌈 TEPAM::DOC_GEN::PATCH 🌈

So generate gives you a limited number of ways to vary the document structure. patch? way more flexibility, periodt. You can add multiple documentations for different procedures, plus meta information, all in one go. Obsessed.

The listing below shows how the patch command works. First it defines an HTML master document string that contains 2 procedure documentation placeholders ({*<ProcedureName>*}). Those placeholders get replaced by patch with the generated documentation of the procedures they refer to. And because these are nonstandard placeholders, patch is called with an explicit placeholder pattern definition — that's the search_pattern argument:

# Define the HTML master document
set HtmlMasterDoc {\
<html>
  <head>
    <title>tepam::doc_gen</title>
    <link rel="stylesheet" href="tepam_doc_stylesheet.css">
    <meta content="documentation" name="keywords"></meta>
  </head>
  <body>
    <h1>tepam::doc_gen</h1>
      <h2>Generate</h2>
{*tepam::doc_gen::generate*}
      <h2>Patch</h2>
{*tepam::doc_gen::patch*}
  </body>
<html>\
}
# Patch the master document: This will replace the placeholders by the
# procedure documentation divisions:
tepam::doc_gen::patch -format HTML -search_pattern {\{\*(.*?)\*\}} \
                      -src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html

👀 SEE ALSO 👀

tepam(n)
tepam::procedure(n)

🔑 KEYWORDS 🔑

automatic documentation, documentation, procedure documentation

🎀 CATEGORY 🎀

Documentation tools

💜 COPYRIGHT 💜

and that's the whole page bestie, you ate it. 💅 This lil legend came out of tcllib, version 0.1.3, and it's filed under the very glamorous name tepam...c_gen(n). Go generate something gorgeous. 🦋✨

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms