Tcl Library Source Code

Check-in [9e39cdbfe8]
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:Filled in test writing and install support sections of the devguide.
Timelines: family | ancestors | descendants | both | doc-overhaul
Files: files | file ages | folders
SHA3-256: 9e39cdbfe84c4185e0963b05cb1997d3eb03b7eb86f88330445fe7e22324aabd
User & Date: aku 2019-03-12 04:59:56
Context
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
2019-03-08
06:47
Removed deprecated tag `strong`, replaced with `emph`. check-in: fec15b366e user: aku tags: doc-overhaul
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to devdoc/parts/d_installation.inc.

            1  +A last thing to consider when adding a new package to the collection
            2  +is installation.
            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}].
            7  +
            8  +[para] Here we document how to extend the installer so that it may
            9  +install the new package(s).
           10  +
           11  +[para] In most cases only a single file has to be modified,
           12  +[file support/installation/modules.tcl] holding one command per module
           13  +and application to install.
           14  +
           15  +[para] The commands are:
           16  +
           17  +[list_begin definitions]
           18  +
           19  +[call [cmd Module] [arg name] \
           20  +      	   [arg code-action] \
           21  +      	   [arg doc-action] \
           22  +	   [arg example-action]]
           23  +
           24  +Install the packages of module [arg name], found in
           25  +[file modules/[arg name]].
           26  +
           27  +[para] The [arg code-action] is responsible for installing the
           28  +packages and their index. The system currently provides
           29  +
           30  +[list_begin definitions]
           31  +
           32  +[def [cmd _tcl]] Copy all [file .tcl] files found in
           33  +[file modules/[arg name]] into the installation.
           34  +
           35  +[def [cmd _tcr]] As [cmd _tcl], copy the [file .tcl] files found in
           36  +the subdirectories of [file modules/[arg name]] as well.
           37  +
           38  +[def [cmd _tci]] As [cmd _tcl], and copy the [file tclIndex.tcl] file
           39  +as well.
           40  +
           41  +[def [cmd _msg]] As [cmd _tcl], and copy the subdirectory [file msgs]
           42  +as well.
           43  +
           44  +[def [cmd _doc]] As [cmd _tcl], and copy the subdirectory
           45  +[file mpformats] as well.
           46  +
           47  +[def [cmd _tex]] As [cmd _tcl], and copy [file .tex] files as well.
           48  +
           49  +[list_end]
           50  +
           51  +[para] The [arg doc-action] is responsible for installing the package
           52  +documentation. The system currently provides
           53  +
           54  +[list_begin definitions]
           55  +[def [cmd _null]] No documentation available, do nothing.
           56  +
           57  +[def [cmd _man]] Process the [file .man] files found in
           58  +[file modules/[arg name]] and install the results (nroff and/or HTML)
           59  +in the proper location, as given to the installer.
           60  +
           61  +[para] This is actually a fallback, normally the installer uses the
           62  +pre-made formatted documentation found under [file idoc].
           63  +
           64  +[list_end]
           65  +
           66  +[para] The [arg example-action] is responsible for installing the
           67  +examples. The system currently provides
           68  +
           69  +[list_begin definitions]
           70  +[def [cmd _null]] No examples available, do nothing.
           71  +
           72  +[def [cmd _exa]] Copy the the directory [file examples/[arg name]]
           73  +recursively to the install location for examples.
           74  +
           75  +[list_end]
           76  +
           77  +[call [cmd Application] [arg name]]
           78  +
           79  +Install the application with [arg name], found in [file apps].
           80  +
           81  +
           82  +[call [cmd Exclude] [arg name]]
           83  +
           84  +This command signals to the installer which of the listed modules to
           85  +[emph not] install. I.e. they name the deprecated modules of Tcllib.
           86  +
           87  +[list_end]
           88  +
           89  +[para] If, and only if the above actions are not suitable for the new
           90  +module then a second file has to be modified,
           91  +[file support/installation/actions.tcl].
           92  +
           93  +[para] This file contains the implementations of the available
           94  +actions, and is the place where any custom action needed to handle the
           95  +special circumstances of module has to be added.

Changes to devdoc/parts/d_testwrite.inc.

            1  +
            2  +While previous sections talked about running the testsuites for a
            3  +module and the packages therein this has no meaning if the module in
            4  +question has no testsuites at all.
            5  +
            6  +[para] This section gives a very basic overview on possible
            7  +methodologies for writing tests and testsuites.
            8  +
            9  +[para] First there are "drudgery" tests. Written to check absolutely
           10  +basic assumptions which should never fail.
           11  +
           12  +[para] For example for a command FOO taking two arguments, three tests
           13  +calling it with zero, one, and three arguments. The basic checks that
           14  +the command fails if it has not enough arguments, or too many.
           15  +
           16  +[para] After that come the tests checking things based on our
           17  +knowledge of the command, about its properties and assumptions. Some
           18  +examples based on the graph operations added during Google's Summer of
           19  +Code 2009 are:
           20  +
           21  +[list_begin itemized]
           22  +
           23  +[item]	The BellmanFord command in struct::graph::ops takes a
           24  +	[arg startnode] as argument, and this node should be a node of
           25  +	the graph. Equals one test case checking the behavior when the
           26  +	specified node is not a node a graph.
           27  +
           28  +[para]  This often gives rise to code in the implementation which
           29  +	explicitly checks the assumption and throws a nice error.
           30  +	Instead of letting the algorithm fails later in some weird
           31  +	non-deterministic way.
           32  +
           33  +[para]  It not always possible to do such checks. The graph argument
           34  +	for example is just a command in itself, and while we expect
           35  +	it to exhibit a certain interface, i.e. a set of sub-commands
           36  +	aka methods, we cannot check that it has them, except by
           37  +	actually trying to use them. That is done by the algorithm
           38  +	anyway, so an explicit check is just overhead we can get by
           39  +	without.
           40  +
           41  +[item]  IIRC one of the distinguishing characteristic of either
           42  +	BellmanFord and/or Johnson is that they are able to handle
           43  +	negative weights. Whereas Dijkstra requires positive weights.
           44  +
           45  +[para]	This induces (at least) three testcases ... Graph with all
           46  +	positive weights, all negative, and a mix of positive and
           47  +	negative weights.
           48  +
           49  +	Thinking further does the algorithm handle the weight
           50  +	[const 0] as well ? Another test case, or several, if we mix
           51  +	zero with positive and negative weights.
           52  +
           53  +[item]	The two algorithms we are currently thinking about are about
           54  +	distances between nodes, and distance can be 'Inf'inity,
           55  +	i.e. nodes may not be connected. This means that good test
           56  +	cases are
           57  +
           58  +	[list_begin enumerated]
           59  +	[enum]	Strongly connected graph
           60  +	[enum]	Connected graph
           61  +	[enum]	Disconnected graph.
           62  +	[list_end]
           63  +
           64  +	[para] At the extremes of strongly connected and disconnected
           65  +	we have the fully connected graphs and graphs without edges,
           66  +	only nodes, i.e. completely disconnected.
           67  +
           68  +[item]	IIRC both of the algorithms take weighted arcs, and fill in a
           69  +	default if arcs are left unweighted in the input graph.
           70  +
           71  +	[para] This also induces three test cases:
           72  +
           73  +	[list_begin enumerated]
           74  +	[enum]	Graph will all arcs with explicit weights.
           75  +	[enum]	Graph without weights at all.
           76  +	[enum]	Graph with mixture of weighted and unweighted graphs.
           77  +	[list_end]
           78  +[list_end]
           79  +
           80  +[para] What was described above via examples is called
           81  +[term black-box] testing. Test cases are designed and written based on
           82  +the developer's knowledge of the properties of the algorithm and its
           83  +inputs, without referencing a particular implementation.
           84  +
           85  +[para] Going further, a complement to [term black-box] testing is
           86  +[term white-box]. For this we know the implementation of the
           87  +algorithm, we look at it and design our tests cases so that they force
           88  +the code through all possible paths in the implementation. Wherever a
           89  +decision is made we have a test case forcing a specific direction of
           90  +the decision, for all possible combinations and directions. It is easy
           91  +to get a combinatorial explosion in the number of needed test-cases.
           92  +
           93  +[para] In practice I often hope that the black-box tests I have made
           94  +are enough to cover all the paths, obviating the need for white-box
           95  +tests.
           96  +
           97  +[para] The above should be enough to make it clear that writing tests
           98  +for an algorithm takes at least as much time as coding the algorithm,
           99  +and often more time. Much more time.
          100  +
          101  +See for example also [uri http://sqlite.org/testing.html], a writeup
          102  +on how the Sqlite database engine is tested.
          103  +
          104  +[para] An interesting connection is to documentation. In one
          105  +direction, the properties checked with black-box testing are exactly
          106  +the properties which should be documented in the algorithm's man
          107  +page. And conversely, the documentation of the properties of an
          108  +algorithm makes a good reference to base the black-box tests on.
          109  +
          110  +[para] In practice test cases and documentation often get written
          111  +together, cross-influencing each other. And the actual writing of test
          112  +cases is a mix of black and white box, possibly influencing the
          113  +implementation while writing the tests. Like writing a test for a
          114  +condition like [term {startnode not in input graph}] serving as
          115  +reminder to put a check for this condition into the code.

Changes to devdoc/tcllib_devguide.man.

    43     43   
    44     44   [comment {===================================================================}]
    45     45   [section {Testsuite Tooling}]
    46     46   [include parts/d_testing.inc]
    47     47   
    48     48   [comment {===================================================================}]
    49     49   [section {Documentation Tooling}]
    50         -[include parts/d_documentation.inc]x
           50  +[include parts/d_documentation.inc]
    51     51   
    52     52   [comment {===================================================================}]
    53     53   [section {Notes On Writing A Testsuite}]
    54         -[include parts/d_testwrite.inc]x
           54  +[include parts/d_testwrite.inc]
    55     55   
    56     56   [comment {===================================================================}]
    57     57   [section {Installation Tooling}]
    58         -[include parts/d_installation.inc]x
           58  +[include parts/d_installation.inc]
    59     59   
    60     60   [comment {===================================================================}]
    61     61   [manpage_end]
    62     62   

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

   102    102   <h1 class="doctools_title">tcllib_devguide(n) 1 tcllib &quot;&quot;</h1>
   103    103   <div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
   104    104   <p>tcllib_devguide - Tcllib - The Developer's Guide</p>
   105    105   </div>
   106    106   <div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
   107    107   <ul class="doctools_toc">
   108    108   <li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
          109  +<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
   109    110   <li class="doctools_section"><a href="#section1">Description</a></li>
   110    111   <li class="doctools_section"><a href="#section2">Commitments</a>
   111    112   <ul>
   112    113   <li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
   113    114   <li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
   114    115   </ul>
   115    116   </li>
................................................................................
   138    139   <li class="doctools_subsection"><a href="#subsection14">Available output formats, help</a></li>
   139    140   <li class="doctools_subsection"><a href="#subsection15">Validation without output</a></li>
   140    141   </ul>
   141    142   </li>
   142    143   <li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
   143    144   <li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
   144    145   </ul>
          146  +</div>
          147  +<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
          148  +<div class="doctools_synopsis">
          149  +<ul class="doctools_syntax">
          150  +<li><a href="#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></li>
          151  +<li><a href="#2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></li>
          152  +<li><a href="#3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></li>
          153  +</ul>
          154  +</div>
   145    155   </div>
   146    156   <div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
   147    157   <p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
   148    158   package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
   149    159   packages that provide utility functions useful to a large collection
   150    160   of Tcl programmers.</p>
   151    161   <p>This document is a guide for developers working on Tcllib,
................................................................................
   453    463   the tool to simply check that the documentation is syntactically
   454    464   correct, without generating actual output.</p>
   455    465   <p>Invoke it as either</p>
   456    466   <pre class="doctools_example">  ./sak.tcl doc validate (modules/)FOO </pre>
   457    467   <p>or</p>
   458    468   <pre class="doctools_example">  ./sak.tcl doc validate </pre>
   459    469   <p>to either check the packages of a specific module or check all of
   460         -them.
   461         -x</p>
          470  +them.</p>
   462    471   </div>
   463    472   </div>
   464    473   <div id="section7" class="doctools_section"><h2><a name="section7">Notes On Writing A Testsuite</a></h2>
   465         -<p>x</p>
          474  +<p>While previous sections talked about running the testsuites for a
          475  +module and the packages therein this has no meaning if the module in
          476  +question has no testsuites at all.</p>
          477  +<p>This section gives a very basic overview on possible
          478  +methodologies for writing tests and testsuites.</p>
          479  +<p>First there are &quot;drudgery&quot; tests. Written to check absolutely
          480  +basic assumptions which should never fail.</p>
          481  +<p>For example for a command FOO taking two arguments, three tests
          482  +calling it with zero, one, and three arguments. The basic checks that
          483  +the command fails if it has not enough arguments, or too many.</p>
          484  +<p>After that come the tests checking things based on our
          485  +knowledge of the command, about its properties and assumptions. Some
          486  +examples based on the graph operations added during Google's Summer of
          487  +Code 2009 are:</p>
          488  +<ul class="doctools_itemized">
          489  +<li><p>The BellmanFord command in struct::graph::ops takes a
          490  +	<i class="arg">startnode</i> as argument, and this node should be a node of
          491  +	the graph. Equals one test case checking the behavior when the
          492  +	specified node is not a node a graph.</p>
          493  +<p>This often gives rise to code in the implementation which
          494  +	explicitly checks the assumption and throws a nice error.
          495  +	Instead of letting the algorithm fails later in some weird
          496  +	non-deterministic way.</p>
          497  +<p>It not always possible to do such checks. The graph argument
          498  +	for example is just a command in itself, and while we expect
          499  +	it to exhibit a certain interface, i.e. a set of sub-commands
          500  +	aka methods, we cannot check that it has them, except by
          501  +	actually trying to use them. That is done by the algorithm
          502  +	anyway, so an explicit check is just overhead we can get by
          503  +	without.</p></li>
          504  +<li><p>IIRC one of the distinguishing characteristic of either
          505  +	BellmanFord and/or Johnson is that they are able to handle
          506  +	negative weights. Whereas Dijkstra requires positive weights.</p>
          507  +<p>This induces (at least) three testcases ... Graph with all
          508  +	positive weights, all negative, and a mix of positive and
          509  +	negative weights.
          510  +	Thinking further does the algorithm handle the weight
          511  +	<b class="const">0</b> as well ? Another test case, or several, if we mix
          512  +	zero with positive and negative weights.</p></li>
          513  +<li><p>The two algorithms we are currently thinking about are about
          514  +	distances between nodes, and distance can be 'Inf'inity,
          515  +	i.e. nodes may not be connected. This means that good test
          516  +	cases are</p>
          517  +<ol class="doctools_enumerated">
          518  +	
          519  +<li><p>Strongly connected graph</p></li>
          520  +<li><p>Connected graph</p></li>
          521  +<li><p>Disconnected graph.</p></li>
          522  +</ol>
          523  +<p>At the extremes of strongly connected and disconnected
          524  +	we have the fully connected graphs and graphs without edges,
          525  +	only nodes, i.e. completely disconnected.</p></li>
          526  +<li><p>IIRC both of the algorithms take weighted arcs, and fill in a
          527  +	default if arcs are left unweighted in the input graph.</p>
          528  +<p>This also induces three test cases:</p>
          529  +<ol class="doctools_enumerated">
          530  +	
          531  +<li><p>Graph will all arcs with explicit weights.</p></li>
          532  +<li><p>Graph without weights at all.</p></li>
          533  +<li><p>Graph with mixture of weighted and unweighted graphs.</p></li>
          534  +</ol>
          535  +</li>
          536  +</ul>
          537  +<p>What was described above via examples is called
          538  +<i class="term">black-box</i> testing. Test cases are designed and written based on
          539  +the developer's knowledge of the properties of the algorithm and its
          540  +inputs, without referencing a particular implementation.</p>
          541  +<p>Going further, a complement to <i class="term">black-box</i> testing is
          542  +<i class="term">white-box</i>. For this we know the implementation of the
          543  +algorithm, we look at it and design our tests cases so that they force
          544  +the code through all possible paths in the implementation. Wherever a
          545  +decision is made we have a test case forcing a specific direction of
          546  +the decision, for all possible combinations and directions. It is easy
          547  +to get a combinatorial explosion in the number of needed test-cases.</p>
          548  +<p>In practice I often hope that the black-box tests I have made
          549  +are enough to cover all the paths, obviating the need for white-box
          550  +tests.</p>
          551  +<p>The above should be enough to make it clear that writing tests
          552  +for an algorithm takes at least as much time as coding the algorithm,
          553  +and often more time. Much more time.
          554  +See for example also <a href="http://sqlite.org/testing.html">http://sqlite.org/testing.html</a>, a writeup
          555  +on how the Sqlite database engine is tested.</p>
          556  +<p>An interesting connection is to documentation. In one
          557  +direction, the properties checked with black-box testing are exactly
          558  +the properties which should be documented in the algorithm's man
          559  +page. And conversely, the documentation of the properties of an
          560  +algorithm makes a good reference to base the black-box tests on.</p>
          561  +<p>In practice test cases and documentation often get written
          562  +together, cross-influencing each other. And the actual writing of test
          563  +cases is a mix of black and white box, possibly influencing the
          564  +implementation while writing the tests. Like writing a test for a
          565  +condition like <i class="term">startnode not in input graph</i> serving as
          566  +reminder to put a check for this condition into the code.</p>
   466    567   </div>
   467    568   <div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>
   468         -<p>x</p>
          569  +<p>A last thing to consider when adding a new package to the collection
          570  +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,
          577  +&quot;<b class="file">support/installation/modules.tcl</b>&quot; holding one command per module
          578  +and application to install.</p>
          579  +<p>The commands are:</p>
          580  +<dl class="doctools_definitions">
          581  +<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  +<dd><p>Install the packages of module <i class="arg">name</i>, found in
          583  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot;.</p>
          584  +<p>The <i class="arg">code-action</i> is responsible for installing the
          585  +packages and their index. The system currently provides</p>
          586  +<dl class="doctools_definitions">
          587  +<dt><b class="cmd">_tcl</b></dt>
          588  +<dd><p>Copy all &quot;<b class="file">.tcl</b>&quot; files found in
          589  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; into the installation.</p></dd>
          590  +<dt><b class="cmd">_tcr</b></dt>
          591  +<dd><p>As <b class="cmd">_tcl</b>, copy the &quot;<b class="file">.tcl</b>&quot; files found in
          592  +the subdirectories of &quot;<b class="file">modules/<i class="arg">name</i></b>&quot; as well.</p></dd>
          593  +<dt><b class="cmd">_tci</b></dt>
          594  +<dd><p>As <b class="cmd">_tcl</b>, and copy the &quot;<b class="file">tclIndex.tcl</b>&quot; file
          595  +as well.</p></dd>
          596  +<dt><b class="cmd">_msg</b></dt>
          597  +<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory &quot;<b class="file">msgs</b>&quot;
          598  +as well.</p></dd>
          599  +<dt><b class="cmd">_doc</b></dt>
          600  +<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory
          601  +&quot;<b class="file">mpformats</b>&quot; as well.</p></dd>
          602  +<dt><b class="cmd">_tex</b></dt>
          603  +<dd><p>As <b class="cmd">_tcl</b>, and copy &quot;<b class="file">.tex</b>&quot; files as well.</p></dd>
          604  +</dl>
          605  +<p>The <i class="arg">doc-action</i> is responsible for installing the package
          606  +documentation. The system currently provides</p>
          607  +<dl class="doctools_definitions">
          608  +<dt><b class="cmd">_null</b></dt>
          609  +<dd><p>No documentation available, do nothing.</p></dd>
          610  +<dt><b class="cmd">_man</b></dt>
          611  +<dd><p>Process the &quot;<b class="file">.man</b>&quot; files found in
          612  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; and install the results (nroff and/or HTML)
          613  +in the proper location, as given to the installer.</p>
          614  +<p>This is actually a fallback, normally the installer uses the
          615  +pre-made formatted documentation found under &quot;<b class="file">idoc</b>&quot;.</p></dd>
          616  +</dl>
          617  +<p>The <i class="arg">example-action</i> is responsible for installing the
          618  +examples. The system currently provides</p>
          619  +<dl class="doctools_definitions">
          620  +<dt><b class="cmd">_null</b></dt>
          621  +<dd><p>No examples available, do nothing.</p></dd>
          622  +<dt><b class="cmd">_exa</b></dt>
          623  +<dd><p>Copy the the directory &quot;<b class="file">examples/<i class="arg">name</i></b>&quot;
          624  +recursively to the install location for examples.</p></dd>
          625  +</dl></dd>
          626  +<dt><a name="2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></dt>
          627  +<dd><p>Install the application with <i class="arg">name</i>, found in &quot;<b class="file">apps</b>&quot;.</p></dd>
          628  +<dt><a name="3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></dt>
          629  +<dd><p>This command signals to the installer which of the listed modules to
          630  +<em>not</em> install. I.e. they name the deprecated modules of Tcllib.</p></dd>
          631  +</dl>
          632  +<p>If, and only if the above actions are not suitable for the new
          633  +module then a second file has to be modified,
          634  +&quot;<b class="file">support/installation/actions.tcl</b>&quot;.</p>
          635  +<p>This file contains the implementations of the available
          636  +actions, and is the place where any custom action needed to handle the
          637  +special circumstances of module has to be added.</p>
   469    638   </div>
   470    639   </div>

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

   268    268   .\"	# MT - "empty" string
   269    269   .de MT
   270    270   .QW ""
   271    271   ..
   272    272   .BS
   273    273   .SH NAME
   274    274   tcllib_devguide \- Tcllib - The Developer's Guide
          275  +.SH SYNOPSIS
          276  +\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR
          277  +.sp
          278  +\fBApplication\fR \fIname\fR
          279  +.sp
          280  +\fBExclude\fR \fIname\fR
          281  +.sp
          282  +.BE
   275    283   .SH DESCRIPTION
   276    284   Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a
   277    285   package itself\&. It is a collection of (semi-independent) \fITcl\fR
   278    286   packages that provide utility functions useful to a large collection
   279    287   of Tcl programmers\&.
   280    288   .PP
   281    289   This document is a guide for developers working on Tcllib,
................................................................................
   647    655   or
   648    656   .CS
   649    657   
   650    658     \&./sak\&.tcl doc validate
   651    659   .CE
   652    660   to either check the packages of a specific module or check all of
   653    661   them\&.
   654         -x
   655    662   .SH "NOTES ON WRITING A TESTSUITE"
   656         -x
          663  +While previous sections talked about running the testsuites for a
          664  +module and the packages therein this has no meaning if the module in
          665  +question has no testsuites at all\&.
          666  +.PP
          667  +This section gives a very basic overview on possible
          668  +methodologies for writing tests and testsuites\&.
          669  +.PP
          670  +First there are "drudgery" tests\&. Written to check absolutely
          671  +basic assumptions which should never fail\&.
          672  +.PP
          673  +For example for a command FOO taking two arguments, three tests
          674  +calling it with zero, one, and three arguments\&. The basic checks that
          675  +the command fails if it has not enough arguments, or too many\&.
          676  +.PP
          677  +After that come the tests checking things based on our
          678  +knowledge of the command, about its properties and assumptions\&. Some
          679  +examples based on the graph operations added during Google's Summer of
          680  +Code 2009 are:
          681  +.IP \(bu
          682  +The BellmanFord command in struct::graph::ops takes a
          683  +\fIstartnode\fR as argument, and this node should be a node of
          684  +the graph\&. Equals one test case checking the behavior when the
          685  +specified node is not a node a graph\&.
          686  +.sp
          687  +This often gives rise to code in the implementation which
          688  +explicitly checks the assumption and throws a nice error\&.
          689  +Instead of letting the algorithm fails later in some weird
          690  +non-deterministic way\&.
          691  +.sp
          692  +It not always possible to do such checks\&. The graph argument
          693  +for example is just a command in itself, and while we expect
          694  +it to exhibit a certain interface, i\&.e\&. a set of sub-commands
          695  +aka methods, we cannot check that it has them, except by
          696  +actually trying to use them\&. That is done by the algorithm
          697  +anyway, so an explicit check is just overhead we can get by
          698  +without\&.
          699  +.IP \(bu
          700  +IIRC one of the distinguishing characteristic of either
          701  +BellmanFord and/or Johnson is that they are able to handle
          702  +negative weights\&. Whereas Dijkstra requires positive weights\&.
          703  +.sp
          704  +This induces (at least) three testcases \&.\&.\&. Graph with all
          705  +positive weights, all negative, and a mix of positive and
          706  +negative weights\&.
          707  +Thinking further does the algorithm handle the weight
          708  +\fB0\fR as well ? Another test case, or several, if we mix
          709  +zero with positive and negative weights\&.
          710  +.IP \(bu
          711  +The two algorithms we are currently thinking about are about
          712  +distances between nodes, and distance can be 'Inf'inity,
          713  +i\&.e\&. nodes may not be connected\&. This means that good test
          714  +cases are
          715  +.RS
          716  +.IP [1]
          717  +Strongly connected graph
          718  +.IP [2]
          719  +Connected graph
          720  +.IP [3]
          721  +Disconnected graph\&.
          722  +.RE
          723  +.sp
          724  +At the extremes of strongly connected and disconnected
          725  +we have the fully connected graphs and graphs without edges,
          726  +only nodes, i\&.e\&. completely disconnected\&.
          727  +.IP \(bu
          728  +IIRC both of the algorithms take weighted arcs, and fill in a
          729  +default if arcs are left unweighted in the input graph\&.
          730  +.sp
          731  +This also induces three test cases:
          732  +.RS
          733  +.IP [1]
          734  +Graph will all arcs with explicit weights\&.
          735  +.IP [2]
          736  +Graph without weights at all\&.
          737  +.IP [3]
          738  +Graph with mixture of weighted and unweighted graphs\&.
          739  +.RE
          740  +.PP
          741  +.PP
          742  +What was described above via examples is called
          743  +\fIblack-box\fR testing\&. Test cases are designed and written based on
          744  +the developer's knowledge of the properties of the algorithm and its
          745  +inputs, without referencing a particular implementation\&.
          746  +.PP
          747  +Going further, a complement to \fIblack-box\fR testing is
          748  +\fIwhite-box\fR\&. For this we know the implementation of the
          749  +algorithm, we look at it and design our tests cases so that they force
          750  +the code through all possible paths in the implementation\&. Wherever a
          751  +decision is made we have a test case forcing a specific direction of
          752  +the decision, for all possible combinations and directions\&. It is easy
          753  +to get a combinatorial explosion in the number of needed test-cases\&.
          754  +.PP
          755  +In practice I often hope that the black-box tests I have made
          756  +are enough to cover all the paths, obviating the need for white-box
          757  +tests\&.
          758  +.PP
          759  +The above should be enough to make it clear that writing tests
          760  +for an algorithm takes at least as much time as coding the algorithm,
          761  +and often more time\&. Much more time\&.
          762  +See for example also \fIhttp://sqlite\&.org/testing\&.html\fR, a writeup
          763  +on how the Sqlite database engine is tested\&.
          764  +.PP
          765  +An interesting connection is to documentation\&. In one
          766  +direction, the properties checked with black-box testing are exactly
          767  +the properties which should be documented in the algorithm's man
          768  +page\&. And conversely, the documentation of the properties of an
          769  +algorithm makes a good reference to base the black-box tests on\&.
          770  +.PP
          771  +In practice test cases and documentation often get written
          772  +together, cross-influencing each other\&. And the actual writing of test
          773  +cases is a mix of black and white box, possibly influencing the
          774  +implementation while writing the tests\&. Like writing a test for a
          775  +condition like \fIstartnode not in input graph\fR serving as
          776  +reminder to put a check for this condition into the code\&.
   657    777   .SH "INSTALLATION TOOLING"
   658         -x
          778  +A last thing to consider when adding a new package to the collection
          779  +is installation\&.
          780  +.PP
          781  +How to \fIuse\fR the tool, the "\fIinstaller\&.tcl\fR" script is
          782  +doumented in
          783  +\fITcllib - The Installer's Guide\fR\&.
          784  +.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,
          789  +"\fIsupport/installation/modules\&.tcl\fR" holding one command per module
          790  +and application to install\&.
          791  +.PP
          792  +The commands are:
          793  +.TP
          794  +\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR
          795  +Install the packages of module \fIname\fR, found in
          796  +"\fImodules/\fIname\fR\fR"\&.
          797  +.sp
          798  +The \fIcode-action\fR is responsible for installing the
          799  +packages and their index\&. The system currently provides
          800  +.RS
          801  +.TP
          802  +\fB_tcl\fR
          803  +Copy all "\fI\&.tcl\fR" files found in
          804  +"\fImodules/\fIname\fR\fR" into the installation\&.
          805  +.TP
          806  +\fB_tcr\fR
          807  +As \fB_tcl\fR, copy the "\fI\&.tcl\fR" files found in
          808  +the subdirectories of "\fImodules/\fIname\fR\fR" as well\&.
          809  +.TP
          810  +\fB_tci\fR
          811  +As \fB_tcl\fR, and copy the "\fItclIndex\&.tcl\fR" file
          812  +as well\&.
          813  +.TP
          814  +\fB_msg\fR
          815  +As \fB_tcl\fR, and copy the subdirectory "\fImsgs\fR"
          816  +as well\&.
          817  +.TP
          818  +\fB_doc\fR
          819  +As \fB_tcl\fR, and copy the subdirectory
          820  +"\fImpformats\fR" as well\&.
          821  +.TP
          822  +\fB_tex\fR
          823  +As \fB_tcl\fR, and copy "\fI\&.tex\fR" files as well\&.
          824  +.RE
          825  +.sp
          826  +The \fIdoc-action\fR is responsible for installing the package
          827  +documentation\&. The system currently provides
          828  +.RS
          829  +.TP
          830  +\fB_null\fR
          831  +No documentation available, do nothing\&.
          832  +.TP
          833  +\fB_man\fR
          834  +Process the "\fI\&.man\fR" files found in
          835  +"\fImodules/\fIname\fR\fR" and install the results (nroff and/or HTML)
          836  +in the proper location, as given to the installer\&.
          837  +.sp
          838  +This is actually a fallback, normally the installer uses the
          839  +pre-made formatted documentation found under "\fIidoc\fR"\&.
          840  +.RE
          841  +.sp
          842  +The \fIexample-action\fR is responsible for installing the
          843  +examples\&. The system currently provides
          844  +.RS
          845  +.TP
          846  +\fB_null\fR
          847  +No examples available, do nothing\&.
          848  +.TP
          849  +\fB_exa\fR
          850  +Copy the the directory "\fIexamples/\fIname\fR\fR"
          851  +recursively to the install location for examples\&.
          852  +.RE
          853  +.TP
          854  +\fBApplication\fR \fIname\fR
          855  +Install the application with \fIname\fR, found in "\fIapps\fR"\&.
          856  +.TP
          857  +\fBExclude\fR \fIname\fR
          858  +This command signals to the installer which of the listed modules to
          859  +\fInot\fR install\&. I\&.e\&. they name the deprecated modules of Tcllib\&.
          860  +.PP
          861  +.PP
          862  +If, and only if the above actions are not suitable for the new
          863  +module then a second file has to be modified,
          864  +"\fIsupport/installation/actions\&.tcl\fR"\&.
          865  +.PP
          866  +This file contains the implementations of the available
          867  +actions, and is the place where any custom action needed to handle the
          868  +special circumstances of module has to be added\&.

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

   109    109   <h1 class="doctools_title">tcllib_devguide(n) 1 tcllib &quot;&quot;</h1>
   110    110   <div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
   111    111   <p>tcllib_devguide - Tcllib - The Developer's Guide</p>
   112    112   </div>
   113    113   <div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
   114    114   <ul class="doctools_toc">
   115    115   <li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
          116  +<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
   116    117   <li class="doctools_section"><a href="#section1">Description</a></li>
   117    118   <li class="doctools_section"><a href="#section2">Commitments</a>
   118    119   <ul>
   119    120   <li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
   120    121   <li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
   121    122   </ul>
   122    123   </li>
................................................................................
   145    146   <li class="doctools_subsection"><a href="#subsection14">Available output formats, help</a></li>
   146    147   <li class="doctools_subsection"><a href="#subsection15">Validation without output</a></li>
   147    148   </ul>
   148    149   </li>
   149    150   <li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
   150    151   <li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
   151    152   </ul>
          153  +</div>
          154  +<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
          155  +<div class="doctools_synopsis">
          156  +<ul class="doctools_syntax">
          157  +<li><a href="#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></li>
          158  +<li><a href="#2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></li>
          159  +<li><a href="#3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></li>
          160  +</ul>
          161  +</div>
   152    162   </div>
   153    163   <div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
   154    164   <p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
   155    165   package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
   156    166   packages that provide utility functions useful to a large collection
   157    167   of Tcl programmers.</p>
   158    168   <p>This document is a guide for developers working on Tcllib,
................................................................................
   460    470   the tool to simply check that the documentation is syntactically
   461    471   correct, without generating actual output.</p>
   462    472   <p>Invoke it as either</p>
   463    473   <pre class="doctools_example">  ./sak.tcl doc validate (modules/)FOO </pre>
   464    474   <p>or</p>
   465    475   <pre class="doctools_example">  ./sak.tcl doc validate </pre>
   466    476   <p>to either check the packages of a specific module or check all of
   467         -them.
   468         -x</p>
          477  +them.</p>
   469    478   </div>
   470    479   </div>
   471    480   <div id="section7" class="doctools_section"><h2><a name="section7">Notes On Writing A Testsuite</a></h2>
   472         -<p>x</p>
          481  +<p>While previous sections talked about running the testsuites for a
          482  +module and the packages therein this has no meaning if the module in
          483  +question has no testsuites at all.</p>
          484  +<p>This section gives a very basic overview on possible
          485  +methodologies for writing tests and testsuites.</p>
          486  +<p>First there are &quot;drudgery&quot; tests. Written to check absolutely
          487  +basic assumptions which should never fail.</p>
          488  +<p>For example for a command FOO taking two arguments, three tests
          489  +calling it with zero, one, and three arguments. The basic checks that
          490  +the command fails if it has not enough arguments, or too many.</p>
          491  +<p>After that come the tests checking things based on our
          492  +knowledge of the command, about its properties and assumptions. Some
          493  +examples based on the graph operations added during Google's Summer of
          494  +Code 2009 are:</p>
          495  +<ul class="doctools_itemized">
          496  +<li><p>The BellmanFord command in struct::graph::ops takes a
          497  +	<i class="arg">startnode</i> as argument, and this node should be a node of
          498  +	the graph. Equals one test case checking the behavior when the
          499  +	specified node is not a node a graph.</p>
          500  +<p>This often gives rise to code in the implementation which
          501  +	explicitly checks the assumption and throws a nice error.
          502  +	Instead of letting the algorithm fails later in some weird
          503  +	non-deterministic way.</p>
          504  +<p>It not always possible to do such checks. The graph argument
          505  +	for example is just a command in itself, and while we expect
          506  +	it to exhibit a certain interface, i.e. a set of sub-commands
          507  +	aka methods, we cannot check that it has them, except by
          508  +	actually trying to use them. That is done by the algorithm
          509  +	anyway, so an explicit check is just overhead we can get by
          510  +	without.</p></li>
          511  +<li><p>IIRC one of the distinguishing characteristic of either
          512  +	BellmanFord and/or Johnson is that they are able to handle
          513  +	negative weights. Whereas Dijkstra requires positive weights.</p>
          514  +<p>This induces (at least) three testcases ... Graph with all
          515  +	positive weights, all negative, and a mix of positive and
          516  +	negative weights.
          517  +	Thinking further does the algorithm handle the weight
          518  +	<b class="const">0</b> as well ? Another test case, or several, if we mix
          519  +	zero with positive and negative weights.</p></li>
          520  +<li><p>The two algorithms we are currently thinking about are about
          521  +	distances between nodes, and distance can be 'Inf'inity,
          522  +	i.e. nodes may not be connected. This means that good test
          523  +	cases are</p>
          524  +<ol class="doctools_enumerated">
          525  +	
          526  +<li><p>Strongly connected graph</p></li>
          527  +<li><p>Connected graph</p></li>
          528  +<li><p>Disconnected graph.</p></li>
          529  +</ol>
          530  +<p>At the extremes of strongly connected and disconnected
          531  +	we have the fully connected graphs and graphs without edges,
          532  +	only nodes, i.e. completely disconnected.</p></li>
          533  +<li><p>IIRC both of the algorithms take weighted arcs, and fill in a
          534  +	default if arcs are left unweighted in the input graph.</p>
          535  +<p>This also induces three test cases:</p>
          536  +<ol class="doctools_enumerated">
          537  +	
          538  +<li><p>Graph will all arcs with explicit weights.</p></li>
          539  +<li><p>Graph without weights at all.</p></li>
          540  +<li><p>Graph with mixture of weighted and unweighted graphs.</p></li>
          541  +</ol>
          542  +</li>
          543  +</ul>
          544  +<p>What was described above via examples is called
          545  +<i class="term">black-box</i> testing. Test cases are designed and written based on
          546  +the developer's knowledge of the properties of the algorithm and its
          547  +inputs, without referencing a particular implementation.</p>
          548  +<p>Going further, a complement to <i class="term">black-box</i> testing is
          549  +<i class="term">white-box</i>. For this we know the implementation of the
          550  +algorithm, we look at it and design our tests cases so that they force
          551  +the code through all possible paths in the implementation. Wherever a
          552  +decision is made we have a test case forcing a specific direction of
          553  +the decision, for all possible combinations and directions. It is easy
          554  +to get a combinatorial explosion in the number of needed test-cases.</p>
          555  +<p>In practice I often hope that the black-box tests I have made
          556  +are enough to cover all the paths, obviating the need for white-box
          557  +tests.</p>
          558  +<p>The above should be enough to make it clear that writing tests
          559  +for an algorithm takes at least as much time as coding the algorithm,
          560  +and often more time. Much more time.
          561  +See for example also <a href="http://sqlite.org/testing.html">http://sqlite.org/testing.html</a>, a writeup
          562  +on how the Sqlite database engine is tested.</p>
          563  +<p>An interesting connection is to documentation. In one
          564  +direction, the properties checked with black-box testing are exactly
          565  +the properties which should be documented in the algorithm's man
          566  +page. And conversely, the documentation of the properties of an
          567  +algorithm makes a good reference to base the black-box tests on.</p>
          568  +<p>In practice test cases and documentation often get written
          569  +together, cross-influencing each other. And the actual writing of test
          570  +cases is a mix of black and white box, possibly influencing the
          571  +implementation while writing the tests. Like writing a test for a
          572  +condition like <i class="term">startnode not in input graph</i> serving as
          573  +reminder to put a check for this condition into the code.</p>
   473    574   </div>
   474    575   <div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>
   475         -<p>x</p>
          576  +<p>A last thing to consider when adding a new package to the collection
          577  +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,
          584  +&quot;<b class="file">support/installation/modules.tcl</b>&quot; holding one command per module
          585  +and application to install.</p>
          586  +<p>The commands are:</p>
          587  +<dl class="doctools_definitions">
          588  +<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  +<dd><p>Install the packages of module <i class="arg">name</i>, found in
          590  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot;.</p>
          591  +<p>The <i class="arg">code-action</i> is responsible for installing the
          592  +packages and their index. The system currently provides</p>
          593  +<dl class="doctools_definitions">
          594  +<dt><b class="cmd">_tcl</b></dt>
          595  +<dd><p>Copy all &quot;<b class="file">.tcl</b>&quot; files found in
          596  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; into the installation.</p></dd>
          597  +<dt><b class="cmd">_tcr</b></dt>
          598  +<dd><p>As <b class="cmd">_tcl</b>, copy the &quot;<b class="file">.tcl</b>&quot; files found in
          599  +the subdirectories of &quot;<b class="file">modules/<i class="arg">name</i></b>&quot; as well.</p></dd>
          600  +<dt><b class="cmd">_tci</b></dt>
          601  +<dd><p>As <b class="cmd">_tcl</b>, and copy the &quot;<b class="file">tclIndex.tcl</b>&quot; file
          602  +as well.</p></dd>
          603  +<dt><b class="cmd">_msg</b></dt>
          604  +<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory &quot;<b class="file">msgs</b>&quot;
          605  +as well.</p></dd>
          606  +<dt><b class="cmd">_doc</b></dt>
          607  +<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory
          608  +&quot;<b class="file">mpformats</b>&quot; as well.</p></dd>
          609  +<dt><b class="cmd">_tex</b></dt>
          610  +<dd><p>As <b class="cmd">_tcl</b>, and copy &quot;<b class="file">.tex</b>&quot; files as well.</p></dd>
          611  +</dl>
          612  +<p>The <i class="arg">doc-action</i> is responsible for installing the package
          613  +documentation. The system currently provides</p>
          614  +<dl class="doctools_definitions">
          615  +<dt><b class="cmd">_null</b></dt>
          616  +<dd><p>No documentation available, do nothing.</p></dd>
          617  +<dt><b class="cmd">_man</b></dt>
          618  +<dd><p>Process the &quot;<b class="file">.man</b>&quot; files found in
          619  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; and install the results (nroff and/or HTML)
          620  +in the proper location, as given to the installer.</p>
          621  +<p>This is actually a fallback, normally the installer uses the
          622  +pre-made formatted documentation found under &quot;<b class="file">idoc</b>&quot;.</p></dd>
          623  +</dl>
          624  +<p>The <i class="arg">example-action</i> is responsible for installing the
          625  +examples. The system currently provides</p>
          626  +<dl class="doctools_definitions">
          627  +<dt><b class="cmd">_null</b></dt>
          628  +<dd><p>No examples available, do nothing.</p></dd>
          629  +<dt><b class="cmd">_exa</b></dt>
          630  +<dd><p>Copy the the directory &quot;<b class="file">examples/<i class="arg">name</i></b>&quot;
          631  +recursively to the install location for examples.</p></dd>
          632  +</dl></dd>
          633  +<dt><a name="2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></dt>
          634  +<dd><p>Install the application with <i class="arg">name</i>, found in &quot;<b class="file">apps</b>&quot;.</p></dd>
          635  +<dt><a name="3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></dt>
          636  +<dd><p>This command signals to the installer which of the listed modules to
          637  +<em>not</em> install. I.e. they name the deprecated modules of Tcllib.</p></dd>
          638  +</dl>
          639  +<p>If, and only if the above actions are not suitable for the new
          640  +module then a second file has to be modified,
          641  +&quot;<b class="file">support/installation/actions.tcl</b>&quot;.</p>
          642  +<p>This file contains the implementations of the available
          643  +actions, and is the place where any custom action needed to handle the
          644  +special circumstances of module has to be added.</p>
   476    645   </div>
   477    646   </div></body></html>