Tcl Library Source Code

Check-in [f6eb7e4e99]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Added info about branches and version number incrementing. Tweaked install tooling notes.
Timelines: family | ancestors | descendants | both | doc-overhaul
Files: files | file ages | folders
SHA3-256: f6eb7e4e99c69b238bba149df7193af4d0da76269c5ebdf4eb5b3d9317919cc2
User & Date: aku 2019-03-12 05:49:48
Context
2019-03-17
19:59
Squash and replace unwanted smart quotes. check-in: 590e67f11c user: aku tags: doc-overhaul
2019-03-12
05:49
Added info about branches and version number incrementing. Tweaked install tooling notes. check-in: f6eb7e4e99 user: aku tags: doc-overhaul
04:59
Filled in test writing and install support sections of the devguide. check-in: 9e39cdbfe8 user: aku tags: doc-overhaul
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to devdoc/parts/d_branchflow.inc.

            1  +[subsection Branches]
            2  +
            3  +An important part of working with a
            4  +[term {Distributed Version Control System}] ([term DVCS]) like
            5  +[uri https://www.fossil-scm.org/ fossil]
            6  +is the management and use of branches.
            7  +
            8  +[para] For Tcllib the main branch of the collection is
            9  +[term trunk]. In [term git] this branch would be called [term master],
           10  +and this exactly the case in the
           11  +[uri https://github.com/tcltk/tcllib/ {github mirror}] of Tcllib.
           12  +
           13  +[para] In support of debugging, like searching for when an issue
           14  +appeared via bisection, each commit on this branch must pass the
           15  +entire testsuite of the collection.
           16  +
           17  +[para] As fossil has no mechanism to enfore this this is handled on
           18  +the honor system for developers and maintainers.
           19  +
           20  +[para] To make the task easier Tcllib comes with a tool
           21  +([file sak.tcl]) providing a number of commands in support. These
           22  +commands are explained in the following sections of this guide.
           23  +
           24  +[para] While it is possible and allowed to commit directly to trunk
           25  +remember the above regarding the testsuite, and the coming notes about
           26  +other possible issues with a commit.
           27  +
           28  +[para] Because of this it is (strongly) recommended to perform any
           29  +development on a nicely named (nick of dev, ticket reference if any,
           30  +keywords applicable to the work, ...) non-trunk branch. Outside of the
           31  +trunk developers are allowed to commit intermediate broken states of
           32  +their work. Only at the end, when the branch is considered ready for
           33  +merging will it be necessary to perform full validation.
           34  +
           35  +[subsection {Version numbers}]
           36  +
           37  +In Tcllib all changes to a package have to come with an increment of
           38  +its version number. With what part is incremented (patchlevel, minor,
           39  +major version) dependent on the kind of change made. With multiple
           40  +changes in a commit the highest "wins".
           41  +
           42  +[para] When working in a development branch the version change can be
           43  +defered until it is time to merge, and then has to cover all the
           44  +changes in the branch.
           45  +
           46  +[para] Below a list of the kinds of changes and their association
           47  +version increments:
           48  +
           49  +[list_begin definitions]
           50  +[def [term {D - documentation}]] No increment
           51  +[def [term {T - testsuite}]] No increment
           52  +[def [term {B - bugfix}]] Patchlevel
           53  +[def [term {I - implementation tweak}]] Patchlevel
           54  +[def [term {P - performance tweak}]] Patchlevel
           55  +[def [term {E - backward-compatible extension}]] Minor
           56  +[def [term {API - incompatible change}]] Major
           57  +[list_end]
           58  +
           59  +[para] Note, a commit containing a version increment has to mention
           60  +the kind of change which caused it in the commit message, as well as
           61  +the new version number.
           62  +
           63  +[para] Note further that the version number of a package currently
           64  +exists in 3 places. An increment has to update all of them:
           65  +
           66  +[list_begin enumerated]
           67  +[enum] The package implementation.
           68  +[enum] The package index ([file pkgIndex.tcl])
           69  +[enum] The package documentation.
           70  +[list_end]
           71  +
           72  +[para] The [file sak.tcl] command [cmd {validate version}] helps
           73  +finding discrepancies between the first two.
           74  +
           75  +All the other [cmd validate] methods are also of interest to any
           76  +developer. Invoke it with
           77  +
           78  +[example {
           79  +    sak.tcl help validate
           80  +}]
           81  +
           82  +to see their documentation.

Changes to devdoc/parts/d_installation.inc.

     1      1   A last thing to consider when adding a new package to the collection
     2      2   is installation.
     3      3   
     4         -[para] How to [emph use] the tool, the [file installer.tcl] script is
     5         -doumented in
     6         -[term {Tcllib - The Installer's Guide}].
            4  +[para] How to [emph use] the [file installer.tcl] script is documented
            5  +in [term {Tcllib - The Installer's Guide}].
     7      6   
     8         -[para] Here we document how to extend the installer so that it may
     9         -install the new package(s).
            7  +[para] Here we document how to extend said installer so that it may
            8  +install new package(s) and/or application(s).
    10      9   
    11         -[para] In most cases only a single file has to be modified,
           10  +[para] In most cases only a single file has to be modified, the
    12     11   [file support/installation/modules.tcl] holding one command per module
    13     12   and application to install.
    14     13   
    15         -[para] The commands are:
           14  +[para] The relevant commands are:
    16     15   
    17     16   [list_begin definitions]
    18     17   
    19     18   [call [cmd Module] [arg name] \
    20     19         	   [arg code-action] \
    21     20         	   [arg doc-action] \
    22     21   	   [arg example-action]]

Changes to devdoc/tcllib_devguide.man.

    31     31   [comment {===================================================================}]
    32     32   [section Commitments]
    33     33   [subsection Contributor][include parts/d_contrib.inc]
    34     34   [subsection Maintainer][include parts/d_maintain.inc]
    35     35   
    36     36   [comment {===================================================================}]
    37     37   [section {Branching and Workflow}]
    38         -[include parts/d_branchflow.inc]x
           38  +[include parts/d_branchflow.inc]
    39     39   
    40     40   [comment {===================================================================}]
    41     41   [section {Structural Overview}]
    42     42   [include parts/d_dirlayout.inc]
    43     43   
    44     44   [comment {===================================================================}]
    45     45   [section {Testsuite Tooling}]

Changes to embedded/www/tcllib/files/devdoc/tcllib_devguide.html.

   110    110   <li class="doctools_section"><a href="#section1">Description</a></li>
   111    111   <li class="doctools_section"><a href="#section2">Commitments</a>
   112    112   <ul>
   113    113   <li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
   114    114   <li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
   115    115   </ul>
   116    116   </li>
   117         -<li class="doctools_section"><a href="#section3">Branching and Workflow</a></li>
          117  +<li class="doctools_section"><a href="#section3">Branching and Workflow</a>
          118  +<ul>
          119  +<li class="doctools_subsection"><a href="#subsection3">Branches</a></li>
          120  +<li class="doctools_subsection"><a href="#subsection4">Version numbers</a></li>
          121  +</ul>
          122  +</li>
   118    123   <li class="doctools_section"><a href="#section4">Structural Overview</a>
   119    124   <ul>
   120         -<li class="doctools_subsection"><a href="#subsection3">Main Directories</a></li>
   121         -<li class="doctools_subsection"><a href="#subsection4">More Directories</a></li>
   122         -<li class="doctools_subsection"><a href="#subsection5">Top Files</a></li>
   123         -<li class="doctools_subsection"><a href="#subsection6">File Types</a></li>
          125  +<li class="doctools_subsection"><a href="#subsection5">Main Directories</a></li>
          126  +<li class="doctools_subsection"><a href="#subsection6">More Directories</a></li>
          127  +<li class="doctools_subsection"><a href="#subsection7">Top Files</a></li>
          128  +<li class="doctools_subsection"><a href="#subsection8">File Types</a></li>
   124    129   </ul>
   125    130   </li>
   126    131   <li class="doctools_section"><a href="#section5">Testsuite Tooling</a>
   127    132   <ul>
   128         -<li class="doctools_subsection"><a href="#subsection7">Invoke the testsuites of a specific module</a></li>
   129         -<li class="doctools_subsection"><a href="#subsection8">Invoke the testsuites of all modules</a></li>
   130         -<li class="doctools_subsection"><a href="#subsection9">Detailed Test Logs</a></li>
   131         -<li class="doctools_subsection"><a href="#subsection10">Shell Selection</a></li>
   132         -<li class="doctools_subsection"><a href="#subsection11">Help</a></li>
          133  +<li class="doctools_subsection"><a href="#subsection9">Invoke the testsuites of a specific module</a></li>
          134  +<li class="doctools_subsection"><a href="#subsection10">Invoke the testsuites of all modules</a></li>
          135  +<li class="doctools_subsection"><a href="#subsection11">Detailed Test Logs</a></li>
          136  +<li class="doctools_subsection"><a href="#subsection12">Shell Selection</a></li>
          137  +<li class="doctools_subsection"><a href="#subsection13">Help</a></li>
   133    138   </ul>
   134    139   </li>
   135    140   <li class="doctools_section"><a href="#section6">Documentation Tooling</a>
   136    141   <ul>
   137         -<li class="doctools_subsection"><a href="#subsection12">Generate documentation for a specific module</a></li>
   138         -<li class="doctools_subsection"><a href="#subsection13">Generate documentation for all modules</a></li>
   139         -<li class="doctools_subsection"><a href="#subsection14">Available output formats, help</a></li>
   140         -<li class="doctools_subsection"><a href="#subsection15">Validation without output</a></li>
          142  +<li class="doctools_subsection"><a href="#subsection14">Generate documentation for a specific module</a></li>
          143  +<li class="doctools_subsection"><a href="#subsection15">Generate documentation for all modules</a></li>
          144  +<li class="doctools_subsection"><a href="#subsection16">Available output formats, help</a></li>
          145  +<li class="doctools_subsection"><a href="#subsection17">Validation without output</a></li>
   141    146   </ul>
   142    147   </li>
   143    148   <li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
   144    149   <li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
   145    150   </ul>
   146    151   </div>
   147    152   <div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
................................................................................
   239    244   </ol>
   240    245   </li>
   241    246   <li><p>Follow the <span class="sectref"><a href="#section3">Branching and Workflow</a></span> of this guide.</p></li>
   242    247   </ol>
   243    248   </div>
   244    249   </div>
   245    250   <div id="section3" class="doctools_section"><h2><a name="section3">Branching and Workflow</a></h2>
   246         -<p>x</p>
          251  +<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Branches</a></h3>
          252  +<p>An important part of working with a
          253  +<i class="term">Distributed Version Control System</i> (<i class="term">DVCS</i>) like
          254  +<a href="https://www.fossil-scm.org/">fossil</a>
          255  +is the management and use of branches.</p>
          256  +<p>For Tcllib the main branch of the collection is
          257  +<i class="term">trunk</i>. In <i class="term">git</i> this branch would be called <i class="term">master</i>,
          258  +and this exactly the case in the
          259  +<a href="https://github.com/tcltk/tcllib/">github mirror</a> of Tcllib.</p>
          260  +<p>In support of debugging, like searching for when an issue
          261  +appeared via bisection, each commit on this branch must pass the
          262  +entire testsuite of the collection.</p>
          263  +<p>As fossil has no mechanism to enfore this this is handled on
          264  +the honor system for developers and maintainers.</p>
          265  +<p>To make the task easier Tcllib comes with a tool
          266  +(&quot;<b class="file">sak.tcl</b>&quot;) providing a number of commands in support. These
          267  +commands are explained in the following sections of this guide.</p>
          268  +<p>While it is possible and allowed to commit directly to trunk
          269  +remember the above regarding the testsuite, and the coming notes about
          270  +other possible issues with a commit.</p>
          271  +<p>Because of this it is (strongly) recommended to perform any
          272  +development on a nicely named (nick of dev, ticket reference if any,
          273  +keywords applicable to the work, ...) non-trunk branch. Outside of the
          274  +trunk developers are allowed to commit intermediate broken states of
          275  +their work. Only at the end, when the branch is considered ready for
          276  +merging will it be necessary to perform full validation.</p>
          277  +</div>
          278  +<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Version numbers</a></h3>
          279  +<p>In Tcllib all changes to a package have to come with an increment of
          280  +its version number. With what part is incremented (patchlevel, minor,
          281  +major version) dependent on the kind of change made. With multiple
          282  +changes in a commit the highest &quot;wins&quot;.</p>
          283  +<p>When working in a development branch the version change can be
          284  +defered until it is time to merge, and then has to cover all the
          285  +changes in the branch.</p>
          286  +<p>Below a list of the kinds of changes and their association
          287  +version increments:</p>
          288  +<dl class="doctools_definitions">
          289  +<dt><i class="term">D - documentation</i></dt>
          290  +<dd><p>No increment</p></dd>
          291  +<dt><i class="term">T - testsuite</i></dt>
          292  +<dd><p>No increment</p></dd>
          293  +<dt><i class="term">B - bugfix</i></dt>
          294  +<dd><p>Patchlevel</p></dd>
          295  +<dt><i class="term">I - implementation tweak</i></dt>
          296  +<dd><p>Patchlevel</p></dd>
          297  +<dt><i class="term">P - performance tweak</i></dt>
          298  +<dd><p>Patchlevel</p></dd>
          299  +<dt><i class="term">E - backward-compatible extension</i></dt>
          300  +<dd><p>Minor</p></dd>
          301  +<dt><i class="term">API - incompatible change</i></dt>
          302  +<dd><p>Major</p></dd>
          303  +</dl>
          304  +<p>Note, a commit containing a version increment has to mention
          305  +the kind of change which caused it in the commit message, as well as
          306  +the new version number.</p>
          307  +<p>Note further that the version number of a package currently
          308  +exists in 3 places. An increment has to update all of them:</p>
          309  +<ol class="doctools_enumerated">
          310  +<li><p>The package implementation.</p></li>
          311  +<li><p>The package index (&quot;<b class="file">pkgIndex.tcl</b>&quot;)</p></li>
          312  +<li><p>The package documentation.</p></li>
          313  +</ol>
          314  +<p>The &quot;<b class="file">sak.tcl</b>&quot; command <b class="cmd">validate version</b> helps
          315  +finding discrepancies between the first two.
          316  +All the other <b class="cmd">validate</b> methods are also of interest to any
          317  +developer. Invoke it with</p>
          318  +<pre class="doctools_example">
          319  +    sak.tcl help validate
          320  +</pre>
          321  +<p>to see their documentation.</p>
          322  +</div>
   247    323   </div>
   248    324   <div id="section4" class="doctools_section"><h2><a name="section4">Structural Overview</a></h2>
   249         -<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Main Directories</a></h3>
          325  +<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Main Directories</a></h3>
   250    326   <p>The main directories in the Tcllib toplevel directory and of interest
   251    327   to a developer are:</p>
   252    328   <dl class="doctools_definitions">
   253    329   <dt>&quot;<b class="file">modules</b>&quot;</dt>
   254    330   <dd><p>Each child directory represents one or more packages.
   255    331   In the case of the latter the packages are usually related in some
   256    332   way. Examples are &quot;<b class="file">base64</b>&quot;, &quot;<b class="file">math</b>&quot;, and &quot;<b class="file">struct</b>&quot;, with
................................................................................
   262    338   into sub-directories.</p></dd>
   263    339   <dt>&quot;<b class="file">examples</b>&quot;</dt>
   264    340   <dd><p>Each child directory &quot;<b class="file">foo</b>&quot; contains one or more example
   265    341   application for the packages in &quot;<b class="file">modules/foo</b>&quot;. These examples are
   266    342   generally not polished enough to be considered for installation.</p></dd>
   267    343   </dl>
   268    344   </div>
   269         -<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">More Directories</a></h3>
          345  +<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">More Directories</a></h3>
   270    346   <dl class="doctools_definitions">
   271    347   <dt>&quot;<b class="file">config</b>&quot;</dt>
   272    348   <dd><p>This directory contains files supporting the unix build system,
   273    349   i.e. &quot;<b class="file">configure</b>&quot; and &quot;<b class="file">Makefile.in</b>&quot;.</p></dd>
   274    350   <dt>&quot;<b class="file">devdoc</b>&quot;</dt>
   275    351   <dd><p>This directories contains the doctools sources for the global
   276    352   documentation, like this document and its sibling guides.</p></dd>
................................................................................
   286    362   This is the documentation which will be installed.</p></dd>
   287    363   <dt>&quot;<b class="file">support</b>&quot;</dt>
   288    364   <dd><p>This directory contains the sources of internal packages and utilities
   289    365   used in the implementation of the &quot;<b class="file">installer.tcl</b>&quot; and
   290    366   &quot;<b class="file">sak.tcl</b>&quot; scripts/tools.</p></dd>
   291    367   </dl>
   292    368   </div>
   293         -<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Top Files</a></h3>
          369  +<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Top Files</a></h3>
   294    370   <dl class="doctools_definitions">
   295    371   <dt>&quot;<b class="file">aclocal.m4</b>&quot;</dt>
   296    372   <dd></dd>
   297    373   <dt>&quot;<b class="file">configure</b>&quot;</dt>
   298    374   <dd></dd>
   299    375   <dt>&quot;<b class="file">configure.in</b>&quot;</dt>
   300    376   <dd></dd>
................................................................................
   334    410   <dd></dd>
   335    411   <dt>&quot;<b class="file">tcllib.tap</b>&quot;</dt>
   336    412   <dd></dd>
   337    413   <dt>&quot;<b class="file">tcllib.yml</b>&quot;</dt>
   338    414   <dd><p>????</p></dd>
   339    415   </dl>
   340    416   </div>
   341         -<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">File Types</a></h3>
          417  +<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">File Types</a></h3>
   342    418   <p>The most common file types, by file extension, are:</p>
   343    419   <dl class="doctools_definitions">
   344    420   <dt>&quot;<b class="file">.tcl</b>&quot;</dt>
   345    421   <dd><p>Tcl code for a package, application, or example.</p></dd>
   346    422   <dt>&quot;<b class="file">.man</b>&quot;</dt>
   347    423   <dd><p>Doctools-formatted documentation, usually for a package.</p></dd>
   348    424   <dt>&quot;<b class="file">.test</b>&quot;</dt>
................................................................................
   363    439   <p>Testsuites in Tcllib are based on Tcl's standard test package
   364    440   <b class="package">tcltest</b>, plus utilities found in the directory
   365    441   &quot;<b class="file">modules/devtools</b>&quot;</p>
   366    442   <p>Tcllib developers invoke the suites through the
   367    443   <b class="cmd">test run</b> method of the &quot;<b class="file">sak.tcl</b>&quot; tool, with other methods
   368    444   of <b class="cmd"><a href="../../../index.html#test">test</a></b> providing management operations, for example setting a
   369    445   list of standard Tcl shells to use.</p>
   370         -<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Invoke the testsuites of a specific module</a></h3>
          446  +<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Invoke the testsuites of a specific module</a></h3>
   371    447   <p>Invoke either</p>
   372    448   <pre class="doctools_example">  ./sak.tcl test run FOO </pre>
   373    449   <p>or</p>
   374    450   <pre class="doctools_example">  ./sak.tcl test run modules/FOO </pre>
   375    451   <p>to invoke the testsuites found in a specific module &quot;<b class="file">FOO</b>&quot;.</p>
   376    452   </div>
   377         -<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Invoke the testsuites of all modules</a></h3>
          453  +<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Invoke the testsuites of all modules</a></h3>
   378    454   <p>Invoke the tool without a module name, i.e.</p>
   379    455   <pre class="doctools_example">  ./sak.tcl test run </pre>
   380    456   <p>to invoke the testsuites of all modules.</p>
   381    457   </div>
   382         -<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Detailed Test Logs</a></h3>
          458  +<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Detailed Test Logs</a></h3>
   383    459   <p>In all the previous examples the test runner will write a combination
   384    460   of progress display and testsuite log to the standard output, showing
   385    461   for each module only the tests that passed or failed and how many of
   386    462   each in a summary at the end.</p>
   387    463   <p>To get a detailed log, it is necessary to invoke the test
   388    464   runner with additional options.</p>
   389    465   <p>For one:</p>
................................................................................
   399    475   </pre>
   400    476   <p>This writes the detailed log to the standard output, instead of the
   401    477   short log.</p>
   402    478   <p>Regardless of form, the detailed log contains a list of all test
   403    479   cases executed, which failed, and how they failed (expected versus
   404    480   actual results).</p>
   405    481   </div>
   406         -<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Shell Selection</a></h3>
          482  +<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">Shell Selection</a></h3>
   407    483   <p>By default the test runner will use all the Tcl shells specified via
   408    484   <b class="cmd">test add</b> to invoke the specified testsuites, if any. If no
   409    485   such are specified it will fall back to the Tcl shell used to ran the
   410    486   tool itself.</p>
   411    487   <p>Use option <b class="option">--shell</b> to explicitly specify the Tcl shell
   412    488   to use, like</p>
   413    489   <pre class="doctools_example">
   414    490     ./sak.tcl test run --shell /path/to/tclsh ...
   415    491   </pre>
   416    492   </div>
   417         -<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Help</a></h3>
          493  +<div id="subsection13" class="doctools_subsection"><h3><a name="subsection13">Help</a></h3>
   418    494   <p>Invoke the tool as</p>
   419    495   <pre class="doctools_example">  ./sak.tcl help test </pre>
   420    496   <p>to see the detailed help for all methods of <b class="cmd"><a href="../../../index.html#test">test</a></b>, and the
   421    497   associated options.</p>
   422    498   </div>
   423    499   </div>
   424    500   <div id="section6" class="doctools_section"><h2><a name="section6">Documentation Tooling</a></h2>
................................................................................
   427    503   Its supporting packages are a part of Tcllib, see the directories
   428    504   &quot;<b class="file">modules/doctools</b>&quot; and &quot;<b class="file">modules/dtplite</b>&quot;. The latter is
   429    505   an application package, with the actual application
   430    506   &quot;<b class="file">apps/dtplite</b>&quot; a light wrapper around it.</p>
   431    507   <p>Tcllib developers gain access to these through the <b class="cmd">doc</b>
   432    508   method of the &quot;<b class="file">sak.tcl</b>&quot; tool, another (internal) wrapper around
   433    509   the &quot;<b class="file">modules/dptlite</b>&quot; application package.</p>
   434         -<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">Generate documentation for a specific module</a></h3>
          510  +<div id="subsection14" class="doctools_subsection"><h3><a name="subsection14">Generate documentation for a specific module</a></h3>
   435    511   <p>Invoke either</p>
   436    512   <pre class="doctools_example">  ./sak.tcl doc html FOO </pre>
   437    513   <p>or</p>
   438    514   <pre class="doctools_example">  ./sak.tcl doc html modules/FOO </pre>
   439    515   <p>to generate HTML for the documentation found in the module &quot;<b class="file">FOO</b>&quot;.
   440    516   Instead of <b class="const">html</b> any other supported format can be used here,
   441    517   of course.</p>
   442    518   <p>The generated formatted documentation will be placed into a
   443    519   directory &quot;<b class="file">doc</b>&quot; in the current working directory.</p>
   444    520   </div>
   445         -<div id="subsection13" class="doctools_subsection"><h3><a name="subsection13">Generate documentation for all modules</a></h3>
          521  +<div id="subsection15" class="doctools_subsection"><h3><a name="subsection15">Generate documentation for all modules</a></h3>
   446    522   <p>Invoke the tool without a module name, i.e.</p>
   447    523   <pre class="doctools_example">  ./sak.tcl doc html </pre>
   448    524   <p>to generate HTML for the documentation found in all modules.
   449    525   Instead of <b class="const">html</b> any other supported format can be used here,
   450    526   of course.</p>
   451    527   <p>The generated formatted documentation will be placed into a
   452    528   directory &quot;<b class="file">doc</b>&quot; in the current working directory.</p>
   453    529   </div>
   454         -<div id="subsection14" class="doctools_subsection"><h3><a name="subsection14">Available output formats, help</a></h3>
          530  +<div id="subsection16" class="doctools_subsection"><h3><a name="subsection16">Available output formats, help</a></h3>
   455    531   <p>Invoke the tool as</p>
   456    532   <pre class="doctools_example">  ./sak.tcl help doc </pre>
   457    533   <p>to see the entire set of supported output formats which can be
   458    534   generated.</p>
   459    535   </div>
   460         -<div id="subsection15" class="doctools_subsection"><h3><a name="subsection15">Validation without output</a></h3>
          536  +<div id="subsection17" class="doctools_subsection"><h3><a name="subsection17">Validation without output</a></h3>
   461    537   <p>Note the special format <b class="const">validate</b>.</p>
   462    538   <p>Using this value as the name of the format to generate forces
   463    539   the tool to simply check that the documentation is syntactically
   464    540   correct, without generating actual output.</p>
   465    541   <p>Invoke it as either</p>
   466    542   <pre class="doctools_example">  ./sak.tcl doc validate (modules/)FOO </pre>
   467    543   <p>or</p>
................................................................................
   564    640   implementation while writing the tests. Like writing a test for a
   565    641   condition like <i class="term">startnode not in input graph</i> serving as
   566    642   reminder to put a check for this condition into the code.</p>
   567    643   </div>
   568    644   <div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>
   569    645   <p>A last thing to consider when adding a new package to the collection
   570    646   is installation.</p>
   571         -<p>How to <em>use</em> the tool, the &quot;<b class="file">installer.tcl</b>&quot; script is
   572         -doumented in
   573         -<i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i>.</p>
   574         -<p>Here we document how to extend the installer so that it may
   575         -install the new package(s).</p>
   576         -<p>In most cases only a single file has to be modified,
          647  +<p>How to <em>use</em> the &quot;<b class="file">installer.tcl</b>&quot; script is documented
          648  +in <i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i>.</p>
          649  +<p>Here we document how to extend said installer so that it may
          650  +install new package(s) and/or application(s).</p>
          651  +<p>In most cases only a single file has to be modified, the
   577    652   &quot;<b class="file">support/installation/modules.tcl</b>&quot; holding one command per module
   578    653   and application to install.</p>
   579         -<p>The commands are:</p>
          654  +<p>The relevant commands are:</p>
   580    655   <dl class="doctools_definitions">
   581    656   <dt><a name="1"><b class="cmd"><a href="../../../index.html#module">Module</a></b> <i class="arg">name</i> <i class="arg">code-action</i> <i class="arg">doc-action</i> <i class="arg">example-action</i></a></dt>
   582    657   <dd><p>Install the packages of module <i class="arg">name</i>, found in
   583    658   &quot;<b class="file">modules/<i class="arg">name</i></b>&quot;.</p>
   584    659   <p>The <i class="arg">code-action</i> is responsible for installing the
   585    660   packages and their index. The system currently provides</p>
   586    661   <dl class="doctools_definitions">

Changes to idoc/man/files/devdoc/tcllib_devguide.n.

   377    377   Coordination and discussion with ticket submitter during
   378    378   the development and/or application of bug fixes\&.
   379    379   .RE
   380    380   .IP [4]
   381    381   Follow the \fBBranching and Workflow\fR of this guide\&.
   382    382   .PP
   383    383   .SH "BRANCHING AND WORKFLOW"
   384         -x
          384  +.SS BRANCHES
          385  +An important part of working with a
          386  +\fIDistributed Version Control System\fR (\fIDVCS\fR) like
          387  +\fIfossil\fR [https://www\&.fossil-scm\&.org/]
          388  +is the management and use of branches\&.
          389  +.PP
          390  +For Tcllib the main branch of the collection is
          391  +\fItrunk\fR\&. In \fIgit\fR this branch would be called \fImaster\fR,
          392  +and this exactly the case in the
          393  +\fIgithub mirror\fR [https://github\&.com/tcltk/tcllib/] of Tcllib\&.
          394  +.PP
          395  +In support of debugging, like searching for when an issue
          396  +appeared via bisection, each commit on this branch must pass the
          397  +entire testsuite of the collection\&.
          398  +.PP
          399  +As fossil has no mechanism to enfore this this is handled on
          400  +the honor system for developers and maintainers\&.
          401  +.PP
          402  +To make the task easier Tcllib comes with a tool
          403  +("\fIsak\&.tcl\fR") providing a number of commands in support\&. These
          404  +commands are explained in the following sections of this guide\&.
          405  +.PP
          406  +While it is possible and allowed to commit directly to trunk
          407  +remember the above regarding the testsuite, and the coming notes about
          408  +other possible issues with a commit\&.
          409  +.PP
          410  +Because of this it is (strongly) recommended to perform any
          411  +development on a nicely named (nick of dev, ticket reference if any,
          412  +keywords applicable to the work, \&.\&.\&.) non-trunk branch\&. Outside of the
          413  +trunk developers are allowed to commit intermediate broken states of
          414  +their work\&. Only at the end, when the branch is considered ready for
          415  +merging will it be necessary to perform full validation\&.
          416  +.SS "VERSION NUMBERS"
          417  +In Tcllib all changes to a package have to come with an increment of
          418  +its version number\&. With what part is incremented (patchlevel, minor,
          419  +major version) dependent on the kind of change made\&. With multiple
          420  +changes in a commit the highest "wins"\&.
          421  +.PP
          422  +When working in a development branch the version change can be
          423  +defered until it is time to merge, and then has to cover all the
          424  +changes in the branch\&.
          425  +.PP
          426  +Below a list of the kinds of changes and their association
          427  +version increments:
          428  +.TP
          429  +\fID - documentation\fR
          430  +No increment
          431  +.TP
          432  +\fIT - testsuite\fR
          433  +No increment
          434  +.TP
          435  +\fIB - bugfix\fR
          436  +Patchlevel
          437  +.TP
          438  +\fII - implementation tweak\fR
          439  +Patchlevel
          440  +.TP
          441  +\fIP - performance tweak\fR
          442  +Patchlevel
          443  +.TP
          444  +\fIE - backward-compatible extension\fR
          445  +Minor
          446  +.TP
          447  +\fIAPI - incompatible change\fR
          448  +Major
          449  +.PP
          450  +.PP
          451  +Note, a commit containing a version increment has to mention
          452  +the kind of change which caused it in the commit message, as well as
          453  +the new version number\&.
          454  +.PP
          455  +Note further that the version number of a package currently
          456  +exists in 3 places\&. An increment has to update all of them:
          457  +.IP [1]
          458  +The package implementation\&.
          459  +.IP [2]
          460  +The package index ("\fIpkgIndex\&.tcl\fR")
          461  +.IP [3]
          462  +The package documentation\&.
          463  +.PP
          464  +.PP
          465  +The "\fIsak\&.tcl\fR" command \fBvalidate version\fR helps
          466  +finding discrepancies between the first two\&.
          467  +All the other \fBvalidate\fR methods are also of interest to any
          468  +developer\&. Invoke it with
          469  +.CS
          470  +
          471  +
          472  +    sak\&.tcl help validate
          473  +
          474  +.CE
          475  +to see their documentation\&.
   385    476   .SH "STRUCTURAL OVERVIEW"
   386    477   .SS "MAIN DIRECTORIES"
   387    478   The main directories in the Tcllib toplevel directory and of interest
   388    479   to a developer are:
   389    480   .TP
   390    481   "\fImodules\fR"
   391    482   Each child directory represents one or more packages\&.
................................................................................
   774    865   implementation while writing the tests\&. Like writing a test for a
   775    866   condition like \fIstartnode not in input graph\fR serving as
   776    867   reminder to put a check for this condition into the code\&.
   777    868   .SH "INSTALLATION TOOLING"
   778    869   A last thing to consider when adding a new package to the collection
   779    870   is installation\&.
   780    871   .PP
   781         -How to \fIuse\fR the tool, the "\fIinstaller\&.tcl\fR" script is
   782         -doumented in
   783         -\fITcllib - The Installer's Guide\fR\&.
          872  +How to \fIuse\fR the "\fIinstaller\&.tcl\fR" script is documented
          873  +in \fITcllib - The Installer's Guide\fR\&.
          874  +.PP
          875  +Here we document how to extend said installer so that it may
          876  +install new package(s) and/or application(s)\&.
   784    877   .PP
   785         -Here we document how to extend the installer so that it may
   786         -install the new package(s)\&.
   787         -.PP
   788         -In most cases only a single file has to be modified,
          878  +In most cases only a single file has to be modified, the
   789    879   "\fIsupport/installation/modules\&.tcl\fR" holding one command per module
   790    880   and application to install\&.
   791    881   .PP
   792         -The commands are:
          882  +The relevant commands are:
   793    883   .TP
   794    884   \fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR
   795    885   Install the packages of module \fIname\fR, found in
   796    886   "\fImodules/\fIname\fR\fR"\&.
   797    887   .sp
   798    888   The \fIcode-action\fR is responsible for installing the
   799    889   packages and their index\&. The system currently provides

Changes to idoc/www/tcllib/files/devdoc/tcllib_devguide.html.

   117    117   <li class="doctools_section"><a href="#section1">Description</a></li>
   118    118   <li class="doctools_section"><a href="#section2">Commitments</a>
   119    119   <ul>
   120    120   <li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
   121    121   <li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
   122    122   </ul>
   123    123   </li>
   124         -<li class="doctools_section"><a href="#section3">Branching and Workflow</a></li>
          124  +<li class="doctools_section"><a href="#section3">Branching and Workflow</a>
          125  +<ul>
          126  +<li class="doctools_subsection"><a href="#subsection3">Branches</a></li>
          127  +<li class="doctools_subsection"><a href="#subsection4">Version numbers</a></li>
          128  +</ul>
          129  +</li>
   125    130   <li class="doctools_section"><a href="#section4">Structural Overview</a>
   126    131   <ul>
   127         -<li class="doctools_subsection"><a href="#subsection3">Main Directories</a></li>
   128         -<li class="doctools_subsection"><a href="#subsection4">More Directories</a></li>
   129         -<li class="doctools_subsection"><a href="#subsection5">Top Files</a></li>
   130         -<li class="doctools_subsection"><a href="#subsection6">File Types</a></li>
          132  +<li class="doctools_subsection"><a href="#subsection5">Main Directories</a></li>
          133  +<li class="doctools_subsection"><a href="#subsection6">More Directories</a></li>
          134  +<li class="doctools_subsection"><a href="#subsection7">Top Files</a></li>
          135  +<li class="doctools_subsection"><a href="#subsection8">File Types</a></li>
   131    136   </ul>
   132    137   </li>
   133    138   <li class="doctools_section"><a href="#section5">Testsuite Tooling</a>
   134    139   <ul>
   135         -<li class="doctools_subsection"><a href="#subsection7">Invoke the testsuites of a specific module</a></li>
   136         -<li class="doctools_subsection"><a href="#subsection8">Invoke the testsuites of all modules</a></li>
   137         -<li class="doctools_subsection"><a href="#subsection9">Detailed Test Logs</a></li>
   138         -<li class="doctools_subsection"><a href="#subsection10">Shell Selection</a></li>
   139         -<li class="doctools_subsection"><a href="#subsection11">Help</a></li>
          140  +<li class="doctools_subsection"><a href="#subsection9">Invoke the testsuites of a specific module</a></li>
          141  +<li class="doctools_subsection"><a href="#subsection10">Invoke the testsuites of all modules</a></li>
          142  +<li class="doctools_subsection"><a href="#subsection11">Detailed Test Logs</a></li>
          143  +<li class="doctools_subsection"><a href="#subsection12">Shell Selection</a></li>
          144  +<li class="doctools_subsection"><a href="#subsection13">Help</a></li>
   140    145   </ul>
   141    146   </li>
   142    147   <li class="doctools_section"><a href="#section6">Documentation Tooling</a>
   143    148   <ul>
   144         -<li class="doctools_subsection"><a href="#subsection12">Generate documentation for a specific module</a></li>
   145         -<li class="doctools_subsection"><a href="#subsection13">Generate documentation for all modules</a></li>
   146         -<li class="doctools_subsection"><a href="#subsection14">Available output formats, help</a></li>
   147         -<li class="doctools_subsection"><a href="#subsection15">Validation without output</a></li>
          149  +<li class="doctools_subsection"><a href="#subsection14">Generate documentation for a specific module</a></li>
          150  +<li class="doctools_subsection"><a href="#subsection15">Generate documentation for all modules</a></li>
          151  +<li class="doctools_subsection"><a href="#subsection16">Available output formats, help</a></li>
          152  +<li class="doctools_subsection"><a href="#subsection17">Validation without output</a></li>
   148    153   </ul>
   149    154   </li>
   150    155   <li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
   151    156   <li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
   152    157   </ul>
   153    158   </div>
   154    159   <div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
................................................................................
   246    251   </ol>
   247    252   </li>
   248    253   <li><p>Follow the <span class="sectref"><a href="#section3">Branching and Workflow</a></span> of this guide.</p></li>
   249    254   </ol>
   250    255   </div>
   251    256   </div>
   252    257   <div id="section3" class="doctools_section"><h2><a name="section3">Branching and Workflow</a></h2>
   253         -<p>x</p>
          258  +<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Branches</a></h3>
          259  +<p>An important part of working with a
          260  +<i class="term">Distributed Version Control System</i> (<i class="term">DVCS</i>) like
          261  +<a href="https://www.fossil-scm.org/">fossil</a>
          262  +is the management and use of branches.</p>
          263  +<p>For Tcllib the main branch of the collection is
          264  +<i class="term">trunk</i>. In <i class="term">git</i> this branch would be called <i class="term">master</i>,
          265  +and this exactly the case in the
          266  +<a href="https://github.com/tcltk/tcllib/">github mirror</a> of Tcllib.</p>
          267  +<p>In support of debugging, like searching for when an issue
          268  +appeared via bisection, each commit on this branch must pass the
          269  +entire testsuite of the collection.</p>
          270  +<p>As fossil has no mechanism to enfore this this is handled on
          271  +the honor system for developers and maintainers.</p>
          272  +<p>To make the task easier Tcllib comes with a tool
          273  +(&quot;<b class="file">sak.tcl</b>&quot;) providing a number of commands in support. These
          274  +commands are explained in the following sections of this guide.</p>
          275  +<p>While it is possible and allowed to commit directly to trunk
          276  +remember the above regarding the testsuite, and the coming notes about
          277  +other possible issues with a commit.</p>
          278  +<p>Because of this it is (strongly) recommended to perform any
          279  +development on a nicely named (nick of dev, ticket reference if any,
          280  +keywords applicable to the work, ...) non-trunk branch. Outside of the
          281  +trunk developers are allowed to commit intermediate broken states of
          282  +their work. Only at the end, when the branch is considered ready for
          283  +merging will it be necessary to perform full validation.</p>
          284  +</div>
          285  +<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Version numbers</a></h3>
          286  +<p>In Tcllib all changes to a package have to come with an increment of
          287  +its version number. With what part is incremented (patchlevel, minor,
          288  +major version) dependent on the kind of change made. With multiple
          289  +changes in a commit the highest &quot;wins&quot;.</p>
          290  +<p>When working in a development branch the version change can be
          291  +defered until it is time to merge, and then has to cover all the
          292  +changes in the branch.</p>
          293  +<p>Below a list of the kinds of changes and their association
          294  +version increments:</p>
          295  +<dl class="doctools_definitions">
          296  +<dt><i class="term">D - documentation</i></dt>
          297  +<dd><p>No increment</p></dd>
          298  +<dt><i class="term">T - testsuite</i></dt>
          299  +<dd><p>No increment</p></dd>
          300  +<dt><i class="term">B - bugfix</i></dt>
          301  +<dd><p>Patchlevel</p></dd>
          302  +<dt><i class="term">I - implementation tweak</i></dt>
          303  +<dd><p>Patchlevel</p></dd>
          304  +<dt><i class="term">P - performance tweak</i></dt>
          305  +<dd><p>Patchlevel</p></dd>
          306  +<dt><i class="term">E - backward-compatible extension</i></dt>
          307  +<dd><p>Minor</p></dd>
          308  +<dt><i class="term">API - incompatible change</i></dt>
          309  +<dd><p>Major</p></dd>
          310  +</dl>
          311  +<p>Note, a commit containing a version increment has to mention
          312  +the kind of change which caused it in the commit message, as well as
          313  +the new version number.</p>
          314  +<p>Note further that the version number of a package currently
          315  +exists in 3 places. An increment has to update all of them:</p>
          316  +<ol class="doctools_enumerated">
          317  +<li><p>The package implementation.</p></li>
          318  +<li><p>The package index (&quot;<b class="file">pkgIndex.tcl</b>&quot;)</p></li>
          319  +<li><p>The package documentation.</p></li>
          320  +</ol>
          321  +<p>The &quot;<b class="file">sak.tcl</b>&quot; command <b class="cmd">validate version</b> helps
          322  +finding discrepancies between the first two.
          323  +All the other <b class="cmd">validate</b> methods are also of interest to any
          324  +developer. Invoke it with</p>
          325  +<pre class="doctools_example">
          326  +    sak.tcl help validate
          327  +</pre>
          328  +<p>to see their documentation.</p>
          329  +</div>
   254    330   </div>
   255    331   <div id="section4" class="doctools_section"><h2><a name="section4">Structural Overview</a></h2>
   256         -<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Main Directories</a></h3>
          332  +<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Main Directories</a></h3>
   257    333   <p>The main directories in the Tcllib toplevel directory and of interest
   258    334   to a developer are:</p>
   259    335   <dl class="doctools_definitions">
   260    336   <dt>&quot;<b class="file">modules</b>&quot;</dt>
   261    337   <dd><p>Each child directory represents one or more packages.
   262    338   In the case of the latter the packages are usually related in some
   263    339   way. Examples are &quot;<b class="file">base64</b>&quot;, &quot;<b class="file">math</b>&quot;, and &quot;<b class="file">struct</b>&quot;, with
................................................................................
   269    345   into sub-directories.</p></dd>
   270    346   <dt>&quot;<b class="file">examples</b>&quot;</dt>
   271    347   <dd><p>Each child directory &quot;<b class="file">foo</b>&quot; contains one or more example
   272    348   application for the packages in &quot;<b class="file">modules/foo</b>&quot;. These examples are
   273    349   generally not polished enough to be considered for installation.</p></dd>
   274    350   </dl>
   275    351   </div>
   276         -<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">More Directories</a></h3>
          352  +<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">More Directories</a></h3>
   277    353   <dl class="doctools_definitions">
   278    354   <dt>&quot;<b class="file">config</b>&quot;</dt>
   279    355   <dd><p>This directory contains files supporting the unix build system,
   280    356   i.e. &quot;<b class="file">configure</b>&quot; and &quot;<b class="file">Makefile.in</b>&quot;.</p></dd>
   281    357   <dt>&quot;<b class="file">devdoc</b>&quot;</dt>
   282    358   <dd><p>This directories contains the doctools sources for the global
   283    359   documentation, like this document and its sibling guides.</p></dd>
................................................................................
   293    369   This is the documentation which will be installed.</p></dd>
   294    370   <dt>&quot;<b class="file">support</b>&quot;</dt>
   295    371   <dd><p>This directory contains the sources of internal packages and utilities
   296    372   used in the implementation of the &quot;<b class="file">installer.tcl</b>&quot; and
   297    373   &quot;<b class="file">sak.tcl</b>&quot; scripts/tools.</p></dd>
   298    374   </dl>
   299    375   </div>
   300         -<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Top Files</a></h3>
          376  +<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Top Files</a></h3>
   301    377   <dl class="doctools_definitions">
   302    378   <dt>&quot;<b class="file">aclocal.m4</b>&quot;</dt>
   303    379   <dd></dd>
   304    380   <dt>&quot;<b class="file">configure</b>&quot;</dt>
   305    381   <dd></dd>
   306    382   <dt>&quot;<b class="file">configure.in</b>&quot;</dt>
   307    383   <dd></dd>
................................................................................
   341    417   <dd></dd>
   342    418   <dt>&quot;<b class="file">tcllib.tap</b>&quot;</dt>
   343    419   <dd></dd>
   344    420   <dt>&quot;<b class="file">tcllib.yml</b>&quot;</dt>
   345    421   <dd><p>????</p></dd>
   346    422   </dl>
   347    423   </div>
   348         -<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">File Types</a></h3>
          424  +<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">File Types</a></h3>
   349    425   <p>The most common file types, by file extension, are:</p>
   350    426   <dl class="doctools_definitions">
   351    427   <dt>&quot;<b class="file">.tcl</b>&quot;</dt>
   352    428   <dd><p>Tcl code for a package, application, or example.</p></dd>
   353    429   <dt>&quot;<b class="file">.man</b>&quot;</dt>
   354    430   <dd><p>Doctools-formatted documentation, usually for a package.</p></dd>
   355    431   <dt>&quot;<b class="file">.test</b>&quot;</dt>
................................................................................
   370    446   <p>Testsuites in Tcllib are based on Tcl's standard test package
   371    447   <b class="package">tcltest</b>, plus utilities found in the directory
   372    448   &quot;<b class="file">modules/devtools</b>&quot;</p>
   373    449   <p>Tcllib developers invoke the suites through the
   374    450   <b class="cmd">test run</b> method of the &quot;<b class="file">sak.tcl</b>&quot; tool, with other methods
   375    451   of <b class="cmd"><a href="../../../index.html#test">test</a></b> providing management operations, for example setting a
   376    452   list of standard Tcl shells to use.</p>
   377         -<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Invoke the testsuites of a specific module</a></h3>
          453  +<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Invoke the testsuites of a specific module</a></h3>
   378    454   <p>Invoke either</p>
   379    455   <pre class="doctools_example">  ./sak.tcl test run FOO </pre>
   380    456   <p>or</p>
   381    457   <pre class="doctools_example">  ./sak.tcl test run modules/FOO </pre>
   382    458   <p>to invoke the testsuites found in a specific module &quot;<b class="file">FOO</b>&quot;.</p>
   383    459   </div>
   384         -<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Invoke the testsuites of all modules</a></h3>
          460  +<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Invoke the testsuites of all modules</a></h3>
   385    461   <p>Invoke the tool without a module name, i.e.</p>
   386    462   <pre class="doctools_example">  ./sak.tcl test run </pre>
   387    463   <p>to invoke the testsuites of all modules.</p>
   388    464   </div>
   389         -<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Detailed Test Logs</a></h3>
          465  +<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Detailed Test Logs</a></h3>
   390    466   <p>In all the previous examples the test runner will write a combination
   391    467   of progress display and testsuite log to the standard output, showing
   392    468   for each module only the tests that passed or failed and how many of
   393    469   each in a summary at the end.</p>
   394    470   <p>To get a detailed log, it is necessary to invoke the test
   395    471   runner with additional options.</p>
   396    472   <p>For one:</p>
................................................................................
   406    482   </pre>
   407    483   <p>This writes the detailed log to the standard output, instead of the
   408    484   short log.</p>
   409    485   <p>Regardless of form, the detailed log contains a list of all test
   410    486   cases executed, which failed, and how they failed (expected versus
   411    487   actual results).</p>
   412    488   </div>
   413         -<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Shell Selection</a></h3>
          489  +<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">Shell Selection</a></h3>
   414    490   <p>By default the test runner will use all the Tcl shells specified via
   415    491   <b class="cmd">test add</b> to invoke the specified testsuites, if any. If no
   416    492   such are specified it will fall back to the Tcl shell used to ran the
   417    493   tool itself.</p>
   418    494   <p>Use option <b class="option">--shell</b> to explicitly specify the Tcl shell
   419    495   to use, like</p>
   420    496   <pre class="doctools_example">
   421    497     ./sak.tcl test run --shell /path/to/tclsh ...
   422    498   </pre>
   423    499   </div>
   424         -<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">Help</a></h3>
          500  +<div id="subsection13" class="doctools_subsection"><h3><a name="subsection13">Help</a></h3>
   425    501   <p>Invoke the tool as</p>
   426    502   <pre class="doctools_example">  ./sak.tcl help test </pre>
   427    503   <p>to see the detailed help for all methods of <b class="cmd"><a href="../../../index.html#test">test</a></b>, and the
   428    504   associated options.</p>
   429    505   </div>
   430    506   </div>
   431    507   <div id="section6" class="doctools_section"><h2><a name="section6">Documentation Tooling</a></h2>
................................................................................
   434    510   Its supporting packages are a part of Tcllib, see the directories
   435    511   &quot;<b class="file">modules/doctools</b>&quot; and &quot;<b class="file">modules/dtplite</b>&quot;. The latter is
   436    512   an application package, with the actual application
   437    513   &quot;<b class="file">apps/dtplite</b>&quot; a light wrapper around it.</p>
   438    514   <p>Tcllib developers gain access to these through the <b class="cmd">doc</b>
   439    515   method of the &quot;<b class="file">sak.tcl</b>&quot; tool, another (internal) wrapper around
   440    516   the &quot;<b class="file">modules/dptlite</b>&quot; application package.</p>
   441         -<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">Generate documentation for a specific module</a></h3>
          517  +<div id="subsection14" class="doctools_subsection"><h3><a name="subsection14">Generate documentation for a specific module</a></h3>
   442    518   <p>Invoke either</p>
   443    519   <pre class="doctools_example">  ./sak.tcl doc html FOO </pre>
   444    520   <p>or</p>
   445    521   <pre class="doctools_example">  ./sak.tcl doc html modules/FOO </pre>
   446    522   <p>to generate HTML for the documentation found in the module &quot;<b class="file">FOO</b>&quot;.
   447    523   Instead of <b class="const">html</b> any other supported format can be used here,
   448    524   of course.</p>
   449    525   <p>The generated formatted documentation will be placed into a
   450    526   directory &quot;<b class="file">doc</b>&quot; in the current working directory.</p>
   451    527   </div>
   452         -<div id="subsection13" class="doctools_subsection"><h3><a name="subsection13">Generate documentation for all modules</a></h3>
          528  +<div id="subsection15" class="doctools_subsection"><h3><a name="subsection15">Generate documentation for all modules</a></h3>
   453    529   <p>Invoke the tool without a module name, i.e.</p>
   454    530   <pre class="doctools_example">  ./sak.tcl doc html </pre>
   455    531   <p>to generate HTML for the documentation found in all modules.
   456    532   Instead of <b class="const">html</b> any other supported format can be used here,
   457    533   of course.</p>
   458    534   <p>The generated formatted documentation will be placed into a
   459    535   directory &quot;<b class="file">doc</b>&quot; in the current working directory.</p>
   460    536   </div>
   461         -<div id="subsection14" class="doctools_subsection"><h3><a name="subsection14">Available output formats, help</a></h3>
          537  +<div id="subsection16" class="doctools_subsection"><h3><a name="subsection16">Available output formats, help</a></h3>
   462    538   <p>Invoke the tool as</p>
   463    539   <pre class="doctools_example">  ./sak.tcl help doc </pre>
   464    540   <p>to see the entire set of supported output formats which can be
   465    541   generated.</p>
   466    542   </div>
   467         -<div id="subsection15" class="doctools_subsection"><h3><a name="subsection15">Validation without output</a></h3>
          543  +<div id="subsection17" class="doctools_subsection"><h3><a name="subsection17">Validation without output</a></h3>
   468    544   <p>Note the special format <b class="const">validate</b>.</p>
   469    545   <p>Using this value as the name of the format to generate forces
   470    546   the tool to simply check that the documentation is syntactically
   471    547   correct, without generating actual output.</p>
   472    548   <p>Invoke it as either</p>
   473    549   <pre class="doctools_example">  ./sak.tcl doc validate (modules/)FOO </pre>
   474    550   <p>or</p>
................................................................................
   571    647   implementation while writing the tests. Like writing a test for a
   572    648   condition like <i class="term">startnode not in input graph</i> serving as
   573    649   reminder to put a check for this condition into the code.</p>
   574    650   </div>
   575    651   <div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>
   576    652   <p>A last thing to consider when adding a new package to the collection
   577    653   is installation.</p>
   578         -<p>How to <em>use</em> the tool, the &quot;<b class="file">installer.tcl</b>&quot; script is
   579         -doumented in
   580         -<i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i>.</p>
   581         -<p>Here we document how to extend the installer so that it may
   582         -install the new package(s).</p>
   583         -<p>In most cases only a single file has to be modified,
          654  +<p>How to <em>use</em> the &quot;<b class="file">installer.tcl</b>&quot; script is documented
          655  +in <i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i>.</p>
          656  +<p>Here we document how to extend said installer so that it may
          657  +install new package(s) and/or application(s).</p>
          658  +<p>In most cases only a single file has to be modified, the
   584    659   &quot;<b class="file">support/installation/modules.tcl</b>&quot; holding one command per module
   585    660   and application to install.</p>
   586         -<p>The commands are:</p>
          661  +<p>The relevant commands are:</p>
   587    662   <dl class="doctools_definitions">
   588    663   <dt><a name="1"><b class="cmd"><a href="../../../index.html#module">Module</a></b> <i class="arg">name</i> <i class="arg">code-action</i> <i class="arg">doc-action</i> <i class="arg">example-action</i></a></dt>
   589    664   <dd><p>Install the packages of module <i class="arg">name</i>, found in
   590    665   &quot;<b class="file">modules/<i class="arg">name</i></b>&quot;.</p>
   591    666   <p>The <i class="arg">code-action</i> is responsible for installing the
   592    667   packages and their index. The system currently provides</p>
   593    668   <dl class="doctools_definitions">