Tcl Library Source Code

Check-in [6612c2b8a8]
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:Integrated the doc overhaul work into the trunk. This makes the various guides official.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 6612c2b8a881d7ddf7c4591b3f72b9d21c37616895f9127838c0a54129e02295
User & Date: aku 2019-05-07 01:21:28
References
2019-05-07
22:58 Closed ticket [f61f2e83a3]: no instructions for building tcllibc plus 6 other changes artifact: 6a8464b48c user: aku
Context
2019-05-07
19:05
Add two tests for the quasirandom packages; describe and test the estimates for the number of primes in an interval check-in: c2db185801 user: arjenmarkus tags: trunk
01:21
Integrated the doc overhaul work into the trunk. This makes the various guides official. check-in: 6612c2b8a8 user: aku tags: trunk
2019-05-06
23:53
Merged latest work from trunk Closed-Leaf check-in: c0006570ed user: aku tags: doc-overhaul
22:53
sha1: sha1, sha256 Bugfixes - (original commit, and now) Version bump. sha256 1.0.4 sha1 2.0.4 Fixed testsuite issues introduced by commit [aa67a2cdc0]. The switch from `rename` to `interp alias` to activate an implementation was not compensated for in the code doing the deactivation just a few lines higher. check-in: 885b50ec5e user: aku tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to .github/CONTRIBUTING.md.

     1      1   
     2         -Hello.
            2  +Hello. __Attention please__
     3      3   
     4      4   You are currently using the github __mirror__ of the Tcllib sources.
     5      5   
     6         -This is __not__ the location where development takes place.
            6  +This is __not__ the location where Tcllib development takes place.
     7      7   
     8         -We are not tracking issues entered here.  With the exception of the
            8  +We are __not tracking issues entered here__. With the exception of the
     9      9   maintainer of the mirroring setup nobody will even see such issues.
    10     10   
    11     11   Please go to the
    12         -[official location of the sources](https://core.tcl.tk/tcllib)
           12  +[official location of the sources](https://core.tcl-lang.org/tcllib)
    13     13   and enter your ticket into the
    14         -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist)
           14  +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
    15     15   instead.
    16     16   
    17     17   Thank you for your consideration.

Changes to .github/ISSUE_TEMPLATE.md.

     1      1   
     2         -Hello.
            2  +Hello. __Attention please__
     3      3   
     4      4   You are currently using the github __mirror__ of the Tcllib sources.
     5      5   
     6         -This is __not__ the location where development takes place.
            6  +This is __not__ the location where Tcllib development takes place.
     7      7   
     8         -We are not tracking issues entered here.  With the exception of the
            8  +We are __not tracking issues entered here__. With the exception of the
     9      9   maintainer of the mirroring setup nobody will even see such issues.
    10     10   
    11     11   Please go to the
    12         -[official location of the sources](https://core.tcl.tk/tcllib)
           12  +[official location of the sources](https://core.tcl-lang.org/tcllib)
    13     13   and enter your ticket into the
    14         -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist)
           14  +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
    15     15   instead.
    16     16   
    17     17   Thank you for your consideration.

Changes to .github/PULL_REQUEST_TEMPLATE.md.

     1      1   
     2         -Hello.
            2  +Hello. __Attention please__
     3      3   
     4      4   You are currently using the github __mirror__ of the Tcllib sources.
     5      5   
     6         -This is __not__ the location where development takes place.
            6  +This is __not__ the location where Tcllib development takes place.
     7      7   
     8         -We are not tracking issues entered here.  With the exception of the
            8  +We are __not tracking issues entered here__. With the exception of the
     9      9   maintainer of the mirroring setup nobody will even see such issues.
    10     10   
    11     11   Please go to the
    12         -[official location of the sources](https://core.tcl.tk/tcllib)
           12  +[official location of the sources](https://core.tcl-lang.org/tcllib)
    13     13   and enter your ticket into the
    14         -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist)
           14  +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
    15     15   instead.
    16     16   
    17     17   Thank you for your consideration.

Deleted INSTALL.txt.

     1         -How to install Tcllib
     2         -=====================
     3         -
     4         -Introduction
     5         -------------
     6         -
     7         -The tcllib distribution, whether a snapshot directly from CVS, or
     8         -officially released, offers a single method for installing tcllib,
     9         -based on Tcl itself.
    10         -
    11         -This is based on the assumption that for tcllib to be of use Tcl has
    12         -to be present, and therefore can be used.
    13         -
    14         -This single method however can be used in a variety of ways.
    15         -
    16         -0	For an unwrapped (= directory) distribution or CVS snapshot
    17         -
    18         -	a.	either call the application 'installer.tcl' directly,
    19         -	b	or use
    20         -
    21         -			% configure ; make install
    22         -
    23         -		The latter is provided for people which are used to
    24         -		this method and more comfortable with it. In end this
    25         -		boils down into a call of 'installer.tcl' too.
    26         -
    27         -1.	A starpack distribution (window-only) is a self-extracting
    28         -	installer which internally uses the aforementioned installer.
    29         -
    30         -2.	A starkit distribution is very much like a starpack, but
    31         -	required an external interpreyter to run. This can be any tcl
    32         -	interpreter which has all the packages to support starkits
    33         -	(tclvfs, memchan, trf).
    34         -
    35         -3.	A distribution in a tarball has to be unpacked first, then any
    36         -	of the methods described in (0) can be used.
    37         -
    38         -
    39         -Usage of the installer
    40         -----------------------
    41         -
    42         -The installer selects automatically either a gui based mode, or a
    43         -command line based mode. If the package Tk is present and can be
    44         -loaded, then the GUI mode is entered, else the system falls back to
    45         -the command line.
    46         -
    47         -Note that it is possible to specify options on the command line even
    48         -if the installer ultimatively selects a gui mode. In that case the
    49         -hardwired defaults and the options determine the data presented to the
    50         -user for editing.
    51         -
    52         -Command line help can be asked for by using the option -help when
    53         -running the installer (3) or the distribution itself in the case of
    54         -(1) or (2).
    55         -
    56         -The installer will select a number of defaults for the locations of
    57         -packages, examples, and documentation, and also the format of the
    58         -documentation. The user can overide these defaults in the GUI, or by
    59         -specifying additional options.
    60         -
    61         -The defaults depend on the platform detected (unix/windows) and the
    62         -executable used to run the installer. In the case of a starpack
    63         -distribution (1) this means that _no defaults_ are possible for the
    64         -various locations as the executable is part of the distribution and
    65         -has no knowledge of its environment.
    66         -
    67         -In all other cases the intepreter executable is outside of the
    68         -distribution, which means that its location can be used to determine
    69         -sensible defaults.
    70         -
    71         -Notes
    72         ------
    73         -
    74         -The installer will overwrite an existing installation of tcllib 1.6
    75         -without asking back after the initial confirmation is given. And if
    76         -the user chooses the same directory as for tcllib 1.4, or 1.3, etc.
    77         -then the installer will overwrite that too.

Deleted README.

     1         -RCS: @(#) $Id: README,v 1.9 2007/08/30 17:24:13 andreas_kupries Exp $
     2         -
     3         -Welcome to the Tcllib, the Tcl Standard Library.  This package is
     4         -intended to be a collection of Tcl packages that provide utility
     5         -functions useful to a large collection of Tcl programmers.
     6         -
     7         -The home web site for this code is http://core.tcl.tk/tcllib/ .
     8         -At this web site, you will find mailing lists, web forums, databases
     9         -for bug reports and feature requests, the CVS repository (browsable on
    10         -the web, or read-only accessible via CVS ), and more.
    11         -
    12         -The structure of the tcllib source hierarchy is:
    13         -
    14         -tcllib
    15         - +- modules
    16         -     +- <module1>
    17         -     +- <module2>
    18         -     +- ...
    19         -
    20         -
    21         -The install hierarchy is:
    22         -
    23         -.../lib/tcllib
    24         -        +- <module1>
    25         -        +- <module2>
    26         -        +- ...
    27         -
    28         -There are some base requirements that a module must meet before it
    29         -will be added to tcllib:
    30         -
    31         -* the module must be a proper Tcl package
    32         -* the module must use a namespace for its commands and variables
    33         -* the name of the package must be the same as the name of the
    34         -  namespace
    35         -* the module must reside in a subdirectory of the modules directory in
    36         -  the source hierarchy, and that subdirectory must have the same name
    37         -  as the package and namespace
    38         -* the module must be released under the BSD License, the terms of
    39         -  which can be found in the toplevel tcllib source directory in the file
    40         -  license.terms
    41         -* the module should have both documentation ([*]) and a test suite
    42         -  (in the form of a group of *.test files in the module directory).
    43         -
    44         -  [*] Possible forms: doctools, TMML/XML, nroff (man), or HTML.
    45         -      The first format is the most preferred as it can be processed with
    46         -      tools provided by tcllib itself (See module doctools). The first
    47         -      two are preferred in general as they are semantic markup and thus
    48         -      easier to convert into other formats.
    49         -
    50         -* the module must have either documentation or a test suite.  It can
    51         -  not have neither.
    52         -* the module should adhere to Tcl coding standards
    53         -
    54         -When adding a module to tcllib, be sure to add it to the files listed below.
    55         -
    56         -* installed_modules.tcl
    57         -
    58         -  contains a table listing all modules to be installed, modules
    59         -  excluded, and names the actions to be taken during installation
    60         -  of each module. Add a line to this table naming your module and
    61         -  its actions.
    62         -
    63         -  Three actions have to be specified, for the package itself, its
    64         -  documentation, and the examples demonstrating it.
    65         -
    66         -  The _null action can be used everywhere and signals that there is
    67         -  nothing to do. Although it is possible to use it for the package
    68         -  action it does make no sense there, as that means that no package
    69         -  code is installed.
    70         -
    71         -  Other package actions are _tcl, _tci, and _text. The first causes
    72         -  the installer to copy all .tcl files from the source directory for
    73         -  the module into the appropriate module directory. _tci does all that
    74         -  and also expects a tclIndex file to copy. _tex is like _tcl, however
    75         -  it also copies all .tex files found in the source directory for the
    76         -  module.
    77         -
    78         -  There is currently only one true documentation action. This action
    79         -  is _doc. It converts all documentation in doctools format into the
    80         -  format chosen by the user for installation and copies the result
    81         -  into the appropriate directory.
    82         -
    83         -  There is currently one true action for examples, _exa. It copies all
    84         -  files in the source directory for examples into the directory chosen
    85         -  by the user as destination for examples.
    86         -
    87         -Each module source directory should have no subdirectories (other than
    88         -the CVS directory), and should contain the following files:
    89         -
    90         -* source code		*.tcl
    91         -* package index		pkgIndex.tcl
    92         -* tests			*.test
    93         -* documentation		*.man, *.n, *.xml
    94         -
    95         -If you do not follow this directory structure, the tcllib Makefile
    96         -will fail to locate the files from the new module.

Changes to README.md.

     1         -
     2         -Hello.
            1  +# Attention
     3      2   
     4         -If you are reading this then you are very likely at the github
     5         -__mirror__ of the Tcllib sources.
            3  +:warning: 
            4  +This repository is mirrored to [github](https://github.com/tcltk/tcllib).
     6      5   
     7         -This means that the
     8         -[official location of the sources](https://core.tcl.tk/tcllib)
     9         -is somewhere else, just follow the link.
    10         -
    11         -This is also where our issue tracking is done.  We are not tracking
    12         -issues at github.  With the exeception of the maintainer of the
    13         -mirroring setup nobody will even see issues created at github.
            6  +We are __not tracking issues at github__.  With the exeception of the
            7  +maintainer of the mirroring setup nobody will even see issues created
            8  +at github.
    14      9   
    15     10   Please use the
    16         -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist)
           11  +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
    17     12   instead.
           13  +
           14  +# Welcome
           15  +
           16  +Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
           17  +package itself. It is a collection of (semi-independent) Tcl packages
           18  +that provide utility functions useful to a large collection of Tcl
           19  +programmers.
           20  +
           21  +At our [home site](http://core.tcl-lang.org/tcllib) you will find the
           22  +official fossil repository used to manage our sources, together with
           23  +the bug tracker. This is also the main location for releases to
           24  +download from.
           25  +
           26  +We have a
           27  +[secondary download location](https://sourceforge.net/projects/tcllib/files)
           28  +where the Tcllib sources were hosted in the past. SourceForge is also
           29  +where our [mailing lists](https://sourceforge.net/p/tcllib/mailman)
           30  +are (still) hosted.
           31  +
           32  +Another location to find these sources at is the
           33  +[github mirror](https://github.com/tcltk/tcllib).
           34  +
           35  +Please note the :warning: at the top.
           36  +
           37  +# Guides To Tcllib
           38  +
           39  +   * [Tcl Community - Kind Communication](embedded/www/tcllib/files/devdoc/tcl_community_communication.html)
           40  +   * [License](embedded/www/tcllib/files/devdoc/tcllib_license.html)
           41  +   * [How To Get The Sources](embedded/www/tcllib/files/devdoc/tcllib_sources.html)
           42  +   * [How To Build And Install Tcllib](embedded/www/tcllib/files/devdoc/tcllib_installer.html)
           43  +   * [The Developer's Guide](embedded/www/tcllib/files/devdoc/tcllib_devguide.html)
           44  +   * [The Release Manager's Guide](embedded/www/tcllib/files/devdoc/tcllib_releasemgr.html)

Deleted README.releasemgr.

     1         -RCS: @(#) $Id: README.releasemgr,v 1.2 2009/07/10 16:33:31 andreas_kupries Exp $
     2         -
     3         -Welcome to the tcllib, the Tcl Standard Library.
     4         -================================================
     5         -
     6         -Introduction
     7         -------------
     8         -
     9         -This README is intended to be a guide to the tools available to a
    10         -
    11         -	Release manager
    12         -
    13         -working on the creation of a release of Tcllib.
    14         -
    15         -Audience
    16         ---------
    17         -
    18         -The intended audience is the release manager of Tcllib, his deputies,
    19         -and anybody else interested in the task.
    20         -
    21         -Basics
    22         -------
    23         -
    24         -< Flesh this out >
    25         -
    26         -	sak.tcl validate
    27         -	sak.tcl test run
    28         -	sak.tcl review
    29         -	sak.tcl readme
    30         -	sak.tcl localdoc
    31         -	sak.tcl release (change to include rpmspec+gentip55+yml)
    32         -
    33         -< Tasks, and how to perform them >
    34         -
    35         -  	 Making a release (candidate) branch.
    36         -	 Readying the release in the branch.
    37         -	 Make the release official, merging the branch back.
    38         -
    39         -Uploading and releasing files
    40         ---------------------------------------------
    41         -
    42         -(1) Create a proper fossil event for the release, via
    43         -
    44         -      http://core.tcl.tk/tcllib/eventedit
    45         -
    46         -    See existing events (*) for a template
    47         -
    48         -    (Ad *) http://core.tcl.tk/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817
    49         -
    50         -(2) Update the following web locations
    51         -
    52         -    (a) Home page:	http://core.tcl.tk/tcllib/home
    53         -    (b) Downloads:	http://core.tcl.tk/tcllib/wiki?name=Downloads 
    54         -    (c) Past Releases:	http://core.tcl.tk/tcllib/wiki?name=Past+Releases
    55         -
    56         -    Admin access to the fossil repository required
    57         -
    58         -    (d) http://www.tcl.tk/home/release.txt
    59         -    (e) http://www.tcl.tk/software/tcllib/*.tml
    60         -
    61         -    ssh access to tcl.activestate.com
    62         -    aka        	  www.tcl.tk
    63         -    required.
    64         -
    65         -    (f) http://wiki.tcl.tk/1246

Changes to apps/dtplite.man.

   439    439   
   440    440   They are left in place, i.e. not deleted, to serve as demonstrations
   441    441   of doctoc and docidx markup.
   442    442   
   443    443   [list_end]
   444    444   
   445    445   [vset CATEGORY doctools]
   446         -[include ../modules/doctools2base/include/feedback.inc]
          446  +[include ../modules/common-text/feedback.inc]
   447    447   [manpage_end]

Changes to apps/nns.man.

   135    135   If this option is not specified it defaults to [const 38573]. It
   136    136   specifies the TCP port the name service to talk to is listening on for
   137    137   requests.
   138    138   
   139    139   [list_end]
   140    140   
   141    141   [vset CATEGORY nameserv]
   142         -[include ../modules/doctools2base/include/feedback.inc]
          142  +[include ../modules/common-text/feedback.inc]
   143    143   [manpage_end]

Changes to apps/nnsd.man.

    83     83   
    84     84   If this option is not specified it defaults to [const 38573]. It
    85     85   specifies the TCP port the server has to listen on for requests.
    86     86   
    87     87   [list_end]
    88     88   
    89     89   [vset CATEGORY nameserv]
    90         -[include ../modules/doctools2base/include/feedback.inc]
           90  +[include ../modules/common-text/feedback.inc]
    91     91   [manpage_end]

Changes to apps/nnslog.man.

    85     85   If this option is not specified it defaults to [const 38573]. It
    86     86   specifies the TCP port the name service to talk to is listening on for
    87     87   requests.
    88     88   
    89     89   [list_end]
    90     90   
    91     91   [vset CATEGORY nameserv]
    92         -[include ../modules/doctools2base/include/feedback.inc]
           92  +[include ../modules/common-text/feedback.inc]
    93     93   [manpage_end]

Changes to apps/page.man.

   459    459   [para]
   460    460   
   461    461   The contents of both environment variables and registry entries are
   462    462   interpreted as a list of paths, with the elements separated by either
   463    463   colon (Unix), or semicolon (Windows).
   464    464   
   465    465   [vset CATEGORY page]
   466         -[include ../modules/doctools2base/include/feedback.inc]
          466  +[include ../modules/common-text/feedback.inc]
   467    467   [manpage_end]

Changes to apps/tcldocstrip.man.

   189    189   Preambles, when active, are written before the actual content of a
   190    190   generated file. In the same manner postambles are, when active,
   191    191   written after the actual content of a generated file.
   192    192   
   193    193   [list_end]
   194    194   
   195    195   [vset CATEGORY docstrip]
   196         -[include ../modules/doctools2base/include/feedback.inc]
          196  +[include ../modules/common-text/feedback.inc]
   197    197   [manpage_end]

Name change from README.developer to devdoc/README.developer.


Deleted devdoc/cvs.branches.fig.

     1         -#FIG 3.2
     2         -Landscape
     3         -Center
     4         -Inches
     5         -Letter  
     6         -100.00
     7         -Single
     8         --2
     9         -1200 2
    10         -6 3000 2025 5400 2400
    11         -4 0 12 50 0 0 14 0.0000 4 150 2385 3000 2175 Point releases are branched\001
    12         -4 0 12 50 0 0 14 0.0000 4 150 1530 3000 2370 from RELEASES\001
    13         --6
    14         -6 2400 750 5700 1200
    15         -4 0 1 50 0 0 14 0.0000 4 195 3225 2400 900 Developer performs internal releases,\001
    16         -4 0 1 50 0 0 14 0.0000 4 195 3285 2400 1095 merging from HEAD into RELEASES\001
    17         --6
    18         -2 1 0 4 0 7 50 0 -1 0.000 0 0 7 1 0 2
    19         -	2 1 4.00 240.00 480.00
    20         -	 300 600 5700 600
    21         -2 1 0 2 1 7 50 0 -1 0.000 0 0 -1 1 0 2
    22         -	2 1 2.00 120.00 240.00
    23         -	 2100 600 2400 1800
    24         -2 1 0 5 12 7 50 0 -1 0.000 0 0 -1 1 0 3
    25         -	2 1 5.00 300.00 600.00
    26         -	 2700 1800 3000 3000 5700 3000
    27         -2 1 0 4 17 7 50 0 -1 0.000 0 0 7 1 0 3
    28         -	2 1 4.00 240.00 480.00
    29         -	 1200 600 1500 1800 5700 1800
    30         -4 0 0 50 0 0 14 0.0000 4 195 2835 3150 1575 Staging for release : RELEASES\001
    31         -4 0 0 50 0 0 14 0.0000 4 195 1905 3900 300 Development : HEAD\001
    32         -4 0 0 50 0 0 14 0.0000 4 150 930 4800 2700 Tcllib 1.2.0\001

Deleted devdoc/devguide.html.

     1         -<!- Guide for Tcllib developers -->
     2         -
     3         -<h1>Guide for Tcllib developers.
     4         -</h1>
     5         -<hr>
     6         -
     7         -<h2>CVS Repository
     8         -</h2>
     9         -<table><tr><td valign=top>
    10         -      <!-- The local source of this image is
    11         -		tcllib/devel/cvs.branches.*
    12         -	-->
    13         -      <img src="http://sourceforge.net/dbimage.php?id=2221">
    14         -</td><td valign=top><p>
    15         -
    16         -The CVS repository for Tcllib contains two main branches, the HEAD for
    17         -development, and RELEASES as the staging area for official
    18         -releases. At RELEASES the minor branches containing the various
    19         -official releases are anchored at.
    20         -</p></td></tr></table>
    21         -
    22         -<p>All the branches are of interest to the developers for
    23         -      Tcllib. Ongoing development happens in HEAD, which can be
    24         -      unstable or may not work at all. Whenever a developer considers
    25         -      a piece of code, or module, he is responsible for as
    26         -      sufficiently stable she has to perform an internal release which
    27         -      merges this part from HEAD into RELEASES. Tools to help with
    28         -      this will be provided.
    29         -</p>
    30         -
    31         -<p>The branches for the official releases of tcllib are of interest to
    32         -      a developer because it is expected that fixes for important bugs
    33         -      not only go into the HEAD branch but also into the release
    34         -      branches for the release they were found in and all releases
    35         -      following that one. This is to allow the release manager to
    36         -      create patch releases of existing releases distributing important
    37         -      bugfixes as well.
    38         -</p>
    39         -
    40         -<p>Version numbers for modules are handled as described below. This
    41         -      way of handling them was chosen so that the modules in the
    42         -      development branch always uses version numbers different from
    43         -      the version numbers in the official releases made so far.
    44         -</p>
    45         -<ul>
    46         -<li>Whenever an internal release of a module FOO is done, the
    47         -	developer performing this internal release has to increment
    48         -	the version number of the module <b>after</b> the release was
    49         -	executed.
    50         -</ul>

Deleted devdoc/installation.txt.

     1         -Tcllib installation directory layout
     2         -====================================
     3         -
     4         -This document describes the possible layouts for an installed tcllib,
     5         -discusses their pro and contra and makes a choice for Tcllib 1.4. A
     6         -roadmap of changes in the future is made available as appendix.
     7         -
     8         -[L1/D] Deep layout
     9         -------------------
    10         -
    11         -	This is the layout of Tcllib 1.3 (and versions before that).
    12         -
    13         -	A single directory tcllib<version> is created, and all
    14         -	subdirectories of the 'modules' subdirectory in the
    15         -	distribution is copied into it. This is restricted at large to
    16         -	*.tcl files, with exception made for some modules with special
    17         -	needs.
    18         -
    19         -	Pro:
    20         -	Contra:
    21         -		Makes the handling of the various package indices,
    22         -		well, not difficult, but uncomfortable.
    23         -
    24         -
    25         -[L2/Fa] Flat layout 1
    26         ----------------------
    27         -
    28         -	A directory is created for each module of tcllib.
    29         -
    30         -	Pro:
    31         -		Handling of package indices is easier than for L1/D, a
    32         -		toplevel index file with all its problems is not
    33         -		required anymore.
    34         -
    35         -	Contra:
    36         -		Directories should be versioned to avoid conflicts
    37         -		between multiple releases. modules have no
    38         -		version. This can be faked for modules containing one
    39         -		package, but not for the modules with more.
    40         -
    41         -
    42         -[L2/Fb] Flat layout 2
    43         ----------------------
    44         -
    45         -	A directory is created for each package in tcllib.
    46         -
    47         -	Pro
    48         -		Handling of package indices is easy, one per package.
    49         -
    50         -	Contra:
    51         -		Modules containing more than one package are difficult
    52         -		to handle. The system has to split them into the
    53         -		individual packages. This rendered very difficult
    54         -		because of shared package index files.
    55         -	
    56         -		This can be solved by moving tcllib (back) towards of
    57         -		one package per module. When that goal is reached
    58         -		L2/Fa and L2/Fb become the same, and the contra for
    59         -		L2/Fa vanishes too as an exact version number can be
    60         -		associated with each directory.
    61         -
    62         -Chosen layout for Tcllib 1.4
    63         -----------------------------
    64         -
    65         -	L2/D
    66         -
    67         -	Despite the problems with package indices the contras against
    68         -	the flat structures are too strong at this point in
    69         -	time. Automatic solutions are not really possible, or require
    70         -	a very high effort.
    71         -
    72         -Roadmap
    73         --------
    74         -	Change the module directories of tcllib to contain exactly one
    75         -	package per directory, with appropriate index (and meta data).
    76         -
    77         -	This not only makes sense for easier handling of installation
    78         -	and package indices, but also in the greater context of
    79         -	wrapping code for deployment.
    80         -
    81         -
    82         ------------------------------------
    83         -This document is in the public domain.
    84         -
    85         -			Andreas Kupries	<[email protected]>

Added devdoc/parts/b_critcl.inc.

            1  +
            2  +While the majority of Tcllib consists of packages written in pure Tcl
            3  +a number of packages also have [term accelerators] associated with them.
            4  +
            5  +These are [syscmd critcl]-based C packages whose use will boost the
            6  +performance of the packages using them.
            7  +
            8  +These accelerators are optional, and they are not installed by
            9  +default.
           10  +
           11  +[para] To build the accelerators the normally optional dependency on
           12  +       [syscmd critcl] becomes required.
           13  +
           14  +[para] To build and install Tcllib with the accelerators in a
           15  +       Unix-like environment invoke:
           16  +
           17  +[example {
           18  +  ./configure
           19  +  make critcl # This builds the shared library holding
           20  +              # the accelerators
           21  +  make install
           22  +}]
           23  +
           24  +[para] The underlying tool is [file sak.tcl] in the toplevel directory
           25  +of Tcllib and the command [cmd {make critcl}] is just a wrapper around
           26  +
           27  +[example {
           28  +  ./sak.tcl critcl
           29  +}]
           30  +
           31  +[para] Therefore in a Windows environment instead invoke
           32  +
           33  +[example {
           34  +  ./sak.tcl critcl
           35  +  ./installer.tcl
           36  +}]
           37  +
           38  +from within a DOS window, i.e. [syscmd cmd.exe].

Added devdoc/parts/b_tooling.inc.

            1  +
            2  +The core of Tcllib's build system is the script [file installer.tcl]
            3  +found in the toplevel directory of a checkout or release.
            4  +
            5  +[para] The
            6  +       [example {
            7  +         configure ; make install
            8  +       }]
            9  +       setup available to
           10  +       developers on Unix-like systems is just a wrapper around it.
           11  +
           12  +       To go beyond the standard embodied in the wrapper it is
           13  +       necessary to directly invoke this script.
           14  +
           15  +[para] On Windows system using it directly is the only way to invoke
           16  +       it.
           17  +
           18  +[para] For basic help invoke it as
           19  +
           20  +       [example {
           21  +         ./installer.tcl -help
           22  +       }]
           23  +
           24  +       This will print a short list of all the available options to
           25  +       the standard output channel.
           26  +
           27  +[para] The commands associated with the various [term install] targets
           28  +       in the [term Makefile.in] for Unix can be used as additional
           29  +       examples on how to use this tool as well.
           30  +
           31  +[para] The installer can operate in GUI and CLI modes.
           32  +
           33  +       By default it chooses the mode automatically, based on if the
           34  +       Tcl package [package Tk] can be used or not.
           35  +
           36  +       The option [option -no-gui] can be used to force CLI mode.
           37  +
           38  +[para] Note that it is possible to specify options on the command line
           39  +       even if the installer ultimatively selects GUI mode. In that
           40  +       case the hardwired defaults and the options determine the data
           41  +       presented to the user for editing.
           42  +
           43  +[para] The installer will select a number of defaults for the
           44  +       locations of packages, examples, and documentation, and also
           45  +       the format of the documentation. The user can overide these
           46  +       defaults in the GUI, or by specifying additional options.
           47  +
           48  +       The defaults depend on the platform detected (Unix/Windows) and
           49  +       on the [syscmd tclsh] executable used to run the installer.
           50  +
           51  +[para][emph Options]
           52  +
           53  +[list_begin options]
           54  +[opt_def -help]
           55  +
           56  +Show the list of options explained here on the standard output channel
           57  +and exit.
           58  +
           59  +[opt_def +excluded]
           60  +
           61  +Include deprecated packages in the installation.
           62  +
           63  +[opt_def -no-gui]
           64  +
           65  +Force command line operation of the installer
           66  +
           67  +[opt_def -no-wait]
           68  +
           69  +In CLI mode the installer will by default ask the user to confirm that
           70  +the chosen configuration (destination paths, things to install) is
           71  +correct before performing any action. Using this option causes the
           72  +installer to skip this query and immediately jump to installation.
           73  +
           74  +[opt_def -app-path [arg path]]
           75  +[opt_def -example-path [arg path]]
           76  +[opt_def -html-path [arg path]]
           77  +[opt_def -nroff-path [arg path]]
           78  +[opt_def -pkg-path [arg path]]
           79  +
           80  +Declare the destination paths for the applications, examples, html
           81  +documentation, nroff manpages, and packages. The defaults are derived
           82  +from the location of the [syscmd tclsh] used to run the installer.
           83  +
           84  +[opt_def -dry-run]
           85  +[opt_def -simulate]
           86  +
           87  +Run the installer without modifying the destination directories.
           88  +
           89  +[opt_def -apps]
           90  +[opt_def -no-apps]
           91  +[opt_def -examples]
           92  +[opt_def -no-examples]
           93  +[opt_def -pkgs]
           94  +[opt_def -no-pkgs]
           95  +[opt_def -html]
           96  +[opt_def -no-html]
           97  +[opt_def -nroff]
           98  +[opt_def -no-nroff]
           99  +
          100  +(De)activate the installation of applications, examples, packages,
          101  +html documentation, and nroff manpages.
          102  +
          103  +[para] Applications, examples, and packages are installed by default.
          104  +
          105  +[para] On Windows the html documentation is installed by default.
          106  +
          107  +[para] On Unix the nroff manpages are installed by default.
          108  +
          109  +[list_end]

Added devdoc/parts/b_unix.inc.

            1  +
            2  +For [term Unix]-like environments Tcllib comes with the standard set
            3  +of files to make
            4  +
            5  +[example {
            6  +  ./configure
            7  +  make install
            8  +}]
            9  +
           10  +a suitable way of installing it.
           11  +
           12  +This is a standard non-interactive install automatically figuring out
           13  +where to place everything, i.e. packages, applications, and the
           14  +manpages.
           15  +
           16  +[para] To get a graphical installer invoke
           17  +
           18  +[example {
           19  +  ./installer.tcl
           20  +}]
           21  +
           22  +instead.

Added devdoc/parts/b_windows.inc.

            1  +
            2  +In a Windows environment we have the [cmd installer.tcl] script to
            3  +perform installation.
            4  +
            5  +[para] If the desired [syscmd tclsh] is associated [file .tcl] files
            6  +       then double-clicking / opening the [cmd installer.tcl] is
            7  +       enough to invoke it in graphical mode.
            8  +
            9  +       This assumes that [term Tk] is installed and available as well.
           10  +
           11  +[para] Without [term Tk] the only way to invoke the installer are to
           12  +       open a DOS window, i.e. [syscmd cmd.exe], and then to invoke
           13  +      
           14  +[example {
           15  +  ./installer.tcl
           16  +}]
           17  +
           18  +inside it.

Added devdoc/parts/d_bf_branchcmds.inc.

            1  +
            2  +In the hope of engendering good work practices now a few example
            3  +operations which will come up with branches, and their associated
            4  +fossil command (sequences).
            5  +
            6  +[list_begin definitions]
            7  +
            8  +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
            9  +[def [emph Awareness]]
           10  +[include d_op_aware.inc]
           11  +
           12  +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
           13  +[def [emph {Clean checkouts}]]
           14  +[include d_op_clean.inc]
           15  +
           16  +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
           17  +[def [emph {Starting a new branch}]]
           18  +[include d_op_branch_open.inc]
           19  +
           20  +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
           21  +[def [emph {Merging a branch into trunk}]]
           22  +[include d_op_branch_close.inc]
           23  +
           24  +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
           25  +[def [emph {Merging from trunk}]]
           26  +[include d_op_branch_import.inc]
           27  +
           28  +[list_end]
           29  +

Added devdoc/parts/d_bf_branches.inc.

            1  +
            2  +Given the constraints placed on the [term trunk] branch of the
            3  +repository it is (strongly) recommended to perform any development
            4  +going beyond trivial changes on a non-trunk branch.
            5  +
            6  +[para] Outside of the trunk developers are allowed to commit
            7  +       intermediate broken states of their work.
            8  +
            9  +       Only at the end of a development cycle, when the relevant
           10  +       branch is considered ready for merging, will it be necessary to
           11  +       perform full the set of validations ensuring that the merge to
           12  +       come will create a good commit on trunk.
           13  +
           14  +[para] Note that while a review from a second developer is not a
           15  +       required condition for merging a branch it is recommended to
           16  +       seek out such an independent opinion as a means of
           17  +       cross-checking the work.
           18  +
           19  +[para] It also recommended to give any new branch a name which aids in
           20  +       determining additional details about it. Examples of good
           21  +       things to stick into a branch name would be
           22  +
           23  +[list_begin itemized]
           24  +[item]	Developer (nick)name
           25  +[item]	Ticket hash/reference
           26  +[item]	One or two keywords applicable to the work
           27  +[item]	...
           28  +[list_end]
           29  +
           30  +[para] Further, while most development branches are likely quite
           31  +       short-lived, no prohibitions exist against making longer-lived
           32  +       branches.
           33  +
           34  +       Creators should however be mindful that the longer such a
           35  +       branch exists without merges the more divergent they will tend
           36  +       to be, with an associated increase in the effort which will
           37  +       have to be spent on either merging from and merging to trunk.

Added devdoc/parts/d_bf_dependencies.inc.

            1  +
            2  +Regarding packages and dependencies between them Tcllib occupies a
            3  +middle position between two extremes:
            4  +
            5  +[list_begin enumerated]
            6  +
            7  +[enum] On one side a strongly interdependent set of packages, usually
            8  +       by a single author, for a single project. Looking at my
            9  +       (Andreas Kupries) own work examples of such are
           10  +       [uri https://core.tcl.tk/akupries/marpa/index Marpa],
           11  +       [uri https://core.tcl.tk/akupries/crimp/index CRIMP],
           12  +       [uri https://core.tcl.tk/akupries/kinetcl/index Kinetcl], etc.
           13  +
           14  +[para] For every change the author of the project handles all the
           15  +       modifications cascading from any incompatibilities it
           16  +       introduced to the system.
           17  +
           18  +[enum] On the other side, the world of semi-independent projects by
           19  +       many different authors where authors know what packages their
           20  +       own creations depend on, yet usually do not know who else
           21  +       depends on them.
           22  +
           23  +[para] The best thing an author making an (incompatible) change to
           24  +       their project can do is to for one announce such changes in
           25  +       some way, and for two use versioning to distinguish the code
           26  +       before and after the change.
           27  +
           28  +[para] The world is then responsible for adapting, be it by updating
           29  +       their own projects to the new version, or by sticking to the
           30  +       old.
           31  +
           32  +[list_end]
           33  +
           34  +As mentioned already, Tcllib lives in the middle of that.
           35  +
           36  +[para] While we as maintainers cannot be aware of all users of
           37  +       Tcllib's packages, and thus have to rely on the mechanisms
           38  +       touched on in point 2 above for that, the dependencies between
           39  +       the packages contained in Tcllib are a different matter.
           40  +
           41  +[para] As we are collectively responsible for the usability of Tcllib
           42  +       in toto to the outside world, it behooves us to be individually
           43  +       mindful even of Tcllib packages we are not directly
           44  +       maintaining, when they depend on packages under our
           45  +       maintainership.
           46  +
           47  +       This may be as simple as coordinating with the maintainers of
           48  +       the affected packages.
           49  +
           50  +       It may also require us to choose how to adapt affected packages
           51  +       which do not have maintainers, i.e. modify them to use our
           52  +       changed package properly, or modify them to properly depend on
           53  +       the unchanged version of our package.
           54  +
           55  +[para] Note that the above is not only a chore but an opportunity as
           56  +       well.
           57  +
           58  +       Additional insight can be had by forcing ourselves to look at
           59  +       our package and the planned change(s) from an outside
           60  +       perspective, to consider the ramifications of our actions on
           61  +       others in general, and on dependent packages in particular.

Added devdoc/parts/d_bf_trunk.inc.

            1  +
            2  +The management and use of branches is an important part of working
            3  +with a [term {Distributed Version Control System}] ([term DVCS]) like
            4  +[uri https://www.fossil-scm.org/ fossil].
            5  +
            6  +[para] For Tcllib the main branch of the collection is
            7  +       [term trunk]. In [term git] this branch would be called
            8  +       [term master], and this is exactly the case in the
            9  +       [uri https://github.com/tcltk/tcllib/ {github mirror}] of
           10  +       Tcllib.
           11  +
           12  +[para] To properly support debugging [emph {each commit}] on this
           13  +       branch [emph {has to pass the entire testsuite}] of the
           14  +       collection. Using bisection to determine when an issue appeared
           15  +       is an example of an action made easier by this constraint.
           16  +
           17  +[para] This is part of our collective responsibility for the usability
           18  +       of Tcllib in toto to the outside world.
           19  +
           20  +       As [term fossil] has no mechanism to enforce this condition
           21  +       this is handled on the honor system for developers and maintainers.
           22  +
           23  +[para] To make the task easier Tcllib comes with a tool
           24  +       ([file sak.tcl]) providing a number of commands in
           25  +       support. These commands are explained in the following sections
           26  +       of this guide.
           27  +
           28  +[para] While it is possible and allowed to commit directly to trunk
           29  +       remember the above constraint regarding the testsuite, and the
           30  +       coming notes about other possible issues with a commit.

Added devdoc/parts/d_bf_versions.inc.

            1  +In Tcllib all changes to a package have to come with an increment of
            2  +its version number. What part is incremented (patchlevel, minor, major
            3  +version) depends on the kind of change made. With multiple changes in
            4  +a commit the highest "wins".
            5  +
            6  +[para] When working in a development branch the version change can be
            7  +       deferred until it is time to merge, and then has to cover all
            8  +       the changes in the branch.
            9  +
           10  +[para] Below a list of the kinds of changes and their associated
           11  +       version increments:
           12  +
           13  +[list_begin definitions]
           14  +[def [term {D - documentation}]] No increment
           15  +[def [term {T - testsuite}]] No increment
           16  +[def [term {B - bugfix}]] Patchlevel
           17  +[def [term {I - implementation tweak}]] Patchlevel
           18  +[def [term {P - performance tweak}]] Patchlevel
           19  +[def [term {E - backward-compatible extension}]] Minor
           20  +[def [term {API - incompatible change}]] Major
           21  +[list_end]
           22  +
           23  +[para] Note that a commit containing a version increment has to
           24  +       mention the new version number in its commit message, as well
           25  +       as the kind of change which caused it.
           26  +
           27  +[para] Note further that the version number of a package currently
           28  +       exists in three places. An increment has to update all of them:
           29  +
           30  +[list_begin enumerated]
           31  +[enum] The package implementation.
           32  +[enum] The package index ([file pkgIndex.tcl])
           33  +[enum] The package documentation.
           34  +[list_end]
           35  +
           36  +[para] The [file sak.tcl] command [cmd {validate version}] helps
           37  +       finding discrepancies between the first two.
           38  +
           39  +       All the other [cmd validate] methods are also of interest to
           40  +       any developer. Invoke it with
           41  +
           42  +       [example { sak.tcl help validate }]
           43  +
           44  +       to see their documentation.

Added devdoc/parts/d_branchflow.inc.

            1  +[comment {===================================================================}]
            2  +[subsection {Package Dependencies}]
            3  +[include d_bf_dependencies.inc]
            4  +
            5  +[comment {===================================================================}]
            6  +[subsection Trunk]
            7  +[include d_bf_trunk.inc]
            8  +
            9  +[comment {===================================================================}]
           10  +[subsection Branches]
           11  +[include d_bf_branches.inc]
           12  +
           13  +[comment {===================================================================}]
           14  +[subsection {Working with Branches}]
           15  +[include d_bf_branchcmds.inc]
           16  +
           17  +[comment {===================================================================}]
           18  +[subsection {Version numbers}]
           19  +[include d_bf_versions.inc]

Added devdoc/parts/d_contrib.inc.

            1  +
            2  +As a contributor to Tcllib you are committing yourself to:
            3  +
            4  +[list_begin enumerated]
            5  +
            6  +[enum] keep the guidelines written down in
            7  +       [term {Tcl Community - Kind Communication}] in your mind.
            8  +       The main point to take away from there is
            9  +       [emph {to be kind to each other}].
           10  +
           11  +[enum] Your contributions getting distributed under a BSD/MIT license.
           12  +       For the details see [term {Tcllib - License}]
           13  +
           14  +[list_end]
           15  +
           16  +Contributions are made by entering tickets into our tracker, providing
           17  +patches, bundles or branches of code for inclusion, or posting to the
           18  +Tcllib related mailing lists.

Added devdoc/parts/d_dirlayout.inc.

            1  +
            2  +[subsection {Main Directories}]
            3  +
            4  +The main directories in the Tcllib toplevel directory and of interest
            5  +to a developer are:
            6  +
            7  +[list_begin definitions]
            8  +
            9  +[def [file modules]]
           10  +
           11  +Each child directory represents one or more packages.
           12  +
           13  +In the case of the latter the packages are usually related in some
           14  +way. Examples are [file base64], [file math], and [file struct], with
           15  +loose (base64) to strong (math) relations between the packages in the
           16  +directory.
           17  +
           18  +[def [file apps]]
           19  +
           20  +This directory contains all the installable applications, with their
           21  +documentation. Note that this directory is currently [emph not] split
           22  +into sub-directories.
           23  +
           24  +[def [file examples]]
           25  +
           26  +Each child directory [file foo] contains one or more example
           27  +application for the packages in [file modules/foo]. These examples are
           28  +generally not polished enough to be considered for installation.
           29  +
           30  +[list_end]
           31  +
           32  +[subsection {More Directories}]
           33  +
           34  +[list_begin definitions]
           35  +
           36  +[def [file config]]
           37  +
           38  +This directory contains files supporting the Unix build system,
           39  +i.e. [file configure] and [file Makefile.in].
           40  +
           41  +[def [file devdoc]]
           42  +
           43  +This directories contains the doctools sources for the global
           44  +documentation, like this document and its sibling guides.
           45  +
           46  +[def [file embedded]]
           47  +
           48  +This directory contains the entire documentation formatted for
           49  +[term HTML] and styled to properly mix into the web site generated by
           50  +fossil for the repository.
           51  +
           52  +[para] This is the documentation accessible from the Tcllib home
           53  +directory, represented in the repository as [file embedded/index.md].
           54  +
           55  +[def [file idoc]]
           56  +
           57  +This directory contains the entire documentation formatted for
           58  +[term nroff] and [term HTML], the latter without any styling.
           59  +This is the documentation which will be installed.
           60  +
           61  +[def [file support]]
           62  +
           63  +This directory contains the sources of internal packages and utilities
           64  +used in the implementation of the [file installer.tcl] and
           65  +[file sak.tcl] scripts/tools.
           66  +
           67  +[list_end]
           68  +
           69  +[subsection {Top Files}]
           70  +
           71  +[list_begin definitions]
           72  +[def [file aclocal.m4]]
           73  +[def [file configure]]
           74  +[def [file configure.in]]
           75  +[def [file Makefile.in]]
           76  +
           77  +These four files comprise the Unix build system layered on top of the
           78  +[file installer.tcl] script.
           79  +
           80  +[def [file installer.tcl]]
           81  +
           82  +The Tcl-based installation script/tool.
           83  +
           84  +[def [file project.shed]]
           85  +
           86  +Configuration file for [term {Sean Wood}]'s [syscmd PracTcl]
           87  +buildsystem.
           88  +
           89  +[def [file sak.tcl]]
           90  +This is the main tool for developers and release managers, the
           91  +[term {Swiss Army Knife}] of management operations on the collection.
           92  +
           93  +[def [file ChangeLog]]
           94  +
           95  +The log of changes to the global support, when the sources were held
           96  +in [term CVS]. Not relevant any longer with the switch to the
           97  +[term fossil] SCM.
           98  +
           99  +[def [file license.terms]]
          100  +
          101  +The license in plain ASCII. See also [term {Tcllib - License}] for the
          102  +nicely formatted form. The text is identical.
          103  +
          104  +[def [file README.md]]
          105  +[def [file .github/CONTRIBUTING.md]]
          106  +[def [file .github/ISSUE_TEMPLATE.md]]
          107  +[def [file .github/PULL_REQUEST_TEMPLATE.md]]
          108  +
          109  +These markdown-formatted documents are used and shown by the github
          110  +mirror of these sources, pointing people back to the official location
          111  +and issue trackers.
          112  +
          113  +[def [file DESCRIPTION.txt]]
          114  +[def [file STATUS]]
          115  +[def [file tcllib.spec]]
          116  +[def [file tcllib.tap]]
          117  +[def [file tcllib.yml]]
          118  +
          119  +????
          120  +
          121  +[list_end]
          122  +
          123  +[subsection {File Types}]
          124  +
          125  +The most common file types, by file extension, are:
          126  +
          127  +[list_begin definitions]
          128  +
          129  +[def [file .tcl]]
          130  +Tcl code for a package, application, or example.
          131  +
          132  +[def [file .man]]
          133  +Doctools-formatted documentation, usually for a package.
          134  +
          135  +[def [file .test]]
          136  +Test suite for a package, or part of.
          137  +Based on [package tcltest].
          138  +
          139  +[def [file .bench]]
          140  +Performance benchmarks for a package, or part of.
          141  +Based on [file modules/bench].
          142  +
          143  +[def [file .pcx]]
          144  +Syntax rules for [term TclDevKit]'s [syscmd tclchecker]. Using these
          145  +rules allows the checker to validate the use of commands of a Tcllib
          146  +package [package foo] without having to scan the [file .tcl] files
          147  +implementing it.
          148  +
          149  +[list_end]

Added devdoc/parts/d_documentation.inc.

            1  +
            2  +The standard format used for documentation of packages and other
            3  +things in Tcllib is [term doctools].
            4  +
            5  +Its supporting packages are a part of Tcllib, see the directories
            6  +[file modules/doctools] and [file modules/dtplite]. The latter is
            7  +an application package, with the actual application
            8  +[file apps/dtplite] a light wrapper around it.
            9  +
           10  +[para] Tcllib developers gain access to these through the [cmd doc]
           11  +method of the [file sak.tcl] tool, another (internal) wrapper around
           12  +the [file modules/dtplite] application package.
           13  +
           14  +[comment {===================================================================}]
           15  +[subsection {Generate documentation for a specific module}]
           16  +
           17  +Invoke either
           18  +
           19  +[example {  ./sak.tcl doc html foo }]
           20  +
           21  +or
           22  +
           23  +[example {  ./sak.tcl doc html modules/foo }]
           24  +
           25  +to generate HTML for the documentation found in the module [file foo].
           26  +
           27  +Instead of [const html] any other supported format can be used here,
           28  +of course.
           29  +
           30  +[para] The generated formatted documentation will be placed into a
           31  +directory [file doc] in the current working directory.
           32  +
           33  +[comment {===================================================================}]
           34  +[subsection {Generate documentation for all modules}]
           35  +
           36  +Invoke the tool without a module name, i.e.
           37  +
           38  +[example {  ./sak.tcl doc html }]
           39  +
           40  +to generate HTML for the documentation found in all modules.
           41  +
           42  +Instead of [const html] any other supported format can be used here,
           43  +of course.
           44  +
           45  +[para] The generated formatted documentation will be placed into a
           46  +directory [file doc] in the current working directory.
           47  +
           48  +[comment {===================================================================}]
           49  +[subsection {Available output formats, help}]
           50  +
           51  +Invoke the tool as
           52  +
           53  +[example {  ./sak.tcl help doc }]
           54  +
           55  +to see the entire set of supported output formats which can be
           56  +generated.
           57  +
           58  +[comment {===================================================================}]
           59  +[subsection {Validation without output}]
           60  +
           61  +Note the special format [const validate].
           62  +
           63  +[para] Using this value as the name of the format to generate forces
           64  +the tool to simply check that the documentation is syntactically
           65  +correct, without generating actual output.
           66  +
           67  +[para] Invoke it as either
           68  +
           69  +[example {  ./sak.tcl doc validate (modules/)foo }]
           70  +
           71  +or
           72  +
           73  +[example {  ./sak.tcl doc validate }]
           74  +
           75  +to either check the packages of a specific module or check all of
           76  +them.

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

Added devdoc/parts/d_maintain.inc.

            1  +
            2  +When contributing one or more packages for full inclusion into Tcllib
            3  +you are committing yourself to
            4  +
            5  +[list_begin enumerated]
            6  +
            7  +[enum] Keep the guidelines written down in
            8  +       [term {Tcl Community - Kind Communication}]
            9  +       (as any contributor) in your mind. The main point to take away
           10  +       from there is [emph {to be kind to each other}].
           11  +
           12  +[enum] Your packages getting distributed under a BSD/MIT license.  For
           13  +       the details see [term {Tcllib - License}]
           14  +
           15  +[enum] Maintenance of the new packages for a period of two years under
           16  +       the following rules, and responsibilities:
           17  +
           18  +       [list_begin enumerated]
           19  +
           20  +       [enum] A maintainer may step down after the mandatory period as
           21  +       	      they see fit.
           22  +
           23  +       [enum] A maintainer may step down before the end of the
           24  +      	      mandatory period, under the condition that a replacement
           25  +      	      maintainer is immediately available and has agreed to
           26  +      	      serve the remainder of the period, plus their own
           27  +      	      mandatory period (see below).
           28  +
           29  +       [enum] When stepping down without a replacement maintainer
           30  +      	      taking over the relevant packages have to be flagged as
           31  +      	      [const unmaintained].
           32  +
           33  +       [enum] When a replacement mantainer is brought in for a package
           34  +      	      it is (kept) marked as [const maintained] (again).
           35  +
           36  +       [para] A replacement maintainer is bound by the same rules as
           37  +	      the original maintainer, except that the mandatory
           38  +	      period of maintenance is shortened to one year.
           39  +
           40  +       [enum] For any [const unmaintained] package a contributor
           41  +       	      interested in becoming its maintainer can become so by
           42  +       	      flagging them as [const maintained] with their name and
           43  +       	      contact information, committing themselves to the rules
           44  +       	      of a replacement maintainer (see previous point).
           45  +
           46  +       [enum] For any already [const maintained] package a contributor
           47  +       	      interested in becoming a co-maintainer can become so
           48  +       	      with the agreement of the existing maintainer(s),
           49  +       	      committing themselves to the rules of a replacement
           50  +       	      maintainer (see two points previous).
           51  +
           52  +       [list_end]
           53  +
           54  +       [para] The responsibilities as a maintainer include:
           55  +
           56  +       [list_begin enumerated]
           57  +
           58  +       [enum] Watching Tcllib's ticket tracker for bugs, bug fixes,
           59  +       	      and feature requests related to the new packages.
           60  +
           61  +       [enum] Reviewing the aforementioned tickets, rejecting or
           62  +       	      applying them
           63  +
           64  +       [enum] Coordination and discussion with ticket submitter during
           65  +       	      the development and/or application of bug fixes.
           66  +
           67  +       [list_end]
           68  +
           69  +[enum] Follow the [sectref {Branching and Workflow}] of this guide.
           70  +
           71  +[list_end]

Added devdoc/parts/d_op_aware.inc.

            1  +
            2  +When developing we have to keep ourselves aware of the context of our
            3  +work. On what branch are we ? What files have we changed ? What new
            4  +files are not yet known to the repository ? What has happened remotely
            5  +since we used our checkout ?
            6  +
            7  +The answers to these questions become especially important when using
            8  +a long-lived checkout and coming back to it after some time away.
            9  +
           10  +[para] Commands to answer questions like the above are:
           11  +
           12  +[list_begin definitions]
           13  +
           14  +[def [cmd {fossil pull}]]
           15  +
           16  +       Get all changes done on the remote since the last pull or sync
           17  +       from it. This has to be done first, before any of the commands
           18  +       below.
           19  +
           20  +[para] Even if the commit in our checkout refers to the branch we want
           21  +       right now control operations committed to the remote may have
           22  +       changed that from underneath us.
           23  +
           24  +[def [cmd {fossil info | grep tags}]]
           25  +[def [cmd {fossil branch list | grep '\*'}]]
           26  +
           27  +       Two different ways of determining the branch our checkout is
           28  +       on.
           29  +
           30  +[def [cmd {fossil timeline}]]
           31  +
           32  +       What have we (and others) done recently ?
           33  +
           34  +[para] [emph Attention], this information is very likely outdated, the
           35  +       more the longer we did not use this checkout.
           36  +
           37  +       Run [cmd {fossil pull}] first to get latest information from
           38  +       the remote repository of the project.
           39  +
           40  +[def [cmd {fossil timeline current}]]
           41  +
           42  +       Place the commit our checkout is based on at the top of the
           43  +       timeline.
           44  +
           45  +[def [cmd {fossil changes}]]
           46  +
           47  +       Lists the files we have changed compared to the commit the
           48  +       checkout is based on.
           49  +
           50  +[def [cmd {fossil extra}]]
           51  +
           52  +       Lists the files we have in the checkout the repository does not
           53  +       know about. This may be leftover chaff from our work, or
           54  +       something we have forgotten to [cmd {fossil add}] to the
           55  +       repository yet.
           56  +
           57  +[list_end]

Added devdoc/parts/d_op_branch_close.inc.

            1  +
            2  +Be aware of where you are (see first definition).
            3  +
            4  +[para] Ensure that you have clean checkout (see second definition).
            5  +
            6  +       In the full-blown sequence (zig-zag) it is [emph required], due
            7  +       to the merging from trunk. In the shorter sequence it is only
            8  +       desired. That said, keeping the checkout clean before
            9  +       any major operations is a good habit to have, in my opinion.
           10  +
           11  +[para] The full-blown sequencing with checks all the way is to
           12  +
           13  +[list_begin enumerated]
           14  +
           15  +[enum] Validate the checkout, i.e. last commit on your branch. Run the
           16  +       full test suite and other validations, fix all the issues which
           17  +       have cropped up.
           18  +
           19  +[enum] Merge the latest state of the [term trunk] (see next definition).
           20  +
           21  +[enum] Validate the checkout again. The incoming trunk changes may
           22  +       have broken something now. Do any required fixes.
           23  +
           24  +[enum] Now merge to the trunk using
           25  +
           26  +[example {
           27  +    fossil update trunk
           28  +    fossil merge --integrate YOUR_BRANCH
           29  +}]
           30  +
           31  +[enum] At this point the checkout should be in the same state as at
           32  +       the end of point (3) above, because we resolved any issues with
           33  +       the trunk already. Thus a simple
           34  +
           35  +[example {
           36  +    fossil commit ...
           37  +}]
           38  +
           39  +       should be sufficient now to commit the merge back and close the
           40  +       branch (due to the [option --integrate] we used on the merge).
           41  +
           42  +[para] The more paranoid may validate the checkout a third time before
           43  +       commiting.
           44  +[list_end]
           45  +
           46  +[para] I call this a [term {zig-zag merge}] because of how the arrows
           47  +       look in the timeline, from trunk to feature branch for the
           48  +       first merge, and then back for the final merge.
           49  +
           50  +[para] A less paranoid can do what I call a [term {simple merge}],
           51  +       which moves step (2) after step (4) and skips step (3)
           52  +       entirely. The resulting shorter sequence is
           53  +
           54  +[list_begin enumerated]
           55  +[enum] Validate
           56  +[enum] Merge to trunk
           57  +[enum] Validate again
           58  +[enum] Commit to trunk
           59  +[list_end]
           60  +
           61  +The last step after either zig-zag or plain merge is to
           62  +
           63  +[example {
           64  +    fossil sync
           65  +}]
           66  +
           67  +This saves our work to the remote side, and further gives us any other
           68  +work done while we were doing our merge. It especially allows us to
           69  +check if we raced somebody else, resulting in a split trunk.
           70  +
           71  +[para] When that happens we should coordinate with the other developer
           72  +       on who fixes the split, to ensure that we do not race each
           73  +       other again.

Added devdoc/parts/d_op_branch_import.inc.

            1  +
            2  +Be aware of where you are (see first definition).
            3  +
            4  +[para] Ensure that you have clean checkout (see second definition).
            5  +       It is [emph required].
            6  +       
            7  +[para] In most situations you want to import the latest commit of
            8  +       branch [term trunk] (or other origin). To get it use
            9  +
           10  +[example {
           11  +    fossil pull
           12  +}]
           13  +
           14  +[para] With that done we can now import this commit into our current
           15  +       branch with
           16  +
           17  +[example {
           18  +    fossil merge trunk
           19  +}]
           20  +
           21  +[para] Even if [syscmd fossil] does not report any conflicts it is a
           22  +       good idea to check that the operation has not broken the new
           23  +       and/or changed functionality we are working on.
           24  +
           25  +[para] With the establishment of a good merge we then save the state
           26  +       with
           27  +
           28  +[example {
           29  +    fossil commit ...
           30  +}]
           31  +
           32  +before continuing development.

Added devdoc/parts/d_op_branch_open.inc.

            1  +
            2  +Be aware of where you are (see first definition).
            3  +
            4  +[para] Ensure that you have clean checkout (see second definition).
            5  +       It is [emph required].
            6  +
            7  +[para] In most situations you want to be on branch [term trunk], and
            8  +       you want to be on the latest commit for it. To get there use
            9  +
           10  +[example {
           11  +    fossil pull
           12  +    fossil update trunk
           13  +}]
           14  +
           15  +If some other branch is desired as the starting point for the coming
           16  +work replace [term trunk] in the commands above with the name of that
           17  +branch.
           18  +
           19  +[para] With the base line established we now have two ways of creating
           20  +       the new branch, with differing (dis)advantages.
           21  +
           22  +       The simpler way is to
           23  +
           24  +[example {
           25  +    fossil branch new NAME_OF_NEW_BRANCH
           26  +}]
           27  +
           28  +and start developing. The advantage here is that you cannot forget to
           29  +create the branch. The disadvantages are that we have a branch commit
           30  +unchanged from where we branched from, and that we have to use
           31  +high-handed techniques like hiding or shunning to get rid of the
           32  +commit should we decide to abandon the work before the first actual
           33  +commit on the branch.
           34  +
           35  +[para] The other way of creating the branch is to start developing,
           36  +and then on the first commit use the option [option --branch] to tell
           37  +[syscmd fossil] that we are starting a branch now. I.e. run
           38  +
           39  +[example {
           40  +    fossil commit --branch NAME_OF_NEW_BRANCH ...
           41  +}]
           42  +
           43  +where [term ...] are any other options used to supply the commit
           44  +message, files to commit, etc.
           45  +
           46  +[para] The (dis)advantages are now reversed.
           47  +
           48  +[para] We have no superflous commit, only what is actually
           49  +       developed. The work is hidden until we commit to make our first
           50  +       commit.
           51  +
           52  +[para] We may forget to use [option {--branch NAME_OF_NEW_BRANCH}] and
           53  +       then have to correct that oversight via the fossil web
           54  +       interface (I am currently unaware of ways of doing such from
           55  +       the command line, although some magic incantantion of
           56  +       [cmd {fossil tag create}] may work).
           57  +
           58  +[para] It helps to keep awareness, like checking before any commit
           59  +       that we are on the desired branch.

Added devdoc/parts/d_op_clean.inc.

            1  +
            2  +Be aware of where you are (see first definition).
            3  +
            4  +[para] For pretty much all the operation recipes below a clean
            5  +       checkout is at least desired, often required.
            6  +       To check that a checkout is clean invoke
            7  +
            8  +[example {
            9  +    fossil changes
           10  +    fossil extra
           11  +}]
           12  +
           13  +How to clean up when uncommitted changes of all sorts are found is
           14  +context-specific and outside of the scope of this guide.

Added devdoc/parts/d_testing.inc.

            1  +
            2  +Testsuites in Tcllib are based on Tcl's standard test package
            3  +[package tcltest], plus utilities found in the directory
            4  +[file modules/devtools]
            5  +
            6  +[para] Tcllib developers invoke the suites through the
            7  +[cmd {test run}] method of the [file sak.tcl] tool, with other methods
            8  +of [cmd test] providing management operations, for example setting a
            9  +list of standard Tcl shells to use.
           10  +
           11  +[comment {===================================================================}]
           12  +[subsection {Invoke the testsuites of a specific module}]
           13  +
           14  +Invoke either
           15  +
           16  +[example {  ./sak.tcl test run foo }]
           17  +
           18  +or
           19  +
           20  +[example {  ./sak.tcl test run modules/foo }]
           21  +
           22  +to invoke the testsuites found in a specific module [file foo].
           23  +
           24  +[comment {===================================================================}]
           25  +[subsection {Invoke the testsuites of all modules}]
           26  +
           27  +Invoke the tool without a module name, i.e.
           28  +
           29  +[example {  ./sak.tcl test run }]
           30  +
           31  +to invoke the testsuites of all modules.
           32  +
           33  +[comment {===================================================================}]
           34  +[subsection {Detailed Test Logs}]
           35  +
           36  +In all the previous examples the test runner will write a combination
           37  +of progress display and testsuite log to the standard output, showing
           38  +for each module only the tests that passed or failed and how many of
           39  +each in a summary at the end.
           40  +
           41  +[para] To get a detailed log, it is necessary to invoke the test
           42  +runner with additional options.
           43  +
           44  +[para] For one:
           45  +
           46  +[example {
           47  +   ./sak.tcl test run --log LOG foo
           48  +}]
           49  +
           50  +While this shows the same short log on the terminal as before, it also
           51  +writes a detailed log to the file [file LOG.log], and excerpts to
           52  +other files ([file LOG.summary], [file LOG.failures], etc.).
           53  +
           54  +[para] For two:
           55  +
           56  +[example {
           57  +  ./sak.tcl test run -v foo
           58  +}]
           59  +
           60  +This writes the detailed log to the standard output, instead of the
           61  +short log.
           62  +
           63  +[para] Regardless of form, the detailed log contains a list of all test
           64  +cases executed, which failed, and how they failed (expected versus
           65  +actual results).
           66  +
           67  +[comment {===================================================================}]
           68  +[subsection {Shell Selection}]
           69  +
           70  +By default the test runner will use all the Tcl shells specified via
           71  +[cmd {test add}] to invoke the specified testsuites, if any. If no
           72  +such are specified it will fall back to the Tcl shell used to run the
           73  +tool itself.
           74  +
           75  +[para] Use option [option --shell] to explicitly specify the Tcl shell
           76  +to use, like
           77  +
           78  +[example {
           79  +  ./sak.tcl test run --shell /path/to/tclsh ...
           80  +}]
           81  +
           82  +[comment {===================================================================}]
           83  +[subsection Help]
           84  +
           85  +Invoke the tool as
           86  +
           87  +[example {  ./sak.tcl help test }]
           88  +
           89  +to see the detailed help for all methods of [cmd test], and the
           90  +associated options.

Added 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. This equals one test case checking the behavior when the
           26  +	specified node is not a node of the graph.
           27  +
           28  +[para]  This often gives rise to code in the implementation which
           29  +	explicitly checks the assumption and throws an understandable error,
           30  +	instead of letting the algorithm fail later in some weird
           31  +	non-deterministic way.
           32  +
           33  +[para]  It is 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. Another article of
          103  +interest might be [uri https://www.researchgate.net/publication/298896236].
          104  +While geared to a particular numerical algorithm it still shows that
          105  +even a simple-looking algorithm can lead to an incredible number of
          106  +test cases.
          107  +
          108  +[para] An interesting connection is to documentation. In one
          109  +direction, the properties checked with black-box testing are exactly
          110  +the properties which should be documented in the algorithm's man
          111  +page. And conversely, the documentation of the properties of an
          112  +algorithm makes a good reference to base the black-box tests on.
          113  +
          114  +[para] In practice test cases and documentation often get written
          115  +together, cross-influencing each other. And the actual writing of test
          116  +cases is a mix of black and white box, possibly influencing the
          117  +implementation while writing the tests. Like writing a test for a
          118  +condition like [term {startnode not in input graph}] serving as
          119  +reminder to put a check for this condition into the code.

Added devdoc/parts/rm_distribute.inc.

            1  +
            2  +With the release made it has to be published and the world notified of
            3  +its existence.
            4  +
            5  +[list_begin enumerated]
            6  +
            7  +[enum]	    Create a proper fossil event for the release, via
            8  +	    [uri http://core.tcl-lang.org/tcllib/eventedit].
            9  +
           10  +[para]	    An [uri http://core.tcl-lang.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817 {existing event}] should be used as template.
           11  +
           12  +[enum]	    Update a number of web locations:
           13  +
           14  +[list_begin enumerated]
           15  +[enum]	    [uri http://core.tcl-lang.org/tcllib/doc/trunk/embedded/index.md {Home page}]
           16  +[enum]	    [uri http://core.tcl-lang.org/tcllib/wiki?name=Downloads     Downloads]
           17  +[enum]	    [uri http://core.tcl-lang.org/tcllib/wiki?name=Past+Releases {Past Releases}]
           18  +[enum]	    [uri http://www.tcl-lang.org/home/release.txt     ]
           19  +[enum]	    [uri http://www.tcl-lang.org/software/tcllib/*.tml]
           20  +[enum]	    [uri http://wiki.tcl-lang.org/page/Tcllib]
           21  +[list_end]
           22  +
           23  +The first location maps to the file [file embedded/index.md] in the
           24  +repository itself, as such it can edited as part of the release
           25  +process. This is where reference to the new fossil event is added, as
           26  +the new current release.
           27  +
           28  +[para] The next two locations are in the fossil tcllib wiki and
           29  +require admin or wiki write permissions for
           30  +[uri http://core.tcl-lang.org/tcllib].
           31  +
           32  +[para] The last two locations require ssh access to
           33  +[uri http://www.tcl-lang.org] and permission to edit
           34  +files in the web area.
           35  +
           36  +
           37  +[enum]	***TODO*** mailing lists and other places to send notes to.
           38  +
           39  +[list_end]

Added devdoc/parts/rm_final.inc.

            1  +todo: finalize release, make candidate official

Added devdoc/parts/rm_start.inc.

            1  +todo: open a candidate for release

Added devdoc/parts/rm_tooling.inc.

            1  +
            2  +The [file sak.tcl] script in the toplevel directory of a Tcllib
            3  +checkout is the one tool used by the release manager to perform its
            4  +[sectref Tasks].
            5  +
            6  +[para] The main commands to be used are
            7  +
            8  +[example {
            9  +    sak.tcl validate
           10  +    sak.tcl test run
           11  +    sak.tcl review
           12  +    sak.tcl readme
           13  +    sak.tcl localdoc
           14  +    sak.tcl release
           15  +}]
           16  +
           17  +More detail will be provided in the explanations of the various
           18  +[sectref Tasks].

Added devdoc/parts/rm_work.inc.

            1  +todo: test, validate and check that the candidate is worthy of release
            2  +fix testsuites, possibly fix packages, documentation
            3  +regenerate docs
            4  +coordinate with package maintainers wrt fixes
            5  +
            6  +big thing: going over the packages, classify changes since last
            7  +release to generate a nice readme.

Added devdoc/parts/rq_critcl.inc.

            1  +
            2  +[subsection Critcl]
            3  +
            4  +The [syscmd critcl] tool is an [emph optional] dependency.
            5  +
            6  +[para] It is only required when trying to build the C-based
            7  +[term accelerators] for a number of packages, as explained in
            8  +[sectref {Critcl & Accelerators}]
            9  +
           10  +[para] Tcllib's build system looks for it in the [variable PATH],
           11  +using the name [syscmd critcl]. This is for Unix.
           12  +
           13  +On Windows on the other hand the search is more complex. First we look
           14  +for a proper application [syscmd critcl.exe]. When that is not found
           15  +we look for a combination of interpreter ([syscmd tclkitsh.exe],
           16  +[syscmd tclsh.exe]) and starkit ([syscmd critcl.kit], [syscmd critcl])
           17  +instead. [emph Note] that the choice of starkit can be overriden via
           18  +the environment variable [variable CRITCL].
           19  +
           20  +[para] Tcllib requires Critcl version 2 or higher.
           21  +
           22  +[para] The github repository providing releases of version 2 and
           23  +higher, and the associated sources, can be found at
           24  +[uri http://andreas-kupries.github.com/critcl].
           25  +
           26  +[para] Any branch of the repository can be used (if not using the
           27  +prebuild starkit or starpack), although the use of the stable branch
           28  +[emph master] is recommended.
           29  +
           30  +[para] At the above url is also an explanation on how to build and
           31  +install Critcl, including a list of its dependencies.
           32  +
           33  +[para] Its instructions will not be repeated here. If there are
           34  +problems with these directions please file a ticket against the
           35  +[term Critcl] project, and not Tcllib.

Added devdoc/parts/rq_tcl.inc.

            1  +
            2  +[subsection Tcl]
            3  +
            4  +As we are installing a number of Tcl packages and applications it
            5  +should be pretty much obvious that a working installation of Tcl
            6  +itself is needed, and I will not belabor the point.
            7  +
            8  +[para] Out of the many possibilities use whatever you are comfortable
            9  +with, as long as it provides at the very least Tcl 8.2, or higher.
           10  +
           11  +This may be a Tcl installation provided by your operating system
           12  +distribution, from a distribution-independent vendor, or built by
           13  +yourself.
           14  +
           15  +[para] [emph Note] that the packages in Tcllib have begun to require
           16  +8.4, 8.5, and even 8.6. Older versions of Tcl will not be able to use
           17  +such packages. Trying to use them will result in
           18  +[emph {package not found}] errors, as their package index files will
           19  +not register them in versions of the core unable to use them.
           20  +
           21  +[para] Myself, I used (and still use)
           22  +[uri http://www.activestate.com ActiveState's]
           23  +ActiveTcl 8.5 distribution during development, as I am most familiar
           24  +with it.
           25  +
           26  +[para] [emph {(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, maintaining ActiveTcl and TclDevKit for them).}].
           27  +I am currently working for SUSE Software Canada ULC, although not in
           28  +Tcl-related areas.
           29  +
           30  +[para] This distribution can be found at
           31  +[uri http://www.activestate.com/activetcl]. Retrieve the archive of
           32  +ActiveTcl 8.5 (or higher) for your platform and install it as directed
           33  +by ActiveState.
           34  +
           35  +[para] For those wishing to build and install Tcl on their own, the
           36  +relevant sources can be found at
           37  +
           38  +[list_begin definitions]
           39  +[def Tcl] [uri http://core.tcl-lang.org/tcl/]
           40  +[list_end]
           41  +
           42  +together with the necessary instructions on how to build it.
           43  +
           44  +[para] If there are problems with building, installing, or using Tcl,
           45  +please file a ticket against [term Tcl], or the vendor of your
           46  +distribution, and [emph not] [term Tcllib].

Added devdoc/parts/welcome.inc.

            1  +
            2  +Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
            3  +package itself. It is a collection of (semi-independent) [term Tcl]
            4  +packages that provide utility functions useful to a large collection
            5  +of Tcl programmers.
            6  +

Deleted devdoc/releaseguide.html.

     1         -<!- Guide to the creation of source releases for Tcllib -->
     2         -
     3         -<h1>Guide to the creation of source releases for Tcllib
     4         -</h1>
     5         -<hr>
     6         -
     7         -<h2>Recap
     8         -</h2>
     9         -<table><tr><td valign=top>
    10         -      <!-- The local source of this image is
    11         -		tcllib/devel/cvs.branches.*
    12         -	-->
    13         -      <img src="http://sourceforge.net/dbimage.php?id=2221">
    14         -</td><td valign=top><p>
    15         -The CVS repository for Tcllib contains two main branches,
    16         -      the HEAD for development, and RELEASES as the staging area for
    17         -      official releases.
    18         -</p></td></tr></table>
    19         -
    20         -<h2>Dependencies
    21         -</h2>
    22         -
    23         -<h2>Creation of a new official release
    24         -</h2>
    25         -
    26         -<p>To create a new official release of Tcllib the release manager has
    27         -      to perform the steps described below:
    28         -</p>
    29         -
    30         -
    31         -<ol>
    32         -<li> Retrieve the sources at the current head
    33         -	from the CVS repository, using a command like
    34         -<pre>
    35         -	  CVSROOT=:pserver:[email protected]:/cvsroot/tcllib
    36         -	  cvs -d${CVSROOT} co tcllib
    37         -</pre>
    38         -	Vary this command according to taste as long as the overall
    39         -	meaning is not changed. Compression options and the like.
    40         -
    41         -<li> Tag these sources with a new branch tag for the new release of
    42         -	  tcllib, like
    43         -<pre>
    44         -	  cvs -d${CVSROOT} rtag tcllib
    45         -</pre>
    46         -
    47         -<li> Commit the changes, then update the working directory.
    48         -
    49         -<li> Use a tclsh to run the <b>sak</b> tool with the argument <i>gendist</i>, like
    50         -<pre>
    51         -    tclsh /path/to/tcllib/sak.tcl gendist
    52         -</pre>
    53         -
    54         -<li> This results in the creation of a <i>tcllib-VERSION</i> directory
    55         -in the current working directory, and of two archives, <i>.zip</i>,
    56         -and <i>.tar.gz</i>. A starkit will be created if <b>sdx</b> is present
    57         -in the PATH. If additionally a file named <b>tclkit</b> is present in
    58         -the current working directory a starpack will be created too, using
    59         -this tclkit as the runtime.
    60         -
    61         -
    62         -<li> Now follow the instructions in the Sourceforge site documentation
    63         -		    for uploading the archives generated by the last
    64         -		    step to
    65         -		    <b>ftp://upload.sourceforge.net/incoming</b>, and
    66         -		    follow the procedures for creating packages and
    67         -		    releases at Sourceforge.
    68         -</ol>
    69         -
    70         -<p>At last notify the relevant persons in other communities like
    71         -Debian (See list of contacts) about the new release.
    72         -</p>

Added devdoc/tcl_community_communication.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[manpage_begin tcl_community_communication n 1]
            3  +[titledesc {Tcl Community - Kind Communication}]
            4  +[description]
            5  +
            6  +The Tcl Community encourages contributions from anyone who wishes to
            7  +advance the development of:
            8  +
            9  +[list_begin itemized]
           10  +[item] The Tcl Language
           11  +[item] Tcl derived languages
           12  +[item] Tcl related libraries
           13  +[item] Tcl extensions
           14  +[item] External Projects that Integrate Tcl
           15  +[list_end]
           16  +
           17  +[para] We welcome those contributions from anyone. We are blind to
           18  +gender, race, religion, cultural background, cybernetic nature, and
           19  +any other demographic characteristics, as well as personal political
           20  +views.
           21  +
           22  +[para] A community lives and dies by communications. And occasionally
           23  +our communications are peppered with patterns that are harsh,
           24  +unfriendly, unwelcoming and/or otherwise unkind. As a volunteer
           25  +community, we need all of the help we can get. Therefore, we ask all
           26  +contributors to make a conscious effort, in Tcl Community discussions,
           27  +to communicate in ways that are welcoming. Ways that are
           28  +friendly. Ways that are, in a word: kind.
           29  +
           30  +[para] These guidelines suggest specific ways to accomplish that goal.
           31  +
           32  +[para] Please note: for the balance of this document any reference to
           33  +"People", "Persons", "anybody" or "somebody" can refer to any sentient
           34  +being, not merely corporeal members of the species Homo Sapien.
           35  +
           36  +[list_begin definitions]
           37  +
           38  +[def {We are a Sanctuary not a Clubhouse}]
           39  +
           40  +The Tcl Community is a collective of amateurs and professionals who
           41  +code, test, and use tools. Our community is open to all. There is no
           42  +velvet rope. There is no bouncer at the door. There are no secret
           43  +handshakes. Any sentient being who enters our midst is welcome. If
           44  +someone is ever asked to leave, it is only because they are being
           45  +disruptive to the functioning of the community.
           46  +
           47  +[def {We Merit Ideas, Not People}]
           48  +
           49  +A good idea can come from anyone, regardless of how little time they
           50  +have been with us. A bad idea can come from anyone, regardless of how
           51  +much time or how little time they have been with us. We judge a
           52  +concept by how it stands up to scrutiny of logic, implementation, and
           53  +regression testing. We don’t judge ideas based on who had the idea
           54  +first, who agrees with the idea, or who disagrees with it.
           55  +
           56  +[def {Treat Everyone with Respect}]
           57  +
           58  +Everyone is deserving of respect and courtesy at all times.
           59  +
           60  +[def {Refer to people by the names they use.}]
           61  +
           62  +If grammar requires you to state a gender for a person, honor their
           63  +preferences about their gender identity. If you are unsure as to the
           64  +gender of an individual, ask. If someone had to guess about your
           65  +gender and got it wrong, please correct them and do not take it
           66  +personally.
           67  +
           68  +[def {Do not take a harsh tone towards other participants.}]
           69  +
           70  +Do not make personal attacks against anyone (participant or not.)
           71  +
           72  +[para] Criticize statements and actions, never people.
           73  +
           74  +[def {Don’t Take Things Personally}]
           75  +
           76  +When in doubt, assume the best in people. A criticism of your
           77  +statements is not a personal attack on you.
           78  +
           79  +[def {Persons, not People}]
           80  +
           81  +Stereotypes are an unhelpful tool on many accounts. They are generally
           82  +oversimplified. They are usually flat out wrong. And even if "right"
           83  +they are of absolutely no utility in determining the capabilities,
           84  +motivations, or fitness of an individual.
           85  +
           86  +[para] Don’t use them in Tcl Community communications.
           87  +
           88  +[def {Mistakes Happen}]
           89  +
           90  +The human condition is a series of trials and errors. Progress is when
           91  +we get one more trial than error. Being wrong or making a mistake is
           92  +the default state of humanity. Accept the errors of your fellow
           93  +sentient beings, and be aware that you are also fallible.
           94  +
           95  +[def {Keep it Real}]
           96  +
           97  +Please respond to what people actually say. We are all amazing
           98  +individuals, but none among us are mind readers. If you find yourself
           99  +responding to what you imagine someone is thinking, odds are you are
          100  +going to be wrong.
          101  +
          102  +[para] If you must criticize someone, stick to things they have
          103  +actually done. Never criticize for something you speculate they have
          104  +done. Or imagine they have done. Or something someone who shares some
          105  +attribute with them has done in the past.
          106  +
          107  +[para] Keep discussions about any non-Tcl subjects to what can be
          108  +stated factually and without emotion or judgement.
          109  +
          110  +[def {When Trouble Arises, Don’t Escalate}]
          111  +
          112  +If you feel you are being personally attacked or offended, take the
          113  +high road. Punching back in a public forum will only makes things
          114  +worse. Address the matter in a private correspondence. Be
          115  +polite. Express your feelings, but note that you are expressing your
          116  +feelings. When writing, look for a way to calm matters down. And when
          117  +in doubt, sleep on your letter before pressing send. And when not in
          118  +doubt, sleep on it for another day after that.
          119  +
          120  +[para] If you are a spectator to a fight in progress, politely request
          121  +the two parties take the matter to a more private forum.
          122  +
          123  +[def {Always get the Last Word: I’m Sorry}]
          124  +
          125  +If an personal argument does arise, be the first to apologize. An
          126  +apology does not concede a logical point. It merely acknowledges that
          127  +at some point the discussion left either logic, community decency, or
          128  +both. Return to the topic when cooler heads can prevail.
          129  +
          130  +[def {Nobody is Keeping Score}]
          131  +
          132  +There is no prize for being right. There is no cost for being wrong. A
          133  +hard sell is not going to advance your idea along any more than a
          134  +logical argument. You aren’t running for office. This isn’t debate
          135  +club. If you find yourself continuing a discussion beyond where a
          136  +topic can be logically discussed, stop.
          137  +
          138  +[def {No Evangelizing}]
          139  +
          140  +The Tcl Community is not the place to promote your chosen operating
          141  +system, political outlook, religion, marketing scheme, or economic
          142  +model. Period.
          143  +
          144  +[para] (And if you do bring it up, be prepared to have your chosen
          145  +topic discussed logically. And odds are, not favorably.)
          146  +
          147  +[def {Respect the Community}]
          148  +
          149  +If the Community has come to a decision on a course of action, please
          150  +stop arguing.
          151  +
          152  +[para] If someone complains about how you are expressing your ideas,
          153  +listen.
          154  +
          155  +[para] If your words are hurting people, stop. There is no amount of
          156  +being "right" that makes up for someone leaving our midst because they
          157  +felt insulted, threatened, or ignored.
          158  +
          159  +[list_end]
          160  +
          161  +By following these guidelines, we will build our community, encourage
          162  +more contribution to our projects, and our discussions will be
          163  +friendlier and reach conclusions more easily.
          164  +
          165  +[para] Thank You.
          166  +
          167  +[section Signatories]
          168  +[list_begin itemized]
          169  +[item] Sean "the Hypnotoad" Woods
          170  +[item] Andreas Kupries
          171  +[list_end]
          172  +
          173  +[section Authors]
          174  +[list_begin definitions]
          175  +[def Primary] Sean "the Hypnotoad" Woods
          176  +[def {Light editing}] Andreas Kupries
          177  +[list_end]
          178  +[manpage_end]

Added devdoc/tcllib_devguide.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[manpage_begin tcllib_devguide n 1]
            3  +[titledesc {Tcllib - The Developer's Guide}]
            4  +[description]
            5  +[include parts/welcome.inc]
            6  +
            7  +[para]
            8  +
            9  +This document is a guide for developers working on Tcllib,
           10  +i.e. maintainers fixing bugs, extending the collection's
           11  +functionality, etc.
           12  +
           13  +[para]
           14  +
           15  +Please read
           16  +
           17  +[list_begin enum]
           18  +[enum] [term {Tcllib - How To Get The Sources}] and
           19  +[enum] [term {Tcllib - The Installer's Guide}]
           20  +[list_end]
           21  +
           22  +first, if that was not done already.
           23  +
           24  +[para] Here we assume that the sources are already available in a
           25  +directory of your choice, and that you not only know how to build and
           26  +install them, but also have all the necessary requisites to actually
           27  +do so. The guide to the sources in particular also explains which
           28  +source code management system is used, where to find it, how to set it
           29  +up, etc.
           30  +
           31  +[comment {===================================================================}]
           32  +[section Commitments]
           33  +[subsection Contributor][include parts/d_contrib.inc]
           34  +[subsection Maintainer][include parts/d_maintain.inc]
           35  +
           36  +[comment {===================================================================}]
           37  +[section {Branching and Workflow}]
           38  +[include parts/d_branchflow.inc]
           39  +
           40  +[comment {===================================================================}]
           41  +[section {Structural Overview}]
           42  +[include parts/d_dirlayout.inc]
           43  +
           44  +[comment {===================================================================}]
           45  +[section {Testsuite Tooling}]
           46  +[include parts/d_testing.inc]
           47  +
           48  +[comment {===================================================================}]
           49  +[section {Documentation Tooling}]
           50  +[include parts/d_documentation.inc]
           51  +
           52  +[comment {===================================================================}]
           53  +[section {Notes On Writing A Testsuite}]
           54  +[include parts/d_testwrite.inc]
           55  +
           56  +[comment {===================================================================}]
           57  +[section {Installation Tooling}]
           58  +[include parts/d_installation.inc]
           59  +
           60  +[comment {===================================================================}]
           61  +[manpage_end]
           62  +

Added devdoc/tcllib_installer.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[manpage_begin tcllib_install_guide n 1]
            3  +[titledesc {Tcllib - The Installer's Guide}]
            4  +[description]
            5  +[include parts/welcome.inc]
            6  +
            7  +[para]
            8  +
            9  +The audience of this document is anyone wishing to build and install
           10  +the packages found in Tcllib, for either themselves, or others.
           11  +
           12  +[para]
           13  +
           14  +For developers intending to work on the packages themselves we
           15  +additionally provide
           16  +
           17  +[list_begin enum]
           18  +[enum] [term {Tcllib - The Developer's Guide}].
           19  +[list_end]
           20  +
           21  +[para]
           22  +
           23  +Please read [term {Tcllib - How To Get The Sources}] first, if that
           24  +was not done already. Here we assume that the sources are already
           25  +available in a directory of your choice.
           26  +
           27  +[para]
           28  +
           29  +[comment {===================================================================}]
           30  +[section Requisites]
           31  +
           32  +Before Tcllib can be build and used a number of requisites must be installed.
           33  +
           34  +These are:
           35  +
           36  +[list_begin enumerated]
           37  +[enum] The scripting language Tcl.
           38  +       For details see [sectref Tcl].
           39  +[enum] Optionally, the [package critcl] package (C embedding) for [syscmd Tcl].
           40  +       For details see [sectref CriTcl].
           41  +[list_end]
           42  +
           43  +This list assumes that the machine where Tcllib is to be installed is
           44  +essentially clean. Of course, if parts of the dependencies listed
           45  +below are already installed the associated steps can be skipped. It is
           46  +still recommended to read their sections though, to validate that the
           47  +dependencies they talk about are indeed installed.
           48  +
           49  +[include parts/rq_tcl.inc]
           50  +[include parts/rq_critcl.inc]
           51  +
           52  +[comment {= build instructions ==============================================}]
           53  +[section {Build & Installation Instructions}]
           54  +
           55  +As Tcllib is mainly a bundle of packages written in pure Tcl building
           56  +it is the same as installing it. The exceptions to this have their own
           57  +subsection, [sectref {Critcl & Accelerators}], later on.
           58  +
           59  +[para] Before that however comes the standard case, differentiated by
           60  +       the platforms with material differences in the instruction, i.e.
           61  +       [term Unix]-like, versus [term Windows].
           62  +
           63  +[para] Regarding the latter it should also be noted that it is
           64  +       possible set up an [term Unix]-like environment using projects
           65  +       like [term MSYS], [term Cygwin], and others. In that case the
           66  +       user has the choice of which instructions to follow.
           67  +
           68  +[para] Regardless of environment or platform, a suitable [term Tcl]
           69  +       has to be installed, and its [syscmd tclsh] should be placed on
           70  +       the [variable PATH] ([term Unix]) or associated with
           71  +       [file .tcl] files ([term Windows]).
           72  +
           73  +[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
           74  +[subsection {Installing on Unix}]
           75  +[include parts/b_unix.inc]
           76  +
           77  +[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
           78  +[subsection {Installing on Windows}]
           79  +[include parts/b_windows.inc]
           80  +
           81  +[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
           82  +[subsection {Critcl & Accelerators}]
           83  +[include parts/b_critcl.inc]
           84  +
           85  +[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
           86  +[subsection Tooling]
           87  +[include parts/b_tooling.inc]
           88  +
           89  +[manpage_end]
           90  +

Added devdoc/tcllib_license.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[manpage_begin tcllib_license n 1]
            3  +[titledesc {Tcllib - License}]
            4  +[description]
            5  +[include parts/welcome.inc]
            6  +
            7  +[para] The collection is under the BSD license.
            8  +
            9  +[section License]
           10  +
           11  +[para]
           12  +
           13  +This software is copyrighted by Ajuba Solutions and other parties.
           14  +The following terms apply to all files associated with the software
           15  +unless explicitly disclaimed in individual files.
           16  +
           17  +[para]
           18  +
           19  +The authors hereby grant permission to use, copy, modify, distribute,
           20  +and license this software and its documentation for any purpose,
           21  +provided that existing copyright notices are retained in all copies
           22  +and that this notice is included verbatim in any distributions. No
           23  +written agreement, license, or royalty fee is required for any of the
           24  +authorized uses.  Modifications to this software may be copyrighted by
           25  +their authors and need not follow the licensing terms described here,
           26  +provided that the new terms are clearly indicated on the first page of
           27  +each file where they apply.
           28  +
           29  +[para]
           30  +
           31  +IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
           32  +FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
           33  +ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
           34  +DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
           35  +POSSIBILITY OF SUCH DAMAGE.
           36  +
           37  +[para]
           38  +
           39  +THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
           40  +INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
           41  +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
           42  +NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
           43  +THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
           44  +MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
           45  +
           46  +[para]
           47  +
           48  +GOVERNMENT USE: If you are acquiring this software on behalf of the
           49  +U.S. government, the Government shall have only "Restricted Rights" in
           50  +the software and related documentation as defined in the Federal
           51  +Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
           52  +are acquiring the software on behalf of the Department of Defense, the
           53  +software shall be classified as "Commercial Computer Software" and the
           54  +Government shall have only "Restricted Rights" as defined in Clause
           55  +252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing, the
           56  +authors grant the U.S. Government and others acting in its behalf
           57  +permission to use and distribute the software in accordance with the
           58  +terms specified in this license.
           59  +
           60  +[manpage_end]
           61  +

Added devdoc/tcllib_releasemgr.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[manpage_begin tcllib_releasemgr n 1]
            3  +[titledesc {Tcllib - The Release Manager's Guide}]
            4  +[description]
            5  +[include parts/welcome.inc]
            6  +
            7  +[para]
            8  +
            9  +The audience of this document is the release manager for Tcllib, their
           10  +deputies, and anybody else interested in the task of creating
           11  +an official release of Tcllib for distribution.
           12  +
           13  +[para]
           14  +
           15  +Please read [term {Tcllib - How To Get The Sources}] first, if that
           16  +was not done already. Here we assume that the sources are already
           17  +available in a directory of your choice.
           18  +
           19  +[para]
           20  +
           21  +[comment {===================================================================}]
           22  +[section Tools]
           23  +[include parts/rm_tooling.inc]
           24  +
           25  +[comment {===================================================================}]
           26  +[section Tasks]
           27  +
           28  +[comment {===================================================================}]
           29  +[subsection {Start a release candidate}]
           30  +[include parts/rm_start.inc]
           31  +
           32  +[comment {===================================================================}]
           33  +[subsection {Ready the candidate}]
           34  +[include parts/rm_work.inc]
           35  +
           36  +[comment {===================================================================}]
           37  +[subsection {Make it official}]
           38  +[include parts/rm_final.inc]
           39  +
           40  +[comment {===================================================================}]
           41  +[subsection {Distribute the release}]
           42  +[include parts/rm_distribute.inc]
           43  +
           44  +[manpage_end]
           45  +

Added devdoc/tcllib_sources.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[manpage_begin tcllib_sources n 1]
            3  +[titledesc {Tcllib - How To Get The Sources}]
            4  +[description]
            5  +[include parts/welcome.inc]
            6  +
            7  +[para]
            8  +
            9  +The audience of this document is anyone wishing to either have just a
           10  +look at Tcllib's source code, or build the packages, or to extend and
           11  +modify them.
           12  +
           13  +[para] For builders and developers we additionally provide
           14  +
           15  +[list_begin enum]
           16  +[enum] [term {Tcllib - The Installer's Guide}].
           17  +[enum] [term {Tcllib - The Developer's Guide}].
           18  +[list_end]
           19  +
           20  +respectively.
           21  +
           22  +[section {Source Location}]
           23  +
           24  +The official repository for Tcllib can be found at
           25  +[uri http://core.tcl-lang.org/tcllib]
           26  +
           27  +[section Retrieval]
           28  +
           29  +Assuming that you simply wish to look at the sources, or build a
           30  +specific revision, the easiest way of retrieving it is to:
           31  +
           32  +[list_begin enum]
           33  +[enum] Log into this site, as "anonymous", using the semi-random password in the captcha.
           34  +[enum] Go to the "Timeline".
           35  +[enum] Choose the revision you wish to have.
           36  +[enum] Follow its link to its detailed information page.
           37  +[enum] On that page, choose either the "ZIP" or "Tarball" link to get
           38  +a copy of this revision in the format of your choice.
           39  +[list_end]
           40  +
           41  +[section {Source Code Management}]
           42  +
           43  +For the curious (or a developer-to-be), the sources are managed by the
           44  +[uri http://www.fossil-scm.org {Fossil SCM}].
           45  +
           46  +Binaries for popular platforms can be found directly at its
           47  +[uri http://www.fossil-scm.org/download.html {download page}].
           48  +
           49  +[para]
           50  +
           51  +With that tool available the full history can be retrieved via:
           52  +
           53  +[example {
           54  +    fossil clone \
           55  +	http://core.tcl-lang.org/tcllib \
           56  +        tcllib.fossil
           57  +}]
           58  +
           59  +followed by
           60  +
           61  +[example {
           62  +    mkdir tcllib
           63  +    cd tcllib
           64  +    fossil open ../tcllib.fossil
           65  +}]
           66  +
           67  +to get a checkout of the head of the trunk.
           68  +
           69  +[manpage_end]

Changes to embedded/index.md.

     1      1   <div class='fossil-doc' data-title='Tcl Library Source Code'>
     2      2   
     3      3   <h1 align="center">Tcl Library Source Code</h1>
     4      4   
     5      5   <center>
     6         -Packages
     7         -- [Table Of Contents](md/toc.md)
     8         -- [Keyword Index](md/index.md)
            6  +Packages - [Table Of Contents](md/toc.md)
            7  +&nbsp;&nbsp;&nbsp;
            8  +[Keyword Index](md/index.md)
     9      9   </center>
    10     10   
    11     11   <center>
    12     12   	<form action='../../../docsrch' method='GET'>
    13     13   	<input type="text" name="s" size="40" autofocus>
    14     14   	<input type="submit" value="Search Package Documentation">
    15     15   	</form>
    16     16   </center>
    17     17   
           18  +## Guides to Tcllib
           19  +
           20  +   * [Tcl Community - Kind Communication](md/tcllib/files/devdoc/tcl_community_communication.md)
           21  +   * [License](md/tcllib/files/devdoc/tcllib_license.md)
           22  +   * [How To Get The Sources](md/tcllib/files/devdoc/tcllib_sources.md)
           23  +   * [How To Build And Install Tcllib](md/tcllib/files/devdoc/tcllib_installer.md)
           24  +   * [The Developer's Guide](md/tcllib/files/devdoc/tcllib_devguide.md)
           25  +   * [The Release Manager's Guide](md/tcllib/files/devdoc/tcllib_releasemgr.md)
           26  +
    18     27   ## Discussion & Contact
    19     28   
    20     29   Tcllib has two
    21     30   [mailing lists](https://sourceforge.net/p/tcllib/mailman/).
    22     31   
    23     32   One for notifications (commits, ticket changes), the other for general
    24     33   discussion. These are managed at SourceForge, at the aforementioned

Added embedded/md/tcllib/files/devdoc/tcl_community_communication.md.

            1  +
            2  +[//000000001]: # (tcl\_community\_communication \- )
            3  +[//000000002]: # (Generated from file 'tcl\_community\_communication\.man' by tcllib/doctools with format 'markdown')
            4  +[//000000003]: # (tcl\_community\_communication\(n\) 1 tcllib "")
            5  +
            6  +<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
            7  +href="../../toc.md">Table Of Contents</a> &#124; <a
            8  +href="../../../index.md">Keyword Index</a> &#124; <a
            9  +href="../../../toc0.md">Categories</a> &#124; <a
           10  +href="../../../toc1.md">Modules</a> &#124; <a
           11  +href="../../../toc2.md">Applications</a> ] <hr>
           12  +
           13  +# NAME
           14  +
           15  +tcl\_community\_communication \- Tcl Community \- Kind Communication
           16  +
           17  +# <a name='toc'></a>Table Of Contents
           18  +
           19  +  - [Table Of Contents](#toc)
           20  +
           21  +  - [Description](#section1)
           22  +
           23  +  - [Signatories](#section2)
           24  +
           25  +  - [Authors](#section3)
           26  +
           27  +# <a name='description'></a>DESCRIPTION
           28  +
           29  +The Tcl Community encourages contributions from anyone who wishes to advance the
           30  +development of:
           31  +
           32  +  - The Tcl Language
           33  +
           34  +  - Tcl derived languages
           35  +
           36  +  - Tcl related libraries
           37  +
           38  +  - Tcl extensions
           39  +
           40  +  - External Projects that Integrate Tcl
           41  +
           42  +We welcome those contributions from anyone\. We are blind to gender, race,
           43  +religion, cultural background, cybernetic nature, and any other demographic
           44  +characteristics, as well as personal political views\.
           45  +
           46  +A community lives and dies by communications\. And occasionally our
           47  +communications are peppered with patterns that are harsh, unfriendly,
           48  +unwelcoming and/or otherwise unkind\. As a volunteer community, we need all of
           49  +the help we can get\. Therefore, we ask all contributors to make a conscious
           50  +effort, in Tcl Community discussions, to communicate in ways that are welcoming\.
           51  +Ways that are friendly\. Ways that are, in a word: kind\.
           52  +
           53  +These guidelines suggest specific ways to accomplish that goal\.
           54  +
           55  +Please note: for the balance of this document any reference to "People",
           56  +"Persons", "anybody" or "somebody" can refer to any sentient being, not merely
           57  +corporeal members of the species Homo Sapien\.
           58  +
           59  +  - We are a Sanctuary not a Clubhouse
           60  +
           61  +    The Tcl Community is a collective of amateurs and professionals who code,
           62  +    test, and use tools\. Our community is open to all\. There is no velvet rope\.
           63  +    There is no bouncer at the door\. There are no secret handshakes\. Any
           64  +    sentient being who enters our midst is welcome\. If someone is ever asked to
           65  +    leave, it is only because they are being disruptive to the functioning of
           66  +    the community\.
           67  +
           68  +  - We Merit Ideas, Not People
           69  +
           70  +    A good idea can come from anyone, regardless of how little time they have
           71  +    been with us\. A bad idea can come from anyone, regardless of how much time
           72  +    or how little time they have been with us\. We judge a concept by how it
           73  +    stands up to scrutiny of logic, implementation, and regression testing\. We
           74  +    don’t judge ideas based on who had the idea first, who agrees with the idea,
           75  +    or who disagrees with it\.
           76  +
           77  +  - Treat Everyone with Respect
           78  +
           79  +    Everyone is deserving of respect and courtesy at all times\.
           80  +
           81  +  - Refer to people by the names they use\.
           82  +
           83  +    If grammar requires you to state a gender for a person, honor their
           84  +    preferences about their gender identity\. If you are unsure as to the gender
           85  +    of an individual, ask\. If someone had to guess about your gender and got it
           86  +    wrong, please correct them and do not take it personally\.
           87  +
           88  +  - Do not take a harsh tone towards other participants\.
           89  +
           90  +    Do not make personal attacks against anyone \(participant or not\.\)
           91  +
           92  +    Criticize statements and actions, never people\.
           93  +
           94  +  - Don’t Take Things Personally
           95  +
           96  +    When in doubt, assume the best in people\. A criticism of your statements is
           97  +    not a personal attack on you\.
           98  +
           99  +  - Persons, not People
          100  +
          101  +    Stereotypes are an unhelpful tool on many accounts\. They are generally
          102  +    oversimplified\. They are usually flat out wrong\. And even if "right" they
          103  +    are of absolutely no utility in determining the capabilities, motivations,
          104  +    or fitness of an individual\.
          105  +
          106  +    Don’t use them in Tcl Community communications\.
          107  +
          108  +  - Mistakes Happen
          109  +
          110  +    The human condition is a series of trials and errors\. Progress is when we
          111  +    get one more trial than error\. Being wrong or making a mistake is the
          112  +    default state of humanity\. Accept the errors of your fellow sentient beings,
          113  +    and be aware that you are also fallible\.
          114  +
          115  +  - Keep it Real
          116  +
          117  +    Please respond to what people actually say\. We are all amazing individuals,
          118  +    but none among us are mind readers\. If you find yourself responding to what
          119  +    you imagine someone is thinking, odds are you are going to be wrong\.
          120  +
          121  +    If you must criticize someone, stick to things they have actually done\.
          122  +    Never criticize for something you speculate they have done\. Or imagine they
          123  +    have done\. Or something someone who shares some attribute with them has done
          124  +    in the past\.
          125  +
          126  +    Keep discussions about any non\-Tcl subjects to what can be stated factually
          127  +    and without emotion or judgement\.
          128  +
          129  +  - When Trouble Arises, Don’t Escalate
          130  +
          131  +    If you feel you are being personally attacked or offended, take the high
          132  +    road\. Punching back in a public forum will only makes things worse\. Address
          133  +    the matter in a private correspondence\. Be polite\. Express your feelings,
          134  +    but note that you are expressing your feelings\. When writing, look for a way
          135  +    to calm matters down\. And when in doubt, sleep on your letter before
          136  +    pressing send\. And when not in doubt, sleep on it for another day after
          137  +    that\.
          138  +
          139  +    If you are a spectator to a fight in progress, politely request the two
          140  +    parties take the matter to a more private forum\.
          141  +
          142  +  - Always get the Last Word: I’m Sorry
          143  +
          144  +    If an personal argument does arise, be the first to apologize\. An apology
          145  +    does not concede a logical point\. It merely acknowledges that at some point
          146  +    the discussion left either logic, community decency, or both\. Return to the
          147  +    topic when cooler heads can prevail\.
          148  +
          149  +  - Nobody is Keeping Score
          150  +
          151  +    There is no prize for being right\. There is no cost for being wrong\. A hard
          152  +    sell is not going to advance your idea along any more than a logical
          153  +    argument\. You aren’t running for office\. This isn’t debate club\. If you find
          154  +    yourself continuing a discussion beyond where a topic can be logically
          155  +    discussed, stop\.
          156  +
          157  +  - No Evangelizing
          158  +
          159  +    The Tcl Community is not the place to promote your chosen operating system,
          160  +    political outlook, religion, marketing scheme, or economic model\. Period\.
          161  +
          162  +    \(And if you do bring it up, be prepared to have your chosen topic discussed
          163  +    logically\. And odds are, not favorably\.\)
          164  +
          165  +  - Respect the Community
          166  +
          167  +    If the Community has come to a decision on a course of action, please stop
          168  +    arguing\.
          169  +
          170  +    If someone complains about how you are expressing your ideas, listen\.
          171  +
          172  +    If your words are hurting people, stop\. There is no amount of being "right"
          173  +    that makes up for someone leaving our midst because they felt insulted,
          174  +    threatened, or ignored\.
          175  +
          176  +By following these guidelines, we will build our community, encourage more
          177  +contribution to our projects, and our discussions will be friendlier and reach
          178  +conclusions more easily\.
          179  +
          180  +Thank You\.
          181  +
          182  +# <a name='section2'></a>Signatories
          183  +
          184  +  - Sean "the Hypnotoad" Woods
          185  +
          186  +  - Andreas Kupries
          187  +
          188  +# <a name='section3'></a>Authors
          189  +
          190  +  - Primary
          191  +
          192  +    Sean "the Hypnotoad" Woods
          193  +
          194  +  - Light editing
          195  +
          196  +    Andreas Kupries

Added embedded/md/tcllib/files/devdoc/tcllib_devguide.md.

            1  +
            2  +[//000000001]: # (tcllib\_devguide \- )
            3  +[//000000002]: # (Generated from file 'tcllib\_devguide\.man' by tcllib/doctools with format 'markdown')
            4  +[//000000003]: # (tcllib\_devguide\(n\) 1 tcllib "")
            5  +
            6  +<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
            7  +href="../../toc.md">Table Of Contents</a> &#124; <a
            8  +href="../../../index.md">Keyword Index</a> &#124; <a
            9  +href="../../../toc0.md">Categories</a> &#124; <a
           10  +href="../../../toc1.md">Modules</a> &#124; <a
           11  +href="../../../toc2.md">Applications</a> ] <hr>
           12  +
           13  +# NAME
           14  +
           15  +tcllib\_devguide \- Tcllib \- The Developer's Guide
           16  +
           17  +# <a name='toc'></a>Table Of Contents
           18  +
           19  +  - [Table Of Contents](#toc)
           20  +
           21  +  - [Synopsis](#synopsis)
           22  +
           23  +  - [Description](#section1)
           24  +
           25  +  - [Commitments](#section2)
           26  +
           27  +      - [Contributor](#subsection1)
           28  +
           29  +      - [Maintainer](#subsection2)
           30  +
           31  +  - [Branching and Workflow](#section3)
           32  +
           33  +      - [Package Dependencies](#subsection3)
           34  +
           35  +      - [Trunk](#subsection4)
           36  +
           37  +      - [Branches](#subsection5)
           38  +
           39  +      - [Working with Branches](#subsection6)
           40  +
           41  +      - [Version numbers](#subsection7)
           42  +
           43  +  - [Structural Overview](#section4)
           44  +
           45  +      - [Main Directories](#subsection8)
           46  +
           47  +      - [More Directories](#subsection9)
           48  +
           49  +      - [Top Files](#subsection10)
           50  +
           51  +      - [File Types](#subsection11)
           52  +
           53  +  - [Testsuite Tooling](#section5)
           54  +
           55  +      - [Invoke the testsuites of a specific module](#subsection12)
           56  +
           57  +      - [Invoke the testsuites of all modules](#subsection13)
           58  +
           59  +      - [Detailed Test Logs](#subsection14)
           60  +
           61  +      - [Shell Selection](#subsection15)
           62  +
           63  +      - [Help](#subsection16)
           64  +
           65  +  - [Documentation Tooling](#section6)
           66  +
           67  +      - [Generate documentation for a specific module](#subsection17)
           68  +
           69  +      - [Generate documentation for all modules](#subsection18)
           70  +
           71  +      - [Available output formats, help](#subsection19)
           72  +
           73  +      - [Validation without output](#subsection20)
           74  +
           75  +  - [Notes On Writing A Testsuite](#section7)
           76  +
           77  +  - [Installation Tooling](#section8)
           78  +
           79  +# <a name='synopsis'></a>SYNOPSIS
           80  +
           81  +[__[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action*](#1)  
           82  +[__[Application](\.\./\.\./\.\./index\.md\#application)__ *name*](#2)  
           83  +[__Exclude__ *name*](#3)  
           84  +
           85  +# <a name='description'></a>DESCRIPTION
           86  +
           87  +Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
           88  +itself\. It is a collection of \(semi\-independent\)
           89  +*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
           90  +useful to a large collection of Tcl programmers\.
           91  +
           92  +This document is a guide for developers working on Tcllib, i\.e\. maintainers
           93  +fixing bugs, extending the collection's functionality, etc\.
           94  +
           95  +Please read
           96  +
           97  +  1. *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* and
           98  +
           99  +  1. *[Tcllib \- The Installer's Guide](tcllib\_installer\.md)*
          100  +
          101  +first, if that was not done already\.
          102  +
          103  +Here we assume that the sources are already available in a directory of your
          104  +choice, and that you not only know how to build and install them, but also have
          105  +all the necessary requisites to actually do so\. The guide to the sources in
          106  +particular also explains which source code management system is used, where to
          107  +find it, how to set it up, etc\.
          108  +
          109  +# <a name='section2'></a>Commitments
          110  +
          111  +## <a name='subsection1'></a>Contributor
          112  +
          113  +As a contributor to Tcllib you are committing yourself to:
          114  +
          115  +  1. keep the guidelines written down in *[Tcl Community \- Kind
          116  +     Communication](tcl\_community\_communication\.md)* in your mind\. The main
          117  +     point to take away from there is *to be kind to each other*\.
          118  +
          119  +  1. Your contributions getting distributed under a BSD/MIT license\. For the
          120  +     details see *[Tcllib \- License](tcllib\_license\.md)*
          121  +
          122  +Contributions are made by entering tickets into our tracker, providing patches,
          123  +bundles or branches of code for inclusion, or posting to the Tcllib related
          124  +mailing lists\.
          125  +
          126  +## <a name='subsection2'></a>Maintainer
          127  +
          128  +When contributing one or more packages for full inclusion into Tcllib you are
          129  +committing yourself to
          130  +
          131  +  1. Keep the guidelines written down in *[Tcl Community \- Kind
          132  +     Communication](tcl\_community\_communication\.md)* \(as any contributor\) in
          133  +     your mind\. The main point to take away from there is *to be kind to each
          134  +     other*\.
          135  +
          136  +  1. Your packages getting distributed under a BSD/MIT license\. For the details
          137  +     see *[Tcllib \- License](tcllib\_license\.md)*
          138  +
          139  +  1. Maintenance of the new packages for a period of two years under the
          140  +     following rules, and responsibilities:
          141  +
          142  +       1) A maintainer may step down after the mandatory period as they see fit\.
          143  +
          144  +       1) A maintainer may step down before the end of the mandatory period,
          145  +          under the condition that a replacement maintainer is immediately
          146  +          available and has agreed to serve the remainder of the period, plus
          147  +          their own mandatory period \(see below\)\.
          148  +
          149  +       1) When stepping down without a replacement maintainer taking over the
          150  +          relevant packages have to be flagged as __unmaintained__\.
          151  +
          152  +       1) When a replacement mantainer is brought in for a package it is \(kept\)
          153  +          marked as __maintained__ \(again\)\.
          154  +
          155  +          A replacement maintainer is bound by the same rules as the original
          156  +          maintainer, except that the mandatory period of maintenance is
          157  +          shortened to one year\.
          158  +
          159  +       1) For any __unmaintained__ package a contributor interested in
          160  +          becoming its maintainer can become so by flagging them as
          161  +          __maintained__ with their name and contact information, committing
          162  +          themselves to the rules of a replacement maintainer \(see previous
          163  +          point\)\.
          164  +
          165  +       1) For any already __maintained__ package a contributor interested in
          166  +          becoming a co\-maintainer can become so with the agreement of the
          167  +          existing maintainer\(s\), committing themselves to the rules of a
          168  +          replacement maintainer \(see two points previous\)\.
          169  +
          170  +     The responsibilities as a maintainer include:
          171  +
          172  +       1) Watching Tcllib's ticket tracker for bugs, bug fixes, and feature
          173  +          requests related to the new packages\.
          174  +
          175  +       1) Reviewing the aforementioned tickets, rejecting or applying them
          176  +
          177  +       1) Coordination and discussion with ticket submitter during the
          178  +          development and/or application of bug fixes\.
          179  +
          180  +  1. Follow the [Branching and Workflow](#section3) of this guide\.
          181  +
          182  +# <a name='section3'></a>Branching and Workflow
          183  +
          184  +## <a name='subsection3'></a>Package Dependencies
          185  +
          186  +Regarding packages and dependencies between them Tcllib occupies a middle
          187  +position between two extremes:
          188  +
          189  +  1. On one side a strongly interdependent set of packages, usually by a single
          190  +     author, for a single project\. Looking at my \(Andreas Kupries\) own work
          191  +     examples of such are [Marpa](https://core\.tcl\.tk/akupries/marpa/index),
          192  +     [CRIMP](https://core\.tcl\.tk/akupries/crimp/index),
          193  +     [Kinetcl](https://core\.tcl\.tk/akupries/kinetcl/index), etc\.
          194  +
          195  +     For every change the author of the project handles all the modifications
          196  +     cascading from any incompatibilities it introduced to the system\.
          197  +
          198  +  1. On the other side, the world of semi\-independent projects by many different
          199  +     authors where authors know what packages their own creations depend on, yet
          200  +     usually do not know who else depends on them\.
          201  +
          202  +     The best thing an author making an \(incompatible\) change to their project
          203  +     can do is to for one announce such changes in some way, and for two use
          204  +     versioning to distinguish the code before and after the change\.
          205  +
          206  +     The world is then responsible for adapting, be it by updating their own
          207  +     projects to the new version, or by sticking to the old\.
          208  +
          209  +As mentioned already, Tcllib lives in the middle of that\.
          210  +
          211  +While we as maintainers cannot be aware of all users of Tcllib's packages, and
          212  +thus have to rely on the mechanisms touched on in point 2 above for that, the
          213  +dependencies between the packages contained in Tcllib are a different matter\.
          214  +
          215  +As we are collectively responsible for the usability of Tcllib in toto to the
          216  +outside world, it behooves us to be individually mindful even of Tcllib packages
          217  +we are not directly maintaining, when they depend on packages under our
          218  +maintainership\. This may be as simple as coordinating with the maintainers of
          219  +the affected packages\. It may also require us to choose how to adapt affected
          220  +packages which do not have maintainers, i\.e\. modify them to use our changed
          221  +package properly, or modify them to properly depend on the unchanged version of
          222  +our package\.
          223  +
          224  +Note that the above is not only a chore but an opportunity as well\. Additional
          225  +insight can be had by forcing ourselves to look at our package and the planned
          226  +change\(s\) from an outside perspective, to consider the ramifications of our
          227  +actions on others in general, and on dependent packages in particular\.
          228  +
          229  +## <a name='subsection4'></a>Trunk
          230  +
          231  +The management and use of branches is an important part of working with a
          232  +*Distributed Version Control System* \(*DVCS*\) like
          233  +[fossil](https://www\.fossil\-scm\.org/)\.
          234  +
          235  +For Tcllib the main branch of the collection is *trunk*\. In *git* this
          236  +branch would be called *master*, and this is exactly the case in the [github
          237  +mirror](https://github\.com/tcltk/tcllib/) of Tcllib\.
          238  +
          239  +To properly support debugging *each commit* on this branch *has to pass the
          240  +entire testsuite* of the collection\. Using bisection to determine when an issue
          241  +appeared is an example of an action made easier by this constraint\.
          242  +
          243  +This is part of our collective responsibility for the usability of Tcllib in
          244  +toto to the outside world\. As *fossil* has no mechanism to enforce this
          245  +condition this is handled on the honor system for developers and maintainers\.
          246  +
          247  +To make the task easier Tcllib comes with a tool \("sak\.tcl"\) providing a number
          248  +of commands in support\. These commands are explained in the following sections
          249  +of this guide\.
          250  +
          251  +While it is possible and allowed to commit directly to trunk remember the above
          252  +constraint regarding the testsuite, and the coming notes about other possible
          253  +issues with a commit\.
          254  +
          255  +## <a name='subsection5'></a>Branches
          256  +
          257  +Given the constraints placed on the *trunk* branch of the repository it is
          258  +\(strongly\) recommended to perform any development going beyond trivial changes
          259  +on a non\-trunk branch\.
          260  +
          261  +Outside of the trunk developers are allowed to commit intermediate broken states
          262  +of their work\. Only at the end of a development cycle, when the relevant branch
          263  +is considered ready for merging, will it be necessary to perform full the set of
          264  +validations ensuring that the merge to come will create a good commit on trunk\.
          265  +
          266  +Note that while a review from a second developer is not a required condition for
          267  +merging a branch it is recommended to seek out such an independent opinion as a
          268  +means of cross\-checking the work\.
          269  +
          270  +It also recommended to give any new branch a name which aids in determining
          271  +additional details about it\. Examples of good things to stick into a branch name
          272  +would be
          273  +
          274  +  - Developer \(nick\)name
          275  +
          276  +  - Ticket hash/reference
          277  +
          278  +  - One or two keywords applicable to the work
          279  +
          280  +  - \.\.\.
          281  +
          282  +Further, while most development branches are likely quite short\-lived, no
          283  +prohibitions exist against making longer\-lived branches\. Creators should however
          284  +be mindful that the longer such a branch exists without merges the more
          285  +divergent they will tend to be, with an associated increase in the effort which
          286  +will have to be spent on either merging from and merging to trunk\.
          287  +
          288  +## <a name='subsection6'></a>Working with Branches
          289  +
          290  +In the hope of engendering good work practices now a few example operations
          291  +which will come up with branches, and their associated fossil command
          292  +\(sequences\)\.
          293  +
          294  +  - *Awareness*
          295  +
          296  +    When developing we have to keep ourselves aware of the context of our work\.
          297  +    On what branch are we ? What files have we changed ? What new files are not
          298  +    yet known to the repository ? What has happened remotely since we used our
          299  +    checkout ? The answers to these questions become especially important when
          300  +    using a long\-lived checkout and coming back to it after some time away\.
          301  +
          302  +    Commands to answer questions like the above are:
          303  +
          304  +      * __fossil pull__
          305  +
          306  +        Get all changes done on the remote since the last pull or sync from it\.
          307  +        This has to be done first, before any of the commands below\.
          308  +
          309  +        Even if the commit in our checkout refers to the branch we want right
          310  +        now control operations committed to the remote may have changed that
          311  +        from underneath us\.
          312  +
          313  +      * __fossil info &#124; grep tags__
          314  +
          315  +      * __fossil branch list &#124; grep '\\\*'__
          316  +
          317  +        Two different ways of determining the branch our checkout is on\.
          318  +
          319  +      * __fossil timeline__
          320  +
          321  +        What have we \(and others\) done recently ?
          322  +
          323  +        *Attention*, this information is very likely outdated, the more the
          324  +        longer we did not use this checkout\. Run __fossil pull__ first to
          325  +        get latest information from the remote repository of the project\.
          326  +
          327  +      * __fossil timeline current__
          328  +
          329  +        Place the commit our checkout is based on at the top of the timeline\.
          330  +
          331  +      * __fossil changes__
          332  +
          333  +        Lists the files we have changed compared to the commit the checkout is
          334  +        based on\.
          335  +
          336  +      * __fossil extra__
          337  +
          338  +        Lists the files we have in the checkout the repository does not know
          339  +        about\. This may be leftover chaff from our work, or something we have
          340  +        forgotten to __fossil add__ to the repository yet\.
          341  +
          342  +  - *Clean checkouts*
          343  +
          344  +    Be aware of where you are \(see first definition\)\.
          345  +
          346  +    For pretty much all the operation recipes below a clean checkout is at least
          347  +    desired, often required\. To check that a checkout is clean invoke
          348  +
          349  +        fossil changes
          350  +        fossil extra
          351  +
          352  +    How to clean up when uncommitted changes of all sorts are found is
          353  +    context\-specific and outside of the scope of this guide\.
          354  +
          355  +  - *Starting a new branch*
          356  +
          357  +    Be aware of where you are \(see first definition\)\.
          358  +
          359  +    Ensure that you have clean checkout \(see second definition\)\. It is
          360  +    *required*\.
          361  +
          362  +    In most situations you want to be on branch *trunk*, and you want to be on
          363  +    the latest commit for it\. To get there use
          364  +
          365  +        fossil pull
          366  +        fossil update trunk
          367  +
          368  +    If some other branch is desired as the starting point for the coming work
          369  +    replace *trunk* in the commands above with the name of that branch\.
          370  +
          371  +    With the base line established we now have two ways of creating the new
          372  +    branch, with differing \(dis\)advantages\. The simpler way is to
          373  +
          374  +        fossil branch new NAME_OF_NEW_BRANCH
          375  +
          376  +    and start developing\. The advantage here is that you cannot forget to create
          377  +    the branch\. The disadvantages are that we have a branch commit unchanged
          378  +    from where we branched from, and that we have to use high\-handed techniques
          379  +    like hiding or shunning to get rid of the commit should we decide to abandon
          380  +    the work before the first actual commit on the branch\.
          381  +
          382  +    The other way of creating the branch is to start developing, and then on the
          383  +    first commit use the option __\-\-branch__ to tell __fossil__ that we
          384  +    are starting a branch now\. I\.e\. run
          385  +
          386  +        fossil commit --branch NAME_OF_NEW_BRANCH ...
          387  +
          388  +    where *\.\.\.* are any other options used to supply the commit message, files
          389  +    to commit, etc\.
          390  +
          391  +    The \(dis\)advantages are now reversed\.
          392  +
          393  +    We have no superflous commit, only what is actually developed\. The work is
          394  +    hidden until we commit to make our first commit\.
          395  +
          396  +    We may forget to use __\-\-branch NAME\_OF\_NEW\_BRANCH__ and then have to
          397  +    correct that oversight via the fossil web interface \(I am currently unaware
          398  +    of ways of doing such from the command line, although some magic
          399  +    incantantion of __fossil tag create__ may work\)\.
          400  +
          401  +    It helps to keep awareness, like checking before any commit that we are on
          402  +    the desired branch\.
          403  +
          404  +  - *Merging a branch into trunk*
          405  +
          406  +    Be aware of where you are \(see first definition\)\.
          407  +
          408  +    Ensure that you have clean checkout \(see second definition\)\. In the
          409  +    full\-blown sequence \(zig\-zag\) it is *required*, due to the merging from
          410  +    trunk\. In the shorter sequence it is only desired\. That said, keeping the
          411  +    checkout clean before any major operations is a good habit to have, in my
          412  +    opinion\.
          413  +
          414  +    The full\-blown sequencing with checks all the way is to
          415  +
          416  +      1. Validate the checkout, i\.e\. last commit on your branch\. Run the full
          417  +         test suite and other validations, fix all the issues which have cropped
          418  +         up\.
          419  +
          420  +      1. Merge the latest state of the *trunk* \(see next definition\)\.
          421  +
          422  +      1. Validate the checkout again\. The incoming trunk changes may have broken
          423  +         something now\. Do any required fixes\.
          424  +
          425  +      1. Now merge to the trunk using
          426  +
          427  +             fossil update trunk
          428  +             fossil merge --integrate YOUR_BRANCH
          429  +
          430  +      1. At this point the checkout should be in the same state as at the end of
          431  +         point \(3\) above, because we resolved any issues with the trunk already\.
          432  +         Thus a simple
          433  +
          434  +             fossil commit ...
          435  +
          436  +         should be sufficient now to commit the merge back and close the branch
          437  +         \(due to the __\-\-integrate__ we used on the merge\)\.
          438  +
          439  +         The more paranoid may validate the checkout a third time before
          440  +         commiting\.
          441  +
          442  +    I call this a *zig\-zag merge* because of how the arrows look in the
          443  +    timeline, from trunk to feature branch for the first merge, and then back
          444  +    for the final merge\.
          445  +
          446  +    A less paranoid can do what I call a *simple merge*, which moves step \(2\)
          447  +    after step \(4\) and skips step \(3\) entirely\. The resulting shorter sequence
          448  +    is
          449  +
          450  +      1. Validate
          451  +
          452  +      1. Merge to trunk
          453  +
          454  +      1. Validate again
          455  +
          456  +      1. Commit to trunk
          457  +
          458  +    The last step after either zig\-zag or plain merge is to
          459  +
          460  +        fossil sync
          461  +
          462  +    This saves our work to the remote side, and further gives us any other work
          463  +    done while we were doing our merge\. It especially allows us to check if we
          464  +    raced somebody else, resulting in a split trunk\.
          465  +
          466  +    When that happens we should coordinate with the other developer on who fixes
          467  +    the split, to ensure that we do not race each other again\.
          468  +
          469  +  - *Merging from trunk*
          470  +
          471  +    Be aware of where you are \(see first definition\)\.
          472  +
          473  +    Ensure that you have clean checkout \(see second definition\)\. It is
          474  +    *required*\.
          475  +
          476  +    In most situations you want to import the latest commit of branch *trunk*
          477  +    \(or other origin\)\. To get it use
          478  +
          479  +        fossil pull
          480  +
          481  +    With that done we can now import this commit into our current branch with
          482  +
          483  +        fossil merge trunk
          484  +
          485  +    Even if __fossil__ does not report any conflicts it is a good idea to
          486  +    check that the operation has not broken the new and/or changed functionality
          487  +    we are working on\.
          488  +
          489  +    With the establishment of a good merge we then save the state with
          490  +
          491  +        fossil commit ...
          492  +
          493  +    before continuing development\.
          494  +
          495  +## <a name='subsection7'></a>Version numbers
          496  +
          497  +In Tcllib all changes to a package have to come with an increment of its version
          498  +number\. What part is incremented \(patchlevel, minor, major version\) depends on
          499  +the kind of change made\. With multiple changes in a commit the highest "wins"\.
          500  +
          501  +When working in a development branch the version change can be deferred until it
          502  +is time to merge, and then has to cover all the changes in the branch\.
          503  +
          504  +Below a list of the kinds of changes and their associated version increments:
          505  +
          506  +  - *D \- documentation*
          507  +
          508  +    No increment
          509  +
          510  +  - *T \- testsuite*
          511  +
          512  +    No increment
          513  +
          514  +  - *B \- bugfix*
          515  +
          516  +    Patchlevel
          517  +
          518  +  - *I \- implementation tweak*
          519  +
          520  +    Patchlevel
          521  +
          522  +  - *P \- performance tweak*
          523  +
          524  +    Patchlevel
          525  +
          526  +  - *E \- backward\-compatible extension*
          527  +
          528  +    Minor
          529  +
          530  +  - *API \- incompatible change*
          531  +
          532  +    Major
          533  +
          534  +Note that a commit containing a version increment has to mention the new version
          535  +number in its commit message, as well as the kind of change which caused it\.
          536  +
          537  +Note further that the version number of a package currently exists in three
          538  +places\. An increment has to update all of them:
          539  +
          540  +  1. The package implementation\.
          541  +
          542  +  1. The package index \("pkgIndex\.tcl"\)
          543  +
          544  +  1. The package documentation\.
          545  +
          546  +The "sak\.tcl" command __validate version__ helps finding discrepancies
          547  +between the first two\. All the other __validate__ methods are also of
          548  +interest to any developer\. Invoke it with
          549  +
          550  +    sak.tcl help validate
          551  +
          552  +to see their documentation\.
          553  +
          554  +# <a name='section4'></a>Structural Overview
          555  +
          556  +## <a name='subsection8'></a>Main Directories
          557  +
          558  +The main directories in the Tcllib toplevel directory and of interest to a
          559  +developer are:
          560  +
          561  +  - "modules"
          562  +
          563  +    Each child directory represents one or more packages\. In the case of the
          564  +    latter the packages are usually related in some way\. Examples are "base64",
          565  +    "math", and "struct", with loose \(base64\) to strong \(math\) relations between
          566  +    the packages in the directory\.
          567  +
          568  +  - "apps"
          569  +
          570  +    This directory contains all the installable applications, with their
          571  +    documentation\. Note that this directory is currently *not* split into
          572  +    sub\-directories\.
          573  +
          574  +  - "examples"
          575  +
          576  +    Each child directory "foo" contains one or more example application for the
          577  +    packages in "modules/foo"\. These examples are generally not polished enough
          578  +    to be considered for installation\.
          579  +
          580  +## <a name='subsection9'></a>More Directories
          581  +
          582  +  - "config"
          583  +
          584  +    This directory contains files supporting the Unix build system, i\.e\.
          585  +    "configure" and "Makefile\.in"\.
          586  +
          587  +  - "devdoc"
          588  +
          589  +    This directories contains the doctools sources for the global documentation,
          590  +    like this document and its sibling guides\.
          591  +
          592  +  - "embedded"
          593  +
          594  +    This directory contains the entire documentation formatted for
          595  +    *[HTML](\.\./\.\./\.\./index\.md\#html)* and styled to properly mix into the
          596  +    web site generated by fossil for the repository\.
          597  +
          598  +    This is the documentation accessible from the Tcllib home directory,
          599  +    represented in the repository as "embedded/index\.md"\.
          600  +
          601  +  - "idoc"
          602  +
          603  +    This directory contains the entire documentation formatted for
          604  +    *[nroff](\.\./\.\./\.\./index\.md\#nroff)* and
          605  +    *[HTML](\.\./\.\./\.\./index\.md\#html)*, the latter without any styling\. This
          606  +    is the documentation which will be installed\.
          607  +
          608  +  - "support"
          609  +
          610  +    This directory contains the sources of internal packages and utilities used
          611  +    in the implementation of the "installer\.tcl" and "sak\.tcl" scripts/tools\.
          612  +
          613  +## <a name='subsection10'></a>Top Files
          614  +
          615  +  - "aclocal\.m4"
          616  +
          617  +  - "configure"
          618  +
          619  +  - "configure\.in"
          620  +
          621  +  - "Makefile\.in"
          622  +
          623  +    These four files comprise the Unix build system layered on top of the
          624  +    "installer\.tcl" script\.
          625  +
          626  +  - "installer\.tcl"
          627  +
          628  +    The Tcl\-based installation script/tool\.
          629  +
          630  +  - "project\.shed"
          631  +
          632  +    Configuration file for *Sean Wood*'s
          633  +    __[PracTcl](\.\./modules/practcl/practcl\.md)__ buildsystem\.
          634  +
          635  +  - "sak\.tcl"
          636  +
          637  +    This is the main tool for developers and release managers, the *Swiss Army
          638  +    Knife* of management operations on the collection\.
          639  +
          640  +  - "ChangeLog"
          641  +
          642  +    The log of changes to the global support, when the sources were held in
          643  +    *[CVS](\.\./\.\./\.\./index\.md\#cvs)*\. Not relevant any longer with the
          644  +    switch to the *fossil* SCM\.
          645  +
          646  +  - "license\.terms"
          647  +
          648  +    The license in plain ASCII\. See also *[Tcllib \-
          649  +    License](tcllib\_license\.md)* for the nicely formatted form\. The text is
          650  +    identical\.
          651  +
          652  +  - "README\.md"
          653  +
          654  +  - "\.github/CONTRIBUTING\.md"
          655  +
          656  +  - "\.github/ISSUE\_TEMPLATE\.md"
          657  +
          658  +  - "\.github/PULL\_REQUEST\_TEMPLATE\.md"
          659  +
          660  +    These markdown\-formatted documents are used and shown by the github mirror
          661  +    of these sources, pointing people back to the official location and issue
          662  +    trackers\.
          663  +
          664  +  - "DESCRIPTION\.txt"
          665  +
          666  +  - "STATUS"
          667  +
          668  +  - "tcllib\.spec"
          669  +
          670  +  - "tcllib\.tap"
          671  +
          672  +  - "tcllib\.yml"
          673  +
          674  +    ????
          675  +
          676  +## <a name='subsection11'></a>File Types
          677  +
          678  +The most common file types, by file extension, are:
          679  +
          680  +  - "\.tcl"
          681  +
          682  +    Tcl code for a package, application, or example\.
          683  +
          684  +  - "\.man"
          685  +
          686  +    Doctools\-formatted documentation, usually for a package\.
          687  +
          688  +  - "\.test"
          689  +
          690  +    Test suite for a package, or part of\. Based on __tcltest__\.
          691  +
          692  +  - "\.bench"
          693  +
          694  +    Performance benchmarks for a package, or part of\. Based on "modules/bench"\.
          695  +
          696  +  - "\.pcx"
          697  +
          698  +    Syntax rules for *TclDevKit*'s __tclchecker__\. Using these rules
          699  +    allows the checker to validate the use of commands of a Tcllib package
          700  +    __foo__ without having to scan the "\.tcl" files implementing it\.
          701  +
          702  +# <a name='section5'></a>Testsuite Tooling
          703  +
          704  +Testsuites in Tcllib are based on Tcl's standard test package __tcltest__,
          705  +plus utilities found in the directory "modules/devtools"
          706  +
          707  +Tcllib developers invoke the suites through the __test run__ method of the
          708  +"sak\.tcl" tool, with other methods of __[test](\.\./\.\./\.\./index\.md\#test)__
          709  +providing management operations, for example setting a list of standard Tcl
          710  +shells to use\.
          711  +
          712  +## <a name='subsection12'></a>Invoke the testsuites of a specific module
          713  +
          714  +Invoke either
          715  +
          716  +    ./sak.tcl test run foo
          717  +
          718  +or
          719  +
          720  +    ./sak.tcl test run modules/foo
          721  +
          722  +to invoke the testsuites found in a specific module "foo"\.
          723  +
          724  +## <a name='subsection13'></a>Invoke the testsuites of all modules
          725  +
          726  +Invoke the tool without a module name, i\.e\.
          727  +
          728  +    ./sak.tcl test run
          729  +
          730  +to invoke the testsuites of all modules\.
          731  +
          732  +## <a name='subsection14'></a>Detailed Test Logs
          733  +
          734  +In all the previous examples the test runner will write a combination of
          735  +progress display and testsuite log to the standard output, showing for each
          736  +module only the tests that passed or failed and how many of each in a summary at
          737  +the end\.
          738  +
          739  +To get a detailed log, it is necessary to invoke the test runner with additional
          740  +options\.
          741  +
          742  +For one:
          743  +
          744  +    ./sak.tcl test run --log LOG foo
          745  +
          746  +While this shows the same short log on the terminal as before, it also writes a
          747  +detailed log to the file "LOG\.log", and excerpts to other files \("LOG\.summary",
          748  +"LOG\.failures", etc\.\)\.
          749  +
          750  +For two:
          751  +
          752  +    ./sak.tcl test run -v foo
          753  +
          754  +This writes the detailed log to the standard output, instead of the short log\.
          755  +
          756  +Regardless of form, the detailed log contains a list of all test cases executed,
          757  +which failed, and how they failed \(expected versus actual results\)\.
          758  +
          759  +## <a name='subsection15'></a>Shell Selection
          760  +
          761  +By default the test runner will use all the Tcl shells specified via __test
          762  +add__ to invoke the specified testsuites, if any\. If no such are specified it
          763  +will fall back to the Tcl shell used to run the tool itself\.
          764  +
          765  +Use option __\-\-shell__ to explicitly specify the Tcl shell to use, like
          766  +
          767  +    ./sak.tcl test run --shell /path/to/tclsh ...
          768  +
          769  +## <a name='subsection16'></a>Help
          770  +
          771  +Invoke the tool as
          772  +
          773  +    ./sak.tcl help test
          774  +
          775  +to see the detailed help for all methods of
          776  +__[test](\.\./\.\./\.\./index\.md\#test)__, and the associated options\.
          777  +
          778  +# <a name='section6'></a>Documentation Tooling
          779  +
          780  +The standard format used for documentation of packages and other things in
          781  +Tcllib is *[doctools](\.\./\.\./\.\./index\.md\#doctools)*\. Its supporting
          782  +packages are a part of Tcllib, see the directories "modules/doctools" and
          783  +"modules/dtplite"\. The latter is an application package, with the actual
          784  +application "apps/dtplite" a light wrapper around it\.
          785  +
          786  +Tcllib developers gain access to these through the __doc__ method of the
          787  +"sak\.tcl" tool, another \(internal\) wrapper around the "modules/dtplite"
          788  +application package\.
          789  +
          790  +## <a name='subsection17'></a>Generate documentation for a specific module
          791  +
          792  +Invoke either
          793  +
          794  +    ./sak.tcl doc html foo
          795  +
          796  +or
          797  +
          798  +    ./sak.tcl doc html modules/foo
          799  +
          800  +to generate HTML for the documentation found in the module "foo"\. Instead of
          801  +__html__ any other supported format can be used here, of course\.
          802  +
          803  +The generated formatted documentation will be placed into a directory "doc" in
          804  +the current working directory\.
          805  +
          806  +## <a name='subsection18'></a>Generate documentation for all modules
          807  +
          808  +Invoke the tool without a module name, i\.e\.
          809  +
          810  +    ./sak.tcl doc html
          811  +
          812  +to generate HTML for the documentation found in all modules\. Instead of
          813  +__html__ any other supported format can be used here, of course\.
          814  +
          815  +The generated formatted documentation will be placed into a directory "doc" in
          816  +the current working directory\.
          817  +
          818  +## <a name='subsection19'></a>Available output formats, help
          819  +
          820  +Invoke the tool as
          821  +
          822  +    ./sak.tcl help doc
          823  +
          824  +to see the entire set of supported output formats which can be generated\.
          825  +
          826  +## <a name='subsection20'></a>Validation without output
          827  +
          828  +Note the special format __validate__\.
          829  +
          830  +Using this value as the name of the format to generate forces the tool to simply
          831  +check that the documentation is syntactically correct, without generating actual
          832  +output\.
          833  +
          834  +Invoke it as either
          835  +
          836  +    ./sak.tcl doc validate (modules/)foo
          837  +
          838  +or
          839  +
          840  +    ./sak.tcl doc validate
          841  +
          842  +to either check the packages of a specific module or check all of them\.
          843  +
          844  +# <a name='section7'></a>Notes On Writing A Testsuite
          845  +
          846  +While previous sections talked about running the testsuites for a module and the
          847  +packages therein, this has no meaning if the module in question has no
          848  +testsuites at all\.
          849  +
          850  +This section gives a very basic overview on possible methodologies for writing
          851  +tests and testsuites\.
          852  +
          853  +First there are "drudgery" tests\. Written to check absolutely basic assumptions
          854  +which should never fail\.
          855  +
          856  +For example for a command FOO taking two arguments, three tests calling it with
          857  +zero, one, and three arguments\. The basic checks that the command fails if it
          858  +has not enough arguments, or too many\.
          859  +
          860  +After that come the tests checking things based on our knowledge of the command,
          861  +about its properties and assumptions\. Some examples based on the graph
          862  +operations added during Google's Summer of Code 2009 are:
          863  +
          864  +  - The BellmanFord command in struct::graph::ops takes a *startnode* as
          865  +    argument, and this node should be a node of the graph\. This equals one test
          866  +    case checking the behavior when the specified node is not a node of the
          867  +    graph\.
          868  +
          869  +    This often gives rise to code in the implementation which explicitly checks
          870  +    the assumption and throws an understandable error, instead of letting the
          871  +    algorithm fail later in some weird non\-deterministic way\.
          872  +
          873  +    It is not always possible to do such checks\. The graph argument for example
          874  +    is just a command in itself, and while we expect it to exhibit a certain
          875  +    interface, i\.e\. a set of sub\-commands aka methods, we cannot check that it
          876  +    has them, except by actually trying to use them\. That is done by the
          877  +    algorithm anyway, so an explicit check is just overhead we can get by
          878  +    without\.
          879  +
          880  +  - IIRC one of the distinguishing characteristic of either BellmanFord and/or
          881  +    Johnson is that they are able to handle negative weights\. Whereas Dijkstra
          882  +    requires positive weights\.
          883  +
          884  +    This induces \(at least\) three testcases \.\.\. Graph with all positive weights,
          885  +    all negative, and a mix of positive and negative weights\. Thinking further
          886  +    does the algorithm handle the weight __0__ as well ? Another test case,
          887  +    or several, if we mix zero with positive and negative weights\.
          888  +
          889  +  - The two algorithms we are currently thinking about are about distances
          890  +    between nodes, and distance can be 'Inf'inity, i\.e\. nodes may not be
          891  +    connected\. This means that good test cases are
          892  +
          893  +      1. Strongly connected graph
          894  +
          895  +      1. Connected graph
          896  +
          897  +      1. Disconnected graph\.
          898  +
          899  +    At the extremes of strongly connected and disconnected we have the fully
          900  +    connected graphs and graphs without edges, only nodes, i\.e\. completely
          901  +    disconnected\.
          902  +
          903  +  - IIRC both of the algorithms take weighted arcs, and fill in a default if
          904  +    arcs are left unweighted in the input graph\.
          905  +
          906  +    This also induces three test cases:
          907  +
          908  +      1. Graph will all arcs with explicit weights\.
          909  +
          910  +      1. Graph without weights at all\.
          911  +
          912  +      1. Graph with mixture of weighted and unweighted graphs\.
          913  +
          914  +What was described above via examples is called *black\-box* testing\. Test
          915  +cases are designed and written based on the developer's knowledge of the
          916  +properties of the algorithm and its inputs, without referencing a particular
          917  +implementation\.
          918  +
          919  +Going further, a complement to *black\-box* testing is *white\-box*\. For this
          920  +we know the implementation of the algorithm, we look at it and design our tests
          921  +cases so that they force the code through all possible paths in the
          922  +implementation\. Wherever a decision is made we have a test case forcing a
          923  +specific direction of the decision, for all possible combinations and
          924  +directions\. It is easy to get a combinatorial explosion in the number of needed
          925  +test\-cases\.
          926  +
          927  +In practice I often hope that the black\-box tests I have made are enough to
          928  +cover all the paths, obviating the need for white\-box tests\.
          929  +
          930  +The above should be enough to make it clear that writing tests for an algorithm
          931  +takes at least as much time as coding the algorithm, and often more time\. Much
          932  +more time\. See for example also
          933  +[http://sqlite\.org/testing\.html](http://sqlite\.org/testing\.html), a writeup
          934  +on how the Sqlite database engine is tested\. Another article of interest might
          935  +be
          936  +[https://www\.researchgate\.net/publication/298896236](https://www\.researchgate\.net/publication/298896236)\.
          937  +While geared to a particular numerical algorithm it still shows that even a
          938  +simple\-looking algorithm can lead to an incredible number of test cases\.
          939  +
          940  +An interesting connection is to documentation\. In one direction, the properties
          941  +checked with black\-box testing are exactly the properties which should be
          942  +documented in the algorithm's man page\. And conversely, the documentation of the
          943  +properties of an algorithm makes a good reference to base the black\-box tests
          944  +on\.
          945  +
          946  +In practice test cases and documentation often get written together,
          947  +cross\-influencing each other\. And the actual writing of test cases is a mix of
          948  +black and white box, possibly influencing the implementation while writing the
          949  +tests\. Like writing a test for a condition like *startnode not in input graph*
          950  +serving as reminder to put a check for this condition into the code\.
          951  +
          952  +# <a name='section8'></a>Installation Tooling
          953  +
          954  +A last thing to consider when adding a new package to the collection is
          955  +installation\.
          956  +
          957  +How to *use* the "installer\.tcl" script is documented in *[Tcllib \- The
          958  +Installer's Guide](tcllib\_installer\.md)*\.
          959  +
          960  +Here we document how to extend said installer so that it may install new
          961  +package\(s\) and/or application\(s\)\.
          962  +
          963  +In most cases only a single file has to be modified, the
          964  +"support/installation/modules\.tcl" holding one command per module and
          965  +application to install\.
          966  +
          967  +The relevant commands are:
          968  +
          969  +  - <a name='1'></a>__[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action*
          970  +
          971  +    Install the packages of module *name*, found in "modules/*name*"\.
          972  +
          973  +    The *code\-action* is responsible for installing the packages and their
          974  +    index\. The system currently provides
          975  +
          976  +      * __\_tcl__
          977  +
          978  +        Copy all "\.tcl" files found in "modules/*name*" into the installation\.
          979  +
          980  +      * __\_tcr__
          981  +
          982  +        As __\_tcl__, copy the "\.tcl" files found in the subdirectories of
          983  +        "modules/*name*" as well\.
          984  +
          985  +      * __\_tci__
          986  +
          987  +        As __\_tcl__, and copy the "tclIndex\.tcl" file as well\.
          988  +
          989  +      * __\_msg__
          990  +
          991  +        As __\_tcl__, and copy the subdirectory "msgs" as well\.
          992  +
          993  +      * __\_doc__
          994  +
          995  +        As __\_tcl__, and copy the subdirectory "mpformats" as well\.
          996  +
          997  +      * __\_tex__
          998  +
          999  +        As __\_tcl__, and copy "\.tex" files as well\.
         1000  +
         1001  +    The *doc\-action* is responsible for installing the package documentation\.
         1002  +    The system currently provides
         1003  +
         1004  +      * __\_null__
         1005  +
         1006  +        No documentation available, do nothing\.
         1007  +
         1008  +      * __\_man__
         1009  +
         1010  +        Process the "\.man" files found in "modules/*name*" and install the
         1011  +        results \(nroff and/or HTML\) in the proper location, as given to the
         1012  +        installer\.
         1013  +
         1014  +        This is actually a fallback, normally the installer uses the pre\-made
         1015  +        formatted documentation found under "idoc"\.
         1016  +
         1017  +    The *example\-action* is responsible for installing the examples\. The
         1018  +    system currently provides
         1019  +
         1020  +      * __\_null__
         1021  +
         1022  +        No examples available, do nothing\.
         1023  +
         1024  +      * __\_exa__
         1025  +
         1026  +        Copy the the directory "examples/*name*" recursively to the install
         1027  +        location for examples\.
         1028  +
         1029  +  - <a name='2'></a>__[Application](\.\./\.\./\.\./index\.md\#application)__ *name*
         1030  +
         1031  +    Install the application with *name*, found in "apps"\.
         1032  +
         1033  +  - <a name='3'></a>__Exclude__ *name*
         1034  +
         1035  +    This command signals to the installer which of the listed modules to *not*
         1036  +    install\. I\.e\. they name the deprecated modules of Tcllib\.
         1037  +
         1038  +If, and only if the above actions are not suitable for the new module then a
         1039  +second file has to be modified, "support/installation/actions\.tcl"\.
         1040  +
         1041  +This file contains the implementations of the available actions, and is the
         1042  +place where any custom action needed to handle the special circumstances of
         1043  +module has to be added\.

Added embedded/md/tcllib/files/devdoc/tcllib_installer.md.

            1  +
            2  +[//000000001]: # (tcllib\_install\_guide \- )
            3  +[//000000002]: # (Generated from file 'tcllib\_installer\.man' by tcllib/doctools with format 'markdown')
            4  +[//000000003]: # (tcllib\_install\_guide\(n\) 1 tcllib "")
            5  +
            6  +<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
            7  +href="../../toc.md">Table Of Contents</a> &#124; <a
            8  +href="../../../index.md">Keyword Index</a> &#124; <a
            9  +href="../../../toc0.md">Categories</a> &#124; <a
           10  +href="../../../toc1.md">Modules</a> &#124; <a
           11  +href="../../../toc2.md">Applications</a> ] <hr>
           12  +
           13  +# NAME
           14  +
           15  +tcllib\_install\_guide \- Tcllib \- The Installer's Guide
           16  +
           17  +# <a name='toc'></a>Table Of Contents
           18  +
           19  +  - [Table Of Contents](#toc)
           20  +
           21  +  - [Description](#section1)
           22  +
           23  +  - [Requisites](#section2)
           24  +
           25  +      - [Tcl](#subsection1)
           26  +
           27  +      - [Critcl](#subsection2)
           28  +
           29  +  - [Build & Installation Instructions](#section3)
           30  +
           31  +      - [Installing on Unix](#subsection3)
           32  +
           33  +      - [Installing on Windows](#subsection4)
           34  +
           35  +      - [Critcl & Accelerators](#subsection5)
           36  +
           37  +      - [Tooling](#subsection6)
           38  +
           39  +# <a name='description'></a>DESCRIPTION
           40  +
           41  +Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
           42  +itself\. It is a collection of \(semi\-independent\)
           43  +*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
           44  +useful to a large collection of Tcl programmers\.
           45  +
           46  +The audience of this document is anyone wishing to build and install the
           47  +packages found in Tcllib, for either themselves, or others\.
           48  +
           49  +For developers intending to work on the packages themselves we additionally
           50  +provide
           51  +
           52  +  1. *[Tcllib \- The Developer's Guide](tcllib\_devguide\.md)*\.
           53  +
           54  +Please read *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* first,
           55  +if that was not done already\. Here we assume that the sources are already
           56  +available in a directory of your choice\.
           57  +
           58  +# <a name='section2'></a>Requisites
           59  +
           60  +Before Tcllib can be build and used a number of requisites must be installed\.
           61  +These are:
           62  +
           63  +  1. The scripting language Tcl\. For details see [Tcl](#subsection1)\.
           64  +
           65  +  1. Optionally, the __critcl__ package \(C embedding\) for
           66  +     __[Tcl](\.\./\.\./\.\./index\.md\#tcl)__\. For details see __CriTcl__\.
           67  +
           68  +This list assumes that the machine where Tcllib is to be installed is
           69  +essentially clean\. Of course, if parts of the dependencies listed below are
           70  +already installed the associated steps can be skipped\. It is still recommended
           71  +to read their sections though, to validate that the dependencies they talk about
           72  +are indeed installed\.
           73  +
           74  +## <a name='subsection1'></a>Tcl
           75  +
           76  +As we are installing a number of Tcl packages and applications it should be
           77  +pretty much obvious that a working installation of Tcl itself is needed, and I
           78  +will not belabor the point\.
           79  +
           80  +Out of the many possibilities use whatever you are comfortable with, as long as
           81  +it provides at the very least Tcl 8\.2, or higher\. This may be a Tcl installation
           82  +provided by your operating system distribution, from a distribution\-independent
           83  +vendor, or built by yourself\.
           84  +
           85  +*Note* that the packages in Tcllib have begun to require 8\.4, 8\.5, and even
           86  +8\.6\. Older versions of Tcl will not be able to use such packages\. Trying to use
           87  +them will result in *package not found* errors, as their package index files
           88  +will not register them in versions of the core unable to use them\.
           89  +
           90  +Myself, I used \(and still use\) [ActiveState's](http://www\.activestate\.com)
           91  +ActiveTcl 8\.5 distribution during development, as I am most familiar with it\.
           92  +
           93  +*\(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016,
           94  +maintaining ActiveTcl and TclDevKit for them\)\.*\. I am currently working for
           95  +SUSE Software Canada ULC, although not in Tcl\-related areas\.
           96  +
           97  +This distribution can be found at
           98  +[http://www\.activestate\.com/activetcl](http://www\.activestate\.com/activetcl)\.
           99  +Retrieve the archive of ActiveTcl 8\.5 \(or higher\) for your platform and install
          100  +it as directed by ActiveState\.
          101  +
          102  +For those wishing to build and install Tcl on their own, the relevant sources
          103  +can be found at
          104  +
          105  +  - Tcl
          106  +
          107  +    [http://core\.tcl\-lang\.org/tcl/](http://core\.tcl\-lang\.org/tcl/)
          108  +
          109  +together with the necessary instructions on how to build it\.
          110  +
          111  +If there are problems with building, installing, or using Tcl, please file a
          112  +ticket against *[Tcl](\.\./\.\./\.\./index\.md\#tcl)*, or the vendor of your
          113  +distribution, and *not* *[Tcllib](\.\./\.\./\.\./index\.md\#tcllib)*\.
          114  +
          115  +## <a name='subsection2'></a>Critcl
          116  +
          117  +The __critcl__ tool is an *optional* dependency\.
          118  +
          119  +It is only required when trying to build the C\-based *accelerators* for a
          120  +number of packages, as explained in [Critcl & Accelerators](#subsection5)
          121  +
          122  +Tcllib's build system looks for it in the , using the name __critcl__\. This
          123  +is for Unix\. On Windows on the other hand the search is more complex\. First we
          124  +look for a proper application __critcl\.exe__\. When that is not found we look
          125  +for a combination of interpreter \(__tclkitsh\.exe__, __tclsh\.exe__\) and
          126  +starkit \(__critcl\.kit__, __critcl__\) instead\. *Note* that the choice
          127  +of starkit can be overriden via the environment variable \.
          128  +
          129  +Tcllib requires Critcl version 2 or higher\.
          130  +
          131  +The github repository providing releases of version 2 and higher, and the
          132  +associated sources, can be found at
          133  +[http://andreas\-kupries\.github\.com/critcl](http://andreas\-kupries\.github\.com/critcl)\.
          134  +
          135  +Any branch of the repository can be used \(if not using the prebuild starkit or
          136  +starpack\), although the use of the stable branch *master* is recommended\.
          137  +
          138  +At the above url is also an explanation on how to build and install Critcl,
          139  +including a list of its dependencies\.
          140  +
          141  +Its instructions will not be repeated here\. If there are problems with these
          142  +directions please file a ticket against the *Critcl* project, and not Tcllib\.
          143  +
          144  +# <a name='section3'></a>Build & Installation Instructions
          145  +
          146  +As Tcllib is mainly a bundle of packages written in pure Tcl building it is the
          147  +same as installing it\. The exceptions to this have their own subsection,
          148  +[Critcl & Accelerators](#subsection5), later on\.
          149  +
          150  +Before that however comes the standard case, differentiated by the platforms
          151  +with material differences in the instruction, i\.e\. *Unix*\-like, versus
          152  +*Windows*\.
          153  +
          154  +Regarding the latter it should also be noted that it is possible set up an
          155  +*Unix*\-like environment using projects like *MSYS*, *Cygwin*, and others\.
          156  +In that case the user has the choice of which instructions to follow\.
          157  +
          158  +Regardless of environment or platform, a suitable
          159  +*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* has to be installed, and its __tclsh__
          160  +should be placed on the \(*Unix*\) or associated with "\.tcl" files
          161  +\(*Windows*\)\.
          162  +
          163  +## <a name='subsection3'></a>Installing on Unix
          164  +
          165  +For *Unix*\-like environments Tcllib comes with the standard set of files to
          166  +make
          167  +
          168  +    ./configure
          169  +    make install
          170  +
          171  +a suitable way of installing it\. This is a standard non\-interactive install
          172  +automatically figuring out where to place everything, i\.e\. packages,
          173  +applications, and the manpages\.
          174  +
          175  +To get a graphical installer invoke
          176  +
          177  +    ./installer.tcl
          178  +
          179  +instead\.
          180  +
          181  +## <a name='subsection4'></a>Installing on Windows
          182  +
          183  +In a Windows environment we have the __installer\.tcl__ script to perform
          184  +installation\.
          185  +
          186  +If the desired __tclsh__ is associated "\.tcl" files then double\-clicking /
          187  +opening the __installer\.tcl__ is enough to invoke it in graphical mode\. This
          188  +assumes that *[Tk](\.\./\.\./\.\./index\.md\#tk)* is installed and available as
          189  +well\.
          190  +
          191  +Without *[Tk](\.\./\.\./\.\./index\.md\#tk)* the only way to invoke the installer
          192  +are to open a DOS window, i\.e\. __cmd\.exe__, and then to invoke
          193  +
          194  +    ./installer.tcl
          195  +
          196  +inside it\.
          197  +
          198  +## <a name='subsection5'></a>Critcl & Accelerators
          199  +
          200  +While the majority of Tcllib consists of packages written in pure Tcl a number
          201  +of packages also have *accelerators* associated with them\. These are
          202  +__critcl__\-based C packages whose use will boost the performance of the
          203  +packages using them\. These accelerators are optional, and they are not installed
          204  +by default\.
          205  +
          206  +To build the accelerators the normally optional dependency on __critcl__
          207  +becomes required\.
          208  +
          209  +To build and install Tcllib with the accelerators in a Unix\-like environment
          210  +invoke:
          211  +
          212  +    ./configure
          213  +    make critcl # This builds the shared library holding
          214  +                # the accelerators
          215  +    make install
          216  +
          217  +The underlying tool is "sak\.tcl" in the toplevel directory of Tcllib and the
          218  +command __make critcl__ is just a wrapper around
          219  +
          220  +    ./sak.tcl critcl
          221  +
          222  +Therefore in a Windows environment instead invoke
          223  +
          224  +    ./sak.tcl critcl
          225  +    ./installer.tcl
          226  +
          227  +from within a DOS window, i\.e\. __cmd\.exe__\.
          228  +
          229  +## <a name='subsection6'></a>Tooling
          230  +
          231  +The core of Tcllib's build system is the script "installer\.tcl" found in the
          232  +toplevel directory of a checkout or release\.
          233  +
          234  +The
          235  +
          236  +    configure ; make install
          237  +
          238  +setup available to developers on Unix\-like systems is just a wrapper around it\.
          239  +To go beyond the standard embodied in the wrapper it is necessary to directly
          240  +invoke this script\.
          241  +
          242  +On Windows system using it directly is the only way to invoke it\.
          243  +
          244  +For basic help invoke it as
          245  +
          246  +    ./installer.tcl -help
          247  +
          248  +This will print a short list of all the available options to the standard output
          249  +channel\.
          250  +
          251  +The commands associated with the various *install* targets in the
          252  +*Makefile\.in* for Unix can be used as additional examples on how to use this
          253  +tool as well\.
          254  +
          255  +The installer can operate in GUI and CLI modes\. By default it chooses the mode
          256  +automatically, based on if the Tcl package
          257  +__[Tk](\.\./\.\./\.\./index\.md\#tk)__ can be used or not\. The option
          258  +__\-no\-gui__ can be used to force CLI mode\.
          259  +
          260  +Note that it is possible to specify options on the command line even if the
          261  +installer ultimatively selects GUI mode\. In that case the hardwired defaults and
          262  +the options determine the data presented to the user for editing\.
          263  +
          264  +The installer will select a number of defaults for the locations of packages,
          265  +examples, and documentation, and also the format of the documentation\. The user
          266  +can overide these defaults in the GUI, or by specifying additional options\. The
          267  +defaults depend on the platform detected \(Unix/Windows\) and on the __tclsh__
          268  +executable used to run the installer\.
          269  +
          270  +*Options*
          271  +
          272  +  - __\-help__
          273  +
          274  +    Show the list of options explained here on the standard output channel and
          275  +    exit\.
          276  +
          277  +  - __\+excluded__
          278  +
          279  +    Include deprecated packages in the installation\.
          280  +
          281  +  - __\-no\-gui__
          282  +
          283  +    Force command line operation of the installer
          284  +
          285  +  - __\-no\-wait__
          286  +
          287  +    In CLI mode the installer will by default ask the user to confirm that the
          288  +    chosen configuration \(destination paths, things to install\) is correct
          289  +    before performing any action\. Using this option causes the installer to skip
          290  +    this query and immediately jump to installation\.
          291  +
          292  +  - __\-app\-path__ *path*
          293  +
          294  +  - __\-example\-path__ *path*
          295  +
          296  +  - __\-html\-path__ *path*
          297  +
          298  +  - __\-nroff\-path__ *path*
          299  +
          300  +  - __\-pkg\-path__ *path*
          301  +
          302  +    Declare the destination paths for the applications, examples, html
          303  +    documentation, nroff manpages, and packages\. The defaults are derived from
          304  +    the location of the __tclsh__ used to run the installer\.
          305  +
          306  +  - __\-dry\-run__
          307  +
          308  +  - __\-simulate__
          309  +
          310  +    Run the installer without modifying the destination directories\.
          311  +
          312  +  - __\-apps__
          313  +
          314  +  - __\-no\-apps__
          315  +
          316  +  - __\-examples__
          317  +
          318  +  - __\-no\-examples__
          319  +
          320  +  - __\-pkgs__
          321  +
          322  +  - __\-no\-pkgs__
          323  +
          324  +  - __\-html__
          325  +
          326  +  - __\-no\-html__
          327  +
          328  +  - __\-nroff__
          329  +
          330  +  - __\-no\-nroff__
          331  +
          332  +    \(De\)activate the installation of applications, examples, packages, html
          333  +    documentation, and nroff manpages\.
          334  +
          335  +    Applications, examples, and packages are installed by default\.
          336  +
          337  +    On Windows the html documentation is installed by default\.
          338  +
          339  +    On Unix the nroff manpages are installed by default\.

Added embedded/md/tcllib/files/devdoc/tcllib_license.md.

            1  +
            2  +[//000000001]: # (tcllib\_license \- )
            3  +[//000000002]: # (Generated from file 'tcllib\_license\.man' by tcllib/doctools with format 'markdown')
            4  +[//000000003]: # (tcllib\_license\(n\) 1 tcllib "")
            5  +
            6  +<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
            7  +href="../../toc.md">Table Of Contents</a> &#124; <a
            8  +href="../../../index.md">Keyword Index</a> &#124; <a
            9  +href="../../../toc0.md">Categories</a> &#124; <a
           10  +href="../../../toc1.md">Modules</a> &#124; <a
           11  +href="../../../toc2.md">Applications</a> ] <hr>
           12  +
           13  +# NAME
           14  +
           15  +tcllib\_license \- Tcllib \- License
           16  +
           17  +# <a name='toc'></a>Table Of Contents
           18  +
           19  +  - [Table Of Contents](#toc)
           20  +
           21  +  - [Description](#section1)
           22  +
           23  +  - [License](#section2)
           24  +
           25  +# <a name='description'></a>DESCRIPTION
           26  +
           27  +Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
           28  +itself\. It is a collection of \(semi\-independent\)
           29  +*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
           30  +useful to a large collection of Tcl programmers\.
           31  +
           32  +The collection is under the BSD license\.
           33  +
           34  +# <a name='section2'></a>License
           35  +
           36  +This software is copyrighted by Ajuba Solutions and other parties\. The following
           37  +terms apply to all files associated with the software unless explicitly
           38  +disclaimed in individual files\.
           39  +
           40  +The authors hereby grant permission to use, copy, modify, distribute, and
           41  +license this software and its documentation for any purpose, provided that
           42  +existing copyright notices are retained in all copies and that this notice is
           43  +included verbatim in any distributions\. No written agreement, license, or
           44  +royalty fee is required for any of the authorized uses\. Modifications to this
           45  +software may be copyrighted by their authors and need not follow the licensing
           46  +terms described here, provided that the new terms are clearly indicated on the
           47  +first page of each file where they apply\.
           48  +
           49  +IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT,
           50  +INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
           51  +OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE
           52  +AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE\.
           53  +
           54  +THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
           55  +BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
           56  +PARTICULAR PURPOSE, AND NON\-INFRINGEMENT\. THIS SOFTWARE IS PROVIDED ON AN "AS
           57  +IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
           58  +MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS\.
           59  +
           60  +GOVERNMENT USE: If you are acquiring this software on behalf of the U\.S\.
           61  +government, the Government shall have only "Restricted Rights" in the software
           62  +and related documentation as defined in the Federal Acquisition Regulations
           63  +\(FARs\) in Clause 52\.227\.19 \(c\) \(2\)\. If you are acquiring the software on behalf
           64  +of the Department of Defense, the software shall be classified as "Commercial
           65  +Computer Software" and the Government shall have only "Restricted Rights" as
           66  +defined in Clause 252\.227\-7013 \(c\) \(1\) of DFARs\. Notwithstanding the foregoing,
           67  +the authors grant the U\.S\. Government and others acting in its behalf permission
           68  +to use and distribute the software in accordance with the terms specified in
           69  +this license\.

Added embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md.

            1  +
            2  +[//000000001]: # (tcllib\_releasemgr \- )
            3  +[//000000002]: # (Generated from file 'tcllib\_releasemgr\.man' by tcllib/doctools with format 'markdown')
            4  +[//000000003]: # (tcllib\_releasemgr\(n\) 1 tcllib "")
            5  +
            6  +<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
            7  +href="../../toc.md">Table Of Contents</a> &#124; <a
            8  +href="../../../index.md">Keyword Index</a> &#124; <a
            9  +href="../../../toc0.md">Categories</a> &#124; <a
           10  +href="../../../toc1.md">Modules</a> &#124; <a
           11  +href="../../../toc2.md">Applications</a> ] <hr>
           12  +
           13  +# NAME
           14  +
           15  +tcllib\_releasemgr \- Tcllib \- The Release Manager's Guide
           16  +
           17  +# <a name='toc'></a>Table Of Contents
           18  +
           19  +  - [Table Of Contents](#toc)
           20  +
           21  +  - [Description](#section1)
           22  +
           23  +  - [Tools](#section2)
           24  +
           25  +  - [Tasks](#section3)
           26  +
           27  +      - [Start a release candidate](#subsection1)
           28  +
           29  +      - [Ready the candidate](#subsection2)
           30  +
           31  +      - [Make it official](#subsection3)
           32  +
           33  +      - [Distribute the release](#subsection4)
           34  +
           35  +# <a name='description'></a>DESCRIPTION
           36  +
           37  +Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
           38  +itself\. It is a collection of \(semi\-independent\)
           39  +*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
           40  +useful to a large collection of Tcl programmers\.
           41  +
           42  +The audience of this document is the release manager for Tcllib, their deputies,
           43  +and anybody else interested in the task of creating an official release of
           44  +Tcllib for distribution\.
           45  +
           46  +Please read *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* first,
           47  +if that was not done already\. Here we assume that the sources are already
           48  +available in a directory of your choice\.
           49  +
           50  +# <a name='section2'></a>Tools
           51  +
           52  +The "sak\.tcl" script in the toplevel directory of a Tcllib checkout is the one
           53  +tool used by the release manager to perform its [Tasks](#section3)\.
           54  +
           55  +The main commands to be used are
           56  +
           57  +    sak.tcl validate
           58  +    sak.tcl test run
           59  +    sak.tcl review
           60  +    sak.tcl readme
           61  +    sak.tcl localdoc
           62  +    sak.tcl release
           63  +
           64  +More detail will be provided in the explanations of the various
           65  +[Tasks](#section3)\.
           66  +
           67  +# <a name='section3'></a>Tasks
           68  +
           69  +## <a name='subsection1'></a>Start a release candidate
           70  +
           71  +todo: open a candidate for release
           72  +
           73  +## <a name='subsection2'></a>Ready the candidate
           74  +
           75  +todo: test, validate and check that the candidate is worthy of release fix
           76  +testsuites, possibly fix packages, documentation regenerate docs coordinate with
           77  +package maintainers wrt fixes big thing: going over the packages, classify
           78  +changes since last release to generate a nice readme\.
           79  +
           80  +## <a name='subsection3'></a>Make it official
           81  +
           82  +todo: finalize release, make candidate official
           83  +
           84  +## <a name='subsection4'></a>Distribute the release
           85  +
           86  +With the release made it has to be published and the world notified of its
           87  +existence\.
           88  +
           89  +  1. Create a proper fossil event for the release, via
           90  +     [http://core\.tcl\-lang\.org/tcllib/eventedit](http://core\.tcl\-lang\.org/tcllib/eventedit)\.
           91  +
           92  +     An [existing
           93  +     event](http://core\.tcl\-lang\.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817)
           94  +     should be used as template\.
           95  +
           96  +  1. Update a number of web locations:
           97  +
           98  +       1) [Home
           99  +          page](http://core\.tcl\-lang\.org/tcllib/doc/trunk/embedded/index\.md)
          100  +
          101  +       1) [Downloads](http://core\.tcl\-lang\.org/tcllib/wiki?name=Downloads)
          102  +
          103  +       1) [Past
          104  +          Releases](http://core\.tcl\-lang\.org/tcllib/wiki?name=Past\+Releases)
          105  +
          106  +       1) [http://www\.tcl\-lang\.org/home/release\.txt](http://www\.tcl\-lang\.org/home/release\.txt)
          107  +
          108  +       1) [http://www\.tcl\-lang\.org/software/tcllib/\*\.tml](http://www\.tcl\-lang\.org/software/tcllib/\*\.tml)
          109  +
          110  +       1) [http://wiki\.tcl\-lang\.org/page/Tcllib](http://wiki\.tcl\-lang\.org/page/Tcllib)
          111  +
          112  +     The first location maps to the file "embedded/index\.md" in the repository
          113  +     itself, as such it can edited as part of the release process\. This is where
          114  +     reference to the new fossil event is added, as the new current release\.
          115  +
          116  +     The next two locations are in the fossil tcllib wiki and require admin or
          117  +     wiki write permissions for
          118  +     [http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib)\.
          119  +
          120  +     The last two locations require ssh access to
          121  +     [http://www\.tcl\-lang\.org](http://www\.tcl\-lang\.org) and permission to
          122  +     edit files in the web area\.
          123  +
          124  +  1. \*\*\*TODO\*\*\* mailing lists and other places to send notes to\.

Added embedded/md/tcllib/files/devdoc/tcllib_sources.md.

            1  +
            2  +[//000000001]: # (tcllib\_sources \- )
            3  +[//000000002]: # (Generated from file 'tcllib\_sources\.man' by tcllib/doctools with format 'markdown')
            4  +[//000000003]: # (tcllib\_sources\(n\) 1 tcllib "")
            5  +
            6  +<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
            7  +href="../../toc.md">Table Of Contents</a> &#124; <a
            8  +href="../../../index.md">Keyword Index</a> &#124; <a
            9  +href="../../../toc0.md">Categories</a> &#124; <a
           10  +href="../../../toc1.md">Modules</a> &#124; <a
           11  +href="../../../toc2.md">Applications</a> ] <hr>
           12  +
           13  +# NAME
           14  +
           15  +tcllib\_sources \- Tcllib \- How To Get The Sources
           16  +
           17  +# <a name='toc'></a>Table Of Contents
           18  +
           19  +  - [Table Of Contents](#toc)
           20  +
           21  +  - [Description](#section1)
           22  +
           23  +  - [Source Location](#section2)
           24  +
           25  +  - [Retrieval](#section3)
           26  +
           27  +  - [Source Code Management](#section4)
           28  +
           29  +# <a name='description'></a>DESCRIPTION
           30  +
           31  +Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
           32  +itself\. It is a collection of \(semi\-independent\)
           33  +*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
           34  +useful to a large collection of Tcl programmers\.
           35  +
           36  +The audience of this document is anyone wishing to either have just a look at
           37  +Tcllib's source code, or build the packages, or to extend and modify them\.
           38  +
           39  +For builders and developers we additionally provide
           40  +
           41  +  1. *[Tcllib \- The Installer's Guide](tcllib\_installer\.md)*\.
           42  +
           43  +  1. *[Tcllib \- The Developer's Guide](tcllib\_devguide\.md)*\.
           44  +
           45  +respectively\.
           46  +
           47  +# <a name='section2'></a>Source Location
           48  +
           49  +The official repository for Tcllib can be found at
           50  +[http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib)
           51  +
           52  +# <a name='section3'></a>Retrieval
           53  +
           54  +Assuming that you simply wish to look at the sources, or build a specific
           55  +revision, the easiest way of retrieving it is to:
           56  +
           57  +  1. Log into this site, as "anonymous", using the semi\-random password in the
           58  +     captcha\.
           59  +
           60  +  1. Go to the "Timeline"\.
           61  +
           62  +  1. Choose the revision you wish to have\.
           63  +
           64  +  1. Follow its link to its detailed information page\.
           65  +
           66  +  1. On that page, choose either the "ZIP" or "Tarball" link to get a copy of
           67  +     this revision in the format of your choice\.
           68  +
           69  +# <a name='section4'></a>Source Code Management
           70  +
           71  +For the curious \(or a developer\-to\-be\), the sources are managed by the [Fossil
           72  +SCM](http://www\.fossil\-scm\.org)\. Binaries for popular platforms can be found
           73  +directly at its [download page](http://www\.fossil\-scm\.org/download\.html)\.
           74  +
           75  +With that tool available the full history can be retrieved via:
           76  +
           77  +    fossil clone  http://core.tcl-lang.org/tcllib  tcllib.fossil
           78  +
           79  +followed by
           80  +
           81  +    mkdir tcllib
           82  +    cd tcllib
           83  +    fossil open ../tcllib.fossil
           84  +
           85  +to get a checkout of the head of the trunk\.

Changes to embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md.

    92     92       [keywords {doctools language}]
    93     93       [keywords {doctools markup}]
    94     94       [keywords {doctools syntax}]
    95     95       [keywords markup]
    96     96       [keywords {semantic markup}]
    97     97           [description]
    98     98           [vset CATEGORY doctools]
    99         -    [include ../doctools2base/include/feedback.inc]
           99  +    [include ../common-text/feedback.inc]
   100    100       [manpage_end]
   101    101   
   102    102   This also shows us that all doctools documents are split into two parts, the
   103    103   *header* and the *body*\. Everything coming before \[__description__\]
   104    104   belongs to the header, and everything coming after belongs to the body, with the
   105    105   whole document bracketed by the two __manpage\_\*__ commands\. Before and after
   106    106   these opening and closing commands we have only *whitespace*\.
................................................................................
   143    143   
   144    144   Remember that the whitespace is optional\. The document
   145    145   
   146    146           [manpage_begin NAME SECTION VERSION]
   147    147           [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
   148    148           [require PACKAGE VERSION][require PACKAGE][description]
   149    149           [vset CATEGORY doctools]
   150         -    [include ../doctools2base/include/feedback.inc]
          150  +    [include ../common-text/feedback.inc]
   151    151       [manpage_end]
   152    152   
   153    153   has the same meaning as the example before\.
   154    154   
   155    155   On the other hand, if *whitespace* is present it consists not only of any
   156    156   sequence of characters containing the space character, horizontal and vertical
   157    157   tabs, carriage return, and newline, but it may contain comment markup as well,

Changes to embedded/md/tcllib/toc.md.

   711    711   
   712    712     - [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption
   713    713   
   714    714     - [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal
   715    715   
   716    716     - [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression
   717    717   
          718  +  - [tcl\_community\_communication](tcllib/files/devdoc/tcl\_community\_communication\.md) Tcl Community \- Kind Communication
          719  +
   718    720     - [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers
   719    721   
   720    722     - [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers
   721    723   
   722    724     - [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor
   723    725   
          726  +  - [tcllib\_devguide](tcllib/files/devdoc/tcllib\_devguide\.md) Tcllib \- The Developer's Guide
          727  +
          728  +  - [tcllib\_install\_guide](tcllib/files/devdoc/tcllib\_installer\.md) Tcllib \- The Installer's Guide
          729  +
   724    730     - [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation
   725    731   
          732  +  - [tcllib\_license](tcllib/files/devdoc/tcllib\_license\.md) Tcllib \- License
          733  +
          734  +  - [tcllib\_releasemgr](tcllib/files/devdoc/tcllib\_releasemgr\.md) Tcllib \- The Release Manager's Guide
          735  +
          736  +  - [tcllib\_sources](tcllib/files/devdoc/tcllib\_sources\.md) Tcllib \- How To Get The Sources
          737  +
   726    738     - [tclrep/machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\.
   727    739   
   728    740     - [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
   729    741   
   730    742     - [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual
   731    743   
   732    744     - [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md) TEPAM DOC Generation, reference manual

Added idoc/man/files/devdoc/tcl_community_communication.n.

            1  +'\"
            2  +'\" Generated from file 'tcl_community_communication\&.man' by tcllib/doctools with format 'nroff'
            3  +'\"
            4  +.TH "tcl_community_communication" n 1 tcllib ""
            5  +.\" The -*- nroff -*- definitions below are for supplemental macros used
            6  +.\" in Tcl/Tk manual entries.
            7  +.\"
            8  +.\" .AP type name in/out ?indent?
            9  +.\"	Start paragraph describing an argument to a library procedure.
           10  +.\"	type is type of argument (int, etc.), in/out is either "in", "out",
           11  +.\"	or "in/out" to describe whether procedure reads or modifies arg,
           12  +.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
           13  +.\"	needed;  use .AS below instead)
           14  +.\"
           15  +.\" .AS ?type? ?name?
           16  +.\"	Give maximum sizes of arguments for setting tab stops.  Type and
           17  +.\"	name are examples of largest possible arguments that will be passed
           18  +.\"	to .AP later.  If args are omitted, default tab stops are used.
           19  +.\"
           20  +.\" .BS
           21  +.\"	Start box enclosure.  From here until next .BE, everything will be
           22  +.\"	enclosed in one large box.
           23  +.\"
           24  +.\" .BE
           25  +.\"	End of box enclosure.
           26  +.\"
           27  +.\" .CS
           28  +.\"	Begin code excerpt.
           29  +.\"
           30  +.\" .CE
           31  +.\"	End code excerpt.
           32  +.\"
           33  +.\" .VS ?version? ?br?
           34  +.\"	Begin vertical sidebar, for use in marking newly-changed parts
           35  +.\"	of man pages.  The first argument is ignored and used for recording
           36  +.\"	the version when the .VS was added, so that the sidebars can be
           37  +.\"	found and removed when they reach a certain age.  If another argument
           38  +.\"	is present, then a line break is forced before starting the sidebar.
           39  +.\"
           40  +.\" .VE
           41  +.\"	End of vertical sidebar.
           42  +.\"
           43  +.\" .DS
           44  +.\"	Begin an indented unfilled display.
           45  +.\"
           46  +.\" .DE
           47  +.\"	End of indented unfilled display.
           48  +.\"
           49  +.\" .SO ?manpage?
           50  +.\"	Start of list of standard options for a Tk widget. The manpage
           51  +.\"	argument defines where to look up the standard options; if
           52  +.\"	omitted, defaults to "options". The options follow on successive
           53  +.\"	lines, in three columns separated by tabs.
           54  +.\"
           55  +.\" .SE
           56  +.\"	End of list of standard options for a Tk widget.
           57  +.\"
           58  +.\" .OP cmdName dbName dbClass
           59  +.\"	Start of description of a specific option.  cmdName gives the
           60  +.\"	option's name as specified in the class command, dbName gives
           61  +.\"	the option's name in the option database, and dbClass gives
           62  +.\"	the option's class in the option database.
           63  +.\"
           64  +.\" .UL arg1 arg2
           65  +.\"	Print arg1 underlined, then print arg2 normally.
           66  +.\"
           67  +.\" .QW arg1 ?arg2?
           68  +.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
           69  +.\"
           70  +.\" .PQ arg1 ?arg2?
           71  +.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
           72  +.\"	(for trailing punctuation) and then a closing parenthesis.
           73  +.\"
           74  +.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
           75  +.if t .wh -1.3i ^B
           76  +.nr ^l \n(.l
           77  +.ad b
           78  +.\"	# Start an argument description
           79  +.de AP
           80  +.ie !"\\$4"" .TP \\$4
           81  +.el \{\
           82  +.   ie !"\\$2"" .TP \\n()Cu
           83  +.   el          .TP 15
           84  +.\}
           85  +.ta \\n()Au \\n()Bu
           86  +.ie !"\\$3"" \{\
           87  +\&\\$1 \\fI\\$2\\fP (\\$3)
           88  +.\".b
           89  +.\}
           90  +.el \{\
           91  +.br
           92  +.ie !"\\$2"" \{\
           93  +\&\\$1	\\fI\\$2\\fP
           94  +.\}
           95  +.el \{\
           96  +\&\\fI\\$1\\fP
           97  +.\}
           98  +.\}
           99  +..
          100  +.\"	# define tabbing values for .AP
          101  +.de AS
          102  +.nr )A 10n
          103  +.if !"\\$1"" .nr )A \\w'\\$1'u+3n
          104  +.nr )B \\n()Au+15n
          105  +.\"
          106  +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
          107  +.nr )C \\n()Bu+\\w'(in/out)'u+2n
          108  +..
          109  +.AS Tcl_Interp Tcl_CreateInterp in/out
          110  +.\"	# BS - start boxed text
          111  +.\"	# ^y = starting y location
          112  +.\"	# ^b = 1
          113  +.de BS
          114  +.br
          115  +.mk ^y
          116  +.nr ^b 1u
          117  +.if n .nf
          118  +.if n .ti 0
          119  +.if n \l'\\n(.lu\(ul'
          120  +.if n .fi
          121  +..
          122  +.\"	# BE - end boxed text (draw box now)
          123  +.de BE
          124  +.nf
          125  +.ti 0
          126  +.mk ^t
          127  +.ie n \l'\\n(^lu\(ul'
          128  +.el \{\
          129  +.\"	Draw four-sided box normally, but don't draw top of
          130  +.\"	box if the box started on an earlier page.
          131  +.ie !\\n(^b-1 \{\
          132  +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          133  +.\}
          134  +.el \}\
          135  +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          136  +.\}
          137  +.\}
          138  +.fi
          139  +.br
          140  +.nr ^b 0
          141  +..
          142  +.\"	# VS - start vertical sidebar
          143  +.\"	# ^Y = starting y location
          144  +.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
          145  +.de VS
          146  +.if !"\\$2"" .br
          147  +.mk ^Y
          148  +.ie n 'mc \s12\(br\s0
          149  +.el .nr ^v 1u
          150  +..
          151  +.\"	# VE - end of vertical sidebar
          152  +.de VE
          153  +.ie n 'mc
          154  +.el \{\
          155  +.ev 2
          156  +.nf
          157  +.ti 0
          158  +.mk ^t
          159  +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
          160  +.sp -1
          161  +.fi
          162  +.ev
          163  +.\}
          164  +.nr ^v 0
          165  +..
          166  +.\"	# Special macro to handle page bottom:  finish off current
          167  +.\"	# box/sidebar if in box/sidebar mode, then invoked standard
          168  +.\"	# page bottom macro.
          169  +.de ^B
          170  +.ev 2
          171  +'ti 0
          172  +'nf
          173  +.mk ^t
          174  +.if \\n(^b \{\
          175  +.\"	Draw three-sided box if this is the box's first page,
          176  +.\"	draw two sides but no top otherwise.
          177  +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          178  +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          179  +.\}
          180  +.if \\n(^v \{\
          181  +.nr ^x \\n(^tu+1v-\\n(^Yu
          182  +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
          183  +.\}
          184  +.bp
          185  +'fi
          186  +.ev
          187  +.if \\n(^b \{\
          188  +.mk ^y
          189  +.nr ^b 2
          190  +.\}
          191  +.if \\n(^v \{\
          192  +.mk ^Y
          193  +.\}
          194  +..
          195  +.\"	# DS - begin display
          196  +.de DS
          197  +.RS
          198  +.nf
          199  +.sp
          200  +..
          201  +.\"	# DE - end display
          202  +.de DE
          203  +.fi
          204  +.RE
          205  +.sp
          206  +..
          207  +.\"	# SO - start of list of standard options
          208  +.de SO
          209  +'ie '\\$1'' .ds So \\fBoptions\\fR
          210  +'el .ds So \\fB\\$1\\fR
          211  +.SH "STANDARD OPTIONS"
          212  +.LP
          213  +.nf
          214  +.ta 5.5c 11c
          215  +.ft B
          216  +..
          217  +.\"	# SE - end of list of standard options
          218  +.de SE
          219  +.fi
          220  +.ft R
          221  +.LP
          222  +See the \\*(So manual entry for details on the standard options.
          223  +..
          224  +.\"	# OP - start of full description for a single option
          225  +.de OP
          226  +.LP
          227  +.nf
          228  +.ta 4c
          229  +Command-Line Name:	\\fB\\$1\\fR
          230  +Database Name:	\\fB\\$2\\fR
          231  +Database Class:	\\fB\\$3\\fR
          232  +.fi
          233  +.IP
          234  +..
          235  +.\"	# CS - begin code excerpt
          236  +.de CS
          237  +.RS
          238  +.nf
          239  +.ta .25i .5i .75i 1i
          240  +..
          241  +.\"	# CE - end code excerpt
          242  +.de CE
          243  +.fi
          244  +.RE
          245  +..
          246  +.\"	# UL - underline word
          247  +.de UL
          248  +\\$1\l'|0\(ul'\\$2
          249  +..
          250  +.\"	# QW - apply quotation marks to word
          251  +.de QW
          252  +.ie '\\*(lq'"' ``\\$1''\\$2
          253  +.\"" fix emacs highlighting
          254  +.el \\*(lq\\$1\\*(rq\\$2
          255  +..
          256  +.\"	# PQ - apply parens and quotation marks to word
          257  +.de PQ
          258  +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
          259  +.\"" fix emacs highlighting
          260  +.el (\\*(lq\\$1\\*(rq\\$2)\\$3
          261  +..
          262  +.\"	# QR - quoted range
          263  +.de QR
          264  +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
          265  +.\"" fix emacs highlighting
          266  +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
          267  +..
          268  +.\"	# MT - "empty" string
          269  +.de MT
          270  +.QW ""
          271  +..
          272  +.BS
          273  +.SH NAME
          274  +tcl_community_communication \- Tcl Community - Kind Communication
          275  +.SH DESCRIPTION
          276  +The Tcl Community encourages contributions from anyone who wishes to
          277  +advance the development of:
          278  +.IP \(bu
          279  +The Tcl Language
          280  +.IP \(bu
          281  +Tcl derived languages
          282  +.IP \(bu
          283  +Tcl related libraries
          284  +.IP \(bu
          285  +Tcl extensions
          286  +.IP \(bu
          287  +External Projects that Integrate Tcl
          288  +.PP
          289  +.PP
          290  +We welcome those contributions from anyone\&. We are blind to
          291  +gender, race, religion, cultural background, cybernetic nature, and
          292  +any other demographic characteristics, as well as personal political
          293  +views\&.
          294  +.PP
          295  +A community lives and dies by communications\&. And occasionally
          296  +our communications are peppered with patterns that are harsh,
          297  +unfriendly, unwelcoming and/or otherwise unkind\&. As a volunteer
          298  +community, we need all of the help we can get\&. Therefore, we ask all
          299  +contributors to make a conscious effort, in Tcl Community discussions,
          300  +to communicate in ways that are welcoming\&. Ways that are
          301  +friendly\&. Ways that are, in a word: kind\&.
          302  +.PP
          303  +These guidelines suggest specific ways to accomplish that goal\&.
          304  +.PP
          305  +Please note: for the balance of this document any reference to
          306  +"People", "Persons", "anybody" or "somebody" can refer to any sentient
          307  +being, not merely corporeal members of the species Homo Sapien\&.
          308  +.TP
          309  +We are a Sanctuary not a Clubhouse
          310  +The Tcl Community is a collective of amateurs and professionals who
          311  +code, test, and use tools\&. Our community is open to all\&. There is no
          312  +velvet rope\&. There is no bouncer at the door\&. There are no secret
          313  +handshakes\&. Any sentient being who enters our midst is welcome\&. If
          314  +someone is ever asked to leave, it is only because they are being
          315  +disruptive to the functioning of the community\&.
          316  +.TP
          317  +We Merit Ideas, Not People
          318  +A good idea can come from anyone, regardless of how little time they
          319  +have been with us\&. A bad idea can come from anyone, regardless of how
          320  +much time or how little time they have been with us\&. We judge a
          321  +concept by how it stands up to scrutiny of logic, implementation, and
          322  +regression testing\&. We don’t judge ideas based on who had the idea
          323  +first, who agrees with the idea, or who disagrees with it\&.
          324  +.TP
          325  +Treat Everyone with Respect
          326  +Everyone is deserving of respect and courtesy at all times\&.
          327  +.TP
          328  +Refer to people by the names they use\&.
          329  +If grammar requires you to state a gender for a person, honor their
          330  +preferences about their gender identity\&. If you are unsure as to the
          331  +gender of an individual, ask\&. If someone had to guess about your
          332  +gender and got it wrong, please correct them and do not take it
          333  +personally\&.
          334  +.TP
          335  +Do not take a harsh tone towards other participants\&.
          336  +Do not make personal attacks against anyone (participant or not\&.)
          337  +.sp
          338  +Criticize statements and actions, never people\&.
          339  +.TP
          340  +Don’t Take Things Personally
          341  +When in doubt, assume the best in people\&. A criticism of your
          342  +statements is not a personal attack on you\&.
          343  +.TP
          344  +Persons, not People
          345  +Stereotypes are an unhelpful tool on many accounts\&. They are generally
          346  +oversimplified\&. They are usually flat out wrong\&. And even if "right"
          347  +they are of absolutely no utility in determining the capabilities,
          348  +motivations, or fitness of an individual\&.
          349  +.sp
          350  +Don’t use them in Tcl Community communications\&.
          351  +.TP
          352  +Mistakes Happen
          353  +The human condition is a series of trials and errors\&. Progress is when
          354  +we get one more trial than error\&. Being wrong or making a mistake is
          355  +the default state of humanity\&. Accept the errors of your fellow
          356  +sentient beings, and be aware that you are also fallible\&.
          357  +.TP
          358  +Keep it Real
          359  +Please respond to what people actually say\&. We are all amazing
          360  +individuals, but none among us are mind readers\&. If you find yourself
          361  +responding to what you imagine someone is thinking, odds are you are
          362  +going to be wrong\&.
          363  +.sp
          364  +If you must criticize someone, stick to things they have
          365  +actually done\&. Never criticize for something you speculate they have
          366  +done\&. Or imagine they have done\&. Or something someone who shares some
          367  +attribute with them has done in the past\&.
          368  +.sp
          369  +Keep discussions about any non-Tcl subjects to what can be
          370  +stated factually and without emotion or judgement\&.
          371  +.TP
          372  +When Trouble Arises, Don’t Escalate
          373  +If you feel you are being personally attacked or offended, take the
          374  +high road\&. Punching back in a public forum will only makes things
          375  +worse\&. Address the matter in a private correspondence\&. Be
          376  +polite\&. Express your feelings, but note that you are expressing your
          377  +feelings\&. When writing, look for a way to calm matters down\&. And when
          378  +in doubt, sleep on your letter before pressing send\&. And when not in
          379  +doubt, sleep on it for another day after that\&.
          380  +.sp
          381  +If you are a spectator to a fight in progress, politely request
          382  +the two parties take the matter to a more private forum\&.
          383  +.TP
          384  +Always get the Last Word: I’m Sorry
          385  +If an personal argument does arise, be the first to apologize\&. An
          386  +apology does not concede a logical point\&. It merely acknowledges that
          387  +at some point the discussion left either logic, community decency, or
          388  +both\&. Return to the topic when cooler heads can prevail\&.
          389  +.TP
          390  +Nobody is Keeping Score
          391  +There is no prize for being right\&. There is no cost for being wrong\&. A
          392  +hard sell is not going to advance your idea along any more than a
          393  +logical argument\&. You aren’t running for office\&. This isn’t debate
          394  +club\&. If you find yourself continuing a discussion beyond where a
          395  +topic can be logically discussed, stop\&.
          396  +.TP
          397  +No Evangelizing
          398  +The Tcl Community is not the place to promote your chosen operating
          399  +system, political outlook, religion, marketing scheme, or economic
          400  +model\&. Period\&.
          401  +.sp
          402  +(And if you do bring it up, be prepared to have your chosen
          403  +topic discussed logically\&. And odds are, not favorably\&.)
          404  +.TP
          405  +Respect the Community
          406  +If the Community has come to a decision on a course of action, please
          407  +stop arguing\&.
          408  +.sp
          409  +If someone complains about how you are expressing your ideas,
          410  +listen\&.
          411  +.sp
          412  +If your words are hurting people, stop\&. There is no amount of
          413  +being "right" that makes up for someone leaving our midst because they
          414  +felt insulted, threatened, or ignored\&.
          415  +.PP
          416  +By following these guidelines, we will build our community, encourage
          417  +more contribution to our projects, and our discussions will be
          418  +friendlier and reach conclusions more easily\&.
          419  +.PP
          420  +Thank You\&.
          421  +.SH SIGNATORIES
          422  +.IP \(bu
          423  +Sean "the Hypnotoad" Woods
          424  +.IP \(bu
          425  +Andreas Kupries
          426  +.PP
          427  +.SH AUTHORS
          428  +.TP
          429  +Primary
          430  +Sean "the Hypnotoad" Woods
          431  +.TP
          432  +Light editing
          433  +Andreas Kupries
          434  +.PP

Added idoc/man/files/devdoc/tcllib_devguide.n.

            1  +'\"
            2  +'\" Generated from file 'tcllib_devguide\&.man' by tcllib/doctools with format 'nroff'
            3  +'\"
            4  +.TH "tcllib_devguide" n 1 tcllib ""
            5  +.\" The -*- nroff -*- definitions below are for supplemental macros used
            6  +.\" in Tcl/Tk manual entries.
            7  +.\"
            8  +.\" .AP type name in/out ?indent?
            9  +.\"	Start paragraph describing an argument to a library procedure.
           10  +.\"	type is type of argument (int, etc.), in/out is either "in", "out",
           11  +.\"	or "in/out" to describe whether procedure reads or modifies arg,
           12  +.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
           13  +.\"	needed;  use .AS below instead)
           14  +.\"
           15  +.\" .AS ?type? ?name?
           16  +.\"	Give maximum sizes of arguments for setting tab stops.  Type and
           17  +.\"	name are examples of largest possible arguments that will be passed
           18  +.\"	to .AP later.  If args are omitted, default tab stops are used.
           19  +.\"
           20  +.\" .BS
           21  +.\"	Start box enclosure.  From here until next .BE, everything will be
           22  +.\"	enclosed in one large box.
           23  +.\"
           24  +.\" .BE
           25  +.\"	End of box enclosure.
           26  +.\"
           27  +.\" .CS
           28  +.\"	Begin code excerpt.
           29  +.\"
           30  +.\" .CE
           31  +.\"	End code excerpt.
           32  +.\"
           33  +.\" .VS ?version? ?br?
           34  +.\"	Begin vertical sidebar, for use in marking newly-changed parts
           35  +.\"	of man pages.  The first argument is ignored and used for recording
           36  +.\"	the version when the .VS was added, so that the sidebars can be
           37  +.\"	found and removed when they reach a certain age.  If another argument
           38  +.\"	is present, then a line break is forced before starting the sidebar.
           39  +.\"
           40  +.\" .VE
           41  +.\"	End of vertical sidebar.
           42  +.\"
           43  +.\" .DS
           44  +.\"	Begin an indented unfilled display.
           45  +.\"
           46  +.\" .DE
           47  +.\"	End of indented unfilled display.
           48  +.\"
           49  +.\" .SO ?manpage?
           50  +.\"	Start of list of standard options for a Tk widget. The manpage
           51  +.\"	argument defines where to look up the standard options; if
           52  +.\"	omitted, defaults to "options". The options follow on successive
           53  +.\"	lines, in three columns separated by tabs.
           54  +.\"
           55  +.\" .SE
           56  +.\"	End of list of standard options for a Tk widget.
           57  +.\"
           58  +.\" .OP cmdName dbName dbClass
           59  +.\"	Start of description of a specific option.  cmdName gives the
           60  +.\"	option's name as specified in the class command, dbName gives
           61  +.\"	the option's name in the option database, and dbClass gives
           62  +.\"	the option's class in the option database.
           63  +.\"
           64  +.\" .UL arg1 arg2
           65  +.\"	Print arg1 underlined, then print arg2 normally.
           66  +.\"
           67  +.\" .QW arg1 ?arg2?
           68  +.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
           69  +.\"
           70  +.\" .PQ arg1 ?arg2?
           71  +.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
           72  +.\"	(for trailing punctuation) and then a closing parenthesis.
           73  +.\"
           74  +.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
           75  +.if t .wh -1.3i ^B
           76  +.nr ^l \n(.l
           77  +.ad b
           78  +.\"	# Start an argument description
           79  +.de AP
           80  +.ie !"\\$4"" .TP \\$4
           81  +.el \{\
           82  +.   ie !"\\$2"" .TP \\n()Cu
           83  +.   el          .TP 15
           84  +.\}
           85  +.ta \\n()Au \\n()Bu
           86  +.ie !"\\$3"" \{\
           87  +\&\\$1 \\fI\\$2\\fP (\\$3)
           88  +.\".b
           89  +.\}
           90  +.el \{\
           91  +.br
           92  +.ie !"\\$2"" \{\
           93  +\&\\$1	\\fI\\$2\\fP
           94  +.\}
           95  +.el \{\
           96  +\&\\fI\\$1\\fP
           97  +.\}
           98  +.\}
           99  +..
          100  +.\"	# define tabbing values for .AP
          101  +.de AS
          102  +.nr )A 10n
          103  +.if !"\\$1"" .nr )A \\w'\\$1'u+3n
          104  +.nr )B \\n()Au+15n
          105  +.\"
          106  +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
          107  +.nr )C \\n()Bu+\\w'(in/out)'u+2n
          108  +..
          109  +.AS Tcl_Interp Tcl_CreateInterp in/out
          110  +.\"	# BS - start boxed text
          111  +.\"	# ^y = starting y location
          112  +.\"	# ^b = 1
          113  +.de BS
          114  +.br
          115  +.mk ^y
          116  +.nr ^b 1u
          117  +.if n .nf
          118  +.if n .ti 0
          119  +.if n \l'\\n(.lu\(ul'
          120  +.if n .fi
          121  +..
          122  +.\"	# BE - end boxed text (draw box now)
          123  +.de BE
          124  +.nf
          125  +.ti 0
          126  +.mk ^t
          127  +.ie n \l'\\n(^lu\(ul'
          128  +.el \{\
          129  +.\"	Draw four-sided box normally, but don't draw top of
          130  +.\"	box if the box started on an earlier page.
          131  +.ie !\\n(^b-1 \{\
          132  +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          133  +.\}
          134  +.el \}\
          135  +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          136  +.\}
          137  +.\}
          138  +.fi
          139  +.br
          140  +.nr ^b 0
          141  +..
          142  +.\"	# VS - start vertical sidebar
          143  +.\"	# ^Y = starting y location
          144  +.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
          145  +.de VS
          146  +.if !"\\$2"" .br
          147  +.mk ^Y
          148  +.ie n 'mc \s12\(br\s0
          149  +.el .nr ^v 1u
          150  +..
          151  +.\"	# VE - end of vertical sidebar
          152  +.de VE
          153  +.ie n 'mc
          154  +.el \{\
          155  +.ev 2
          156  +.nf
          157  +.ti 0
          158  +.mk ^t
          159  +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
          160  +.sp -1
          161  +.fi
          162  +.ev
          163  +.\}
          164  +.nr ^v 0
          165  +..
          166  +.\"	# Special macro to handle page bottom:  finish off current
          167  +.\"	# box/sidebar if in box/sidebar mode, then invoked standard
          168  +.\"	# page bottom macro.
          169  +.de ^B
          170  +.ev 2
          171  +'ti 0
          172  +'nf
          173  +.mk ^t
          174  +.if \\n(^b \{\
          175  +.\"	Draw three-sided box if this is the box's first page,
          176  +.\"	draw two sides but no top otherwise.
          177  +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          178  +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          179  +.\}
          180  +.if \\n(^v \{\
          181  +.nr ^x \\n(^tu+1v-\\n(^Yu
          182  +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
          183  +.\}
          184  +.bp
          185  +'fi
          186  +.ev
          187  +.if \\n(^b \{\
          188  +.mk ^y
          189  +.nr ^b 2
          190  +.\}
          191  +.if \\n(^v \{\
          192  +.mk ^Y
          193  +.\}
          194  +..
          195  +.\"	# DS - begin display
          196  +.de DS
          197  +.RS
          198  +.nf
          199  +.sp
          200  +..
          201  +.\"	# DE - end display
          202  +.de DE
          203  +.fi
          204  +.RE
          205  +.sp
          206  +..
          207  +.\"	# SO - start of list of standard options
          208  +.de SO
          209  +'ie '\\$1'' .ds So \\fBoptions\\fR
          210  +'el .ds So \\fB\\$1\\fR
          211  +.SH "STANDARD OPTIONS"
          212  +.LP
          213  +.nf
          214  +.ta 5.5c 11c
          215  +.ft B
          216  +..
          217  +.\"	# SE - end of list of standard options
          218  +.de SE
          219  +.fi
          220  +.ft R
          221  +.LP
          222  +See the \\*(So manual entry for details on the standard options.
          223  +..
          224  +.\"	# OP - start of full description for a single option
          225  +.de OP
          226  +.LP
          227  +.nf
          228  +.ta 4c
          229  +Command-Line Name:	\\fB\\$1\\fR
          230  +Database Name:	\\fB\\$2\\fR
          231  +Database Class:	\\fB\\$3\\fR
          232  +.fi
          233  +.IP
          234  +..
          235  +.\"	# CS - begin code excerpt
          236  +.de CS
          237  +.RS
          238  +.nf
          239  +.ta .25i .5i .75i 1i
          240  +..
          241  +.\"	# CE - end code excerpt
          242  +.de CE
          243  +.fi
          244  +.RE
          245  +..
          246  +.\"	# UL - underline word
          247  +.de UL
          248  +\\$1\l'|0\(ul'\\$2
          249  +..
          250  +.\"	# QW - apply quotation marks to word
          251  +.de QW
          252  +.ie '\\*(lq'"' ``\\$1''\\$2
          253  +.\"" fix emacs highlighting
          254  +.el \\*(lq\\$1\\*(rq\\$2
          255  +..
          256  +.\"	# PQ - apply parens and quotation marks to word
          257  +.de PQ
          258  +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
          259  +.\"" fix emacs highlighting
          260  +.el (\\*(lq\\$1\\*(rq\\$2)\\$3
          261  +..
          262  +.\"	# QR - quoted range
          263  +.de QR
          264  +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
          265  +.\"" fix emacs highlighting
          266  +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
          267  +..
          268  +.\"	# MT - "empty" string
          269  +.de MT
          270  +.QW ""
          271  +..
          272  +.BS
          273  +.SH NAME
          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
          283  +.SH DESCRIPTION
          284  +Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a
          285  +package itself\&. It is a collection of (semi-independent) \fITcl\fR
          286  +packages that provide utility functions useful to a large collection
          287  +of Tcl programmers\&.
          288  +.PP
          289  +This document is a guide for developers working on Tcllib,
          290  +i\&.e\&. maintainers fixing bugs, extending the collection's
          291  +functionality, etc\&.
          292  +.PP
          293  +Please read
          294  +.IP [1]
          295  +\fITcllib - How To Get The Sources\fR and
          296  +.IP [2]
          297  +\fITcllib - The Installer's Guide\fR
          298  +.PP
          299  +first, if that was not done already\&.
          300  +.PP
          301  +Here we assume that the sources are already available in a
          302  +directory of your choice, and that you not only know how to build and
          303  +install them, but also have all the necessary requisites to actually
          304  +do so\&. The guide to the sources in particular also explains which
          305  +source code management system is used, where to find it, how to set it
          306  +up, etc\&.
          307  +.SH COMMITMENTS
          308  +.SS CONTRIBUTOR
          309  +As a contributor to Tcllib you are committing yourself to:
          310  +.IP [1]
          311  +keep the guidelines written down in
          312  +\fITcl Community - Kind Communication\fR in your mind\&.
          313  +The main point to take away from there is
          314  +\fIto be kind to each other\fR\&.
          315  +.IP [2]
          316  +Your contributions getting distributed under a BSD/MIT license\&.
          317  +For the details see \fITcllib - License\fR
          318  +.PP
          319  +Contributions are made by entering tickets into our tracker, providing
          320  +patches, bundles or branches of code for inclusion, or posting to the
          321  +Tcllib related mailing lists\&.
          322  +.SS MAINTAINER
          323  +When contributing one or more packages for full inclusion into Tcllib
          324  +you are committing yourself to
          325  +.IP [1]
          326  +Keep the guidelines written down in
          327  +\fITcl Community - Kind Communication\fR
          328  +(as any contributor) in your mind\&. The main point to take away
          329  +from there is \fIto be kind to each other\fR\&.
          330  +.IP [2]
          331  +Your packages getting distributed under a BSD/MIT license\&.  For
          332  +the details see \fITcllib - License\fR
          333  +.IP [3]
          334  +Maintenance of the new packages for a period of two years under
          335  +the following rules, and responsibilities:
          336  +.RS
          337  +.IP [1]
          338  +A maintainer may step down after the mandatory period as
          339  +they see fit\&.
          340  +.IP [2]
          341  +A maintainer may step down before the end of the
          342  +mandatory period, under the condition that a replacement
          343  +maintainer is immediately available and has agreed to
          344  +serve the remainder of the period, plus their own
          345  +mandatory period (see below)\&.
          346  +.IP [3]
          347  +When stepping down without a replacement maintainer
          348  +taking over the relevant packages have to be flagged as
          349  +\fBunmaintained\fR\&.
          350  +.IP [4]
          351  +When a replacement mantainer is brought in for a package
          352  +it is (kept) marked as \fBmaintained\fR (again)\&.
          353  +.sp
          354  +A replacement maintainer is bound by the same rules as
          355  +the original maintainer, except that the mandatory
          356  +period of maintenance is shortened to one year\&.
          357  +.IP [5]
          358  +For any \fBunmaintained\fR package a contributor
          359  +interested in becoming its maintainer can become so by
          360  +flagging them as \fBmaintained\fR with their name and
          361  +contact information, committing themselves to the rules
          362  +of a replacement maintainer (see previous point)\&.
          363  +.IP [6]
          364  +For any already \fBmaintained\fR package a contributor
          365  +interested in becoming a co-maintainer can become so
          366  +with the agreement of the existing maintainer(s),
          367  +committing themselves to the rules of a replacement
          368  +maintainer (see two points previous)\&.
          369  +.RE
          370  +.sp
          371  +The responsibilities as a maintainer include:
          372  +.RS
          373  +.IP [1]
          374  +Watching Tcllib's ticket tracker for bugs, bug fixes,
          375  +and feature requests related to the new packages\&.
          376  +.IP [2]
          377  +Reviewing the aforementioned tickets, rejecting or
          378  +applying them
          379  +.IP [3]
          380  +Coordination and discussion with ticket submitter during
          381  +the development and/or application of bug fixes\&.
          382  +.RE
          383  +.IP [4]
          384  +Follow the \fBBranching and Workflow\fR of this guide\&.
          385  +.PP
          386  +.SH "BRANCHING AND WORKFLOW"
          387  +.SS "PACKAGE DEPENDENCIES"
          388  +Regarding packages and dependencies between them Tcllib occupies a
          389  +middle position between two extremes:
          390  +.IP [1]
          391  +On one side a strongly interdependent set of packages, usually
          392  +by a single author, for a single project\&. Looking at my
          393  +(Andreas Kupries) own work examples of such are
          394  +\fIMarpa\fR [https://core\&.tcl\&.tk/akupries/marpa/index],
          395  +\fICRIMP\fR [https://core\&.tcl\&.tk/akupries/crimp/index],
          396  +\fIKinetcl\fR [https://core\&.tcl\&.tk/akupries/kinetcl/index], etc\&.
          397  +.sp
          398  +For every change the author of the project handles all the
          399  +modifications cascading from any incompatibilities it
          400  +introduced to the system\&.
          401  +.IP [2]
          402  +On the other side, the world of semi-independent projects by
          403  +many different authors where authors know what packages their
          404  +own creations depend on, yet usually do not know who else
          405  +depends on them\&.
          406  +.sp
          407  +The best thing an author making an (incompatible) change to
          408  +their project can do is to for one announce such changes in
          409  +some way, and for two use versioning to distinguish the code
          410  +before and after the change\&.
          411  +.sp
          412  +The world is then responsible for adapting, be it by updating
          413  +their own projects to the new version, or by sticking to the
          414  +old\&.
          415  +.PP
          416  +As mentioned already, Tcllib lives in the middle of that\&.
          417  +.PP
          418  +While we as maintainers cannot be aware of all users of
          419  +Tcllib's packages, and thus have to rely on the mechanisms
          420  +touched on in point 2 above for that, the dependencies between
          421  +the packages contained in Tcllib are a different matter\&.
          422  +.PP
          423  +As we are collectively responsible for the usability of Tcllib
          424  +in toto to the outside world, it behooves us to be individually
          425  +mindful even of Tcllib packages we are not directly
          426  +maintaining, when they depend on packages under our
          427  +maintainership\&.
          428  +This may be as simple as coordinating with the maintainers of
          429  +the affected packages\&.
          430  +It may also require us to choose how to adapt affected packages
          431  +which do not have maintainers, i\&.e\&. modify them to use our
          432  +changed package properly, or modify them to properly depend on
          433  +the unchanged version of our package\&.
          434  +.PP
          435  +Note that the above is not only a chore but an opportunity as
          436  +well\&.
          437  +Additional insight can be had by forcing ourselves to look at
          438  +our package and the planned change(s) from an outside
          439  +perspective, to consider the ramifications of our actions on
          440  +others in general, and on dependent packages in particular\&.
          441  +.SS TRUNK
          442  +The management and use of branches is an important part of working
          443  +with a \fIDistributed Version Control System\fR (\fIDVCS\fR) like
          444  +\fIfossil\fR [https://www\&.fossil-scm\&.org/]\&.
          445  +.PP
          446  +For Tcllib the main branch of the collection is
          447  +\fItrunk\fR\&. In \fIgit\fR this branch would be called
          448  +\fImaster\fR, and this is exactly the case in the
          449  +\fIgithub mirror\fR [https://github\&.com/tcltk/tcllib/] of
          450  +Tcllib\&.
          451  +.PP
          452  +To properly support debugging \fIeach commit\fR on this
          453  +branch \fIhas to pass the entire testsuite\fR of the
          454  +collection\&. Using bisection to determine when an issue appeared
          455  +is an example of an action made easier by this constraint\&.
          456  +.PP
          457  +This is part of our collective responsibility for the usability
          458  +of Tcllib in toto to the outside world\&.
          459  +As \fIfossil\fR has no mechanism to enforce this condition
          460  +this is handled on the honor system for developers and maintainers\&.
          461  +.PP
          462  +To make the task easier Tcllib comes with a tool
          463  +("\fIsak\&.tcl\fR") providing a number of commands in
          464  +support\&. These commands are explained in the following sections
          465  +of this guide\&.
          466  +.PP
          467  +While it is possible and allowed to commit directly to trunk
          468  +remember the above constraint regarding the testsuite, and the
          469  +coming notes about other possible issues with a commit\&.
          470  +.SS BRANCHES
          471  +Given the constraints placed on the \fItrunk\fR branch of the
          472  +repository it is (strongly) recommended to perform any development
          473  +going beyond trivial changes on a non-trunk branch\&.
          474  +.PP
          475  +Outside of the trunk developers are allowed to commit
          476  +intermediate broken states of their work\&.
          477  +Only at the end of a development cycle, when the relevant
          478  +branch is considered ready for merging, will it be necessary to
          479  +perform full the set of validations ensuring that the merge to
          480  +come will create a good commit on trunk\&.
          481  +.PP
          482  +Note that while a review from a second developer is not a
          483  +required condition for merging a branch it is recommended to
          484  +seek out such an independent opinion as a means of
          485  +cross-checking the work\&.
          486  +.PP
          487  +It also recommended to give any new branch a name which aids in
          488  +determining additional details about it\&. Examples of good
          489  +things to stick into a branch name would be
          490  +.IP \(bu
          491  +Developer (nick)name
          492  +.IP \(bu
          493  +Ticket hash/reference
          494  +.IP \(bu
          495  +One or two keywords applicable to the work
          496  +.IP \(bu
          497  +\&.\&.\&.
          498  +.PP
          499  +.PP
          500  +Further, while most development branches are likely quite
          501  +short-lived, no prohibitions exist against making longer-lived
          502  +branches\&.
          503  +Creators should however be mindful that the longer such a
          504  +branch exists without merges the more divergent they will tend
          505  +to be, with an associated increase in the effort which will
          506  +have to be spent on either merging from and merging to trunk\&.
          507  +.SS "WORKING WITH BRANCHES"
          508  +In the hope of engendering good work practices now a few example
          509  +operations which will come up with branches, and their associated
          510  +fossil command (sequences)\&.
          511  +.TP
          512  +\fIAwareness\fR
          513  +When developing we have to keep ourselves aware of the context of our
          514  +work\&. On what branch are we ? What files have we changed ? What new
          515  +files are not yet known to the repository ? What has happened remotely
          516  +since we used our checkout ?
          517  +The answers to these questions become especially important when using
          518  +a long-lived checkout and coming back to it after some time away\&.
          519  +.sp
          520  +Commands to answer questions like the above are:
          521  +.RS
          522  +.TP
          523  +\fBfossil pull\fR
          524  +Get all changes done on the remote since the last pull or sync
          525  +from it\&. This has to be done first, before any of the commands
          526  +below\&.
          527  +.sp
          528  +Even if the commit in our checkout refers to the branch we want
          529  +right now control operations committed to the remote may have
          530  +changed that from underneath us\&.
          531  +.TP
          532  +\fBfossil info | grep tags\fR
          533  +.TP
          534  +\fBfossil branch list | grep '\\*'\fR
          535  +Two different ways of determining the branch our checkout is
          536  +on\&.
          537  +.TP
          538  +\fBfossil timeline\fR
          539  +What have we (and others) done recently ?
          540  +.sp
          541  +\fIAttention\fR, this information is very likely outdated, the
          542  +more the longer we did not use this checkout\&.
          543  +Run \fBfossil pull\fR first to get latest information from
          544  +the remote repository of the project\&.
          545  +.TP
          546  +\fBfossil timeline current\fR
          547  +Place the commit our checkout is based on at the top of the
          548  +timeline\&.
          549  +.TP
          550  +\fBfossil changes\fR
          551  +Lists the files we have changed compared to the commit the
          552  +checkout is based on\&.
          553  +.TP
          554  +\fBfossil extra\fR
          555  +Lists the files we have in the checkout the repository does not
          556  +know about\&. This may be leftover chaff from our work, or
          557  +something we have forgotten to \fBfossil add\fR to the
          558  +repository yet\&.
          559  +.RE
          560  +.TP
          561  +\fIClean checkouts\fR
          562  +Be aware of where you are (see first definition)\&.
          563  +.sp
          564  +For pretty much all the operation recipes below a clean
          565  +checkout is at least desired, often required\&.
          566  +To check that a checkout is clean invoke
          567  +.CS
          568  +
          569  +
          570  +    fossil changes
          571  +    fossil extra
          572  +
          573  +.CE
          574  +.IP
          575  +How to clean up when uncommitted changes of all sorts are found is
          576  +context-specific and outside of the scope of this guide\&.
          577  +.TP
          578  +\fIStarting a new branch\fR
          579  +Be aware of where you are (see first definition)\&.
          580  +.sp
          581  +Ensure that you have clean checkout (see second definition)\&.
          582  +It is \fIrequired\fR\&.
          583  +.sp
          584  +In most situations you want to be on branch \fItrunk\fR, and
          585  +you want to be on the latest commit for it\&. To get there use
          586  +.CS
          587  +
          588  +
          589  +    fossil pull
          590  +    fossil update trunk
          591  +
          592  +.CE
          593  +.IP
          594  +If some other branch is desired as the starting point for the coming
          595  +work replace \fItrunk\fR in the commands above with the name of that
          596  +branch\&.
          597  +.sp
          598  +With the base line established we now have two ways of creating
          599  +the new branch, with differing (dis)advantages\&.
          600  +The simpler way is to
          601  +.CS
          602  +
          603  +
          604  +    fossil branch new NAME_OF_NEW_BRANCH
          605  +
          606  +.CE
          607  +.IP
          608  +and start developing\&. The advantage here is that you cannot forget to
          609  +create the branch\&. The disadvantages are that we have a branch commit
          610  +unchanged from where we branched from, and that we have to use
          611  +high-handed techniques like hiding or shunning to get rid of the
          612  +commit should we decide to abandon the work before the first actual
          613  +commit on the branch\&.
          614  +.sp
          615  +The other way of creating the branch is to start developing,
          616  +and then on the first commit use the option \fB--branch\fR to tell
          617  +\fBfossil\fR that we are starting a branch now\&. I\&.e\&. run
          618  +.CS
          619  +
          620  +
          621  +    fossil commit --branch NAME_OF_NEW_BRANCH \&.\&.\&.
          622  +
          623  +.CE
          624  +.IP
          625  +where \fI\&.\&.\&.\fR are any other options used to supply the commit
          626  +message, files to commit, etc\&.
          627  +.sp
          628  +The (dis)advantages are now reversed\&.
          629  +.sp
          630  +We have no superflous commit, only what is actually
          631  +developed\&. The work is hidden until we commit to make our first
          632  +commit\&.
          633  +.sp
          634  +We may forget to use \fB--branch NAME_OF_NEW_BRANCH\fR and
          635  +then have to correct that oversight via the fossil web
          636  +interface (I am currently unaware of ways of doing such from
          637  +the command line, although some magic incantantion of
          638  +\fBfossil tag create\fR may work)\&.
          639  +.sp
          640  +It helps to keep awareness, like checking before any commit
          641  +that we are on the desired branch\&.
          642  +.TP
          643  +\fIMerging a branch into trunk\fR
          644  +Be aware of where you are (see first definition)\&.
          645  +.sp
          646  +Ensure that you have clean checkout (see second definition)\&.
          647  +In the full-blown sequence (zig-zag) it is \fIrequired\fR, due
          648  +to the merging from trunk\&. In the shorter sequence it is only
          649  +desired\&. That said, keeping the checkout clean before
          650  +any major operations is a good habit to have, in my opinion\&.
          651  +.sp
          652  +The full-blown sequencing with checks all the way is to
          653  +.RS
          654  +.IP [1]
          655  +Validate the checkout, i\&.e\&. last commit on your branch\&. Run the
          656  +full test suite and other validations, fix all the issues which
          657  +have cropped up\&.
          658  +.IP [2]
          659  +Merge the latest state of the \fItrunk\fR (see next definition)\&.
          660  +.IP [3]
          661  +Validate the checkout again\&. The incoming trunk changes may
          662  +have broken something now\&. Do any required fixes\&.
          663  +.IP [4]
          664  +Now merge to the trunk using
          665  +.CS
          666  +
          667  +
          668  +    fossil update trunk
          669  +    fossil merge --integrate YOUR_BRANCH
          670  +
          671  +.CE
          672  +.IP [5]
          673  +At this point the checkout should be in the same state as at
          674  +the end of point (3) above, because we resolved any issues with
          675  +the trunk already\&. Thus a simple
          676  +.CS
          677  +
          678  +
          679  +    fossil commit \&.\&.\&.
          680  +
          681  +.CE
          682  +.IP
          683  +should be sufficient now to commit the merge back and close the
          684  +branch (due to the \fB--integrate\fR we used on the merge)\&.
          685  +.sp
          686  +The more paranoid may validate the checkout a third time before
          687  +commiting\&.
          688  +.RE
          689  +.sp
          690  +I call this a \fIzig-zag merge\fR because of how the arrows
          691  +look in the timeline, from trunk to feature branch for the
          692  +first merge, and then back for the final merge\&.
          693  +.sp
          694  +A less paranoid can do what I call a \fIsimple merge\fR,
          695  +which moves step (2) after step (4) and skips step (3)
          696  +entirely\&. The resulting shorter sequence is
          697  +.RS
          698  +.IP [1]
          699  +Validate
          700  +.IP [2]
          701  +Merge to trunk
          702  +.IP [3]
          703  +Validate again
          704  +.IP [4]
          705  +Commit to trunk
          706  +.RE
          707  +.IP
          708  +The last step after either zig-zag or plain merge is to
          709  +.CS
          710  +
          711  +
          712  +    fossil sync
          713  +
          714  +.CE
          715  +.IP
          716  +This saves our work to the remote side, and further gives us any other
          717  +work done while we were doing our merge\&. It especially allows us to
          718  +check if we raced somebody else, resulting in a split trunk\&.
          719  +.sp
          720  +When that happens we should coordinate with the other developer
          721  +on who fixes the split, to ensure that we do not race each
          722  +other again\&.
          723  +.TP
          724  +\fIMerging from trunk\fR
          725  +Be aware of where you are (see first definition)\&.
          726  +.sp
          727  +Ensure that you have clean checkout (see second definition)\&.
          728  +It is \fIrequired\fR\&.
          729  +.sp
          730  +In most situations you want to import the latest commit of
          731  +branch \fItrunk\fR (or other origin)\&. To get it use
          732  +.CS
          733  +
          734  +
          735  +    fossil pull
          736  +
          737  +.CE
          738  +.sp
          739  +With that done we can now import this commit into our current
          740  +branch with
          741  +.CS
          742  +
          743  +
          744  +    fossil merge trunk
          745  +
          746  +.CE
          747  +.sp
          748  +Even if \fBfossil\fR does not report any conflicts it is a
          749  +good idea to check that the operation has not broken the new
          750  +and/or changed functionality we are working on\&.
          751  +.sp
          752  +With the establishment of a good merge we then save the state
          753  +with
          754  +.CS
          755  +
          756  +
          757  +    fossil commit \&.\&.\&.
          758  +
          759  +.CE
          760  +.IP
          761  +before continuing development\&.
          762  +.PP
          763  +.SS "VERSION NUMBERS"
          764  +In Tcllib all changes to a package have to come with an increment of
          765  +its version number\&. What part is incremented (patchlevel, minor, major
          766  +version) depends on the kind of change made\&. With multiple changes in
          767  +a commit the highest "wins"\&.
          768  +.PP
          769  +When working in a development branch the version change can be
          770  +deferred until it is time to merge, and then has to cover all
          771  +the changes in the branch\&.
          772  +.PP
          773  +Below a list of the kinds of changes and their associated
          774  +version increments:
          775  +.TP
          776  +\fID - documentation\fR
          777  +No increment
          778  +.TP
          779  +\fIT - testsuite\fR
          780  +No increment
          781  +.TP
          782  +\fIB - bugfix\fR
          783  +Patchlevel
          784  +.TP
          785  +\fII - implementation tweak\fR
          786  +Patchlevel
          787  +.TP
          788  +\fIP - performance tweak\fR
          789  +Patchlevel
          790  +.TP
          791  +\fIE - backward-compatible extension\fR
          792  +Minor
          793  +.TP
          794  +\fIAPI - incompatible change\fR
          795  +Major
          796  +.PP
          797  +.PP
          798  +Note that a commit containing a version increment has to
          799  +mention the new version number in its commit message, as well
          800  +as the kind of change which caused it\&.
          801  +.PP
          802  +Note further that the version number of a package currently
          803  +exists in three places\&. An increment has to update all of them:
          804  +.IP [1]
          805  +The package implementation\&.
          806  +.IP [2]
          807  +The package index ("\fIpkgIndex\&.tcl\fR")
          808  +.IP [3]
          809  +The package documentation\&.
          810  +.PP
          811  +.PP
          812  +The "\fIsak\&.tcl\fR" command \fBvalidate version\fR helps
          813  +finding discrepancies between the first two\&.
          814  +All the other \fBvalidate\fR methods are also of interest to
          815  +any developer\&. Invoke it with
          816  +.CS
          817  +
          818  + sak\&.tcl help validate
          819  +.CE
          820  +to see their documentation\&.
          821  +.SH "STRUCTURAL OVERVIEW"
          822  +.SS "MAIN DIRECTORIES"
          823  +The main directories in the Tcllib toplevel directory and of interest
          824  +to a developer are:
          825  +.TP
          826  +"\fImodules\fR"
          827  +Each child directory represents one or more packages\&.
          828  +In the case of the latter the packages are usually related in some
          829  +way\&. Examples are "\fIbase64\fR", "\fImath\fR", and "\fIstruct\fR", with
          830  +loose (base64) to strong (math) relations between the packages in the
          831  +directory\&.
          832  +.TP
          833  +"\fIapps\fR"
          834  +This directory contains all the installable applications, with their
          835  +documentation\&. Note that this directory is currently \fInot\fR split
          836  +into sub-directories\&.
          837  +.TP
          838  +"\fIexamples\fR"
          839  +Each child directory "\fIfoo\fR" contains one or more example
          840  +application for the packages in "\fImodules/foo\fR"\&. These examples are
          841  +generally not polished enough to be considered for installation\&.
          842  +.PP
          843  +.SS "MORE DIRECTORIES"
          844  +.TP
          845  +"\fIconfig\fR"
          846  +This directory contains files supporting the Unix build system,
          847  +i\&.e\&. "\fIconfigure\fR" and "\fIMakefile\&.in\fR"\&.
          848  +.TP
          849  +"\fIdevdoc\fR"
          850  +This directories contains the doctools sources for the global
          851  +documentation, like this document and its sibling guides\&.
          852  +.TP
          853  +"\fIembedded\fR"
          854  +This directory contains the entire documentation formatted for
          855  +\fIHTML\fR and styled to properly mix into the web site generated by
          856  +fossil for the repository\&.
          857  +.sp
          858  +This is the documentation accessible from the Tcllib home
          859  +directory, represented in the repository as "\fIembedded/index\&.md\fR"\&.
          860  +.TP
          861  +"\fIidoc\fR"
          862  +This directory contains the entire documentation formatted for
          863  +\fInroff\fR and \fIHTML\fR, the latter without any styling\&.
          864  +This is the documentation which will be installed\&.
          865  +.TP
          866  +"\fIsupport\fR"
          867  +This directory contains the sources of internal packages and utilities
          868  +used in the implementation of the "\fIinstaller\&.tcl\fR" and
          869  +"\fIsak\&.tcl\fR" scripts/tools\&.
          870  +.PP
          871  +.SS "TOP FILES"
          872  +.TP
          873  +"\fIaclocal\&.m4\fR"
          874  +.TP
          875  +"\fIconfigure\fR"
          876  +.TP
          877  +"\fIconfigure\&.in\fR"
          878  +.TP
          879  +"\fIMakefile\&.in\fR"
          880  +These four files comprise the Unix build system layered on top of the
          881  +"\fIinstaller\&.tcl\fR" script\&.
          882  +.TP
          883  +"\fIinstaller\&.tcl\fR"
          884  +The Tcl-based installation script/tool\&.
          885  +.TP
          886  +"\fIproject\&.shed\fR"
          887  +Configuration file for \fISean Wood\fR's \fBPracTcl\fR
          888  +buildsystem\&.
          889  +.TP
          890  +"\fIsak\&.tcl\fR"
          891  +This is the main tool for developers and release managers, the
          892  +\fISwiss Army Knife\fR of management operations on the collection\&.
          893  +.TP
          894  +"\fIChangeLog\fR"
          895  +The log of changes to the global support, when the sources were held
          896  +in \fICVS\fR\&. Not relevant any longer with the switch to the
          897  +\fIfossil\fR SCM\&.
          898  +.TP
          899  +"\fIlicense\&.terms\fR"
          900  +The license in plain ASCII\&. See also \fITcllib - License\fR for the
          901  +nicely formatted form\&. The text is identical\&.
          902  +.TP
          903  +"\fIREADME\&.md\fR"
          904  +.TP
          905  +"\fI\&.github/CONTRIBUTING\&.md\fR"
          906  +.TP
          907  +"\fI\&.github/ISSUE_TEMPLATE\&.md\fR"
          908  +.TP
          909  +"\fI\&.github/PULL_REQUEST_TEMPLATE\&.md\fR"
          910  +These markdown-formatted documents are used and shown by the github
          911  +mirror of these sources, pointing people back to the official location
          912  +and issue trackers\&.
          913  +.TP
          914  +"\fIDESCRIPTION\&.txt\fR"
          915  +.TP
          916  +"\fISTATUS\fR"
          917  +.TP
          918  +"\fItcllib\&.spec\fR"
          919  +.TP
          920  +"\fItcllib\&.tap\fR"
          921  +.TP
          922  +"\fItcllib\&.yml\fR"
          923  +????
          924  +.PP
          925  +.SS "FILE TYPES"
          926  +The most common file types, by file extension, are:
          927  +.TP
          928  +"\fI\&.tcl\fR"
          929  +Tcl code for a package, application, or example\&.
          930  +.TP
          931  +"\fI\&.man\fR"
          932  +Doctools-formatted documentation, usually for a package\&.
          933  +.TP
          934  +"\fI\&.test\fR"
          935  +Test suite for a package, or part of\&.
          936  +Based on \fBtcltest\fR\&.
          937  +.TP
          938  +"\fI\&.bench\fR"
          939  +Performance benchmarks for a package, or part of\&.
          940  +Based on "\fImodules/bench\fR"\&.
          941  +.TP
          942  +"\fI\&.pcx\fR"
          943  +Syntax rules for \fITclDevKit\fR's \fBtclchecker\fR\&. Using these
          944  +rules allows the checker to validate the use of commands of a Tcllib
          945  +package \fBfoo\fR without having to scan the "\fI\&.tcl\fR" files
          946  +implementing it\&.
          947  +.PP
          948  +.SH "TESTSUITE TOOLING"
          949  +Testsuites in Tcllib are based on Tcl's standard test package
          950  +\fBtcltest\fR, plus utilities found in the directory
          951  +"\fImodules/devtools\fR"
          952  +.PP
          953  +Tcllib developers invoke the suites through the
          954  +\fBtest run\fR method of the "\fIsak\&.tcl\fR" tool, with other methods
          955  +of \fBtest\fR providing management operations, for example setting a
          956  +list of standard Tcl shells to use\&.
          957  +.SS "INVOKE THE TESTSUITES OF A SPECIFIC MODULE"
          958  +Invoke either
          959  +.CS
          960  +
          961  +  \&./sak\&.tcl test run foo
          962  +.CE
          963  +or
          964  +.CS
          965  +
          966  +  \&./sak\&.tcl test run modules/foo
          967  +.CE
          968  +to invoke the testsuites found in a specific module "\fIfoo\fR"\&.
          969  +.SS "INVOKE THE TESTSUITES OF ALL MODULES"
          970  +Invoke the tool without a module name, i\&.e\&.
          971  +.CS
          972  +
          973  +  \&./sak\&.tcl test run
          974  +.CE
          975  +to invoke the testsuites of all modules\&.
          976  +.SS "DETAILED TEST LOGS"
          977  +In all the previous examples the test runner will write a combination
          978  +of progress display and testsuite log to the standard output, showing
          979  +for each module only the tests that passed or failed and how many of
          980  +each in a summary at the end\&.
          981  +.PP
          982  +To get a detailed log, it is necessary to invoke the test
          983  +runner with additional options\&.
          984  +.PP
          985  +For one:
          986  +.CS
          987  +
          988  +
          989  +   \&./sak\&.tcl test run --log LOG foo
          990  +
          991  +.CE
          992  +While this shows the same short log on the terminal as before, it also
          993  +writes a detailed log to the file "\fILOG\&.log\fR", and excerpts to
          994  +other files ("\fILOG\&.summary\fR", "\fILOG\&.failures\fR", etc\&.)\&.
          995  +.PP
          996  +For two:
          997  +.CS
          998  +
          999  +
         1000  +  \&./sak\&.tcl test run -v foo
         1001  +
         1002  +.CE
         1003  +This writes the detailed log to the standard output, instead of the
         1004  +short log\&.
         1005  +.PP
         1006  +Regardless of form, the detailed log contains a list of all test
         1007  +cases executed, which failed, and how they failed (expected versus
         1008  +actual results)\&.
         1009  +.SS "SHELL SELECTION"
         1010  +By default the test runner will use all the Tcl shells specified via
         1011  +\fBtest add\fR to invoke the specified testsuites, if any\&. If no
         1012  +such are specified it will fall back to the Tcl shell used to run the
         1013  +tool itself\&.
         1014  +.PP
         1015  +Use option \fB--shell\fR to explicitly specify the Tcl shell
         1016  +to use, like
         1017  +.CS
         1018  +
         1019  +
         1020  +  \&./sak\&.tcl test run --shell /path/to/tclsh \&.\&.\&.
         1021  +
         1022  +.CE
         1023  +.SS HELP
         1024  +Invoke the tool as
         1025  +.CS
         1026  +
         1027  +  \&./sak\&.tcl help test
         1028  +.CE
         1029  +to see the detailed help for all methods of \fBtest\fR, and the
         1030  +associated options\&.
         1031  +.SH "DOCUMENTATION TOOLING"
         1032  +The standard format used for documentation of packages and other
         1033  +things in Tcllib is \fIdoctools\fR\&.
         1034  +Its supporting packages are a part of Tcllib, see the directories
         1035  +"\fImodules/doctools\fR" and "\fImodules/dtplite\fR"\&. The latter is
         1036  +an application package, with the actual application
         1037  +"\fIapps/dtplite\fR" a light wrapper around it\&.
         1038  +.PP
         1039  +Tcllib developers gain access to these through the \fBdoc\fR
         1040  +method of the "\fIsak\&.tcl\fR" tool, another (internal) wrapper around
         1041  +the "\fImodules/dtplite\fR" application package\&.
         1042  +.SS "GENERATE DOCUMENTATION FOR A SPECIFIC MODULE"
         1043  +Invoke either
         1044  +.CS
         1045  +
         1046  +  \&./sak\&.tcl doc html foo
         1047  +.CE
         1048  +or
         1049  +.CS
         1050  +
         1051  +  \&./sak\&.tcl doc html modules/foo
         1052  +.CE
         1053  +to generate HTML for the documentation found in the module "\fIfoo\fR"\&.
         1054  +Instead of \fBhtml\fR any other supported format can be used here,
         1055  +of course\&.
         1056  +.PP
         1057  +The generated formatted documentation will be placed into a
         1058  +directory "\fIdoc\fR" in the current working directory\&.
         1059  +.SS "GENERATE DOCUMENTATION FOR ALL MODULES"
         1060  +Invoke the tool without a module name, i\&.e\&.
         1061  +.CS
         1062  +
         1063  +  \&./sak\&.tcl doc html
         1064  +.CE
         1065  +to generate HTML for the documentation found in all modules\&.
         1066  +Instead of \fBhtml\fR any other supported format can be used here,
         1067  +of course\&.
         1068  +.PP
         1069  +The generated formatted documentation will be placed into a
         1070  +directory "\fIdoc\fR" in the current working directory\&.
         1071  +.SS "AVAILABLE OUTPUT FORMATS, HELP"
         1072  +Invoke the tool as
         1073  +.CS
         1074  +
         1075  +  \&./sak\&.tcl help doc
         1076  +.CE
         1077  +to see the entire set of supported output formats which can be
         1078  +generated\&.
         1079  +.SS "VALIDATION WITHOUT OUTPUT"
         1080  +Note the special format \fBvalidate\fR\&.
         1081  +.PP
         1082  +Using this value as the name of the format to generate forces
         1083  +the tool to simply check that the documentation is syntactically
         1084  +correct, without generating actual output\&.
         1085  +.PP
         1086  +Invoke it as either
         1087  +.CS
         1088  +
         1089  +  \&./sak\&.tcl doc validate (modules/)foo
         1090  +.CE
         1091  +or
         1092  +.CS
         1093  +
         1094  +  \&./sak\&.tcl doc validate
         1095  +.CE
         1096  +to either check the packages of a specific module or check all of
         1097  +them\&.
         1098  +.SH "NOTES ON WRITING A TESTSUITE"
         1099  +While previous sections talked about running the testsuites for a
         1100  +module and the packages therein, this has no meaning if the module in
         1101  +question has no testsuites at all\&.
         1102  +.PP
         1103  +This section gives a very basic overview on possible
         1104  +methodologies for writing tests and testsuites\&.
         1105  +.PP
         1106  +First there are "drudgery" tests\&. Written to check absolutely
         1107  +basic assumptions which should never fail\&.
         1108  +.PP
         1109  +For example for a command FOO taking two arguments, three tests
         1110  +calling it with zero, one, and three arguments\&. The basic checks that
         1111  +the command fails if it has not enough arguments, or too many\&.
         1112  +.PP
         1113  +After that come the tests checking things based on our
         1114  +knowledge of the command, about its properties and assumptions\&. Some
         1115  +examples based on the graph operations added during Google's Summer of
         1116  +Code 2009 are:
         1117  +.IP \(bu
         1118  +The BellmanFord command in struct::graph::ops takes a
         1119  +\fIstartnode\fR as argument, and this node should be a node of
         1120  +the graph\&. This equals one test case checking the behavior when the
         1121  +specified node is not a node of the graph\&.
         1122  +.sp
         1123  +This often gives rise to code in the implementation which
         1124  +explicitly checks the assumption and throws an understandable error,
         1125  +instead of letting the algorithm fail later in some weird
         1126  +non-deterministic way\&.
         1127  +.sp
         1128  +It is not always possible to do such checks\&. The graph argument
         1129  +for example is just a command in itself, and while we expect
         1130  +it to exhibit a certain interface, i\&.e\&. a set of sub-commands
         1131  +aka methods, we cannot check that it has them, except by
         1132  +actually trying to use them\&. That is done by the algorithm
         1133  +anyway, so an explicit check is just overhead we can get by
         1134  +without\&.
         1135  +.IP \(bu
         1136  +IIRC one of the distinguishing characteristic of either
         1137  +BellmanFord and/or Johnson is that they are able to handle
         1138  +negative weights\&. Whereas Dijkstra requires positive weights\&.
         1139  +.sp
         1140  +This induces (at least) three testcases \&.\&.\&. Graph with all
         1141  +positive weights, all negative, and a mix of positive and
         1142  +negative weights\&.
         1143  +Thinking further does the algorithm handle the weight
         1144  +\fB0\fR as well ? Another test case, or several, if we mix
         1145  +zero with positive and negative weights\&.
         1146  +.IP \(bu
         1147  +The two algorithms we are currently thinking about are about
         1148  +distances between nodes, and distance can be 'Inf'inity,
         1149  +i\&.e\&. nodes may not be connected\&. This means that good test
         1150  +cases are
         1151  +.RS
         1152  +.IP [1]
         1153  +Strongly connected graph
         1154  +.IP [2]
         1155  +Connected graph
         1156  +.IP [3]
         1157  +Disconnected graph\&.
         1158  +.RE
         1159  +.sp
         1160  +At the extremes of strongly connected and disconnected
         1161  +we have the fully connected graphs and graphs without edges,
         1162  +only nodes, i\&.e\&. completely disconnected\&.
         1163  +.IP \(bu
         1164  +IIRC both of the algorithms take weighted arcs, and fill in a
         1165  +default if arcs are left unweighted in the input graph\&.
         1166  +.sp
         1167  +This also induces three test cases:
         1168  +.RS
         1169  +.IP [1]
         1170  +Graph will all arcs with explicit weights\&.
         1171  +.IP [2]
         1172  +Graph without weights at all\&.
         1173  +.IP [3]
         1174  +Graph with mixture of weighted and unweighted graphs\&.
         1175  +.RE
         1176  +.PP
         1177  +.PP
         1178  +What was described above via examples is called
         1179  +\fIblack-box\fR testing\&. Test cases are designed and written based on
         1180  +the developer's knowledge of the properties of the algorithm and its
         1181  +inputs, without referencing a particular implementation\&.
         1182  +.PP
         1183  +Going further, a complement to \fIblack-box\fR testing is
         1184  +\fIwhite-box\fR\&. For this we know the implementation of the
         1185  +algorithm, we look at it and design our tests cases so that they force
         1186  +the code through all possible paths in the implementation\&. Wherever a
         1187  +decision is made we have a test case forcing a specific direction of
         1188  +the decision, for all possible combinations and directions\&. It is easy
         1189  +to get a combinatorial explosion in the number of needed test-cases\&.
         1190  +.PP
         1191  +In practice I often hope that the black-box tests I have made
         1192  +are enough to cover all the paths, obviating the need for white-box
         1193  +tests\&.
         1194  +.PP
         1195  +The above should be enough to make it clear that writing tests
         1196  +for an algorithm takes at least as much time as coding the algorithm,
         1197  +and often more time\&. Much more time\&.
         1198  +See for example also \fIhttp://sqlite\&.org/testing\&.html\fR, a writeup
         1199  +on how the Sqlite database engine is tested\&. Another article of
         1200  +interest might be \fIhttps://www\&.researchgate\&.net/publication/298896236\fR\&.
         1201  +While geared to a particular numerical algorithm it still shows that
         1202  +even a simple-looking algorithm can lead to an incredible number of
         1203  +test cases\&.
         1204  +.PP
         1205  +An interesting connection is to documentation\&. In one
         1206  +direction, the properties checked with black-box testing are exactly
         1207  +the properties which should be documented in the algorithm's man
         1208  +page\&. And conversely, the documentation of the properties of an
         1209  +algorithm makes a good reference to base the black-box tests on\&.
         1210  +.PP
         1211  +In practice test cases and documentation often get written
         1212  +together, cross-influencing each other\&. And the actual writing of test
         1213  +cases is a mix of black and white box, possibly influencing the
         1214  +implementation while writing the tests\&. Like writing a test for a
         1215  +condition like \fIstartnode not in input graph\fR serving as
         1216  +reminder to put a check for this condition into the code\&.
         1217  +.SH "INSTALLATION TOOLING"
         1218  +A last thing to consider when adding a new package to the collection
         1219  +is installation\&.
         1220  +.PP
         1221  +How to \fIuse\fR the "\fIinstaller\&.tcl\fR" script is documented
         1222  +in \fITcllib - The Installer's Guide\fR\&.
         1223  +.PP
         1224  +Here we document how to extend said installer so that it may
         1225  +install new package(s) and/or application(s)\&.
         1226  +.PP
         1227  +In most cases only a single file has to be modified, the
         1228  +"\fIsupport/installation/modules\&.tcl\fR" holding one command per module
         1229  +and application to install\&.
         1230  +.PP
         1231  +The relevant commands are:
         1232  +.TP
         1233  +\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR
         1234  +Install the packages of module \fIname\fR, found in
         1235  +"\fImodules/\fIname\fR\fR"\&.
         1236  +.sp
         1237  +The \fIcode-action\fR is responsible for installing the
         1238  +packages and their index\&. The system currently provides
         1239  +.RS
         1240  +.TP
         1241  +\fB_tcl\fR
         1242  +Copy all "\fI\&.tcl\fR" files found in
         1243  +"\fImodules/\fIname\fR\fR" into the installation\&.
         1244  +.TP
         1245  +\fB_tcr\fR
         1246  +As \fB_tcl\fR, copy the "\fI\&.tcl\fR" files found in
         1247  +the subdirectories of "\fImodules/\fIname\fR\fR" as well\&.
         1248  +.TP
         1249  +\fB_tci\fR
         1250  +As \fB_tcl\fR, and copy the "\fItclIndex\&.tcl\fR" file
         1251  +as well\&.
         1252  +.TP
         1253  +\fB_msg\fR
         1254  +As \fB_tcl\fR, and copy the subdirectory "\fImsgs\fR"
         1255  +as well\&.
         1256  +.TP
         1257  +\fB_doc\fR
         1258  +As \fB_tcl\fR, and copy the subdirectory
         1259  +"\fImpformats\fR" as well\&.
         1260  +.TP
         1261  +\fB_tex\fR
         1262  +As \fB_tcl\fR, and copy "\fI\&.tex\fR" files as well\&.
         1263  +.RE
         1264  +.sp
         1265  +The \fIdoc-action\fR is responsible for installing the package
         1266  +documentation\&. The system currently provides
         1267  +.RS
         1268  +.TP
         1269  +\fB_null\fR
         1270  +No documentation available, do nothing\&.
         1271  +.TP
         1272  +\fB_man\fR
         1273  +Process the "\fI\&.man\fR" files found in
         1274  +"\fImodules/\fIname\fR\fR" and install the results (nroff and/or HTML)
         1275  +in the proper location, as given to the installer\&.
         1276  +.sp
         1277  +This is actually a fallback, normally the installer uses the
         1278  +pre-made formatted documentation found under "\fIidoc\fR"\&.
         1279  +.RE
         1280  +.sp
         1281  +The \fIexample-action\fR is responsible for installing the
         1282  +examples\&. The system currently provides
         1283  +.RS
         1284  +.TP
         1285  +\fB_null\fR
         1286  +No examples available, do nothing\&.
         1287  +.TP
         1288  +\fB_exa\fR
         1289  +Copy the the directory "\fIexamples/\fIname\fR\fR"
         1290  +recursively to the install location for examples\&.
         1291  +.RE
         1292  +.TP
         1293  +\fBApplication\fR \fIname\fR
         1294  +Install the application with \fIname\fR, found in "\fIapps\fR"\&.
         1295  +.TP
         1296  +\fBExclude\fR \fIname\fR
         1297  +This command signals to the installer which of the listed modules to
         1298  +\fInot\fR install\&. I\&.e\&. they name the deprecated modules of Tcllib\&.
         1299  +.PP
         1300  +.PP
         1301  +If, and only if the above actions are not suitable for the new
         1302  +module then a second file has to be modified,
         1303  +"\fIsupport/installation/actions\&.tcl\fR"\&.
         1304  +.PP
         1305  +This file contains the implementations of the available
         1306  +actions, and is the place where any custom action needed to handle the
         1307  +special circumstances of module has to be added\&.

Added idoc/man/files/devdoc/tcllib_installer.n.

            1  +'\"
            2  +'\" Generated from file 'tcllib_installer\&.man' by tcllib/doctools with format 'nroff'
            3  +'\"
            4  +.TH "tcllib_install_guide" n 1 tcllib ""
            5  +.\" The -*- nroff -*- definitions below are for supplemental macros used
            6  +.\" in Tcl/Tk manual entries.
            7  +.\"
            8  +.\" .AP type name in/out ?indent?
            9  +.\"	Start paragraph describing an argument to a library procedure.
           10  +.\"	type is type of argument (int, etc.), in/out is either "in", "out",
           11  +.\"	or "in/out" to describe whether procedure reads or modifies arg,
           12  +.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
           13  +.\"	needed;  use .AS below instead)
           14  +.\"
           15  +.\" .AS ?type? ?name?
           16  +.\"	Give maximum sizes of arguments for setting tab stops.  Type and
           17  +.\"	name are examples of largest possible arguments that will be passed
           18  +.\"	to .AP later.  If args are omitted, default tab stops are used.
           19  +.\"
           20  +.\" .BS
           21  +.\"	Start box enclosure.  From here until next .BE, everything will be
           22  +.\"	enclosed in one large box.
           23  +.\"
           24  +.\" .BE
           25  +.\"	End of box enclosure.
           26  +.\"
           27  +.\" .CS
           28  +.\"	Begin code excerpt.
           29  +.\"
           30  +.\" .CE
           31  +.\"	End code excerpt.
           32  +.\"
           33  +.\" .VS ?version? ?br?
           34  +.\"	Begin vertical sidebar, for use in marking newly-changed parts
           35  +.\"	of man pages.  The first argument is ignored and used for recording
           36  +.\"	the version when the .VS was added, so that the sidebars can be
           37  +.\"	found and removed when they reach a certain age.  If another argument
           38  +.\"	is present, then a line break is forced before starting the sidebar.
           39  +.\"
           40  +.\" .VE
           41  +.\"	End of vertical sidebar.
           42  +.\"
           43  +.\" .DS
           44  +.\"	Begin an indented unfilled display.
           45  +.\"
           46  +.\" .DE
           47  +.\"	End of indented unfilled display.
           48  +.\"
           49  +.\" .SO ?manpage?
           50  +.\"	Start of list of standard options for a Tk widget. The manpage
           51  +.\"	argument defines where to look up the standard options; if
           52  +.\"	omitted, defaults to "options". The options follow on successive
           53  +.\"	lines, in three columns separated by tabs.
           54  +.\"
           55  +.\" .SE
           56  +.\"	End of list of standard options for a Tk widget.
           57  +.\"
           58  +.\" .OP cmdName dbName dbClass
           59  +.\"	Start of description of a specific option.  cmdName gives the
           60  +.\"	option's name as specified in the class command, dbName gives
           61  +.\"	the option's name in the option database, and dbClass gives
           62  +.\"	the option's class in the option database.
           63  +.\"
           64  +.\" .UL arg1 arg2
           65  +.\"	Print arg1 underlined, then print arg2 normally.
           66  +.\"
           67  +.\" .QW arg1 ?arg2?
           68  +.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
           69  +.\"
           70  +.\" .PQ arg1 ?arg2?
           71  +.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
           72  +.\"	(for trailing punctuation) and then a closing parenthesis.
           73  +.\"
           74  +.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
           75  +.if t .wh -1.3i ^B
           76  +.nr ^l \n(.l
           77  +.ad b
           78  +.\"	# Start an argument description
           79  +.de AP
           80  +.ie !"\\$4"" .TP \\$4
           81  +.el \{\
           82  +.   ie !"\\$2"" .TP \\n()Cu
           83  +.   el          .TP 15
           84  +.\}
           85  +.ta \\n()Au \\n()Bu
           86  +.ie !"\\$3"" \{\
           87  +\&\\$1 \\fI\\$2\\fP (\\$3)
           88  +.\".b
           89  +.\}
           90  +.el \{\
           91  +.br
           92  +.ie !"\\$2"" \{\
           93  +\&\\$1	\\fI\\$2\\fP
           94  +.\}
           95  +.el \{\
           96  +\&\\fI\\$1\\fP
           97  +.\}
           98  +.\}
           99  +..
          100  +.\"	# define tabbing values for .AP
          101  +.de AS
          102  +.nr )A 10n
          103  +.if !"\\$1"" .nr )A \\w'\\$1'u+3n
          104  +.nr )B \\n()Au+15n
          105  +.\"
          106  +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
          107  +.nr )C \\n()Bu+\\w'(in/out)'u+2n
          108  +..
          109  +.AS Tcl_Interp Tcl_CreateInterp in/out
          110  +.\"	# BS - start boxed text
          111  +.\"	# ^y = starting y location
          112  +.\"	# ^b = 1
          113  +.de BS
          114  +.br
          115  +.mk ^y
          116  +.nr ^b 1u
          117  +.if n .nf
          118  +.if n .ti 0
          119  +.if n \l'\\n(.lu\(ul'
          120  +.if n .fi
          121  +..
          122  +.\"	# BE - end boxed text (draw box now)
          123  +.de BE
          124  +.nf
          125  +.ti 0
          126  +.mk ^t
          127  +.ie n \l'\\n(^lu\(ul'
          128  +.el \{\
          129  +.\"	Draw four-sided box normally, but don't draw top of
          130  +.\"	box if the box started on an earlier page.
          131  +.ie !\\n(^b-1 \{\
          132  +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          133  +.\}
          134  +.el \}\
          135  +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          136  +.\}
          137  +.\}
          138  +.fi
          139  +.br
          140  +.nr ^b 0
          141  +..
          142  +.\"	# VS - start vertical sidebar
          143  +.\"	# ^Y = starting y location
          144  +.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
          145  +.de VS
          146  +.if !"\\$2"" .br
          147  +.mk ^Y
          148  +.ie n 'mc \s12\(br\s0
          149  +.el .nr ^v 1u
          150  +..
          151  +.\"	# VE - end of vertical sidebar
          152  +.de VE
          153  +.ie n 'mc
          154  +.el \{\
          155  +.ev 2
          156  +.nf
          157  +.ti 0
          158  +.mk ^t
          159  +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
          160  +.sp -1
          161  +.fi
          162  +.ev
          163  +.\}
          164  +.nr ^v 0
          165  +..
          166  +.\"	# Special macro to handle page bottom:  finish off current
          167  +.\"	# box/sidebar if in box/sidebar mode, then invoked standard
          168  +.\"	# page bottom macro.
          169  +.de ^B
          170  +.ev 2
          171  +'ti 0
          172  +'nf
          173  +.mk ^t
          174  +.if \\n(^b \{\
          175  +.\"	Draw three-sided box if this is the box's first page,
          176  +.\"	draw two sides but no top otherwise.
          177  +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          178  +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          179  +.\}
          180  +.if \\n(^v \{\
          181  +.nr ^x \\n(^tu+1v-\\n(^Yu
          182  +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
          183  +.\}
          184  +.bp
          185  +'fi
          186  +.ev
          187  +.if \\n(^b \{\
          188  +.mk ^y
          189  +.nr ^b 2
          190  +.\}
          191  +.if \\n(^v \{\
          192  +.mk ^Y
          193  +.\}
          194  +..
          195  +.\"	# DS - begin display
          196  +.de DS
          197  +.RS
          198  +.nf
          199  +.sp
          200  +..
          201  +.\"	# DE - end display
          202  +.de DE
          203  +.fi
          204  +.RE
          205  +.sp
          206  +..
          207  +.\"	# SO - start of list of standard options
          208  +.de SO
          209  +'ie '\\$1'' .ds So \\fBoptions\\fR
          210  +'el .ds So \\fB\\$1\\fR
          211  +.SH "STANDARD OPTIONS"
          212  +.LP
          213  +.nf
          214  +.ta 5.5c 11c
          215  +.ft B
          216  +..
          217  +.\"	# SE - end of list of standard options
          218  +.de SE
          219  +.fi
          220  +.ft R
          221  +.LP
          222  +See the \\*(So manual entry for details on the standard options.
          223  +..
          224  +.\"	# OP - start of full description for a single option
          225  +.de OP
          226  +.LP
          227  +.nf
          228  +.ta 4c
          229  +Command-Line Name:	\\fB\\$1\\fR
          230  +Database Name:	\\fB\\$2\\fR
          231  +Database Class:	\\fB\\$3\\fR
          232  +.fi
          233  +.IP
          234  +..
          235  +.\"	# CS - begin code excerpt
          236  +.de CS
          237  +.RS
          238  +.nf
          239  +.ta .25i .5i .75i 1i
          240  +..
          241  +.\"	# CE - end code excerpt
          242  +.de CE
          243  +.fi
          244  +.RE
          245  +..
          246  +.\"	# UL - underline word
          247  +.de UL
          248  +\\$1\l'|0\(ul'\\$2
          249  +..
          250  +.\"	# QW - apply quotation marks to word
          251  +.de QW
          252  +.ie '\\*(lq'"' ``\\$1''\\$2
          253  +.\"" fix emacs highlighting
          254  +.el \\*(lq\\$1\\*(rq\\$2
          255  +..
          256  +.\"	# PQ - apply parens and quotation marks to word
          257  +.de PQ
          258  +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
          259  +.\"" fix emacs highlighting
          260  +.el (\\*(lq\\$1\\*(rq\\$2)\\$3
          261  +..
          262  +.\"	# QR - quoted range
          263  +.de QR
          264  +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
          265  +.\"" fix emacs highlighting
          266  +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
          267  +..
          268  +.\"	# MT - "empty" string
          269  +.de MT
          270  +.QW ""
          271  +..
          272  +.BS
          273  +.SH NAME
          274  +tcllib_install_guide \- Tcllib - The Installer's Guide
          275  +.SH DESCRIPTION
          276  +Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a
          277  +package itself\&. It is a collection of (semi-independent) \fITcl\fR
          278  +packages that provide utility functions useful to a large collection
          279  +of Tcl programmers\&.
          280  +.PP
          281  +The audience of this document is anyone wishing to build and install
          282  +the packages found in Tcllib, for either themselves, or others\&.
          283  +.PP
          284  +For developers intending to work on the packages themselves we
          285  +additionally provide
          286  +.IP [1]
          287  +\fITcllib - The Developer's Guide\fR\&.
          288  +.PP
          289  +.PP
          290  +Please read \fITcllib - How To Get The Sources\fR first, if that
          291  +was not done already\&. Here we assume that the sources are already
          292  +available in a directory of your choice\&.
          293  +.PP
          294  +.SH REQUISITES
          295  +Before Tcllib can be build and used a number of requisites must be installed\&.
          296  +These are:
          297  +.IP [1]
          298  +The scripting language Tcl\&.
          299  +For details see \fBTcl\fR\&.
          300  +.IP [2]
          301  +Optionally, the \fBcritcl\fR package (C embedding) for \fBTcl\fR\&.
          302  +For details see \fBCriTcl\fR\&.
          303  +.PP
          304  +This list assumes that the machine where Tcllib is to be installed is
          305  +essentially clean\&. Of course, if parts of the dependencies listed
          306  +below are already installed the associated steps can be skipped\&. It is
          307  +still recommended to read their sections though, to validate that the
          308  +dependencies they talk about are indeed installed\&.
          309  +.SS TCL
          310  +As we are installing a number of Tcl packages and applications it
          311  +should be pretty much obvious that a working installation of Tcl
          312  +itself is needed, and I will not belabor the point\&.
          313  +.PP
          314  +Out of the many possibilities use whatever you are comfortable
          315  +with, as long as it provides at the very least Tcl 8\&.2, or higher\&.
          316  +This may be a Tcl installation provided by your operating system
          317  +distribution, from a distribution-independent vendor, or built by
          318  +yourself\&.
          319  +.PP
          320  +\fINote\fR that the packages in Tcllib have begun to require
          321  +8\&.4, 8\&.5, and even 8\&.6\&. Older versions of Tcl will not be able to use
          322  +such packages\&. Trying to use them will result in
          323  +\fIpackage not found\fR errors, as their package index files will
          324  +not register them in versions of the core unable to use them\&.
          325  +.PP
          326  +Myself, I used (and still use)
          327  +\fIActiveState's\fR [http://www\&.activestate\&.com]
          328  +ActiveTcl 8\&.5 distribution during development, as I am most familiar
          329  +with it\&.
          330  +.PP
          331  +\fI(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, maintaining ActiveTcl and TclDevKit for them)\&.\fR\&.
          332  +I am currently working for SUSE Software Canada ULC, although not in
          333  +Tcl-related areas\&.
          334  +.PP
          335  +This distribution can be found at
          336  +\fIhttp://www\&.activestate\&.com/activetcl\fR\&. Retrieve the archive of
          337  +ActiveTcl 8\&.5 (or higher) for your platform and install it as directed
          338  +by ActiveState\&.
          339  +.PP
          340  +For those wishing to build and install Tcl on their own, the
          341  +relevant sources can be found at
          342  +.TP
          343  +Tcl
          344  +\fIhttp://core\&.tcl-lang\&.org/tcl/\fR
          345  +.PP
          346  +together with the necessary instructions on how to build it\&.
          347  +.PP
          348  +If there are problems with building, installing, or using Tcl,
          349  +please file a ticket against \fITcl\fR, or the vendor of your
          350  +distribution, and \fInot\fR \fITcllib\fR\&.
          351  +.SS CRITCL
          352  +The \fBcritcl\fR tool is an \fIoptional\fR dependency\&.
          353  +.PP
          354  +It is only required when trying to build the C-based
          355  +\fIaccelerators\fR for a number of packages, as explained in
          356  +\fBCritcl & Accelerators\fR
          357  +.PP
          358  +Tcllib's build system looks for it in the ,
          359  +using the name \fBcritcl\fR\&. This is for Unix\&.
          360  +On Windows on the other hand the search is more complex\&. First we look
          361  +for a proper application \fBcritcl\&.exe\fR\&. When that is not found
          362  +we look for a combination of interpreter (\fBtclkitsh\&.exe\fR,
          363  +\fBtclsh\&.exe\fR) and starkit (\fBcritcl\&.kit\fR, \fBcritcl\fR)
          364  +instead\&. \fINote\fR that the choice of starkit can be overriden via
          365  +the environment variable \&.
          366  +.PP
          367  +Tcllib requires Critcl version 2 or higher\&.
          368  +.PP
          369  +The github repository providing releases of version 2 and
          370  +higher, and the associated sources, can be found at
          371  +\fIhttp://andreas-kupries\&.github\&.com/critcl\fR\&.
          372  +.PP
          373  +Any branch of the repository can be used (if not using the
          374  +prebuild starkit or starpack), although the use of the stable branch
          375  +\fImaster\fR is recommended\&.
          376  +.PP
          377  +At the above url is also an explanation on how to build and
          378  +install Critcl, including a list of its dependencies\&.
          379  +.PP
          380  +Its instructions will not be repeated here\&. If there are
          381  +problems with these directions please file a ticket against the
          382  +\fICritcl\fR project, and not Tcllib\&.
          383  +.SH "BUILD & INSTALLATION INSTRUCTIONS"
          384  +As Tcllib is mainly a bundle of packages written in pure Tcl building
          385  +it is the same as installing it\&. The exceptions to this have their own
          386  +subsection, \fBCritcl & Accelerators\fR, later on\&.
          387  +.PP
          388  +Before that however comes the standard case, differentiated by
          389  +the platforms with material differences in the instruction, i\&.e\&.
          390  +\fIUnix\fR-like, versus \fIWindows\fR\&.
          391  +.PP
          392  +Regarding the latter it should also be noted that it is
          393  +possible set up an \fIUnix\fR-like environment using projects
          394  +like \fIMSYS\fR, \fICygwin\fR, and others\&. In that case the
          395  +user has the choice of which instructions to follow\&.
          396  +.PP
          397  +Regardless of environment or platform, a suitable \fITcl\fR
          398  +has to be installed, and its \fBtclsh\fR should be placed on
          399  +the  (\fIUnix\fR) or associated with
          400  +"\fI\&.tcl\fR" files (\fIWindows\fR)\&.
          401  +.SS "INSTALLING ON UNIX"
          402  +For \fIUnix\fR-like environments Tcllib comes with the standard set
          403  +of files to make
          404  +.CS
          405  +
          406  +
          407  +  \&./configure
          408  +  make install
          409  +
          410  +.CE
          411  +a suitable way of installing it\&.
          412  +This is a standard non-interactive install automatically figuring out
          413  +where to place everything, i\&.e\&. packages, applications, and the
          414  +manpages\&.
          415  +.PP
          416  +To get a graphical installer invoke
          417  +.CS
          418  +
          419  +
          420  +  \&./installer\&.tcl
          421  +
          422  +.CE
          423  +instead\&.
          424  +.SS "INSTALLING ON WINDOWS"
          425  +In a Windows environment we have the \fBinstaller\&.tcl\fR script to
          426  +perform installation\&.
          427  +.PP
          428  +If the desired \fBtclsh\fR is associated "\fI\&.tcl\fR" files
          429  +then double-clicking / opening the \fBinstaller\&.tcl\fR is
          430  +enough to invoke it in graphical mode\&.
          431  +This assumes that \fITk\fR is installed and available as well\&.
          432  +.PP
          433  +Without \fITk\fR the only way to invoke the installer are to
          434  +open a DOS window, i\&.e\&. \fBcmd\&.exe\fR, and then to invoke
          435  +.CS
          436  +
          437  +
          438  +  \&./installer\&.tcl
          439  +
          440  +.CE
          441  +inside it\&.
          442  +.SS "CRITCL & ACCELERATORS"
          443  +While the majority of Tcllib consists of packages written in pure Tcl
          444  +a number of packages also have \fIaccelerators\fR associated with them\&.
          445  +These are \fBcritcl\fR-based C packages whose use will boost the
          446  +performance of the packages using them\&.
          447  +These accelerators are optional, and they are not installed by
          448  +default\&.
          449  +.PP
          450  +To build the accelerators the normally optional dependency on
          451  +\fBcritcl\fR becomes required\&.
          452  +.PP
          453  +To build and install Tcllib with the accelerators in a
          454  +Unix-like environment invoke:
          455  +.CS
          456  +
          457  +
          458  +  \&./configure
          459  +  make critcl # This builds the shared library holding
          460  +              # the accelerators
          461  +  make install
          462  +
          463  +.CE
          464  +.PP
          465  +The underlying tool is "\fIsak\&.tcl\fR" in the toplevel directory
          466  +of Tcllib and the command \fBmake critcl\fR is just a wrapper around
          467  +.CS
          468  +
          469  +
          470  +  \&./sak\&.tcl critcl
          471  +
          472  +.CE
          473  +.PP
          474  +Therefore in a Windows environment instead invoke
          475  +.CS
          476  +
          477  +
          478  +  \&./sak\&.tcl critcl
          479  +  \&./installer\&.tcl
          480  +
          481  +.CE
          482  +from within a DOS window, i\&.e\&. \fBcmd\&.exe\fR\&.
          483  +.SS TOOLING
          484  +The core of Tcllib's build system is the script "\fIinstaller\&.tcl\fR"
          485  +found in the toplevel directory of a checkout or release\&.
          486  +.PP
          487  +The
          488  +.CS
          489  +
          490  +
          491  +         configure ; make install
          492  +
          493  +.CE
          494  +setup available to
          495  +developers on Unix-like systems is just a wrapper around it\&.
          496  +To go beyond the standard embodied in the wrapper it is
          497  +necessary to directly invoke this script\&.
          498  +.PP
          499  +On Windows system using it directly is the only way to invoke
          500  +it\&.
          501  +.PP
          502  +For basic help invoke it as
          503  +.CS
          504  +
          505  +
          506  +         \&./installer\&.tcl -help
          507  +
          508  +.CE
          509  +This will print a short list of all the available options to
          510  +the standard output channel\&.
          511  +.PP
          512  +The commands associated with the various \fIinstall\fR targets
          513  +in the \fIMakefile\&.in\fR for Unix can be used as additional
          514  +examples on how to use this tool as well\&.
          515  +.PP
          516  +The installer can operate in GUI and CLI modes\&.
          517  +By default it chooses the mode automatically, based on if the
          518  +Tcl package \fBTk\fR can be used or not\&.
          519  +The option \fB-no-gui\fR can be used to force CLI mode\&.
          520  +.PP
          521  +Note that it is possible to specify options on the command line
          522  +even if the installer ultimatively selects GUI mode\&. In that
          523  +case the hardwired defaults and the options determine the data
          524  +presented to the user for editing\&.
          525  +.PP
          526  +The installer will select a number of defaults for the
          527  +locations of packages, examples, and documentation, and also
          528  +the format of the documentation\&. The user can overide these
          529  +defaults in the GUI, or by specifying additional options\&.
          530  +The defaults depend on the platform detected (Unix/Windows) and
          531  +on the \fBtclsh\fR executable used to run the installer\&.
          532  +.PP
          533  +\fIOptions\fR
          534  +.TP
          535  +\fB-help\fR
          536  +Show the list of options explained here on the standard output channel
          537  +and exit\&.
          538  +.TP
          539  +\fB+excluded\fR
          540  +Include deprecated packages in the installation\&.
          541  +.TP
          542  +\fB-no-gui\fR
          543  +Force command line operation of the installer
          544  +.TP
          545  +\fB-no-wait\fR
          546  +In CLI mode the installer will by default ask the user to confirm that
          547  +the chosen configuration (destination paths, things to install) is
          548  +correct before performing any action\&. Using this option causes the
          549  +installer to skip this query and immediately jump to installation\&.
          550  +.TP
          551  +\fB-app-path\fR \fIpath\fR
          552  +.TP
          553  +\fB-example-path\fR \fIpath\fR
          554  +.TP
          555  +\fB-html-path\fR \fIpath\fR
          556  +.TP
          557  +\fB-nroff-path\fR \fIpath\fR
          558  +.TP
          559  +\fB-pkg-path\fR \fIpath\fR
          560  +Declare the destination paths for the applications, examples, html
          561  +documentation, nroff manpages, and packages\&. The defaults are derived
          562  +from the location of the \fBtclsh\fR used to run the installer\&.
          563  +.TP
          564  +\fB-dry-run\fR
          565  +.TP
          566  +\fB-simulate\fR
          567  +Run the installer without modifying the destination directories\&.
          568  +.TP
          569  +\fB-apps\fR
          570  +.TP
          571  +\fB-no-apps\fR
          572  +.TP
          573  +\fB-examples\fR
          574  +.TP
          575  +\fB-no-examples\fR
          576  +.TP
          577  +\fB-pkgs\fR
          578  +.TP
          579  +\fB-no-pkgs\fR
          580  +.TP
          581  +\fB-html\fR
          582  +.TP
          583  +\fB-no-html\fR
          584  +.TP
          585  +\fB-nroff\fR
          586  +.TP
          587  +\fB-no-nroff\fR
          588  +(De)activate the installation of applications, examples, packages,
          589  +html documentation, and nroff manpages\&.
          590  +.sp
          591  +Applications, examples, and packages are installed by default\&.
          592  +.sp
          593  +On Windows the html documentation is installed by default\&.
          594  +.sp
          595  +On Unix the nroff manpages are installed by default\&.
          596  +.PP

Added idoc/man/files/devdoc/tcllib_license.n.

            1  +'\"
            2  +'\" Generated from file 'tcllib_license\&.man' by tcllib/doctools with format 'nroff'
            3  +'\"
            4  +.TH "tcllib_license" n 1 tcllib ""
            5  +.\" The -*- nroff -*- definitions below are for supplemental macros used
            6  +.\" in Tcl/Tk manual entries.
            7  +.\"
            8  +.\" .AP type name in/out ?indent?
            9  +.\"	Start paragraph describing an argument to a library procedure.
           10  +.\"	type is type of argument (int, etc.), in/out is either "in", "out",
           11  +.\"	or "in/out" to describe whether procedure reads or modifies arg,
           12  +.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
           13  +.\"	needed;  use .AS below instead)
           14  +.\"
           15  +.\" .AS ?type? ?name?
           16  +.\"	Give maximum sizes of arguments for setting tab stops.  Type and
           17  +.\"	name are examples of largest possible arguments that will be passed
           18  +.\"	to .AP later.  If args are omitted, default tab stops are used.
           19  +.\"
           20  +.\" .BS
           21  +.\"	Start box enclosure.  From here until next .BE, everything will be
           22  +.\"	enclosed in one large box.
           23  +.\"
           24  +.\" .BE
           25  +.\"	End of box enclosure.
           26  +.\"
           27  +.\" .CS
           28  +.\"	Begin code excerpt.
           29  +.\"
           30  +.\" .CE
           31  +.\"	End code excerpt.
           32  +.\"
           33  +.\" .VS ?version? ?br?
           34  +.\"	Begin vertical sidebar, for use in marking newly-changed parts
           35  +.\"	of man pages.  The first argument is ignored and used for recording
           36  +.\"	the version when the .VS was added, so that the sidebars can be
           37  +.\"	found and removed when they reach a certain age.  If another argument
           38  +.\"	is present, then a line break is forced before starting the sidebar.
           39  +.\"
           40  +.\" .VE
           41  +.\"	End of vertical sidebar.
           42  +.\"
           43  +.\" .DS
           44  +.\"	Begin an indented unfilled display.
           45  +.\"
           46  +.\" .DE
           47  +.\"	End of indented unfilled display.
           48  +.\"
           49  +.\" .SO ?manpage?
           50  +.\"	Start of list of standard options for a Tk widget. The manpage
           51  +.\"	argument defines where to look up the standard options; if
           52  +.\"	omitted, defaults to "options". The options follow on successive
           53  +.\"	lines, in three columns separated by tabs.
           54  +.\"
           55  +.\" .SE
           56  +.\"	End of list of standard options for a Tk widget.
           57  +.\"
           58  +.\" .OP cmdName dbName dbClass
           59  +.\"	Start of description of a specific option.  cmdName gives the
           60  +.\"	option's name as specified in the class command, dbName gives
           61  +.\"	the option's name in the option database, and dbClass gives
           62  +.\"	the option's class in the option database.
           63  +.\"
           64  +.\" .UL arg1 arg2
           65  +.\"	Print arg1 underlined, then print arg2 normally.
           66  +.\"
           67  +.\" .QW arg1 ?arg2?
           68  +.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
           69  +.\"
           70  +.\" .PQ arg1 ?arg2?
           71  +.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
           72  +.\"	(for trailing punctuation) and then a closing parenthesis.
           73  +.\"
           74  +.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
           75  +.if t .wh -1.3i ^B
           76  +.nr ^l \n(.l
           77  +.ad b
           78  +.\"	# Start an argument description
           79  +.de AP
           80  +.ie !"\\$4"" .TP \\$4
           81  +.el \{\
           82  +.   ie !"\\$2"" .TP \\n()Cu
           83  +.   el          .TP 15
           84  +.\}
           85  +.ta \\n()Au \\n()Bu
           86  +.ie !"\\$3"" \{\
           87  +\&\\$1 \\fI\\$2\\fP (\\$3)
           88  +.\".b
           89  +.\}
           90  +.el \{\
           91  +.br
           92  +.ie !"\\$2"" \{\
           93  +\&\\$1	\\fI\\$2\\fP
           94  +.\}
           95  +.el \{\
           96  +\&\\fI\\$1\\fP
           97  +.\}
           98  +.\}
           99  +..
          100  +.\"	# define tabbing values for .AP
          101  +.de AS
          102  +.nr )A 10n
          103  +.if !"\\$1"" .nr )A \\w'\\$1'u+3n
          104  +.nr )B \\n()Au+15n
          105  +.\"
          106  +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
          107  +.nr )C \\n()Bu+\\w'(in/out)'u+2n
          108  +..
          109  +.AS Tcl_Interp Tcl_CreateInterp in/out
          110  +.\"	# BS - start boxed text
          111  +.\"	# ^y = starting y location
          112  +.\"	# ^b = 1
          113  +.de BS
          114  +.br
          115  +.mk ^y
          116  +.nr ^b 1u
          117  +.if n .nf
          118  +.if n .ti 0
          119  +.if n \l'\\n(.lu\(ul'
          120  +.if n .fi
          121  +..
          122  +.\"	# BE - end boxed text (draw box now)
          123  +.de BE
          124  +.nf
          125  +.ti 0
          126  +.mk ^t
          127  +.ie n \l'\\n(^lu\(ul'
          128  +.el \{\
          129  +.\"	Draw four-sided box normally, but don't draw top of
          130  +.\"	box if the box started on an earlier page.
          131  +.ie !\\n(^b-1 \{\
          132  +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          133  +.\}
          134  +.el \}\
          135  +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          136  +.\}
          137  +.\}
          138  +.fi
          139  +.br
          140  +.nr ^b 0
          141  +..
          142  +.\"	# VS - start vertical sidebar
          143  +.\"	# ^Y = starting y location
          144  +.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
          145  +.de VS
          146  +.if !"\\$2"" .br
          147  +.mk ^Y
          148  +.ie n 'mc \s12\(br\s0
          149  +.el .nr ^v 1u
          150  +..
          151  +.\"	# VE - end of vertical sidebar
          152  +.de VE
          153  +.ie n 'mc
          154  +.el \{\
          155  +.ev 2
          156  +.nf
          157  +.ti 0
          158  +.mk ^t
          159  +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
          160  +.sp -1
          161  +.fi
          162  +.ev
          163  +.\}
          164  +.nr ^v 0
          165  +..
          166  +.\"	# Special macro to handle page bottom:  finish off current
          167  +.\"	# box/sidebar if in box/sidebar mode, then invoked standard
          168  +.\"	# page bottom macro.
          169  +.de ^B
          170  +.ev 2
          171  +'ti 0
          172  +'nf
          173  +.mk ^t
          174  +.if \\n(^b \{\
          175  +.\"	Draw three-sided box if this is the box's first page,
          176  +.\"	draw two sides but no top otherwise.
          177  +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          178  +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          179  +.\}
          180  +.if \\n(^v \{\
          181  +.nr ^x \\n(^tu+1v-\\n(^Yu
          182  +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
          183  +.\}
          184  +.bp
          185  +'fi
          186  +.ev
          187  +.if \\n(^b \{\
          188  +.mk ^y
          189  +.nr ^b 2
          190  +.\}
          191  +.if \\n(^v \{\
          192  +.mk ^Y
          193  +.\}
          194  +..
          195  +.\"	# DS - begin display
          196  +.de DS
          197  +.RS
          198  +.nf
          199  +.sp
          200  +..
          201  +.\"	# DE - end display
          202  +.de DE
          203  +.fi
          204  +.RE
          205  +.sp
          206  +..
          207  +.\"	# SO - start of list of standard options
          208  +.de SO
          209  +'ie '\\$1'' .ds So \\fBoptions\\fR
          210  +'el .ds So \\fB\\$1\\fR
          211  +.SH "STANDARD OPTIONS"
          212  +.LP
          213  +.nf
          214  +.ta 5.5c 11c
          215  +.ft B
          216  +..
          217  +.\"	# SE - end of list of standard options
          218  +.de SE
          219  +.fi
          220  +.ft R
          221  +.LP
          222  +See the \\*(So manual entry for details on the standard options.
          223  +..
          224  +.\"	# OP - start of full description for a single option
          225  +.de OP
          226  +.LP
          227  +.nf
          228  +.ta 4c
          229  +Command-Line Name:	\\fB\\$1\\fR
          230  +Database Name:	\\fB\\$2\\fR
          231  +Database Class:	\\fB\\$3\\fR
          232  +.fi
          233  +.IP
          234  +..
          235  +.\"	# CS - begin code excerpt
          236  +.de CS
          237  +.RS
          238  +.nf
          239  +.ta .25i .5i .75i 1i
          240  +..
          241  +.\"	# CE - end code excerpt
          242  +.de CE
          243  +.fi
          244  +.RE
          245  +..
          246  +.\"	# UL - underline word
          247  +.de UL
          248  +\\$1\l'|0\(ul'\\$2
          249  +..
          250  +.\"	# QW - apply quotation marks to word
          251  +.de QW
          252  +.ie '\\*(lq'"' ``\\$1''\\$2
          253  +.\"" fix emacs highlighting
          254  +.el \\*(lq\\$1\\*(rq\\$2
          255  +..
          256  +.\"	# PQ - apply parens and quotation marks to word
          257  +.de PQ
          258  +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
          259  +.\"" fix emacs highlighting
          260  +.el (\\*(lq\\$1\\*(rq\\$2)\\$3
          261  +..
          262  +.\"	# QR - quoted range
          263  +.de QR
          264  +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
          265  +.\"" fix emacs highlighting
          266  +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
          267  +..
          268  +.\"	# MT - "empty" string
          269  +.de MT
          270  +.QW ""
          271  +..
          272  +.BS
          273  +.SH NAME
          274  +tcllib_license \- Tcllib - License
          275  +.SH DESCRIPTION
          276  +Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a
          277  +package itself\&. It is a collection of (semi-independent) \fITcl\fR
          278  +packages that provide utility functions useful to a large collection
          279  +of Tcl programmers\&.
          280  +.PP
          281  +The collection is under the BSD license\&.
          282  +.SH LICENSE
          283  +.PP
          284  +This software is copyrighted by Ajuba Solutions and other parties\&.
          285  +The following terms apply to all files associated with the software
          286  +unless explicitly disclaimed in individual files\&.
          287  +.PP
          288  +The authors hereby grant permission to use, copy, modify, distribute,
          289  +and license this software and its documentation for any purpose,
          290  +provided that existing copyright notices are retained in all copies
          291  +and that this notice is included verbatim in any distributions\&. No
          292  +written agreement, license, or royalty fee is required for any of the
          293  +authorized uses\&.  Modifications to this software may be copyrighted by
          294  +their authors and need not follow the licensing terms described here,
          295  +provided that the new terms are clearly indicated on the first page of
          296  +each file where they apply\&.
          297  +.PP
          298  +IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
          299  +FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
          300  +ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
          301  +DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
          302  +POSSIBILITY OF SUCH DAMAGE\&.
          303  +.PP
          304  +THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
          305  +INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
          306  +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
          307  +NON-INFRINGEMENT\&.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
          308  +THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
          309  +MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS\&.
          310  +.PP
          311  +GOVERNMENT USE: If you are acquiring this software on behalf of the
          312  +U\&.S\&. government, the Government shall have only "Restricted Rights" in
          313  +the software and related documentation as defined in the Federal
          314  +Acquisition Regulations (FARs) in Clause 52\&.227\&.19 (c) (2)\&.  If you
          315  +are acquiring the software on behalf of the Department of Defense, the
          316  +software shall be classified as "Commercial Computer Software" and the
          317  +Government shall have only "Restricted Rights" as defined in Clause
          318  +252\&.227-7013 (c) (1) of DFARs\&.  Notwithstanding the foregoing, the
          319  +authors grant the U\&.S\&. Government and others acting in its behalf
          320  +permission to use and distribute the software in accordance with the
          321  +terms specified in this license\&.

Added idoc/man/files/devdoc/tcllib_releasemgr.n.

            1  +'\"
            2  +'\" Generated from file 'tcllib_releasemgr\&.man' by tcllib/doctools with format 'nroff'
            3  +'\"
            4  +.TH "tcllib_releasemgr" n 1 tcllib ""
            5  +.\" The -*- nroff -*- definitions below are for supplemental macros used
            6  +.\" in Tcl/Tk manual entries.
            7  +.\"
            8  +.\" .AP type name in/out ?indent?
            9  +.\"	Start paragraph describing an argument to a library procedure.
           10  +.\"	type is type of argument (int, etc.), in/out is either "in", "out",
           11  +.\"	or "in/out" to describe whether procedure reads or modifies arg,
           12  +.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
           13  +.\"	needed;  use .AS below instead)
           14  +.\"
           15  +.\" .AS ?type? ?name?
           16  +.\"	Give maximum sizes of arguments for setting tab stops.  Type and
           17  +.\"	name are examples of largest possible arguments that will be passed
           18  +.\"	to .AP later.  If args are omitted, default tab stops are used.
           19  +.\"
           20  +.\" .BS
           21  +.\"	Start box enclosure.  From here until next .BE, everything will be
           22  +.\"	enclosed in one large box.
           23  +.\"
           24  +.\" .BE
           25  +.\"	End of box enclosure.
           26  +.\"
           27  +.\" .CS
           28  +.\"	Begin code excerpt.
           29  +.\"
           30  +.\" .CE
           31  +.\"	End code excerpt.
           32  +.\"
           33  +.\" .VS ?version? ?br?
           34  +.\"	Begin vertical sidebar, for use in marking newly-changed parts
           35  +.\"	of man pages.  The first argument is ignored and used for recording
           36  +.\"	the version when the .VS was added, so that the sidebars can be
           37  +.\"	found and removed when they reach a certain age.  If another argument
           38  +.\"	is present, then a line break is forced before starting the sidebar.
           39  +.\"
           40  +.\" .VE
           41  +.\"	End of vertical sidebar.
           42  +.\"
           43  +.\" .DS
           44  +.\"	Begin an indented unfilled display.
           45  +.\"
           46  +.\" .DE
           47  +.\"	End of indented unfilled display.
           48  +.\"
           49  +.\" .SO ?manpage?
           50  +.\"	Start of list of standard options for a Tk widget. The manpage
           51  +.\"	argument defines where to look up the standard options; if
           52  +.\"	omitted, defaults to "options". The options follow on successive
           53  +.\"	lines, in three columns separated by tabs.
           54  +.\"
           55  +.\" .SE
           56  +.\"	End of list of standard options for a Tk widget.
           57  +.\"
           58  +.\" .OP cmdName dbName dbClass
           59  +.\"	Start of description of a specific option.  cmdName gives the
           60  +.\"	option's name as specified in the class command, dbName gives
           61  +.\"	the option's name in the option database, and dbClass gives
           62  +.\"	the option's class in the option database.
           63  +.\"
           64  +.\" .UL arg1 arg2
           65  +.\"	Print arg1 underlined, then print arg2 normally.
           66  +.\"
           67  +.\" .QW arg1 ?arg2?
           68  +.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
           69  +.\"
           70  +.\" .PQ arg1 ?arg2?
           71  +.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
           72  +.\"	(for trailing punctuation) and then a closing parenthesis.
           73  +.\"
           74  +.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
           75  +.if t .wh -1.3i ^B
           76  +.nr ^l \n(.l
           77  +.ad b
           78  +.\"	# Start an argument description
           79  +.de AP
           80  +.ie !"\\$4"" .TP \\$4
           81  +.el \{\
           82  +.   ie !"\\$2"" .TP \\n()Cu
           83  +.   el          .TP 15
           84  +.\}
           85  +.ta \\n()Au \\n()Bu
           86  +.ie !"\\$3"" \{\
           87  +\&\\$1 \\fI\\$2\\fP (\\$3)
           88  +.\".b
           89  +.\}
           90  +.el \{\
           91  +.br
           92  +.ie !"\\$2"" \{\
           93  +\&\\$1	\\fI\\$2\\fP
           94  +.\}
           95  +.el \{\
           96  +\&\\fI\\$1\\fP
           97  +.\}
           98  +.\}
           99  +..
          100  +.\"	# define tabbing values for .AP
          101  +.de AS
          102  +.nr )A 10n
          103  +.if !"\\$1"" .nr )A \\w'\\$1'u+3n
          104  +.nr )B \\n()Au+15n
          105  +.\"
          106  +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
          107  +.nr )C \\n()Bu+\\w'(in/out)'u+2n
          108  +..
          109  +.AS Tcl_Interp Tcl_CreateInterp in/out
          110  +.\"	# BS - start boxed text
          111  +.\"	# ^y = starting y location
          112  +.\"	# ^b = 1
          113  +.de BS
          114  +.br
          115  +.mk ^y
          116  +.nr ^b 1u
          117  +.if n .nf
          118  +.if n .ti 0
          119  +.if n \l'\\n(.lu\(ul'
          120  +.if n .fi
          121  +..
          122  +.\"	# BE - end boxed text (draw box now)
          123  +.de BE
          124  +.nf
          125  +.ti 0
          126  +.mk ^t
          127  +.ie n \l'\\n(^lu\(ul'
          128  +.el \{\
          129  +.\"	Draw four-sided box normally, but don't draw top of
          130  +.\"	box if the box started on an earlier page.
          131  +.ie !\\n(^b-1 \{\
          132  +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          133  +.\}
          134  +.el \}\
          135  +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          136  +.\}
          137  +.\}
          138  +.fi
          139  +.br
          140  +.nr ^b 0
          141  +..
          142  +.\"	# VS - start vertical sidebar
          143  +.\"	# ^Y = starting y location
          144  +.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
          145  +.de VS
          146  +.if !"\\$2"" .br
          147  +.mk ^Y
          148  +.ie n 'mc \s12\(br\s0
          149  +.el .nr ^v 1u
          150  +..
          151  +.\"	# VE - end of vertical sidebar
          152  +.de VE
          153  +.ie n 'mc
          154  +.el \{\
          155  +.ev 2
          156  +.nf
          157  +.ti 0
          158  +.mk ^t
          159  +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
          160  +.sp -1
          161  +.fi
          162  +.ev
          163  +.\}
          164  +.nr ^v 0
          165  +..
          166  +.\"	# Special macro to handle page bottom:  finish off current
          167  +.\"	# box/sidebar if in box/sidebar mode, then invoked standard
          168  +.\"	# page bottom macro.
          169  +.de ^B
          170  +.ev 2
          171  +'ti 0
          172  +'nf
          173  +.mk ^t
          174  +.if \\n(^b \{\
          175  +.\"	Draw three-sided box if this is the box's first page,
          176  +.\"	draw two sides but no top otherwise.
          177  +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          178  +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          179  +.\}
          180  +.if \\n(^v \{\
          181  +.nr ^x \\n(^tu+1v-\\n(^Yu
          182  +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
          183  +.\}
          184  +.bp
          185  +'fi
          186  +.ev
          187  +.if \\n(^b \{\
          188  +.mk ^y
          189  +.nr ^b 2
          190  +.\}
          191  +.if \\n(^v \{\
          192  +.mk ^Y
          193  +.\}
          194  +..
          195  +.\"	# DS - begin display
          196  +.de DS
          197  +.RS
          198  +.nf
          199  +.sp
          200  +..
          201  +.\"	# DE - end display
          202  +.de DE
          203  +.fi
          204  +.RE
          205  +.sp
          206  +..
          207  +.\"	# SO - start of list of standard options
          208  +.de SO
          209  +'ie '\\$1'' .ds So \\fBoptions\\fR
          210  +'el .ds So \\fB\\$1\\fR
          211  +.SH "STANDARD OPTIONS"
          212  +.LP
          213  +.nf
          214  +.ta 5.5c 11c
          215  +.ft B
          216  +..
          217  +.\"	# SE - end of list of standard options
          218  +.de SE
          219  +.fi
          220  +.ft R
          221  +.LP
          222  +See the \\*(So manual entry for details on the standard options.
          223  +..
          224  +.\"	# OP - start of full description for a single option
          225  +.de OP
          226  +.LP
          227  +.nf
          228  +.ta 4c
          229  +Command-Line Name:	\\fB\\$1\\fR
          230  +Database Name:	\\fB\\$2\\fR
          231  +Database Class:	\\fB\\$3\\fR
          232  +.fi
          233  +.IP
          234  +..
          235  +.\"	# CS - begin code excerpt
          236  +.de CS
          237  +.RS
          238  +.nf
          239  +.ta .25i .5i .75i 1i
          240  +..
          241  +.\"	# CE - end code excerpt
          242  +.de CE
          243  +.fi
          244  +.RE
          245  +..
          246  +.\"	# UL - underline word
          247  +.de UL
          248  +\\$1\l'|0\(ul'\\$2
          249  +..
          250  +.\"	# QW - apply quotation marks to word
          251  +.de QW
          252  +.ie '\\*(lq'"' ``\\$1''\\$2
          253  +.\"" fix emacs highlighting
          254  +.el \\*(lq\\$1\\*(rq\\$2
          255  +..
          256  +.\"	# PQ - apply parens and quotation marks to word
          257  +.de PQ
          258  +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
          259  +.\"" fix emacs highlighting
          260  +.el (\\*(lq\\$1\\*(rq\\$2)\\$3
          261  +..
          262  +.\"	# QR - quoted range
          263  +.de QR
          264  +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
          265  +.\"" fix emacs highlighting
          266  +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
          267  +..
          268  +.\"	# MT - "empty" string
          269  +.de MT
          270  +.QW ""
          271  +..
          272  +.BS
          273  +.SH NAME
          274  +tcllib_releasemgr \- Tcllib - The Release Manager's Guide
          275  +.SH DESCRIPTION
          276  +Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a
          277  +package itself\&. It is a collection of (semi-independent) \fITcl\fR
          278  +packages that provide utility functions useful to a large collection
          279  +of Tcl programmers\&.
          280  +.PP
          281  +The audience of this document is the release manager for Tcllib, their
          282  +deputies, and anybody else interested in the task of creating
          283  +an official release of Tcllib for distribution\&.
          284  +.PP
          285  +Please read \fITcllib - How To Get The Sources\fR first, if that
          286  +was not done already\&. Here we assume that the sources are already
          287  +available in a directory of your choice\&.
          288  +.PP
          289  +.SH TOOLS
          290  +The "\fIsak\&.tcl\fR" script in the toplevel directory of a Tcllib
          291  +checkout is the one tool used by the release manager to perform its
          292  +\fBTasks\fR\&.
          293  +.PP
          294  +The main commands to be used are
          295  +.CS
          296  +
          297  +
          298  +    sak\&.tcl validate
          299  +    sak\&.tcl test run
          300  +    sak\&.tcl review
          301  +    sak\&.tcl readme
          302  +    sak\&.tcl localdoc
          303  +    sak\&.tcl release
          304  +
          305  +.CE
          306  +More detail will be provided in the explanations of the various
          307  +\fBTasks\fR\&.
          308  +.SH TASKS
          309  +.SS "START A RELEASE CANDIDATE"
          310  +todo: open a candidate for release
          311  +.SS "READY THE CANDIDATE"
          312  +todo: test, validate and check that the candidate is worthy of release
          313  +fix testsuites, possibly fix packages, documentation
          314  +regenerate docs
          315  +coordinate with package maintainers wrt fixes
          316  +big thing: going over the packages, classify changes since last
          317  +release to generate a nice readme\&.
          318  +.SS "MAKE IT OFFICIAL"
          319  +todo: finalize release, make candidate official
          320  +.SS "DISTRIBUTE THE RELEASE"
          321  +With the release made it has to be published and the world notified of
          322  +its existence\&.
          323  +.IP [1]
          324  +Create a proper fossil event for the release, via
          325  +\fIhttp://core\&.tcl-lang\&.org/tcllib/eventedit\fR\&.
          326  +.sp
          327  +An \fIexisting event\fR [http://core\&.tcl-lang\&.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817] should be used as template\&.
          328  +.IP [2]
          329  +Update a number of web locations:
          330  +.RS
          331  +.IP [1]
          332  +\fIHome page\fR [http://core\&.tcl-lang\&.org/tcllib/doc/trunk/embedded/index\&.md]
          333  +.IP [2]
          334  +\fIDownloads\fR [http://core\&.tcl-lang\&.org/tcllib/wiki?name=Downloads]
          335  +.IP [3]
          336  +\fIPast Releases\fR [http://core\&.tcl-lang\&.org/tcllib/wiki?name=Past+Releases]
          337  +.IP [4]
          338  +\fIhttp://www\&.tcl-lang\&.org/home/release\&.txt\fR
          339  +.IP [5]
          340  +\fIhttp://www\&.tcl-lang\&.org/software/tcllib/*\&.tml\fR
          341  +.IP [6]
          342  +\fIhttp://wiki\&.tcl-lang\&.org/page/Tcllib\fR
          343  +.RE
          344  +.IP
          345  +The first location maps to the file "\fIembedded/index\&.md\fR" in the
          346  +repository itself, as such it can edited as part of the release
          347  +process\&. This is where reference to the new fossil event is added, as
          348  +the new current release\&.
          349  +.sp
          350  +The next two locations are in the fossil tcllib wiki and
          351  +require admin or wiki write permissions for
          352  +\fIhttp://core\&.tcl-lang\&.org/tcllib\fR\&.
          353  +.sp
          354  +The last two locations require ssh access to
          355  +\fIhttp://www\&.tcl-lang\&.org\fR and permission to edit
          356  +files in the web area\&.
          357  +.IP [3]
          358  +***TODO*** mailing lists and other places to send notes to\&.
          359  +.PP

Added idoc/man/files/devdoc/tcllib_sources.n.

            1  +'\"
            2  +'\" Generated from file 'tcllib_sources\&.man' by tcllib/doctools with format 'nroff'
            3  +'\"
            4  +.TH "tcllib_sources" n 1 tcllib ""
            5  +.\" The -*- nroff -*- definitions below are for supplemental macros used
            6  +.\" in Tcl/Tk manual entries.
            7  +.\"
            8  +.\" .AP type name in/out ?indent?
            9  +.\"	Start paragraph describing an argument to a library procedure.
           10  +.\"	type is type of argument (int, etc.), in/out is either "in", "out",
           11  +.\"	or "in/out" to describe whether procedure reads or modifies arg,
           12  +.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
           13  +.\"	needed;  use .AS below instead)
           14  +.\"
           15  +.\" .AS ?type? ?name?
           16  +.\"	Give maximum sizes of arguments for setting tab stops.  Type and
           17  +.\"	name are examples of largest possible arguments that will be passed
           18  +.\"	to .AP later.  If args are omitted, default tab stops are used.
           19  +.\"
           20  +.\" .BS
           21  +.\"	Start box enclosure.  From here until next .BE, everything will be
           22  +.\"	enclosed in one large box.
           23  +.\"
           24  +.\" .BE
           25  +.\"	End of box enclosure.
           26  +.\"
           27  +.\" .CS
           28  +.\"	Begin code excerpt.
           29  +.\"
           30  +.\" .CE
           31  +.\"	End code excerpt.
           32  +.\"
           33  +.\" .VS ?version? ?br?
           34  +.\"	Begin vertical sidebar, for use in marking newly-changed parts
           35  +.\"	of man pages.  The first argument is ignored and used for recording
           36  +.\"	the version when the .VS was added, so that the sidebars can be
           37  +.\"	found and removed when they reach a certain age.  If another argument
           38  +.\"	is present, then a line break is forced before starting the sidebar.
           39  +.\"
           40  +.\" .VE
           41  +.\"	End of vertical sidebar.
           42  +.\"
           43  +.\" .DS
           44  +.\"	Begin an indented unfilled display.
           45  +.\"
           46  +.\" .DE
           47  +.\"	End of indented unfilled display.
           48  +.\"
           49  +.\" .SO ?manpage?
           50  +.\"	Start of list of standard options for a Tk widget. The manpage
           51  +.\"	argument defines where to look up the standard options; if
           52  +.\"	omitted, defaults to "options". The options follow on successive
           53  +.\"	lines, in three columns separated by tabs.
           54  +.\"
           55  +.\" .SE
           56  +.\"	End of list of standard options for a Tk widget.
           57  +.\"
           58  +.\" .OP cmdName dbName dbClass
           59  +.\"	Start of description of a specific option.  cmdName gives the
           60  +.\"	option's name as specified in the class command, dbName gives
           61  +.\"	the option's name in the option database, and dbClass gives
           62  +.\"	the option's class in the option database.
           63  +.\"
           64  +.\" .UL arg1 arg2
           65  +.\"	Print arg1 underlined, then print arg2 normally.
           66  +.\"
           67  +.\" .QW arg1 ?arg2?
           68  +.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
           69  +.\"
           70  +.\" .PQ arg1 ?arg2?
           71  +.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
           72  +.\"	(for trailing punctuation) and then a closing parenthesis.
           73  +.\"
           74  +.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
           75  +.if t .wh -1.3i ^B
           76  +.nr ^l \n(.l
           77  +.ad b
           78  +.\"	# Start an argument description
           79  +.de AP
           80  +.ie !"\\$4"" .TP \\$4
           81  +.el \{\
           82  +.   ie !"\\$2"" .TP \\n()Cu
           83  +.   el          .TP 15
           84  +.\}
           85  +.ta \\n()Au \\n()Bu
           86  +.ie !"\\$3"" \{\
           87  +\&\\$1 \\fI\\$2\\fP (\\$3)
           88  +.\".b
           89  +.\}
           90  +.el \{\
           91  +.br
           92  +.ie !"\\$2"" \{\
           93  +\&\\$1	\\fI\\$2\\fP
           94  +.\}
           95  +.el \{\
           96  +\&\\fI\\$1\\fP
           97  +.\}
           98  +.\}
           99  +..
          100  +.\"	# define tabbing values for .AP
          101  +.de AS
          102  +.nr )A 10n
          103  +.if !"\\$1"" .nr )A \\w'\\$1'u+3n
          104  +.nr )B \\n()Au+15n
          105  +.\"
          106  +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
          107  +.nr )C \\n()Bu+\\w'(in/out)'u+2n
          108  +..
          109  +.AS Tcl_Interp Tcl_CreateInterp in/out
          110  +.\"	# BS - start boxed text
          111  +.\"	# ^y = starting y location
          112  +.\"	# ^b = 1
          113  +.de BS
          114  +.br
          115  +.mk ^y
          116  +.nr ^b 1u
          117  +.if n .nf
          118  +.if n .ti 0
          119  +.if n \l'\\n(.lu\(ul'
          120  +.if n .fi
          121  +..
          122  +.\"	# BE - end boxed text (draw box now)
          123  +.de BE
          124  +.nf
          125  +.ti 0
          126  +.mk ^t
          127  +.ie n \l'\\n(^lu\(ul'
          128  +.el \{\
          129  +.\"	Draw four-sided box normally, but don't draw top of
          130  +.\"	box if the box started on an earlier page.
          131  +.ie !\\n(^b-1 \{\
          132  +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          133  +.\}
          134  +.el \}\
          135  +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
          136  +.\}
          137  +.\}
          138  +.fi
          139  +.br
          140  +.nr ^b 0
          141  +..
          142  +.\"	# VS - start vertical sidebar
          143  +.\"	# ^Y = starting y location
          144  +.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
          145  +.de VS
          146  +.if !"\\$2"" .br
          147  +.mk ^Y
          148  +.ie n 'mc \s12\(br\s0
          149  +.el .nr ^v 1u
          150  +..
          151  +.\"	# VE - end of vertical sidebar
          152  +.de VE
          153  +.ie n 'mc
          154  +.el \{\
          155  +.ev 2
          156  +.nf
          157  +.ti 0
          158  +.mk ^t
          159  +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
          160  +.sp -1
          161  +.fi
          162  +.ev
          163  +.\}
          164  +.nr ^v 0
          165  +..
          166  +.\"	# Special macro to handle page bottom:  finish off current
          167  +.\"	# box/sidebar if in box/sidebar mode, then invoked standard
          168  +.\"	# page bottom macro.
          169  +.de ^B
          170  +.ev 2
          171  +'ti 0
          172  +'nf
          173  +.mk ^t
          174  +.if \\n(^b \{\
          175  +.\"	Draw three-sided box if this is the box's first page,
          176  +.\"	draw two sides but no top otherwise.
          177  +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          178  +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
          179  +.\}
          180  +.if \\n(^v \{\
          181  +.nr ^x \\n(^tu+1v-\\n(^Yu
          182  +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
          183  +.\}
          184  +.bp
          185  +'fi
          186  +.ev
          187  +.if \\n(^b \{\
          188  +.mk ^y
          189  +.nr ^b 2
          190  +.\}
          191  +.if \\n(^v \{\
          192  +.mk ^Y
          193  +.\}
          194  +..
          195  +.\"	# DS - begin display
          196  +.de DS
          197  +.RS
          198  +.nf
          199  +.sp
          200  +..
          201  +.\"	# DE - end display
          202  +.de DE
          203  +.fi
          204  +.RE
          205  +.sp
          206  +..
          207  +.\"	# SO - start of list of standard options
          208  +.de SO
          209  +'ie '\\$1'' .ds So \\fBoptions\\fR
          210  +'el .ds So \\fB\\$1\\fR
          211  +.SH "STANDARD OPTIONS"
          212  +.LP
          213  +.nf
          214  +.ta 5.5c 11c
          215  +.ft B
          216  +..
          217  +.\"	# SE - end of list of standard options
          218  +.de SE
          219  +.fi
          220  +.ft R
          221  +.LP
          222  +See the \\*(So manual entry for details on the standard options.
          223  +..
          224  +.\"	# OP - start of full description for a single option
          225  +.de OP
          226  +.LP
          227  +.nf
          228  +.ta 4c
          229  +Command-Line Name:	\\fB\\$1\\fR
          230  +Database Name:	\\fB\\$2\\fR
          231  +Database Class:	\\fB\\$3\\fR
          232  +.fi
          233  +.IP
          234  +..
          235  +.\"	# CS - begin code excerpt
          236  +.de CS
          237  +.RS
          238  +.nf
          239  +.ta .25i .5i .75i 1i
          240  +..
          241  +.\"	# CE - end code excerpt
          242  +.de CE
          243  +.fi
          244  +.RE
          245  +..
          246  +.\"	# UL - underline word
          247  +.de UL
          248  +\\$1\l'|0\(ul'\\$2
          249  +..
          250  +.\"	# QW - apply quotation marks to word
          251  +.de QW
          252  +.ie '\\*(lq'"' ``\\$1''\\$2
          253  +.\"" fix emacs highlighting
          254  +.el \\*(lq\\$1\\*(rq\\$2
          255  +..
          256  +.\"	# PQ - apply parens and quotation marks to word
          257  +.de PQ
          258  +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
          259  +.\"" fix emacs highlighting
          260  +.el (\\*(lq\\$1\\*(rq\\$2)\\$3
          261  +..
          262  +.\"	# QR - quoted range
          263  +.de QR
          264  +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
          265  +.\"" fix emacs highlighting
          266  +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
          267  +..
          268  +.\"	# MT - "empty" string
          269  +.de MT
          270  +.QW ""
          271  +..
          272  +.BS
          273  +.SH NAME
          274  +tcllib_sources \- Tcllib - How To Get The Sources
          275  +.SH DESCRIPTION
          276  +Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a
          277  +package itself\&. It is a collection of (semi-independent) \fITcl\fR
          278  +packages that provide utility functions useful to a large collection
          279  +of Tcl programmers\&.
          280  +.PP
          281  +The audience of this document is anyone wishing to either have just a
          282  +look at Tcllib's source code, or build the packages, or to extend and
          283  +modify them\&.
          284  +.PP
          285  +For builders and developers we additionally provide
          286  +.IP [1]
          287  +\fITcllib - The Installer's Guide\fR\&.
          288  +.IP [2]
          289  +\fITcllib - The Developer's Guide\fR\&.
          290  +.PP
          291  +respectively\&.
          292  +.SH "SOURCE LOCATION"
          293  +The official repository for Tcllib can be found at
          294  +\fIhttp://core\&.tcl-lang\&.org/tcllib\fR
          295  +.SH RETRIEVAL
          296  +Assuming that you simply wish to look at the sources, or build a
          297  +specific revision, the easiest way of retrieving it is to:
          298  +.IP [1]
          299  +Log into this site, as "anonymous", using the semi-random password in the captcha\&.
          300  +.IP [2]
          301  +Go to the "Timeline"\&.
          302  +.IP [3]
          303  +Choose the revision you wish to have\&.
          304  +.IP [4]
          305  +Follow its link to its detailed information page\&.
          306  +.IP [5]
          307  +On that page, choose either the "ZIP" or "Tarball" link to get
          308  +a copy of this revision in the format of your choice\&.
          309  +.PP
          310  +.SH "SOURCE CODE MANAGEMENT"
          311  +For the curious (or a developer-to-be), the sources are managed by the
          312  +\fIFossil SCM\fR [http://www\&.fossil-scm\&.org]\&.
          313  +Binaries for popular platforms can be found directly at its
          314  +\fIdownload page\fR [http://www\&.fossil-scm\&.org/download\&.html]\&.
          315  +.PP
          316  +With that tool available the full history can be retrieved via:
          317  +.CS
          318  +
          319  +
          320  +    fossil clone  http://core\&.tcl-lang\&.org/tcllib  tcllib\&.fossil
          321  +
          322  +.CE
          323  +followed by
          324  +.CS
          325  +
          326  +
          327  +    mkdir tcllib
          328  +    cd tcllib
          329  +    fossil open \&.\&./tcllib\&.fossil
          330  +
          331  +.CE
          332  +to get a checkout of the head of the trunk\&.

Changes to idoc/man/files/modules/doctools/doctools_lang_intro.n.

   330    330   [keywords {doctools language}]
   331    331   [keywords {doctools markup}]
   332    332   [keywords {doctools syntax}]
   333    333   [keywords markup]
   334    334   [keywords {semantic markup}]
   335    335       [description]
   336    336       [vset CATEGORY doctools]
   337         -[include \&.\&./doctools2base/include/feedback\&.inc]
          337  +[include \&.\&./common-text/feedback\&.inc]
   338    338   [manpage_end]
   339    339   
   340    340   .CE
   341    341   This also shows us that all doctools documents are split into two
   342    342   parts, the \fIheader\fR and the \fIbody\fR\&. Everything coming before
   343    343   [\fBdescription\fR] belongs to the header, and everything coming
   344    344   after belongs to the body, with the whole document bracketed by the
................................................................................
   389    389   .CS
   390    390   
   391    391   
   392    392       [manpage_begin NAME SECTION VERSION]
   393    393       [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
   394    394       [require PACKAGE VERSION][require PACKAGE][description]
   395    395       [vset CATEGORY doctools]
   396         -[include \&.\&./doctools2base/include/feedback\&.inc]
          396  +[include \&.\&./common-text/feedback\&.inc]
   397    397   [manpage_end]
   398    398   
   399    399   .CE
   400    400   has the same meaning as the example before\&.
   401    401   .PP
   402    402   On the other hand, if \fIwhitespace\fR is present it consists not
   403    403   only of any sequence of characters containing the space character,

Changes to idoc/man/toc.n.

  1337   1337   .TP
  1338   1338   \fBtcl::transform::spacer\fR
  1339   1339   \fIfiles/modules/virtchannel_transform/spacer\&.n\fR: Space insertation and removal
  1340   1340   .TP
  1341   1341   \fBtcl::transform::zlib\fR
  1342   1342   \fIfiles/modules/virtchannel_transform/tcllib_zlib\&.n\fR: zlib (de)compression
  1343   1343   .TP
         1344  +\fBtcl_community_communication\fR
         1345  +\fIfiles/devdoc/tcl_community_communication\&.n\fR: Tcl Community - Kind Communication
         1346  +.TP
  1344   1347   \fBtclDES\fR
  1345   1348   \fIfiles/modules/des/tcldes\&.n\fR: Implementation of the DES and triple-DES ciphers
  1346   1349   .TP
  1347   1350   \fBtclDESjr\fR
  1348   1351   \fIfiles/modules/des/tcldesjr\&.n\fR: Implementation of the DES and triple-DES ciphers
  1349   1352   .TP
  1350   1353   \fBtcldocstrip\fR
  1351   1354   \fIfiles/apps/tcldocstrip\&.n\fR: Tcl-based Docstrip Processor
  1352   1355   .TP
         1356  +\fBtcllib_devguide\fR
         1357  +\fIfiles/devdoc/tcllib_devguide\&.n\fR: Tcllib - The Developer's Guide
         1358  +.TP
         1359  +\fBtcllib_install_guide\fR
         1360  +\fIfiles/devdoc/tcllib_installer\&.n\fR: Tcllib - The Installer's Guide
         1361  +.TP
  1353   1362   \fBtcllib_ip\fR
  1354   1363   \fIfiles/modules/dns/tcllib_ip\&.n\fR: IPv4 and IPv6 address manipulation
  1355   1364   .TP
         1365  +\fBtcllib_license\fR
         1366  +\fIfiles/devdoc/tcllib_license\&.n\fR: Tcllib - License
         1367  +.TP
         1368  +\fBtcllib_releasemgr\fR
         1369  +\fIfiles/devdoc/tcllib_releasemgr\&.n\fR: Tcllib - The Release Manager's Guide
         1370  +.TP
         1371  +\fBtcllib_sources\fR
         1372  +\fIfiles/devdoc/tcllib_sources\&.n\fR: Tcllib - How To Get The Sources
         1373  +.TP
  1356   1374   \fBtclrep/machineparameters\fR
  1357   1375   \fIfiles/modules/math/machineparameters\&.n\fR: Compute double precision machine parameters\&.
  1358   1376   .TP
  1359   1377   \fBtepam\fR
  1360   1378   \fIfiles/modules/tepam/tepam_introduction\&.n\fR: An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
  1361   1379   .TP
  1362   1380   \fBtepam::argument_dialogbox\fR

Added idoc/www/tcllib/files/devdoc/tcl_community_communication.html.

            1  +<!DOCTYPE html><html><head>
            2  +<title>tcl_community_communication - </title>
            3  +<style type="text/css"><!--
            4  +    HTML {
            5  +	background: 	#FFFFFF;
            6  +	color: 		black;
            7  +    }
            8  +    BODY {
            9  +	background: 	#FFFFFF;
           10  +	color:	 	black;
           11  +    }
           12  +    DIV.doctools {
           13  +	margin-left:	10%;
           14  +	margin-right:	10%;
           15  +    }
           16  +    DIV.doctools H1,DIV.doctools H2 {
           17  +	margin-left:	-5%;
           18  +    }
           19  +    H1, H2, H3, H4 {
           20  +	margin-top: 	1em;
           21  +	font-family:	sans-serif;
           22  +	font-size:	large;
           23  +	color:		#005A9C;
           24  +	background: 	transparent;
           25  +	text-align:		left;
           26  +    }
           27  +    H1.doctools_title {
           28  +	text-align: center;
           29  +    }
           30  +    UL,OL {
           31  +	margin-right: 0em;
           32  +	margin-top: 3pt;
           33  +	margin-bottom: 3pt;
           34  +    }
           35  +    UL LI {
           36  +	list-style: disc;
           37  +    }
           38  +    OL LI {
           39  +	list-style: decimal;
           40  +    }
           41  +    DT {
           42  +	padding-top: 	1ex;
           43  +    }
           44  +    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
           45  +	font:		normal 12pt/14pt sans-serif;
           46  +	list-style:	none;
           47  +    }
           48  +    LI.doctools_section, LI.doctools_subsection {
           49  +	list-style: 	none;
           50  +	margin-left: 	0em;
           51  +	text-indent:	0em;
           52  +	padding: 	0em;
           53  +    }
           54  +    PRE {
           55  +	display: 	block;
           56  +	font-family:	monospace;
           57  +	white-space:	pre;
           58  +	margin:		0%;
           59  +	padding-top:	0.5ex;
           60  +	padding-bottom:	0.5ex;
           61  +	padding-left:	1ex;
           62  +	padding-right:	1ex;
           63  +	width:		100%;
           64  +    }
           65  +    PRE.doctools_example {
           66  +	color: 		black;
           67  +	background: 	#f5dcb3;
           68  +	border:		1px solid black;
           69  +    }
           70  +    UL.doctools_requirements LI, UL.doctools_syntax LI {
           71  +	list-style: 	none;
           72  +	margin-left: 	0em;
           73  +	text-indent:	0em;
           74  +	padding:	0em;
           75  +    }
           76  +    DIV.doctools_synopsis {
           77  +	color: 		black;
           78  +	background: 	#80ffff;
           79  +	border:		1px solid black;
           80  +	font-family:	serif;
           81  +	margin-top: 	1em;
           82  +	margin-bottom: 	1em;
           83  +    }
           84  +    UL.doctools_syntax {
           85  +	margin-top: 	1em;
           86  +	border-top:	1px solid black;
           87  +    }
           88  +    UL.doctools_requirements {
           89  +	margin-bottom: 	1em;
           90  +	border-bottom:	1px solid black;
           91  +    }
           92  +--></style>
           93  +</head>
           94  +<!-- Generated from file 'tcl_community_communication.man' by tcllib/doctools with format 'html'
           95  +   -->
           96  +<!-- tcl_community_communication.n
           97  +   -->
           98  +<body><hr> [
           99  +   <a href="../../../../../../../home">Tcllib Home</a>
          100  +&#124; <a href="../../../toc.html">Main Table Of Contents</a>
          101  +&#124; <a href="../../toc.html">Table Of Contents</a>
          102  +&#124; <a href="../../../index.html">Keyword Index</a>
          103  +&#124; <a href="../../../toc0.html">Categories</a>
          104  +&#124; <a href="../../../toc1.html">Modules</a>
          105  +&#124; <a href="../../../toc2.html">Applications</a>
          106  + ] <hr>
          107  +<div class="doctools">
          108  +<h1 class="doctools_title">tcl_community_communication(n) 1 tcllib &quot;&quot;</h1>
          109  +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
          110  +<p>tcl_community_communication - Tcl Community - Kind Communication</p>
          111  +</div>
          112  +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
          113  +<ul class="doctools_toc">
          114  +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
          115  +<li class="doctools_section"><a href="#section1">Description</a></li>
          116  +<li class="doctools_section"><a href="#section2">Signatories</a></li>
          117  +<li class="doctools_section"><a href="#section3">Authors</a></li>
          118  +</ul>
          119  +</div>
          120  +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
          121  +<p>The Tcl Community encourages contributions from anyone who wishes to
          122  +advance the development of:</p>
          123  +<ul class="doctools_itemized">
          124  +<li><p>The Tcl Language</p></li>
          125  +<li><p>Tcl derived languages</p></li>
          126  +<li><p>Tcl related libraries</p></li>
          127  +<li><p>Tcl extensions</p></li>
          128  +<li><p>External Projects that Integrate Tcl</p></li>
          129  +</ul>
          130  +<p>We welcome those contributions from anyone. We are blind to
          131  +gender, race, religion, cultural background, cybernetic nature, and
          132  +any other demographic characteristics, as well as personal political
          133  +views.</p>
          134  +<p>A community lives and dies by communications. And occasionally
          135  +our communications are peppered with patterns that are harsh,
          136  +unfriendly, unwelcoming and/or otherwise unkind. As a volunteer
          137  +community, we need all of the help we can get. Therefore, we ask all
          138  +contributors to make a conscious effort, in Tcl Community discussions,
          139  +to communicate in ways that are welcoming. Ways that are
          140  +friendly. Ways that are, in a word: kind.</p>
          141  +<p>These guidelines suggest specific ways to accomplish that goal.</p>
          142  +<p>Please note: for the balance of this document any reference to
          143  +&quot;People&quot;, &quot;Persons&quot;, &quot;anybody&quot; or &quot;somebody&quot; can refer to any sentient
          144  +being, not merely corporeal members of the species Homo Sapien.</p>
          145  +<dl class="doctools_definitions">
          146  +<dt>We are a Sanctuary not a Clubhouse</dt>
          147  +<dd><p>The Tcl Community is a collective of amateurs and professionals who
          148  +code, test, and use tools. Our community is open to all. There is no
          149  +velvet rope. There is no bouncer at the door. There are no secret
          150  +handshakes. Any sentient being who enters our midst is welcome. If
          151  +someone is ever asked to leave, it is only because they are being
          152  +disruptive to the functioning of the community.</p></dd>
          153  +<dt>We Merit Ideas, Not People</dt>
          154  +<dd><p>A good idea can come from anyone, regardless of how little time they
          155  +have been with us. A bad idea can come from anyone, regardless of how
          156  +much time or how little time they have been with us. We judge a
          157  +concept by how it stands up to scrutiny of logic, implementation, and
          158  +regression testing. We don’t judge ideas based on who had the idea
          159  +first, who agrees with the idea, or who disagrees with it.</p></dd>
          160  +<dt>Treat Everyone with Respect</dt>
          161  +<dd><p>Everyone is deserving of respect and courtesy at all times.</p></dd>
          162  +<dt>Refer to people by the names they use.</dt>
          163  +<dd><p>If grammar requires you to state a gender for a person, honor their
          164  +preferences about their gender identity. If you are unsure as to the
          165  +gender of an individual, ask. If someone had to guess about your
          166  +gender and got it wrong, please correct them and do not take it
          167  +personally.</p></dd>
          168  +<dt>Do not take a harsh tone towards other participants.</dt>
          169  +<dd><p>Do not make personal attacks against anyone (participant or not.)</p>
          170  +<p>Criticize statements and actions, never people.</p></dd>
          171  +<dt>Don’t Take Things Personally</dt>
          172  +<dd><p>When in doubt, assume the best in people. A criticism of your
          173  +statements is not a personal attack on you.</p></dd>
          174  +<dt>Persons, not People</dt>
          175  +<dd><p>Stereotypes are an unhelpful tool on many accounts. They are generally
          176  +oversimplified. They are usually flat out wrong. And even if &quot;right&quot;
          177  +they are of absolutely no utility in determining the capabilities,
          178  +motivations, or fitness of an individual.</p>
          179  +<p>Don’t use them in Tcl Community communications.</p></dd>
          180  +<dt>Mistakes Happen</dt>
          181  +<dd><p>The human condition is a series of trials and errors. Progress is when
          182  +we get one more trial than error. Being wrong or making a mistake is
          183  +the default state of humanity. Accept the errors of your fellow
          184  +sentient beings, and be aware that you are also fallible.</p></dd>
          185  +<dt>Keep it Real</dt>
          186  +<dd><p>Please respond to what people actually say. We are all amazing
          187  +individuals, but none among us are mind readers. If you find yourself
          188  +responding to what you imagine someone is thinking, odds are you are
          189  +going to be wrong.</p>
          190  +<p>If you must criticize someone, stick to things they have
          191  +actually done. Never criticize for something you speculate they have
          192  +done. Or imagine they have done. Or something someone who shares some
          193  +attribute with them has done in the past.</p>
          194  +<p>Keep discussions about any non-Tcl subjects to what can be
          195  +stated factually and without emotion or judgement.</p></dd>
          196  +<dt>When Trouble Arises, Don’t Escalate</dt>
          197  +<dd><p>If you feel you are being personally attacked or offended, take the
          198  +high road. Punching back in a public forum will only makes things
          199  +worse. Address the matter in a private correspondence. Be
          200  +polite. Express your feelings, but note that you are expressing your
          201  +feelings. When writing, look for a way to calm matters down. And when
          202  +in doubt, sleep on your letter before pressing send. And when not in
          203  +doubt, sleep on it for another day after that.</p>
          204  +<p>If you are a spectator to a fight in progress, politely request
          205  +the two parties take the matter to a more private forum.</p></dd>
          206  +<dt>Always get the Last Word: I’m Sorry</dt>
          207  +<dd><p>If an personal argument does arise, be the first to apologize. An
          208  +apology does not concede a logical point. It merely acknowledges that
          209  +at some point the discussion left either logic, community decency, or
          210  +both. Return to the topic when cooler heads can prevail.</p></dd>
          211  +<dt>Nobody is Keeping Score</dt>
          212  +<dd><p>There is no prize for being right. There is no cost for being wrong. A
          213  +hard sell is not going to advance your idea along any more than a
          214  +logical argument. You aren’t running for office. This isn’t debate
          215  +club. If you find yourself continuing a discussion beyond where a
          216  +topic can be logically discussed, stop.</p></dd>
          217  +<dt>No Evangelizing</dt>
          218  +<dd><p>The Tcl Community is not the place to promote your chosen operating
          219  +system, political outlook, religion, marketing scheme, or economic
          220  +model. Period.</p>
          221  +<p>(And if you do bring it up, be prepared to have your chosen
          222  +topic discussed logically. And odds are, not favorably.)</p></dd>
          223  +<dt>Respect the Community</dt>
          224  +<dd><p>If the Community has come to a decision on a course of action, please
          225  +stop arguing.</p>
          226  +<p>If someone complains about how you are expressing your ideas,
          227  +listen.</p>
          228  +<p>If your words are hurting people, stop. There is no amount of
          229  +being &quot;right&quot; that makes up for someone leaving our midst because they
          230  +felt insulted, threatened, or ignored.</p></dd>
          231  +</dl>
          232  +<p>By following these guidelines, we will build our community, encourage
          233  +more contribution to our projects, and our discussions will be
          234  +friendlier and reach conclusions more easily.</p>
          235  +<p>Thank You.</p>
          236  +</div>
          237  +<div id="section2" class="doctools_section"><h2><a name="section2">Signatories</a></h2>
          238  +<ul class="doctools_itemized">
          239  +<li><p>Sean &quot;the Hypnotoad&quot; Woods</p></li>
          240  +<li><p>Andreas Kupries</p></li>
          241  +</ul>
          242  +</div>
          243  +<div id="section3" class="doctools_section"><h2><a name="section3">Authors</a></h2>
          244  +<dl class="doctools_definitions">
          245  +<dt>Primary</dt>
          246  +<dd><p>Sean &quot;the Hypnotoad&quot; Woods</p></dd>
          247  +<dt>Light editing</dt>
          248  +<dd><p>Andreas Kupries</p></dd>
          249  +</dl>
          250  +</div>
          251  +</div></body></html>

Added idoc/www/tcllib/files/devdoc/tcllib_devguide.html.

            1  +<!DOCTYPE html><html><head>
            2  +<title>tcllib_devguide - </title>
            3  +<style type="text/css"><!--
            4  +    HTML {
            5  +	background: 	#FFFFFF;
            6  +	color: 		black;
            7  +    }
            8  +    BODY {
            9  +	background: 	#FFFFFF;
           10  +	color:	 	black;
           11  +    }
           12  +    DIV.doctools {
           13  +	margin-left:	10%;
           14  +	margin-right:	10%;
           15  +    }
           16  +    DIV.doctools H1,DIV.doctools H2 {
           17  +	margin-left:	-5%;
           18  +    }
           19  +    H1, H2, H3, H4 {
           20  +	margin-top: 	1em;
           21  +	font-family:	sans-serif;
           22  +	font-size:	large;
           23  +	color:		#005A9C;
           24  +	background: 	transparent;
           25  +	text-align:		left;
           26  +    }
           27  +    H1.doctools_title {
           28  +	text-align: center;
           29  +    }
           30  +    UL,OL {
           31  +	margin-right: 0em;
           32  +	margin-top: 3pt;
           33  +	margin-bottom: 3pt;
           34  +    }
           35  +    UL LI {
           36  +	list-style: disc;
           37  +    }
           38  +    OL LI {
           39  +	list-style: decimal;
           40  +    }
           41  +    DT {
           42  +	padding-top: 	1ex;
           43  +    }
           44  +    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
           45  +	font:		normal 12pt/14pt sans-serif;
           46  +	list-style:	none;
           47  +    }
           48  +    LI.doctools_section, LI.doctools_subsection {
           49  +	list-style: 	none;
           50  +	margin-left: 	0em;
           51  +	text-indent:	0em;
           52  +	padding: 	0em;
           53  +    }
           54  +    PRE {
           55  +	display: 	block;
           56  +	font-family:	monospace;
           57  +	white-space:	pre;
           58  +	margin:		0%;
           59  +	padding-top:	0.5ex;
           60  +	padding-bottom:	0.5ex;
           61  +	padding-left:	1ex;
           62  +	padding-right:	1ex;
           63  +	width:		100%;
           64  +    }
           65  +    PRE.doctools_example {
           66  +	color: 		black;
           67  +	background: 	#f5dcb3;
           68  +	border:		1px solid black;
           69  +    }
           70  +    UL.doctools_requirements LI, UL.doctools_syntax LI {
           71  +	list-style: 	none;
           72  +	margin-left: 	0em;
           73  +	text-indent:	0em;
           74  +	padding:	0em;
           75  +    }
           76  +    DIV.doctools_synopsis {
           77  +	color: 		black;
           78  +	background: 	#80ffff;
           79  +	border:		1px solid black;
           80  +	font-family:	serif;
           81  +	margin-top: 	1em;
           82  +	margin-bottom: 	1em;
           83  +    }
           84  +    UL.doctools_syntax {
           85  +	margin-top: 	1em;
           86  +	border-top:	1px solid black;
           87  +    }
           88  +    UL.doctools_requirements {
           89  +	margin-bottom: 	1em;
           90  +	border-bottom:	1px solid black;
           91  +    }
           92  +--></style>
           93  +</head>
           94  +<!-- Generated from file 'tcllib_devguide.man' by tcllib/doctools with format 'html'
           95  +   -->
           96  +<!-- tcllib_devguide.n
           97  +   -->
           98  +<body><hr> [
           99  +   <a href="../../../../../../../home">Tcllib Home</a>
          100  +&#124; <a href="../../../toc.html">Main Table Of Contents</a>
          101  +&#124; <a href="../../toc.html">Table Of Contents</a>
          102  +&#124; <a href="../../../index.html">Keyword Index</a>
          103  +&#124; <a href="../../../toc0.html">Categories</a>
          104  +&#124; <a href="../../../toc1.html">Modules</a>
          105  +&#124; <a href="../../../toc2.html">Applications</a>
          106  + ] <hr>
          107  +<div class="doctools">
          108  +<h1 class="doctools_title">tcllib_devguide(n) 1 tcllib &quot;&quot;</h1>
          109  +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
          110  +<p>tcllib_devguide - Tcllib - The Developer's Guide</p>
          111  +</div>
          112  +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
          113  +<ul class="doctools_toc">
          114  +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
          115  +<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
          116  +<li class="doctools_section"><a href="#section1">Description</a></li>
          117  +<li class="doctools_section"><a href="#section2">Commitments</a>
          118  +<ul>
          119  +<li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
          120  +<li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
          121  +</ul>
          122  +</li>
          123  +<li class="doctools_section"><a href="#section3">Branching and Workflow</a>
          124  +<ul>
          125  +<li class="doctools_subsection"><a href="#subsection3">Package Dependencies</a></li>
          126  +<li class="doctools_subsection"><a href="#subsection4">Trunk</a></li>
          127  +<li class="doctools_subsection"><a href="#subsection5">Branches</a></li>
          128  +<li class="doctools_subsection"><a href="#subsection6">Working with Branches</a></li>
          129  +<li class="doctools_subsection"><a href="#subsection7">Version numbers</a></li>
          130  +</ul>
          131  +</li>
          132  +<li class="doctools_section"><a href="#section4">Structural Overview</a>
          133  +<ul>
          134  +<li class="doctools_subsection"><a href="#subsection8">Main Directories</a></li>
          135  +<li class="doctools_subsection"><a href="#subsection9">More Directories</a></li>
          136  +<li class="doctools_subsection"><a href="#subsection10">Top Files</a></li>
          137  +<li class="doctools_subsection"><a href="#subsection11">File Types</a></li>
          138  +</ul>
          139  +</li>
          140  +<li class="doctools_section"><a href="#section5">Testsuite Tooling</a>
          141  +<ul>
          142  +<li class="doctools_subsection"><a href="#subsection12">Invoke the testsuites of a specific module</a></li>
          143  +<li class="doctools_subsection"><a href="#subsection13">Invoke the testsuites of all modules</a></li>
          144  +<li class="doctools_subsection"><a href="#subsection14">Detailed Test Logs</a></li>
          145  +<li class="doctools_subsection"><a href="#subsection15">Shell Selection</a></li>
          146  +<li class="doctools_subsection"><a href="#subsection16">Help</a></li>
          147  +</ul>
          148  +</li>
          149  +<li class="doctools_section"><a href="#section6">Documentation Tooling</a>
          150  +<ul>
          151  +<li class="doctools_subsection"><a href="#subsection17">Generate documentation for a specific module</a></li>
          152  +<li class="doctools_subsection"><a href="#subsection18">Generate documentation for all modules</a></li>
          153  +<li class="doctools_subsection"><a href="#subsection19">Available output formats, help</a></li>
          154  +<li class="doctools_subsection"><a href="#subsection20">Validation without output</a></li>
          155  +</ul>
          156  +</li>
          157  +<li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
          158  +<li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
          159  +</ul>
          160  +</div>
          161  +<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
          162  +<div class="doctools_synopsis">
          163  +<ul class="doctools_syntax">
          164  +<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>
          165  +<li><a href="#2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></li>
          166  +<li><a href="#3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></li>
          167  +</ul>
          168  +</div>
          169  +</div>
          170  +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
          171  +<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
          172  +package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
          173  +packages that provide utility functions useful to a large collection
          174  +of Tcl programmers.</p>
          175  +<p>This document is a guide for developers working on Tcllib,
          176  +i.e. maintainers fixing bugs, extending the collection's
          177  +functionality, etc.</p>
          178  +<p>Please read</p>
          179  +<ol class="doctools_enumerated">
          180  +<li><p><i class="term"><a href="tcllib_sources.html">Tcllib - How To Get The Sources</a></i> and</p></li>
          181  +<li><p><i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i></p></li>
          182  +</ol>
          183  +<p>first, if that was not done already.</p>
          184  +<p>Here we assume that the sources are already available in a
          185  +directory of your choice, and that you not only know how to build and
          186  +install them, but also have all the necessary requisites to actually
          187  +do so. The guide to the sources in particular also explains which
          188  +source code management system is used, where to find it, how to set it
          189  +up, etc.</p>
          190  +</div>
          191  +<div id="section2" class="doctools_section"><h2><a name="section2">Commitments</a></h2>
          192  +<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Contributor</a></h3>
          193  +<p>As a contributor to Tcllib you are committing yourself to:</p>
          194  +<ol class="doctools_enumerated">
          195  +<li><p>keep the guidelines written down in
          196  +       <i class="term"><a href="tcl_community_communication.html">Tcl Community - Kind Communication</a></i> in your mind.
          197  +       The main point to take away from there is
          198  +       <em>to be kind to each other</em>.</p></li>
          199  +<li><p>Your contributions getting distributed under a BSD/MIT license.
          200  +       For the details see <i class="term"><a href="tcllib_license.html">Tcllib - License</a></i></p></li>
          201  +</ol>
          202  +<p>Contributions are made by entering tickets into our tracker, providing
          203  +patches, bundles or branches of code for inclusion, or posting to the
          204  +Tcllib related mailing lists.</p>
          205  +</div>
          206  +<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Maintainer</a></h3>
          207  +<p>When contributing one or more packages for full inclusion into Tcllib
          208  +you are committing yourself to</p>
          209  +<ol class="doctools_enumerated">
          210  +<li><p>Keep the guidelines written down in
          211  +       <i class="term"><a href="tcl_community_communication.html">Tcl Community - Kind Communication</a></i>
          212  +       (as any contributor) in your mind. The main point to take away
          213  +       from there is <em>to be kind to each other</em>.</p></li>
          214  +<li><p>Your packages getting distributed under a BSD/MIT license.  For
          215  +       the details see <i class="term"><a href="tcllib_license.html">Tcllib - License</a></i></p></li>
          216  +<li><p>Maintenance of the new packages for a period of two years under
          217  +       the following rules, and responsibilities:</p>
          218  +<ol class="doctools_enumerated">
          219  +       
          220  +<li><p>A maintainer may step down after the mandatory period as
          221  +       	      they see fit.</p></li>
          222  +<li><p>A maintainer may step down before the end of the
          223  +      	      mandatory period, under the condition that a replacement
          224  +      	      maintainer is immediately available and has agreed to
          225  +      	      serve the remainder of the period, plus their own
          226  +      	      mandatory period (see below).</p></li>
          227  +<li><p>When stepping down without a replacement maintainer
          228  +      	      taking over the relevant packages have to be flagged as
          229  +      	      <b class="const">unmaintained</b>.</p></li>
          230  +<li><p>When a replacement mantainer is brought in for a package
          231  +      	      it is (kept) marked as <b class="const">maintained</b> (again).</p>
          232  +<p>A replacement maintainer is bound by the same rules as
          233  +	      the original maintainer, except that the mandatory
          234  +	      period of maintenance is shortened to one year.</p></li>
          235  +<li><p>For any <b class="const">unmaintained</b> package a contributor
          236  +       	      interested in becoming its maintainer can become so by
          237  +       	      flagging them as <b class="const">maintained</b> with their name and
          238  +       	      contact information, committing themselves to the rules
          239  +       	      of a replacement maintainer (see previous point).</p></li>
          240  +<li><p>For any already <b class="const">maintained</b> package a contributor
          241  +       	      interested in becoming a co-maintainer can become so
          242  +       	      with the agreement of the existing maintainer(s),
          243  +       	      committing themselves to the rules of a replacement
          244  +       	      maintainer (see two points previous).</p></li>
          245  +</ol>
          246  +<p>The responsibilities as a maintainer include:</p>
          247  +<ol class="doctools_enumerated">
          248  +       
          249  +<li><p>Watching Tcllib's ticket tracker for bugs, bug fixes,
          250  +       	      and feature requests related to the new packages.</p></li>
          251  +<li><p>Reviewing the aforementioned tickets, rejecting or
          252  +       	      applying them</p></li>
          253  +<li><p>Coordination and discussion with ticket submitter during
          254  +       	      the development and/or application of bug fixes.</p></li>
          255  +</ol>
          256  +</li>
          257  +<li><p>Follow the <span class="sectref"><a href="#section3">Branching and Workflow</a></span> of this guide.</p></li>
          258  +</ol>
          259  +</div>
          260  +</div>
          261  +<div id="section3" class="doctools_section"><h2><a name="section3">Branching and Workflow</a></h2>
          262  +<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Package Dependencies</a></h3>
          263  +<p>Regarding packages and dependencies between them Tcllib occupies a
          264  +middle position between two extremes:</p>
          265  +<ol class="doctools_enumerated">
          266  +<li><p>On one side a strongly interdependent set of packages, usually
          267  +       by a single author, for a single project. Looking at my
          268  +       (Andreas Kupries) own work examples of such are
          269  +       <a href="https://core.tcl.tk/akupries/marpa/index">Marpa</a>,
          270  +       <a href="https://core.tcl.tk/akupries/crimp/index">CRIMP</a>,
          271  +       <a href="https://core.tcl.tk/akupries/kinetcl/index">Kinetcl</a>, etc.</p>
          272  +<p>For every change the author of the project handles all the
          273  +       modifications cascading from any incompatibilities it
          274  +       introduced to the system.</p></li>
          275  +<li><p>On the other side, the world of semi-independent projects by
          276  +       many different authors where authors know what packages their
          277  +       own creations depend on, yet usually do not know who else
          278  +       depends on them.</p>
          279  +<p>The best thing an author making an (incompatible) change to
          280  +       their project can do is to for one announce such changes in
          281  +       some way, and for two use versioning to distinguish the code
          282  +       before and after the change.</p>
          283  +<p>The world is then responsible for adapting, be it by updating
          284  +       their own projects to the new version, or by sticking to the
          285  +       old.</p></li>
          286  +</ol>
          287  +<p>As mentioned already, Tcllib lives in the middle of that.</p>
          288  +<p>While we as maintainers cannot be aware of all users of
          289  +       Tcllib's packages, and thus have to rely on the mechanisms
          290  +       touched on in point 2 above for that, the dependencies between
          291  +       the packages contained in Tcllib are a different matter.</p>
          292  +<p>As we are collectively responsible for the usability of Tcllib
          293  +       in toto to the outside world, it behooves us to be individually
          294  +       mindful even of Tcllib packages we are not directly
          295  +       maintaining, when they depend on packages under our
          296  +       maintainership.
          297  +       This may be as simple as coordinating with the maintainers of
          298  +       the affected packages.
          299  +       It may also require us to choose how to adapt affected packages
          300  +       which do not have maintainers, i.e. modify them to use our
          301  +       changed package properly, or modify them to properly depend on
          302  +       the unchanged version of our package.</p>
          303  +<p>Note that the above is not only a chore but an opportunity as
          304  +       well.
          305  +       Additional insight can be had by forcing ourselves to look at
          306  +       our package and the planned change(s) from an outside
          307  +       perspective, to consider the ramifications of our actions on
          308  +       others in general, and on dependent packages in particular.</p>
          309  +</div>
          310  +<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Trunk</a></h3>
          311  +<p>The management and use of branches is an important part of working
          312  +with a <i class="term">Distributed Version Control System</i> (<i class="term">DVCS</i>) like
          313  +<a href="https://www.fossil-scm.org/">fossil</a>.</p>
          314  +<p>For Tcllib the main branch of the collection is
          315  +       <i class="term">trunk</i>. In <i class="term">git</i> this branch would be called
          316  +       <i class="term">master</i>, and this is exactly the case in the
          317  +       <a href="https://github.com/tcltk/tcllib/">github mirror</a> of
          318  +       Tcllib.</p>
          319  +<p>To properly support debugging <em>each commit</em> on this
          320  +       branch <em>has to pass the entire testsuite</em> of the
          321  +       collection. Using bisection to determine when an issue appeared
          322  +       is an example of an action made easier by this constraint.</p>
          323  +<p>This is part of our collective responsibility for the usability
          324  +       of Tcllib in toto to the outside world.
          325  +       As <i class="term">fossil</i> has no mechanism to enforce this condition
          326  +       this is handled on the honor system for developers and maintainers.</p>
          327  +<p>To make the task easier Tcllib comes with a tool
          328  +       (&quot;<b class="file">sak.tcl</b>&quot;) providing a number of commands in
          329  +       support. These commands are explained in the following sections
          330  +       of this guide.</p>
          331  +<p>While it is possible and allowed to commit directly to trunk
          332  +       remember the above constraint regarding the testsuite, and the
          333  +       coming notes about other possible issues with a commit.</p>
          334  +</div>
          335  +<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Branches</a></h3>
          336  +<p>Given the constraints placed on the <i class="term">trunk</i> branch of the
          337  +repository it is (strongly) recommended to perform any development
          338  +going beyond trivial changes on a non-trunk branch.</p>
          339  +<p>Outside of the trunk developers are allowed to commit
          340  +       intermediate broken states of their work.
          341  +       Only at the end of a development cycle, when the relevant
          342  +       branch is considered ready for merging, will it be necessary to
          343  +       perform full the set of validations ensuring that the merge to
          344  +       come will create a good commit on trunk.</p>
          345  +<p>Note that while a review from a second developer is not a
          346  +       required condition for merging a branch it is recommended to
          347  +       seek out such an independent opinion as a means of
          348  +       cross-checking the work.</p>
          349  +<p>It also recommended to give any new branch a name which aids in
          350  +       determining additional details about it. Examples of good
          351  +       things to stick into a branch name would be</p>
          352  +<ul class="doctools_itemized">
          353  +<li><p>Developer (nick)name</p></li>
          354  +<li><p>Ticket hash/reference</p></li>
          355  +<li><p>One or two keywords applicable to the work</p></li>
          356  +<li><p>...</p></li>
          357  +</ul>
          358  +<p>Further, while most development branches are likely quite
          359  +       short-lived, no prohibitions exist against making longer-lived
          360  +       branches.
          361  +       Creators should however be mindful that the longer such a
          362  +       branch exists without merges the more divergent they will tend
          363  +       to be, with an associated increase in the effort which will
          364  +       have to be spent on either merging from and merging to trunk.</p>
          365  +</div>
          366  +<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Working with Branches</a></h3>
          367  +<p>In the hope of engendering good work practices now a few example
          368  +operations which will come up with branches, and their associated
          369  +fossil command (sequences).</p>
          370  +<dl class="doctools_definitions">
          371  +<dt><em>Awareness</em></dt>
          372  +<dd><p>When developing we have to keep ourselves aware of the context of our
          373  +work. On what branch are we ? What files have we changed ? What new
          374  +files are not yet known to the repository ? What has happened remotely
          375  +since we used our checkout ?
          376  +The answers to these questions become especially important when using
          377  +a long-lived checkout and coming back to it after some time away.</p>
          378  +<p>Commands to answer questions like the above are:</p>
          379  +<dl class="doctools_definitions">
          380  +<dt><b class="cmd">fossil pull</b></dt>
          381  +<dd><p>Get all changes done on the remote since the last pull or sync
          382  +       from it. This has to be done first, before any of the commands
          383  +       below.</p>
          384  +<p>Even if the commit in our checkout refers to the branch we want
          385  +       right now control operations committed to the remote may have
          386  +       changed that from underneath us.</p></dd>
          387  +<dt><b class="cmd">fossil info | grep tags</b></dt>
          388  +<dd></dd>
          389  +<dt><b class="cmd">fossil branch list | grep '\*'</b></dt>
          390  +<dd><p>Two different ways of determining the branch our checkout is
          391  +       on.</p></dd>
          392  +<dt><b class="cmd">fossil timeline</b></dt>
          393  +<dd><p>What have we (and others) done recently ?</p>
          394  +<p><em>Attention</em>, this information is very likely outdated, the
          395  +       more the longer we did not use this checkout.
          396  +       Run <b class="cmd">fossil pull</b> first to get latest information from
          397  +       the remote repository of the project.</p></dd>
          398  +<dt><b class="cmd">fossil timeline current</b></dt>
          399  +<dd><p>Place the commit our checkout is based on at the top of the
          400  +       timeline.</p></dd>
          401  +<dt><b class="cmd">fossil changes</b></dt>
          402  +<dd><p>Lists the files we have changed compared to the commit the
          403  +       checkout is based on.</p></dd>
          404  +<dt><b class="cmd">fossil extra</b></dt>
          405  +<dd><p>Lists the files we have in the checkout the repository does not
          406  +       know about. This may be leftover chaff from our work, or
          407  +       something we have forgotten to <b class="cmd">fossil add</b> to the
          408  +       repository yet.</p></dd>
          409  +</dl></dd>
          410  +<dt><em>Clean checkouts</em></dt>
          411  +<dd><p>Be aware of where you are (see first definition).</p>
          412  +<p>For pretty much all the operation recipes below a clean
          413  +       checkout is at least desired, often required.
          414  +       To check that a checkout is clean invoke</p>
          415  +<pre class="doctools_example">
          416  +    fossil changes
          417  +    fossil extra
          418  +</pre>
          419  +<p>How to clean up when uncommitted changes of all sorts are found is
          420  +context-specific and outside of the scope of this guide.</p></dd>
          421  +<dt><em>Starting a new branch</em></dt>
          422  +<dd><p>Be aware of where you are (see first definition).</p>
          423  +<p>Ensure that you have clean checkout (see second definition).
          424  +       It is <em>required</em>.</p>
          425  +<p>In most situations you want to be on branch <i class="term">trunk</i>, and
          426  +       you want to be on the latest commit for it. To get there use</p>
          427  +<pre class="doctools_example">
          428  +    fossil pull
          429  +    fossil update trunk
          430  +</pre>
          431  +<p>If some other branch is desired as the starting point for the coming
          432  +work replace <i class="term">trunk</i> in the commands above with the name of that
          433  +branch.</p>
          434  +<p>With the base line established we now have two ways of creating
          435  +       the new branch, with differing (dis)advantages.
          436  +       The simpler way is to</p>
          437  +<pre class="doctools_example">
          438  +    fossil branch new NAME_OF_NEW_BRANCH
          439  +</pre>
          440  +<p>and start developing. The advantage here is that you cannot forget to
          441  +create the branch. The disadvantages are that we have a branch commit
          442  +unchanged from where we branched from, and that we have to use
          443  +high-handed techniques like hiding or shunning to get rid of the
          444  +commit should we decide to abandon the work before the first actual
          445  +commit on the branch.</p>
          446  +<p>The other way of creating the branch is to start developing,
          447  +and then on the first commit use the option <b class="option">--branch</b> to tell
          448  +<b class="syscmd">fossil</b> that we are starting a branch now. I.e. run</p>
          449  +<pre class="doctools_example">
          450  +    fossil commit --branch NAME_OF_NEW_BRANCH ...
          451  +</pre>
          452  +<p>where <i class="term">...</i> are any other options used to supply the commit
          453  +message, files to commit, etc.</p>
          454  +<p>The (dis)advantages are now reversed.</p>
          455  +<p>We have no superflous commit, only what is actually
          456  +       developed. The work is hidden until we commit to make our first
          457  +       commit.</p>
          458  +<p>We may forget to use <b class="option">--branch NAME_OF_NEW_BRANCH</b> and
          459  +       then have to correct that oversight via the fossil web
          460  +       interface (I am currently unaware of ways of doing such from
          461  +       the command line, although some magic incantantion of
          462  +       <b class="cmd">fossil tag create</b> may work).</p>
          463  +<p>It helps to keep awareness, like checking before any commit
          464  +       that we are on the desired branch.</p></dd>
          465  +<dt><em>Merging a branch into trunk</em></dt>
          466  +<dd><p>Be aware of where you are (see first definition).</p>
          467  +<p>Ensure that you have clean checkout (see second definition).
          468  +       In the full-blown sequence (zig-zag) it is <em>required</em>, due
          469  +       to the merging from trunk. In the shorter sequence it is only
          470  +       desired. That said, keeping the checkout clean before
          471  +       any major operations is a good habit to have, in my opinion.</p>
          472  +<p>The full-blown sequencing with checks all the way is to</p>
          473  +<ol class="doctools_enumerated">
          474  +<li><p>Validate the checkout, i.e. last commit on your branch. Run the
          475  +       full test suite and other validations, fix all the issues which
          476  +       have cropped up.</p></li>
          477  +<li><p>Merge the latest state of the <i class="term">trunk</i> (see next definition).</p></li>
          478  +<li><p>Validate the checkout again. The incoming trunk changes may
          479  +       have broken something now. Do any required fixes.</p></li>
          480  +<li><p>Now merge to the trunk using</p>
          481  +<pre class="doctools_example">
          482  +    fossil update trunk
          483  +    fossil merge --integrate YOUR_BRANCH
          484  +</pre>
          485  +</li>
          486  +<li><p>At this point the checkout should be in the same state as at
          487  +       the end of point (3) above, because we resolved any issues with
          488  +       the trunk already. Thus a simple</p>
          489  +<pre class="doctools_example">
          490  +    fossil commit ...
          491  +</pre>
          492  +<p>should be sufficient now to commit the merge back and close the
          493  +       branch (due to the <b class="option">--integrate</b> we used on the merge).</p>
          494  +<p>The more paranoid may validate the checkout a third time before
          495  +       commiting.</p></li>
          496  +</ol>
          497  +<p>I call this a <i class="term">zig-zag merge</i> because of how the arrows
          498  +       look in the timeline, from trunk to feature branch for the
          499  +       first merge, and then back for the final merge.</p>
          500  +<p>A less paranoid can do what I call a <i class="term">simple merge</i>,
          501  +       which moves step (2) after step (4) and skips step (3)
          502  +       entirely. The resulting shorter sequence is</p>
          503  +<ol class="doctools_enumerated">
          504  +<li><p>Validate</p></li>
          505  +<li><p>Merge to trunk</p></li>
          506  +<li><p>Validate again</p></li>
          507  +<li><p>Commit to trunk</p></li>
          508  +</ol>
          509  +<p>The last step after either zig-zag or plain merge is to</p>
          510  +<pre class="doctools_example">
          511  +    fossil sync
          512  +</pre>
          513  +<p>This saves our work to the remote side, and further gives us any other
          514  +work done while we were doing our merge. It especially allows us to
          515  +check if we raced somebody else, resulting in a split trunk.</p>
          516  +<p>When that happens we should coordinate with the other developer
          517  +       on who fixes the split, to ensure that we do not race each
          518  +       other again.</p></dd>
          519  +<dt><em>Merging from trunk</em></dt>
          520  +<dd><p>Be aware of where you are (see first definition).</p>
          521  +<p>Ensure that you have clean checkout (see second definition).
          522  +       It is <em>required</em>.</p>
          523  +<p>In most situations you want to import the latest commit of
          524  +       branch <i class="term">trunk</i> (or other origin). To get it use</p>
          525  +<pre class="doctools_example">
          526  +    fossil pull
          527  +</pre>
          528  +<p>With that done we can now import this commit into our current
          529  +       branch with</p>
          530  +<pre class="doctools_example">
          531  +    fossil merge trunk
          532  +</pre>
          533  +<p>Even if <b class="syscmd">fossil</b> does not report any conflicts it is a
          534  +       good idea to check that the operation has not broken the new
          535  +       and/or changed functionality we are working on.</p>
          536  +<p>With the establishment of a good merge we then save the state
          537  +       with</p>
          538  +<pre class="doctools_example">
          539  +    fossil commit ...
          540  +</pre>
          541  +<p>before continuing development.</p></dd>
          542  +</dl>
          543  +</div>
          544  +<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Version numbers</a></h3>
          545  +<p>In Tcllib all changes to a package have to come with an increment of
          546  +its version number. What part is incremented (patchlevel, minor, major
          547  +version) depends on the kind of change made. With multiple changes in
          548  +a commit the highest &quot;wins&quot;.</p>
          549  +<p>When working in a development branch the version change can be
          550  +       deferred until it is time to merge, and then has to cover all
          551  +       the changes in the branch.</p>
          552  +<p>Below a list of the kinds of changes and their associated
          553  +       version increments:</p>
          554  +<dl class="doctools_definitions">
          555  +<dt><i class="term">D - documentation</i></dt>
          556  +<dd><p>No increment</p></dd>
          557  +<dt><i class="term">T - testsuite</i></dt>
          558  +<dd><p>No increment</p></dd>
          559  +<dt><i class="term">B - bugfix</i></dt>
          560  +<dd><p>Patchlevel</p></dd>
          561  +<dt><i class="term">I - implementation tweak</i></dt>
          562  +<dd><p>Patchlevel</p></dd>
          563  +<dt><i class="term">P - performance tweak</i></dt>
          564  +<dd><p>Patchlevel</p></dd>
          565  +<dt><i class="term">E - backward-compatible extension</i></dt>
          566  +<dd><p>Minor</p></dd>
          567  +<dt><i class="term">API - incompatible change</i></dt>
          568  +<dd><p>Major</p></dd>
          569  +</dl>
          570  +<p>Note that a commit containing a version increment has to
          571  +       mention the new version number in its commit message, as well
          572  +       as the kind of change which caused it.</p>
          573  +<p>Note further that the version number of a package currently
          574  +       exists in three places. An increment has to update all of them:</p>
          575  +<ol class="doctools_enumerated">
          576  +<li><p>The package implementation.</p></li>
          577  +<li><p>The package index (&quot;<b class="file">pkgIndex.tcl</b>&quot;)</p></li>
          578  +<li><p>The package documentation.</p></li>
          579  +</ol>
          580  +<p>The &quot;<b class="file">sak.tcl</b>&quot; command <b class="cmd">validate version</b> helps
          581  +       finding discrepancies between the first two.
          582  +       All the other <b class="cmd">validate</b> methods are also of interest to
          583  +       any developer. Invoke it with</p>
          584  +<pre class="doctools_example"> sak.tcl help validate </pre>
          585  +<p>to see their documentation.</p>
          586  +</div>
          587  +</div>
          588  +<div id="section4" class="doctools_section"><h2><a name="section4">Structural Overview</a></h2>
          589  +<div id="subsection8" class="doctools_subsection"><h3><a name="subsection8">Main Directories</a></h3>
          590  +<p>The main directories in the Tcllib toplevel directory and of interest
          591  +to a developer are:</p>
          592  +<dl class="doctools_definitions">
          593  +<dt>&quot;<b class="file">modules</b>&quot;</dt>
          594  +<dd><p>Each child directory represents one or more packages.
          595  +In the case of the latter the packages are usually related in some
          596  +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
          597  +loose (base64) to strong (math) relations between the packages in the
          598  +directory.</p></dd>
          599  +<dt>&quot;<b class="file">apps</b>&quot;</dt>
          600  +<dd><p>This directory contains all the installable applications, with their
          601  +documentation. Note that this directory is currently <em>not</em> split
          602  +into sub-directories.</p></dd>
          603  +<dt>&quot;<b class="file">examples</b>&quot;</dt>
          604  +<dd><p>Each child directory &quot;<b class="file">foo</b>&quot; contains one or more example
          605  +application for the packages in &quot;<b class="file">modules/foo</b>&quot;. These examples are
          606  +generally not polished enough to be considered for installation.</p></dd>
          607  +</dl>
          608  +</div>
          609  +<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">More Directories</a></h3>
          610  +<dl class="doctools_definitions">
          611  +<dt>&quot;<b class="file">config</b>&quot;</dt>
          612  +<dd><p>This directory contains files supporting the Unix build system,
          613  +i.e. &quot;<b class="file">configure</b>&quot; and &quot;<b class="file">Makefile.in</b>&quot;.</p></dd>
          614  +<dt>&quot;<b class="file">devdoc</b>&quot;</dt>
          615  +<dd><p>This directories contains the doctools sources for the global
          616  +documentation, like this document and its sibling guides.</p></dd>
          617  +<dt>&quot;<b class="file">embedded</b>&quot;</dt>
          618  +<dd><p>This directory contains the entire documentation formatted for
          619  +<i class="term"><a href="../../../index.html#html">HTML</a></i> and styled to properly mix into the web site generated by
          620  +fossil for the repository.</p>
          621  +<p>This is the documentation accessible from the Tcllib home
          622  +directory, represented in the repository as &quot;<b class="file">embedded/index.md</b>&quot;.</p></dd>
          623  +<dt>&quot;<b class="file">idoc</b>&quot;</dt>
          624  +<dd><p>This directory contains the entire documentation formatted for
          625  +<i class="term"><a href="../../../index.html#nroff">nroff</a></i> and <i class="term"><a href="../../../index.html#html">HTML</a></i>, the latter without any styling.
          626  +This is the documentation which will be installed.</p></dd>
          627  +<dt>&quot;<b class="file">support</b>&quot;</dt>
          628  +<dd><p>This directory contains the sources of internal packages and utilities
          629  +used in the implementation of the &quot;<b class="file">installer.tcl</b>&quot; and
          630  +&quot;<b class="file">sak.tcl</b>&quot; scripts/tools.</p></dd>
          631  +</dl>
          632  +</div>
          633  +<div id="subsection10" class="doctools_subsection"><h3><a name="subsection10">Top Files</a></h3>
          634  +<dl class="doctools_definitions">
          635  +<dt>&quot;<b class="file">aclocal.m4</b>&quot;</dt>
          636  +<dd></dd>
          637  +<dt>&quot;<b class="file">configure</b>&quot;</dt>
          638  +<dd></dd>
          639  +<dt>&quot;<b class="file">configure.in</b>&quot;</dt>
          640  +<dd></dd>
          641  +<dt>&quot;<b class="file">Makefile.in</b>&quot;</dt>
          642  +<dd><p>These four files comprise the Unix build system layered on top of the
          643  +&quot;<b class="file">installer.tcl</b>&quot; script.</p></dd>
          644  +<dt>&quot;<b class="file">installer.tcl</b>&quot;</dt>
          645  +<dd><p>The Tcl-based installation script/tool.</p></dd>
          646  +<dt>&quot;<b class="file">project.shed</b>&quot;</dt>
          647  +<dd><p>Configuration file for <i class="term">Sean Wood</i>'s <b class="syscmd"><a href="../modules/practcl/practcl.html">PracTcl</a></b>
          648  +buildsystem.</p></dd>
          649  +<dt>&quot;<b class="file">sak.tcl</b>&quot;</dt>
          650  +<dd><p>This is the main tool for developers and release managers, the
          651  +<i class="term">Swiss Army Knife</i> of management operations on the collection.</p></dd>
          652  +<dt>&quot;<b class="file">ChangeLog</b>&quot;</dt>
          653  +<dd><p>The log of changes to the global support, when the sources were held
          654  +in <i class="term"><a href="../../../index.html#cvs">CVS</a></i>. Not relevant any longer with the switch to the
          655  +<i class="term">fossil</i> SCM.</p></dd>
          656  +<dt>&quot;<b class="file">license.terms</b>&quot;</dt>
          657  +<dd><p>The license in plain ASCII. See also <i class="term"><a href="tcllib_license.html">Tcllib - License</a></i> for the
          658  +nicely formatted form. The text is identical.</p></dd>
          659  +<dt>&quot;<b class="file">README.md</b>&quot;</dt>
          660  +<dd></dd>
          661  +<dt>&quot;<b class="file">.github/CONTRIBUTING.md</b>&quot;</dt>
          662  +<dd></dd>
          663  +<dt>&quot;<b class="file">.github/ISSUE_TEMPLATE.md</b>&quot;</dt>
          664  +<dd></dd>
          665  +<dt>&quot;<b class="file">.github/PULL_REQUEST_TEMPLATE.md</b>&quot;</dt>
          666  +<dd><p>These markdown-formatted documents are used and shown by the github
          667  +mirror of these sources, pointing people back to the official location
          668  +and issue trackers.</p></dd>
          669  +<dt>&quot;<b class="file">DESCRIPTION.txt</b>&quot;</dt>
          670  +<dd></dd>
          671  +<dt>&quot;<b class="file">STATUS</b>&quot;</dt>
          672  +<dd></dd>
          673  +<dt>&quot;<b class="file">tcllib.spec</b>&quot;</dt>
          674  +<dd></dd>
          675  +<dt>&quot;<b class="file">tcllib.tap</b>&quot;</dt>
          676  +<dd></dd>
          677  +<dt>&quot;<b class="file">tcllib.yml</b>&quot;</dt>
          678  +<dd><p>????</p></dd>
          679  +</dl>
          680  +</div>
          681  +<div id="subsection11" class="doctools_subsection"><h3><a name="subsection11">File Types</a></h3>
          682  +<p>The most common file types, by file extension, are:</p>
          683  +<dl class="doctools_definitions">
          684  +<dt>&quot;<b class="file">.tcl</b>&quot;</dt>
          685  +<dd><p>Tcl code for a package, application, or example.</p></dd>
          686  +<dt>&quot;<b class="file">.man</b>&quot;</dt>
          687  +<dd><p>Doctools-formatted documentation, usually for a package.</p></dd>
          688  +<dt>&quot;<b class="file">.test</b>&quot;</dt>
          689  +<dd><p>Test suite for a package, or part of.
          690  +Based on <b class="package">tcltest</b>.</p></dd>
          691  +<dt>&quot;<b class="file">.bench</b>&quot;</dt>
          692  +<dd><p>Performance benchmarks for a package, or part of.
          693  +Based on &quot;<b class="file">modules/bench</b>&quot;.</p></dd>
          694  +<dt>&quot;<b class="file">.pcx</b>&quot;</dt>
          695  +<dd><p>Syntax rules for <i class="term">TclDevKit</i>'s <b class="syscmd">tclchecker</b>. Using these
          696  +rules allows the checker to validate the use of commands of a Tcllib
          697  +package <b class="package">foo</b> without having to scan the &quot;<b class="file">.tcl</b>&quot; files
          698  +implementing it.</p></dd>
          699  +</dl>
          700  +</div>
          701  +</div>
          702  +<div id="section5" class="doctools_section"><h2><a name="section5">Testsuite Tooling</a></h2>
          703  +<p>Testsuites in Tcllib are based on Tcl's standard test package
          704  +<b class="package">tcltest</b>, plus utilities found in the directory
          705  +&quot;<b class="file">modules/devtools</b>&quot;</p>
          706  +<p>Tcllib developers invoke the suites through the
          707  +<b class="cmd">test run</b> method of the &quot;<b class="file">sak.tcl</b>&quot; tool, with other methods
          708  +of <b class="cmd"><a href="../../../index.html#test">test</a></b> providing management operations, for example setting a
          709  +list of standard Tcl shells to use.</p>
          710  +<div id="subsection12" class="doctools_subsection"><h3><a name="subsection12">Invoke the testsuites of a specific module</a></h3>
          711  +<p>Invoke either</p>
          712  +<pre class="doctools_example">  ./sak.tcl test run foo </pre>
          713  +<p>or</p>
          714  +<pre class="doctools_example">  ./sak.tcl test run modules/foo </pre>
          715  +<p>to invoke the testsuites found in a specific module &quot;<b class="file">foo</b>&quot;.</p>
          716  +</div>
          717  +<div id="subsection13" class="doctools_subsection"><h3><a name="subsection13">Invoke the testsuites of all modules</a></h3>
          718  +<p>Invoke the tool without a module name, i.e.</p>
          719  +<pre class="doctools_example">  ./sak.tcl test run </pre>
          720  +<p>to invoke the testsuites of all modules.</p>
          721  +</div>
          722  +<div id="subsection14" class="doctools_subsection"><h3><a name="subsection14">Detailed Test Logs</a></h3>
          723  +<p>In all the previous examples the test runner will write a combination
          724  +of progress display and testsuite log to the standard output, showing
          725  +for each module only the tests that passed or failed and how many of
          726  +each in a summary at the end.</p>
          727  +<p>To get a detailed log, it is necessary to invoke the test
          728  +runner with additional options.</p>
          729  +<p>For one:</p>
          730  +<pre class="doctools_example">
          731  +   ./sak.tcl test run --log LOG foo
          732  +</pre>
          733  +<p>While this shows the same short log on the terminal as before, it also
          734  +writes a detailed log to the file &quot;<b class="file">LOG.log</b>&quot;, and excerpts to
          735  +other files (&quot;<b class="file">LOG.summary</b>&quot;, &quot;<b class="file">LOG.failures</b>&quot;, etc.).</p>
          736  +<p>For two:</p>
          737  +<pre class="doctools_example">
          738  +  ./sak.tcl test run -v foo
          739  +</pre>
          740  +<p>This writes the detailed log to the standard output, instead of the
          741  +short log.</p>
          742  +<p>Regardless of form, the detailed log contains a list of all test
          743  +cases executed, which failed, and how they failed (expected versus
          744  +actual results).</p>
          745  +</div>
          746  +<div id="subsection15" class="doctools_subsection"><h3><a name="subsection15">Shell Selection</a></h3>
          747  +<p>By default the test runner will use all the Tcl shells specified via
          748  +<b class="cmd">test add</b> to invoke the specified testsuites, if any. If no
          749  +such are specified it will fall back to the Tcl shell used to run the
          750  +tool itself.</p>
          751  +<p>Use option <b class="option">--shell</b> to explicitly specify the Tcl shell
          752  +to use, like</p>
          753  +<pre class="doctools_example">
          754  +  ./sak.tcl test run --shell /path/to/tclsh ...
          755  +</pre>
          756  +</div>
          757  +<div id="subsection16" class="doctools_subsection"><h3><a name="subsection16">Help</a></h3>
          758  +<p>Invoke the tool as</p>
          759  +<pre class="doctools_example">  ./sak.tcl help test </pre>
          760  +<p>to see the detailed help for all methods of <b class="cmd"><a href="../../../index.html#test">test</a></b>, and the
          761  +associated options.</p>
          762  +</div>
          763  +</div>
          764  +<div id="section6" class="doctools_section"><h2><a name="section6">Documentation Tooling</a></h2>
          765  +<p>The standard format used for documentation of packages and other
          766  +things in Tcllib is <i class="term"><a href="../../../index.html#doctools">doctools</a></i>.
          767  +Its supporting packages are a part of Tcllib, see the directories
          768  +&quot;<b class="file">modules/doctools</b>&quot; and &quot;<b class="file">modules/dtplite</b>&quot;. The latter is
          769  +an application package, with the actual application
          770  +&quot;<b class="file">apps/dtplite</b>&quot; a light wrapper around it.</p>
          771  +<p>Tcllib developers gain access to these through the <b class="cmd">doc</b>
          772  +method of the &quot;<b class="file">sak.tcl</b>&quot; tool, another (internal) wrapper around
          773  +the &quot;<b class="file">modules/dtplite</b>&quot; application package.</p>
          774  +<div id="subsection17" class="doctools_subsection"><h3><a name="subsection17">Generate documentation for a specific module</a></h3>
          775  +<p>Invoke either</p>
          776  +<pre class="doctools_example">  ./sak.tcl doc html foo </pre>
          777  +<p>or</p>
          778  +<pre class="doctools_example">  ./sak.tcl doc html modules/foo </pre>
          779  +<p>to generate HTML for the documentation found in the module &quot;<b class="file">foo</b>&quot;.
          780  +Instead of <b class="const">html</b> any other supported format can be used here,
          781  +of course.</p>
          782  +<p>The generated formatted documentation will be placed into a
          783  +directory &quot;<b class="file">doc</b>&quot; in the current working directory.</p>
          784  +</div>
          785  +<div id="subsection18" class="doctools_subsection"><h3><a name="subsection18">Generate documentation for all modules</a></h3>
          786  +<p>Invoke the tool without a module name, i.e.</p>
          787  +<pre class="doctools_example">  ./sak.tcl doc html </pre>
          788  +<p>to generate HTML for the documentation found in all modules.
          789  +Instead of <b class="const">html</b> any other supported format can be used here,
          790  +of course.</p>
          791  +<p>The generated formatted documentation will be placed into a
          792  +directory &quot;<b class="file">doc</b>&quot; in the current working directory.</p>
          793  +</div>
          794  +<div id="subsection19" class="doctools_subsection"><h3><a name="subsection19">Available output formats, help</a></h3>
          795  +<p>Invoke the tool as</p>
          796  +<pre class="doctools_example">  ./sak.tcl help doc </pre>
          797  +<p>to see the entire set of supported output formats which can be
          798  +generated.</p>
          799  +</div>
          800  +<div id="subsection20" class="doctools_subsection"><h3><a name="subsection20">Validation without output</a></h3>
          801  +<p>Note the special format <b class="const">validate</b>.</p>
          802  +<p>Using this value as the name of the format to generate forces
          803  +the tool to simply check that the documentation is syntactically
          804  +correct, without generating actual output.</p>
          805  +<p>Invoke it as either</p>
          806  +<pre class="doctools_example">  ./sak.tcl doc validate (modules/)foo </pre>
          807  +<p>or</p>
          808  +<pre class="doctools_example">  ./sak.tcl doc validate </pre>
          809  +<p>to either check the packages of a specific module or check all of
          810  +them.</p>
          811  +</div>
          812  +</div>
          813  +<div id="section7" class="doctools_section"><h2><a name="section7">Notes On Writing A Testsuite</a></h2>
          814  +<p>While previous sections talked about running the testsuites for a
          815  +module and the packages therein, this has no meaning if the module in
          816  +question has no testsuites at all.</p>
          817  +<p>This section gives a very basic overview on possible
          818  +methodologies for writing tests and testsuites.</p>
          819  +<p>First there are &quot;drudgery&quot; tests. Written to check absolutely
          820  +basic assumptions which should never fail.</p>
          821  +<p>For example for a command FOO taking two arguments, three tests
          822  +calling it with zero, one, and three arguments. The basic checks that
          823  +the command fails if it has not enough arguments, or too many.</p>
          824  +<p>After that come the tests checking things based on our
          825  +knowledge of the command, about its properties and assumptions. Some
          826  +examples based on the graph operations added during Google's Summer of
          827  +Code 2009 are:</p>
          828  +<ul class="doctools_itemized">
          829  +<li><p>The BellmanFord command in struct::graph::ops takes a
          830  +	<i class="arg">startnode</i> as argument, and this node should be a node of
          831  +	the graph. This equals one test case checking the behavior when the
          832  +	specified node is not a node of the graph.</p>
          833  +<p>This often gives rise to code in the implementation which
          834  +	explicitly checks the assumption and throws an understandable error,
          835  +	instead of letting the algorithm fail later in some weird
          836  +	non-deterministic way.</p>
          837  +<p>It is not always possible to do such checks. The graph argument
          838  +	for example is just a command in itself, and while we expect
          839  +	it to exhibit a certain interface, i.e. a set of sub-commands
          840  +	aka methods, we cannot check that it has them, except by
          841  +	actually trying to use them. That is done by the algorithm
          842  +	anyway, so an explicit check is just overhead we can get by
          843  +	without.</p></li>
          844  +<li><p>IIRC one of the distinguishing characteristic of either
          845  +	BellmanFord and/or Johnson is that they are able to handle
          846  +	negative weights. Whereas Dijkstra requires positive weights.</p>
          847  +<p>This induces (at least) three testcases ... Graph with all
          848  +	positive weights, all negative, and a mix of positive and
          849  +	negative weights.
          850  +	Thinking further does the algorithm handle the weight
          851  +	<b class="const">0</b> as well ? Another test case, or several, if we mix
          852  +	zero with positive and negative weights.</p></li>
          853  +<li><p>The two algorithms we are currently thinking about are about
          854  +	distances between nodes, and distance can be 'Inf'inity,
          855  +	i.e. nodes may not be connected. This means that good test
          856  +	cases are</p>
          857  +<ol class="doctools_enumerated">
          858  +	
          859  +<li><p>Strongly connected graph</p></li>
          860  +<li><p>Connected graph</p></li>
          861  +<li><p>Disconnected graph.</p></li>
          862  +</ol>
          863  +<p>At the extremes of strongly connected and disconnected
          864  +	we have the fully connected graphs and graphs without edges,
          865  +	only nodes, i.e. completely disconnected.</p></li>
          866  +<li><p>IIRC both of the algorithms take weighted arcs, and fill in a
          867  +	default if arcs are left unweighted in the input graph.</p>
          868  +<p>This also induces three test cases:</p>
          869  +<ol class="doctools_enumerated">
          870  +	
          871  +<li><p>Graph will all arcs with explicit weights.</p></li>
          872  +<li><p>Graph without weights at all.</p></li>
          873  +<li><p>Graph with mixture of weighted and unweighted graphs.</p></li>
          874  +</ol>
          875  +</li>
          876  +</ul>
          877  +<p>What was described above via examples is called
          878  +<i class="term">black-box</i> testing. Test cases are designed and written based on
          879  +the developer's knowledge of the properties of the algorithm and its
          880  +inputs, without referencing a particular implementation.</p>
          881  +<p>Going further, a complement to <i class="term">black-box</i> testing is
          882  +<i class="term">white-box</i>. For this we know the implementation of the
          883  +algorithm, we look at it and design our tests cases so that they force
          884  +the code through all possible paths in the implementation. Wherever a
          885  +decision is made we have a test case forcing a specific direction of
          886  +the decision, for all possible combinations and directions. It is easy
          887  +to get a combinatorial explosion in the number of needed test-cases.</p>
          888  +<p>In practice I often hope that the black-box tests I have made
          889  +are enough to cover all the paths, obviating the need for white-box
          890  +tests.</p>
          891  +<p>The above should be enough to make it clear that writing tests
          892  +for an algorithm takes at least as much time as coding the algorithm,
          893  +and often more time. Much more time.
          894  +See for example also <a href="http://sqlite.org/testing.html">http://sqlite.org/testing.html</a>, a writeup
          895  +on how the Sqlite database engine is tested. Another article of
          896  +interest might be <a href="https://www.researchgate.net/publication/298896236">https://www.researchgate.net/publication/298896236</a>.
          897  +While geared to a particular numerical algorithm it still shows that
          898  +even a simple-looking algorithm can lead to an incredible number of
          899  +test cases.</p>
          900  +<p>An interesting connection is to documentation. In one
          901  +direction, the properties checked with black-box testing are exactly
          902  +the properties which should be documented in the algorithm's man
          903  +page. And conversely, the documentation of the properties of an
          904  +algorithm makes a good reference to base the black-box tests on.</p>
          905  +<p>In practice test cases and documentation often get written
          906  +together, cross-influencing each other. And the actual writing of test
          907  +cases is a mix of black and white box, possibly influencing the
          908  +implementation while writing the tests. Like writing a test for a
          909  +condition like <i class="term">startnode not in input graph</i> serving as
          910  +reminder to put a check for this condition into the code.</p>
          911  +</div>
          912  +<div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>
          913  +<p>A last thing to consider when adding a new package to the collection
          914  +is installation.</p>
          915  +<p>How to <em>use</em> the &quot;<b class="file">installer.tcl</b>&quot; script is documented
          916  +in <i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i>.</p>
          917  +<p>Here we document how to extend said installer so that it may
          918  +install new package(s) and/or application(s).</p>
          919  +<p>In most cases only a single file has to be modified, the
          920  +&quot;<b class="file">support/installation/modules.tcl</b>&quot; holding one command per module
          921  +and application to install.</p>
          922  +<p>The relevant commands are:</p>
          923  +<dl class="doctools_definitions">
          924  +<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>
          925  +<dd><p>Install the packages of module <i class="arg">name</i>, found in
          926  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot;.</p>
          927  +<p>The <i class="arg">code-action</i> is responsible for installing the
          928  +packages and their index. The system currently provides</p>
          929  +<dl class="doctools_definitions">
          930  +<dt><b class="cmd">_tcl</b></dt>
          931  +<dd><p>Copy all &quot;<b class="file">.tcl</b>&quot; files found in
          932  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; into the installation.</p></dd>
          933  +<dt><b class="cmd">_tcr</b></dt>
          934  +<dd><p>As <b class="cmd">_tcl</b>, copy the &quot;<b class="file">.tcl</b>&quot; files found in
          935  +the subdirectories of &quot;<b class="file">modules/<i class="arg">name</i></b>&quot; as well.</p></dd>
          936  +<dt><b class="cmd">_tci</b></dt>
          937  +<dd><p>As <b class="cmd">_tcl</b>, and copy the &quot;<b class="file">tclIndex.tcl</b>&quot; file
          938  +as well.</p></dd>
          939  +<dt><b class="cmd">_msg</b></dt>
          940  +<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory &quot;<b class="file">msgs</b>&quot;
          941  +as well.</p></dd>
          942  +<dt><b class="cmd">_doc</b></dt>
          943  +<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory
          944  +&quot;<b class="file">mpformats</b>&quot; as well.</p></dd>
          945  +<dt><b class="cmd">_tex</b></dt>
          946  +<dd><p>As <b class="cmd">_tcl</b>, and copy &quot;<b class="file">.tex</b>&quot; files as well.</p></dd>
          947  +</dl>
          948  +<p>The <i class="arg">doc-action</i> is responsible for installing the package
          949  +documentation. The system currently provides</p>
          950  +<dl class="doctools_definitions">
          951  +<dt><b class="cmd">_null</b></dt>
          952  +<dd><p>No documentation available, do nothing.</p></dd>
          953  +<dt><b class="cmd">_man</b></dt>
          954  +<dd><p>Process the &quot;<b class="file">.man</b>&quot; files found in
          955  +&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; and install the results (nroff and/or HTML)
          956  +in the proper location, as given to the installer.</p>
          957  +<p>This is actually a fallback, normally the installer uses the
          958  +pre-made formatted documentation found under &quot;<b class="file">idoc</b>&quot;.</p></dd>
          959  +</dl>
          960  +<p>The <i class="arg">example-action</i> is responsible for installing the
          961  +examples. The system currently provides</p>
          962  +<dl class="doctools_definitions">
          963  +<dt><b class="cmd">_null</b></dt>
          964  +<dd><p>No examples available, do nothing.</p></dd>
          965  +<dt><b class="cmd">_exa</b></dt>
          966  +<dd><p>Copy the the directory &quot;<b class="file">examples/<i class="arg">name</i></b>&quot;
          967  +recursively to the install location for examples.</p></dd>
          968  +</dl></dd>
          969  +<dt><a name="2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></dt>
          970  +<dd><p>Install the application with <i class="arg">name</i>, found in &quot;<b class="file">apps</b>&quot;.</p></dd>
          971  +<dt><a name="3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></dt>
          972  +<dd><p>This command signals to the installer which of the listed modules to
          973  +<em>not</em> install. I.e. they name the deprecated modules of Tcllib.</p></dd>
          974  +</dl>
          975  +<p>If, and only if the above actions are not suitable for the new
          976  +module then a second file has to be modified,
          977  +&quot;<b class="file">support/installation/actions.tcl</b>&quot;.</p>
          978  +<p>This file contains the implementations of the available
          979  +actions, and is the place where any custom action needed to handle the
          980  +special circumstances of module has to be added.</p>
          981  +</div>
          982  +</div></body></html>

Added idoc/www/tcllib/files/devdoc/tcllib_installer.html.

            1  +<!DOCTYPE html><html><head>
            2  +<title>tcllib_install_guide - </title>
            3  +<style type="text/css"><!--
            4  +    HTML {
            5  +	background: 	#FFFFFF;
            6  +	color: 		black;
            7  +    }
            8  +    BODY {
            9  +	background: 	#FFFFFF;
           10  +	color:	 	black;
           11  +    }
           12  +    DIV.doctools {
           13  +	margin-left:	10%;
           14  +	margin-right:	10%;
           15  +    }
           16  +    DIV.doctools H1,DIV.doctools H2 {
           17  +	margin-left:	-5%;
           18  +    }
           19  +    H1, H2, H3, H4 {
           20  +	margin-top: 	1em;
           21  +	font-family:	sans-serif;
           22  +	font-size:	large;
           23  +	color:		#005A9C;
           24  +	background: 	transparent;
           25  +	text-align:		left;
           26  +    }
           27  +    H1.doctools_title {
           28  +	text-align: center;
           29  +    }
           30  +    UL,OL {
           31  +	margin-right: 0em;
           32  +	margin-top: 3pt;
           33  +	margin-bottom: 3pt;
           34  +    }
           35  +    UL LI {
           36  +	list-style: disc;
           37  +    }
           38  +    OL LI {
           39  +	list-style: decimal;
           40  +    }
           41  +    DT {
           42  +	padding-top: 	1ex;
           43  +    }
           44  +    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
           45  +	font:		normal 12pt/14pt sans-serif;
           46  +	list-style:	none;
           47  +    }
           48  +    LI.doctools_section, LI.doctools_subsection {
           49  +	list-style: 	none;
           50  +	margin-left: 	0em;
           51  +	text-indent:	0em;
           52  +	padding: 	0em;
           53  +    }
           54  +    PRE {
           55  +	display: 	block;
           56  +	font-family:	monospace;
           57  +	white-space:	pre;
           58  +	margin:		0%;
           59  +	padding-top:	0.5ex;
           60  +	padding-bottom:	0.5ex;
           61  +	padding-left:	1ex;
           62  +	padding-right:	1ex;
           63  +	width:		100%;
           64  +    }
           65  +    PRE.doctools_example {
           66  +	color: 		black;
           67  +	background: 	#f5dcb3;
           68  +	border:		1px solid black;
           69  +    }
           70  +    UL.doctools_requirements LI, UL.doctools_syntax LI {
           71  +	list-style: 	none;
           72  +	margin-left: 	0em;
           73  +	text-indent:	0em;
           74  +	padding:	0em;
           75  +    }
           76  +    DIV.doctools_synopsis {
           77  +	color: 		black;
           78  +	background: 	#80ffff;
           79  +	border:		1px solid black;
           80  +	font-family:	serif;
           81  +	margin-top: 	1em;
           82  +	margin-bottom: 	1em;
           83  +    }
           84  +    UL.doctools_syntax {
           85  +	margin-top: 	1em;
           86  +	border-top:	1px solid black;
           87  +    }
           88  +    UL.doctools_requirements {
           89  +	margin-bottom: 	1em;
           90  +	border-bottom:	1px solid black;
           91  +    }
           92  +--></style>
           93  +</head>
           94  +<!-- Generated from file 'tcllib_installer.man' by tcllib/doctools with format 'html'
           95  +   -->
           96  +<!-- tcllib_install_guide.n
           97  +   -->
           98  +<body><hr> [
           99  +   <a href="../../../../../../../home">Tcllib Home</a>
          100  +&#124; <a href="../../../toc.html">Main Table Of Contents</a>
          101  +&#124; <a href="../../toc.html">Table Of Contents</a>
          102  +&#124; <a href="../../../index.html">Keyword Index</a>
          103  +&#124; <a href="../../../toc0.html">Categories</a>
          104  +&#124; <a href="../../../toc1.html">Modules</a>
          105  +&#124; <a href="../../../toc2.html">Applications</a>
          106  + ] <hr>
          107  +<div class="doctools">
          108  +<h1 class="doctools_title">tcllib_install_guide(n) 1 tcllib &quot;&quot;</h1>
          109  +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
          110  +<p>tcllib_install_guide - Tcllib - The Installer's Guide</p>
          111  +</div>
          112  +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
          113  +<ul class="doctools_toc">
          114  +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
          115  +<li class="doctools_section"><a href="#section1">Description</a></li>
          116  +<li class="doctools_section"><a href="#section2">Requisites</a>
          117  +<ul>
          118  +<li class="doctools_subsection"><a href="#subsection1">Tcl</a></li>
          119  +<li class="doctools_subsection"><a href="#subsection2">Critcl</a></li>
          120  +</ul>
          121  +</li>
          122  +<li class="doctools_section"><a href="#section3">Build &amp; Installation Instructions</a>
          123  +<ul>
          124  +<li class="doctools_subsection"><a href="#subsection3">Installing on Unix</a></li>
          125  +<li class="doctools_subsection"><a href="#subsection4">Installing on Windows</a></li>
          126  +<li class="doctools_subsection"><a href="#subsection5">Critcl &amp; Accelerators</a></li>
          127  +<li class="doctools_subsection"><a href="#subsection6">Tooling</a></ul>
          128  +</li>
          129  +</ul>
          130  +</div>
          131  +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
          132  +<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
          133  +package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
          134  +packages that provide utility functions useful to a large collection
          135  +of Tcl programmers.</p>
          136  +<p>The audience of this document is anyone wishing to build and install
          137  +the packages found in Tcllib, for either themselves, or others.</p>
          138  +<p>For developers intending to work on the packages themselves we
          139  +additionally provide</p>
          140  +<ol class="doctools_enumerated">
          141  +<li><p><i class="term"><a href="tcllib_devguide.html">Tcllib - The Developer's Guide</a></i>.</p></li>
          142  +</ol>
          143  +<p>Please read <i class="term"><a href="tcllib_sources.html">Tcllib - How To Get The Sources</a></i> first, if that
          144  +was not done already. Here we assume that the sources are already
          145  +available in a directory of your choice.</p>
          146  +</div>
          147  +<div id="section2" class="doctools_section"><h2><a name="section2">Requisites</a></h2>
          148  +<p>Before Tcllib can be build and used a number of requisites must be installed.
          149  +These are:</p>
          150  +<ol class="doctools_enumerated">
          151  +<li><p>The scripting language Tcl.
          152  +       For details see <span class="sectref"><a href="#subsection1">Tcl</a></span>.</p></li>
          153  +<li><p>Optionally, the <b class="package">critcl</b> package (C embedding) for <b class="syscmd"><a href="../../../index.html#tcl">Tcl</a></b>.
          154  +       For details see <b class="sectref">CriTcl</b>.</p></li>
          155  +</ol>
          156  +<p>This list assumes that the machine where Tcllib is to be installed is
          157  +essentially clean. Of course, if parts of the dependencies listed
          158  +below are already installed the associated steps can be skipped. It is