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 Unified Diffs Ignore Whitespace Patch

Changes to .github/CONTRIBUTING.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Hello.

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where development takes place.

We are not tracking issues entered here.  With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl.tk/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl.tk/tcllib/reportlist)
instead.

Thank you for your consideration.
|



|

|



|

|



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Hello. __Attention please__

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where Tcllib development takes place.

We are __not tracking issues entered here__. With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl-lang.org/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
instead.

Thank you for your consideration.

Changes to .github/ISSUE_TEMPLATE.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Hello.

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where development takes place.

We are not tracking issues entered here.  With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl.tk/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl.tk/tcllib/reportlist)
instead.

Thank you for your consideration.
|



|

|



|

|



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Hello. __Attention please__

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where Tcllib development takes place.

We are __not tracking issues entered here__. With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl-lang.org/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
instead.

Thank you for your consideration.

Changes to .github/PULL_REQUEST_TEMPLATE.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Hello.

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where development takes place.

We are not tracking issues entered here.  With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl.tk/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl.tk/tcllib/reportlist)
instead.

Thank you for your consideration.
|



|

|



|

|



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Hello. __Attention please__

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where Tcllib development takes place.

We are __not tracking issues entered here__. With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl-lang.org/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
instead.

Thank you for your consideration.

Deleted INSTALL.txt.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
How to install Tcllib
=====================

Introduction
------------

The tcllib distribution, whether a snapshot directly from CVS, or
officially released, offers a single method for installing tcllib,
based on Tcl itself.

This is based on the assumption that for tcllib to be of use Tcl has
to be present, and therefore can be used.

This single method however can be used in a variety of ways.

0	For an unwrapped (= directory) distribution or CVS snapshot

	a.	either call the application 'installer.tcl' directly,
	b	or use

			% configure ; make install

		The latter is provided for people which are used to
		this method and more comfortable with it. In end this
		boils down into a call of 'installer.tcl' too.

1.	A starpack distribution (window-only) is a self-extracting
	installer which internally uses the aforementioned installer.

2.	A starkit distribution is very much like a starpack, but
	required an external interpreyter to run. This can be any tcl
	interpreter which has all the packages to support starkits
	(tclvfs, memchan, trf).

3.	A distribution in a tarball has to be unpacked first, then any
	of the methods described in (0) can be used.


Usage of the installer
----------------------

The installer selects automatically either a gui based mode, or a
command line based mode. If the package Tk is present and can be
loaded, then the GUI mode is entered, else the system falls back to
the command line.

Note that it is possible to specify options on the command line even
if the installer ultimatively selects a gui mode. In that case the
hardwired defaults and the options determine the data presented to the
user for editing.

Command line help can be asked for by using the option -help when
running the installer (3) or the distribution itself in the case of
(1) or (2).

The installer will select a number of defaults for the locations of
packages, examples, and documentation, and also the format of the
documentation. The user can overide these defaults in the GUI, or by
specifying additional options.

The defaults depend on the platform detected (unix/windows) and the
executable used to run the installer. In the case of a starpack
distribution (1) this means that _no defaults_ are possible for the
various locations as the executable is part of the distribution and
has no knowledge of its environment.

In all other cases the intepreter executable is outside of the
distribution, which means that its location can be used to determine
sensible defaults.

Notes
-----

The installer will overwrite an existing installation of tcllib 1.6
without asking back after the initial confirmation is given. And if
the user chooses the same directory as for tcllib 1.4, or 1.3, etc.
then the installer will overwrite that too.
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
























































































































































Deleted README.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
RCS: @(#) $Id: README,v 1.9 2007/08/30 17:24:13 andreas_kupries Exp $

Welcome to the Tcllib, the Tcl Standard Library.  This package is
intended to be a collection of Tcl packages that provide utility
functions useful to a large collection of Tcl programmers.

The home web site for this code is http://core.tcl.tk/tcllib/ .
At this web site, you will find mailing lists, web forums, databases
for bug reports and feature requests, the CVS repository (browsable on
the web, or read-only accessible via CVS ), and more.

The structure of the tcllib source hierarchy is:

tcllib
 +- modules
     +- <module1>
     +- <module2>
     +- ...


The install hierarchy is:

.../lib/tcllib
        +- <module1>
        +- <module2>
        +- ...

There are some base requirements that a module must meet before it
will be added to tcllib:

* the module must be a proper Tcl package
* the module must use a namespace for its commands and variables
* the name of the package must be the same as the name of the
  namespace
* the module must reside in a subdirectory of the modules directory in
  the source hierarchy, and that subdirectory must have the same name
  as the package and namespace
* the module must be released under the BSD License, the terms of
  which can be found in the toplevel tcllib source directory in the file
  license.terms
* the module should have both documentation ([*]) and a test suite
  (in the form of a group of *.test files in the module directory).

  [*] Possible forms: doctools, TMML/XML, nroff (man), or HTML.
      The first format is the most preferred as it can be processed with
      tools provided by tcllib itself (See module doctools). The first
      two are preferred in general as they are semantic markup and thus
      easier to convert into other formats.

* the module must have either documentation or a test suite.  It can
  not have neither.
* the module should adhere to Tcl coding standards

When adding a module to tcllib, be sure to add it to the files listed below.

* installed_modules.tcl

  contains a table listing all modules to be installed, modules
  excluded, and names the actions to be taken during installation
  of each module. Add a line to this table naming your module and
  its actions.

  Three actions have to be specified, for the package itself, its
  documentation, and the examples demonstrating it.

  The _null action can be used everywhere and signals that there is
  nothing to do. Although it is possible to use it for the package
  action it does make no sense there, as that means that no package
  code is installed.

  Other package actions are _tcl, _tci, and _text. The first causes
  the installer to copy all .tcl files from the source directory for
  the module into the appropriate module directory. _tci does all that
  and also expects a tclIndex file to copy. _tex is like _tcl, however
  it also copies all .tex files found in the source directory for the
  module.

  There is currently only one true documentation action. This action
  is _doc. It converts all documentation in doctools format into the
  format chosen by the user for installation and copies the result
  into the appropriate directory.

  There is currently one true action for examples, _exa. It copies all
  files in the source directory for examples into the directory chosen
  by the user as destination for examples.

Each module source directory should have no subdirectories (other than
the CVS directory), and should contain the following files:

* source code		*.tcl
* package index		pkgIndex.tcl
* tests			*.test
* documentation		*.man, *.n, *.xml

If you do not follow this directory structure, the tcllib Makefile
will fail to locate the files from the new module.
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<






























































































































































































Changes to README.md.


1
2
3

4
5
6
7
8
9
10
11
12
13

14
15
16
17

































Hello.


If you are reading this then you are very likely at the github
__mirror__ of the Tcllib sources.

This means that the
[official location of the sources](https://core.tcl.tk/tcllib)
is somewhere else, just follow the link.

This is also where our issue tracking is done.  We are not tracking
issues at github.  With the exeception of the maintainer of the
mirroring setup nobody will even see issues created at github.


Please use the
[official ticket tracker](https://core.tcl.tk/tcllib/reportlist)
instead.
































>

<
<
>
|
<

<
<
<
<
<
|
|
>


|

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2


3
4

5





6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# Attention



:warning: 
This repository is mirrored to [github](https://github.com/tcltk/tcllib).







We are __not tracking issues at github__.  With the exeception of the
maintainer of the mirroring setup nobody will even see issues created
at github.

Please use the
[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
instead.

# Welcome

Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) Tcl packages
that provide utility functions useful to a large collection of Tcl
programmers.

At our [home site](http://core.tcl-lang.org/tcllib) you will find the
official fossil repository used to manage our sources, together with
the bug tracker. This is also the main location for releases to
download from.

We have a
[secondary download location](https://sourceforge.net/projects/tcllib/files)
where the Tcllib sources were hosted in the past. SourceForge is also
where our [mailing lists](https://sourceforge.net/p/tcllib/mailman)
are (still) hosted.

Another location to find these sources at is the
[github mirror](https://github.com/tcltk/tcllib).

Please note the :warning: at the top.

# Guides To Tcllib

   * [Tcl Community - Kind Communication](embedded/www/tcllib/files/devdoc/tcl_community_communication.html)
   * [License](embedded/www/tcllib/files/devdoc/tcllib_license.html)
   * [How To Get The Sources](embedded/www/tcllib/files/devdoc/tcllib_sources.html)
   * [How To Build And Install Tcllib](embedded/www/tcllib/files/devdoc/tcllib_installer.html)
   * [The Developer's Guide](embedded/www/tcllib/files/devdoc/tcllib_devguide.html)
   * [The Release Manager's Guide](embedded/www/tcllib/files/devdoc/tcllib_releasemgr.html)

Deleted README.releasemgr.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
RCS: @(#) $Id: README.releasemgr,v 1.2 2009/07/10 16:33:31 andreas_kupries Exp $

Welcome to the tcllib, the Tcl Standard Library.
================================================

Introduction
------------

This README is intended to be a guide to the tools available to a

	Release manager

working on the creation of a release of Tcllib.

Audience
--------

The intended audience is the release manager of Tcllib, his deputies,
and anybody else interested in the task.

Basics
------

< Flesh this out >

	sak.tcl validate
	sak.tcl test run
	sak.tcl review
	sak.tcl readme
	sak.tcl localdoc
	sak.tcl release (change to include rpmspec+gentip55+yml)

< Tasks, and how to perform them >

  	 Making a release (candidate) branch.
	 Readying the release in the branch.
	 Make the release official, merging the branch back.

Uploading and releasing files
--------------------------------------------

(1) Create a proper fossil event for the release, via

      http://core.tcl.tk/tcllib/eventedit

    See existing events (*) for a template

    (Ad *) http://core.tcl.tk/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817

(2) Update the following web locations

    (a) Home page:	http://core.tcl.tk/tcllib/home
    (b) Downloads:	http://core.tcl.tk/tcllib/wiki?name=Downloads 
    (c) Past Releases:	http://core.tcl.tk/tcllib/wiki?name=Past+Releases

    Admin access to the fossil repository required

    (d) http://www.tcl.tk/home/release.txt
    (e) http://www.tcl.tk/software/tcllib/*.tml

    ssh access to tcl.activestate.com
    aka        	  www.tcl.tk
    required.

    (f) http://wiki.tcl.tk/1246
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
































































































































Changes to apps/dtplite.man.

439
440
441
442
443
444
445
446
447
They are left in place, i.e. not deleted, to serve as demonstrations
of doctoc and docidx markup.

[list_end]

[vset CATEGORY doctools]
[include ../modules/doctools2base/include/feedback.inc]
[manpage_end]






|

439
440
441
442
443
444
445
446
447
They are left in place, i.e. not deleted, to serve as demonstrations
of doctoc and docidx markup.

[list_end]

[vset CATEGORY doctools]
[include ../modules/common-text/feedback.inc]
[manpage_end]

Changes to apps/nns.man.

135
136
137
138
139
140
141
142
143
If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the name service to talk to is listening on for
requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/doctools2base/include/feedback.inc]
[manpage_end]






|

135
136
137
138
139
140
141
142
143
If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the name service to talk to is listening on for
requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/common-text/feedback.inc]
[manpage_end]

Changes to apps/nnsd.man.

83
84
85
86
87
88
89
90
91
If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the server has to listen on for requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/doctools2base/include/feedback.inc]
[manpage_end]






|

83
84
85
86
87
88
89
90
91
If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the server has to listen on for requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/common-text/feedback.inc]
[manpage_end]

Changes to apps/nnslog.man.

85
86
87
88
89
90
91
92
93
If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the name service to talk to is listening on for
requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/doctools2base/include/feedback.inc]
[manpage_end]






|

85
86
87
88
89
90
91
92
93
If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the name service to talk to is listening on for
requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/common-text/feedback.inc]
[manpage_end]

Changes to apps/page.man.

459
460
461
462
463
464
465
466
467
[para]

The contents of both environment variables and registry entries are
interpreted as a list of paths, with the elements separated by either
colon (Unix), or semicolon (Windows).

[vset CATEGORY page]
[include ../modules/doctools2base/include/feedback.inc]
[manpage_end]






|

459
460
461
462
463
464
465
466
467
[para]

The contents of both environment variables and registry entries are
interpreted as a list of paths, with the elements separated by either
colon (Unix), or semicolon (Windows).

[vset CATEGORY page]
[include ../modules/common-text/feedback.inc]
[manpage_end]

Changes to apps/tcldocstrip.man.

189
190
191
192
193
194
195
196
197
Preambles, when active, are written before the actual content of a
generated file. In the same manner postambles are, when active,
written after the actual content of a generated file.

[list_end]

[vset CATEGORY docstrip]
[include ../modules/doctools2base/include/feedback.inc]
[manpage_end]






|

189
190
191
192
193
194
195
196
197
Preambles, when active, are written before the actual content of a
generated file. In the same manner postambles are, when active,
written after the actual content of a generated file.

[list_end]

[vset CATEGORY docstrip]
[include ../modules/common-text/feedback.inc]
[manpage_end]

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

Deleted devdoc/cvs.branches.fig.

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






























































Deleted devdoc/devguide.html.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
<!- Guide for Tcllib developers -->

<h1>Guide for Tcllib developers.
</h1>
<hr>

<h2>CVS Repository
</h2>
<table><tr><td valign=top>
      <!-- The local source of this image is
		tcllib/devel/cvs.branches.*
	-->
      <img src="http://sourceforge.net/dbimage.php?id=2221">
</td><td valign=top><p>

The CVS repository for Tcllib contains two main branches, the HEAD for
development, and RELEASES as the staging area for official
releases. At RELEASES the minor branches containing the various
official releases are anchored at.
</p></td></tr></table>

<p>All the branches are of interest to the developers for
      Tcllib. Ongoing development happens in HEAD, which can be
      unstable or may not work at all. Whenever a developer considers
      a piece of code, or module, he is responsible for as
      sufficiently stable she has to perform an internal release which
      merges this part from HEAD into RELEASES. Tools to help with
      this will be provided.
</p>

<p>The branches for the official releases of tcllib are of interest to
      a developer because it is expected that fixes for important bugs
      not only go into the HEAD branch but also into the release
      branches for the release they were found in and all releases
      following that one. This is to allow the release manager to
      create patch releases of existing releases distributing important
      bugfixes as well.
</p>

<p>Version numbers for modules are handled as described below. This
      way of handling them was chosen so that the modules in the
      development branch always uses version numbers different from
      the version numbers in the official releases made so far.
</p>
<ul>
<li>Whenever an internal release of a module FOO is done, the
	developer performing this internal release has to increment
	the version number of the module <b>after</b> the release was
	executed.
</ul>
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<


































































































Deleted devdoc/installation.txt.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
Tcllib installation directory layout
====================================

This document describes the possible layouts for an installed tcllib,
discusses their pro and contra and makes a choice for Tcllib 1.4. A
roadmap of changes in the future is made available as appendix.

[L1/D] Deep layout
------------------

	This is the layout of Tcllib 1.3 (and versions before that).

	A single directory tcllib<version> is created, and all
	subdirectories of the 'modules' subdirectory in the
	distribution is copied into it. This is restricted at large to
	*.tcl files, with exception made for some modules with special
	needs.

	Pro:
	Contra:
		Makes the handling of the various package indices,
		well, not difficult, but uncomfortable.


[L2/Fa] Flat layout 1
---------------------

	A directory is created for each module of tcllib.

	Pro:
		Handling of package indices is easier than for L1/D, a
		toplevel index file with all its problems is not
		required anymore.

	Contra:
		Directories should be versioned to avoid conflicts
		between multiple releases. modules have no
		version. This can be faked for modules containing one
		package, but not for the modules with more.


[L2/Fb] Flat layout 2
---------------------

	A directory is created for each package in tcllib.

	Pro
		Handling of package indices is easy, one per package.

	Contra:
		Modules containing more than one package are difficult
		to handle. The system has to split them into the
		individual packages. This rendered very difficult
		because of shared package index files.
	
		This can be solved by moving tcllib (back) towards of
		one package per module. When that goal is reached
		L2/Fa and L2/Fb become the same, and the contra for
		L2/Fa vanishes too as an exact version number can be
		associated with each directory.

Chosen layout for Tcllib 1.4
----------------------------

	L2/D

	Despite the problems with package indices the contras against
	the flat structures are too strong at this point in
	time. Automatic solutions are not really possible, or require
	a very high effort.

Roadmap
-------
	Change the module directories of tcllib to contain exactly one
	package per directory, with appropriate index (and meta data).

	This not only makes sense for easier handling of installation
	and package indices, but also in the greater context of
	wrapping code for deployment.


-----------------------------------
This document is in the public domain.

			Andreas Kupries	<[email protected]>
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<








































































































































































Added devdoc/parts/b_critcl.inc.












































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
While the majority of Tcllib consists of packages written in pure Tcl
a number of packages also have [term accelerators] associated with them.

These are [syscmd critcl]-based C packages whose use will boost the
performance of the packages using them.

These accelerators are optional, and they are not installed by
default.

[para] To build the accelerators the normally optional dependency on
       [syscmd critcl] becomes required.

[para] To build and install Tcllib with the accelerators in a
       Unix-like environment invoke:

[example {
  ./configure
  make critcl # This builds the shared library holding
              # the accelerators
  make install
}]

[para] The underlying tool is [file sak.tcl] in the toplevel directory
of Tcllib and the command [cmd {make critcl}] is just a wrapper around

[example {
  ./sak.tcl critcl
}]

[para] Therefore in a Windows environment instead invoke

[example {
  ./sak.tcl critcl
  ./installer.tcl
}]

from within a DOS window, i.e. [syscmd cmd.exe].

Added devdoc/parts/b_tooling.inc.


























































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
The core of Tcllib's build system is the script [file installer.tcl]
found in the toplevel directory of a checkout or release.

[para] The
       [example {
         configure ; make install
       }]
       setup available to
       developers on Unix-like systems is just a wrapper around it.

       To go beyond the standard embodied in the wrapper it is
       necessary to directly invoke this script.

[para] On Windows system using it directly is the only way to invoke
       it.

[para] For basic help invoke it as

       [example {
         ./installer.tcl -help
       }]

       This will print a short list of all the available options to
       the standard output channel.

[para] The commands associated with the various [term install] targets
       in the [term Makefile.in] for Unix can be used as additional
       examples on how to use this tool as well.

[para] The installer can operate in GUI and CLI modes.

       By default it chooses the mode automatically, based on if the
       Tcl package [package Tk] can be used or not.

       The option [option -no-gui] can be used to force CLI mode.

[para] Note that it is possible to specify options on the command line
       even if the installer ultimatively selects GUI mode. In that
       case the hardwired defaults and the options determine the data
       presented to the user for editing.

[para] The installer will select a number of defaults for the
       locations of packages, examples, and documentation, and also
       the format of the documentation. The user can overide these
       defaults in the GUI, or by specifying additional options.

       The defaults depend on the platform detected (Unix/Windows) and
       on the [syscmd tclsh] executable used to run the installer.

[para][emph Options]

[list_begin options]
[opt_def -help]

Show the list of options explained here on the standard output channel
and exit.

[opt_def +excluded]

Include deprecated packages in the installation.

[opt_def -no-gui]

Force command line operation of the installer

[opt_def -no-wait]

In CLI mode the installer will by default ask the user to confirm that
the chosen configuration (destination paths, things to install) is
correct before performing any action. Using this option causes the
installer to skip this query and immediately jump to installation.

[opt_def -app-path [arg path]]
[opt_def -example-path [arg path]]
[opt_def -html-path [arg path]]
[opt_def -nroff-path [arg path]]
[opt_def -pkg-path [arg path]]

Declare the destination paths for the applications, examples, html
documentation, nroff manpages, and packages. The defaults are derived
from the location of the [syscmd tclsh] used to run the installer.

[opt_def -dry-run]
[opt_def -simulate]

Run the installer without modifying the destination directories.

[opt_def -apps]
[opt_def -no-apps]
[opt_def -examples]
[opt_def -no-examples]
[opt_def -pkgs]
[opt_def -no-pkgs]
[opt_def -html]
[opt_def -no-html]
[opt_def -nroff]
[opt_def -no-nroff]

(De)activate the installation of applications, examples, packages,
html documentation, and nroff manpages.

[para] Applications, examples, and packages are installed by default.

[para] On Windows the html documentation is installed by default.

[para] On Unix the nroff manpages are installed by default.

[list_end]

Added devdoc/parts/b_unix.inc.












































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
For [term Unix]-like environments Tcllib comes with the standard set
of files to make

[example {
  ./configure
  make install
}]

a suitable way of installing it.

This is a standard non-interactive install automatically figuring out
where to place everything, i.e. packages, applications, and the
manpages.

[para] To get a graphical installer invoke

[example {
  ./installer.tcl
}]

instead.

Added devdoc/parts/b_windows.inc.




































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
In a Windows environment we have the [cmd installer.tcl] script to
perform installation.

[para] If the desired [syscmd tclsh] is associated [file .tcl] files
       then double-clicking / opening the [cmd installer.tcl] is
       enough to invoke it in graphical mode.

       This assumes that [term Tk] is installed and available as well.

[para] Without [term Tk] the only way to invoke the installer are to
       open a DOS window, i.e. [syscmd cmd.exe], and then to invoke
      
[example {
  ./installer.tcl
}]

inside it.

Added devdoc/parts/d_bf_branchcmds.inc.


























































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
In the hope of engendering good work practices now a few example
operations which will come up with branches, and their associated
fossil command (sequences).

[list_begin definitions]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph Awareness]]
[include d_op_aware.inc]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph {Clean checkouts}]]
[include d_op_clean.inc]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph {Starting a new branch}]]
[include d_op_branch_open.inc]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph {Merging a branch into trunk}]]
[include d_op_branch_close.inc]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph {Merging from trunk}]]
[include d_op_branch_import.inc]

[list_end]

Added devdoc/parts/d_bf_branches.inc.










































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
Given the constraints placed on the [term trunk] branch of the
repository it is (strongly) recommended to perform any development
going beyond trivial changes on a non-trunk branch.

[para] Outside of the trunk developers are allowed to commit
       intermediate broken states of their work.

       Only at the end of a development cycle, when the relevant
       branch is considered ready for merging, will it be necessary to
       perform full the set of validations ensuring that the merge to
       come will create a good commit on trunk.

[para] Note that while a review from a second developer is not a
       required condition for merging a branch it is recommended to
       seek out such an independent opinion as a means of
       cross-checking the work.

[para] It also recommended to give any new branch a name which aids in
       determining additional details about it. Examples of good
       things to stick into a branch name would be

[list_begin itemized]
[item]	Developer (nick)name
[item]	Ticket hash/reference
[item]	One or two keywords applicable to the work
[item]	...
[list_end]

[para] Further, while most development branches are likely quite
       short-lived, no prohibitions exist against making longer-lived
       branches.

       Creators should however be mindful that the longer such a
       branch exists without merges the more divergent they will tend
       to be, with an associated increase in the effort which will
       have to be spent on either merging from and merging to trunk.

Added devdoc/parts/d_bf_dependencies.inc.


























































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
Regarding packages and dependencies between them Tcllib occupies a
middle position between two extremes:

[list_begin enumerated]

[enum] On one side a strongly interdependent set of packages, usually
       by a single author, for a single project. Looking at my
       (Andreas Kupries) own work examples of such are
       [uri https://core.tcl.tk/akupries/marpa/index Marpa],
       [uri https://core.tcl.tk/akupries/crimp/index CRIMP],
       [uri https://core.tcl.tk/akupries/kinetcl/index Kinetcl], etc.

[para] For every change the author of the project handles all the
       modifications cascading from any incompatibilities it
       introduced to the system.

[enum] On the other side, the world of semi-independent projects by
       many different authors where authors know what packages their
       own creations depend on, yet usually do not know who else
       depends on them.

[para] The best thing an author making an (incompatible) change to
       their project can do is to for one announce such changes in
       some way, and for two use versioning to distinguish the code
       before and after the change.

[para] The world is then responsible for adapting, be it by updating
       their own projects to the new version, or by sticking to the
       old.

[list_end]

As mentioned already, Tcllib lives in the middle of that.

[para] While we as maintainers cannot be aware of all users of
       Tcllib's packages, and thus have to rely on the mechanisms
       touched on in point 2 above for that, the dependencies between
       the packages contained in Tcllib are a different matter.

[para] As we are collectively responsible for the usability of Tcllib
       in toto to the outside world, it behooves us to be individually
       mindful even of Tcllib packages we are not directly
       maintaining, when they depend on packages under our
       maintainership.

       This may be as simple as coordinating with the maintainers of
       the affected packages.

       It may also require us to choose how to adapt affected packages
       which do not have maintainers, i.e. modify them to use our
       changed package properly, or modify them to properly depend on
       the unchanged version of our package.

[para] Note that the above is not only a chore but an opportunity as
       well.

       Additional insight can be had by forcing ourselves to look at
       our package and the planned change(s) from an outside
       perspective, to consider the ramifications of our actions on
       others in general, and on dependent packages in particular.

Added devdoc/parts/d_bf_trunk.inc.




























































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
The management and use of branches is an important part of working
with a [term {Distributed Version Control System}] ([term DVCS]) like
[uri https://www.fossil-scm.org/ fossil].

[para] For Tcllib the main branch of the collection is
       [term trunk]. In [term git] this branch would be called
       [term master], and this is exactly the case in the
       [uri https://github.com/tcltk/tcllib/ {github mirror}] of
       Tcllib.

[para] To properly support debugging [emph {each commit}] on this
       branch [emph {has to pass the entire testsuite}] of the
       collection. Using bisection to determine when an issue appeared
       is an example of an action made easier by this constraint.

[para] This is part of our collective responsibility for the usability
       of Tcllib in toto to the outside world.

       As [term fossil] has no mechanism to enforce this condition
       this is handled on the honor system for developers and maintainers.

[para] To make the task easier Tcllib comes with a tool
       ([file sak.tcl]) providing a number of commands in
       support. These commands are explained in the following sections
       of this guide.

[para] While it is possible and allowed to commit directly to trunk
       remember the above constraint regarding the testsuite, and the
       coming notes about other possible issues with a commit.

Added devdoc/parts/d_bf_versions.inc.
























































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
In Tcllib all changes to a package have to come with an increment of
its version number. What part is incremented (patchlevel, minor, major
version) depends on the kind of change made. With multiple changes in
a commit the highest "wins".

[para] When working in a development branch the version change can be
       deferred until it is time to merge, and then has to cover all
       the changes in the branch.

[para] Below a list of the kinds of changes and their associated
       version increments:

[list_begin definitions]
[def [term {D - documentation}]] No increment
[def [term {T - testsuite}]] No increment
[def [term {B - bugfix}]] Patchlevel
[def [term {I - implementation tweak}]] Patchlevel
[def [term {P - performance tweak}]] Patchlevel
[def [term {E - backward-compatible extension}]] Minor
[def [term {API - incompatible change}]] Major
[list_end]

[para] Note that a commit containing a version increment has to
       mention the new version number in its commit message, as well
       as the kind of change which caused it.

[para] Note further that the version number of a package currently
       exists in three places. An increment has to update all of them:

[list_begin enumerated]
[enum] The package implementation.
[enum] The package index ([file pkgIndex.tcl])
[enum] The package documentation.
[list_end]

[para] The [file sak.tcl] command [cmd {validate version}] helps
       finding discrepancies between the first two.

       All the other [cmd validate] methods are also of interest to
       any developer. Invoke it with

       [example { sak.tcl help validate }]

       to see their documentation.

Added devdoc/parts/d_branchflow.inc.






































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[comment {===================================================================}]
[subsection {Package Dependencies}]
[include d_bf_dependencies.inc]

[comment {===================================================================}]
[subsection Trunk]
[include d_bf_trunk.inc]

[comment {===================================================================}]
[subsection Branches]
[include d_bf_branches.inc]

[comment {===================================================================}]
[subsection {Working with Branches}]
[include d_bf_branchcmds.inc]

[comment {===================================================================}]
[subsection {Version numbers}]
[include d_bf_versions.inc]

Added devdoc/parts/d_contrib.inc.




































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
As a contributor to Tcllib you are committing yourself to:

[list_begin enumerated]

[enum] keep the guidelines written down in
       [term {Tcl Community - Kind Communication}] in your mind.
       The main point to take away from there is
       [emph {to be kind to each other}].

[enum] Your contributions getting distributed under a BSD/MIT license.
       For the details see [term {Tcllib - License}]

[list_end]

Contributions are made by entering tickets into our tracker, providing
patches, bundles or branches of code for inclusion, or posting to the
Tcllib related mailing lists.

Added devdoc/parts/d_dirlayout.inc.










































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
[subsection {Main Directories}]

The main directories in the Tcllib toplevel directory and of interest
to a developer are:

[list_begin definitions]

[def [file modules]]

Each child directory represents one or more packages.

In the case of the latter the packages are usually related in some
way. Examples are [file base64], [file math], and [file struct], with
loose (base64) to strong (math) relations between the packages in the
directory.

[def [file apps]]

This directory contains all the installable applications, with their
documentation. Note that this directory is currently [emph not] split
into sub-directories.

[def [file examples]]

Each child directory [file foo] contains one or more example
application for the packages in [file modules/foo]. These examples are
generally not polished enough to be considered for installation.

[list_end]

[subsection {More Directories}]

[list_begin definitions]

[def [file config]]

This directory contains files supporting the Unix build system,
i.e. [file configure] and [file Makefile.in].

[def [file devdoc]]

This directories contains the doctools sources for the global
documentation, like this document and its sibling guides.

[def [file embedded]]

This directory contains the entire documentation formatted for
[term HTML] and styled to properly mix into the web site generated by
fossil for the repository.

[para] This is the documentation accessible from the Tcllib home
directory, represented in the repository as [file embedded/index.md].

[def [file idoc]]

This directory contains the entire documentation formatted for
[term nroff] and [term HTML], the latter without any styling.
This is the documentation which will be installed.

[def [file support]]

This directory contains the sources of internal packages and utilities
used in the implementation of the [file installer.tcl] and
[file sak.tcl] scripts/tools.

[list_end]

[subsection {Top Files}]

[list_begin definitions]
[def [file aclocal.m4]]
[def [file configure]]
[def [file configure.in]]
[def [file Makefile.in]]

These four files comprise the Unix build system layered on top of the
[file installer.tcl] script.

[def [file installer.tcl]]

The Tcl-based installation script/tool.

[def [file project.shed]]

Configuration file for [term {Sean Wood}]'s [syscmd PracTcl]
buildsystem.

[def [file sak.tcl]]
This is the main tool for developers and release managers, the
[term {Swiss Army Knife}] of management operations on the collection.

[def [file ChangeLog]]

The log of changes to the global support, when the sources were held
in [term CVS]. Not relevant any longer with the switch to the
[term fossil] SCM.

[def [file license.terms]]

The license in plain ASCII. See also [term {Tcllib - License}] for the
nicely formatted form. The text is identical.

[def [file README.md]]
[def [file .github/CONTRIBUTING.md]]
[def [file .github/ISSUE_TEMPLATE.md]]
[def [file .github/PULL_REQUEST_TEMPLATE.md]]

These markdown-formatted documents are used and shown by the github
mirror of these sources, pointing people back to the official location
and issue trackers.

[def [file DESCRIPTION.txt]]
[def [file STATUS]]
[def [file tcllib.spec]]
[def [file tcllib.tap]]
[def [file tcllib.yml]]

????

[list_end]

[subsection {File Types}]

The most common file types, by file extension, are:

[list_begin definitions]

[def [file .tcl]]
Tcl code for a package, application, or example.

[def [file .man]]
Doctools-formatted documentation, usually for a package.

[def [file .test]]
Test suite for a package, or part of.
Based on [package tcltest].

[def [file .bench]]
Performance benchmarks for a package, or part of.
Based on [file modules/bench].

[def [file .pcx]]
Syntax rules for [term TclDevKit]'s [syscmd tclchecker]. Using these
rules allows the checker to validate the use of commands of a Tcllib
package [package foo] without having to scan the [file .tcl] files
implementing it.

[list_end]

Added devdoc/parts/d_documentation.inc.
























































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
The standard format used for documentation of packages and other
things in Tcllib is [term doctools].

Its supporting packages are a part of Tcllib, see the directories
[file modules/doctools] and [file modules/dtplite]. The latter is
an application package, with the actual application
[file apps/dtplite] a light wrapper around it.

[para] Tcllib developers gain access to these through the [cmd doc]
method of the [file sak.tcl] tool, another (internal) wrapper around
the [file modules/dtplite] application package.

[comment {===================================================================}]
[subsection {Generate documentation for a specific module}]

Invoke either

[example {  ./sak.tcl doc html foo }]

or

[example {  ./sak.tcl doc html modules/foo }]

to generate HTML for the documentation found in the module [file foo].

Instead of [const html] any other supported format can be used here,
of course.

[para] The generated formatted documentation will be placed into a
directory [file doc] in the current working directory.

[comment {===================================================================}]
[subsection {Generate documentation for all modules}]

Invoke the tool without a module name, i.e.

[example {  ./sak.tcl doc html }]

to generate HTML for the documentation found in all modules.

Instead of [const html] any other supported format can be used here,
of course.

[para] The generated formatted documentation will be placed into a
directory [file doc] in the current working directory.

[comment {===================================================================}]
[subsection {Available output formats, help}]

Invoke the tool as

[example {  ./sak.tcl help doc }]

to see the entire set of supported output formats which can be
generated.

[comment {===================================================================}]
[subsection {Validation without output}]

Note the special format [const validate].

[para] Using this value as the name of the format to generate forces
the tool to simply check that the documentation is syntactically
correct, without generating actual output.

[para] Invoke it as either

[example {  ./sak.tcl doc validate (modules/)foo }]

or

[example {  ./sak.tcl doc validate }]

to either check the packages of a specific module or check all of
them.

Added devdoc/parts/d_installation.inc.




























































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
A last thing to consider when adding a new package to the collection
is installation.

[para] How to [emph use] the [file installer.tcl] script is documented
in [term {Tcllib - The Installer's Guide}].

[para] Here we document how to extend said installer so that it may
install new package(s) and/or application(s).

[para] In most cases only a single file has to be modified, the
[file support/installation/modules.tcl] holding one command per module
and application to install.

[para] The relevant commands are:

[list_begin definitions]

[call [cmd Module] [arg name] \
      	   [arg code-action] \
      	   [arg doc-action] \
	   [arg example-action]]

Install the packages of module [arg name], found in
[file modules/[arg name]].

[para] The [arg code-action] is responsible for installing the
packages and their index. The system currently provides

[list_begin definitions]

[def [cmd _tcl]] Copy all [file .tcl] files found in
[file modules/[arg name]] into the installation.

[def [cmd _tcr]] As [cmd _tcl], copy the [file .tcl] files found in
the subdirectories of [file modules/[arg name]] as well.

[def [cmd _tci]] As [cmd _tcl], and copy the [file tclIndex.tcl] file
as well.

[def [cmd _msg]] As [cmd _tcl], and copy the subdirectory [file msgs]
as well.

[def [cmd _doc]] As [cmd _tcl], and copy the subdirectory
[file mpformats] as well.

[def [cmd _tex]] As [cmd _tcl], and copy [file .tex] files as well.

[list_end]

[para] The [arg doc-action] is responsible for installing the package
documentation. The system currently provides

[list_begin definitions]
[def [cmd _null]] No documentation available, do nothing.

[def [cmd _man]] Process the [file .man] files found in
[file modules/[arg name]] and install the results (nroff and/or HTML)
in the proper location, as given to the installer.

[para] This is actually a fallback, normally the installer uses the
pre-made formatted documentation found under [file idoc].

[list_end]

[para] The [arg example-action] is responsible for installing the
examples. The system currently provides

[list_begin definitions]
[def [cmd _null]] No examples available, do nothing.

[def [cmd _exa]] Copy the the directory [file examples/[arg name]]
recursively to the install location for examples.

[list_end]

[call [cmd Application] [arg name]]

Install the application with [arg name], found in [file apps].


[call [cmd Exclude] [arg name]]

This command signals to the installer which of the listed modules to
[emph not] install. I.e. they name the deprecated modules of Tcllib.

[list_end]

[para] If, and only if the above actions are not suitable for the new
module then a second file has to be modified,
[file support/installation/actions.tcl].

[para] This file contains the implementations of the available
actions, and is the place where any custom action needed to handle the
special circumstances of module has to be added.

Added devdoc/parts/d_maintain.inc.














































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
When contributing one or more packages for full inclusion into Tcllib
you are committing yourself to

[list_begin enumerated]

[enum] Keep the guidelines written down in
       [term {Tcl Community - Kind Communication}]
       (as any contributor) in your mind. The main point to take away
       from there is [emph {to be kind to each other}].

[enum] Your packages getting distributed under a BSD/MIT license.  For
       the details see [term {Tcllib - License}]

[enum] Maintenance of the new packages for a period of two years under
       the following rules, and responsibilities:

       [list_begin enumerated]

       [enum] A maintainer may step down after the mandatory period as
       	      they see fit.

       [enum] A maintainer may step down before the end of the
      	      mandatory period, under the condition that a replacement
      	      maintainer is immediately available and has agreed to
      	      serve the remainder of the period, plus their own
      	      mandatory period (see below).

       [enum] When stepping down without a replacement maintainer
      	      taking over the relevant packages have to be flagged as
      	      [const unmaintained].

       [enum] When a replacement mantainer is brought in for a package
      	      it is (kept) marked as [const maintained] (again).

       [para] A replacement maintainer is bound by the same rules as
	      the original maintainer, except that the mandatory
	      period of maintenance is shortened to one year.

       [enum] For any [const unmaintained] package a contributor
       	      interested in becoming its maintainer can become so by
       	      flagging them as [const maintained] with their name and
       	      contact information, committing themselves to the rules
       	      of a replacement maintainer (see previous point).

       [enum] For any already [const maintained] package a contributor
       	      interested in becoming a co-maintainer can become so
       	      with the agreement of the existing maintainer(s),
       	      committing themselves to the rules of a replacement
       	      maintainer (see two points previous).

       [list_end]

       [para] The responsibilities as a maintainer include:

       [list_begin enumerated]

       [enum] Watching Tcllib's ticket tracker for bugs, bug fixes,
       	      and feature requests related to the new packages.

       [enum] Reviewing the aforementioned tickets, rejecting or
       	      applying them

       [enum] Coordination and discussion with ticket submitter during
       	      the development and/or application of bug fixes.

       [list_end]

[enum] Follow the [sectref {Branching and Workflow}] of this guide.

[list_end]

Added devdoc/parts/d_op_aware.inc.


















































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
When developing we have to keep ourselves aware of the context of our
work. On what branch are we ? What files have we changed ? What new
files are not yet known to the repository ? What has happened remotely
since we used our checkout ?

The answers to these questions become especially important when using
a long-lived checkout and coming back to it after some time away.

[para] Commands to answer questions like the above are:

[list_begin definitions]

[def [cmd {fossil pull}]]

       Get all changes done on the remote since the last pull or sync
       from it. This has to be done first, before any of the commands
       below.

[para] Even if the commit in our checkout refers to the branch we want
       right now control operations committed to the remote may have
       changed that from underneath us.

[def [cmd {fossil info | grep tags}]]
[def [cmd {fossil branch list | grep '\*'}]]

       Two different ways of determining the branch our checkout is
       on.

[def [cmd {fossil timeline}]]

       What have we (and others) done recently ?

[para] [emph Attention], this information is very likely outdated, the
       more the longer we did not use this checkout.

       Run [cmd {fossil pull}] first to get latest information from
       the remote repository of the project.

[def [cmd {fossil timeline current}]]

       Place the commit our checkout is based on at the top of the
       timeline.

[def [cmd {fossil changes}]]

       Lists the files we have changed compared to the commit the
       checkout is based on.

[def [cmd {fossil extra}]]

       Lists the files we have in the checkout the repository does not
       know about. This may be leftover chaff from our work, or
       something we have forgotten to [cmd {fossil add}] to the
       repository yet.

[list_end]

Added devdoc/parts/d_op_branch_close.inc.


















































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
Be aware of where you are (see first definition).

[para] Ensure that you have clean checkout (see second definition).

       In the full-blown sequence (zig-zag) it is [emph required], due
       to the merging from trunk. In the shorter sequence it is only
       desired. That said, keeping the checkout clean before
       any major operations is a good habit to have, in my opinion.

[para] The full-blown sequencing with checks all the way is to

[list_begin enumerated]

[enum] Validate the checkout, i.e. last commit on your branch. Run the
       full test suite and other validations, fix all the issues which
       have cropped up.

[enum] Merge the latest state of the [term trunk] (see next definition).

[enum] Validate the checkout again. The incoming trunk changes may
       have broken something now. Do any required fixes.

[enum] Now merge to the trunk using

[example {
    fossil update trunk
    fossil merge --integrate YOUR_BRANCH
}]

[enum] At this point the checkout should be in the same state as at
       the end of point (3) above, because we resolved any issues with
       the trunk already. Thus a simple

[example {
    fossil commit ...
}]

       should be sufficient now to commit the merge back and close the
       branch (due to the [option --integrate] we used on the merge).

[para] The more paranoid may validate the checkout a third time before
       commiting.
[list_end]

[para] I call this a [term {zig-zag merge}] because of how the arrows
       look in the timeline, from trunk to feature branch for the
       first merge, and then back for the final merge.

[para] A less paranoid can do what I call a [term {simple merge}],
       which moves step (2) after step (4) and skips step (3)
       entirely. The resulting shorter sequence is

[list_begin enumerated]
[enum] Validate
[enum] Merge to trunk
[enum] Validate again
[enum] Commit to trunk
[list_end]

The last step after either zig-zag or plain merge is to

[example {
    fossil sync
}]

This saves our work to the remote side, and further gives us any other
work done while we were doing our merge. It especially allows us to
check if we raced somebody else, resulting in a split trunk.

[para] When that happens we should coordinate with the other developer
       on who fixes the split, to ensure that we do not race each
       other again.

Added devdoc/parts/d_op_branch_import.inc.
































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
Be aware of where you are (see first definition).

[para] Ensure that you have clean checkout (see second definition).
       It is [emph required].
       
[para] In most situations you want to import the latest commit of
       branch [term trunk] (or other origin). To get it use

[example {
    fossil pull
}]

[para] With that done we can now import this commit into our current
       branch with

[example {
    fossil merge trunk
}]

[para] Even if [syscmd fossil] does not report any conflicts it is a
       good idea to check that the operation has not broken the new
       and/or changed functionality we are working on.

[para] With the establishment of a good merge we then save the state
       with

[example {
    fossil commit ...
}]

before continuing development.

Added devdoc/parts/d_op_branch_open.inc.






















































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
Be aware of where you are (see first definition).

[para] Ensure that you have clean checkout (see second definition).
       It is [emph required].

[para] In most situations you want to be on branch [term trunk], and
       you want to be on the latest commit for it. To get there use

[example {
    fossil pull
    fossil update trunk
}]

If some other branch is desired as the starting point for the coming
work replace [term trunk] in the commands above with the name of that
branch.

[para] With the base line established we now have two ways of creating
       the new branch, with differing (dis)advantages.

       The simpler way is to

[example {
    fossil branch new NAME_OF_NEW_BRANCH
}]

and start developing. The advantage here is that you cannot forget to
create the branch. The disadvantages are that we have a branch commit
unchanged from where we branched from, and that we have to use
high-handed techniques like hiding or shunning to get rid of the
commit should we decide to abandon the work before the first actual
commit on the branch.

[para] The other way of creating the branch is to start developing,
and then on the first commit use the option [option --branch] to tell
[syscmd fossil] that we are starting a branch now. I.e. run

[example {
    fossil commit --branch NAME_OF_NEW_BRANCH ...
}]

where [term ...] are any other options used to supply the commit
message, files to commit, etc.

[para] The (dis)advantages are now reversed.

[para] We have no superflous commit, only what is actually
       developed. The work is hidden until we commit to make our first
       commit.

[para] We may forget to use [option {--branch NAME_OF_NEW_BRANCH}] and
       then have to correct that oversight via the fossil web
       interface (I am currently unaware of ways of doing such from
       the command line, although some magic incantantion of
       [cmd {fossil tag create}] may work).

[para] It helps to keep awareness, like checking before any commit
       that we are on the desired branch.

Added devdoc/parts/d_op_clean.inc.




























>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Be aware of where you are (see first definition).

[para] For pretty much all the operation recipes below a clean
       checkout is at least desired, often required.
       To check that a checkout is clean invoke

[example {
    fossil changes
    fossil extra
}]

How to clean up when uncommitted changes of all sorts are found is
context-specific and outside of the scope of this guide.

Added devdoc/parts/d_testing.inc.




















































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
Testsuites in Tcllib are based on Tcl's standard test package
[package tcltest], plus utilities found in the directory
[file modules/devtools]

[para] Tcllib developers invoke the suites through the
[cmd {test run}] method of the [file sak.tcl] tool, with other methods
of [cmd test] providing management operations, for example setting a
list of standard Tcl shells to use.

[comment {===================================================================}]
[subsection {Invoke the testsuites of a specific module}]

Invoke either

[example {  ./sak.tcl test run foo }]

or

[example {  ./sak.tcl test run modules/foo }]

to invoke the testsuites found in a specific module [file foo].

[comment {===================================================================}]
[subsection {Invoke the testsuites of all modules}]

Invoke the tool without a module name, i.e.

[example {  ./sak.tcl test run }]

to invoke the testsuites of all modules.

[comment {===================================================================}]
[subsection {Detailed Test Logs}]

In all the previous examples the test runner will write a combination
of progress display and testsuite log to the standard output, showing
for each module only the tests that passed or failed and how many of
each in a summary at the end.

[para] To get a detailed log, it is necessary to invoke the test
runner with additional options.

[para] For one:

[example {
   ./sak.tcl test run --log LOG foo
}]

While this shows the same short log on the terminal as before, it also
writes a detailed log to the file [file LOG.log], and excerpts to
other files ([file LOG.summary], [file LOG.failures], etc.).

[para] For two:

[example {
  ./sak.tcl test run -v foo
}]

This writes the detailed log to the standard output, instead of the
short log.

[para] Regardless of form, the detailed log contains a list of all test
cases executed, which failed, and how they failed (expected versus
actual results).

[comment {===================================================================}]
[subsection {Shell Selection}]

By default the test runner will use all the Tcl shells specified via
[cmd {test add}] to invoke the specified testsuites, if any. If no
such are specified it will fall back to the Tcl shell used to run the
tool itself.

[para] Use option [option --shell] to explicitly specify the Tcl shell
to use, like

[example {
  ./sak.tcl test run --shell /path/to/tclsh ...
}]

[comment {===================================================================}]
[subsection Help]

Invoke the tool as

[example {  ./sak.tcl help test }]

to see the detailed help for all methods of [cmd test], and the
associated options.

Added devdoc/parts/d_testwrite.inc.














































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
While previous sections talked about running the testsuites for a
module and the packages therein, this has no meaning if the module in
question has no testsuites at all.

[para] This section gives a very basic overview on possible
methodologies for writing tests and testsuites.

[para] First there are "drudgery" tests. Written to check absolutely
basic assumptions which should never fail.

[para] For example for a command FOO taking two arguments, three tests
calling it with zero, one, and three arguments. The basic checks that
the command fails if it has not enough arguments, or too many.

[para] After that come the tests checking things based on our
knowledge of the command, about its properties and assumptions. Some
examples based on the graph operations added during Google's Summer of
Code 2009 are:

[list_begin itemized]

[item]	The BellmanFord command in struct::graph::ops takes a
	[arg startnode] as argument, and this node should be a node of
	the graph. This equals one test case checking the behavior when the
	specified node is not a node of the graph.

[para]  This often gives rise to code in the implementation which
	explicitly checks the assumption and throws an understandable error,
	instead of letting the algorithm fail later in some weird
	non-deterministic way.

[para]  It is not always possible to do such checks. The graph argument
	for example is just a command in itself, and while we expect
	it to exhibit a certain interface, i.e. a set of sub-commands
	aka methods, we cannot check that it has them, except by
	actually trying to use them. That is done by the algorithm
	anyway, so an explicit check is just overhead we can get by
	without.

[item]  IIRC one of the distinguishing characteristic of either
	BellmanFord and/or Johnson is that they are able to handle
	negative weights. Whereas Dijkstra requires positive weights.

[para]	This induces (at least) three testcases ... Graph with all
	positive weights, all negative, and a mix of positive and
	negative weights.

	Thinking further does the algorithm handle the weight
	[const 0] as well ? Another test case, or several, if we mix
	zero with positive and negative weights.

[item]	The two algorithms we are currently thinking about are about
	distances between nodes, and distance can be 'Inf'inity,
	i.e. nodes may not be connected. This means that good test
	cases are

	[list_begin enumerated]
	[enum]	Strongly connected graph
	[enum]	Connected graph
	[enum]	Disconnected graph.
	[list_end]

	[para] At the extremes of strongly connected and disconnected
	we have the fully connected graphs and graphs without edges,
	only nodes, i.e. completely disconnected.

[item]	IIRC both of the algorithms take weighted arcs, and fill in a
	default if arcs are left unweighted in the input graph.

	[para] This also induces three test cases:

	[list_begin enumerated]
	[enum]	Graph will all arcs with explicit weights.
	[enum]	Graph without weights at all.
	[enum]	Graph with mixture of weighted and unweighted graphs.
	[list_end]
[list_end]

[para] What was described above via examples is called
[term black-box] testing. Test cases are designed and written based on
the developer's knowledge of the properties of the algorithm and its
inputs, without referencing a particular implementation.

[para] Going further, a complement to [term black-box] testing is
[term white-box]. For this we know the implementation of the
algorithm, we look at it and design our tests cases so that they force
the code through all possible paths in the implementation. Wherever a
decision is made we have a test case forcing a specific direction of
the decision, for all possible combinations and directions. It is easy
to get a combinatorial explosion in the number of needed test-cases.

[para] In practice I often hope that the black-box tests I have made
are enough to cover all the paths, obviating the need for white-box
tests.

[para] The above should be enough to make it clear that writing tests
for an algorithm takes at least as much time as coding the algorithm,
and often more time. Much more time.

See for example also [uri http://sqlite.org/testing.html], a writeup
on how the Sqlite database engine is tested. Another article of
interest might be [uri https://www.researchgate.net/publication/298896236].
While geared to a particular numerical algorithm it still shows that
even a simple-looking algorithm can lead to an incredible number of
test cases.

[para] An interesting connection is to documentation. In one
direction, the properties checked with black-box testing are exactly
the properties which should be documented in the algorithm's man
page. And conversely, the documentation of the properties of an
algorithm makes a good reference to base the black-box tests on.

[para] In practice test cases and documentation often get written
together, cross-influencing each other. And the actual writing of test
cases is a mix of black and white box, possibly influencing the
implementation while writing the tests. Like writing a test for a
condition like [term {startnode not in input graph}] serving as
reminder to put a check for this condition into the code.

Added devdoc/parts/rm_distribute.inc.














































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
With the release made it has to be published and the world notified of
its existence.

[list_begin enumerated]

[enum]	    Create a proper fossil event for the release, via
	    [uri http://core.tcl-lang.org/tcllib/eventedit].

[para]	    An [uri http://core.tcl-lang.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817 {existing event}] should be used as template.

[enum]	    Update a number of web locations:

[list_begin enumerated]
[enum]	    [uri http://core.tcl-lang.org/tcllib/doc/trunk/embedded/index.md {Home page}]
[enum]	    [uri http://core.tcl-lang.org/tcllib/wiki?name=Downloads     Downloads]
[enum]	    [uri http://core.tcl-lang.org/tcllib/wiki?name=Past+Releases {Past Releases}]
[enum]	    [uri http://www.tcl-lang.org/home/release.txt     ]
[enum]	    [uri http://www.tcl-lang.org/software/tcllib/*.tml]
[enum]	    [uri http://wiki.tcl-lang.org/page/Tcllib]
[list_end]

The first location maps to the file [file embedded/index.md] in the
repository itself, as such it can edited as part of the release
process. This is where reference to the new fossil event is added, as
the new current release.

[para] The next two locations are in the fossil tcllib wiki and
require admin or wiki write permissions for
[uri http://core.tcl-lang.org/tcllib].

[para] The last two locations require ssh access to
[uri http://www.tcl-lang.org] and permission to edit
files in the web area.


[enum]	***TODO*** mailing lists and other places to send notes to.

[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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
The [file sak.tcl] script in the toplevel directory of a Tcllib
checkout is the one tool used by the release manager to perform its
[sectref Tasks].

[para] The main commands to be used are

[example {
    sak.tcl validate
    sak.tcl test run
    sak.tcl review
    sak.tcl readme
    sak.tcl localdoc
    sak.tcl release
}]

More detail will be provided in the explanations of the various
[sectref Tasks].

Added devdoc/parts/rm_work.inc.














>
>
>
>
>
>
>
1
2
3
4
5
6
7
todo: test, validate and check that the candidate is worthy of release
fix testsuites, possibly fix packages, documentation
regenerate docs
coordinate with package maintainers wrt fixes

big thing: going over the packages, classify changes since last
release to generate a nice readme.

Added devdoc/parts/rq_critcl.inc.






































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
[subsection Critcl]

The [syscmd critcl] tool is an [emph optional] dependency.

[para] It is only required when trying to build the C-based
[term accelerators] for a number of packages, as explained in
[sectref {Critcl & Accelerators}]

[para] Tcllib's build system looks for it in the [variable PATH],
using the name [syscmd critcl]. This is for Unix.

On Windows on the other hand the search is more complex. First we look
for a proper application [syscmd critcl.exe]. When that is not found
we look for a combination of interpreter ([syscmd tclkitsh.exe],
[syscmd tclsh.exe]) and starkit ([syscmd critcl.kit], [syscmd critcl])
instead. [emph Note] that the choice of starkit can be overriden via
the environment variable [variable CRITCL].

[para] Tcllib requires Critcl version 2 or higher.

[para] The github repository providing releases of version 2 and
higher, and the associated sources, can be found at
[uri http://andreas-kupries.github.com/critcl].

[para] Any branch of the repository can be used (if not using the
prebuild starkit or starpack), although the use of the stable branch
[emph master] is recommended.

[para] At the above url is also an explanation on how to build and
install Critcl, including a list of its dependencies.

[para] Its instructions will not be repeated here. If there are
problems with these directions please file a ticket against the
[term Critcl] project, and not Tcllib.

Added devdoc/parts/rq_tcl.inc.




























































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
[subsection Tcl]

As we are installing a number of Tcl packages and applications it
should be pretty much obvious that a working installation of Tcl
itself is needed, and I will not belabor the point.

[para] Out of the many possibilities use whatever you are comfortable
with, as long as it provides at the very least Tcl 8.2, or higher.

This may be a Tcl installation provided by your operating system
distribution, from a distribution-independent vendor, or built by
yourself.

[para] [emph Note] that the packages in Tcllib have begun to require
8.4, 8.5, and even 8.6. Older versions of Tcl will not be able to use
such packages. Trying to use them will result in
[emph {package not found}] errors, as their package index files will
not register them in versions of the core unable to use them.

[para] Myself, I used (and still use)
[uri http://www.activestate.com ActiveState's]
ActiveTcl 8.5 distribution during development, as I am most familiar
with it.

[para] [emph {(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, maintaining ActiveTcl and TclDevKit for them).}].
I am currently working for SUSE Software Canada ULC, although not in
Tcl-related areas.

[para] This distribution can be found at
[uri http://www.activestate.com/activetcl]. Retrieve the archive of
ActiveTcl 8.5 (or higher) for your platform and install it as directed
by ActiveState.

[para] For those wishing to build and install Tcl on their own, the
relevant sources can be found at

[list_begin definitions]
[def Tcl] [uri http://core.tcl-lang.org/tcl/]
[list_end]

together with the necessary instructions on how to build it.

[para] If there are problems with building, installing, or using Tcl,
please file a ticket against [term Tcl], or the vendor of your
distribution, and [emph not] [term Tcllib].

Added devdoc/parts/welcome.inc.












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

Deleted devdoc/releaseguide.html.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
<!- Guide to the creation of source releases for Tcllib -->

<h1>Guide to the creation of source releases for Tcllib
</h1>
<hr>

<h2>Recap
</h2>
<table><tr><td valign=top>
      <!-- The local source of this image is
		tcllib/devel/cvs.branches.*
	-->
      <img src="http://sourceforge.net/dbimage.php?id=2221">
</td><td valign=top><p>
The CVS repository for Tcllib contains two main branches,
      the HEAD for development, and RELEASES as the staging area for
      official releases.
</p></td></tr></table>

<h2>Dependencies
</h2>

<h2>Creation of a new official release
</h2>

<p>To create a new official release of Tcllib the release manager has
      to perform the steps described below:
</p>


<ol>
<li> Retrieve the sources at the current head
	from the CVS repository, using a command like
<pre>
	  CVSROOT=:pserver:[email protected]:/cvsroot/tcllib
	  cvs -d${CVSROOT} co tcllib
</pre>
	Vary this command according to taste as long as the overall
	meaning is not changed. Compression options and the like.

<li> Tag these sources with a new branch tag for the new release of
	  tcllib, like
<pre>
	  cvs -d${CVSROOT} rtag tcllib
</pre>

<li> Commit the changes, then update the working directory.

<li> Use a tclsh to run the <b>sak</b> tool with the argument <i>gendist</i>, like
<pre>
    tclsh /path/to/tcllib/sak.tcl gendist
</pre>

<li> This results in the creation of a <i>tcllib-VERSION</i> directory
in the current working directory, and of two archives, <i>.zip</i>,
and <i>.tar.gz</i>. A starkit will be created if <b>sdx</b> is present
in the PATH. If additionally a file named <b>tclkit</b> is present in
the current working directory a starpack will be created too, using
this tclkit as the runtime.


<li> Now follow the instructions in the Sourceforge site documentation
		    for uploading the archives generated by the last
		    step to
		    <b>ftp://upload.sourceforge.net/incoming</b>, and
		    follow the procedures for creating packages and
		    releases at Sourceforge.
</ol>

<p>At last notify the relevant persons in other communities like
Debian (See list of contacts) about the new release.
</p>
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<














































































































































Added devdoc/tcl_community_communication.man.




































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcl_community_communication n 1]
[titledesc {Tcl Community - Kind Communication}]
[description]

The Tcl Community encourages contributions from anyone who wishes to
advance the development of:

[list_begin itemized]
[item] The Tcl Language
[item] Tcl derived languages
[item] Tcl related libraries
[item] Tcl extensions
[item] External Projects that Integrate Tcl
[list_end]

[para] We welcome those contributions from anyone. We are blind to
gender, race, religion, cultural background, cybernetic nature, and
any other demographic characteristics, as well as personal political
views.

[para] A community lives and dies by communications. And occasionally
our communications are peppered with patterns that are harsh,
unfriendly, unwelcoming and/or otherwise unkind. As a volunteer
community, we need all of the help we can get. Therefore, we ask all
contributors to make a conscious effort, in Tcl Community discussions,
to communicate in ways that are welcoming. Ways that are
friendly. Ways that are, in a word: kind.

[para] These guidelines suggest specific ways to accomplish that goal.

[para] Please note: for the balance of this document any reference to
"People", "Persons", "anybody" or "somebody" can refer to any sentient
being, not merely corporeal members of the species Homo Sapien.

[list_begin definitions]

[def {We are a Sanctuary not a Clubhouse}]

The Tcl Community is a collective of amateurs and professionals who
code, test, and use tools. Our community is open to all. There is no
velvet rope. There is no bouncer at the door. There are no secret
handshakes. Any sentient being who enters our midst is welcome. If
someone is ever asked to leave, it is only because they are being
disruptive to the functioning of the community.

[def {We Merit Ideas, Not People}]

A good idea can come from anyone, regardless of how little time they
have been with us. A bad idea can come from anyone, regardless of how
much time or how little time they have been with us. We judge a
concept by how it stands up to scrutiny of logic, implementation, and
regression testing. We don’t judge ideas based on who had the idea
first, who agrees with the idea, or who disagrees with it.

[def {Treat Everyone with Respect}]

Everyone is deserving of respect and courtesy at all times.

[def {Refer to people by the names they use.}]

If grammar requires you to state a gender for a person, honor their
preferences about their gender identity. If you are unsure as to the
gender of an individual, ask. If someone had to guess about your
gender and got it wrong, please correct them and do not take it
personally.

[def {Do not take a harsh tone towards other participants.}]

Do not make personal attacks against anyone (participant or not.)

[para] Criticize statements and actions, never people.

[def {Don’t Take Things Personally}]

When in doubt, assume the best in people. A criticism of your
statements is not a personal attack on you.

[def {Persons, not People}]

Stereotypes are an unhelpful tool on many accounts. They are generally
oversimplified. They are usually flat out wrong. And even if "right"
they are of absolutely no utility in determining the capabilities,
motivations, or fitness of an individual.

[para] Don’t use them in Tcl Community communications.

[def {Mistakes Happen}]

The human condition is a series of trials and errors. Progress is when
we get one more trial than error. Being wrong or making a mistake is
the default state of humanity. Accept the errors of your fellow
sentient beings, and be aware that you are also fallible.

[def {Keep it Real}]

Please respond to what people actually say. We are all amazing
individuals, but none among us are mind readers. If you find yourself
responding to what you imagine someone is thinking, odds are you are
going to be wrong.

[para] If you must criticize someone, stick to things they have
actually done. Never criticize for something you speculate they have
done. Or imagine they have done. Or something someone who shares some
attribute with them has done in the past.

[para] Keep discussions about any non-Tcl subjects to what can be
stated factually and without emotion or judgement.

[def {When Trouble Arises, Don’t Escalate}]

If you feel you are being personally attacked or offended, take the
high road. Punching back in a public forum will only makes things
worse. Address the matter in a private correspondence. Be
polite. Express your feelings, but note that you are expressing your
feelings. When writing, look for a way to calm matters down. And when
in doubt, sleep on your letter before pressing send. And when not in
doubt, sleep on it for another day after that.

[para] If you are a spectator to a fight in progress, politely request
the two parties take the matter to a more private forum.

[def {Always get the Last Word: I’m Sorry}]

If an personal argument does arise, be the first to apologize. An
apology does not concede a logical point. It merely acknowledges that
at some point the discussion left either logic, community decency, or
both. Return to the topic when cooler heads can prevail.

[def {Nobody is Keeping Score}]

There is no prize for being right. There is no cost for being wrong. A
hard sell is not going to advance your idea along any more than a
logical argument. You aren’t running for office. This isn’t debate
club. If you find yourself continuing a discussion beyond where a
topic can be logically discussed, stop.

[def {No Evangelizing}]

The Tcl Community is not the place to promote your chosen operating
system, political outlook, religion, marketing scheme, or economic
model. Period.

[para] (And if you do bring it up, be prepared to have your chosen
topic discussed logically. And odds are, not favorably.)

[def {Respect the Community}]

If the Community has come to a decision on a course of action, please
stop arguing.

[para] If someone complains about how you are expressing your ideas,
listen.

[para] If your words are hurting people, stop. There is no amount of
being "right" that makes up for someone leaving our midst because they
felt insulted, threatened, or ignored.

[list_end]

By following these guidelines, we will build our community, encourage
more contribution to our projects, and our discussions will be
friendlier and reach conclusions more easily.

[para] Thank You.

[section Signatories]
[list_begin itemized]
[item] Sean "the Hypnotoad" Woods
[item] Andreas Kupries
[list_end]

[section Authors]
[list_begin definitions]
[def Primary] Sean "the Hypnotoad" Woods
[def {Light editing}] Andreas Kupries
[list_end]
[manpage_end]

Added devdoc/tcllib_devguide.man.




























































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_devguide n 1]
[titledesc {Tcllib - The Developer's Guide}]
[description]
[include parts/welcome.inc]

[para]

This document is a guide for developers working on Tcllib,
i.e. maintainers fixing bugs, extending the collection's
functionality, etc.

[para]

Please read

[list_begin enum]
[enum] [term {Tcllib - How To Get The Sources}] and
[enum] [term {Tcllib - The Installer's Guide}]
[list_end]

first, if that was not done already.

[para] Here we assume that the sources are already available in a
directory of your choice, and that you not only know how to build and
install them, but also have all the necessary requisites to actually
do so. The guide to the sources in particular also explains which
source code management system is used, where to find it, how to set it
up, etc.

[comment {===================================================================}]
[section Commitments]
[subsection Contributor][include parts/d_contrib.inc]
[subsection Maintainer][include parts/d_maintain.inc]

[comment {===================================================================}]
[section {Branching and Workflow}]
[include parts/d_branchflow.inc]

[comment {===================================================================}]
[section {Structural Overview}]
[include parts/d_dirlayout.inc]

[comment {===================================================================}]
[section {Testsuite Tooling}]
[include parts/d_testing.inc]

[comment {===================================================================}]
[section {Documentation Tooling}]
[include parts/d_documentation.inc]

[comment {===================================================================}]
[section {Notes On Writing A Testsuite}]
[include parts/d_testwrite.inc]

[comment {===================================================================}]
[section {Installation Tooling}]
[include parts/d_installation.inc]

[comment {===================================================================}]
[manpage_end]

Added devdoc/tcllib_installer.man.




















































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_install_guide n 1]
[titledesc {Tcllib - The Installer's Guide}]
[description]
[include parts/welcome.inc]

[para]

The audience of this document is anyone wishing to build and install
the packages found in Tcllib, for either themselves, or others.

[para]

For developers intending to work on the packages themselves we
additionally provide

[list_begin enum]
[enum] [term {Tcllib - The Developer's Guide}].
[list_end]

[para]

Please read [term {Tcllib - How To Get The Sources}] first, if that
was not done already. Here we assume that the sources are already
available in a directory of your choice.

[para]

[comment {===================================================================}]
[section Requisites]

Before Tcllib can be build and used a number of requisites must be installed.

These are:

[list_begin enumerated]
[enum] The scripting language Tcl.
       For details see [sectref Tcl].
[enum] Optionally, the [package critcl] package (C embedding) for [syscmd Tcl].
       For details see [sectref CriTcl].
[list_end]

This list assumes that the machine where Tcllib is to be installed is
essentially clean. Of course, if parts of the dependencies listed
below are already installed the associated steps can be skipped. It is
still recommended to read their sections though, to validate that the
dependencies they talk about are indeed installed.

[include parts/rq_tcl.inc]
[include parts/rq_critcl.inc]

[comment {= build instructions ==============================================}]
[section {Build & Installation Instructions}]

As Tcllib is mainly a bundle of packages written in pure Tcl building
it is the same as installing it. The exceptions to this have their own
subsection, [sectref {Critcl & Accelerators}], later on.

[para] Before that however comes the standard case, differentiated by
       the platforms with material differences in the instruction, i.e.
       [term Unix]-like, versus [term Windows].

[para] Regarding the latter it should also be noted that it is
       possible set up an [term Unix]-like environment using projects
       like [term MSYS], [term Cygwin], and others. In that case the
       user has the choice of which instructions to follow.

[para] Regardless of environment or platform, a suitable [term Tcl]
       has to be installed, and its [syscmd tclsh] should be placed on
       the [variable PATH] ([term Unix]) or associated with
       [file .tcl] files ([term Windows]).

[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
[subsection {Installing on Unix}]
[include parts/b_unix.inc]

[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
[subsection {Installing on Windows}]
[include parts/b_windows.inc]

[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
[subsection {Critcl & Accelerators}]
[include parts/b_critcl.inc]

[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
[subsection Tooling]
[include parts/b_tooling.inc]

[manpage_end]

Added devdoc/tcllib_license.man.


























































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_license n 1]
[titledesc {Tcllib - License}]
[description]
[include parts/welcome.inc]

[para] The collection is under the BSD license.

[section License]

[para]

This software is copyrighted by Ajuba Solutions and other parties.
The following terms apply to all files associated with the software
unless explicitly disclaimed in individual files.

[para]

The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose,
provided that existing copyright notices are retained in all copies
and that this notice is included verbatim in any distributions. No
written agreement, license, or royalty fee is required for any of the
authorized uses.  Modifications to this software may be copyrighted by
their authors and need not follow the licensing terms described here,
provided that the new terms are clearly indicated on the first page of
each file where they apply.

[para]

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

[para]

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

[para]

GOVERNMENT USE: If you are acquiring this software on behalf of the
U.S. government, the Government shall have only "Restricted Rights" in
the software and related documentation as defined in the Federal
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
are acquiring the software on behalf of the Department of Defense, the
software shall be classified as "Commercial Computer Software" and the
Government shall have only "Restricted Rights" as defined in Clause
252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing, the
authors grant the U.S. Government and others acting in its behalf
permission to use and distribute the software in accordance with the
terms specified in this license.

[manpage_end]

Added devdoc/tcllib_releasemgr.man.


























































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_releasemgr n 1]
[titledesc {Tcllib - The Release Manager's Guide}]
[description]
[include parts/welcome.inc]

[para]

The audience of this document is the release manager for Tcllib, their
deputies, and anybody else interested in the task of creating
an official release of Tcllib for distribution.

[para]

Please read [term {Tcllib - How To Get The Sources}] first, if that
was not done already. Here we assume that the sources are already
available in a directory of your choice.

[para]

[comment {===================================================================}]
[section Tools]
[include parts/rm_tooling.inc]

[comment {===================================================================}]
[section Tasks]

[comment {===================================================================}]
[subsection {Start a release candidate}]
[include parts/rm_start.inc]

[comment {===================================================================}]
[subsection {Ready the candidate}]
[include parts/rm_work.inc]

[comment {===================================================================}]
[subsection {Make it official}]
[include parts/rm_final.inc]

[comment {===================================================================}]
[subsection {Distribute the release}]
[include parts/rm_distribute.inc]

[manpage_end]

Added devdoc/tcllib_sources.man.










































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_sources n 1]
[titledesc {Tcllib - How To Get The Sources}]
[description]
[include parts/welcome.inc]

[para]

The audience of this document is anyone wishing to either have just a
look at Tcllib's source code, or build the packages, or to extend and
modify them.

[para] For builders and developers we additionally provide

[list_begin enum]
[enum] [term {Tcllib - The Installer's Guide}].
[enum] [term {Tcllib - The Developer's Guide}].
[list_end]

respectively.

[section {Source Location}]

The official repository for Tcllib can be found at
[uri http://core.tcl-lang.org/tcllib]

[section Retrieval]

Assuming that you simply wish to look at the sources, or build a
specific revision, the easiest way of retrieving it is to:

[list_begin enum]
[enum] Log into this site, as "anonymous", using the semi-random password in the captcha.
[enum] Go to the "Timeline".
[enum] Choose the revision you wish to have.
[enum] Follow its link to its detailed information page.
[enum] On that page, choose either the "ZIP" or "Tarball" link to get
a copy of this revision in the format of your choice.
[list_end]

[section {Source Code Management}]

For the curious (or a developer-to-be), the sources are managed by the
[uri http://www.fossil-scm.org {Fossil SCM}].

Binaries for popular platforms can be found directly at its
[uri http://www.fossil-scm.org/download.html {download page}].

[para]

With that tool available the full history can be retrieved via:

[example {
    fossil clone \
	http://core.tcl-lang.org/tcllib \
        tcllib.fossil
}]

followed by

[example {
    mkdir tcllib
    cd tcllib
    fossil open ../tcllib.fossil
}]

to get a checkout of the head of the trunk.

[manpage_end]

Changes to embedded/index.md.

1
2
3
4
5
6
7

8
9
10
11
12
13
14
15
16
17









18
19
20
21
22
23
24
<div class='fossil-doc' data-title='Tcl Library Source Code'>

<h1 align="center">Tcl Library Source Code</h1>

<center>
Packages
- [Table Of Contents](md/toc.md)

- [Keyword Index](md/index.md)
</center>

<center>
	<form action='../../../docsrch' method='GET'>
	<input type="text" name="s" size="40" autofocus>
	<input type="submit" value="Search Package Documentation">
	</form>
</center>










## Discussion & Contact

Tcllib has two
[mailing lists](https://sourceforge.net/p/tcllib/mailman/).

One for notifications (commits, ticket changes), the other for general
discussion. These are managed at SourceForge, at the aforementioned




<
|
>
|









>
>
>
>
>
>
>
>
>







1
2
3
4
5

6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<div class='fossil-doc' data-title='Tcl Library Source Code'>

<h1 align="center">Tcl Library Source Code</h1>

<center>

Packages - [Table Of Contents](md/toc.md)
&nbsp;&nbsp;&nbsp;
[Keyword Index](md/index.md)
</center>

<center>
	<form action='../../../docsrch' method='GET'>
	<input type="text" name="s" size="40" autofocus>
	<input type="submit" value="Search Package Documentation">
	</form>
</center>

## Guides to Tcllib

   * [Tcl Community - Kind Communication](md/tcllib/files/devdoc/tcl_community_communication.md)
   * [License](md/tcllib/files/devdoc/tcllib_license.md)
   * [How To Get The Sources](md/tcllib/files/devdoc/tcllib_sources.md)
   * [How To Build And Install Tcllib](md/tcllib/files/devdoc/tcllib_installer.md)
   * [The Developer's Guide](md/tcllib/files/devdoc/tcllib_devguide.md)
   * [The Release Manager's Guide](md/tcllib/files/devdoc/tcllib_releasemgr.md)

## Discussion & Contact

Tcllib has two
[mailing lists](https://sourceforge.net/p/tcllib/mailman/).

One for notifications (commits, ticket changes), the other for general
discussion. These are managed at SourceForge, at the aforementioned

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








































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
[//000000001]: # (tcl\_community\_communication \- )
[//000000002]: # (Generated from file 'tcl\_community\_communication\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl\_community\_communication\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcl\_community\_communication \- Tcl Community \- Kind Communication

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Signatories](#section2)

  - [Authors](#section3)

# <a name='description'></a>DESCRIPTION

The Tcl Community encourages contributions from anyone who wishes to advance the
development of:

  - The Tcl Language

  - Tcl derived languages

  - Tcl related libraries

  - Tcl extensions

  - External Projects that Integrate Tcl

We welcome those contributions from anyone\. We are blind to gender, race,
religion, cultural background, cybernetic nature, and any other demographic
characteristics, as well as personal political views\.

A community lives and dies by communications\. And occasionally our
communications are peppered with patterns that are harsh, unfriendly,
unwelcoming and/or otherwise unkind\. As a volunteer community, we need all of
the help we can get\. Therefore, we ask all contributors to make a conscious
effort, in Tcl Community discussions, to communicate in ways that are welcoming\.
Ways that are friendly\. Ways that are, in a word: kind\.

These guidelines suggest specific ways to accomplish that goal\.

Please note: for the balance of this document any reference to "People",
"Persons", "anybody" or "somebody" can refer to any sentient being, not merely
corporeal members of the species Homo Sapien\.

  - We are a Sanctuary not a Clubhouse

    The Tcl Community is a collective of amateurs and professionals who code,
    test, and use tools\. Our community is open to all\. There is no velvet rope\.
    There is no bouncer at the door\. There are no secret handshakes\. Any
    sentient being who enters our midst is welcome\. If someone is ever asked to
    leave, it is only because they are being disruptive to the functioning of
    the community\.

  - We Merit Ideas, Not People

    A good idea can come from anyone, regardless of how little time they have
    been with us\. A bad idea can come from anyone, regardless of how much time
    or how little time they have been with us\. We judge a concept by how it
    stands up to scrutiny of logic, implementation, and regression testing\. We
    don’t judge ideas based on who had the idea first, who agrees with the idea,
    or who disagrees with it\.

  - Treat Everyone with Respect

    Everyone is deserving of respect and courtesy at all times\.

  - Refer to people by the names they use\.

    If grammar requires you to state a gender for a person, honor their
    preferences about their gender identity\. If you are unsure as to the gender
    of an individual, ask\. If someone had to guess about your gender and got it
    wrong, please correct them and do not take it personally\.

  - Do not take a harsh tone towards other participants\.

    Do not make personal attacks against anyone \(participant or not\.\)

    Criticize statements and actions, never people\.

  - Don’t Take Things Personally

    When in doubt, assume the best in people\. A criticism of your statements is
    not a personal attack on you\.

  - Persons, not People

    Stereotypes are an unhelpful tool on many accounts\. They are generally
    oversimplified\. They are usually flat out wrong\. And even if "right" they
    are of absolutely no utility in determining the capabilities, motivations,
    or fitness of an individual\.

    Don’t use them in Tcl Community communications\.

  - Mistakes Happen

    The human condition is a series of trials and errors\. Progress is when we
    get one more trial than error\. Being wrong or making a mistake is the
    default state of humanity\. Accept the errors of your fellow sentient beings,
    and be aware that you are also fallible\.

  - Keep it Real

    Please respond to what people actually say\. We are all amazing individuals,
    but none among us are mind readers\. If you find yourself responding to what
    you imagine someone is thinking, odds are you are going to be wrong\.

    If you must criticize someone, stick to things they have actually done\.
    Never criticize for something you speculate they have done\. Or imagine they
    have done\. Or something someone who shares some attribute with them has done
    in the past\.

    Keep discussions about any non\-Tcl subjects to what can be stated factually
    and without emotion or judgement\.

  - When Trouble Arises, Don’t Escalate

    If you feel you are being personally attacked or offended, take the high
    road\. Punching back in a public forum will only makes things worse\. Address
    the matter in a private correspondence\. Be polite\. Express your feelings,
    but note that you are expressing your feelings\. When writing, look for a way
    to calm matters down\. And when in doubt, sleep on your letter before
    pressing send\. And when not in doubt, sleep on it for another day after
    that\.

    If you are a spectator to a fight in progress, politely request the two
    parties take the matter to a more private forum\.

  - Always get the Last Word: I’m Sorry

    If an personal argument does arise, be the first to apologize\. An apology
    does not concede a logical point\. It merely acknowledges that at some point
    the discussion left either logic, community decency, or both\. Return to the
    topic when cooler heads can prevail\.

  - Nobody is Keeping Score

    There is no prize for being right\. There is no cost for being wrong\. A hard
    sell is not going to advance your idea along any more than a logical
    argument\. You aren’t running for office\. This isn’t debate club\. If you find
    yourself continuing a discussion beyond where a topic can be logically
    discussed, stop\.

  - No Evangelizing

    The Tcl Community is not the place to promote your chosen operating system,
    political outlook, religion, marketing scheme, or economic model\. Period\.

    \(And if you do bring it up, be prepared to have your chosen topic discussed
    logically\. And odds are, not favorably\.\)

  - Respect the Community

    If the Community has come to a decision on a course of action, please stop
    arguing\.

    If someone complains about how you are expressing your ideas, listen\.

    If your words are hurting people, stop\. There is no amount of being "right"
    that makes up for someone leaving our midst because they felt insulted,
    threatened, or ignored\.

By following these guidelines, we will build our community, encourage more
contribution to our projects, and our discussions will be friendlier and reach
conclusions more easily\.

Thank You\.

# <a name='section2'></a>Signatories

  - Sean "the Hypnotoad" Woods

  - Andreas Kupries

# <a name='section3'></a>Authors

  - Primary

    Sean "the Hypnotoad" Woods

  - Light editing

    Andreas Kupries

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






































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
[//000000001]: # (tcllib\_devguide \- )
[//000000002]: # (Generated from file 'tcllib\_devguide\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_devguide\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_devguide \- Tcllib \- The Developer's Guide

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [Commitments](#section2)

      - [Contributor](#subsection1)

      - [Maintainer](#subsection2)

  - [Branching and Workflow](#section3)

      - [Package Dependencies](#subsection3)

      - [Trunk](#subsection4)

      - [Branches](#subsection5)

      - [Working with Branches](#subsection6)

      - [Version numbers](#subsection7)

  - [Structural Overview](#section4)

      - [Main Directories](#subsection8)

      - [More Directories](#subsection9)

      - [Top Files](#subsection10)

      - [File Types](#subsection11)

  - [Testsuite Tooling](#section5)

      - [Invoke the testsuites of a specific module](#subsection12)

      - [Invoke the testsuites of all modules](#subsection13)

      - [Detailed Test Logs](#subsection14)

      - [Shell Selection](#subsection15)

      - [Help](#subsection16)

  - [Documentation Tooling](#section6)

      - [Generate documentation for a specific module](#subsection17)

      - [Generate documentation for all modules](#subsection18)

      - [Available output formats, help](#subsection19)

      - [Validation without output](#subsection20)

  - [Notes On Writing A Testsuite](#section7)

  - [Installation Tooling](#section8)

# <a name='synopsis'></a>SYNOPSIS

[__[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action*](#1)  
[__[Application](\.\./\.\./\.\./index\.md\#application)__ *name*](#2)  
[__Exclude__ *name*](#3)  

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

This document is a guide for developers working on Tcllib, i\.e\. maintainers
fixing bugs, extending the collection's functionality, etc\.

Please read

  1. *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* and

  1. *[Tcllib \- The Installer's Guide](tcllib\_installer\.md)*

first, if that was not done already\.

Here we assume that the sources are already available in a directory of your
choice, and that you not only know how to build and install them, but also have
all the necessary requisites to actually do so\. The guide to the sources in
particular also explains which source code management system is used, where to
find it, how to set it up, etc\.

# <a name='section2'></a>Commitments

## <a name='subsection1'></a>Contributor

As a contributor to Tcllib you are committing yourself to:

  1. keep the guidelines written down in *[Tcl Community \- Kind
     Communication](tcl\_community\_communication\.md)* in your mind\. The main
     point to take away from there is *to be kind to each other*\.

  1. Your contributions getting distributed under a BSD/MIT license\. For the
     details see *[Tcllib \- License](tcllib\_license\.md)*

Contributions are made by entering tickets into our tracker, providing patches,
bundles or branches of code for inclusion, or posting to the Tcllib related
mailing lists\.

## <a name='subsection2'></a>Maintainer

When contributing one or more packages for full inclusion into Tcllib you are
committing yourself to

  1. Keep the guidelines written down in *[Tcl Community \- Kind
     Communication](tcl\_community\_communication\.md)* \(as any contributor\) in
     your mind\. The main point to take away from there is *to be kind to each
     other*\.

  1. Your packages getting distributed under a BSD/MIT license\. For the details
     see *[Tcllib \- License](tcllib\_license\.md)*

  1. Maintenance of the new packages for a period of two years under the
     following rules, and responsibilities:

       1) A maintainer may step down after the mandatory period as they see fit\.

       1) A maintainer may step down before the end of the mandatory period,
          under the condition that a replacement maintainer is immediately
          available and has agreed to serve the remainder of the period, plus
          their own mandatory period \(see below\)\.

       1) When stepping down without a replacement maintainer taking over the
          relevant packages have to be flagged as __unmaintained__\.

       1) When a replacement mantainer is brought in for a package it is \(kept\)
          marked as __maintained__ \(again\)\.

          A replacement maintainer is bound by the same rules as the original
          maintainer, except that the mandatory period of maintenance is
          shortened to one year\.

       1) For any __unmaintained__ package a contributor interested in
          becoming its maintainer can become so by flagging them as
          __maintained__ with their name and contact information, committing
          themselves to the rules of a replacement maintainer \(see previous
          point\)\.

       1) For any already __maintained__ package a contributor interested in
          becoming a co\-maintainer can become so with the agreement of the
          existing maintainer\(s\), committing themselves to the rules of a
          replacement maintainer \(see two points previous\)\.

     The responsibilities as a maintainer include:

       1) Watching Tcllib's ticket tracker for bugs, bug fixes, and feature
          requests related to the new packages\.

       1) Reviewing the aforementioned tickets, rejecting or applying them

       1) Coordination and discussion with ticket submitter during the
          development and/or application of bug fixes\.

  1. Follow the [Branching and Workflow](#section3) of this guide\.

# <a name='section3'></a>Branching and Workflow

## <a name='subsection3'></a>Package Dependencies

Regarding packages and dependencies between them Tcllib occupies a middle
position between two extremes:

  1. On one side a strongly interdependent set of packages, usually by a single
     author, for a single project\. Looking at my \(Andreas Kupries\) own work
     examples of such are [Marpa](https://core\.tcl\.tk/akupries/marpa/index),
     [CRIMP](https://core\.tcl\.tk/akupries/crimp/index),
     [Kinetcl](https://core\.tcl\.tk/akupries/kinetcl/index), etc\.

     For every change the author of the project handles all the modifications
     cascading from any incompatibilities it introduced to the system\.

  1. On the other side, the world of semi\-independent projects by many different
     authors where authors know what packages their own creations depend on, yet
     usually do not know who else depends on them\.

     The best thing an author making an \(incompatible\) change to their project
     can do is to for one announce such changes in some way, and for two use
     versioning to distinguish the code before and after the change\.

     The world is then responsible for adapting, be it by updating their own
     projects to the new version, or by sticking to the old\.

As mentioned already, Tcllib lives in the middle of that\.

While we as maintainers cannot be aware of all users of Tcllib's packages, and
thus have to rely on the mechanisms touched on in point 2 above for that, the
dependencies between the packages contained in Tcllib are a different matter\.

As we are collectively responsible for the usability of Tcllib in toto to the
outside world, it behooves us to be individually mindful even of Tcllib packages
we are not directly maintaining, when they depend on packages under our
maintainership\. This may be as simple as coordinating with the maintainers of
the affected packages\. It may also require us to choose how to adapt affected
packages which do not have maintainers, i\.e\. modify them to use our changed
package properly, or modify them to properly depend on the unchanged version of
our package\.

Note that the above is not only a chore but an opportunity as well\. Additional
insight can be had by forcing ourselves to look at our package and the planned
change\(s\) from an outside perspective, to consider the ramifications of our
actions on others in general, and on dependent packages in particular\.

## <a name='subsection4'></a>Trunk

The management and use of branches is an important part of working with a
*Distributed Version Control System* \(*DVCS*\) like
[fossil](https://www\.fossil\-scm\.org/)\.

For Tcllib the main branch of the collection is *trunk*\. In *git* this
branch would be called *master*, and this is exactly the case in the [github
mirror](https://github\.com/tcltk/tcllib/) of Tcllib\.

To properly support debugging *each commit* on this branch *has to pass the
entire testsuite* of the collection\. Using bisection to determine when an issue
appeared is an example of an action made easier by this constraint\.

This is part of our collective responsibility for the usability of Tcllib in
toto to the outside world\. As *fossil* has no mechanism to enforce this
condition this is handled on the honor system for developers and maintainers\.

To make the task easier Tcllib comes with a tool \("sak\.tcl"\) providing a number
of commands in support\. These commands are explained in the following sections
of this guide\.

While it is possible and allowed to commit directly to trunk remember the above
constraint regarding the testsuite, and the coming notes about other possible
issues with a commit\.

## <a name='subsection5'></a>Branches

Given the constraints placed on the *trunk* branch of the repository it is
\(strongly\) recommended to perform any development going beyond trivial changes
on a non\-trunk branch\.

Outside of the trunk developers are allowed to commit intermediate broken states
of their work\. Only at the end of a development cycle, when the relevant branch
is considered ready for merging, will it be necessary to perform full the set of
validations ensuring that the merge to come will create a good commit on trunk\.

Note that while a review from a second developer is not a required condition for
merging a branch it is recommended to seek out such an independent opinion as a
means of cross\-checking the work\.

It also recommended to give any new branch a name which aids in determining
additional details about it\. Examples of good things to stick into a branch name
would be

  - Developer \(nick\)name

  - Ticket hash/reference

  - One or two keywords applicable to the work

  - \.\.\.

Further, while most development branches are likely quite short\-lived, no
prohibitions exist against making longer\-lived branches\. Creators should however
be mindful that the longer such a branch exists without merges the more
divergent they will tend to be, with an associated increase in the effort which
will have to be spent on either merging from and merging to trunk\.

## <a name='subsection6'></a>Working with Branches

In the hope of engendering good work practices now a few example operations
which will come up with branches, and their associated fossil command
\(sequences\)\.

  - *Awareness*

    When developing we have to keep ourselves aware of the context of our work\.
    On what branch are we ? What files have we changed ? What new files are not
    yet known to the repository ? What has happened remotely since we used our
    checkout ? The answers to these questions become especially important when
    using a long\-lived checkout and coming back to it after some time away\.

    Commands to answer questions like the above are:

      * __fossil pull__

        Get all changes done on the remote since the last pull or sync from it\.
        This has to be done first, before any of the commands below\.

        Even if the commit in our checkout refers to the branch we want right
        now control operations committed to the remote may have changed that
        from underneath us\.

      * __fossil info &#124; grep tags__

      * __fossil branch list &#124; grep '\\\*'__

        Two different ways of determining the branch our checkout is on\.

      * __fossil timeline__

        What have we \(and others\) done recently ?

        *Attention*, this information is very likely outdated, the more the
        longer we did not use this checkout\. Run __fossil pull__ first to
        get latest information from the remote repository of the project\.

      * __fossil timeline current__

        Place the commit our checkout is based on at the top of the timeline\.

      * __fossil changes__

        Lists the files we have changed compared to the commit the checkout is
        based on\.

      * __fossil extra__

        Lists the files we have in the checkout the repository does not know
        about\. This may be leftover chaff from our work, or something we have
        forgotten to __fossil add__ to the repository yet\.

  - *Clean checkouts*

    Be aware of where you are \(see first definition\)\.

    For pretty much all the operation recipes below a clean checkout is at least
    desired, often required\. To check that a checkout is clean invoke

        fossil changes
        fossil extra

    How to clean up when uncommitted changes of all sorts are found is
    context\-specific and outside of the scope of this guide\.

  - *Starting a new branch*

    Be aware of where you are \(see first definition\)\.

    Ensure that you have clean checkout \(see second definition\)\. It is
    *required*\.

    In most situations you want to be on branch *trunk*, and you want to be on
    the latest commit for it\. To get there use

        fossil pull
        fossil update trunk

    If some other branch is desired as the starting point for the coming work
    replace *trunk* in the commands above with the name of that branch\.

    With the base line established we now have two ways of creating the new
    branch, with differing \(dis\)advantages\. The simpler way is to

        fossil branch new NAME_OF_NEW_BRANCH

    and start developing\. The advantage here is that you cannot forget to create
    the branch\. The disadvantages are that we have a branch commit unchanged
    from where we branched from, and that we have to use high\-handed techniques
    like hiding or shunning to get rid of the commit should we decide to abandon
    the work before the first actual commit on the branch\.

    The other way of creating the branch is to start developing, and then on the
    first commit use the option __\-\-branch__ to tell __fossil__ that we
    are starting a branch now\. I\.e\. run

        fossil commit --branch NAME_OF_NEW_BRANCH ...

    where *\.\.\.* are any other options used to supply the commit message, files
    to commit, etc\.

    The \(dis\)advantages are now reversed\.

    We have no superflous commit, only what is actually developed\. The work is
    hidden until we commit to make our first commit\.

    We may forget to use __\-\-branch NAME\_OF\_NEW\_BRANCH__ and then have to
    correct that oversight via the fossil web interface \(I am currently unaware
    of ways of doing such from the command line, although some magic
    incantantion of __fossil tag create__ may work\)\.

    It helps to keep awareness, like checking before any commit that we are on
    the desired branch\.

  - *Merging a branch into trunk*

    Be aware of where you are \(see first definition\)\.

    Ensure that you have clean checkout \(see second definition\)\. In the
    full\-blown sequence \(zig\-zag\) it is *required*, due to the merging from
    trunk\. In the shorter sequence it is only desired\. That said, keeping the
    checkout clean before any major operations is a good habit to have, in my
    opinion\.

    The full\-blown sequencing with checks all the way is to

      1. Validate the checkout, i\.e\. last commit on your branch\. Run the full
         test suite and other validations, fix all the issues which have cropped
         up\.

      1. Merge the latest state of the *trunk* \(see next definition\)\.

      1. Validate the checkout again\. The incoming trunk changes may have broken
         something now\. Do any required fixes\.

      1. Now merge to the trunk using

             fossil update trunk
             fossil merge --integrate YOUR_BRANCH

      1. At this point the checkout should be in the same state as at the end of
         point \(3\) above, because we resolved any issues with the trunk already\.
         Thus a simple

             fossil commit ...

         should be sufficient now to commit the merge back and close the branch
         \(due to the __\-\-integrate__ we used on the merge\)\.

         The more paranoid may validate the checkout a third time before
         commiting\.

    I call this a *zig\-zag merge* because of how the arrows look in the
    timeline, from trunk to feature branch for the first merge, and then back
    for the final merge\.

    A less paranoid can do what I call a *simple merge*, which moves step \(2\)
    after step \(4\) and skips step \(3\) entirely\. The resulting shorter sequence
    is

      1. Validate

      1. Merge to trunk

      1. Validate again

      1. Commit to trunk

    The last step after either zig\-zag or plain merge is to

        fossil sync

    This saves our work to the remote side, and further gives us any other work
    done while we were doing our merge\. It especially allows us to check if we
    raced somebody else, resulting in a split trunk\.

    When that happens we should coordinate with the other developer on who fixes
    the split, to ensure that we do not race each other again\.

  - *Merging from trunk*

    Be aware of where you are \(see first definition\)\.

    Ensure that you have clean checkout \(see second definition\)\. It is
    *required*\.

    In most situations you want to import the latest commit of branch *trunk*
    \(or other origin\)\. To get it use

        fossil pull

    With that done we can now import this commit into our current branch with

        fossil merge trunk

    Even if __fossil__ does not report any conflicts it is a good idea to
    check that the operation has not broken the new and/or changed functionality
    we are working on\.

    With the establishment of a good merge we then save the state with

        fossil commit ...

    before continuing development\.

## <a name='subsection7'></a>Version numbers

In Tcllib all changes to a package have to come with an increment of its version
number\. What part is incremented \(patchlevel, minor, major version\) depends on
the kind of change made\. With multiple changes in a commit the highest "wins"\.

When working in a development branch the version change can be deferred until it
is time to merge, and then has to cover all the changes in the branch\.

Below a list of the kinds of changes and their associated version increments:

  - *D \- documentation*

    No increment

  - *T \- testsuite*

    No increment

  - *B \- bugfix*

    Patchlevel

  - *I \- implementation tweak*

    Patchlevel

  - *P \- performance tweak*

    Patchlevel

  - *E \- backward\-compatible extension*

    Minor

  - *API \- incompatible change*

    Major

Note that a commit containing a version increment has to mention the new version
number in its commit message, as well as the kind of change which caused it\.

Note further that the version number of a package currently exists in three
places\. An increment has to update all of them:

  1. The package implementation\.

  1. The package index \("pkgIndex\.tcl"\)

  1. The package documentation\.

The "sak\.tcl" command __validate version__ helps finding discrepancies
between the first two\. All the other __validate__ methods are also of
interest to any developer\. Invoke it with

    sak.tcl help validate

to see their documentation\.

# <a name='section4'></a>Structural Overview

## <a name='subsection8'></a>Main Directories

The main directories in the Tcllib toplevel directory and of interest to a
developer are:

  - "modules"

    Each child directory represents one or more packages\. In the case of the
    latter the packages are usually related in some way\. Examples are "base64",
    "math", and "struct", with loose \(base64\) to strong \(math\) relations between
    the packages in the directory\.

  - "apps"

    This directory contains all the installable applications, with their
    documentation\. Note that this directory is currently *not* split into
    sub\-directories\.

  - "examples"

    Each child directory "foo" contains one or more example application for the
    packages in "modules/foo"\. These examples are generally not polished enough
    to be considered for installation\.

## <a name='subsection9'></a>More Directories

  - "config"

    This directory contains files supporting the Unix build system, i\.e\.
    "configure" and "Makefile\.in"\.

  - "devdoc"

    This directories contains the doctools sources for the global documentation,
    like this document and its sibling guides\.

  - "embedded"

    This directory contains the entire documentation formatted for
    *[HTML](\.\./\.\./\.\./index\.md\#html)* and styled to properly mix into the
    web site generated by fossil for the repository\.

    This is the documentation accessible from the Tcllib home directory,
    represented in the repository as "embedded/index\.md"\.

  - "idoc"

    This directory contains the entire documentation formatted for
    *[nroff](\.\./\.\./\.\./index\.md\#nroff)* and
    *[HTML](\.\./\.\./\.\./index\.md\#html)*, the latter without any styling\. This
    is the documentation which will be installed\.

  - "support"

    This directory contains the sources of internal packages and utilities used
    in the implementation of the "installer\.tcl" and "sak\.tcl" scripts/tools\.

## <a name='subsection10'></a>Top Files

  - "aclocal\.m4"

  - "configure"

  - "configure\.in"

  - "Makefile\.in"

    These four files comprise the Unix build system layered on top of the
    "installer\.tcl" script\.

  - "installer\.tcl"

    The Tcl\-based installation script/tool\.

  - "project\.shed"

    Configuration file for *Sean Wood*'s
    __[PracTcl](\.\./modules/practcl/practcl\.md)__ buildsystem\.

  - "sak\.tcl"

    This is the main tool for developers and release managers, the *Swiss Army
    Knife* of management operations on the collection\.

  - "ChangeLog"

    The log of changes to the global support, when the sources were held in
    *[CVS](\.\./\.\./\.\./index\.md\#cvs)*\. Not relevant any longer with the
    switch to the *fossil* SCM\.

  - "license\.terms"

    The license in plain ASCII\. See also *[Tcllib \-
    License](tcllib\_license\.md)* for the nicely formatted form\. The text is
    identical\.

  - "README\.md"

  - "\.github/CONTRIBUTING\.md"

  - "\.github/ISSUE\_TEMPLATE\.md"

  - "\.github/PULL\_REQUEST\_TEMPLATE\.md"

    These markdown\-formatted documents are used and shown by the github mirror
    of these sources, pointing people back to the official location and issue
    trackers\.

  - "DESCRIPTION\.txt"

  - "STATUS"

  - "tcllib\.spec"

  - "tcllib\.tap"

  - "tcllib\.yml"

    ????

## <a name='subsection11'></a>File Types

The most common file types, by file extension, are:

  - "\.tcl"

    Tcl code for a package, application, or example\.

  - "\.man"

    Doctools\-formatted documentation, usually for a package\.

  - "\.test"

    Test suite for a package, or part of\. Based on __tcltest__\.

  - "\.bench"

    Performance benchmarks for a package, or part of\. Based on "modules/bench"\.

  - "\.pcx"

    Syntax rules for *TclDevKit*'s __tclchecker__\. Using these rules
    allows the checker to validate the use of commands of a Tcllib package
    __foo__ without having to scan the "\.tcl" files implementing it\.

# <a name='section5'></a>Testsuite Tooling

Testsuites in Tcllib are based on Tcl's standard test package __tcltest__,
plus utilities found in the directory "modules/devtools"

Tcllib developers invoke the suites through the __test run__ method of the
"sak\.tcl" tool, with other methods of __[test](\.\./\.\./\.\./index\.md\#test)__
providing management operations, for example setting a list of standard Tcl
shells to use\.

## <a name='subsection12'></a>Invoke the testsuites of a specific module

Invoke either

    ./sak.tcl test run foo

or

    ./sak.tcl test run modules/foo

to invoke the testsuites found in a specific module "foo"\.

## <a name='subsection13'></a>Invoke the testsuites of all modules

Invoke the tool without a module name, i\.e\.

    ./sak.tcl test run

to invoke the testsuites of all modules\.

## <a name='subsection14'></a>Detailed Test Logs

In all the previous examples the test runner will write a combination of
progress display and testsuite log to the standard output, showing for each
module only the tests that passed or failed and how many of each in a summary at
the end\.

To get a detailed log, it is necessary to invoke the test runner with additional
options\.

For one:

    ./sak.tcl test run --log LOG foo

While this shows the same short log on the terminal as before, it also writes a
detailed log to the file "LOG\.log", and excerpts to other files \("LOG\.summary",
"LOG\.failures", etc\.\)\.

For two:

    ./sak.tcl test run -v foo

This writes the detailed log to the standard output, instead of the short log\.

Regardless of form, the detailed log contains a list of all test cases executed,
which failed, and how they failed \(expected versus actual results\)\.

## <a name='subsection15'></a>Shell Selection

By default the test runner will use all the Tcl shells specified via __test
add__ to invoke the specified testsuites, if any\. If no such are specified it
will fall back to the Tcl shell used to run the tool itself\.

Use option __\-\-shell__ to explicitly specify the Tcl shell to use, like

    ./sak.tcl test run --shell /path/to/tclsh ...

## <a name='subsection16'></a>Help

Invoke the tool as

    ./sak.tcl help test

to see the detailed help for all methods of
__[test](\.\./\.\./\.\./index\.md\#test)__, and the associated options\.

# <a name='section6'></a>Documentation Tooling

The standard format used for documentation of packages and other things in
Tcllib is *[doctools](\.\./\.\./\.\./index\.md\#doctools)*\. Its supporting
packages are a part of Tcllib, see the directories "modules/doctools" and
"modules/dtplite"\. The latter is an application package, with the actual
application "apps/dtplite" a light wrapper around it\.

Tcllib developers gain access to these through the __doc__ method of the
"sak\.tcl" tool, another \(internal\) wrapper around the "modules/dtplite"
application package\.

## <a name='subsection17'></a>Generate documentation for a specific module

Invoke either

    ./sak.tcl doc html foo

or

    ./sak.tcl doc html modules/foo

to generate HTML for the documentation found in the module "foo"\. Instead of
__html__ any other supported format can be used here, of course\.

The generated formatted documentation will be placed into a directory "doc" in
the current working directory\.

## <a name='subsection18'></a>Generate documentation for all modules

Invoke the tool without a module name, i\.e\.

    ./sak.tcl doc html

to generate HTML for the documentation found in all modules\. Instead of
__html__ any other supported format can be used here, of course\.

The generated formatted documentation will be placed into a directory "doc" in
the current working directory\.

## <a name='subsection19'></a>Available output formats, help

Invoke the tool as

    ./sak.tcl help doc

to see the entire set of supported output formats which can be generated\.

## <a name='subsection20'></a>Validation without output

Note the special format __validate__\.

Using this value as the name of the format to generate forces the tool to simply
check that the documentation is syntactically correct, without generating actual
output\.

Invoke it as either

    ./sak.tcl doc validate (modules/)foo

or

    ./sak.tcl doc validate

to either check the packages of a specific module or check all of them\.

# <a name='section7'></a>Notes On Writing A Testsuite

While previous sections talked about running the testsuites for a module and the
packages therein, this has no meaning if the module in question has no
testsuites at all\.

This section gives a very basic overview on possible methodologies for writing
tests and testsuites\.

First there are "drudgery" tests\. Written to check absolutely basic assumptions
which should never fail\.

For example for a command FOO taking two arguments, three tests calling it with
zero, one, and three arguments\. The basic checks that the command fails if it
has not enough arguments, or too many\.

After that come the tests checking things based on our knowledge of the command,
about its properties and assumptions\. Some examples based on the graph
operations added during Google's Summer of Code 2009 are:

  - The BellmanFord command in struct::graph::ops takes a *startnode* as
    argument, and this node should be a node of the graph\. This equals one test
    case checking the behavior when the specified node is not a node of the
    graph\.

    This often gives rise to code in the implementation which explicitly checks
    the assumption and throws an understandable error, instead of letting the
    algorithm fail later in some weird non\-deterministic way\.

    It is not always possible to do such checks\. The graph argument for example
    is just a command in itself, and while we expect it to exhibit a certain
    interface, i\.e\. a set of sub\-commands aka methods, we cannot check that it
    has them, except by actually trying to use them\. That is done by the
    algorithm anyway, so an explicit check is just overhead we can get by
    without\.

  - IIRC one of the distinguishing characteristic of either BellmanFord and/or
    Johnson is that they are able to handle negative weights\. Whereas Dijkstra
    requires positive weights\.

    This induces \(at least\) three testcases \.\.\. Graph with all positive weights,
    all negative, and a mix of positive and negative weights\. Thinking further
    does the algorithm handle the weight __0__ as well ? Another test case,
    or several, if we mix zero with positive and negative weights\.

  - The two algorithms we are currently thinking about are about distances
    between nodes, and distance can be 'Inf'inity, i\.e\. nodes may not be
    connected\. This means that good test cases are

      1. Strongly connected graph

      1. Connected graph

      1. Disconnected graph\.

    At the extremes of strongly connected and disconnected we have the fully
    connected graphs and graphs without edges, only nodes, i\.e\. completely
    disconnected\.

  - IIRC both of the algorithms take weighted arcs, and fill in a default if
    arcs are left unweighted in the input graph\.

    This also induces three test cases:

      1. Graph will all arcs with explicit weights\.

      1. Graph without weights at all\.

      1. Graph with mixture of weighted and unweighted graphs\.

What was described above via examples is called *black\-box* testing\. Test
cases are designed and written based on the developer's knowledge of the
properties of the algorithm and its inputs, without referencing a particular
implementation\.

Going further, a complement to *black\-box* testing is *white\-box*\. For this
we know the implementation of the algorithm, we look at it and design our tests
cases so that they force the code through all possible paths in the
implementation\. Wherever a decision is made we have a test case forcing a
specific direction of the decision, for all possible combinations and
directions\. It is easy to get a combinatorial explosion in the number of needed
test\-cases\.

In practice I often hope that the black\-box tests I have made are enough to
cover all the paths, obviating the need for white\-box tests\.

The above should be enough to make it clear that writing tests for an algorithm
takes at least as much time as coding the algorithm, and often more time\. Much
more time\. See for example also
[http://sqlite\.org/testing\.html](http://sqlite\.org/testing\.html), a writeup
on how the Sqlite database engine is tested\. Another article of interest might
be
[https://www\.researchgate\.net/publication/298896236](https://www\.researchgate\.net/publication/298896236)\.
While geared to a particular numerical algorithm it still shows that even a
simple\-looking algorithm can lead to an incredible number of test cases\.

An interesting connection is to documentation\. In one direction, the properties
checked with black\-box testing are exactly the properties which should be
documented in the algorithm's man page\. And conversely, the documentation of the
properties of an algorithm makes a good reference to base the black\-box tests
on\.

In practice test cases and documentation often get written together,
cross\-influencing each other\. And the actual writing of test cases is a mix of
black and white box, possibly influencing the implementation while writing the
tests\. Like writing a test for a condition like *startnode not in input graph*
serving as reminder to put a check for this condition into the code\.

# <a name='section8'></a>Installation Tooling

A last thing to consider when adding a new package to the collection is
installation\.

How to *use* the "installer\.tcl" script is documented in *[Tcllib \- The
Installer's Guide](tcllib\_installer\.md)*\.

Here we document how to extend said installer so that it may install new
package\(s\) and/or application\(s\)\.

In most cases only a single file has to be modified, the
"support/installation/modules\.tcl" holding one command per module and
application to install\.

The relevant commands are:

  - <a name='1'></a>__[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action*

    Install the packages of module *name*, found in "modules/*name*"\.

    The *code\-action* is responsible for installing the packages and their
    index\. The system currently provides

      * __\_tcl__

        Copy all "\.tcl" files found in "modules/*name*" into the installation\.

      * __\_tcr__

        As __\_tcl__, copy the "\.tcl" files found in the subdirectories of
        "modules/*name*" as well\.

      * __\_tci__

        As __\_tcl__, and copy the "tclIndex\.tcl" file as well\.

      * __\_msg__

        As __\_tcl__, and copy the subdirectory "msgs" as well\.

      * __\_doc__

        As __\_tcl__, and copy the subdirectory "mpformats" as well\.

      * __\_tex__

        As __\_tcl__, and copy "\.tex" files as well\.

    The *doc\-action* is responsible for installing the package documentation\.
    The system currently provides

      * __\_null__

        No documentation available, do nothing\.

      * __\_man__

        Process the "\.man" files found in "modules/*name*" and install the
        results \(nroff and/or HTML\) in the proper location, as given to the
        installer\.

        This is actually a fallback, normally the installer uses the pre\-made
        formatted documentation found under "idoc"\.

    The *example\-action* is responsible for installing the examples\. The
    system currently provides

      * __\_null__

        No examples available, do nothing\.

      * __\_exa__

        Copy the the directory "examples/*name*" recursively to the install
        location for examples\.

  - <a name='2'></a>__[Application](\.\./\.\./\.\./index\.md\#application)__ *name*

    Install the application with *name*, found in "apps"\.

  - <a name='3'></a>__Exclude__ *name*

    This command signals to the installer which of the listed modules to *not*
    install\. I\.e\. they name the deprecated modules of Tcllib\.

If, and only if the above actions are not suitable for the new module then a
second file has to be modified, "support/installation/actions\.tcl"\.

This file contains the implementations of the available actions, and is the
place where any custom action needed to handle the special circumstances of
module has to be added\.

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






































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
[//000000001]: # (tcllib\_install\_guide \- )
[//000000002]: # (Generated from file 'tcllib\_installer\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_install\_guide\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_install\_guide \- Tcllib \- The Installer's Guide

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Requisites](#section2)

      - [Tcl](#subsection1)

      - [Critcl](#subsection2)

  - [Build & Installation Instructions](#section3)

      - [Installing on Unix](#subsection3)

      - [Installing on Windows](#subsection4)

      - [Critcl & Accelerators](#subsection5)

      - [Tooling](#subsection6)

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

The audience of this document is anyone wishing to build and install the
packages found in Tcllib, for either themselves, or others\.

For developers intending to work on the packages themselves we additionally
provide

  1. *[Tcllib \- The Developer's Guide](tcllib\_devguide\.md)*\.

Please read *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* first,
if that was not done already\. Here we assume that the sources are already
available in a directory of your choice\.

# <a name='section2'></a>Requisites

Before Tcllib can be build and used a number of requisites must be installed\.
These are:

  1. The scripting language Tcl\. For details see [Tcl](#subsection1)\.

  1. Optionally, the __critcl__ package \(C embedding\) for
     __[Tcl](\.\./\.\./\.\./index\.md\#tcl)__\. For details see __CriTcl__\.

This list assumes that the machine where Tcllib is to be installed is
essentially clean\. Of course, if parts of the dependencies listed below are
already installed the associated steps can be skipped\. It is still recommended
to read their sections though, to validate that the dependencies they talk about
are indeed installed\.

## <a name='subsection1'></a>Tcl

As we are installing a number of Tcl packages and applications it should be
pretty much obvious that a working installation of Tcl itself is needed, and I
will not belabor the point\.

Out of the many possibilities use whatever you are comfortable with, as long as
it provides at the very least Tcl 8\.2, or higher\. This may be a Tcl installation
provided by your operating system distribution, from a distribution\-independent
vendor, or built by yourself\.

*Note* that the packages in Tcllib have begun to require 8\.4, 8\.5, and even
8\.6\. Older versions of Tcl will not be able to use such packages\. Trying to use
them will result in *package not found* errors, as their package index files
will not register them in versions of the core unable to use them\.

Myself, I used \(and still use\) [ActiveState's](http://www\.activestate\.com)
ActiveTcl 8\.5 distribution during development, as I am most familiar with it\.

*\(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016,
maintaining ActiveTcl and TclDevKit for them\)\.*\. I am currently working for
SUSE Software Canada ULC, although not in Tcl\-related areas\.

This distribution can be found at
[http://www\.activestate\.com/activetcl](http://www\.activestate\.com/activetcl)\.
Retrieve the archive of ActiveTcl 8\.5 \(or higher\) for your platform and install
it as directed by ActiveState\.

For those wishing to build and install Tcl on their own, the relevant sources
can be found at

  - Tcl

    [http://core\.tcl\-lang\.org/tcl/](http://core\.tcl\-lang\.org/tcl/)

together with the necessary instructions on how to build it\.

If there are problems with building, installing, or using Tcl, please file a
ticket against *[Tcl](\.\./\.\./\.\./index\.md\#tcl)*, or the vendor of your
distribution, and *not* *[Tcllib](\.\./\.\./\.\./index\.md\#tcllib)*\.

## <a name='subsection2'></a>Critcl

The __critcl__ tool is an *optional* dependency\.

It is only required when trying to build the C\-based *accelerators* for a
number of packages, as explained in [Critcl & Accelerators](#subsection5)

Tcllib's build system looks for it in the , using the name __critcl__\. This
is for Unix\. On Windows on the other hand the search is more complex\. First we
look for a proper application __critcl\.exe__\. When that is not found we look
for a combination of interpreter \(__tclkitsh\.exe__, __tclsh\.exe__\) and
starkit \(__critcl\.kit__, __critcl__\) instead\. *Note* that the choice
of starkit can be overriden via the environment variable \.

Tcllib requires Critcl version 2 or higher\.

The github repository providing releases of version 2 and higher, and the
associated sources, can be found at
[http://andreas\-kupries\.github\.com/critcl](http://andreas\-kupries\.github\.com/critcl)\.

Any branch of the repository can be used \(if not using the prebuild starkit or
starpack\), although the use of the stable branch *master* is recommended\.

At the above url is also an explanation on how to build and install Critcl,
including a list of its dependencies\.

Its instructions will not be repeated here\. If there are problems with these
directions please file a ticket against the *Critcl* project, and not Tcllib\.

# <a name='section3'></a>Build & Installation Instructions

As Tcllib is mainly a bundle of packages written in pure Tcl building it is the
same as installing it\. The exceptions to this have their own subsection,
[Critcl & Accelerators](#subsection5), later on\.

Before that however comes the standard case, differentiated by the platforms
with material differences in the instruction, i\.e\. *Unix*\-like, versus
*Windows*\.

Regarding the latter it should also be noted that it is possible set up an
*Unix*\-like environment using projects like *MSYS*, *Cygwin*, and others\.
In that case the user has the choice of which instructions to follow\.

Regardless of environment or platform, a suitable
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* has to be installed, and its __tclsh__
should be placed on the \(*Unix*\) or associated with "\.tcl" files
\(*Windows*\)\.

## <a name='subsection3'></a>Installing on Unix

For *Unix*\-like environments Tcllib comes with the standard set of files to
make

    ./configure
    make install

a suitable way of installing it\. This is a standard non\-interactive install
automatically figuring out where to place everything, i\.e\. packages,
applications, and the manpages\.

To get a graphical installer invoke

    ./installer.tcl

instead\.

## <a name='subsection4'></a>Installing on Windows

In a Windows environment we have the __installer\.tcl__ script to perform
installation\.

If the desired __tclsh__ is associated "\.tcl" files then double\-clicking /
opening the __installer\.tcl__ is enough to invoke it in graphical mode\. This
assumes that *[Tk](\.\./\.\./\.\./index\.md\#tk)* is installed and available as
well\.

Without *[Tk](\.\./\.\./\.\./index\.md\#tk)* the only way to invoke the installer
are to open a DOS window, i\.e\. __cmd\.exe__, and then to invoke

    ./installer.tcl

inside it\.

## <a name='subsection5'></a>Critcl & Accelerators

While the majority of Tcllib consists of packages written in pure Tcl a number
of packages also have *accelerators* associated with them\. These are
__critcl__\-based C packages whose use will boost the performance of the
packages using them\. These accelerators are optional, and they are not installed
by default\.

To build the accelerators the normally optional dependency on __critcl__
becomes required\.

To build and install Tcllib with the accelerators in a Unix\-like environment
invoke:

    ./configure
    make critcl # This builds the shared library holding
                # the accelerators
    make install

The underlying tool is "sak\.tcl" in the toplevel directory of Tcllib and the
command __make critcl__ is just a wrapper around

    ./sak.tcl critcl

Therefore in a Windows environment instead invoke

    ./sak.tcl critcl
    ./installer.tcl

from within a DOS window, i\.e\. __cmd\.exe__\.

## <a name='subsection6'></a>Tooling

The core of Tcllib's build system is the script "installer\.tcl" found in the
toplevel directory of a checkout or release\.

The

    configure ; make install

setup available to developers on Unix\-like systems is just a wrapper around it\.
To go beyond the standard embodied in the wrapper it is necessary to directly
invoke this script\.

On Windows system using it directly is the only way to invoke it\.

For basic help invoke it as

    ./installer.tcl -help

This will print a short list of all the available options to the standard output
channel\.

The commands associated with the various *install* targets in the
*Makefile\.in* for Unix can be used as additional examples on how to use this
tool as well\.

The installer can operate in GUI and CLI modes\. By default it chooses the mode
automatically, based on if the Tcl package
__[Tk](\.\./\.\./\.\./index\.md\#tk)__ can be used or not\. The option
__\-no\-gui__ can be used to force CLI mode\.

Note that it is possible to specify options on the command line even if the
installer ultimatively selects GUI mode\. In that case the hardwired defaults and
the options determine the data presented to the user for editing\.

The installer will select a number of defaults for the locations of packages,
examples, and documentation, and also the format of the documentation\. The user
can overide these defaults in the GUI, or by specifying additional options\. The
defaults depend on the platform detected \(Unix/Windows\) and on the __tclsh__
executable used to run the installer\.

*Options*

  - __\-help__

    Show the list of options explained here on the standard output channel and
    exit\.

  - __\+excluded__

    Include deprecated packages in the installation\.

  - __\-no\-gui__

    Force command line operation of the installer

  - __\-no\-wait__

    In CLI mode the installer will by default ask the user to confirm that the
    chosen configuration \(destination paths, things to install\) is correct
    before performing any action\. Using this option causes the installer to skip
    this query and immediately jump to installation\.

  - __\-app\-path__ *path*

  - __\-example\-path__ *path*

  - __\-html\-path__ *path*

  - __\-nroff\-path__ *path*

  - __\-pkg\-path__ *path*

    Declare the destination paths for the applications, examples, html
    documentation, nroff manpages, and packages\. The defaults are derived from
    the location of the __tclsh__ used to run the installer\.

  - __\-dry\-run__

  - __\-simulate__

    Run the installer without modifying the destination directories\.

  - __\-apps__

  - __\-no\-apps__

  - __\-examples__

  - __\-no\-examples__

  - __\-pkgs__

  - __\-no\-pkgs__

  - __\-html__

  - __\-no\-html__

  - __\-nroff__

  - __\-no\-nroff__

    \(De\)activate the installation of applications, examples, packages, html
    documentation, and nroff manpages\.

    Applications, examples, and packages are installed by default\.

    On Windows the html documentation is installed by default\.

    On Unix the nroff manpages are installed by default\.

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










































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
[//000000001]: # (tcllib\_license \- )
[//000000002]: # (Generated from file 'tcllib\_license\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_license\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_license \- Tcllib \- License

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [License](#section2)

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

The collection is under the BSD license\.

# <a name='section2'></a>License

This software is copyrighted by Ajuba Solutions and other parties\. The following
terms apply to all files associated with the software unless explicitly
disclaimed in individual files\.

The authors hereby grant permission to use, copy, modify, distribute, and
license this software and its documentation for any purpose, provided that
existing copyright notices are retained in all copies and that this notice is
included verbatim in any distributions\. No written agreement, license, or
royalty fee is required for any of the authorized uses\. Modifications to this
software may be copyrighted by their authors and need not follow the licensing
terms described here, provided that the new terms are clearly indicated on the
first page of each file where they apply\.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE
AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE\.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NON\-INFRINGEMENT\. THIS SOFTWARE IS PROVIDED ON AN "AS
IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS\.

GOVERNMENT USE: If you are acquiring this software on behalf of the U\.S\.
government, the Government shall have only "Restricted Rights" in the software
and related documentation as defined in the Federal Acquisition Regulations
\(FARs\) in Clause 52\.227\.19 \(c\) \(2\)\. If you are acquiring the software on behalf
of the Department of Defense, the software shall be classified as "Commercial
Computer Software" and the Government shall have only "Restricted Rights" as
defined in Clause 252\.227\-7013 \(c\) \(1\) of DFARs\. Notwithstanding the foregoing,
the authors grant the U\.S\. Government and others acting in its behalf permission
to use and distribute the software in accordance with the terms specified in
this license\.

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
























































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
[//000000001]: # (tcllib\_releasemgr \- )
[//000000002]: # (Generated from file 'tcllib\_releasemgr\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_releasemgr\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_releasemgr \- Tcllib \- The Release Manager's Guide

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Tools](#section2)

  - [Tasks](#section3)

      - [Start a release candidate](#subsection1)

      - [Ready the candidate](#subsection2)

      - [Make it official](#subsection3)

      - [Distribute the release](#subsection4)

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

The audience of this document is the release manager for Tcllib, their deputies,
and anybody else interested in the task of creating an official release of
Tcllib for distribution\.

Please read *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* first,
if that was not done already\. Here we assume that the sources are already
available in a directory of your choice\.

# <a name='section2'></a>Tools

The "sak\.tcl" script in the toplevel directory of a Tcllib checkout is the one
tool used by the release manager to perform its [Tasks](#section3)\.

The main commands to be used are

    sak.tcl validate
    sak.tcl test run
    sak.tcl review
    sak.tcl readme
    sak.tcl localdoc
    sak.tcl release

More detail will be provided in the explanations of the various
[Tasks](#section3)\.

# <a name='section3'></a>Tasks

## <a name='subsection1'></a>Start a release candidate

todo: open a candidate for release

## <a name='subsection2'></a>Ready the candidate

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

## <a name='subsection3'></a>Make it official

todo: finalize release, make candidate official

## <a name='subsection4'></a>Distribute the release

With the release made it has to be published and the world notified of its
existence\.

  1. Create a proper fossil event for the release, via
     [http://core\.tcl\-lang\.org/tcllib/eventedit](http://core\.tcl\-lang\.org/tcllib/eventedit)\.

     An [existing
     event](http://core\.tcl\-lang\.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817)
     should be used as template\.

  1. Update a number of web locations:

       1) [Home
          page](http://core\.tcl\-lang\.org/tcllib/doc/trunk/embedded/index\.md)

       1) [Downloads](http://core\.tcl\-lang\.org/tcllib/wiki?name=Downloads)

       1) [Past
          Releases](http://core\.tcl\-lang\.org/tcllib/wiki?name=Past\+Releases)

       1) [http://www\.tcl\-lang\.org/home/release\.txt](http://www\.tcl\-lang\.org/home/release\.txt)

       1) [http://www\.tcl\-lang\.org/software/tcllib/\*\.tml](http://www\.tcl\-lang\.org/software/tcllib/\*\.tml)

       1) [http://wiki\.tcl\-lang\.org/page/Tcllib](http://wiki\.tcl\-lang\.org/page/Tcllib)

     The first location maps to the file "embedded/index\.md" in the repository
     itself, as such it can edited as part of the release process\. This is where
     reference to the new fossil event is added, as the new current release\.

     The next two locations are in the fossil tcllib wiki and require admin or
     wiki write permissions for
     [http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib)\.

     The last two locations require ssh access to
     [http://www\.tcl\-lang\.org](http://www\.tcl\-lang\.org) and permission to
     edit files in the web area\.

  1. \*\*\*TODO\*\*\* mailing lists and other places to send notes to\.

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










































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
[//000000001]: # (tcllib\_sources \- )
[//000000002]: # (Generated from file 'tcllib\_sources\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_sources\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_sources \- Tcllib \- How To Get The Sources

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Source Location](#section2)

  - [Retrieval](#section3)

  - [Source Code Management](#section4)

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

The audience of this document is anyone wishing to either have just a look at
Tcllib's source code, or build the packages, or to extend and modify them\.

For builders and developers we additionally provide

  1. *[Tcllib \- The Installer's Guide](tcllib\_installer\.md)*\.

  1. *[Tcllib \- The Developer's Guide](tcllib\_devguide\.md)*\.

respectively\.

# <a name='section2'></a>Source Location

The official repository for Tcllib can be found at
[http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib)

# <a name='section3'></a>Retrieval

Assuming that you simply wish to look at the sources, or build a specific
revision, the easiest way of retrieving it is to:

  1. Log into this site, as "anonymous", using the semi\-random password in the
     captcha\.

  1. Go to the "Timeline"\.

  1. Choose the revision you wish to have\.

  1. Follow its link to its detailed information page\.

  1. On that page, choose either the "ZIP" or "Tarball" link to get a copy of
     this revision in the format of your choice\.

# <a name='section4'></a>Source Code Management

For the curious \(or a developer\-to\-be\), the sources are managed by the [Fossil
SCM](http://www\.fossil\-scm\.org)\. Binaries for popular platforms can be found
directly at its [download page](http://www\.fossil\-scm\.org/download\.html)\.

With that tool available the full history can be retrieved via:

    fossil clone  http://core.tcl-lang.org/tcllib  tcllib.fossil

followed by

    mkdir tcllib
    cd tcllib
    fossil open ../tcllib.fossil

to get a checkout of the head of the trunk\.

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

92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
...
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
    [keywords {doctools language}]
    [keywords {doctools markup}]
    [keywords {doctools syntax}]
    [keywords markup]
    [keywords {semantic markup}]
        [description]
        [vset CATEGORY doctools]
    [include ../doctools2base/include/feedback.inc]
    [manpage_end]

This also shows us that all doctools documents are split into two parts, the
*header* and the *body*\. Everything coming before \[__description__\]
belongs to the header, and everything coming after belongs to the body, with the
whole document bracketed by the two __manpage\_\*__ commands\. Before and after
these opening and closing commands we have only *whitespace*\.
................................................................................

Remember that the whitespace is optional\. The document

        [manpage_begin NAME SECTION VERSION]
        [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
        [require PACKAGE VERSION][require PACKAGE][description]
        [vset CATEGORY doctools]
    [include ../doctools2base/include/feedback.inc]
    [manpage_end]

has the same meaning as the example before\.

On the other hand, if *whitespace* is present it consists not only of any
sequence of characters containing the space character, horizontal and vertical
tabs, carriage return, and newline, but it may contain comment markup as well,






|







 







|







92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
...
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
    [keywords {doctools language}]
    [keywords {doctools markup}]
    [keywords {doctools syntax}]
    [keywords markup]
    [keywords {semantic markup}]
        [description]
        [vset CATEGORY doctools]
    [include ../common-text/feedback.inc]
    [manpage_end]

This also shows us that all doctools documents are split into two parts, the
*header* and the *body*\. Everything coming before \[__description__\]
belongs to the header, and everything coming after belongs to the body, with the
whole document bracketed by the two __manpage\_\*__ commands\. Before and after
these opening and closing commands we have only *whitespace*\.
................................................................................

Remember that the whitespace is optional\. The document

        [manpage_begin NAME SECTION VERSION]
        [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
        [require PACKAGE VERSION][require PACKAGE][description]
        [vset CATEGORY doctools]
    [include ../common-text/feedback.inc]
    [manpage_end]

has the same meaning as the example before\.

On the other hand, if *whitespace* is present it consists not only of any
sequence of characters containing the space character, horizontal and vertical
tabs, carriage return, and newline, but it may contain comment markup as well,

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

711
712
713
714
715
716
717


718
719
720
721
722
723




724
725






726
727
728
729
730
731
732
  - [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption

  - [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal

  - [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression



  - [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers

  - [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers

  - [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor





  - [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation







  - [tclrep/machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\.

  - [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager

  - [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual

  - [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md) TEPAM DOC Generation, reference manual






>
>






>
>
>
>


>
>
>
>
>
>







711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
  - [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption

  - [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal

  - [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression

  - [tcl\_community\_communication](tcllib/files/devdoc/tcl\_community\_communication\.md) Tcl Community \- Kind Communication

  - [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers

  - [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers

  - [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor

  - [tcllib\_devguide](tcllib/files/devdoc/tcllib\_devguide\.md) Tcllib \- The Developer's Guide

  - [tcllib\_install\_guide](tcllib/files/devdoc/tcllib\_installer\.md) Tcllib \- The Installer's Guide

  - [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation

  - [tcllib\_license](tcllib/files/devdoc/tcllib\_license\.md) Tcllib \- License

  - [tcllib\_releasemgr](tcllib/files/devdoc/tcllib\_releasemgr\.md) Tcllib \- The Release Manager's Guide

  - [tcllib\_sources](tcllib/files/devdoc/tcllib\_sources\.md) Tcllib \- How To Get The Sources

  - [tclrep/machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\.

  - [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager

  - [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual

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

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






















































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
'\"
'\" Generated from file 'tcllib_devguide\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "tcllib_devguide" n 1 tcllib ""
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.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
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
tcllib_devguide \- Tcllib - The Developer's Guide
.SH SYNOPSIS
\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR
.sp
\fBApplication\fR \fIname\fR
.sp
\fBExclude\fR \fIname\fR
.sp
.BE
.SH DESCRIPTION
Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a
package itself\&. It is a collection of (semi-independent) \fITcl\fR
packages that provide utility functions useful to a large collection
of Tcl programmers\&.
.PP
This document is a guide for developers working on Tcllib,
i\&.e\&. maintainers fixing bugs, extending the collection's
functionality, etc\&.
.PP
Please read
.IP [1]
\fITcllib - How To Get The Sources\fR and
.IP [2]
\fITcllib - The Installer's Guide\fR
.PP
first, if that was not done already\&.
.PP
Here we assume that the sources are already available in a
directory of your choice, and that you not only know how to build and
install them, but also have all the necessary requisites to actually
do so\&. The guide to the sources in particular also explains which
source code management system is used, where to find it, how to set it
up, etc\&.
.SH COMMITMENTS
.SS CONTRIBUTOR
As a contributor to Tcllib you are committing yourself to:
.IP [1]
keep the guidelines written down in
\fITcl Community - Kind Communication\fR in your mind\&.
The main point to take away from there is
\fIto be kind to each other\fR\&.
.IP [2]
Your contributions getting distributed under a BSD/MIT license\&.
For the details see \fITcllib - License\fR
.PP
Contributions are made by entering tickets into our tracker, providing
patches, bundles or branches of code for inclusion, or posting to the
Tcllib related mailing lists\&.
.SS MAINTAINER
When contributing one or more packages for full inclusion into Tcllib
you are committing yourself to
.IP [1]
Keep the guidelines written down in
\fITcl Community - Kind Communication\fR
(as any contributor) in your mind\&. The main point to take away
from there is \fIto be kind to each other\fR\&.
.IP [2]
Your packages getting distributed under a BSD/MIT license\&.  For
the details see \fITcllib - License\fR
.IP [3]
Maintenance of the new packages for a period of two years under
the following rules, and responsibilities:
.RS
.IP [1]
A maintainer may step down after the mandatory period as
they see fit\&.
.IP [2]
A maintainer may step down before the end of the
mandatory period, under the condition that a replacement
maintainer is immediately available and has agreed to
serve the remainder of the period, plus their own
mandatory period (see below)\&.
.IP [3]
When stepping down without a replacement maintainer
taking over the relevant packages have to be flagged as
\fBunmaintained\fR\&.
.IP [4]
When a replacement mantainer is brought in for a package
it is (kept) marked as \fBmaintained\fR (again)\&.
.sp
A replacement maintainer is bound by the same rules as
the original maintainer, except that the mandatory
period of maintenance is shortened to one year\&.
.IP [5]
For any \fBunmaintained\fR package a contributor
interested in becoming its maintainer can become so by
flagging them as \fBmaintained\fR with their name and
contact information, committing themselves to the rules
of a replacement maintainer (see previous point)\&.
.IP [6]
For any already \fBmaintained\fR package a contributor
interested in becoming a co-maintainer can become so
with the agreement of the existing maintainer(s),
committing themselves to the rules of a replacement
maintainer (see two points previous)\&.
.RE
.sp
The responsibilities as a maintainer include:
.RS
.IP [1]
Watching Tcllib's ticket tracker for bugs, bug fixes,
and feature requests related to the new packages\&.
.IP [2]
Reviewing the aforementioned tickets, rejecting or
applying them
.IP [3]
Coordination and discussion with ticket submitter during
the development and/or application of bug fixes\&.
.RE
.IP [4]
Follow the \fBBranching and Workflow\fR of this guide\&.
.PP
.SH "BRANCHING AND WORKFLOW"
.SS "PACKAGE DEPENDENCIES"
Regarding packages and dependencies between them Tcllib occupies a
middle position between two extremes:
.IP [1]
On one side a strongly interdependent set of packages, usually
by a single author, for a single project\&. Looking at my
(Andreas Kupries) own work examples of such are
\fIMarpa\fR [https://core\&.tcl\&.tk/akupries/marpa/index],
\fICRIMP\fR [https://core\&.tcl\&.tk/akupries/crimp/index],
\fIKinetcl\fR [https://core\&.tcl\&.tk/akupries/kinetcl/index], etc\&.
.sp
For every change the author of the project handles all the
modifications cascading from any incompatibilities it
introduced to the system\&.
.IP [2]
On the other side, the world of semi-independent projects by
many different authors where authors know what packages their
own creations depend on, yet usually do not know who else
depends on them\&.
.sp
The best thing an author making an (incompatible) change to
their project can do is to for one announce such changes in
some way, and for two use versioning to distinguish the code
before and after the change\&.
.sp
The world is then responsible for adapting, be it by updating
their own projects to the new version, or by sticking to the
old\&.
.PP
As mentioned already, Tcllib lives in the middle of that\&.
.PP
While we as maintainers cannot be aware of all users of
Tcllib's packages, and thus have to rely on the mechanisms
touched on in point 2 above for that, the dependencies between
the packages contained in Tcllib are a different matter\&.
.PP
As we are collectively responsible for the usability of Tcllib
in toto to the outside world, it behooves us to be individually
mindful even of Tcllib packages we are not directly
maintaining, when they depend on packages under our
maintainership\&.
This may be as simple as coordinating with the maintainers of
the affected packages\&.
It may also require us to choose how to adapt affected packages
which do not have maintainers, i\&.e\&. modify them to use our
changed package properly, or modify them to properly depend on
the unchanged version of our package\&.
.PP
Note that the above is not only a chore but an opportunity as
well\&.
Additional insight can be had by forcing ourselves to look at
our package and the planned change(s) from an outside
perspective, to consider the ramifications of our actions on
others in general, and on dependent packages in particular\&.
.SS TRUNK
The management and use of branches is an important part of working
with a \fIDistributed Version Control System\fR (\fIDVCS\fR) like
\fIfossil\fR [https://www\&.fossil-scm\&.org/]\&.
.PP
For Tcllib the main branch of the collection is
\fItrunk\fR\&. In \fIgit\fR this branch would be called
\fImaster\fR, and this is exactly the case in the
\fIgithub mirror\fR [https://github\&.com/tcltk/tcllib/] of
Tcllib\&.
.PP
To properly support debugging \fIeach commit\fR on this
branch \fIhas to pass the entire testsuite\fR of the
collection\&. Using bisection to determine when an issue appeared
is an example of an action made easier by this constraint\&.
.PP
This is part of our collective responsibility for the usability
of Tcllib in toto to the outside world\&.
As \fIfossil\fR has no mechanism to enforce this condition
this is handled on the honor system for developers and maintainers\&.
.PP
To make the task easier Tcllib comes with a tool
("\fIsak\&.tcl\fR") providing a number of commands in
support\&. These commands are explained in the following sections
of this guide\&.
.PP
While it is possible and allowed to commit directly to trunk
remember the above constraint regarding the testsuite, and the
coming notes about other possible issues with a commit\&.
.SS BRANCHES
Given the constraints placed on the \fItrunk\fR branch of the
repository it is (strongly) recommended to perform any development
going beyond trivial changes on a non-trunk branch\&.
.PP
Outside of the trunk developers are allowed to commit
intermediate broken states of their work\&.
Only at the end of a development cycle, when the relevant
branch is considered ready for merging, will it be necessary to
perform full the set of validations ensuring that the merge to
come will create a good commit on trunk\&.
.PP
Note that while a review from a second developer is not a
required condition for merging a branch it is recommended to
seek out such an independent opinion as a means of
cross-checking the work\&.
.PP
It also recommended to give any new branch a name which aids in
determining additional details about it\&. Examples of good
things to stick into a branch name would be
.IP \(bu
Developer (nick)name
.IP \(bu
Ticket hash/reference
.IP \(bu
One or two keywords applicable to the work
.IP \(bu
\&.\&.\&.
.PP
.PP
Further, while most development branches are likely quite
short-lived, no prohibitions exist against making longer-lived
branches\&.
Creators should however be mindful that the longer such a
branch exists without merges the more divergent they will tend
to be, with an associated increase in the effort which will
have to be spent on either merging from and merging to trunk\&.
.SS "WORKING WITH BRANCHES"
In the hope of engendering good work practices now a few example
operations which will come up with branches, and their associated
fossil command (sequences)\&.
.TP
\fIAwareness\fR
When developing we have to keep ourselves aware of the context of our
work\&. On what branch are we ? What files have we changed ? What new
files are not yet known to the repository ? What has happened remotely
since we used our checkout ?
The answers to these questions become especially important when using
a long-lived checkout and coming back to it after some time away\&.
.sp
Commands to answer questions like the above are:
.RS
.TP
\fBfossil pull\fR
Get all changes done on the remote since the last pull or sync
from it\&. This has to be done first, before any of the commands
below\&.
.sp
Even if the commit in our checkout refers to the branch we want
right now control operations committed to the remote may have
changed that from underneath us\&.
.TP
\fBfossil info | grep tags\fR
.TP
\fBfossil branch list | grep '\\*'\fR
Two different ways of determining the branch our checkout is
on\&.
.TP
\fBfossil timeline\fR
What have we (and others) done recently ?
.sp
\fIAttention\fR, this information is very likely outdated, the
more the longer we did not use this checkout\&.
Run \fBfossil pull\fR first to get latest information from
the remote repository of the project\&.
.TP
\fBfossil timeline current\fR
Place the commit our checkout is based on at the top of the
timeline\&.
.TP
\fBfossil changes\fR
Lists the files we have changed compared to the commit the
checkout is based on\&.
.TP
\fBfossil extra\fR
Lists the files we have in the checkout the repository does not
know about\&. This may be leftover chaff from our work, or
something we have forgotten to \fBfossil add\fR to the
repository yet\&.
.RE
.TP
\fIClean checkouts\fR
Be aware of where you are (see first definition)\&.
.sp
For pretty much all the operation recipes below a clean
checkout is at least desired, often required\&.
To check that a checkout is clean invoke
.CS


    fossil changes
    fossil extra

.CE
.IP
How to clean up when uncommitted changes of all sorts are found is
context-specific and outside of the scope of this guide\&.
.TP
\fIStarting a new branch\fR
Be aware of where you are (see first definition)\&.
.sp
Ensure that you have clean checkout (see second definition)\&.
It is \fIrequired\fR\&.
.sp
In most situations you want to be on branch \fItrunk\fR, and
you want to be on the latest commit for it\&. To get there use
.CS


    fossil pull
    fossil update trunk

.CE
.IP
If some other branch is desired as the starting point for the coming
work replace \fItrunk\fR in the commands above with the name of that
branch\&.
.sp
With the base line established we now have two ways of creating
the new branch, with differing (dis)advantages\&.
The simpler way is to
.CS


    fossil branch new NAME_OF_NEW_BRANCH

.CE
.IP
and start developing\&. The advantage here is that you cannot forget to
create the branch\&. The disadvantages are that we have a branch commit
unchanged from where we branched from, and that we have to use
high-handed techniques like hiding or shunning to get rid of the
commit should we decide to abandon the work before the first actual
commit on the branch\&.
.sp
The other way of creating the branch is to start developing,
and then on the first commit use the option \fB--branch\fR to tell
\fBfossil\fR that we are starting a branch now\&. I\&.e\&. run
.CS


    fossil commit --branch NAME_OF_NEW_BRANCH \&.\&.\&.

.CE
.IP
where \fI\&.\&.\&.\fR are any other options used to supply the commit
message, files to commit, etc\&.
.sp
The (dis)advantages are now reversed\&.
.sp
We have no superflous commit, only what is actually
developed\&. The work is hidden until we commit to make our first
commit\&.
.sp
We may forget to use \fB--branch NAME_OF_NEW_BRANCH\fR and
then have to correct that oversight via the fossil web
interface (I am currently unaware of ways of doing such from
the command line, although some magic incantantion of
\fBfossil tag create\fR may work)\&.
.sp
It helps to keep awareness, like checking before any commit
that we are on the desired branch\&.
.TP
\fIMerging a branch into trunk\fR
Be aware of where you are (see first definition)\&.
.sp
Ensure that you have clean checkout (see second definition)\&.
In the full-blown sequence (zig-zag) it is \fIrequired\fR, due
to the merging from trunk\&. In the shorter sequence it is only
desired\&. That said, keeping the checkout clean before
any major operations is a good habit to have, in my opinion\&.
.sp
The full-blown sequencing with checks all the way is to
.RS
.IP [1]
Validate the checkout, i\&.e\&. last commit on your branch\&. Run the
full test suite and other validations, fix all the issues which
have cropped up\&.
.IP [2]
Merge the latest state of the \fItrunk\fR (see next definition)\&.
.IP [3]
Validate the checkout again\&. The incoming trunk changes may
have broken something now\&. Do any required fixes\&.
.IP [4]
Now merge to the trunk using
.CS


    fossil update trunk
    fossil merge --integrate YOUR_BRANCH

.CE
.IP [5]
At this point the checkout should be in the same state as at
the end of point (3) above, because we resolved any issues with
the trunk already\&. Thus a simple
.CS


    fossil commit \&.\&.\&.

.CE
.IP
should be sufficient now to commit the merge back and close the
branch (due to the \fB--integrate\fR we used on the merge)\&.
.sp
The more paranoid may validate the checkout a third time before
commiting\&.
.RE
.sp
I call this a \fIzig-zag merge\fR because of how the arrows
look in the timeline, from trunk to feature branch for the
first merge, and then back for the final merge\&.
.sp
A less paranoid can do what I call a \fIsimple merge\fR,
which moves step (2) after step (4) and skips step (3)
entirely\&. The resulting shorter sequence is
.RS
.IP [1]
Validate
.IP [2]
Merge to trunk
.IP [3]
Validate again
.IP [4]
Commit to trunk
.RE
.IP
The last step after either zig-zag or plain merge is to
.CS


    fossil sync

.CE
.IP
This saves our work to the remote side, and further gives us any other
work done while we were doing our merge\&. It especially allows us to
check if we raced somebody else, resulting in a split trunk\&.
.sp
When that happens we should coordinate with the other developer
on who fixes the split, to ensure that we do not race each
other again\&.
.TP
\fIMerging from trunk\fR
Be aware of where you are (see first definition)\&.
.sp
Ensure that you have clean checkout (see second definition)\&.
It is \fIrequired\fR\&.
.sp
In most situations you want to import the latest commit of
branch \fItrunk\fR (or other origin)\&. To get it use
.CS


    fossil pull

.CE
.sp
With that done we can now import this commit into our current
branch with
.CS


    fossil merge trunk

.CE
.sp
Even if \fBfossil\fR does not report any conflicts it is a
good idea to check that the operation has not broken the new
and/or changed functionality we are working on\&.
.sp
With the establishment of a good merge we then save the state
with
.CS


    fossil commit \&.\&.\&.

.CE
.IP
before continuing development\&.
.PP
.SS "VERSION NUMBERS"
In Tcllib all changes to a package have to come with an increment of
its version number\&. What part is incremented (patchlevel, minor, major
version) depends on the kind of change made\&. With multiple changes in
a commit the highest "wins"\&.
.PP
When working in a development branch the version change can be
deferred until it is time to merge, and then has to cover all
the changes in the branch\&.
.PP
Below a list of the kinds of changes and their associated
version increments:
.TP
\fID - documentation\fR
No increment
.TP
\fIT - testsuite\fR
No increment
.TP
\fIB - bugfix\fR
Patchlevel
.TP
\fII - implementation tweak\fR
Patchlevel
.TP
\fIP - performance tweak\fR
Patchlevel
.TP
\fIE - backward-compatible extension\fR
Minor
.TP
\fIAPI - incompatible change\fR
Major
.PP
.PP
Note that a commit containing a version increment has to
mention the new version number in its commit message, as well
as the kind of change which caused it\&.
.PP
Note further that the version number of a package currently
exists in three places\&. An increment has to update all of them:
.IP [1]
The package implementation\&.
.IP [2]
The package index ("\fIpkgIndex\&.tcl\fR")
.IP [3]
The package documentation\&.
.PP
.PP
The "\fIsak\&.tcl\fR" command \fBvalidate version\fR helps
finding discrepancies between the first two\&.
All the other \fBvalidate\fR methods are also of interest to
any developer\&. Invoke it with
.CS

 sak\&.tcl help validate
.CE
to see their documentation\&.
.SH "STRUCTURAL OVERVIEW"
.SS "MAIN DIRECTORIES"
The main directories in the Tcllib toplevel directory and of interest
to a developer are:
.TP
"\fImodules\fR"
Each child directory represents one or more packages\&.
In the case of the latter the packages are usually related in some
way\&. Examples are "\fIbase64\fR", "\fImath\fR", and "\fIstruct\fR", with
loose (base64) to strong (math) relations between the packages in the
directory\&.
.TP
"\fIapps\fR"
This directory contains all the installable applications, with their
documentation\&. Note that this directory is currently \fInot\fR split
into sub-directories\&.
.TP
"\fIexamples\fR"
Each child directory "\fIfoo\fR" contains one or more example
application for the packages in "\fImodules/foo\fR"\&. These examples are
generally not polished enough to be considered for installation\&.
.PP
.SS "MORE DIRECTORIES"
.TP
"\fIconfig\fR"
This directory contains files supporting the Unix build system,
i\&.e\&. "\fIconfigure\fR" and "\fIMakefile\&.in\fR"\&.
.TP
"\fIdevdoc\fR"
This directories contains the doctools sources for the global
documentation, like this document and its sibling guides\&.
.TP
"\fIembedded\fR"
This directory contains the entire documentation formatted for
\fIHTML\fR and styled to properly mix into the web site generated by
fossil for the repository\&.
.sp
This is the documentation accessible from the Tcllib home
directory, represented in the repository as "\fIembedded/index\&.md\fR"\&.
.TP
"\fIidoc\fR"
This directory contains the entire documentation formatted for
\fInroff\fR and \fIHTML\fR, the latter without any styling\&.
This is the documentation which will be installed\&.
.TP
"\fIsupport\fR"
This directory contains the sources of internal packages and utilities
used in the implementation of the "\fIinstaller\&.tcl\fR" and
"\fIsak\&.tcl\fR" scripts/tools\&.
.PP
.SS "TOP FILES"
.TP
"\fIaclocal\&.m4\fR"
.TP
"\fIconfigure\fR"
.TP
"\fIconfigure\&.in\fR"
.TP
"\fIMakefile\&.in\fR"
These four files comprise the Unix build system layered on top of the
"\fIinstaller\&.tcl\fR" script\&.
.TP
"\fIinstaller\&.tcl\fR"
The Tcl-based installation script/tool\&.
.TP
"\fIproject\&.shed\fR"
Configuration file for \fISean Wood\fR's \fBPracTcl\fR
buildsystem\&.
.TP
"\fIsak\&.tcl\fR"
This is the main tool for developers and release managers, the
\fISwiss Army Knife\fR of management operations on the collection\&.
.TP
"\fIChangeLog\fR"
The log of changes to the global support, when the sources were held
in \fICVS\fR\&. Not relevant any longer with the switch to the
\fIfossil\fR SCM\&.
.TP
"\fIlicense\&.terms\fR"
The license in plain ASCII\&. See also \fITcllib - License\fR for the
nicely formatted form\&. The text is identical\&.
.TP
"\fIREADME\&.md\fR"
.TP
"\fI\&.github/CONTRIBUTING\&.md\fR"
.TP
"\fI\&.github/ISSUE_TEMPLATE\&.md\fR"
.TP
"\fI\&.github/PULL_REQUEST_TEMPLATE\&.md\fR"
These markdown-formatted documents are used and shown by the github
mirror of these sources, pointing people back to the official location
and issue trackers\&.
.TP
"\fIDESCRIPTION\&.txt\fR"
.TP
"\fISTATUS\fR"
.TP
"\fItcllib\&.spec\fR"
.TP
"\fItcllib\&.tap\fR"
.TP
"\fItcllib\&.yml\fR"
????
.PP
.SS "FILE TYPES"
The most common file types, by file extension, are:
.TP
"\fI\&.tcl\fR"
Tcl code for a package, application, or example\&.
.TP
"\fI\&.man\fR"
Doctools-formatted documentation, usually for a package\&.
.TP
"\fI\&.test\fR"
Test suite for a package, or part of\&.
Based on \fBtcltest\fR\&.
.TP
"\fI\&.bench\fR"
Performance benchmarks for a package, or part of\&.
Based on "\fImodules/bench\fR"\&.
.TP
"\fI\&.pcx\fR"
Syntax rules for \fITclDevKit\fR's \fBtclchecker\fR\&. Using these
rules allows the checker to validate the use of commands of a Tcllib
package \fBfoo\fR without having to scan the "\fI\&.tcl\fR" files
implementing it\&.
.PP
.SH "TESTSUITE TOOLING"
Testsuites in Tcllib are based on Tcl's standard test package
\fBtcltest\fR, plus utilities found in the directory
"\fImodules/devtools\fR"
.PP
Tcllib developers invoke the suites through the
\fBtest run\fR method of the "\fIsak\&.tcl\fR" tool, with other methods
of \fBtest\fR providing management operations, for example setting a
list of standard Tcl shells to use\&.
.SS "INVOKE THE TESTSUITES OF A SPECIFIC MODULE"
Invoke either
.CS

  \&./sak\&.tcl test run foo
.CE
or
.CS

  \&./sak\&.tcl test run modules/foo
.CE
to invoke the testsuites found in a specific module "\fIfoo\fR"\&.
.SS "INVOKE THE TESTSUITES OF ALL MODULES"
Invoke the tool without a module name, i\&.e\&.
.CS

  \&./sak\&.tcl test run
.CE
to invoke the testsuites of all modules\&.
.SS "DETAILED TEST LOGS"
In all the previous examples the test runner will write a combination
of progress display and testsuite log to the standard output, showing
for each module only the tests that passed or failed and how many of
each in a summary at the end\&.
.PP
To get a detailed log, it is necessary to invoke the test
runner with additional options\&.
.PP
For one:
.CS


   \&./sak\&.tcl test run --log LOG foo

.CE
While this shows the same short log on the terminal as before, it also
writes a detailed log to the file "\fILOG\&.log\fR", and excerpts to
other files ("\fILOG\&.summary\fR", "\fILOG\&.failures\fR", etc\&.)\&.
.PP
For two:
.CS


  \&./sak\&.tcl test run -v foo

.CE
This writes the detailed log to the standard output, instead of the
short log\&.
.PP
Regardless of form, the detailed log contains a list of all test
cases executed, which failed, and how they failed (expected versus
actual results)\&.
.SS "SHELL SELECTION"
By default the test runner will use all the Tcl shells specified via
\fBtest add\fR to invoke the specified testsuites, if any\&. If no
such are specified it will fall back to the Tcl shell used to run the
tool itself\&.
.PP
Use option \fB--shell\fR to explicitly specify the Tcl shell
to use, like
.CS


  \&./sak\&.tcl test run --shell /path/to/tclsh \&.\&.\&.

.CE
.SS HELP
Invoke the tool as
.CS

  \&./sak\&.tcl help test
.CE
to see the detailed help for all methods of \fBtest\fR, and the
associated options\&.
.SH "DOCUMENTATION TOOLING"
The standard format used for documentation of packages and other
things in Tcllib is \fIdoctools\fR\&.
Its supporting packages are a part of Tcllib, see the directories
"\fImodules/doctools\fR" and "\fImodules/dtplite\fR"\&. The latter is
an application package, with the actual application
"\fIapps/dtplite\fR" a light wrapper around it\&.
.PP
Tcllib developers gain access to these through the \fBdoc\fR
method of the "\fIsak\&.tcl\fR" tool, another (internal) wrapper around
the "\fImodules/dtplite\fR" application package\&.
.SS "GENERATE DOCUMENTATION FOR A SPECIFIC MODULE"
Invoke either
.CS

  \&./sak\&.tcl doc html foo
.CE
or
.CS

  \&./sak\&.tcl doc html modules/foo
.CE
to generate HTML for the documentation found in the module "\fIfoo\fR"\&.
Instead of \fBhtml\fR any other supported format can be used here,
of course\&.
.PP
The generated formatted documentation will be placed into a
directory "\fIdoc\fR" in the current working directory\&.
.SS "GENERATE DOCUMENTATION FOR ALL MODULES"
Invoke the tool without a module name, i\&.e\&.
.CS

  \&./sak\&.tcl doc html
.CE
to generate HTML for the documentation found in all modules\&.
Instead of \fBhtml\fR any other supported format can be used here,
of course\&.
.PP
The generated formatted documentation will be placed into a
directory "\fIdoc\fR" in the current working directory\&.
.SS "AVAILABLE OUTPUT FORMATS, HELP"
Invoke the tool as
.CS

  \&./sak\&.tcl help doc
.CE
to see the entire set of supported output formats which can be
generated\&.
.SS "VALIDATION WITHOUT OUTPUT"
Note the special format \fBvalidate\fR\&.
.PP
Using this value as the name of the format to generate forces
the tool to simply check that the documentation is syntactically
correct, without generating actual output\&.
.PP
Invoke it as either
.CS

  \&./sak\&.tcl doc validate (modules/)foo
.CE
or
.CS

  \&./sak\&.tcl doc validate
.CE
to either check the packages of a specific module or check all of
them\&.
.SH "NOTES ON WRITING A TESTSUITE"
While previous sections talked about running the testsuites for a
module and the packages therein, this has no meaning if the module in
question has no testsuites at all\&.
.PP
This section gives a very basic overview on possible
methodologies for writing tests and testsuites\&.
.PP
First there are "drudgery" tests\&. Written to check absolutely
basic assumptions which should never fail\&.
.PP
For example for a command FOO taking two arguments, three tests
calling it with zero, one, and three arguments\&. The basic checks that
the command fails if it has not enough arguments, or too many\&.
.PP
After that come the tests checking things based on our
knowledge of the command, about its properties and assumptions\&. Some
examples based on the graph operations added during Google's Summer of
Code 2009 are:
.IP \(bu
The BellmanFord command in struct::graph::ops takes a
\fIstartnode\fR as argument, and this node should be a node of
the graph\&. This equals one test case checking the behavior when the
specified node is not a node of the graph\&.
.sp
This often gives rise to code in the implementation which
explicitly checks the assumption and throws an understandable error,
instead of letting the algorithm fail later in some weird
non-deterministic way\&.
.sp
It is not always possible to do such checks\&. The graph argument
for example is just a command in itself, and while we expect
it to exhibit a certain interface, i\&.e\&. a set of sub-commands
aka methods, we cannot check that it has them, except by
actually trying to use them\&. That is done by the algorithm
anyway, so an explicit check is just overhead we can get by
without\&.
.IP \(bu
IIRC one of the distinguishing characteristic of either
BellmanFord and/or Johnson is that they are able to handle
negative weights\&. Whereas Dijkstra requires positive weights\&.
.sp
This induces (at least) three testcases \&.\&.\&. Graph with all
positive weights, all negative, and a mix of positive and
negative weights\&.
Thinking further does the algorithm handle the weight
\fB0\fR as well ? Another test case, or several, if we mix
zero with positive and negative weights\&.
.IP \(bu
The two algorithms we are currently thinking about are about
distances between nodes, and distance can be 'Inf'inity,
i\&.e\&. nodes may not be connected\&. This means that good test
cases are
.RS
.IP [1]
Strongly connected graph
.IP [2]
Connected graph
.IP [3]
Disconnected graph\&.
.RE
.sp
At the extremes of strongly connected and disconnected
we have the fully connected graphs and graphs without edges,
only nodes, i\&.e\&. completely disconnected\&.
.IP \(bu
IIRC both of the algorithms take weighted arcs, and fill in a
default if arcs are left unweighted in the input graph\&.
.sp
This also induces three test cases:
.RS
.IP [1]
Graph will all arcs with explicit weights\&.
.IP [2]
Graph without weights at all\&.
.IP [3]
Graph with mixture of weighted and unweighted graphs\&.
.RE
.PP
.PP
What was described above via examples is called
\fIblack-box\fR testing\&. Test cases are designed and written based on
the developer's knowledge of the properties of the algorithm and its
inputs, without referencing a particular implementation\&.
.PP
Going further, a complement to \fIblack-box\fR testing is
\fIwhite-box\fR\&. For this we know the implementation of the
algorithm, we look at it and design our tests cases so that they force
the code through all possible paths in the implementation\&. Wherever a
decision is made we have a test case forcing a specific direction of
the decision, for all possible combinations and directions\&. It is easy
to get a combinatorial explosion in the number of needed test-cases\&.
.PP
In practice I often hope that the black-box tests I have made
are enough to cover all the paths, obviating the need for white-box
tests\&.
.PP
The above should be enough to make it clear that writing tests
for an algorithm takes at least as much time as coding the algorithm,
and often more time\&. Much more time\&.
See for example also \fIhttp://sqlite\&.org/testing\&.html\fR, a writeup
on how the Sqlite database engine is tested\&. Another article of
interest might be \fIhttps://www\&.researchgate\&.net/publication/298896236\fR\&.
While geared to a particular numerical algorithm it still shows that
even a simple-looking algorithm can lead to an incredible number of
test cases\&.
.PP
An interesting connection is to documentation\&. In one
direction, the properties checked with black-box testing are exactly
the properties which should be documented in the algorithm's man
page\&. And conversely, the documentation of the properties of an
algorithm makes a good reference to base the black-box tests on\&.
.PP
In practice test cases and documentation often get written
together, cross-influencing each other\&. And the actual writing of test
cases is a mix of black and white box, possibly influencing the
implementation while writing the tests\&. Like writing a test for a
condition like \fIstartnode not in input graph\fR serving as
reminder to put a check for this condition into the code\&.
.SH "INSTALLATION TOOLING"
A last thing to consider when adding a new package to the collection
is installation\&.
.PP
How to \fIuse\fR the "\fIinstaller\&.tcl\fR" script is documented
in \fITcllib - The Installer's Guide\fR\&.
.PP
Here we document how to extend said installer so that it may
install new package(s) and/or application(s)\&.
.PP
In most cases only a single file has to be modified, the
"\fIsupport/installation/modules\&.tcl\fR" holding one command per module
and application to install\&.
.PP
The relevant commands are:
.TP
\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR
Install the packages of module \fIname\fR, found in
"\fImodules/\fIname\fR\fR"\&.
.sp
The \fIcode-action\fR is responsible for installing the
packages and their index\&. The system currently provides
.RS
.TP
\fB_tcl\fR
Copy all "\fI\&.tcl\fR" files found in
"\fImodules/\fIname\fR\fR" into the installation\&.
.TP
\fB_tcr\fR
As \fB_tcl\fR, copy the "\fI\&.tcl\fR" files found in
the subdirectories of "\fImodules/\fIname\fR\fR" as well\&.
.TP
\fB_tci\fR
As \fB_tcl\fR, and copy the "\fItclIndex\&.tcl\fR" file
as well\&.
.TP
\fB_msg\fR
As \fB_tcl\fR, and copy the subdirectory "\fImsgs\fR"
as well\&.
.TP
\fB_doc\fR
As \fB_tcl\fR, and copy the subdirectory
"\fImpformats\fR" as well\&.
.TP
\fB_tex\fR
As \fB_tcl\fR, and copy "\fI\&.tex\fR" files as well\&.
.RE
.sp
The \fIdoc-action\fR is responsible for installing the package
documentation\&. The system currently provides
.RS
.TP
\fB_null\fR
No documentation available, do nothing\&.
.TP
\fB_man\fR
Process the "\fI\&.man\fR" files found in
"\fImodules/\fIname\fR\fR" and install the results (nroff and/or HTML)
in the proper location, as given to the installer\&.
.sp
This is actually a fallback, normally the installer uses the
pre-made formatted documentation found under "\fIidoc\fR"\&.
.RE
.sp
The \fIexample-action\fR is responsible for installing the
examples\&. The system currently provides
.RS
.TP
\fB_null\fR
No examples available, do nothing\&.
.TP
\fB_exa\fR
Copy the the directory "\fIexamples/\fIname\fR\fR"
recursively to the install location for examples\&.
.RE
.TP
\fBApplication\fR \fIname\fR
Install the application with \fIname\fR, found in "\fIapps\fR"\&.
.TP
\fBExclude\fR \fIname\fR
This command signals to the installer which of the listed modules to
\fInot\fR install\&. I\&.e\&. they name the deprecated modules of Tcllib\&.
.PP
.PP
If, and only if the above actions are not suitable for the new
module then a second file has to be modified,
"\fIsupport/installation/actions\&.tcl\fR"\&.
.PP
This file contains the implementations of the available
actions, and is the place where any custom action needed to handle the
special circumstances of module has to be added\&.

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








































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































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


  \&./configure
  make install

.CE
a suitable way of installing it\&.
This is a standard non-interactive install automatically figuring out
where to place everything, i\&.e\&. packages, applications, and the
manpages\&.
.PP
To get a graphical installer invoke
.CS


  \&./installer\&.tcl

.CE
instead\&.
.SS "INSTALLING ON WINDOWS"
In a Windows environment we have the \fBinstaller\&.tcl\fR script to
perform installation\&.
.PP
If the desired \fBtclsh\fR is associated "\fI\&.tcl\fR" files
then double-clicking / opening the \fBinstaller\&.tcl\fR is
enough to invoke it in graphical mode\&.
This assumes that \fITk\fR is installed and available as well\&.
.PP
Without \fITk\fR the only way to invoke the installer are to
open a DOS window, i\&.e\&. \fBcmd\&.exe\fR, and then to invoke
.CS


  \&./installer\&.tcl

.CE
inside it\&.
.SS "CRITCL & ACCELERATORS"
While the majority of Tcllib consists of packages written in pure Tcl
a number of packages also have \fIaccelerators\fR associated with them\&.
These are \fBcritcl\fR-based C packages whose use will boost the
performance of the packages using them\&.
These accelerators are optional, and they are not installed by
default\&.
.PP
To build the accelerators the normally optional dependency on
\fBcritcl\fR becomes required\&.
.PP
To build and install Tcllib with the accelerators in a
Unix-like environment invoke:
.CS


  \&./configure
  make critcl # This builds the shared library holding
              # the accelerators
  make install

.CE
.PP
The underlying tool is "\fIsak\&.tcl\fR" in the toplevel directory
of Tcllib and the command \fBmake critcl\fR is just a wrapper around
.CS


  \&./sak\&.tcl critcl

.CE
.PP
Therefore in a Windows environment instead invoke
.CS


  \&./sak\&.tcl critcl
  \&./installer\&.tcl

.CE
from within a DOS window, i\&.e\&. \fBcmd\&.exe\fR\&.
.SS TOOLING
The core of Tcllib's build system is the script "\fIinstaller\&.tcl\fR"
found in the toplevel directory of a checkout or release\&.
.PP
The
.CS


         configure ; make install

.CE
setup available to
developers on Unix-like systems is just a wrapper around it\&.
To go beyond the standard embodied in the wrapper it is
necessary to directly invoke this script\&.
.PP
On Windows system using it directly is the only way to invoke
it\&.
.PP
For basic help invoke it as
.CS


         \&./installer\&.tcl -help

.CE
This will print a short list of all the available options to
the standard output channel\&.
.PP
The commands associated with the various \fIinstall\fR targets
in the \fIMakefile\&.in\fR for Unix can be used as additional
examples on how to use this tool as well\&.
.PP
The installer can operate in GUI and CLI modes\&.
By default it chooses the mode automatically, based on if the
Tcl package \fBTk\fR can be used or not\&.
The option \fB-no-gui\fR can be used to force CLI mode\&.
.PP
Note that it is possible to specify options on the command line
even if the installer ultimatively selects GUI mode\&. In that
case the hardwired defaults and the options determine the data
presented to the user for editing\&.
.PP
The installer will select a number of defaults for the
locations of packages, examples, and documentation, and also
the format of the documentation\&. The user can overide these
defaults in the GUI, or by specifying additional options\&.
The defaults depend on the platform detected (Unix/Windows) and
on the \fBtclsh\fR executable used to run the installer\&.
.PP
\fIOptions\fR
.TP
\fB-help\fR
Show the list of options explained here on the standard output channel
and exit\&.
.TP
\fB+excluded\fR
Include deprecated packages in the installation\&.
.TP
\fB-no-gui\fR
Force command line operation of the installer
.TP
\fB-no-wait\fR
In CLI mode the installer will by default ask the user to confirm that
the chosen configuration (destination paths, things to install) is
correct before performing any action\&. Using this option causes the
installer to skip this query and immediately jump to installation\&.
.TP
\fB-app-path\fR \fIpath\fR
.TP
\fB-example-path\fR \fIpath\fR
.TP
\fB-html-path\fR \fIpath\fR
.TP
\fB-nroff-path\fR \fIpath\fR
.TP
\fB-pkg-path\fR \fIpath\fR
Declare the destination paths for the applications, examples, html
documentation, nroff manpages, and packages\&. The defaults are derived
from the location of the \fBtclsh\fR used to run the installer\&.
.TP
\fB-dry-run\fR
.TP
\fB-simulate\fR
Run the installer without modifying the destination directories\&.
.TP
\fB-apps\fR
.TP
\fB-no-apps\fR
.TP
\fB-examples\fR
.TP
\fB-no-examples\fR
.TP
\fB-pkgs\fR
.TP
\fB-no-pkgs\fR
.TP
\fB-html\fR
.TP
\fB-no-html\fR
.TP
\fB-nroff\fR
.TP
\fB-no-nroff\fR
(De)activate the installation of applications, examples, packages,
html documentation, and nroff manpages\&.
.sp
Applications, examples, and packages are installed by default\&.
.sp
On Windows the html documentation is installed by default\&.
.sp
On Unix the nroff manpages are installed by default\&.
.PP

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


































































































































































































































































































































































































































































































































































































































































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

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














































































































































































































































































































































































































































































































































































































































































































































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


    sak\&.tcl validate
    sak\&.tcl test run
    sak\&.tcl review
    sak\&.tcl readme
    sak\&.tcl localdoc
    sak\&.tcl release

.CE
More detail will be provided in the explanations of the various
\fBTasks\fR\&.
.SH TASKS
.SS "START A RELEASE CANDIDATE"
todo: open a candidate for release
.SS "READY THE CANDIDATE"
todo: test, validate and check that the candidate is worthy of release
fix testsuites, possibly fix packages, documentation
regenerate docs
coordinate with package maintainers wrt fixes
big thing: going over the packages, classify changes since last
release to generate a nice readme\&.
.SS "MAKE IT OFFICIAL"
todo: finalize release, make candidate official
.SS "DISTRIBUTE THE RELEASE"
With the release made it has to be published and the world notified of
its existence\&.
.IP [1]
Create a proper fossil event for the release, via
\fIhttp://core\&.tcl-lang\&.org/tcllib/eventedit\fR\&.
.sp
An \fIexisting event\fR [http://core\&.tcl-lang\&.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817] should be used as template\&.
.IP [2]
Update a number of web locations:
.RS
.IP [1]
\fIHome page\fR [http://core\&.tcl-lang\&.org/tcllib/doc/trunk/embedded/index\&.md]
.IP [2]
\fIDownloads\fR [http://core\&.tcl-lang\&.org/tcllib/wiki?name=Downloads]
.IP [3]
\fIPast Releases\fR [http://core\&.tcl-lang\&.org/tcllib/wiki?name=Past+Releases]
.IP [4]
\fIhttp://www\&.tcl-lang\&.org/home/release\&.txt\fR
.IP [5]
\fIhttp://www\&.tcl-lang\&.org/software/tcllib/*\&.tml\fR
.IP [6]
\fIhttp://wiki\&.tcl-lang\&.org/page/Tcllib\fR
.RE
.IP
The first location maps to the file "\fIembedded/index\&.md\fR" in the
repository itself, as such it can edited as part of the release
process\&. This is where reference to the new fossil event is added, as
the new current release\&.
.sp
The next two locations are in the fossil tcllib wiki and
require admin or wiki write permissions for
\fIhttp://core\&.tcl-lang\&.org/tcllib\fR\&.
.sp
The last two locations require ssh access to
\fIhttp://www\&.tcl-lang\&.org\fR and permission to edit
files in the web area\&.
.IP [3]
***TODO*** mailing lists and other places to send notes to\&.
.PP

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
























































































































































































































































































































































































































































































































































































































































































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


    fossil clone  http://core\&.tcl-lang\&.org/tcllib  tcllib\&.fossil

.CE
followed by
.CS


    mkdir tcllib
    cd tcllib
    fossil open \&.\&./tcllib\&.fossil

.CE
to get a checkout of the head of the trunk\&.

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

330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
...
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
[keywords {doctools language}]
[keywords {doctools markup}]
[keywords {doctools syntax}]
[keywords markup]
[keywords {semantic markup}]
    [description]
    [vset CATEGORY doctools]
[include \&.\&./doctools2base/include/feedback\&.inc]
[manpage_end]

.CE
This also shows us that all doctools documents are split into two
parts, the \fIheader\fR and the \fIbody\fR\&. Everything coming before
[\fBdescription\fR] belongs to the header, and everything coming
after belongs to the body, with the whole document bracketed by the
................................................................................
.CS


    [manpage_begin NAME SECTION VERSION]
    [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
    [require PACKAGE VERSION][require PACKAGE][description]
    [vset CATEGORY doctools]
[include \&.\&./doctools2base/include/feedback\&.inc]
[manpage_end]

.CE
has the same meaning as the example before\&.
.PP
On the other hand, if \fIwhitespace\fR is present it consists not
only of any sequence of characters containing the space character,






|







 







|







330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
...
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
[keywords {doctools language}]
[keywords {doctools markup}]
[keywords {doctools syntax}]
[keywords markup]
[keywords {semantic markup}]
    [description]
    [vset CATEGORY doctools]
[include \&.\&./common-text/feedback\&.inc]
[manpage_end]

.CE
This also shows us that all doctools documents are split into two
parts, the \fIheader\fR and the \fIbody\fR\&. Everything coming before
[\fBdescription\fR] belongs to the header, and everything coming
after belongs to the body, with the whole document bracketed by the
................................................................................
.CS


    [manpage_begin NAME SECTION VERSION]
    [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
    [require PACKAGE VERSION][require PACKAGE][description]
    [vset CATEGORY doctools]
[include \&.\&./common-text/feedback\&.inc]
[manpage_end]

.CE
has the same meaning as the example before\&.
.PP
On the other hand, if \fIwhitespace\fR is present it consists not
only of any sequence of characters containing the space character,

Changes to idoc/man/toc.n.

1337
1338
1339
1340
1341
1342
1343



1344
1345
1346
1347
1348
1349
1350
1351
1352






1353
1354
1355









1356
1357
1358
1359
1360
1361
1362
.TP
\fBtcl::transform::spacer\fR
\fIfiles/modules/virtchannel_transform/spacer\&.n\fR: Space insertation and removal
.TP
\fBtcl::transform::zlib\fR
\fIfiles/modules/virtchannel_transform/tcllib_zlib\&.n\fR: zlib (de)compression
.TP



\fBtclDES\fR
\fIfiles/modules/des/tcldes\&.n\fR: Implementation of the DES and triple-DES ciphers
.TP
\fBtclDESjr\fR
\fIfiles/modules/des/tcldesjr\&.n\fR: Implementation of the DES and triple-DES ciphers
.TP
\fBtcldocstrip\fR
\fIfiles/apps/tcldocstrip\&.n\fR: Tcl-based Docstrip Processor
.TP






\fBtcllib_ip\fR
\fIfiles/modules/dns/tcllib_ip\&.n\fR: IPv4 and IPv6 address manipulation
.TP









\fBtclrep/machineparameters\fR
\fIfiles/modules/math/machineparameters\&.n\fR: Compute double precision machine parameters\&.
.TP
\fBtepam\fR
\fIfiles/modules/tepam/tepam_introduction\&.n\fR: An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
.TP
\fBtepam::argument_dialogbox\fR






>
>
>









>
>
>
>
>
>



>
>
>
>
>
>
>
>
>







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

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






















































































































































































































































































































































































































































































































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

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












































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































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

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
















































































































































































































































































































































































































































































































































































































































































































































































































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

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




































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
<!DOCTYPE html><html><head>
<title>tcllib_license - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'tcllib_license.man' by tcllib/doctools with format 'html'
   -->
<!-- tcllib_license.n
   -->
<body><hr> [
   <a href="../../../../../../../home">Tcllib Home</a>
&#124; <a href="../../../toc.html">Main Table Of Contents</a>
&#124; <a href="../../toc.html">Table Of Contents</a>
&#124; <a href="../../../index.html">Keyword Index</a>
&#124; <a href="../../../toc0.html">Categories</a>
&#124; <a href="../../../toc1.html">Modules</a>
&#124; <a href="../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">tcllib_license(n) 1 tcllib &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcllib_license - Tcllib - License</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">License</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
packages that provide utility functions useful to a large collection
of Tcl programmers.</p>
<p>The collection is under the BSD license.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">License</a></h2>
<p>This software is copyrighted by Ajuba Solutions and other parties.
The following terms apply to all files associated with the software
unless explicitly disclaimed in individual files.</p>
<p>The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose,
provided that existing copyright notices are retained in all copies
and that this notice is included verbatim in any distributions. No
written agreement, license, or royalty fee is required for any of the
authorized uses.  Modifications to this software may be copyrighted by
their authors and need not follow the licensing terms described here,
provided that the new terms are clearly indicated on the first page of
each file where they apply.</p>
<p>IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.</p>
<p>THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN &quot;AS IS&quot; BASIS, AND
THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.</p>
<p>GOVERNMENT USE: If you are acquiring this software on behalf of the
U.S. government, the Government shall have only &quot;Restricted Rights&quot; in
the software and related documentation as defined in the Federal
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
are acquiring the software on behalf of the Department of Defense, the
software shall be classified as &quot;Commercial Computer Software&quot; and the
Government shall have only &quot;Restricted Rights&quot; as defined in Clause
252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing, the
authors grant the U.S. Government and others acting in its behalf
permission to use and distribute the software in accordance with the
terms specified in this license.</p>
</div>
</div></body></html>

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














































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
<!DOCTYPE html><html><head>
<title>tcllib_releasemgr - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'tcllib_releasemgr.man' by tcllib/doctools with format 'html'
   -->
<!-- tcllib_releasemgr.n
   -->
<body><hr> [
   <a href="../../../../../../../home">Tcllib Home</a>
&#124; <a href="../../../toc.html">Main Table Of Contents</a>
&#124; <a href="../../toc.html">Table Of Contents</a>
&#124; <a href="../../../index.html">Keyword Index</a>
&#124; <a href="../../../toc0.html">Categories</a>
&#124; <a href="../../../toc1.html">Modules</a>
&#124; <a href="../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">tcllib_releasemgr(n) 1 tcllib &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcllib_releasemgr - Tcllib - The Release Manager's Guide</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Tools</a></li>
<li class="doctools_section"><a href="#section3">Tasks</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Start a release candidate</a></li>
<li class="doctools_subsection"><a href="#subsection2">Ready the candidate</a></li>
<li class="doctools_subsection"><a href="#subsection3">Make it official</a></li>
<li class="doctools_subsection"><a href="#subsection4">Distribute the release</a></ul>
</li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
packages that provide utility functions useful to a large collection
of Tcl programmers.</p>
<p>The audience of this document is the release manager for Tcllib, their
deputies, and anybody else interested in the task of creating
an official release of Tcllib for distribution.</p>
<p>Please read <i class="term"><a href="tcllib_sources.html">Tcllib - How To Get The Sources</a></i> first, if that
was not done already. Here we assume that the sources are already
available in a directory of your choice.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Tools</a></h2>
<p>The &quot;<b class="file">sak.tcl</b>&quot; script in the toplevel directory of a Tcllib
checkout is the one tool used by the release manager to perform its
<span class="sectref"><a href="#section3">Tasks</a></span>.</p>
<p>The main commands to be used are</p>
<pre class="doctools_example">
    sak.tcl validate
    sak.tcl test run
    sak.tcl review
    sak.tcl readme
    sak.tcl localdoc
    sak.tcl release
</pre>
<p>More detail will be provided in the explanations of the various
<span class="sectref"><a href="#section3">Tasks</a></span>.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Tasks</a></h2>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Start a release candidate</a></h3>
<p>todo: open a candidate for release</p>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Ready the candidate</a></h3>
<p>todo: test, validate and check that the candidate is worthy of release
fix testsuites, possibly fix packages, documentation
regenerate docs
coordinate with package maintainers wrt fixes
big thing: going over the packages, classify changes since last
release to generate a nice readme.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Make it official</a></h3>
<p>todo: finalize release, make candidate official</p>
</div>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Distribute the release</a></h3>
<p>With the release made it has to be published and the world notified of
its existence.</p>
<ol class="doctools_enumerated">
<li><p>Create a proper fossil event for the release, via
	    <a href="http://core.tcl-lang.org/tcllib/eventedit">http://core.tcl-lang.org/tcllib/eventedit</a>.</p>
<p>An <a href="http://core.tcl-lang.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817">existing event</a> should be used as template.</p></li>
<li><p>Update a number of web locations:</p>
<ol class="doctools_enumerated">
<li><p><a href="http://core.tcl-lang.org/tcllib/doc/trunk/embedded/index.md">Home page</a></p></li>
<li><p><a href="http://core.tcl-lang.org/tcllib/wiki?name=Downloads">Downloads</a></p></li>
<li><p><a href="http://core.tcl-lang.org/tcllib/wiki?name=Past+Releases">Past Releases</a></p></li>
<li><p><a href="http://www.tcl-lang.org/home/release.txt">http://www.tcl-lang.org/home/release.txt</a></p></li>
<li><p><a href="http://www.tcl-lang.org/software/tcllib/*.tml">http://www.tcl-lang.org/software/tcllib/*.tml</a></p></li>
<li><p><a href="http://wiki.tcl-lang.org/page/Tcllib">http://wiki.tcl-lang.org/page/Tcllib</a></p></li>
</ol>
<p>The first location maps to the file &quot;<b class="file">embedded/index.md</b>&quot; in the
repository itself, as such it can edited as part of the release
process. This is where reference to the new fossil event is added, as
the new current release.</p>
<p>The next two locations are in the fossil tcllib wiki and
require admin or wiki write permissions for
<a href="http://core.tcl-lang.org/tcllib">http://core.tcl-lang.org/tcllib</a>.</p>
<p>The last two locations require ssh access to
<a href="http://www.tcl-lang.org">http://www.tcl-lang.org</a> and permission to edit
files in the web area.</p></li>
<li><p>***TODO*** mailing lists and other places to send notes to.</p></li>
</ol>
</div>
</div>
</div></body></html>

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


















































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
<!DOCTYPE html><html><head>
<title>tcllib_sources - </title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'tcllib_sources.man' by tcllib/doctools with format 'html'
   -->
<!-- tcllib_sources.n
   -->
<body><hr> [
   <a href="../../../../../../../home">Tcllib Home</a>
&#124; <a href="../../../toc.html">Main Table Of Contents</a>
&#124; <a href="../../toc.html">Table Of Contents</a>
&#124; <a href="../../../index.html">Keyword Index</a>
&#124; <a href="../../../toc0.html">Categories</a>
&#124; <a href="../../../toc1.html">Modules</a>
&#124; <a href="../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">tcllib_sources(n) 1 tcllib &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcllib_sources - Tcllib - How To Get The Sources</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Source Location</a></li>
<li class="doctools_section"><a href="#section3">Retrieval</a></li>
<li class="doctools_section"><a href="#section4">Source Code Management</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
packages that provide utility functions useful to a large collection
of Tcl programmers.</p>
<p>The audience of this document is anyone wishing to either have just a
look at Tcllib's source code, or build the packages, or to extend and
modify them.</p>
<p>For builders and developers we additionally provide</p>
<ol class="doctools_enumerated">
<li><p><i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i>.</p></li>
<li><p><i class="term"><a href="tcllib_devguide.html">Tcllib - The Developer's Guide</a></i>.</p></li>
</ol>
<p>respectively.</p>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Source Location</a></h2>
<p>The official repository for Tcllib can be found at
<a href="http://core.tcl-lang.org/tcllib">http://core.tcl-lang.org/tcllib</a></p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Retrieval</a></h2>
<p>Assuming that you simply wish to look at the sources, or build a
specific revision, the easiest way of retrieving it is to:</p>
<ol class="doctools_enumerated">
<li><p>Log into this site, as &quot;anonymous&quot;, using the semi-random password in the captcha.</p></li>
<li><p>Go to the &quot;Timeline&quot;.</p></li>
<li><p>Choose the revision you wish to have.</p></li>
<li><p>Follow its link to its detailed information page.</p></li>
<li><p>On that page, choose either the &quot;ZIP&quot; or &quot;Tarball&quot; link to get
a copy of this revision in the format of your choice.</p></li>
</ol>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">Source Code Management</a></h2>
<p>For the curious (or a developer-to-be), the sources are managed by the
<a href="http://www.fossil-scm.org">Fossil SCM</a>.
Binaries for popular platforms can be found directly at its
<a href="http://www.fossil-scm.org/download.html">download page</a>.</p>
<p>With that tool available the full history can be retrieved via:</p>
<pre class="doctools_example">
    fossil clone  http://core.tcl-lang.org/tcllib  tcllib.fossil
</pre>
<p>followed by</p>
<pre class="doctools_example">
    mkdir tcllib
    cd tcllib
    fossil open ../tcllib.fossil
</pre>
<p>to get a checkout of the head of the trunk.</p>
</div>
</div></body></html>

Changes to idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html.

176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
...
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
[keywords {doctools language}]
[keywords {doctools markup}]
[keywords {doctools syntax}]
[keywords markup]
[keywords {semantic markup}]
    [description]
    [vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
</pre>
<p>This also shows us that all doctools documents are split into two
parts, the <i class="term">header</i> and the <i class="term">body</i>. Everything coming before
[<b class="cmd">description</b>] belongs to the header, and everything coming
after belongs to the body, with the whole document bracketed by the
two <b class="cmd">manpage_*</b> commands. Before and after these opening and
................................................................................
</pre>
<p>Remember that the whitespace is optional. The document</p>
<pre class="doctools_example">
    [manpage_begin NAME SECTION VERSION]
    [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
    [require PACKAGE VERSION][require PACKAGE][description]
    [vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
</pre>
<p>has the same meaning as the example before.</p>
<p>On the other hand, if <i class="term">whitespace</i> is present it consists not
only of any sequence of characters containing the space character,
horizontal and vertical tabs, carriage return, and newline, but it may
contain comment markup as well, in the form of the <b class="cmd"><a href="../../../../index.html#comment">comment</a></b>






|







 







|







176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
...
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
[keywords {doctools language}]
[keywords {doctools markup}]
[keywords {doctools syntax}]
[keywords markup]
[keywords {semantic markup}]
    [description]
    [vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]
</pre>
<p>This also shows us that all doctools documents are split into two
parts, the <i class="term">header</i> and the <i class="term">body</i>. Everything coming before
[<b class="cmd">description</b>] belongs to the header, and everything coming
after belongs to the body, with the whole document bracketed by the
two <b class="cmd">manpage_*</b> commands. Before and after these opening and
................................................................................
</pre>
<p>Remember that the whitespace is optional. The document</p>
<pre class="doctools_example">
    [manpage_begin NAME SECTION VERSION]
    [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
    [require PACKAGE VERSION][require PACKAGE][description]
    [vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]
</pre>
<p>has the same meaning as the example before.</p>
<p>On the other hand, if <i class="term">whitespace</i> is present it consists not
only of any sequence of characters containing the space character,
horizontal and vertical tabs, carriage return, and newline, but it may
contain comment markup as well, in the form of the <b class="cmd"><a href="../../../../index.html#comment">comment</a></b>

Changes to idoc/www/tcllib/toc.html.

1437
1438
1439
1440
1441
1442
1443




1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454




1455




1456
1457
1458












1459
1460
1461
1462
1463
1464
1465
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
<tr class="#doctools_toceven" >




<td class="#doctools_tocleft" ><a name='tcldes'><a href="files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>




<tr class="#doctools_tocodd"  >




<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>












<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tepam'><a href="files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>






>
>
>
>



|



|



>
>
>
>

>
>
>
>



>
>
>
>
>
>
>
>
>
>
>
>







1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
<td class="#doctools_tocright">Space insertation and removal</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tcl_transform_zlib'><a href="files/modules/virtchannel_transform/tcllib_zlib.html">tcl::transform::zlib</a></td>
<td class="#doctools_tocright">zlib (de)compression</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcl_community_communication'><a href="files/devdoc/tcl_community_communication.html">tcl_community_communication</a></td>
<td class="#doctools_tocright">Tcl Community - Kind Communication</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tcldes'><a href="files/modules/des/tcldes.html">tclDES</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcldesjr'><a href="files/modules/des/tcldesjr.html">tclDESjr</a></td>
<td class="#doctools_tocright">Implementation of the DES and triple-DES ciphers</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tcldocstrip'><a href="files/apps/tcldocstrip.html">tcldocstrip</a></td>
<td class="#doctools_tocright">Tcl-based Docstrip Processor</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcllib_devguide'><a href="files/devdoc/tcllib_devguide.html">tcllib_devguide</a></td>
<td class="#doctools_tocright">Tcllib - The Developer's Guide</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tcllib_install_guide'><a href="files/devdoc/tcllib_installer.html">tcllib_install_guide</a></td>
<td class="#doctools_tocright">Tcllib - The Installer's Guide</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcllib_ip'><a href="files/modules/dns/tcllib_ip.html">tcllib_ip</a></td>
<td class="#doctools_tocright">IPv4 and IPv6 address manipulation</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tcllib_license'><a href="files/devdoc/tcllib_license.html">tcllib_license</a></td>
<td class="#doctools_tocright">Tcllib - License</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tcllib_releasemgr'><a href="files/devdoc/tcllib_releasemgr.html">tcllib_releasemgr</a></td>
<td class="#doctools_tocright">Tcllib - The Release Manager's Guide</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tcllib_sources'><a href="files/devdoc/tcllib_sources.html">tcllib_sources</a></td>
<td class="#doctools_tocright">Tcllib - How To Get The Sources</td>
</tr>
<tr class="#doctools_toceven" >
<td class="#doctools_tocleft" ><a name='tclrep_machineparameters'><a href="files/modules/math/machineparameters.html">tclrep/machineparameters</a></td>
<td class="#doctools_tocright">Compute double precision machine parameters.</td>
</tr>
<tr class="#doctools_tocodd"  >
<td class="#doctools_tocleft" ><a name='tepam'><a href="files/modules/tepam/tepam_introduction.html">tepam</a></td>
<td class="#doctools_tocright">An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager</td>

Changes to installer.tcl.

278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
	# Starpack. No defaults for location.
    } else {
	# Starkit, or unwrapped. Derive defaults location from the
	# location of the executable running the installer, or the
	# location of its library.

	# For a starkit [info library] is inside the running
	# tclkit. Detect this and derive the lcoation from the
	# location of the executable itself for that case.

	if {[string match [info nameofexecutable]* [info library]]} {
	    # Starkit
	    set libdir [file join [file dirname [file dirname [info nameofexecutable]]] lib]
	} else {
	    # Unwrapped.






|







278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
	# Starpack. No defaults for location.
    } else {
	# Starkit, or unwrapped. Derive defaults location from the
	# location of the executable running the installer, or the
	# location of its library.

	# For a starkit [info library] is inside the running
	# tclkit. Detect this and derive the location from the
	# location of the executable itself for that case.

	if {[string match [info nameofexecutable]* [info library]]} {
	    # Starkit
	    set libdir [file join [file dirname [file dirname [info nameofexecutable]]] lib]
	} else {
	    # Unwrapped.

Changes to license.terms.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
This software is copyrighted by Ajuba Solutions and other parties.
The following terms apply to all files associated with the software unless
explicitly disclaimed in individual files.

The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose, provided
that existing copyright notices are retained in all copies and that this
notice is included verbatim in any distributions. No written agreement,
license, or royalty fee is required for any of the authorized uses.
Modifications to this software may be copyrighted by their authors
and need not follow the licensing terms described here, provided that
the new terms are clearly indicated on the first page of each file where
they apply.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.

GOVERNMENT USE: If you are acquiring this software on behalf of the
U.S. government, the Government shall have only "Restricted Rights"
in the software and related documentation as defined in the Federal 
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
are acquiring the software on behalf of the Department of Defense, the
software shall be classified as "Commercial Computer Software" and the
Government shall have only "Restricted Rights" as defined in Clause
252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing, the
authors grant the U.S. Government and others acting in its behalf
permission to use and distribute the software in accordance with the
terms specified in this license. 
|
|


|
|
|
|
|
|
|
|








|
|
|
|
|


|
|







|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
This software is copyrighted by Ajuba Solutions and other parties.
The following terms apply to all files associated with the software
unless explicitly disclaimed in individual files.

The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose,
provided that existing copyright notices are retained in all copies
and that this notice is included verbatim in any distributions. No
written agreement, license, or royalty fee is required for any of the
authorized uses.  Modifications to this software may be copyrighted by
their authors and need not follow the licensing terms described here,
provided that the new terms are clearly indicated on the first page of
each file where they apply.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

GOVERNMENT USE: If you are acquiring this software on behalf of the
U.S. government, the Government shall have only "Restricted Rights" in
the software and related documentation as defined in the Federal
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
are acquiring the software on behalf of the Department of Defense, the
software shall be classified as "Commercial Computer Software" and the
Government shall have only "Restricted Rights" as defined in Clause
252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing, the
authors grant the U.S. Government and others acting in its behalf
permission to use and distribute the software in accordance with the
terms specified in this license.

Changes to modules/aes/aes.man.

160
161
162
163
164
165
166
167
168
[list_end]

[section AUTHORS]
Thorsten Schloermann, Pat Thoyts

[vset CATEGORY aes]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

160
161
162
163
164
165
166
167
168
[list_end]

[section AUTHORS]
Thorsten Schloermann, Pat Thoyts

[vset CATEGORY aes]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/amazon-s3/S3.man.

1442
1443
1444
1445
1446
1447
1448
1449
1450
each moving on to the next unstarted task as it finishes each.
This is still being designed, and it is intended primarily
to be run on Amazon's Elastic Compute Cloud.

[include ../common-text/tls-security-notes.inc]

[vset CATEGORY amazon-s3]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

1442
1443
1444
1445
1446
1447
1448
1449
1450
each moving on to the next unstarted task as it finishes each.
This is still being designed, and it is intended primarily
to be run on Amazon's Elastic Compute Cloud.

[include ../common-text/tls-security-notes.inc]

[vset CATEGORY amazon-s3]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/amazon-s3/xsxp.man.

129
130
131
132
133
134
135
136
137
[call [cmd xsxp::prettyprint] [arg pxml] [opt [arg chan]]]
This outputs to [arg chan] (default stdout) a pretty-printed
version of [arg pxml].

[list_end]

[vset CATEGORY amazon-s3]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

129
130
131
132
133
134
135
136
137
[call [cmd xsxp::prettyprint] [arg pxml] [opt [arg chan]]]
This outputs to [arg chan] (default stdout) a pretty-printed
version of [arg pxml].

[list_end]

[vset CATEGORY amazon-s3]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/asn/asn.man.

456
457
458
459
460
461
462
463
464
[section EXAMPLES]

Examples for the usage of this package can be found in the
implementation of package [package ldap].

[vset CATEGORY asn]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

456
457
458
459
460
461
462
463
464
[section EXAMPLES]

Examples for the usage of this package can be found in the
implementation of package [package ldap].

[vset CATEGORY asn]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/base32/base32.man.

67
68
69
70
71
72
73
74
75
	5 F   14 O   23 X
	6 G   15 P   24 Y
	7 H   16 Q   25 Z
	8 I   17 R   26 2
}]

[vset CATEGORY base32]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

67
68
69
70
71
72
73
74
75
	5 F   14 O   23 X
	6 G   15 P   24 Y
	7 H   16 Q   25 Z
	8 I   17 R   26 2
}]

[vset CATEGORY base32]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/base32/base32core.man.

58
59
60
61
62
63
64
65
66
[enum] The length of the input is not a multiple of eight,
[enum] The padding appears not at the end of input, but in the middle,
[enum] The padding has not of length six, four, three, or one characters,
[list_end]
[list_end]

[vset CATEGORY base32]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

58
59
60
61
62
63
64
65
66
[enum] The length of the input is not a multiple of eight,
[enum] The padding appears not at the end of input, but in the middle,
[enum] The padding has not of length six, four, three, or one characters,
[list_end]
[list_end]

[vset CATEGORY base32]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/base32/base32hex.man.

70
71
72
73
74
75
76
77
78
	5 5   14 E        23 N
	6 6   15 F        24 O
	7 7        16 G   25 P
	8 8        17 H   26 Q
}]

[vset CATEGORY base32]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

70
71
72
73
74
75
76
77
78
	5 5   14 E        23 N
	6 6   15 F        24 O
	7 7        16 G   25 P
	8 8        17 H   26 Q
}]

[vset CATEGORY base32]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/base64/ascii85.man.

67
68
69
70
71
72
73
74
75
[list_begin enum]
[enum] [uri http://en.wikipedia.org/wiki/Ascii85]
[enum] Postscript Language Reference Manual, 3rd Edition, page 131.
       [uri http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf]
[list_end]

[vset CATEGORY base64]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

67
68
69
70
71
72
73
74
75
[list_begin enum]
[enum] [uri http://en.wikipedia.org/wiki/Ascii85]
[enum] Postscript Language Reference Manual, 3rd Edition, page 131.
       [uri http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf]
[list_end]

[vset CATEGORY base64]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/base64/base64.man.

62
63
64
65
66
67
68
69
70
% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
% set encoded [base64::encode $chemical]
Q+KCiEjigoHigoBO4oKET+KCgg==
% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]
}]

[vset CATEGORY base64]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

62
63
64
65
66
67
68
69
70
% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
% set encoded [base64::encode $chemical]
Q+KCiEjigoHigoBO4oKET+KCgg==
% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]
}]

[vset CATEGORY base64]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/base64/uuencode.man.

89
90
91
92
93
94
95
96
97
[para]
[example {
% uuencode::uudecode $d
{hello.txt 644 {Hello World}}
}]

[vset CATEGORY base64]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

89
90
91
92
93
94
95
96
97
[para]
[example {
% uuencode::uudecode $d
{hello.txt 644 {Hello World}}
}]

[vset CATEGORY base64]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/base64/yencode.man.

88
89
90
91
92
93
94
95
96
[section References]

[list_begin enum]
[enum] [uri http://www.yenc.org/yenc-draft.1.3.txt]
[list_end]

[vset CATEGORY base64]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

88
89
90
91
92
93
94
95
96
[section References]

[list_begin enum]
[enum] [uri http://www.yenc.org/yenc-draft.1.3.txt]
[list_end]

[vset CATEGORY base64]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bee/bee.man.

335
336
337
338
339
340
341
342
343
By wrapping an integer number into [const i]...[const e] the format
makes sure that they are different from strings, which all begin with
a digit.

[section EXAMPLES]

[vset CATEGORY bee]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

335
336
337
338
339
340
341
342
343
By wrapping an integer number into [const i]...[const e] the format
makes sure that they are different from strings, which all begin with
a digit.

[section EXAMPLES]

[vset CATEGORY bee]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bench/bench.man.

288
289
290
291
292
293
294
295
296
The benchmark could be executed, however the result from its body did
not match the declared expectations.

[list_end]
[list_end]

[vset CATEGORY bench]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

288
289
290
291
292
293
294
295
296
The benchmark could be executed, however the result from its body did
not match the declared expectations.

[list_end]
[list_end]

[vset CATEGORY bench]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bench/bench_intro.man.

83
84
85
86
87
88
89
90
91
[section {HISTORICAL NOTES}]

This module and package have been derived from Jeff Hobbs'
[syscmd tclbench] application for the benchmarking of the Tcl core and
its ancestor [file runbench.tcl].

[vset CATEGORY bench]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

83
84
85
86
87
88
89
90
91
[section {HISTORICAL NOTES}]

This module and package have been derived from Jeff Hobbs'
[syscmd tclbench] application for the benchmarking of the Tcl core and
its ancestor [file runbench.tcl].

[vset CATEGORY bench]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bench/bench_lang_intro.man.

145
146
147
148
149
150
151
152
153
to understand the formal [term {bench language specfication}]. It will
also serve as the detailed specification and cheat sheet for all
available commands and their syntax.

[para]

[vset CATEGORY bench]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

145
146
147
148
149
150
151
152
153
to understand the formal [term {bench language specfication}]. It will
also serve as the detailed specification and cheat sheet for all
available commands and their syntax.

[para]

[vset CATEGORY bench]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bench/bench_lang_spec.man.

124
125
126
127
128
129
130
131
132
responsibility is to create whatever resources are needed by the body
to run without failing.

[list_end]
[list_end]

[vset CATEGORY bench]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

124
125
126
127
128
129
130
131
132
responsibility is to create whatever resources are needed by the body
to run without failing.

[list_end]
[list_end]

[vset CATEGORY bench]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bench/bench_read.man.

57
58
59
60
61
62
63
64
65
[para]

and automatically detects which format is used by the input file.

[list_end]

[vset CATEGORY bench]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

57
58
59
60
61
62
63
64
65
[para]

and automatically detects which format is used by the input file.

[list_end]

[vset CATEGORY bench]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bench/bench_wcsv.man.

46
47
48
49
50
51
52
53
54
For other formatting styles see the packages [package bench] and
[package bench::out::text] which provide commands to format benchmark
results in raw form, or for human consumption, respectively.

[list_end]

[vset CATEGORY bench]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

46
47
48
49
50
51
52
53
54
For other formatting styles see the packages [package bench] and
[package bench::out::text] which provide commands to format benchmark
results in raw form, or for human consumption, respectively.

[list_end]

[vset CATEGORY bench]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bench/bench_wtext.man.

47
48
49
50
51
52
53
54
55
For other formatting styles see the packages [package bench] and
[package bench::out::csv] which provide commands to format benchmark
results in raw form, or as importable CSV data, respectively.

[list_end]

[vset CATEGORY bench]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

47
48
49
50
51
52
53
54
55
For other formatting styles see the packages [package bench] and
[package bench::out::csv] which provide commands to format benchmark
results in raw form, or as importable CSV data, respectively.

[list_end]

[vset CATEGORY bench]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/bibtex/bibtex.man.

172
173
174
175
176
177
178
179
180
replacement strings. This command has the correct signature for use as
a [option -stringcommand] callback in an invokation of the command
[cmd ::bibtex::parse].

[list_end]

[vset CATEGORY bibtex]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

172
173
174
175
176
177
178
179
180
replacement strings. This command has the correct signature for use as
a [option -stringcommand] callback in an invokation of the command
[cmd ::bibtex::parse].

[list_end]

[vset CATEGORY bibtex]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/blowfish/blowfish.man.

156
157
158
159
160
161
162
163
164
[list_end]

[section AUTHORS]
Frank Pilhofer, Pat Thoyts

[vset CATEGORY blowfish]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

156
157
158
159
160
161
162
163
164
[list_end]

[section AUTHORS]
Frank Pilhofer, Pat Thoyts

[vset CATEGORY blowfish]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/cache/async.man.

136
137
138
139
140
141
142
143
144
This method resets the state of either the specified [arg key] or of
all keys known to the cache, making it unkown. This forces future
[method get]-requests to reload the information from the provider.

[list_end]

[vset CATEGORY cache]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

136
137
138
139
140
141
142
143
144
This method resets the state of either the specified [arg key] or of
all keys known to the cache, making it unkown. This forces future
[method get]-requests to reload the information from the provider.

[list_end]

[vset CATEGORY cache]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/clock/iso8601.man.

39
40
41
42
43
44
45
46
47
[option -locale], and
[option -timezone]
of the builtin command [cmd {clock scan}].

[list_end]

[vset CATEGORY clock::iso8601]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

39
40
41
42
43
44
45
46
47
[option -locale], and
[option -timezone]
of the builtin command [cmd {clock scan}].

[list_end]

[vset CATEGORY clock::iso8601]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/clock/rfc2822.man.

19
20
21
22
23
24
25
26
27
This command parses an RFC2822 date string and returns
the given date in seconds since epoch. An error is thrown
if the command is unable to parse the date.

[list_end]

[vset CATEGORY clock::rfc2822]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

19
20
21
22
23
24
25
26
27
This command parses an RFC2822 date string and returns
the given date in seconds since epoch. An error is thrown
if the command is unable to parse the date.

[list_end]

[vset CATEGORY clock::rfc2822]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/cmdline/cmdline.man.

196
197
198
199
200
201
202
203
204
This example, taken (and slightly modified) from the package
[package fileutil], shows how to use cmdline.  First, a list of
options is created, then the 'args' list is passed to cmdline for
processing.  Subsequently, different options are checked to see if
they have been passed to the script, and what their value is.

[vset CATEGORY cmdline]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

196
197
198
199
200
201
202
203
204
This example, taken (and slightly modified) from the package
[package fileutil], shows how to use cmdline.  First, a list of
options is created, then the 'args' list is passed to cmdline for
processing.  Subsequently, different options are checked to see if
they have been passed to the script, and what their value is.

[vset CATEGORY cmdline]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/comm/comm.man.

1224
1225
1226
1227
1228
1229
1230
1231
1232
[para]
Andreas Kupries <[email protected]> uses
[package comm] and has built a simple nameserver as part of his Pool
library.  See [uri http://www.purl.org/net/akupries/soft/pool/index.htm].

[vset CATEGORY comm]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

1224
1225
1226
1227
1228
1229
1230
1231
1232
[para]
Andreas Kupries <[email protected]> uses
[package comm] and has built a simple nameserver as part of his Pool
library.  See [uri http://www.purl.org/net/akupries/soft/pool/index.htm].

[vset CATEGORY comm]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/comm/comm_wire.man.

276
277
278
279
280
281
282
283
284
		 negotiated.

		 IOW if v2 is used the client will not see a version
	         reply during the negotiation handshake.
}]

[vset CATEGORY comm]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

276
277
278
279
280
281
282
283
284
		 negotiated.

		 IOW if v2 is used the client will not see a version
	         reply during the negotiation handshake.
}]

[vset CATEGORY comm]
[include ../common-text/feedback.inc]
[manpage_end]

Name change from modules/doctools2base/include/feedback.inc to modules/common-text/feedback.inc.

Changes to modules/control/control.man.

157
158
159
160
161
162
163
164
165
% catch a
1
% catch b
0
}]

[vset CATEGORY control]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

157
158
159
160
161
162
163
164
165
% catch a
1
% catch b
0
}]

[vset CATEGORY control]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/coroutine/coro_auto.man.

38
39
40
41
42
43
44
45
46
[def [cmd global]]
[def [cmd read]]
[def [cmd update]]
[def [cmd vwait]]
[list_end]

[vset CATEGORY coroutine]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

38
39
40
41
42
43
44
45
46
[def [cmd global]]
[def [cmd read]]
[def [cmd update]]
[def [cmd vwait]]
[list_end]

[vset CATEGORY coroutine]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/coroutine/tcllib_coroutine.man.

109
110
111
112
113
114
115
116
117
This command causes the coroutine calling it to wait for a write to
the named namespace variable [arg varname].

[list_end]

[vset CATEGORY coroutine]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

109
110
111
112
113
114
115
116
117
This command causes the coroutine calling it to wait for a write to
the named namespace variable [arg varname].

[list_end]

[vset CATEGORY coroutine]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/counter/counter.man.

242
243
244
245
246
247
248
249
250
Resets the counter with the name [arg tag] to an initial state. The
[arg args] determine the new characteristics of the counter. They have
the same meaning as described for [cmd ::counter::init].

[list_end]

[vset CATEGORY counter]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

242
243
244
245
246
247
248
249
250
Resets the counter with the name [arg tag] to an initial state. The
[arg args] determine the new characteristics of the counter. They have
the same meaning as described for [cmd ::counter::init].

[list_end]

[vset CATEGORY counter]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/crc/cksum.man.

123
124
125
126
127
128
129
130
131
2609532967
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY crc]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

123
124
125
126
127
128
129
130
131
2609532967
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY crc]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/crc/crc16.man.

141
142
143
144
145
146
147
148
149
51675
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY crc]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

141
142
143
144
145
146
147
148
149
51675
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY crc]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/crc/crc32.man.

144
145
146
147
148
149
150
151
152
3964322768
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY crc]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

144
145
146
147
148
149
150
151
152
3964322768
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY crc]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/crc/sum.man.

100
101
102
103
104
105
106
107
108
13392
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY crc]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

100
101
102
103
104
105
106
107
108
13392
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY crc]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/cron/cron.man.

178
179
180
181
182
183
184
185
186
[para]
[arg newtime] is expressed in absolute milliseconds since the beginning of the epoch.


[list_end]
[para]
[vset CATEGORY odie]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

178
179
180
181
182
183
184
185
186
[para]
[arg newtime] is expressed in absolute milliseconds since the beginning of the epoch.


[list_end]
[para]
[vset CATEGORY odie]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/csv/csv.man.

239
240
241
242
243
244
245
246
247
d) (the empty string)
}]

instead. As can be seen only item (d) is different, now the empty string
instead of a ".

[vset CATEGORY csv]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

239
240
241
242
243
244
245
246
247
d) (the empty string)
}]

instead. As can be seen only item (d) is different, now the empty string
instead of a ".

[vset CATEGORY csv]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/debug/debug.man.

239
240
241
242
243
244
245
246
247
[para] The result of the method is the specified text.

[comment {= = == === ===== ======== ============= =====================}]
[list_end]

[vset CATEGORY debug]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

239
240
241
242
243
244
245
246
247
[para] The result of the method is the specified text.

[comment {= = == === ===== ======== ============= =====================}]
[list_end]

[vset CATEGORY debug]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/debug/debug_caller.man.

36
37
38
39
40
41
42
43
44
The main anticipiated use case for this is the exclusion of arguments
expected to contain large Tcl values, i.e. long lists, large
dictionaries, etc. to prevent them from overwhelming the narrative.

[list_end]

[vset CATEGORY debug]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

36
37
38
39
40
41
42
43
44
The main anticipiated use case for this is the exclusion of arguments
expected to contain large Tcl values, i.e. long lists, large
dictionaries, etc. to prevent them from overwhelming the narrative.

[list_end]

[vset CATEGORY debug]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/debug/debug_heartbeat.man.

35
36
37
38
39
40
41
42
43
counter and the time in milliseconds since the last beat, thus
providing insight into timing variationsn and deviations from the
nominal [arg delta].

[list_end]

[vset CATEGORY debug]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

35
36
37
38
39
40
41
42
43
counter and the time in milliseconds since the last beat, thus
providing insight into timing variationsn and deviations from the
nominal [arg delta].

[list_end]

[vset CATEGORY debug]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/debug/debug_timestamp.man.

26
27
28
29
30
31
32
33
34
last call, making it useful in a tag-specific prefix to automatically
provide caller information for all uses of the tag. Or in a message,
when only specific places need such detail.

[list_end]

[vset CATEGORY debug]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

26
27
28
29
30
31
32
33
34
last call, making it useful in a tag-specific prefix to automatically
provide caller information for all uses of the tag. Or in a message,
when only specific places need such detail.

[list_end]

[vset CATEGORY debug]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/defer/defer.man.

94
95
96
97
98
99
100
101
102
[enum]
[list_end]

[section AUTHORS]
Roy Keene

[vset CATEGORY defer]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

94
95
96
97
98
99
100
101
102
[enum]
[list_end]

[section AUTHORS]
Roy Keene

[vset CATEGORY defer]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/des/des.man.

198
199
200
201
202
203
204
205
206
[section "AUTHORS"]
Jochen C Loewer,
Mac Cody,
Pat Thoyts

[vset CATEGORY des]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

198
199
200
201
202
203
204
205
206
[section "AUTHORS"]
Jochen C Loewer,
Mac Cody,
Pat Thoyts

[vset CATEGORY des]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/des/tcldes.man.

18
19
20
21
22
23
24
25
26
[para]

The [package tclDES] package is a helper package for [package des].

[para] Please see the documentation of [package des] for details.

[vset CATEGORY des]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

18
19
20
21
22
23
24
25
26
[para]

The [package tclDES] package is a helper package for [package des].

[para] Please see the documentation of [package des] for details.

[vset CATEGORY des]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/des/tcldesjr.man.

18
19
20
21
22
23
24
25
26
[para]

The [package tclDESjr] package is a helper package for [package des].

[para] Please see the documentation of [package des] for details.

[vset CATEGORY des]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

18
19
20
21
22
23
24
25
26
[para]

The [package tclDESjr] package is a helper package for [package des].

[para] Please see the documentation of [package des] for details.

[vset CATEGORY des]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/dicttool/dicttool.man.

70
71
72
73
74
75
76
77
78
  }
}
}]

[list_end]

[vset CATEGORY dict]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

70
71
72
73
74
75
76
77
78
  }
}
}]

[list_end]

[vset CATEGORY dict]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/dns/tcllib_dns.man.

283
284
285
286
287
288
289
290
291
[list_end]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY dns]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

283
284
285
286
287
288
289
290
291
[list_end]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY dns]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/dns/tcllib_ip.man.

443
444
445
446
447
448
449
450
451
[list_end]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY dns]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

443
444
445
446
447
448
449
450
451
[list_end]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY dns]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/changelog.man.

79
80
81
82
83
84
85
86
87
command merges all of them into a single structure, and collapses
multiple entries for the same date and author into a single entry. The
new structure is returned as the result of the command.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

79
80
81
82
83
84
85
86
87
command merges all of them into a single structure, and collapses
multiple entries for the same date and author into a single entry. The
new structure is returned as the result of the command.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/cvs.man.

93
94
95
96
97
98
99
100
101
logs. It takes this information and converts it into a text in the
format of a ChangeLog as accepted and generated by [syscmd emacs]. The
constructed text is returned as the result of the command.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

93
94
95
96
97
98
99
100
101
logs. It takes this information and converts it into a text in the
format of a ChangeLog as accepted and generated by [syscmd emacs]. The
constructed text is returned as the result of the command.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/docidx.man.

402
403
404
405
406
407
408
409
410
This engine generates Wiki markup as understood by Jean Claude
Wippler's [syscmd wikit] application.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

402
403
404
405
406
407
408
409
410
This engine generates Wiki markup as understood by Jean Claude
Wippler's [syscmd wikit] application.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/docidx_intro.man.

98
99
100
101
102
103
104
105
106
respectively.

They are described in their own sets of documents, starting at the
[term {doctoc introduction}] and the [term {doctools introduction}],
respectively.

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

98
99
100
101
102
103
104
105
106
respectively.

They are described in their own sets of documents, starting at the
[term {doctoc introduction}] and the [term {doctools introduction}],
respectively.

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/docidx_lang_cmdref.man.

108
109
110
111
112
113
114
115
116
Templating. In this form the command is replaced by the value of the
named document variable

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

108
109
110
111
112
113
114
115
116
Templating. In this form the command is replaced by the value of the
named document variable

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/docidx_lang_faq.man.

20
21
22
23
24
25
26
27
28
[section OVERVIEW]

[include include/placeholder.inc]
[include include/examples.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

20
21
22
23
24
25
26
27
28
[section OVERVIEW]

[include include/placeholder.inc]
[include include/examples.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/docidx_lang_intro.man.

206
207
208
209
210
211
212
213
214
On the other hand, docidx is perfectly suited for the automatic
generation from doctools documents, and this is the route Tcllib's
easy and simple [syscmd dtplite] goes, creating an index for a set of
documents behind the scenes, without the writer having to do so on
their own.

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

206
207
208
209
210
211
212
213
214
On the other hand, docidx is perfectly suited for the automatic
generation from doctools documents, and this is the route Tcllib's
easy and simple [syscmd dtplite] goes, creating an index for a set of
documents behind the scenes, without the writer having to do so on
their own.

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/docidx_lang_syntax.man.

112
113
114
115
116
117
118
119
120
[enum][cmd rb], or
[enum][cmd vset] (1-argument form).
[list_end]

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

112
113
114
115
116
117
118
119
120
[enum][cmd rb], or
[enum][cmd vset] (1-argument form).
[list_end]

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/docidx_plugin_apiref.man.

413
414
415
416
417
418
419
420
421
[para] The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

413
414
415
416
417
418
419
420
421
[para] The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctoc.man.

402
403
404
405
406
407
408
409
410
This engine generates Wiki markup as understood by Jean Claude
Wippler's [syscmd wikit] application.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

402
403
404
405
406
407
408
409
410
This engine generates Wiki markup as understood by Jean Claude
Wippler's [syscmd wikit] application.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctoc_intro.man.

97
98
99
100
101
102
103
104
105
of [term {keyword indices}], and general documentation, respectively.

They are described in their own sets of documents, starting at the
[term {docidx introduction}] and the [term {doctools introduction}],
respectively.

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

97
98
99
100
101
102
103
104
105
of [term {keyword indices}], and general documentation, respectively.

They are described in their own sets of documents, starting at the
[term {docidx introduction}] and the [term {doctools introduction}],
respectively.

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctoc_lang_cmdref.man.

119
120
121
122
123
124
125
126
127
Templating. In this form the command is replaced by the value of the
named document variable

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

119
120
121
122
123
124
125
126
127
Templating. In this form the command is replaced by the value of the
named document variable

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctoc_lang_faq.man.

20
21
22
23
24
25
26
27
28
[section OVERVIEW]

[include include/placeholder.inc]
[include include/examples.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

20
21
22
23
24
25
26
27
28
[section OVERVIEW]

[include include/placeholder.inc]
[include include/examples.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctoc_lang_intro.man.

289
290
291
292
293
294
295
296
297
On the other hand, doctoc is perfectly suited for the automatic
generation from doctools documents, and this is the route Tcllib's
easy and simple [syscmd dtplite] goes, creating a table of contents
for a set of documents behind the scenes, without the writer having to
do so on their own.

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

289
290
291
292
293
294
295
296
297
On the other hand, doctoc is perfectly suited for the automatic
generation from doctools documents, and this is the route Tcllib's
easy and simple [syscmd dtplite] goes, creating a table of contents
for a set of documents behind the scenes, without the writer having to
do so on their own.

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctoc_lang_syntax.man.

97
98
99
100
101
102
103
104
105
division  = DIVISION_START
            contents
            DIVISION_END
}]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

97
98
99
100
101
102
103
104
105
division  = DIVISION_START
            contents
            DIVISION_END
}]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctoc_plugin_apiref.man.

413
414
415
416
417
418
419
420
421
[para] The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

413
414
415
416
417
418
419
420
421
[para] The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctools.man.

567
568
569
570
571
572
573
574
575
This engine generates Wiki markup as understood by Jean Claude
Wippler's [syscmd wikit] application.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

567
568
569
570
571
572
573
574
575
This engine generates Wiki markup as understood by Jean Claude
Wippler's [syscmd wikit] application.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctools_intro.man.

95
96
97
98
99
100
101
102
103
respectively.

They are described in their own sets of documents, starting at the
[term {docidx introduction}] and the [term {doctoc introduction}],
respectively.

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

95
96
97
98
99
100
101
102
103
respectively.

They are described in their own sets of documents, starting at the
[term {docidx introduction}] and the [term {doctoc introduction}],
respectively.

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctools_lang_cmdref.man.

462
463
464
465
466
467
468
469
470
Text markup. The argument is marked up as the name of a
[term widget]. The text may have other markup already applied to
it. Main use is the highlighting of widget names in free-form text.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

462
463
464
465
466
467
468
469
470
Text markup. The argument is marked up as the name of a
[term widget]. The text may have other markup already applied to
it. Main use is the highlighting of widget names in free-form text.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctools_lang_faq.man.

20
21
22
23
24
25
26
27
28
[section OVERVIEW]

[include include/placeholder.inc]
[include include/examples.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

20
21
22
23
24
25
26
27
28
[section OVERVIEW]

[include include/placeholder.inc]
[include include/examples.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctools_lang_intro.man.

69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
...
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
...
609
610
611
612
613
614
615
616
617
[keywords {doctools language}]
[keywords {doctools markup}]
[keywords {doctools syntax}]
[keywords markup]
[keywords {semantic markup}]
    [description]
    [vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
}]

This also shows us that all doctools documents are split into two
parts, the [term header] and the [term body]. Everything coming before
[lb][cmd description][rb] belongs to the header, and everything coming
after belongs to the body, with the whole document bracketed by the
................................................................................
Remember that the whitespace is optional. The document

[example {
    [manpage_begin NAME SECTION VERSION]
    [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
    [require PACKAGE VERSION][require PACKAGE][description]
    [vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
}]

has the same meaning as the example before.

[para]

................................................................................
To be able to validate a document while writing it, it is also
recommended to familiarize oneself with one of the applications for
the processing and conversion of doctools documents, i.e. either
Tcllib's easy and simple [syscmd dtplite], or Tclapps'
ultra-configurable [syscmd dtp].

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|







 







|







 







|

69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
...
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
...
609
610
611
612
613
614
615
616
617
[keywords {doctools language}]
[keywords {doctools markup}]
[keywords {doctools syntax}]
[keywords markup]
[keywords {semantic markup}]
    [description]
    [vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]
}]

This also shows us that all doctools documents are split into two
parts, the [term header] and the [term body]. Everything coming before
[lb][cmd description][rb] belongs to the header, and everything coming
after belongs to the body, with the whole document bracketed by the
................................................................................
Remember that the whitespace is optional. The document

[example {
    [manpage_begin NAME SECTION VERSION]
    [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
    [require PACKAGE VERSION][require PACKAGE][description]
    [vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]
}]

has the same meaning as the example before.

[para]

................................................................................
To be able to validate a document while writing it, it is also
recommended to familiarize oneself with one of the applications for
the processing and conversion of doctools documents, i.e. either
Tcllib's easy and simple [syscmd dtplite], or Tclapps'
ultra-configurable [syscmd dtp].

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctools_lang_syntax.man.

134
135
136
137
138
139
140
141
142
enum_list   = [ <WHITE> ] { ENUM         paras }
item_list   = [ <WHITE> ] { ITEM         paras }
optd_list   = [ <WHITE> ] { OPT_DEF      paras }
tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
}]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

134
135
136
137
138
139
140
141
142
enum_list   = [ <WHITE> ] { ENUM         paras }
item_list   = [ <WHITE> ] { ITEM         paras }
optd_list   = [ <WHITE> ] { OPT_DEF      paras }
tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
}]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/doctools_plugin_apiref.man.

470
471
472
473
474
475
476
477
478
[para] The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

470
471
472
473
474
475
476
477
478
[para] The formatted text is expected as the result of the command,
and added to the output. If no special processing is required it has
to simply return its argument without change.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools/mpexpand.man.

99
100
101
102
103
104
105
106
107
[section NOTES]
[para]

Possible future formats are plain text, pdf and postscript.

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

99
100
101
102
103
104
105
106
107
[section NOTES]
[para]

Possible future formats are plain text, pdf and postscript.

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2base/html_cssdefaults.man.

32
33
34
35
36
37
38
39
40
This command returns the text of the default CSS style to use for HTML
markup generated by the various HTML export plugins.

[list_end]

[vset CATEGORY doctools]
[include include/feedback.inc]
[manpage_end]






|

32
33
34
35
36
37
38
39
40
This command returns the text of the default CSS style to use for HTML
markup generated by the various HTML export plugins.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2base/nroff_manmacros.man.

32
33
34
35
36
37
38
39
40
This command returns the text of the default CSS style to use for NROFF
generated by the various NROFF export plugins.

[list_end]

[vset CATEGORY doctools]
[include include/feedback.inc]
[manpage_end]






|

32
33
34
35
36
37
38
39
40
This command returns the text of the default CSS style to use for NROFF
generated by the various NROFF export plugins.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2base/tcl_parse.man.

176
177
178
179
180
181
182
183
184
[enum]
All leaves of the tree are either Text or Command nodes.
Word nodes cannot be leaves.
[list_end]

[vset CATEGORY doctools]
[include include/feedback.inc]
[manpage_end]






|

176
177
178
179
180
181
182
183
184
[enum]
All leaves of the tree are either Text or Command nodes.
Word nodes cannot be leaves.
[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2base/tcllib_msgcat.man.

59
60
61
62
63
64
65
66
67
"doctools::msgcat::[arg prefix]::[var langcode]", with [arg prefix]
the argument to the command, and the [var langcode] supplied by the
result of [cmd msgcat::mcpreferences].

[list_end]

[vset CATEGORY doctools]
[include include/feedback.inc]
[manpage_end]






|

59
60
61
62
63
64
65
66
67
"doctools::msgcat::[arg prefix]::[var langcode]", with [arg prefix]
the argument to the command, and the [var langcode] supplied by the
result of [cmd msgcat::mcpreferences].

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/idx_container.man.

288
289
290
291
292
293
294
295
296
In that case an error will be thrown if the container has no export
manager attached to it.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

288
289
290
291
292
293
294
295
296
In that case an error will be thrown if the container has no export
manager attached to it.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/idx_export.man.

301
302
303
304
305
306
307
308
309
       the command [cmd export]. This call has to leave the plugin in
       a state where another usage cycle can be run without problems.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

301
302
303
304
305
306
307
308
309
       the command [cmd export]. This call has to leave the plugin in
       a state where another usage cycle can be run without problems.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/idx_import.man.

387
388
389
390
391
392
393
394
395
       the command [cmd import]. This call has to leave the plugin in
       a state where another usage cycle can be run without problems.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

387
388
389
390
391
392
393
394
395
       the command [cmd import]. This call has to leave the plugin in
       a state where another usage cycle can be run without problems.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/idx_introduction.man.

138
139
140
141
142
143
144
145
146
the [manpage {DocTools - Tables Of Contents}] and
the [manpage {DocTools - General}], respectively.

[section {Package Overview}]
[include include/dependencies.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

138
139
140
141
142
143
144
145
146
the [manpage {DocTools - Tables Of Contents}] and
the [manpage {DocTools - General}], respectively.

[section {Package Overview}]
[include include/dependencies.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/idx_parse.man.

167
168
169
170
171
172
173
174
175
[list_end]
[list_end]

[include include/format/docidx.inc]
[include include/serialization.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

167
168
169
170
171
172
173
174
175
[list_end]
[list_end]

[include include/format/docidx.inc]
[include include/serialization.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/idx_structure.man.

121
122
123
124
125
126
127
128
129
[sectref {Keyword index serialization format}].

[list_end]

[include include/serialization.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

121
122
123
124
125
126
127
128
129
[sectref {Keyword index serialization format}].

[list_end]

[include include/serialization.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/include/export/plugin.inc.

47
48
49
50
51
52
53
54
55
[list_end]

[include config/[vset CONFIG].inc]
[include ../serialization.inc]

[vset CATEGORY doctools]
[include ../../../doctools2base/include/feedback.inc]
[manpage_end]






|

47
48
49
50
51
52
53
54
55
[list_end]

[include config/[vset CONFIG].inc]
[include ../serialization.inc]

[vset CATEGORY doctools]
[include ../../../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/include/import/plugin.inc.

48
49
50
51
52
53
54
55
56
[list_end]


[include config/[vset CONFIG].inc]
[include ../serialization.inc]

[vset CATEGORY doctools]
[include ../../../doctools2base/include/feedback.inc]
[manpage_end]






|

48
49
50
51
52
53
54
55
56
[list_end]


[include config/[vset CONFIG].inc]
[include ../serialization.inc]

[vset CATEGORY doctools]
[include ../../../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2idx/include/msgcat.inc.

38
39
40
41
42
43
44
45
46
[section API]

This package has no exported API.


[vset CATEGORY doctools]
[include ../../doctools2base/include/feedback.inc]
[manpage_end]






|

38
39
40
41
42
43
44
45
46
[section API]

This package has no exported API.


[vset CATEGORY doctools]
[include ../../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/include/export/plugin.inc.

47
48
49
50
51
52
53
54
55
[list_end]

[include config/[vset CONFIG].inc]
[include ../serialization.inc]

[vset CATEGORY doctools]
[include ../../../doctools2base/include/feedback.inc]
[manpage_end]






|

47
48
49
50
51
52
53
54
55
[list_end]

[include config/[vset CONFIG].inc]
[include ../serialization.inc]

[vset CATEGORY doctools]
[include ../../../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/include/import/plugin.inc.

48
49
50
51
52
53
54
55
56
[list_end]


[include config/[vset CONFIG].inc]
[include ../serialization.inc]

[vset CATEGORY doctools]
[include ../../../doctools2base/include/feedback.inc]
[manpage_end]






|

48
49
50
51
52
53
54
55
56
[list_end]


[include config/[vset CONFIG].inc]
[include ../serialization.inc]

[vset CATEGORY doctools]
[include ../../../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/include/msgcat.inc.

38
39
40
41
42
43
44
45
46
[section API]

This package has no exported API.


[vset CATEGORY doctools]
[include ../../doctools2base/include/feedback.inc]
[manpage_end]






|

38
39
40
41
42
43
44
45
46
[section API]

This package has no exported API.


[vset CATEGORY doctools]
[include ../../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/toc_container.man.

362
363
364
365
366
367
368
369
370
In that case an error will be thrown if the container has no export
manager attached to it.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

362
363
364
365
366
367
368
369
370
In that case an error will be thrown if the container has no export
manager attached to it.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/toc_export.man.

299
300
301
302
303
304
305
306
307
       the command [cmd export]. This call has to leave the plugin in
       a state where another usage cycle can be run without problems.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

299
300
301
302
303
304
305
306
307
       the command [cmd export]. This call has to leave the plugin in
       a state where another usage cycle can be run without problems.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/toc_import.man.

387
388
389
390
391
392
393
394
395
       the command [cmd import]. This call has to leave the plugin in
       a state where another usage cycle can be run without problems.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

387
388
389
390
391
392
393
394
395
       the command [cmd import]. This call has to leave the plugin in
       a state where another usage cycle can be run without problems.

[list_end]

[include include/serialization.inc]
[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/toc_introduction.man.

135
136
137
138
139
140
141
142
143
the [manpage {DocTools - Keyword Indices}] and
the [manpage {DocTools - General}], respectively.

[section {Package Overview}]
[include include/dependencies.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

135
136
137
138
139
140
141
142
143
the [manpage {DocTools - Keyword Indices}] and
the [manpage {DocTools - General}], respectively.

[section {Package Overview}]
[include include/dependencies.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/toc_parse.man.

167
168
169
170
171
172
173
174
175
[list_end]
[list_end]

[include include/format/doctoc.inc]
[include include/serialization.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

167
168
169
170
171
172
173
174
175
[list_end]
[list_end]

[include include/format/doctoc.inc]
[include include/serialization.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/doctools2toc/toc_structure.man.

143
144
145
146
147
148
149
150
151
section [sectref {ToC serialization format}].

[list_end]

[include include/serialization.inc]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

143
144
145
146
147
148
149
150
151
section [sectref {ToC serialization format}].

[list_end]

[include include/serialization.inc]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/dtplite/pkg_dtplite.man.

441
442
443
444
445
446
447
448
449
They are left in place, i.e. not deleted, to serve as demonstrations
of doctoc and docidx markup.

[list_end]

[vset CATEGORY doctools]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

441
442
443
444
445
446
447
448
449
They are left in place, i.e. not deleted, to serve as demonstrations
of doctoc and docidx markup.

[list_end]

[vset CATEGORY doctools]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/exif/exif.man.

72
73
74
75
76
77
78
79
80
[section ACKNOWLEDGEMENTS]

This code is a direct translation of version 1.3 of exif.pl by Chris
Breeze.  See the source for full headers, references, etc.

[vset CATEGORY exif]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

72
73
74
75
76
77
78
79
80
[section ACKNOWLEDGEMENTS]

This code is a direct translation of version 1.3 of exif.pl by Chris
Breeze.  See the source for full headers, references, etc.

[vset CATEGORY exif]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fileutil/fileutil.man.

514
515
516
517
518
519
520
521
522
option to prevent the traverser from following symbolic links, like so:

[include include/cross-index-trav.inc]

[list_end]

[vset CATEGORY fileutil]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

514
515
516
517
518
519
520
521
522
option to prevent the traverser from following symbolic links, like so:

[include include/cross-index-trav.inc]

[list_end]

[vset CATEGORY fileutil]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fileutil/multi.man.

48
49
50
51
52
53
54
55
56
The result of the command is the result generated by the last file
command it executed.

[list_end]

[vset CATEGORY fileutil]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

48
49
50
51
52
53
54
55
56
The result of the command is the result generated by the last file
command it executed.

[list_end]

[vset CATEGORY fileutil]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fileutil/multiop.man.

394
395
396
397
398
399
400
401
402
    into /scratch           \\
    but not *.html not index \\
    the  index               \\
    as   pkgIndex.tcl
}]

[vset CATEGORY fileutil]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

394
395
396
397
398
399
400
401
402
    into /scratch           \\
    but not *.html not index \\
    the  index               \\
    as   pkgIndex.tcl
}]

[vset CATEGORY fileutil]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fileutil/paths.man.

68
69
70
71
72
73
74
75
76
Unknown paths are ignored without error.

The result of the command is the empty string.

[list_end]

[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

68
69
70
71
72
73
74
75
76
Unknown paths are ignored without error.

The result of the command is the empty string.

[list_end]

[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fileutil/traverse.man.

157
158
159
160
161
162
163
164
165
traverser from following symbolic links, like so:

[include include/cross-index-trav.inc]

[list_end]

[vset CATEGORY fileutil]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

157
158
159
160
161
162
163
164
165
traverser from following symbolic links, like so:

[include include/cross-index-trav.inc]

[list_end]

[vset CATEGORY fileutil]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ftp/ftp.man.

432
433
434
435
436
437
438
439
440
[para]

An update command placed in the procedure [cmd ::ftp::DisplayMsg] may
run into persistent errors or infinite loops. The solution to this
problem is to use [cmd {update idletasks}] instead of [cmd update].

[vset CATEGORY ftp]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

432
433
434
435
436
437
438
439
440
[para]

An update command placed in the procedure [cmd ::ftp::DisplayMsg] may
run into persistent errors or infinite loops. The solution to this
problem is to use [cmd {update idletasks}] instead of [cmd update].

[vset CATEGORY ftp]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ftp/ftp_geturl.man.

49
50
51
52
53
54
55
56
57
The attributes of the link, including the path it refers to.

[list_end]
[list_end]

[vset CATEGORY ftp]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

49
50
51
52
53
54
55
56
57
The attributes of the link, including the path it refers to.

[list_end]
[list_end]

[vset CATEGORY ftp]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ftpd/ftpd.man.

271
272
273
274
275
276
277
278
279
Accessible to all callbacks and all filesystem commands (which are a
special form of callback) and contains the handle of the socket
channel which was active when the callback was invoked.

[list_end]

[vset CATEGORY ftpd]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

271
272
273
274
275
276
277
278
279
Accessible to all callbacks and all filesystem commands (which are a
special form of callback) and contains the handle of the socket
channel which was active when the callback was invoked.

[list_end]

[vset CATEGORY ftpd]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fumagic/cfront.man.

63
64
65
66
67
68
69
70
71
The name of each new procedure is derived from the name of the
file/directory used in its creation, with file/directory [file FOO]
causing the creation of procedure [const ::fileutil::magic::/FOO::run].

[list_end]

[vset CATEGORY {fileutil :: magic}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

63
64
65
66
67
68
69
70
71
The name of each new procedure is derived from the name of the
file/directory used in its creation, with file/directory [file FOO]
causing the creation of procedure [const ::fileutil::magic::/FOO::run].

[list_end]

[vset CATEGORY {fileutil :: magic}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fumagic/cgen.man.

55
56
57
58
59
60
61
62
63
The generated script makes extensive use of the commands provided by
the recognizer runtime package [package fileutil::magic::rt] to
perform its duties.

[list_end]

[vset CATEGORY {fileutil :: magic}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

55
56
57
58
59
60
61
62
63
The generated script makes extensive use of the commands provided by
the recognizer runtime package [package fileutil::magic::rt] to
perform its duties.

[list_end]

[vset CATEGORY {fileutil :: magic}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fumagic/filetypes.man.

54
55
56
57
58
59
60
61
62
This site contains the current sources for the file command, including
the magic definitions used by it. The latter were used by us to
generate this recognizer.

[list_end]

[vset CATEGORY {fileutil :: magic}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

54
55
56
57
58
59
60
61
62
This site contains the current sources for the file command, including
the magic definitions used by it. The latter were used by us to
generate this recognizer.

[list_end]

[vset CATEGORY {fileutil :: magic}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/fumagic/rtcore.man.

243
244
245
246
247
248
249
250
251
[def [const ledate]]  see above, stored in small/little endian
[def [const ldate]]   32-bit integer timestamp, stored in native endianess
[def [const beldate]] see above, stored in big endian
[def [const leldate]] see above, stored in small/little endian
[list_end]

[vset CATEGORY {fileutil :: magic}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

243
244
245
246
247
248
249
250
251
[def [const ledate]]  see above, stored in small/little endian
[def [const ldate]]   32-bit integer timestamp, stored in native endianess
[def [const beldate]] see above, stored in big endian
[def [const leldate]] see above, stored in small/little endian
[list_end]

[vset CATEGORY {fileutil :: magic}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/gpx/gpx.man.

150
151
152
153
154
155
156
157
158
[list_end]

[section AUTHOR]
Keith Vetter

[vset CATEGORY gpx]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

150
151
152
153
154
155
156
157
158
[list_end]

[section AUTHOR]
Keith Vetter

[vset CATEGORY gpx]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_fa/dacceptor.man.

94
95
96
97
98
99
100
101
102
[list_end]

[para]

[section EXAMPLES]

[vset CATEGORY grammar_fa]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

94
95
96
97
98
99
100
101
102
[list_end]

[para]

[section EXAMPLES]

[vset CATEGORY grammar_fa]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_fa/dexec.man.

175
176
177
178
179
180
181
182
183
[list_end]

[para]

[section EXAMPLES]

[vset CATEGORY grammar_fa]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

175
176
177
178
179
180
181
182
183
[list_end]

[para]

[section EXAMPLES]

[vset CATEGORY grammar_fa]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_fa/fa.man.

644
645
646
647
648
649
650
651
652
[para]

Transducers are not handled by this package. They will get their own
package in the future.

[vset CATEGORY grammar_fa]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

644
645
646
647
648
649
650
651
652
[para]

Transducers are not handled by this package. They will get their own
package in the future.

[vset CATEGORY grammar_fa]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_fa/faop.man.

472
473
474
475
476
477
478
479
480
[list_end]

[para]

[section EXAMPLES]

[vset CATEGORY grammar_fa]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

472
473
474
475
476
477
478
479
480
[list_end]

[para]

[section EXAMPLES]

[vset CATEGORY grammar_fa]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_me/gasm.man.

431
432
433
434
435
436
437
438
439
[para]

The command returns the empty string as its result.

[list_end]

[vset CATEGORY grammar_me]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

431
432
433
434
435
436
437
438
439
[para]

The command returns the empty string as its result.

[list_end]

[vset CATEGORY grammar_me]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_me/me_ast.man.

126
127
128
129
130
131
132
133
134
This new attribute is defined for all nodes, and contains the
locations from attribute [term range] translated into line number and
column index. Lines are counted from 1, columns are counted from 0.

[list_end]

[vset CATEGORY grammar_me]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

126
127
128
129
130
131
132
133
134
This new attribute is defined for all nodes, and contains the
locations from attribute [term range] translated into line number and
column index. Lines are counted from 1, columns are counted from 0.

[list_end]

[vset CATEGORY grammar_me]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_me/me_cpu.man.

281
282
283
284
285
286
287
288
289
[call [arg meName] [method destroy]]

This method deletes the object and releases all resurces it claimed.

[list_end]

[vset CATEGORY grammar_me]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

281
282
283
284
285
286
287
288
289
[call [arg meName] [method destroy]]

This method deletes the object and releases all resurces it claimed.

[list_end]

[vset CATEGORY grammar_me]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_me/me_cpucore.man.

366
367
368
369
370
371
372
373
374
[para]

[term nc], the nonterminal cache is keyed by nonterminal name and
location, each value a four-element list containing current location,
match status, semantic value, and error status, in this order.

[vset CATEGORY grammar_me]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

366
367
368
369
370
371
372
373
374
[para]

[term nc], the nonterminal cache is keyed by nonterminal name and
location, each value a four-element list containing current location,
match status, semantic value, and error status, in this order.

[vset CATEGORY grammar_me]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_me/me_intro.man.

86
87
88
89
90
91
92
93
94
Core functionality for state manipulation and stepping used in the
bytecode based implementation of ME virtual machines.

[list_end]
[para]

[vset CATEGORY grammar_me]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

86
87
88
89
90
91
92
93
94
Core functionality for state manipulation and stepping used in the
bytecode based implementation of ME virtual machines.

[list_end]
[para]

[vset CATEGORY grammar_me]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_me/me_tcl.man.

335
336
337
338
339
340
341
342
343
The command takes the marker as argument as it comes from the
Tcl stack, not the machine state. It replaces [term ias_mpop].

[list_end]
[para]

[vset CATEGORY grammar_me]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

335
336
337
338
339
340
341
342
343
The command takes the marker as argument as it comes from the
Tcl stack, not the machine state. It replaces [term ias_mpop].

[list_end]
[para]

[vset CATEGORY grammar_me]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_me/me_util.man.

75
76
77
78
79
80
81
82
83
If a [arg root] node is specified the AST is generated from that node
downward. Otherwise the root of the tree object is used as the
starting point.

[list_end]

[vset CATEGORY grammar_me]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

75
76
77
78
79
80
81
82
83
If a [arg root] node is specified the AST is generated from that node
downward. Otherwise the root of the tree object is used as the
starting point.

[list_end]

[vset CATEGORY grammar_me]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_me/me_vm.man.

655
656
657
658
659
660
661
662
663
This instruction pops an entry from the AST Marker stack [term MS] and
discards it.

[list_end]

[vset CATEGORY grammar_me]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

655
656
657
658
659
660
661
662
663
This instruction pops an entry from the AST Marker stack [term MS] and
discards it.

[list_end]

[vset CATEGORY grammar_me]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_peg/peg.man.

713
714
715
716
717
718
719
720
721
[enum]
[uri {http://scifac.ru.ac.za/compilers/} \
	{Compilers and Compiler Generators}], an online book using
CoCo/R, a generator for recursive descent parsers.
[list_end]

[vset CATEGORY grammar_peg]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

713
714
715
716
717
718
719
720
721
[enum]
[uri {http://scifac.ru.ac.za/compilers/} \
	{Compilers and Compiler Generators}], an online book using
CoCo/R, a generator for recursive descent parsers.
[list_end]

[vset CATEGORY grammar_peg]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/grammar_peg/peg_interp.man.

114
115
116
117
118
119
120
121
122
described in section [sectref-external {AST VALUES}] of
document [term grammar::me_ast].

[list_end]
[para]

[vset CATEGORY grammar_peg]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

114
115
116
117
118
119
120
121
122
described in section [sectref-external {AST VALUES}] of
document [term grammar::me_ast].

[list_end]
[para]

[vset CATEGORY grammar_peg]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/hook/hook.man.

367
368
369
370
371
372
373
374
375
All bindings involving [widget .view] are deleted.

[section Credits]

Hook has been designed and implemented by William H. Duquette.

[vset CATEGORY hook]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

367
368
369
370
371
372
373
374
375
All bindings involving [widget .view] are deleted.

[section Credits]

Hook has been designed and implemented by William H. Duquette.

[vset CATEGORY hook]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/html/html.man.

468
469
470
471
472
473
474
475
476
[enum] XHTML11
[enum] XHTMLB
[list_end]

[list_end]

[vset CATEGORY html]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

468
469
470
471
472
473
474
475
476
[enum] XHTML11
[enum] XHTMLB
[list_end]

[list_end]

[vset CATEGORY html]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/htmlparse/htmlparse.man.

258
259
260
261
262
263
264
265
266
[cmd ::htmlparse::2tree]. It removes all nodes representing forms and
form elements. Its only argument is the name of the tree to cut down.

[list_end]

[vset CATEGORY htmlparse]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

258
259
260
261
262
263
264
265
266
[cmd ::htmlparse::2tree]. It removes all nodes representing forms and
form elements. Its only argument is the name of the tree to cut down.

[list_end]

[vset CATEGORY htmlparse]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/http/autoproxy.man.

208
209
210
211
212
213
214
215
216
At this time only Basic authentication (1) (2) is supported. It is
planned to add support for Digest (2) and NTLM in the future.

[section AUTHORS]
Pat Thoyts

[vset CATEGORY {http :: autoproxy}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

208
209
210
211
212
213
214
215
216
At this time only Basic authentication (1) (2) is supported. It is
planned to add support for Digest (2) and NTLM in the future.

[section AUTHORS]
Pat Thoyts

[vset CATEGORY {http :: autoproxy}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/httpd/httpd.man.

57
58
59
60
61
62
63
64
65
[include build/reply.man]
[include build/content.man]

[section AUTHORS]
Sean Woods

[vset CATEGORY network]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

57
58
59
60
61
62
63
64
65
[include build/reply.man]
[include build/content.man]

[section AUTHORS]
Sean Woods

[vset CATEGORY network]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ident/ident.man.

46
47
48
49
50
51
52
53
54
to the RFC. A detailed error message is returned under the
[const error] key.

[list_end]
[list_end]

[vset CATEGORY ident]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

46
47
48
49
50
51
52
53
54
to the RFC. A detailed error message is returned under the
[const error] key.

[list_end]
[list_end]

[vset CATEGORY ident]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/imap4/imap4.man.

358
359
360
361
362
363
364
365
366
367
368
Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
RFC 3501, March 2003, [uri http://www.rfc-editor.org/rfc/rfc3501.txt]

[para]
OpenSSL, [uri http://www.openssl.org/]

[vset CATEGORY imap4]
[include ../doctools2base/include/feedback.inc]

Only a small part of rfc3501 implemented.
[manpage_end]






|



358
359
360
361
362
363
364
365
366
367
368
Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
RFC 3501, March 2003, [uri http://www.rfc-editor.org/rfc/rfc3501.txt]

[para]
OpenSSL, [uri http://www.openssl.org/]

[vset CATEGORY imap4]
[include ../common-text/feedback.inc]

Only a small part of rfc3501 implemented.
[manpage_end]

Changes to modules/inifile/ini.man.

92
93
94
95
96
97
98
99
100
Reads and sets the comment character. Lines that begin with this character are treated as
comments. When comments are written out each line is preceded by this character. The default
is [const \;].

[list_end]

[vset CATEGORY inifile]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

92
93
94
95
96
97
98
99
100
Reads and sets the comment character. Lines that begin with this character are treated as
comments. When comments are written out each line is preceded by this character. The default
is [const \;].

[list_end]

[vset CATEGORY inifile]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/interp/deleg_method.man.

41
42
43
44
45
46
47
48
49
returns the result from the remote method as its own result. If
however the option [option -async] was specified then the generated
method will not wait for a result and return immediately.

[list_end]

[vset CATEGORY interp]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

41
42
43
44
45
46
47
48
49
returns the result from the remote method as its own result. If
however the option [option -async] was specified then the generated
method will not wait for a result and return immediately.

[list_end]

[vset CATEGORY interp]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/interp/deleg_proc.man.

39
40
41
42
43
44
45
46
47
returns the result from the remote procedure as its own result. If
however the option [option -async] was specified then the generated
procedure will not wait for a result and return immediately.

[list_end]

[vset CATEGORY interp]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

39
40
41
42
43
44
45
46
47
returns the result from the remote procedure as its own result. If
however the option [option -async] was specified then the generated
procedure will not wait for a result and return immediately.

[list_end]

[vset CATEGORY interp]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/interp/tcllib_interp.man.

66
67
68
69
70
71
72
73
74
[para]

The result of the command is the empty string.

[list_end]

[vset CATEGORY interp]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

66
67
68
69
70
71
72
73
74
[para]

The result of the command is the empty string.

[list_end]

[vset CATEGORY interp]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/irc/irc.man.

232
233
234
235
236
237
238
239
240
[call [cmd msg]]

Returns the message portion of the command (the part after the :).

[list_end]

[vset CATEGORY irc]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

232
233
234
235
236
237
238
239
240
[call [cmd msg]]

Returns the message portion of the command (the part after the :).

[list_end]

[vset CATEGORY irc]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/javascript/javascript.man.

88
89
90
91
92
93
94
95
96
checked.  The [arg parentName] argument is the name of the child's
parent html checkbox object.  The [arg childName] argument is the name
of child html checkbox object to create.

[list_end]

[vset CATEGORY javascript]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

88
89
90
91
92
93
94
95
96
checked.  The [arg parentName] argument is the name of the child's
parent html checkbox object.  The [arg childName] argument is the name
of child html checkbox object to create.

[list_end]

[vset CATEGORY javascript]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/jpeg/jpeg.man.

188
189
190
191
192
193
194
195
196
can only work with files
cant write exif data
gps exif data not parsed
makernote data not yet implemented

[vset CATEGORY jpeg]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

188
189
190
191
192
193
194
195
196
can only work with files
cant write exif data
gps exif data not parsed
makernote data not yet implemented

[vset CATEGORY jpeg]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/json/json.man.

106
107
108
109
110
111
112
113
114
}]

[section RELATED]

To write json, instead of parsing it, see package [package json::write].

[vset CATEGORY json]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

106
107
108
109
110
111
112
113
114
}]

[section RELATED]

To write json, instead of parsing it, see package [package json::write].

[vset CATEGORY json]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/json/json_write.man.

84
85
86
87
88
89
90
91
92
[para]

[section RELATED]

To parse json, instead of writing it, see package [package json].

[vset CATEGORY json]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

84
85
86
87
88
89
90
91
92
[para]

[section RELATED]

To parse json, instead of writing it, see package [package json].

[vset CATEGORY json]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/lambda/lambda.man.

81
82
83
84
85
86
87
88
89
[list_end]

[section AUTHORS]
Andreas Kupries

[vset CATEGORY lambda]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

81
82
83
84
85
86
87
88
89
[list_end]

[section AUTHORS]
Andreas Kupries

[vset CATEGORY lambda]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/lazyset/lazyset.man.

72
73
74
75
76
77
78
79
80
	puts $simple
}]

[section AUTHORS]
Roy Keene

[vset CATEGORY utility]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

72
73
74
75
76
77
78
79
80
	puts $simple
}]

[section AUTHORS]
Roy Keene

[vset CATEGORY utility]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ldap/ldap.man.

541
542
543
544
545
546
547
548
549
	puts ""
    }
    ldap::unbind $handle
    ldap::disconnect $handle
}]

[vset CATEGORY ldap]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

541
542
543
544
545
546
547
548
549
	puts ""
    }
    ldap::unbind $handle
    ldap::disconnect $handle
}]

[vset CATEGORY ldap]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ldap/ldapx.man.

766
767
768
769
770
771
772
773
774
    liout destroy
    liin destroy
}]

[section References]

[vset CATEGORY ldap]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

766
767
768
769
770
771
772
773
774
    liout destroy
    liin destroy
}]

[section References]

[vset CATEGORY ldap]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/log/log.man.

281
282
283
284
285
286
287
288
289
[emph Note] that by default all messages with levels [const warning] down to
[const debug] are suppressed. This is done intentionally, because (we believe
that) in most situations debugging output is not wanted. Most people wish to
have such output only when actually debugging an application.

[vset CATEGORY log]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

281
282
283
284
285
286
287
288
289
[emph Note] that by default all messages with levels [const warning] down to
[const debug] are suppressed. This is done intentionally, because (we believe
that) in most situations debugging output is not wanted. Most people wish to
have such output only when actually debugging an application.

[vset CATEGORY log]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/log/logger.man.

389
390
391
392
393
394
395
396
397
     # install as logproc
     ${log}::logproc debug log_local_var
     }
]

[vset CATEGORY logger]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

389
390
391
392
393
394
395
396
397
     # install as logproc
     ${log}::logproc debug log_local_var
     }
]

[vset CATEGORY logger]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/log/loggerAppender.man.

57
58
59
60
61
62
63
64
65
See [cmd ::logger::appender::colorConsole] for a description of the
applicable options.

[list_end]

[vset CATEGORY logger]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

57
58
59
60
61
62
63
64
65
See [cmd ::logger::appender::colorConsole] for a description of the
applicable options.

[list_end]

[vset CATEGORY logger]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/log/loggerUtils.man.

141
142
143
144
145
146
147
148
149
  logger::utils::applyAppender -appender console
  set log [logger::init applyAppender-3]
  ${log}::error "this is an error"
}]
[list_end]

[vset CATEGORY logger]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

141
142
143
144
145
146
147
148
149
  logger::utils::applyAppender -appender console
  set log [logger::init applyAppender-3]
  ${log}::error "this is an error"
}]
[list_end]

[vset CATEGORY logger]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/markdown/markdown.man.

45
46
47
48
49
50
51
52
53
[call [cmd ::Markdown::reset_lang_counter]]

Reset the language counters.

[list_end]

[vset CATEGORY textutil]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

45
46
47
48
49
50
51
52
53
[call [cmd ::Markdown::reset_lang_counter]]

Reset the language counters.

[list_end]

[vset CATEGORY textutil]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/bigfloat.man.

424
425
426
427
428
429
430
431
432
set sinProduct [lb]mul [lb]sin $angle1[rb] [lb]sin $angle2[rb][rb]
set cosProduct [lb]mul [lb]cos $angle1[rb] [lb]cos $angle2[rb][rb]
set angle3 [lb]asin [lb]add [lb]mul $sinProduct [lb]cos $opposite3[rb][rb] $cosProduct[rb][rb]
puts "angle3 : [lb]tostr [lb]rad2deg $angle3[rb][rb]"
[example_end]

[vset CATEGORY {math :: bignum :: float}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

424
425
426
427
428
429
430
431
432
set sinProduct [lb]mul [lb]sin $angle1[rb] [lb]sin $angle2[rb][rb]
set cosProduct [lb]mul [lb]cos $angle1[rb] [lb]cos $angle2[rb][rb]
set angle3 [lb]asin [lb]add [lb]mul $sinProduct [lb]cos $opposite3[rb][rb] $cosProduct[rb][rb]
puts "angle3 : [lb]tostr [lb]rad2deg $angle3[rb][rb]"
[example_end]

[vset CATEGORY {math :: bignum :: float}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/bignum.man.

220
221
222
223
224
225
226
227
228
[call [cmd ::math::bignum::bits] [arg bignum]]
Return the number of bits needed to represent bignum in radix 2.

[list_end]
[para]

[vset CATEGORY {math :: bignum}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

220
221
222
223
224
225
226
227
228
[call [cmd ::math::bignum::bits] [arg bignum]]
Return the number of bits needed to represent bignum in radix 2.

[list_end]
[para]

[vset CATEGORY {math :: bignum}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/calculus.man.

443
444
445
446
447
448
449
450
451
   set length 100.0

   set y [lb]::math::calculus::boundaryValueSecondOrder \
      coeffs force {0.0 1.0} [lb]list $length 0.0[rb] 100[rb]
[example_end]

[vset CATEGORY {math :: calculus}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

443
444
445
446
447
448
449
450
451
   set length 100.0

   set y [lb]::math::calculus::boundaryValueSecondOrder \
      coeffs force {0.0 1.0} [lb]list $length 0.0[rb] 100[rb]
[example_end]

[vset CATEGORY {math :: calculus}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/combinatorics.man.

100
101
102
103
104
105
106
107
108
Results are returned as a floating point number precise to better than
nine significant digits provided that [arg w] and [arg z] are both at
least 1.

[list_end]

[vset CATEGORY math]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

100
101
102
103
104
105
106
107
108
Results are returned as a floating point number precise to better than
nine significant digits provided that [arg w] and [arg z] are both at
least 1.

[list_end]

[vset CATEGORY math]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/constants.man.

128
129
130
131
132
133
134
135
136
[def [const onesixth]] One sixth (0.1666....)
[def [const huge]]     (Approximately) largest number
[def [const tiny]]     (Approximately) smallest number not equal zero
[def [const eps]]      Smallest number such that 1+eps != 1
[list_end]

[vset CATEGORY {math :: constants}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

128
129
130
131
132
133
134
135
136
[def [const onesixth]] One sixth (0.1666....)
[def [const huge]]     (Approximately) largest number
[def [const tiny]]     (Approximately) smallest number not equal zero
[def [const eps]]      Smallest number such that 1+eps != 1
[list_end]

[vset CATEGORY {math :: constants}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/decimal.man.

191
192
193
194
195
196
197
198
199
Rounds [emph decimal] to [emph digits] number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow
the result is the same as for round-down.

[list_end]
[para]

[vset CATEGORY decimal]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

191
192
193
194
195
196
197
198
199
Rounds [emph decimal] to [emph digits] number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow
the result is the same as for round-down.

[list_end]
[para]

[vset CATEGORY decimal]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/fourier.man.

126
127
128
129
130
131
132
133
134
[arg_def list in_data] List of data (amplitudes)
[list_end]
[para]

[list_end]

[vset CATEGORY {math :: fourier}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

126
127
128
129
130
131
132
133
134
[arg_def list in_data] List of data (amplitudes)
[list_end]
[para]

[list_end]

[vset CATEGORY {math :: fourier}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/fuzzy.man.

125
126
127
128
129
130
131
132
133
APL QUOTE QUAD 8(3):16-23, March 1978.
[para]
D. Knuth, Art of Computer Programming,

Vol. 1, Problem 1.2.4-5.

[vset CATEGORY {math :: fuzzy}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

125
126
127
128
129
130
131
132
133
APL QUOTE QUAD 8(3):16-23, March 1978.
[para]
D. Knuth, Art of Computer Programming,

Vol. 1, Problem 1.2.4-5.

[vset CATEGORY {math :: fuzzy}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/interpolate.man.

291
292
293
294
295
296
297
298
299
0.8: 4.11
0.9: 3.95675857843
1.0: 4.12
}]
As you can see, the values at the abscissae are reproduced perfectly.

[vset CATEGORY {math :: interpolate}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

291
292
293
294
295
296
297
298
299
0.8: 4.11
0.9: 3.95675857843
1.0: 4.12
}]
As you can see, the values at the abscissae are reproduced perfectly.

[vset CATEGORY {math :: interpolate}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/linalg.man.

960
961
962
963
964
965
966
967
968
namespace eval compute {
    rename ::scale scaleTk
    scaleTk .scale ...
}
}]

[vset CATEGORY {math :: linearalgebra}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

960
961
962
963
964
965
966
967
968
namespace eval compute {
    rename ::scale scaleTk
    scaleTk .scale ...
}
}]

[vset CATEGORY {math :: linearalgebra}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/machineparameters.man.

183
184
185
186
187
188
189
190
191
[call [arg objectname] [method print]]

Print machine parameters on standard output.

[list_end]

[vset CATEGORY math]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

183
184
185
186
187
188
189
190
191
[call [arg objectname] [method print]]

Print machine parameters on standard output.

[list_end]

[vset CATEGORY math]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/math.man.

118
119
120
121
122
123
124
125
126
[call [cmd ::math::sum] [arg value] [opt [arg {value ...}]]]

Return the sum of one or more numeric values.

[list_end]

[vset CATEGORY math]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

118
119
120
121
122
123
124
125
126
[call [cmd ::math::sum] [arg value] [opt [arg {value ...}]]]

Return the sum of one or more numeric values.

[list_end]

[vset CATEGORY math]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/math_geometry.man.

607
608
609
610
611
612
613
614
615
[list_begin enumerated]
[enum] [uri http:/wiki.tcl.tk/12070 {Polygon Intersection}]
[enum] [uri http://en.wikipedia.org/wiki/Line-line_intersection]
[enum] [uri http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/]
[list_end]

[vset CATEGORY {math :: geometry}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

607
608
609
610
611
612
613
614
615
[list_begin enumerated]
[enum] [uri http:/wiki.tcl.tk/12070 {Polygon Intersection}]
[enum] [uri http://en.wikipedia.org/wiki/Line-line_intersection]
[enum] [uri http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/]
[list_end]

[vset CATEGORY {math :: geometry}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/numtheory.dtx.

1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
% \section*{Closings}
% 
% \begin{tcl}
%<*man>
[list_end]

[vset CATEGORY {math :: numtheory}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
%</man>
% \end{tcl}
% 
% \begin{tcl}
%<test_common>testsuiteCleanup
% \end{tcl}






|







1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
% \section*{Closings}
% 
% \begin{tcl}
%<*man>
[list_end]

[vset CATEGORY {math :: numtheory}]
[include ../common-text/feedback.inc]
[manpage_end]
%</man>
% \end{tcl}
% 
% \begin{tcl}
%<test_common>testsuiteCleanup
% \end{tcl}

Changes to modules/math/numtheory.man.

197
198
199
200
201
202
203
204
205
[arg_def integer N in]
Number in question
[list_end]

[list_end]

[vset CATEGORY {math :: numtheory}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

197
198
199
200
201
202
203
204
205
[arg_def integer N in]
Number in question
[list_end]

[list_end]

[vset CATEGORY {math :: numtheory}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/optimize.man.

317
318
319
320
321
322
323
324
325
[para]
The theory of linear programming is the subject of many a text book and
the Simplex algorithm that is implemented here is the best-known
method to solve this type of problems, but it is not the only one.

[vset CATEGORY {math :: optimize}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

317
318
319
320
321
322
323
324
325
[para]
The theory of linear programming is the subject of many a text book and
the Simplex algorithm that is implemented here is the best-known
method to solve this type of problems, but it is not the only one.

[vset CATEGORY {math :: optimize}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/pca.man.

128
129
130
131
132
133
134
135
136
[section EXAMPLE]
TODO: NIST example



[vset CATEGORY PCA]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

128
129
130
131
132
133
134
135
136
[section EXAMPLE]
TODO: NIST example



[vset CATEGORY PCA]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/polynomials.man.

211
212
213
214
215
216
217
218
219
To recognise that a polynomial definition is indeed a correct
definition, it consists of a list of two elements: the keyword
"POLYNOMIAL" and the list of coefficients in descending order. The
latter makes it easier to implement Horner's rule.

[vset CATEGORY {math :: polynomials}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

211
212
213
214
215
216
217
218
219
To recognise that a polynomial definition is indeed a correct
definition, it consists of a list of two elements: the keyword
"POLYNOMIAL" and the list of coefficients in descending order. The
latter makes it easier to implement Horner's rule.

[vset CATEGORY {math :: polynomials}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/qcomplex.man.

294
295
296
297
298
299
300
301
302
The complex power to be used

[list_end]

[list_end]

[vset CATEGORY {math :: complexnumbers}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

294
295
296
297
298
299
300
301
302
The complex power to be used

[list_end]

[list_end]

[vset CATEGORY {math :: complexnumbers}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/rational_funcs.man.

178
179
180
181
182
183
184
185
186
[section "REMARKS ON THE IMPLEMENTATION"]

The implementation of the rational functions relies on the
math::polynomials package. For further remarks see the documentation on
that package.

[vset CATEGORY {math :: rationalfunctions}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

178
179
180
181
182
183
184
185
186
[section "REMARKS ON THE IMPLEMENTATION"]

The implementation of the rational functions relies on the
math::polynomials package. For further remarks see the documentation on
that package.

[vset CATEGORY {math :: rationalfunctions}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/roman.man.

43
44
45
46
47
48
49
50
51
  [list_end]

Of these commands both [emph toroman] and [emph tointeger] are exported
for easier use. The other two are not, as they could interfer or be
confused with existing Tcl commands.

[vset CATEGORY {math :: roman}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

43
44
45
46
47
48
49
50
51
  [list_end]

Of these commands both [emph toroman] and [emph tointeger] are exported
for easier use. The other two are not, as they could interfer or be
confused with existing Tcl commands.

[vset CATEGORY {math :: roman}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/romberg.man.

332
333
334
335
336
337
338
339
340
foreach { value error } [romberg_sine f -1.0 1.0] break
puts [format "integral is %.6g +/- %.6g" $value $error]

integral is 3.97746 +/- 2.3557e-010
}]

[vset CATEGORY {math :: calculus}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

332
333
334
335
336
337
338
339
340
foreach { value error } [romberg_sine f -1.0 1.0] break
puts [format "integral is %.6g +/- %.6g" $value $error]

integral is 3.97746 +/- 2.3557e-010
}]

[vset CATEGORY {math :: calculus}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/special.man.

464
465
466
467
468
469
470
471
472
[para]
Much information about these functions can be found in:
[para]
Abramowitz and Stegun: [emph "Handbook of Mathematical Functions"]
(Dover, ISBN 486-61272-4)

[vset CATEGORY {math :: special}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

464
465
466
467
468
469
470
471
472
[para]
Much information about these functions can be found in:
[para]
Abramowitz and Stegun: [emph "Handbook of Mathematical Functions"]
(Dover, ISBN 486-61272-4)

[vset CATEGORY {math :: special}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/statistics.man.

1631
1632
1633
1634
1635
1636
1637
1638
1639
Both time series show a significant periodic component
[item]
The histograms are not very useful in identifying the nature of the time
series - they do not show the periodic nature.
[list_end]

[vset CATEGORY {math :: statistics}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

1631
1632
1633
1634
1635
1636
1637
1638
1639
Both time series show a significant periodic component
[item]
The histograms are not very useful in identifying the nature of the time
series - they do not show the periodic nature.
[list_end]

[vset CATEGORY {math :: statistics}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/symdiff.man.

64
65
66
67
68
69
70
71
72
==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d)))
math::calculus::symdiff::jacobian {x {$a * $x + $b * $y}
                         y {$c * $x + $d * $y}}
==> {{$a} {$b}} {{$c} {$d}}
}]

[vset CATEGORY {math :: calculus}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

64
65
66
67
68
69
70
71
72
==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d)))
math::calculus::symdiff::jacobian {x {$a * $x + $b * $y}
                         y {$c * $x + $d * $y}}
==> {{$a} {$b}} {{$c} {$d}}
}]

[vset CATEGORY {math :: calculus}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/math/trig.man.

187
188
189
190
191
192
193
194
195
[list_begin arguments]
[arg_def float angle] Angle (in degrees)
[list_end]

[list_end]

[vset CATEGORY {math :: trig}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

187
188
189
190
191
192
193
194
195
[list_begin arguments]
[arg_def float angle] Angle (in degrees)
[list_end]

[list_end]

[vset CATEGORY {math :: trig}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/md4/md4.man.

160
161
162
163
164
165
166
167
168
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY md4]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

160
161
162
163
164
165
166
167
168
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY md4]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/md5/md5.man.

166
167
168
169
170
171
172
173
174
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY md5]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

166
167
168
169
170
171
172
173
174
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY md5]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/md5crypt/md5crypt.man.

77
78
79
80
81
82
83
84
85
[example {
% md5crypt::md5crypt password [md5crypt::salt]
$1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb.
}]

[vset CATEGORY md5crypt]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

77
78
79
80
81
82
83
84
85
[example {
% md5crypt::md5crypt password [md5crypt::salt]
$1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb.
}]

[vset CATEGORY md5crypt]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/mime/mime.man.

398
399
400
401
402
403
404
405
406
[para]

See [uri {/tktview?name=447037} {Ticket 447037}] for additional information.

[list_end]

[vset CATEGORY mime]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

398
399
400
401
402
403
404
405
406
[para]

See [uri {/tktview?name=447037} {Ticket 447037}] for additional information.

[list_end]

[vset CATEGORY mime]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/mime/smtp.man.

199
200
201
202
203
204
205
206
207
208
209
210
    J. Myers, "SMTP Service Extension for Authentication",
    RFC 2554, March 1999.
    ([uri http://www.rfc-editor.org/rfc/rfc2554.txt])

[list_end]

[vset CATEGORY smtp]
[include ../doctools2base/include/feedback.inc]

[keywords mail mail email smtp mime tls \
     {rfc 821} {rfc 822} {rfc 2821} {rfc 3207} {rfc 2554} internet net]
[manpage_end]






|




199
200
201
202
203
204
205
206
207
208
209
210
    J. Myers, "SMTP Service Extension for Authentication",
    RFC 2554, March 1999.
    ([uri http://www.rfc-editor.org/rfc/rfc2554.txt])

[list_end]

[vset CATEGORY smtp]
[include ../common-text/feedback.inc]

[keywords mail mail email smtp mime tls \
     {rfc 821} {rfc 822} {rfc 2821} {rfc 3207} {rfc 2554} internet net]
[manpage_end]

Changes to modules/multiplexer/multiplexer.man.

122
123
124
125
126
127
128
129
130
EOF: The channel connecting us to the client, its ip-address, and its
ip-port.

[list_end]
[list_end]

[vset CATEGORY multiplexer]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

122
123
124
125
126
127
128
129
130
EOF: The channel connecting us to the client, its ip-address, and its
ip-port.

[list_end]
[list_end]

[vset CATEGORY multiplexer]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/namespacex/namespacex.man.

166
167
168
169
170
171
172
173
174
a child namespace of namespace [arg prefix].

Returns the corresponding list of relative names of child namespaces.

[list_end]

[vset CATEGORY namespacex]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

166
167
168
169
170
171
172
173
174
a child namespace of namespace [arg prefix].

Returns the corresponding list of relative names of child namespaces.

[list_end]

[vset CATEGORY namespacex]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ncgi/ncgi.man.

305
306
307
308
309
310
311
312
313
puts -nonewline $fh $filedata
close $fh
}]

[para]

[vset CATEGORY ncgi]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

305
306
307
308
309
310
311
312
313
puts -nonewline $fh $filedata
close $fh
}]

[para]

[vset CATEGORY ncgi]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nettool/nettool.man.

135
136
137
138
139
140
141
142
143
Return a fully qualified path to a folder where [arg appname] should store it's data.
The path is not created, only computed, by this command.

[list_end]
[para]
[vset CATEGORY odie]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

135
136
137
138
139
140
141
142
143
Return a fully qualified path to a folder where [arg appname] should store it's data.
The path is not created, only computed, by this command.

[list_end]
[para]
[vset CATEGORY odie]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nmea/nmea.man.

94
95
96
97
98
99
100
101
102
    puts "unknown data type $name"
}
}]

[list_end]

[vset CATEGORY nmea]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

94
95
96
97
98
99
100
101
102
    puts "unknown data type $name"
}
}]

[list_end]

[vset CATEGORY nmea]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nns/nns_auto.man.

111
112
113
114
115
116
117
118
119
[para]

Another loss of the connection, be it during or after re-entering the
remembered information simply restarts the timer and subsequent
reconnection attempts.

[vset CATEGORY nameserv]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

111
112
113
114
115
116
117
118
119
[para]

Another loss of the connection, be it during or after re-entering the
remembered information simply restarts the timer and subsequent
reconnection attempts.

[vset CATEGORY nameserv]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nns/nns_client.man.

330
331
332
333
334
335
336
337
338
its connection to the name service. Based on package [package uevent].

[def 0.1]
Initial implementation of the client.
[list_end]

[vset CATEGORY nameserv]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

330
331
332
333
334
335
336
337
338
its connection to the name service. Based on package [package uevent].

[def 0.1]
Initial implementation of the client.
[list_end]

[vset CATEGORY nameserv]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nns/nns_common.man.

39
40
41
42
43
44
45
46
47
The result returned by the command is the id of the default TCP/IP
port a nameservice server will listen on, and a name service client
will try to connect to.

[list_end]

[vset CATEGORY nameserv]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

39
40
41
42
43
44
45
46
47
The result returned by the command is the id of the default TCP/IP
port a nameservice server will listen on, and a name service client
will try to connect to.

[list_end]

[vset CATEGORY nameserv]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nns/nns_intro.man.

120
121
122
123
124
125
126
127
128
[para]

Developers wishing to modify and/or extend or to just understand the
internals of the nameservice facility however are strongly advised to
read it.

[vset CATEGORY nameserv]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

120
121
122
123
124
125
126
127
128
[para]

Developers wishing to modify and/or extend or to just understand the
internals of the nameservice facility however are strongly advised to
read it.

[vset CATEGORY nameserv]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nns/nns_protocol.man.

174
175
176
177
178
179
180
181
182
The argument coming before the response tells the client whether the
names in the response were added or removed from the service.

[list_end]

[vset CATEGORY nameserv]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

174
175
176
177
178
179
180
181
182
The argument coming before the response tells the client whether the
names in the response were added or removed from the service.

[list_end]

[vset CATEGORY nameserv]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nns/nns_server.man.

137
138
139
140
141
142
143
144
145
Changed name of -local switch to -localonly.

[def 0.1]
Initial implementation of the server.
[list_end]

[vset CATEGORY nameserv]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

137
138
139
140
141
142
143
144
145
Changed name of -local switch to -localonly.

[def 0.1]
Initial implementation of the server.
[list_end]

[vset CATEGORY nameserv]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/nntp/nntp.man.

330
331
332
333
334
335
336
337
338
    Date: [clock format [clock seconds] -format "%a, %d %
    b %y %H:%M:%S GMT" -gmt true]

    Test message body"
}]

[vset CATEGORY nntp]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

330
331
332
333
334
335
336
337
338
    Date: [clock format [clock seconds] -format "%a, %d %
    b %y %H:%M:%S GMT" -gmt true]

    Test message body"
}]

[vset CATEGORY nntp]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ntp/ntp_time.man.

123
124
125
126
127
128
129
130
131
time::getsntp -command on_time pool.ntp.org
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY ntp]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

123
124
125
126
127
128
129
130
131
time::getsntp -command on_time pool.ntp.org
}]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY ntp]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/oauth/oauth.man.

183
184
185
186
187
188
189
190
191
follow_request_sent => false
notifications => false}]

[list_end]
[para]

[vset CATEGORY oauth]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

183
184
185
186
187
188
189
190
191
follow_request_sent => false
notifications => false}]

[list_end]
[para]

[vset CATEGORY oauth]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/oometa/oometa.man.

143
144
145
146
147
148
149
150
151
152
is faster than [cmd {my meta getnull}] [opt [arg field]] [opt [arg ...]] [arg field]], because
it performs a search instead directly instead of producing the recursive merge product
between the class metadata, the local [emph meta] variable, and THEN performing the search.

[list_end]

[vset CATEGORY tcloo]
[include ../doctools2base/include/feedback.inc]
[manpage_end]







|


143
144
145
146
147
148
149
150
151
152
is faster than [cmd {my meta getnull}] [opt [arg field]] [opt [arg ...]] [arg field]], because
it performs a search instead directly instead of producing the recursive merge product
between the class metadata, the local [emph meta] variable, and THEN performing the search.

[list_end]

[vset CATEGORY tcloo]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ooutil/ooutil.man.

157
158
159
160
161
162
163
164
165
[list_end]

[section AUTHORS]
Donal Fellows, Andreas Kupries

[vset CATEGORY oo::util]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

157
158
159
160
161
162
163
164
165
[list_end]

[section AUTHORS]
Donal Fellows, Andreas Kupries

[vset CATEGORY oo::util]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/otp/otp.man.

87
88
89
90
91
92
93
94
95
        "Secure Hash Standard", National Institute of Standards
        and Technology, U.S. Department Of Commerce, April 1995.
	([uri http://www.itl.nist.gov/fipspubs/fip180-1.htm])

[list_end]

[vset CATEGORY otp]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

87
88
89
90
91
92
93
94
95
        "Secure Hash Standard", National Institute of Standards
        and Technology, U.S. Department Of Commerce, April 1995.
	([uri http://www.itl.nist.gov/fipspubs/fip180-1.htm])

[list_end]

[vset CATEGORY otp]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/page/page_intro.man.

27
28
29
30
31
32
33
34
35
The packages implementing the plugins are not documented as regular
packages, as they cannot be loaded into a general interpreter, like
tclsh, without extensive preparation of the interpreter. Preparation
which is done for them by the plugin manager.

[vset CATEGORY page]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

27
28
29
30
31
32
33
34
35
The packages implementing the plugins are not documented as regular
packages, as they cannot be loaded into a general interpreter, like
tclsh, without extensive preparation of the interpreter. Preparation
which is done for them by the plugin manager.

[vset CATEGORY page]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/page/page_pluginmgr.man.

792
793
794
795
796
797
798
799
800
[section FEATURES]

The plugin manager currently checks the plugins for only one feature,
[const timeable]. A plugin supporting this feature is assumed to be
able to collect timing statistics on request.

[vset CATEGORY page]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

792
793
794
795
796
797
798
799
800
[section FEATURES]

The plugin manager currently checks the plugins for only one feature,
[const timeable]. A plugin supporting this feature is assumed to be
able to collect timing statistics on request.

[vset CATEGORY page]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/page/page_util_flow.man.

88
89
90
91
92
93
94
95
96
This is the variadic arguments form of the method [method visitl], see
above.

[list_end]

[vset CATEGORY page]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

88
89
90
91
92
93
94
95
96
This is the variadic arguments form of the method [method visitl], see
above.

[list_end]

[vset CATEGORY page]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/page/page_util_norm_lemon.man.

43
44
45
46
47
48
49
50
51
[para]

The exact operations performed are left undocumented for the moment.

[list_end]

[vset CATEGORY page]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

43
44
45
46
47
48
49
50
51
[para]

The exact operations performed are left undocumented for the moment.

[list_end]

[vset CATEGORY page]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/page/page_util_norm_peg.man.

97
98
99
100
101
102
103
104
105
The order matters, to shed as much nodes as possible early, and
to avoid unnecessary work later.

[list_end]
[list_end]

[vset CATEGORY page]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

97
98
99
100
101
102
103
104
105
The order matters, to shed as much nodes as possible early, and
to avoid unnecessary work later.

[list_end]
[list_end]

[vset CATEGORY page]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/page/page_util_peg.man.

100
101
102
103
104
105
106
107
108
See the package [package grammar::peg] for the exact syntax of
[arg pe].

[list_end]

[vset CATEGORY page]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

100
101
102
103
104
105
106
107
108
See the package [package grammar::peg] for the exact syntax of
[arg pe].

[list_end]

[vset CATEGORY page]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/page/page_util_quote.man.

54
55
56
57
58
59
60
61
62
converts it into a string which is accepted by the Tcl parser when
used within a Tcl comment. The string is returned as the result of
this command.

[list_end]

[vset CATEGORY page]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

54
55
56
57
58
59
60
61
62
converts it into a string which is accepted by the Tcl parser when
used within a Tcl comment. The string is returned as the result of
this command.

[list_end]

[vset CATEGORY page]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/pki/pki.man.

294
295
296
297
298
299
300
301
302
[enum]
[list_end]

[section AUTHORS]
Roy Keene

[vset CATEGORY rsa]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

294
295
296
297
298
299
300
301
302
[enum]
[list_end]

[section AUTHORS]
Roy Keene

[vset CATEGORY rsa]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/pluginmgr/pluginmgr.man.

419
420
421
422
423
424
425
426
427
Its purpose is give a user of the plugin management the ability to
define commands, packages, etc. a chosen plugin may need while being
loaded.

[list_end]

[vset CATEGORY pluginmgr]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

419
420
421
422
423
424
425
426
427
Its purpose is give a user of the plugin management the ability to
define commands, packages, etc. a chosen plugin may need while being
loaded.

[list_end]

[vset CATEGORY pluginmgr]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/png/png.man.

147
148
149
150
151
152
153
154
155
Takes a list of scanlines in the Tk_GetColor format and writes the represented image
to [arg file].

[list_end]

[vset CATEGORY png]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

147
148
149
150
151
152
153
154
155
Takes a list of scanlines in the Tk_GetColor format and writes the represented image
to [arg file].

[list_end]

[vset CATEGORY png]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/pop3/pop3.man.

266
267
268
269
270
271
272
273
274
	pop3::open -stls 1 \\
		$thehost $theuser $thepassword

	...
}]

[vset CATEGORY pop3]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

266
267
268
269
270
271
272
273
274
	pop3::open -stls 1 \\
		$thehost $theuser $thepassword

	...
}]

[vset CATEGORY pop3]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/pop3d/pop3d.man.

265
266
267
268
269
270
271
272
273
[list_begin enumerated]
[enum] [uri http://www.rfc-editor.org/rfc/rfc1939.txt {RFC 1939}]
[enum] [uri http://www.rfc-editor.org/rfc/rfc2449.txt {RFC 2449}]
[list_end]

[vset CATEGORY pop3d]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

265
266
267
268
269
270
271
272
273
[list_begin enumerated]
[enum] [uri http://www.rfc-editor.org/rfc/rfc1939.txt {RFC 1939}]
[enum] [uri http://www.rfc-editor.org/rfc/rfc2449.txt {RFC 2449}]
[list_end]

[vset CATEGORY pop3d]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/pop3d/pop3d_dbox.man.

156
157
158
159
160
161
162
163
164
call will fail. If [method stat] was not called
before this call, [method get] will assume
that there are zero messages in the mailbox.

[list_end]

[vset CATEGORY pop3d]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

156
157
158
159
160
161
162
163
164
call will fail. If [method stat] was not called
before this call, [method get] will assume
that there are zero messages in the mailbox.

[list_end]

[vset CATEGORY pop3d]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/pop3d/pop3d_udb.man.

104
105
106
107
108
109
110
111
112
remembered internally so that it can be used in the next call of

[arg dbName] [method save] without an argument.

[list_end]

[vset CATEGORY pop3d]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

104
105
106
107
108
109
110
111
112
remembered internally so that it can be used in the next call of

[arg dbName] [method save] without an argument.

[list_end]

[vset CATEGORY pop3d]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/practcl/practcl.man.

55
56
57
58
59
60
61
62
63
[call [cmd practcl::submodule] [arg "parent"] [opt [arg "keyvaluelist"]]]

A Practcl object representing a dynamically generated C/H/Tcl suite, subordinate to a module
[list_end]

[vset CATEGORY practcl]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

55
56
57
58
59
60
61
62
63
[call [cmd practcl::submodule] [arg "parent"] [opt [arg "keyvaluelist"]]]

A Practcl object representing a dynamically generated C/H/Tcl suite, subordinate to a module
[list_end]

[vset CATEGORY practcl]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/processman/processman.man.

66
67
68
69
70
71
72
73
74
Start a child process, identified by [arg id]. [arg cmd] is the name
of the command to execute. [arg args] are arguments to pass to that command.

[list_end]
[para]
[vset CATEGORY odie]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

66
67
68
69
70
71
72
73
74
Start a child process, identified by [arg id]. [arg cmd] is the name
of the command to execute. [arg args] are arguments to pass to that command.

[list_end]
[para]
[vset CATEGORY odie]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/profiler/profiler.man.

113
114
115
116
117
118
119
120
121
[const avgRuntime].  The return result is a list of lists, where each
sublist consists of a function name and the value of [arg key] for
that function.

[list_end]

[vset CATEGORY profiler]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

113
114
115
116
117
118
119
120
121
[const avgRuntime].  The return result is a list of lists, where each
sublist consists of a function name and the value of [arg key] for
that function.

[list_end]

[vset CATEGORY profiler]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/pt/include/feedback.inc.

1
2
3
[comment {--- Standard trailer for all manpages in this module --}]
[vset CATEGORY pt]
[include ../../doctools2base/include/feedback.inc]

|
1
2
3
[comment {--- Standard trailer for all manpages in this module --}]
[vset CATEGORY pt]
[include ../../common-text/feedback.inc]

Changes to modules/rc4/rc4.man.

112
113
114
115
116
117
118
119
120
 rc4::rc4 -in $socket -command [list ::Finish $ApplicationState]
}]

[section "AUTHORS"]
Pat Thoyts

[vset CATEGORY rc4]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

112
113
114
115
116
117
118
119
120
 rc4::rc4 -in $socket -command [list ::Finish $ApplicationState]
}]

[section "AUTHORS"]
Pat Thoyts

[vset CATEGORY rc4]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/rcs/rcs.man.

322
323
324
325
326
327
328
329
330
[example {{{d 1 2} {d 4 1} {a 4 {The named is the mother of all things.

}} {a 11 {They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!}}}}]

[vset CATEGORY rcs]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

322
323
324
325
326
327
328
329
330
[example {{{d 1 2} {d 4 1} {a 4 {The named is the mother of all things.

}} {a 11 {They both may be called deep and profound.
Deeper and more profound,
The door of all subtleties!}}}}]

[vset CATEGORY rcs]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/report/report.man.

468
469
470
471
472
473
474
475
476
    +---+-------------------+-------+-------+--------+
    %
    % # alternate way of doing the above
    % m format 2string r
}]

[vset CATEGORY report]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

468
469
470
471
472
473
474
475
476
    +---+-------------------+-------+-------+--------+
    %
    % # alternate way of doing the above
    % m format 2string r
}]

[vset CATEGORY report]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/rest/rest.man.

545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
    package require tls
    http::register https 443 ::tls::socket
}]

[include ../common-text/tls-security-notes.inc]

[vset CATEGORY rest]
[include ../doctools2base/include/feedback.inc]
[comment {
TOKENS
     the value is substituted into the url at call time.
     tokens in the form of %name:default_value% will be
     an optional argument with a default value.
}]
[manpage_end]






|







545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
    package require tls
    http::register https 443 ::tls::socket
}]

[include ../common-text/tls-security-notes.inc]

[vset CATEGORY rest]
[include ../common-text/feedback.inc]
[comment {
TOKENS
     the value is substituted into the url at call time.
     tokens in the form of %name:default_value% will be
     an optional argument with a default value.
}]
[manpage_end]

Changes to modules/ripemd/ripemd128.man.

183
184
185
186
187
188
189
190
191
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY ripemd]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

183
184
185
186
187
188
189
190
191
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY ripemd]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/ripemd/ripemd160.man.

167
168
169
170
171
172
173
174
175
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY ripemd]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

167
168
169
170
171
172
173
174
175
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY ripemd]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/sasl/gtoken.man.

19
20
21
22
23
24
25
26
27
[include ../common-text/tls-security-notes.inc]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY sasl]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

19
20
21
22
23
24
25
26
27
[include ../common-text/tls-security-notes.inc]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY sasl]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/sasl/ntlm.man.

28
29
30
31
32
33
34
35
36
[list_end]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY sasl]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

28
29
30
31
32
33
34
35
36
[list_end]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY sasl]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/sasl/sasl.man.

332
333
334
335
336
337
338
339
340
[list_end]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY sasl]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

332
333
334
335
336
337
338
339
340
[list_end]

[section AUTHORS]
Pat Thoyts

[vset CATEGORY sasl]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/sasl/scram.man.

28
29
30
31
32
33
34
35
36
[list_end]

[section AUTHORS]
Sergei Golovan

[vset CATEGORY sasl]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

28
29
30
31
32
33
34
35
36
[list_end]

[section AUTHORS]
Sergei Golovan

[vset CATEGORY sasl]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/sha1/sha1.man.

175
176
177
178
179
180
181
182
183
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY sha1]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

175
176
177
178
179
180
181
182
183
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY sha1]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/sha1/sha256.man.

187
188
189
190
191
192
193
194
195
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY sha1]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

187
188
189
190
191
192
193
194
195
      Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for
      Message Authentication", RFC 2104, February 1997.
	([uri http://www.rfc-editor.org/rfc/rfc2104.txt])

[list_end]

[vset CATEGORY sha1]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/smtpd/smtpd.man.

286
287
288
289
290
291
292
293
294
This software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file
[file license.terms] for more details.

[vset CATEGORY smtpd]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

286
287
288
289
290
291
292
293
294
This software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file
[file license.terms] for more details.

[vset CATEGORY smtpd]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/snit/snit.man.

2831
2832
2833
2834
2835
2836
2837
2838
2839
Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, Brian
Griffin, Donal Fellows, Miguel Sofer, Kenneth Green,
and Anton Kovalenko.
If I've forgotten anyone, my apologies; let me know and I'll add
your name to the list.

[vset CATEGORY snit]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

2831
2832
2833
2834
2835
2836
2837
2838
2839
Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, Brian
Griffin, Donal Fellows, Miguel Sofer, Kenneth Green,
and Anton Kovalenko.
If I've forgotten anyone, my apologies; let me know and I'll add
your name to the list.

[vset CATEGORY snit]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/snit/snitfaq.man.

4106
4107
4108
4109
4110
4111
4112
4113
4114
    mylib::propagate -background to {comp1 comp2 comp3}
    mylib::propagate -foreground to {comp1 comp2 comp3}
}
}]

[vset CATEGORY snit]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

4106
4107
4108
4109
4110
4111
4112
4113
4114
    mylib::propagate -background to {comp1 comp2 comp3}
    mylib::propagate -foreground to {comp1 comp2 comp3}
}
}]

[vset CATEGORY snit]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/soundex/soundex.man.

37
38
39
40
41
42
43
44
45
[example {
    % ::soundex::knuth Knuth
    K530
}]

[vset CATEGORY soundex]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

37
38
39
40
41
42
43
44
45
[example {
    % ::soundex::knuth Knuth
    K530
}]

[vset CATEGORY soundex]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/stooop/stooop.man.

215
216
217
218
219
220
221
222
223
[list_end]

[section EXAMPLES]

Please see the full HTML documentation in [uri stooop_man.html].

[vset CATEGORY stooop]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

215
216
217
218
219
220
221
222
223
[list_end]

[section EXAMPLES]

Please see the full HTML documentation in [uri stooop_man.html].

[vset CATEGORY stooop]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/stooop/switched.man.

320
321
322
323
324
325
326
327
328
    ...
}
}]

[list_end]

[vset CATEGORY stooop]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

320
321
322
323
324
325
326
327
328
    ...
}
}]

[list_end]

[vset CATEGORY stooop]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/string/token.man.

89
90
91
92
93
94
95
96
97
[para] Further note that all regex patterns are implicitly prefixed
with the constraint escape [const \A] to ensure that a match starts
exactly at the character index found in [arg startvar].

[list_end]

[vset CATEGORY textutil]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

89
90
91
92
93
94
95
96
97
[para] Further note that all regex patterns are implicitly prefixed
with the constraint escape [const \A] to ensure that a match starts
exactly at the character index found in [arg startvar].

[list_end]

[vset CATEGORY textutil]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/string/token_shell.man.

133
134
135
136
137
138
139
140
141
[para] Whitespace may occur before the first word, or after the last word. Whitespace must occur between adjacent words.

[list_end]
[list_end]

[vset CATEGORY textutil]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

133
134
135
136
137
138
139
140
141
[para] Whitespace may occur before the first word, or after the last word. Whitespace must occur between adjacent words.

[list_end]
[list_end]

[vset CATEGORY textutil]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/stringprep/stringprep.man.

143
144
145
146
147
148
149
150
151
[list_end]

[section "AUTHORS"]
Sergei Golovan

[vset CATEGORY stringprep]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

143
144
145
146
147
148
149
150
151
[list_end]

[section "AUTHORS"]
Sergei Golovan

[vset CATEGORY stringprep]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/stringprep/stringprep_data.man.

13
14
15
16
17
18
19
20
21
The [package stringprep::data] package is a helper for
[package stringprep], providing it with the data tables needed to
perform its functions. It is an [emph internal] package which should
not be accessed on its own. Because of that it has no publicly
documented API either. Its implementation is generated by a script.

[vset CATEGORY stringprep]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

13
14
15
16
17
18
19
20
21
The [package stringprep::data] package is a helper for
[package stringprep], providing it with the data tables needed to
perform its functions. It is an [emph internal] package which should
not be accessed on its own. Because of that it has no publicly
documented API either. Its implementation is generated by a script.

[vset CATEGORY stringprep]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/stringprep/unicode.man.

75
76
77
78
79
80
81
82
83
[list_end]

[section "AUTHORS"]
Sergei Golovan

[vset CATEGORY stringprep]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

75
76
77
78
79
80
81
82
83
[list_end]

[section "AUTHORS"]
Sergei Golovan

[vset CATEGORY stringprep]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/stringprep/unicode_data.man.

13
14
15
16
17
18
19
20
21
The [package unicode::data] package is a helper for
[package unicode], providing it with the data tables needed to
perform its functions. It is an [emph internal] package which should
not be accessed on its own. Because of that it has no publicly
documented API either. Its implementation is generated by a script.

[vset CATEGORY stringprep]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

13
14
15
16
17
18
19
20
21
The [package unicode::data] package is a helper for
[package unicode], providing it with the data tables needed to
perform its functions. It is an [emph internal] package which should
not be accessed on its own. Because of that it has no publicly
documented API either. Its implementation is generated by a script.

[vset CATEGORY stringprep]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/struct/disjointset.man.

228
229
230
231
232
233
234
235
236
[call [arg disjointsetName] [method destroy]]

Destroys the disjoint set object and all associated memory.

[list_end]

[vset CATEGORY {struct :: disjointset}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

228
229
230
231
232
233
234
235
236
[call [arg disjointsetName] [method destroy]]

Destroys the disjoint set object and all associated memory.

[list_end]

[vset CATEGORY {struct :: disjointset}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/struct/graph.man.

956
957
958
959
960
961
962
963
964
Both methods [method arcs] and [method nodes] have been extended with
the ability to select arcs and nodes based on an arbitrary filtering
criterium.

[list_end]

[vset CATEGORY {struct :: graph}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

956
957
958
959
960
961
962
963
964
Both methods [method arcs] and [method nodes] have been extended with
the ability to select arcs and nodes based on an arbitrary filtering
criterium.

[list_end]

[vset CATEGORY {struct :: graph}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/struct/graph1.man.

367
368
369
370
371
372
373
374
375
node appended. For a pre-order walk, all nodes are [const enter]ed, for a
post-order all nodes are left. In a both-order walk the first visit of
a node [const enter]s it, the second visit [const leave]s it.

[list_end]

[vset CATEGORY {struct :: graph}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

367
368
369
370
371
372
373
374
375
node appended. For a pre-order walk, all nodes are [const enter]ed, for a
post-order all nodes are left. In a both-order walk the first visit of
a node [const enter]s it, the second visit [const leave]s it.

[list_end]

[vset CATEGORY {struct :: graph}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/struct/graphops.man.

1311
1312
1313
1314
1315
1316
1317
1318
1319
[enum] [uri http://www.csc.kth.se/~viggo/wwwcompendium/node128.html {K-Center problem}]
[enum] [uri http://en.wikipedia.org/wiki/Breadth-first_search {BFS}]
[enum] [uri http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree {Minimum Degree Spanning Tree}]
[enum] [uri http://en.wikipedia.org/wiki/Approximation_algorithm {Approximation algorithm}]
[list_end]

[vset CATEGORY {struct :: graph}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

1311
1312
1313
1314
1315
1316
1317
1318
1319
[enum] [uri http://www.csc.kth.se/~viggo/wwwcompendium/node128.html {K-Center problem}]
[enum] [uri http://en.wikipedia.org/wiki/Breadth-first_search {BFS}]
[enum] [uri http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree {Minimum Degree Spanning Tree}]
[enum] [uri http://en.wikipedia.org/wiki/Approximation_algorithm {Approximation algorithm}]
[list_end]

[vset CATEGORY {struct :: graph}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/struct/matrix.man.

531
532
533
534
535
536
537
538
539
    +---+-------------------+-------+-------+--------+
    %
    % # alternate way of doing the above
    % r printmatrix m
}]

[vset CATEGORY {struct :: matrix}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|

531
532
533
534
535
536
537
538
539
    +---+-------------------+-------+-------+--------+
    %
    % # alternate way of doing the above
    % r printmatrix m
}]

[vset CATEGORY {struct :: matrix}]
[include ../common-text/feedback.inc]
[manpage_end]

Changes to modules/struct/matrix1.man.

373
374
375
376
377
378
379
380
381
    +---+-------------------+-------+-------+--------+
    %
    % # alternate way of doing the above
    % r printmatrix m
}]

[vset CATEGORY {struct :: matrix}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]






|