tep...gen(3tcl)

📦

version 2.0 · 2 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.21 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 tep...gen(3tcl) — Tcl's Enhanced Procedure and Argument Manager 🌸

okay bestie, welcome to the manual page for tep...gen — aka Tcl's Enhanced Procedure and Argument Manager. this is the TEPAM Doc Gen reference manual, and it's giving documentation-generation main character energy. 💅

✨ NAME ✨

tepam::doc_gen — TEPAM DOC Generation, reference manual

🌈 SYNOPSIS 🌈

okay so first, the vibe check on requirements and signatures:

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?

periodt. those are the exact spells you cast. ✨

💖 DESCRIPTION 💖

okay so this package generates documentations of TEPAM procedures — and when we say TEPAM procedures, we mean procedures that have been declared with tepam::procedure. The documents are generated in the classic UNIX document style using the following document sections: Name, Synopsis, Description, Arguments and Example. TEPAM Doc Gen provides support for various document formats. Support for additional formats can be added if necessary. no cap. 🫶

The TEPAM Doc Gen package provides the following commands:

tepam::doc_gen::generate ?-format format? ?-style style? ?-header_footer? ?-dest_file dest_file? name — This command generates the documentation for a specified procedure (name) in one of the supported formats (TXT, HTML, POD (Perl Doc), DT (TclLib DocTool), or in a custom specific format). The format is specified via ?format?. The flag ?-header_footer? adds to the documentation file header and footer. If ?dest_file? is specified the documentation is stored in a file (the file header and footer are added automatically in this case) and the file name is returned. Otherwise the documentation string is returned by generate. 💅
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 command inserts procedure documentations into an existing master document at the locations indicated by insertion placeholders which are matching the pattern of ?search_pattern?. The existing master document is either provided as data to the argument (?src_string?) or via a file (?src_file?). The final document is returned by patch if no destination file is defined (?dest_file?). Otherwise, the document is stored in the specified file, and the number of insertion placeholders that could be handled successfully is returned.

Any insertion placeholders of the master document are handled by default. By defining the argument ?name? the documentation insertion will be restricted to a particular procedure. 🦋

🎀 ARGUMENTS 🎀

here's the tea on every argument, bestie. don't skip a single one, fr fr:

?-format format? — Specifies the documentation format. TEPAM Doc Gen provides support for the following formats:
- TXT - Text format (default)
- HTML
- POD - Perl Plain Old Documentation format (PerlPOD)
- DT - TclLib DocTool format

Section ADDING SUPPORT FOR NEW DOCUMENT FORMATS shows how support for additional formats can be added.

?-style style? — The documentation is by default generated in Tcl style (e.g. command arg1 arg2 ...). C-style documentation can be generated by setting this argument to 'C' (e.g. command(arg1,arg2,...)).
?-dest_file dest_file? — If ?dest_file? is defined the documentation is 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. This is a mandatory argument for generate, but an optional argument for patch.
?-header_footer? — generate adds to the generated procedure documentation the file header and footer 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 string by generate.
?-src_string src_string | -src_file src_file? — patch inserts procedure documentations into an existing document that is either provided as string to the argument (?src_string?) or as a file (?src_file?). One of these two arguments need to be specified.
?-search_pattern search_pattern? — The argument ?search_pattern? defines the documentation insertion placeholder used in a document. It is a regular expression accepted by regexp and 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 that 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.

🦋 ADDING SUPPORT FOR NEW DOCUMENT FORMATS 🦋

okay bestie, so you wanna teach tepam a brand new document format? iconic. all you gotta do is define a lil family of procedures inside the tepam::doc_gen namespace, and those procedures will generate the different document components. that's it, that's the whole vibe 💅

this next listing is like the master map — every token in here points at one of the 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>

so there's 2 types of document generation procedures, and you gotta know the difference, fr fr:

Content generation procedures (like <40s>...<40e>) — these ones spit out actual document content based on the text you hand them as an argument. and see how the listing above shows two tokens for them? that's to mark the beginning and the end of the generated content. cute, right? 🎀
Control generation procedures (like <03>) — these generate control constructs, like the prolog code and epilog code for lists, sections, whatever. and guess what, they take no argument at all. low maintenance queens 👑

🌸 the procedure set you gotta define 🌸

here's the full roster that needs to exist to support a new document format. no skipping, bestie, all of them:

01 — gen($Format,Header) {Text} — only gets called if doc_gen generates 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 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 (a.k.a. the preamble).
04 — gen($Format,End) {} — generates the documentation epilog.
20 — gen($Format,SectionTitle) {Text} — generates a section title (like 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 there's a separation between them. the raw title text comes in as the parameter.
30 — gen($Format,Name) {Text} — generates the name section (no title). the raw section text comes in as the parameter.
40 — gen($Format,Synopsis) {Text} — generates the synopsis section (no title). the section text you get as parameter is pre-formatted (the argument strings are generated by gen($Format,ArgumentString)).
50 — gen($Format,Description) {Text} — generates a description paragraph. the raw paragraph text comes in as the parameter.
51 — gen($Format,DescriptionListBegin) {} — generates the prolog of a bulleted/unordered list inside the description section. this prolog is usually the start code of a list structure.
52 — gen($Format,DescriptionListEnd) {} — generates the epilog of a bulleted/unordered list inside the description section. this epilog is usually the end code of a list structure.
53 — gen($Format,DescriptionListItem) {Text} — generates a text item in a bulleted/unordered description list. the raw item text comes in as the parameter.
54 — gen($Format,DescriptionSynopsis) {Text} — generates the synopsis line at the beginning of the description section. the command can totally return an empty string if no synopsys line is needed in that spot.

some formats (hi Tcl DocTools 👋) require that the synopsis line is defined in the description section, so they can then automatically build the synopsis section. the section text you get as parameter is pre-formatted (the argument strings are generated by gen($Format,ArgumentString)).

60 — gen($Format,ArgumentListBegin) {} — generates the prolog of an argument list (definition/non-bulleted list). this prolog is usually the start code of a definition list.
61 — gen($Format,ArgumentListEnd) {} — generates the epilog of the argument list. this epilog is 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. this command can lean on gen($Format,ArgumentDetailBegin) because the parameters are identical. twin behavior, slay 💅
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 (single paragraph).
66 — gen($Format,ArgumentAttribute) {Text} — generates a single argument attribute string. this command gets called individually for each attribute.
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 in the example section. this command is 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. the generated string has to show whether an argument is optional, named, and whether it's a flag.

🧚 the `gen($Format,ArgumentString)` parameters 🧚

here's what gets handed to that procedure, one by one:

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

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

IsNamed — if it's 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 named arguments can also be optional, bestie:

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

Type — tells you the type of the argument. if the type is set to none, the argument is a flag, and the generated string needs to show that. example:

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

✨ EXAMPLES ✨

Okay bestie, this is the part where it gets fun — actual working examples, we love to see it 💖

🌸 TEPAM::DOC_GEN::GENERATE 🌸

The cutest way to explore the TEPAM Doc Gen package is literally just to generate the documentation of tepam::doc_gen::generate itself. Meta, right? Iconic behaviour honestly.

This first one spits out the doc in text format (which is the default format, no cap):

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

And this one goes full glow-up and gives you HTML instead:

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

The flag ?header_footer? also throws in the file header and the footer, like accessories for your doc:

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

Now — the documentation can be stored directly 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 refers to a CSS stylesheet file (default: tepam_doc_stylesheet.css). If you want that HTML to actually display correctly, you need to copy the CSS stylesheet into the directory of the generated HTML file. Otherwise it's giving unstyled chaos 💀

The Tcl DOC Tools format can be used as an intermediate format to generate other formats — HTML, for example. It's a whole pipeline, and it's lowkey genius:

# 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, right? But patch? patch is the flexible one 💅. Multiple documentations for different procedures plus meta information can be added, for example.

Here's how the patch command does its thing. It first defines a HTML master document string that contains 2 procedure documentation placeholders — those are {*<ProcedureName>*}. Then patch swaps those placeholders out with the generated documentation of the referred procedures. And since these are nonstandard placeholders, patch gets called with an explicit placeholder pattern definition (that's the argument search_pattern):

# 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(3tcl)
tepam::procedure(3tcl)

🔑 KEYWORDS 🔑

automatic documentation
documentation
procedure documentation

🏷️ CATEGORY 🏷️

Documentation tools — yes, that's the whole category, and it ate ✨

And that's a wrap on tep...gen(3tcl), bestie 🫶💖 Go forth and document everything, you've got this. This page is from tcllib, version 0.1.3 — periodt 💅✨

📦 where this page comes from

debian trixie: tcllib 2.0+dfsg-4 · Tcl
ubuntu questing: tcllib 2.0+dfsg-4
ubuntu resolute: tcllib 2.0+dfsg-5 · Tcl
ubuntu stonking: tcllib 2.0+dfsg-6 · Tcl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms