Tcl Library Source Code

Check-in [e3ae2af3f4]
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 testsuite fixups Merged latest work from trunk Regenerated documentation. - Fixed outdated references to feedback.inc Use `modules/common-text/feedback.inc` now.
Timelines: family | ancestors | descendants | both | hypnotoad
Files: files | file ages | folders
SHA3-256: e3ae2af3f4799a6561757a03dc4a497e0a01a5058b9d7b39c734f504d00e3d8a
User & Date: aku 2019-06-05 05:02:36
Context
2019-06-05
13:30
Pulling changes from trunk check-in: 147792792a user: hypnotoad tags: hypnotoad
06:31
Integrated last of hypnotoad branch check-in: 8ec2d6ea79 user: aku tags: trunk
05:02
Integrated testsuite fixups Merged latest work from trunk Regenerated documentation. - Fixed outdated references to feedback.inc Use `modules/common-text/feedback.inc` now. check-in: e3ae2af3f4 user: aku tags: hypnotoad
2019-06-04
20:08
Added demonstrations of passing configuration parameters and seeing the data reflected in behavior in httpd Closed-Leaf check-in: 367088a3b3 user: hypnotoad tags: aku-the-big-httpd-testsuite-cleanup
2019-06-03
23:44
Update to clay, practcl, and httpd brought over from the clay project. clay - fixes a typo in the ensemble generator - Removed a call to cron::object_destroy (we don't always run with cron) - Added a tool-like event manager - Removed where the amalgamater was adding dictargs twice - Added a "short" uuid for local projects httpd - updates to clay - Test fixes - Remove CSS templating from the vanilla httpd - Some behind the scenes tweaks to accomodate the cuneiform module when httpd is used in external packages practcl - updates to clay - Static packages are now advertised in the tclpreinitscript, eliminating the need for the master process to throw a bootstrap to new threads check-in: 6ae00eec07 user: hypnotoad tags: hypnotoad
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
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

Changes to embedded/md/index.md.

392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
...
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
...
610
611
612
613
614
615
616

617
618
619
620
621
622
623
...
683
684
685
686
687
688
689

690
691
692
693
694
695
696
...
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
...
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
...
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
|<a name='hex'></a>hex|[base32::hex](tcllib/files/modules/base32/base32hex\.md)|
|<a name='hexadecimal'></a>hexadecimal|[tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md)|
|<a name='histogram'></a>histogram|[counter](tcllib/files/modules/counter/counter\.md)|
|<a name='hook'></a>hook|[hook](tcllib/files/modules/hook/hook\.md) &#183; [uevent](tcllib/files/modules/uev/uevent\.md)|
|<a name='horspool'></a>horspool|[grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md)|
|<a name='html'></a>HTML|[doctools](tcllib/files/modules/doctools/doctools\.md) &#183; [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) &#183; [doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) &#183; [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) &#183; [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) &#183; [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) &#183; [dtplite](tcllib/files/apps/dtplite\.md) &#183; [mpexpand](tcllib/files/modules/doctools/mpexpand\.md)|
|<a name='html'></a>html|[html](tcllib/files/modules/html/html\.md) &#183; [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) &#183; [javascript](tcllib/files/modules/javascript/javascript\.md) &#183; [ncgi](tcllib/files/modules/ncgi/ncgi\.md)|
|<a name='http'></a>http|[autoproxy](tcllib/files/modules/http/autoproxy\.md) &#183; [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) &#183; [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) &#183; [tool](tcllib/files/modules/httpd/httpd\.md) &#183; [uri](tcllib/files/modules/uri/uri\.md) &#183; [websocket](tcllib/files/modules/websocket/websocket\.md)|
|<a name='httpd'></a>httpd|[tool](tcllib/files/modules/httpd/httpd\.md)|
|<a name='https'></a>https|[uri](tcllib/files/modules/uri/uri\.md)|
|<a name='httpserver'></a>httpserver|[tool](tcllib/files/modules/httpd/httpd\.md)|
|<a name='huddle'></a>huddle|[huddle](tcllib/files/modules/yaml/huddle\.md) &#183; [yaml](tcllib/files/modules/yaml/yaml\.md)|
|<a name='human\_readable'></a>human readable|[bench::in](tcllib/files/modules/bench/bench\_read\.md) &#183; [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md)|
|<a name='hyphenation'></a>hyphenation|[textutil](tcllib/files/modules/textutil/textutil\.md) &#183; [textutil::adjust](tcllib/files/modules/textutil/adjust\.md)|


#### <a name='cI'></a>Keywords: I

................................................................................
|<a name='manpage'></a>manpage|[doctools](tcllib/files/modules/doctools/doctools\.md) &#183; [doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) &#183; [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) &#183; [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) &#183; [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) &#183; [dtplite](tcllib/files/apps/dtplite\.md) &#183; [mpexpand](tcllib/files/modules/doctools/mpexpand\.md)|
|<a name='map'></a>map|[generator](tcllib/files/modules/generator/generator\.md) &#183; [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) &#183; [map::slippy](tcllib/files/modules/map/map\_slippy\.md) &#183; [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) &#183; [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) &#183; [mapproj](tcllib/files/modules/mapproj/mapproj\.md) &#183; [struct::list](tcllib/files/modules/struct/struct\_list\.md)|
|<a name='markdown'></a>markdown|[doctools](tcllib/files/modules/doctools/doctools\.md) &#183; [doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md)|
|<a name='markup'></a>markup|[docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) &#183; [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) &#183; [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) &#183; [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) &#183; [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) &#183; [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) &#183; [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) &#183; [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) &#183; [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) &#183; [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) &#183; [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) &#183; [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) &#183; [doctools](tcllib/files/modules/doctools/doctools\.md) &#183; [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) &#183; [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) &#183; [doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) &#183; [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) &#183; [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) &#183; [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) &#183; [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) &#183; [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) &#183; [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) &#183; [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) &#183; [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) &#183; [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) &#183; [dtplite](tcllib/files/apps/dtplite\.md) &#183; [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) &#183; [tcldocstrip](tcllib/files/apps/tcldocstrip\.md)|
|<a name='mastercard'></a>MasterCard|[valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md)|
|<a name='matching'></a>matching|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) &#183; [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) &#183; [pt](tcllib/files/apps/pt\.md) &#183; [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) &#183; [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) &#183; [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) &#183; [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) &#183; [pt::param](tcllib/files/modules/pt/pt\_param\.md) &#183; [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) &#183; [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) &#183; [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) &#183; [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) &#183; [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) &#183; [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) &#183; [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) &#183; [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) &#183; [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) &#183; [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) &#183; [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) &#183; [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) &#183; [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) &#183; [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) &#183; [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) &#183; [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) &#183; [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) &#183; [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) &#183; [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) &#183; [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) &#183; [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) &#183; [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) &#183; [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) &#183; [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) &#183; [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) &#183; [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) &#183; [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) &#183; [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) &#183; [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) &#183; [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) &#183; [pt::util](tcllib/files/modules/pt/pt\_util\.md) &#183; [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) &#183; [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) &#183; [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) &#183; [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) &#183; [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) &#183; [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) &#183; [struct::graph::op](tcllib/files/modules/struct/graphops\.md)|
|<a name='math'></a>math|[math](tcllib/files/modules/math/math\.md) &#183; [math::bigfloat](tcllib/files/modules/math/bigfloat\.md) &#183; [math::bignum](tcllib/files/modules/math/bignum\.md) &#183; [math::calculus](tcllib/files/modules/math/calculus\.md) &#183; [math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) &#183; [math::constants](tcllib/files/modules/math/constants\.md) &#183; [math::decimal](tcllib/files/modules/math/decimal\.md) &#183; [math::fuzzy](tcllib/files/modules/math/fuzzy\.md) &#183; [math::geometry](tcllib/files/modules/math/math\_geometry\.md) &#183; [math::interpolate](tcllib/files/modules/math/interpolate\.md) &#183; [math::linearalgebra](tcllib/files/modules/math/linalg\.md) &#183; [math::optimize](tcllib/files/modules/math/optimize\.md) &#183; [math::PCA](tcllib/files/modules/math/pca\.md) &#183; [math::polynomials](tcllib/files/modules/math/polynomials\.md) &#183; [math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md) &#183; [math::special](tcllib/files/modules/math/special\.md) &#183; [math::trig](tcllib/files/modules/math/trig\.md) &#183; [simulation::annealing](tcllib/files/modules/simulation/annealing\.md) &#183; [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md) &#183; [simulation::random](tcllib/files/modules/simulation/simulation\_random\.md)|
|<a name='mathematics'></a>mathematics|[math::fourier](tcllib/files/modules/math/fourier\.md) &#183; [math::statistics](tcllib/files/modules/math/statistics\.md)|
|<a name='matrices'></a>matrices|[math::linearalgebra](tcllib/files/modules/math/linalg\.md)|
|<a name='matrix'></a>matrix|[csv](tcllib/files/modules/csv/csv\.md) &#183; [math::linearalgebra](tcllib/files/modules/math/linalg\.md) &#183; [report](tcllib/files/modules/report/report\.md) &#183; [struct::matrix](tcllib/files/modules/struct/matrix\.md) &#183; [struct::matrix\_v1](tcllib/files/modules/struct/matrix1\.md) &#183; [struct::queue](tcllib/files/modules/struct/queue\.md) &#183; [struct::stack](tcllib/files/modules/struct/stack\.md)|
|<a name='max\_cut'></a>max cut|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)|
|<a name='maximum'></a>maximum|[math::optimize](tcllib/files/modules/math/optimize\.md)|
|<a name='maximum\_flow'></a>maximum flow|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)|
|<a name='md4'></a>md4|[md4](tcllib/files/modules/md4/md4\.md) &#183; [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) &#183; [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md)|
|<a name='md5'></a>md5|[md5](tcllib/files/modules/md5/md5\.md) &#183; [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md)|
................................................................................
|<a name='oauth'></a>oauth|[oauth](tcllib/files/modules/oauth/oauth\.md)|
|<a name='object'></a>object|[snit](tcllib/files/modules/snit/snit\.md) &#183; [snitfaq](tcllib/files/modules/snit/snitfaq\.md) &#183; [stooop](tcllib/files/modules/stooop/stooop\.md) &#183; [switched](tcllib/files/modules/stooop/switched\.md)|
|<a name='object\_oriented'></a>object oriented|[snit](tcllib/files/modules/snit/snit\.md) &#183; [snitfaq](tcllib/files/modules/snit/snitfaq\.md) &#183; [stooop](tcllib/files/modules/stooop/stooop\.md) &#183; [switched](tcllib/files/modules/stooop/switched\.md)|
|<a name='observer'></a>observer|[hook](tcllib/files/modules/hook/hook\.md) &#183; [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md)|
|<a name='odie'></a>odie|[cron](tcllib/files/modules/cron/cron\.md) &#183; [nettool](tcllib/files/modules/nettool/nettool\.md) &#183; [processman](tcllib/files/modules/processman/processman\.md)|
|<a name='on\_idle'></a>on\-idle|[uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md)|
|<a name='one\_time\_pad'></a>one time pad|[tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md)|

|<a name='optimization'></a>optimization|[math::optimize](tcllib/files/modules/math/optimize\.md) &#183; [simulation::annealing](tcllib/files/modules/simulation/annealing\.md)|
|<a name='ordered\_list'></a>ordered list|[struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md)|
|<a name='otp'></a>otp|[tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md)|
|<a name='outer\_join'></a>outer join|[struct::list](tcllib/files/modules/struct/struct\_list\.md)|


#### <a name='cP'></a>Keywords: P
................................................................................
|<a name='push\_down\_automaton'></a>push down automaton|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) &#183; [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) &#183; [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) &#183; [pt](tcllib/files/apps/pt\.md) &#183; [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) &#183; [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) &#183; [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) &#183; [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) &#183; [pt::param](tcllib/files/modules/pt/pt\_param\.md) &#183; [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) &#183; [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) &#183; [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) &#183; [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) &#183; [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) &#183; [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) &#183; [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) &#183; [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) &#183; [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) &#183; [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) &#183; [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) &#183; [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) &#183; [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) &#183; [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) &#183; [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) &#183; [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) &#183; [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) &#183; [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) &#183; [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) &#183; [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) &#183; [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) &#183; [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) &#183; [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) &#183; [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) &#183; [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) &#183; [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) &#183; [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) &#183; [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) &#183; [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) &#183; [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) &#183; [pt::util](tcllib/files/modules/pt/pt\_util\.md) &#183; [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) &#183; [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) &#183; [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) &#183; [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) &#183; [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) &#183; [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)|


#### <a name='cQ'></a>Keywords: Q

|||
|---|---|

|<a name='queue'></a>queue|[csv](tcllib/files/modules/csv/csv\.md) &#183; [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) &#183; [struct::stack](tcllib/files/modules/struct/stack\.md) &#183; [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md)|
|<a name='quoting'></a>quoting|[page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md)|


#### <a name='cR'></a>Keywords: R

|||
................................................................................
|<a name='seed'></a>seed|[tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md)|
|<a name='selectionbox'></a>selectionbox|[javascript](tcllib/files/modules/javascript/javascript\.md)|
|<a name='semantic\_markup'></a>semantic markup|[docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) &#183; [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) &#183; [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) &#183; [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) &#183; [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) &#183; [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) &#183; [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) &#183; [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) &#183; [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) &#183; [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) &#183; [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) &#183; [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) &#183; [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) &#183; [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) &#183; [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) &#183; [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) &#183; [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) &#183; [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) &#183; [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) &#183; [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md)|
|<a name='send'></a>send|[comm](tcllib/files/modules/comm/comm\.md)|
|<a name='serialization'></a>serialization|[bee](tcllib/files/modules/bee/bee\.md) &#183; [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) &#183; [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) &#183; [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) &#183; [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) &#183; [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) &#183; [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) &#183; [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) &#183; [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) &#183; [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) &#183; [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) &#183; [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) &#183; [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) &#183; [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) &#183; [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) &#183; [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) &#183; [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) &#183; [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) &#183; [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) &#183; [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) &#183; [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) &#183; [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) &#183; [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) &#183; [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) &#183; [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) &#183; [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) &#183; [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) &#183; [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) &#183; [struct::graph](tcllib/files/modules/struct/graph\.md) &#183; [struct::tree](tcllib/files/modules/struct/struct\_tree\.md)|
|<a name='server'></a>server|[map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) &#183; [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) &#183; [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) &#183; [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) &#183; [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) &#183; [nnsd](tcllib/files/apps/nnsd\.md) &#183; [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md)|
|<a name='service'></a>service|[logger](tcllib/files/modules/log/logger\.md)|
|<a name='services'></a>services|[ftpd](tcllib/files/modules/ftpd/ftpd\.md) &#183; [smtpd](tcllib/files/modules/smtpd/smtpd\.md) &#183; [tool](tcllib/files/modules/httpd/httpd\.md)|
|<a name='set'></a>set|[struct::queue](tcllib/files/modules/struct/queue\.md) &#183; [struct::set](tcllib/files/modules/struct/struct\_set\.md)|
|<a name='sha1'></a>sha1|[sha1](tcllib/files/modules/sha1/sha1\.md)|
|<a name='sha256'></a>sha256|[sha256](tcllib/files/modules/sha1/sha256\.md)|
|<a name='shell'></a>shell|[string::token::shell](tcllib/files/modules/string/token\_shell\.md)|
|<a name='shortest\_path'></a>shortest path|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)|
|<a name='shuffle'></a>shuffle|[struct::list](tcllib/files/modules/struct/struct\_list\.md)|
|<a name='simulated\_annealing'></a>simulated annealing|[simulation::annealing](tcllib/files/modules/simulation/annealing\.md)|
................................................................................
|<a name='tape\_archive'></a>tape archive|[tar](tcllib/files/modules/tar/tar\.md)|
|<a name='tar'></a>tar|[tar](tcllib/files/modules/tar/tar\.md)|
|<a name='tcl'></a>tcl|[math::bigfloat](tcllib/files/modules/math/bigfloat\.md) &#183; [math::bignum](tcllib/files/modules/math/bignum\.md) &#183; [math::decimal](tcllib/files/modules/math/decimal\.md) &#183; [math::PCA](tcllib/files/modules/math/pca\.md)|
|<a name='tcl\_module'></a>Tcl module|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md)|
|<a name='tcl\_syntax'></a>Tcl syntax|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md)|
|<a name='tcler\_s\_wiki'></a>tcler's wiki|[doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md)|
|<a name='tcllib'></a>tcllib|[csv](tcllib/files/modules/csv/csv\.md)|
|<a name='tcloo'></a>TclOO|[oo::util](tcllib/files/modules/tool/meta\.md) &#183; [oo::util](tcllib/files/modules/ooutil/ooutil\.md) &#183; [oometa](tcllib/files/modules/oometa/oometa\.md) &#183; [tool](tcllib/files/modules/httpd/httpd\.md) &#183; [tool](tcllib/files/modules/tool/tool\.md) &#183; [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md)|
|<a name='tclparam'></a>TCLPARAM|[pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md)|
|<a name='tdpl'></a>TDPL|[grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) &#183; [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) &#183; [pt](tcllib/files/apps/pt\.md) &#183; [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) &#183; [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) &#183; [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) &#183; [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) &#183; [pt::param](tcllib/files/modules/pt/pt\_param\.md) &#183; [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) &#183; [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) &#183; [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) &#183; [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) &#183; [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) &#183; [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) &#183; [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) &#183; [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) &#183; [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) &#183; [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) &#183; [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) &#183; [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) &#183; [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) &#183; [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) &#183; [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) &#183; [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) &#183; [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) &#183; [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) &#183; [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) &#183; [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) &#183; [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) &#183; [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) &#183; [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) &#183; [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) &#183; [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) &#183; [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) &#183; [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) &#183; [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) &#183; [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) &#183; [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) &#183; [pt::util](tcllib/files/modules/pt/pt\_util\.md) &#183; [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) &#183; [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) &#183; [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) &#183; [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) &#183; [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) &#183; [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)|
|<a name='temp\_file'></a>temp file|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)|
|<a name='template\_processing'></a>template processing|[textutil::expander](tcllib/files/modules/textutil/expander\.md)|
|<a name='terminal'></a>terminal|[term](tcllib/files/modules/term/term\.md) &#183; [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) &#183; [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) &#183; [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) &#183; [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) &#183; [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) &#183; [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) &#183; [term::interact::menu](tcllib/files/modules/term/imenu\.md) &#183; [term::interact::pager](tcllib/files/modules/term/ipager\.md) &#183; [term::receive](tcllib/files/modules/term/receive\.md) &#183; [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) &#183; [term::send](tcllib/files/modules/term/term\_send\.md)|
|<a name='test'></a>test|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)|
|<a name='testing'></a>Testing|[valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) &#183; [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) &#183; [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) &#183; [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) &#183; [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) &#183; [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) &#183; [valtype::iban](tcllib/files/modules/valtype/iban\.md) &#183; [valtype::imei](tcllib/files/modules/valtype/imei\.md) &#183; [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) &#183; [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) &#183; [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) &#183; [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) &#183; [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)|
................................................................................
|||
|---|---|
|<a name='wais'></a>wais|[uri](tcllib/files/modules/uri/uri\.md)|
|<a name='widget'></a>widget|[snit](tcllib/files/modules/snit/snit\.md) &#183; [snitfaq](tcllib/files/modules/snit/snitfaq\.md)|
|<a name='widget\_adaptors'></a>widget adaptors|[snit](tcllib/files/modules/snit/snit\.md) &#183; [snitfaq](tcllib/files/modules/snit/snitfaq\.md)|
|<a name='wiki'></a>wiki|[doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) &#183; [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) &#183; [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md)|
|<a name='word'></a>word|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) &#183; [wip](tcllib/files/modules/wip/wip\.md)|
|<a name='www'></a>WWW|[tool](tcllib/files/modules/httpd/httpd\.md)|
|<a name='www'></a>www|[uri](tcllib/files/modules/uri/uri\.md)|


#### <a name='cX'></a>Keywords: X

|||
|---|---|






|
|

|







 







|







 







>







 







>







 







|







 







|







 







|







392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
...
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
...
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
...
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
...
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
...
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
...
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
|<a name='hex'></a>hex|[base32::hex](tcllib/files/modules/base32/base32hex\.md)|
|<a name='hexadecimal'></a>hexadecimal|[tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md)|
|<a name='histogram'></a>histogram|[counter](tcllib/files/modules/counter/counter\.md)|
|<a name='hook'></a>hook|[hook](tcllib/files/modules/hook/hook\.md) &#183; [uevent](tcllib/files/modules/uev/uevent\.md)|
|<a name='horspool'></a>horspool|[grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md)|
|<a name='html'></a>HTML|[doctools](tcllib/files/modules/doctools/doctools\.md) &#183; [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) &#183; [doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) &#183; [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) &#183; [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) &#183; [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) &#183; [dtplite](tcllib/files/apps/dtplite\.md) &#183; [mpexpand](tcllib/files/modules/doctools/mpexpand\.md)|
|<a name='html'></a>html|[html](tcllib/files/modules/html/html\.md) &#183; [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) &#183; [javascript](tcllib/files/modules/javascript/javascript\.md) &#183; [ncgi](tcllib/files/modules/ncgi/ncgi\.md)|
|<a name='http'></a>http|[autoproxy](tcllib/files/modules/http/autoproxy\.md) &#183; [httpd](tcllib/files/modules/httpd/httpd\.md) &#183; [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) &#183; [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) &#183; [uri](tcllib/files/modules/uri/uri\.md) &#183; [websocket](tcllib/files/modules/websocket/websocket\.md)|
|<a name='httpd'></a>httpd|[httpd](tcllib/files/modules/httpd/httpd\.md)|
|<a name='https'></a>https|[uri](tcllib/files/modules/uri/uri\.md)|
|<a name='httpserver'></a>httpserver|[httpd](tcllib/files/modules/httpd/httpd\.md)|
|<a name='huddle'></a>huddle|[huddle](tcllib/files/modules/yaml/huddle\.md) &#183; [yaml](tcllib/files/modules/yaml/yaml\.md)|
|<a name='human\_readable'></a>human readable|[bench::in](tcllib/files/modules/bench/bench\_read\.md) &#183; [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md)|
|<a name='hyphenation'></a>hyphenation|[textutil](tcllib/files/modules/textutil/textutil\.md) &#183; [textutil::adjust](tcllib/files/modules/textutil/adjust\.md)|


#### <a name='cI'></a>Keywords: I

................................................................................
|<a name='manpage'></a>manpage|[doctools](tcllib/files/modules/doctools/doctools\.md) &#183; [doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) &#183; [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) &#183; [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) &#183; [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) &#183; [dtplite](tcllib/files/apps/dtplite\.md) &#183; [mpexpand](tcllib/files/modules/doctools/mpexpand\.md)|
|<a name='map'></a>map|[generator](tcllib/files/modules/generator/generator\.md) &#183; [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) &#183; [map::slippy](tcllib/files/modules/map/map\_slippy\.md) &#183; [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) &#183; [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) &#183; [mapproj](tcllib/files/modules/mapproj/mapproj\.md) &#183; [struct::list](tcllib/files/modules/struct/struct\_list\.md)|
|<a name='markdown'></a>markdown|[doctools](tcllib/files/modules/doctools/doctools\.md) &#183; [doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md)|
|<a name='markup'></a>markup|[docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) &#183; [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) &#183; [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) &#183; [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) &#183; [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) &#183; [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) &#183; [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) &#183; [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) &#183; [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) &#183; [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) &#183; [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) &#183; [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) &#183; [doctools](tcllib/files/modules/doctools/doctools\.md) &#183; [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) &#183; [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) &#183; [doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) &#183; [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) &#183; [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) &#183; [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) &#183; [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) &#183; [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) &#183; [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) &#183; [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) &#183; [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) &#183; [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) &#183; [dtplite](tcllib/files/apps/dtplite\.md) &#183; [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) &#183; [tcldocstrip](tcllib/files/apps/tcldocstrip\.md)|
|<a name='mastercard'></a>MasterCard|[valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md)|
|<a name='matching'></a>matching|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) &#183; [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) &#183; [pt](tcllib/files/apps/pt\.md) &#183; [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) &#183; [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) &#183; [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) &#183; [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) &#183; [pt::param](tcllib/files/modules/pt/pt\_param\.md) &#183; [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) &#183; [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) &#183; [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) &#183; [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) &#183; [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) &#183; [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) &#183; [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) &#183; [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) &#183; [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) &#183; [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) &#183; [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) &#183; [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) &#183; [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) &#183; [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) &#183; [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) &#183; [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) &#183; [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) &#183; [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) &#183; [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) &#183; [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) &#183; [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) &#183; [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) &#183; [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) &#183; [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) &#183; [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) &#183; [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) &#183; [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) &#183; [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) &#183; [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) &#183; [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) &#183; [pt::util](tcllib/files/modules/pt/pt\_util\.md) &#183; [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) &#183; [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) &#183; [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) &#183; [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) &#183; [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) &#183; [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) &#183; [struct::graph::op](tcllib/files/modules/struct/graphops\.md)|
|<a name='math'></a>math|[math](tcllib/files/modules/math/math\.md) &#183; [math::bigfloat](tcllib/files/modules/math/bigfloat\.md) &#183; [math::bignum](tcllib/files/modules/math/bignum\.md) &#183; [math::calculus](tcllib/files/modules/math/calculus\.md) &#183; [math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) &#183; [math::constants](tcllib/files/modules/math/constants\.md) &#183; [math::decimal](tcllib/files/modules/math/decimal\.md) &#183; [math::fuzzy](tcllib/files/modules/math/fuzzy\.md) &#183; [math::geometry](tcllib/files/modules/math/math\_geometry\.md) &#183; [math::interpolate](tcllib/files/modules/math/interpolate\.md) &#183; [math::linearalgebra](tcllib/files/modules/math/linalg\.md) &#183; [math::optimize](tcllib/files/modules/math/optimize\.md) &#183; [math::PCA](tcllib/files/modules/math/pca\.md) &#183; [math::polynomials](tcllib/files/modules/math/polynomials\.md) &#183; [math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md) &#183; [math::special](tcllib/files/modules/math/special\.md) &#183; [math::trig](tcllib/files/modules/math/trig\.md) &#183; [simulation::annealing](tcllib/files/modules/simulation/annealing\.md) &#183; [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md) &#183; [simulation::random](tcllib/files/modules/simulation/simulation\_random\.md)|
|<a name='mathematics'></a>mathematics|[math::fourier](tcllib/files/modules/math/fourier\.md) &#183; [math::quasirandom](tcllib/files/modules/math/quasirandom\.md) &#183; [math::statistics](tcllib/files/modules/math/statistics\.md)|
|<a name='matrices'></a>matrices|[math::linearalgebra](tcllib/files/modules/math/linalg\.md)|
|<a name='matrix'></a>matrix|[csv](tcllib/files/modules/csv/csv\.md) &#183; [math::linearalgebra](tcllib/files/modules/math/linalg\.md) &#183; [report](tcllib/files/modules/report/report\.md) &#183; [struct::matrix](tcllib/files/modules/struct/matrix\.md) &#183; [struct::matrix\_v1](tcllib/files/modules/struct/matrix1\.md) &#183; [struct::queue](tcllib/files/modules/struct/queue\.md) &#183; [struct::stack](tcllib/files/modules/struct/stack\.md)|
|<a name='max\_cut'></a>max cut|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)|
|<a name='maximum'></a>maximum|[math::optimize](tcllib/files/modules/math/optimize\.md)|
|<a name='maximum\_flow'></a>maximum flow|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)|
|<a name='md4'></a>md4|[md4](tcllib/files/modules/md4/md4\.md) &#183; [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) &#183; [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md)|
|<a name='md5'></a>md5|[md5](tcllib/files/modules/md5/md5\.md) &#183; [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md)|
................................................................................
|<a name='oauth'></a>oauth|[oauth](tcllib/files/modules/oauth/oauth\.md)|
|<a name='object'></a>object|[snit](tcllib/files/modules/snit/snit\.md) &#183; [snitfaq](tcllib/files/modules/snit/snitfaq\.md) &#183; [stooop](tcllib/files/modules/stooop/stooop\.md) &#183; [switched](tcllib/files/modules/stooop/switched\.md)|
|<a name='object\_oriented'></a>object oriented|[snit](tcllib/files/modules/snit/snit\.md) &#183; [snitfaq](tcllib/files/modules/snit/snitfaq\.md) &#183; [stooop](tcllib/files/modules/stooop/stooop\.md) &#183; [switched](tcllib/files/modules/stooop/switched\.md)|
|<a name='observer'></a>observer|[hook](tcllib/files/modules/hook/hook\.md) &#183; [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md)|
|<a name='odie'></a>odie|[cron](tcllib/files/modules/cron/cron\.md) &#183; [nettool](tcllib/files/modules/nettool/nettool\.md) &#183; [processman](tcllib/files/modules/processman/processman\.md)|
|<a name='on\_idle'></a>on\-idle|[uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md)|
|<a name='one\_time\_pad'></a>one time pad|[tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md)|
|<a name='oo'></a>oo|[clay](tcllib/files/modules/clay/clay\.md)|
|<a name='optimization'></a>optimization|[math::optimize](tcllib/files/modules/math/optimize\.md) &#183; [simulation::annealing](tcllib/files/modules/simulation/annealing\.md)|
|<a name='ordered\_list'></a>ordered list|[struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md)|
|<a name='otp'></a>otp|[tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md)|
|<a name='outer\_join'></a>outer join|[struct::list](tcllib/files/modules/struct/struct\_list\.md)|


#### <a name='cP'></a>Keywords: P
................................................................................
|<a name='push\_down\_automaton'></a>push down automaton|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) &#183; [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) &#183; [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) &#183; [pt](tcllib/files/apps/pt\.md) &#183; [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) &#183; [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) &#183; [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) &#183; [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) &#183; [pt::param](tcllib/files/modules/pt/pt\_param\.md) &#183; [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) &#183; [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) &#183; [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) &#183; [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) &#183; [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) &#183; [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) &#183; [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) &#183; [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) &#183; [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) &#183; [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) &#183; [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) &#183; [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) &#183; [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) &#183; [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) &#183; [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) &#183; [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) &#183; [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) &#183; [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) &#183; [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) &#183; [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) &#183; [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) &#183; [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) &#183; [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) &#183; [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) &#183; [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) &#183; [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) &#183; [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) &#183; [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) &#183; [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) &#183; [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) &#183; [pt::util](tcllib/files/modules/pt/pt\_util\.md) &#183; [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) &#183; [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) &#183; [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) &#183; [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) &#183; [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) &#183; [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)|


#### <a name='cQ'></a>Keywords: Q

|||
|---|---|
|<a name='quasi\_random'></a>quasi\-random|[math::quasirandom](tcllib/files/modules/math/quasirandom\.md)|
|<a name='queue'></a>queue|[csv](tcllib/files/modules/csv/csv\.md) &#183; [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) &#183; [struct::stack](tcllib/files/modules/struct/stack\.md) &#183; [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md)|
|<a name='quoting'></a>quoting|[page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md)|


#### <a name='cR'></a>Keywords: R

|||
................................................................................
|<a name='seed'></a>seed|[tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md)|
|<a name='selectionbox'></a>selectionbox|[javascript](tcllib/files/modules/javascript/javascript\.md)|
|<a name='semantic\_markup'></a>semantic markup|[docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) &#183; [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) &#183; [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) &#183; [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) &#183; [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) &#183; [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) &#183; [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) &#183; [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) &#183; [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) &#183; [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) &#183; [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) &#183; [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) &#183; [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) &#183; [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) &#183; [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) &#183; [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) &#183; [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) &#183; [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) &#183; [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) &#183; [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md)|
|<a name='send'></a>send|[comm](tcllib/files/modules/comm/comm\.md)|
|<a name='serialization'></a>serialization|[bee](tcllib/files/modules/bee/bee\.md) &#183; [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) &#183; [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) &#183; [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) &#183; [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) &#183; [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) &#183; [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) &#183; [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) &#183; [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) &#183; [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) &#183; [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) &#183; [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) &#183; [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) &#183; [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) &#183; [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) &#183; [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) &#183; [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) &#183; [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) &#183; [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) &#183; [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) &#183; [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) &#183; [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) &#183; [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) &#183; [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) &#183; [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) &#183; [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) &#183; [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) &#183; [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) &#183; [struct::graph](tcllib/files/modules/struct/graph\.md) &#183; [struct::tree](tcllib/files/modules/struct/struct\_tree\.md)|
|<a name='server'></a>server|[map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) &#183; [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) &#183; [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) &#183; [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) &#183; [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) &#183; [nnsd](tcllib/files/apps/nnsd\.md) &#183; [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md)|
|<a name='service'></a>service|[logger](tcllib/files/modules/log/logger\.md)|
|<a name='services'></a>services|[ftpd](tcllib/files/modules/ftpd/ftpd\.md) &#183; [httpd](tcllib/files/modules/httpd/httpd\.md) &#183; [smtpd](tcllib/files/modules/smtpd/smtpd\.md)|
|<a name='set'></a>set|[struct::queue](tcllib/files/modules/struct/queue\.md) &#183; [struct::set](tcllib/files/modules/struct/struct\_set\.md)|
|<a name='sha1'></a>sha1|[sha1](tcllib/files/modules/sha1/sha1\.md)|
|<a name='sha256'></a>sha256|[sha256](tcllib/files/modules/sha1/sha256\.md)|
|<a name='shell'></a>shell|[string::token::shell](tcllib/files/modules/string/token\_shell\.md)|
|<a name='shortest\_path'></a>shortest path|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)|
|<a name='shuffle'></a>shuffle|[struct::list](tcllib/files/modules/struct/struct\_list\.md)|
|<a name='simulated\_annealing'></a>simulated annealing|[simulation::annealing](tcllib/files/modules/simulation/annealing\.md)|
................................................................................
|<a name='tape\_archive'></a>tape archive|[tar](tcllib/files/modules/tar/tar\.md)|
|<a name='tar'></a>tar|[tar](tcllib/files/modules/tar/tar\.md)|
|<a name='tcl'></a>tcl|[math::bigfloat](tcllib/files/modules/math/bigfloat\.md) &#183; [math::bignum](tcllib/files/modules/math/bignum\.md) &#183; [math::decimal](tcllib/files/modules/math/decimal\.md) &#183; [math::PCA](tcllib/files/modules/math/pca\.md)|
|<a name='tcl\_module'></a>Tcl module|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md)|
|<a name='tcl\_syntax'></a>Tcl syntax|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md)|
|<a name='tcler\_s\_wiki'></a>tcler's wiki|[doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md)|
|<a name='tcllib'></a>tcllib|[csv](tcllib/files/modules/csv/csv\.md)|
|<a name='tcloo'></a>TclOO|[clay](tcllib/files/modules/clay/clay\.md) &#183; [httpd](tcllib/files/modules/httpd/httpd\.md) &#183; [oo::util](tcllib/files/modules/tool/meta\.md) &#183; [oo::util](tcllib/files/modules/ooutil/ooutil\.md) &#183; [oometa](tcllib/files/modules/oometa/oometa\.md) &#183; [tool](tcllib/files/modules/tool/tool\.md) &#183; [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md)|
|<a name='tclparam'></a>TCLPARAM|[pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md)|
|<a name='tdpl'></a>TDPL|[grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) &#183; [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) &#183; [pt](tcllib/files/apps/pt\.md) &#183; [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) &#183; [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) &#183; [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) &#183; [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) &#183; [pt::param](tcllib/files/modules/pt/pt\_param\.md) &#183; [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) &#183; [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) &#183; [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) &#183; [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) &#183; [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) &#183; [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) &#183; [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) &#183; [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) &#183; [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) &#183; [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) &#183; [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) &#183; [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) &#183; [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) &#183; [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) &#183; [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) &#183; [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) &#183; [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) &#183; [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) &#183; [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) &#183; [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) &#183; [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) &#183; [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) &#183; [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) &#183; [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) &#183; [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) &#183; [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) &#183; [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) &#183; [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) &#183; [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) &#183; [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) &#183; [pt::util](tcllib/files/modules/pt/pt\_util\.md) &#183; [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) &#183; [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) &#183; [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) &#183; [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) &#183; [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) &#183; [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)|
|<a name='temp\_file'></a>temp file|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)|
|<a name='template\_processing'></a>template processing|[textutil::expander](tcllib/files/modules/textutil/expander\.md)|
|<a name='terminal'></a>terminal|[term](tcllib/files/modules/term/term\.md) &#183; [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) &#183; [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) &#183; [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) &#183; [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) &#183; [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) &#183; [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) &#183; [term::interact::menu](tcllib/files/modules/term/imenu\.md) &#183; [term::interact::pager](tcllib/files/modules/term/ipager\.md) &#183; [term::receive](tcllib/files/modules/term/receive\.md) &#183; [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) &#183; [term::send](tcllib/files/modules/term/term\_send\.md)|
|<a name='test'></a>test|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)|
|<a name='testing'></a>Testing|[valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) &#183; [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) &#183; [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) &#183; [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) &#183; [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) &#183; [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) &#183; [valtype::iban](tcllib/files/modules/valtype/iban\.md) &#183; [valtype::imei](tcllib/files/modules/valtype/imei\.md) &#183; [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) &#183; [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) &#183; [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) &#183; [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) &#183; [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)|
................................................................................
|||
|---|---|
|<a name='wais'></a>wais|[uri](tcllib/files/modules/uri/uri\.md)|
|<a name='widget'></a>widget|[snit](tcllib/files/modules/snit/snit\.md) &#183; [snitfaq](tcllib/files/modules/snit/snitfaq\.md)|
|<a name='widget\_adaptors'></a>widget adaptors|[snit](tcllib/files/modules/snit/snit\.md) &#183; [snitfaq](tcllib/files/modules/snit/snitfaq\.md)|
|<a name='wiki'></a>wiki|[doctools::idx](tcllib/files/modules/doctools/docidx\.md) &#183; [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) &#183; [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) &#183; [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) &#183; [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) &#183; [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) &#183; [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) &#183; [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md)|
|<a name='word'></a>word|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) &#183; [wip](tcllib/files/modules/wip/wip\.md)|
|<a name='www'></a>WWW|[httpd](tcllib/files/modules/httpd/httpd\.md)|
|<a name='www'></a>www|[uri](tcllib/files/modules/uri/uri\.md)|


#### <a name='cX'></a>Keywords: X

|||
|---|---|

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/aes/aes.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (aes \- Advanced Encryption Standard \(AES\))
[//000000002]: # (Generated from file 'aes\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2005, Pat Thoyts <[email protected]\.sourceforge\.net>  
Copyright &copy; 2012\-2014, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (aes\(n\) 1\.2\.1 tcllib "Advanced Encryption Standard \(AES\)")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (aes \- Advanced Encryption Standard \(AES\))
[//000000002]: # (Generated from file 'aes\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2005, Pat Thoyts <[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2012\-2014, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (aes\(n\) 1\.2\.1 tcllib "Advanced Encryption Standard \(AES\)")

<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>

Changes to embedded/md/tcllib/files/modules/asn/asn.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (asn \- ASN\.1 processing)
[//000000002]: # (Generated from file 'asn\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2004 Jochen Loewer <[email protected]\.de>  
Copyright &copy; 2004\-2011 Michael Schlenker <[email protected]\.sourceforge\.net>)
[//000000004]: # (asn\(n\) 0\.8 tcllib "ASN\.1 processing")

<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>


|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (asn \- ASN\.1 processing)
[//000000002]: # (Generated from file 'asn\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2004 Jochen Loewer <[email protected]\.de>)
[//000000005]: # (Copyright &copy; 2004\-2011 Michael Schlenker <[email protected]\.sourceforge\.net>)
[//000000006]: # (asn\(n\) 0\.8 tcllib "ASN\.1 processing")

<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>

Changes to embedded/md/tcllib/files/modules/base64/base64.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (base64 \- Text encoding & decoding binary data)
[//000000002]: # (Generated from file 'base64\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2000, Eric Melski  
Copyright &copy; 2001, Miguel Sofer)
[//000000004]: # (base64\(n\) 2\.4\.2 tcllib "Text encoding & decoding binary data")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (base64 \- Text encoding & decoding binary data)
[//000000002]: # (Generated from file 'base64\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2000, Eric Melski)
[//000000004]: # (Copyright &copy; 2001, Miguel Sofer)
[//000000005]: # (base64\(n\) 2\.4\.2 tcllib "Text encoding & decoding binary data")

<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>

Changes to embedded/md/tcllib/files/modules/bench/bench_lang_intro.md.

76
77
78
79
80
81
82
83
84
85
86
87
88
89

90
91
92
93
94
95
96
...
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

142
143
144
145
146
147
148
__\-post__\-body, respectively\.

In our example, directly drawn from the benchmark suite of Tcllib's
__[aes](\.\./aes/aes\.md)__ package, the concrete initialization code
constructs the key schedule used by the encryption command whose speed we
measure, and the cleanup code releases any resources bound to that schedule\.

    bench -desc "AES-${len} ECB encryption core" __-pre__ {
        set key [aes::Init ecb $k $i]
    } -body {
        aes::Encrypt $key $p
    } __-post__ {
        aes::Final $key
    }


## <a name='subsection4'></a>Advanced pre\- and postprocessing

Our last example again deals with initialization and cleanup code\. To see the
difference to the regular initialization and cleanup discussed in the last
section it is necessary to know a bit more about how bench actually measures the
speed of the the __\-body__\.
................................................................................
example we used above to demonstrate the necessity for the advanced
initialization and cleanup\. Its concrete initialization code constructs a
variable refering to a set with specific properties \(The set has a string
representation, which is shared\) affecting the speed of the inclusion command,
and the cleanup code releases the temporary variables created by this
initialization\.

    bench -desc "set include, missing <SC> x$times $n" __-ipre__ {
        set A $sx($times,$n)
        set B $A
    } -body {
        struct::set include A x
    } __-ipost__ {
        unset A B
    }


# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of benchmarks, he should be fortified enough to be able to understand the formal
*bench language specfication*\. It will also serve as the detailed
specification and cheat sheet for all available commands and their syntax\.






|
|
|
|
|
|
<
>







 







|
|
|
|
|
|
|
<
>







76
77
78
79
80
81
82
83
84
85
86
87
88

89
90
91
92
93
94
95
96
...
127
128
129
130
131
132
133
134
135
136
137
138
139
140

141
142
143
144
145
146
147
148
__\-post__\-body, respectively\.

In our example, directly drawn from the benchmark suite of Tcllib's
__[aes](\.\./aes/aes\.md)__ package, the concrete initialization code
constructs the key schedule used by the encryption command whose speed we
measure, and the cleanup code releases any resources bound to that schedule\.

> bench \-desc "AES\-$\{len\} ECB encryption core" __\-pre__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;set key \[aes::Init ecb $k $i\]  
> \} \-body \{  
> &nbsp;&nbsp;&nbsp;&nbsp;aes::Encrypt $key $p  
> \} __\-post__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;aes::Final $key  

> \}

## <a name='subsection4'></a>Advanced pre\- and postprocessing

Our last example again deals with initialization and cleanup code\. To see the
difference to the regular initialization and cleanup discussed in the last
section it is necessary to know a bit more about how bench actually measures the
speed of the the __\-body__\.
................................................................................
example we used above to demonstrate the necessity for the advanced
initialization and cleanup\. Its concrete initialization code constructs a
variable refering to a set with specific properties \(The set has a string
representation, which is shared\) affecting the speed of the inclusion command,
and the cleanup code releases the temporary variables created by this
initialization\.

> bench \-desc "set include, missing <SC> x$times $n" __\-ipre__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;set A $sx\($times,$n\)  
> &nbsp;&nbsp;&nbsp;&nbsp;set B $A  
> \} \-body \{  
> &nbsp;&nbsp;&nbsp;&nbsp;struct::set include A x  
> \} __\-ipost__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;unset A B  

> \}

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of benchmarks, he should be fortified enough to be able to understand the formal
*bench language specfication*\. It will also serve as the detailed
specification and cheat sheet for all available commands and their syntax\.

Changes to embedded/md/tcllib/files/modules/comm/comm.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (comm \- Remote communication)
[//000000002]: # (Generated from file 'comm\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 1995\-1998 The Open Group\. All Rights Reserved\.  
Copyright &copy; 2003\-2004 ActiveState Corporation\.  
Copyright &copy; 2006\-2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (comm\(n\) 4\.6\.3 tcllib "Remote communication")

<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>


|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (comm \- Remote communication)
[//000000002]: # (Generated from file 'comm\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 1995\-1998 The Open Group\. All Rights Reserved\.)
[//000000004]: # (Copyright &copy; 2003\-2004 ActiveState Corporation\.)
[//000000005]: # (Copyright &copy; 2006\-2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000006]: # (comm\(n\) 4\.6\.3 tcllib "Remote communication")

<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>

Changes to embedded/md/tcllib/files/modules/debug/debug.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (debug \- debug narrative)
[//000000002]: # (Generated from file 'debug\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 200?, Colin McCormack, Wub Server Utilities  
Copyright &copy; 2012\-2014, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (debug\(n\) 1\.0\.6 tcllib "debug narrative")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (debug \- debug narrative)
[//000000002]: # (Generated from file 'debug\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 200?, Colin McCormack, Wub Server Utilities)
[//000000004]: # (Copyright &copy; 2012\-2014, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (debug\(n\) 1\.0\.6 tcllib "debug narrative")

<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>

Changes to embedded/md/tcllib/files/modules/debug/debug_heartbeat.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (debug::heartbeat \- debug narrative)
[//000000002]: # (Generated from file 'debug\_heartbeat\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 200?, Colin McCormack, Wub Server Utilities  
Copyright &copy; 2012, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (debug::heartbeat\(n\) 1 tcllib "debug narrative")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (debug::heartbeat \- debug narrative)
[//000000002]: # (Generated from file 'debug\_heartbeat\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 200?, Colin McCormack, Wub Server Utilities)
[//000000004]: # (Copyright &copy; 2012, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (debug::heartbeat\(n\) 1 tcllib "debug narrative")

<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>

Changes to embedded/md/tcllib/files/modules/debug/debug_timestamp.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (debug::timestamp \- debug narrative)
[//000000002]: # (Generated from file 'debug\_timestamp\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 200?, Colin McCormack, Wub Server Utilities  
Copyright &copy; 2012, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (debug::timestamp\(n\) 1 tcllib "debug narrative")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (debug::timestamp \- debug narrative)
[//000000002]: # (Generated from file 'debug\_timestamp\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 200?, Colin McCormack, Wub Server Utilities)
[//000000004]: # (Copyright &copy; 2012, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (debug::timestamp\(n\) 1 tcllib "debug narrative")

<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>

Changes to embedded/md/tcllib/files/modules/dicttool/dicttool.md.

30
31
32
33
34
35
36

37
38
39
40
41
42
43
..
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  


[__ladd__ *varname* *args*](#1)  
[__ldelete__ *varname* *args*](#2)  
[__dict getnull__ *args*](#3)  
[__dict print__ *dict*](#4)  
[__dict is\_dict__ *value*](#5)  
[__rmerge__ *args*](#6)  
................................................................................
  - <a name='1'></a>__ladd__ *varname* *args*

    This command will add a new instance of each element in *args* to
    *varname*, but only if that element is not already present\.

  - <a name='2'></a>__ldelete__ *varname* *args*

    This command will add a delete all instances of each element in *args*
    from *varname*\.

  - <a name='3'></a>__dict getnull__ *args*

    Operates like __dict get__, however if the key *args* does not exist,
    it returns an empty list instead of throwing an error\.

  - <a name='4'></a>__dict print__ *dict*






>







 







|
|







30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
..
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require dicttool ?1\.0?  

[__ladd__ *varname* *args*](#1)  
[__ldelete__ *varname* *args*](#2)  
[__dict getnull__ *args*](#3)  
[__dict print__ *dict*](#4)  
[__dict is\_dict__ *value*](#5)  
[__rmerge__ *args*](#6)  
................................................................................
  - <a name='1'></a>__ladd__ *varname* *args*

    This command will add a new instance of each element in *args* to
    *varname*, but only if that element is not already present\.

  - <a name='2'></a>__ldelete__ *varname* *args*

    This command will delete all instances of each element in *args* from
    *varname*\.

  - <a name='3'></a>__dict getnull__ *args*

    Operates like __dict get__, however if the key *args* does not exist,
    it returns an empty list instead of throwing an error\.

  - <a name='4'></a>__dict print__ *dict*

Changes to embedded/md/tcllib/files/modules/dns/tcllib_ip.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (tcllib\_ip \- Domain Name Service)
[//000000002]: # (Generated from file 'tcllib\_ip\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004, Pat Thoyts  
Copyright &copy; 2005 Aamer Akhter <[email protected]\.com>)
[//000000004]: # (tcllib\_ip\(n\) 1\.4 tcllib "Domain Name Service")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (tcllib\_ip \- Domain Name Service)
[//000000002]: # (Generated from file 'tcllib\_ip\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004, Pat Thoyts)
[//000000004]: # (Copyright &copy; 2005 Aamer Akhter <[email protected]\.com>)
[//000000005]: # (tcllib\_ip\(n\) 1\.4 tcllib "Domain Name Service")

<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>

Changes to embedded/md/tcllib/files/modules/docstrip/docstrip.md.

391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
that files employing that document format are given the suffix "\.ddt", to
distinguish them from the more traditional LaTeX\-based "\.dtx" files\.

Master source files with "\.dtx" extension are usually set up so that they can be
typeset directly by __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ without any
support from other files\. This is achieved by beginning the file with the lines

    % \iffalse
    %<*driver>
    \documentclass{tclldoc}
    \begin{document}
    \DocInput{*filename.dtx*}
    \end{document}
    %</driver>
    % \fi

or some variation thereof\. The trick is that the file gets read twice\. With
normal LaTeX reading rules, the first two lines are comments and therefore
ignored\. The third line is the document preamble, the fourth line begins the
document body, and the sixth line ends the document, so LaTeX stops there —
non\-comments below that point in the file are never subjected to the normal
LaTeX reading rules\. Before that, however, the \\DocInput command on the fifth






|
|
|
|
|
|
|
|







391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
that files employing that document format are given the suffix "\.ddt", to
distinguish them from the more traditional LaTeX\-based "\.dtx" files\.

Master source files with "\.dtx" extension are usually set up so that they can be
typeset directly by __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ without any
support from other files\. This is achieved by beginning the file with the lines

> &nbsp;&nbsp;&nbsp;% \\iffalse  
> &nbsp;&nbsp;&nbsp;%<\*driver>  
> &nbsp;&nbsp;&nbsp;\\documentclass\{tclldoc\}  
> &nbsp;&nbsp;&nbsp;\\begin\{document\}  
> &nbsp;&nbsp;&nbsp;\\DocInput\{*filename\.dtx*\}  
> &nbsp;&nbsp;&nbsp;\\end\{document\}  
> &nbsp;&nbsp;&nbsp;%</driver>  
> &nbsp;&nbsp;&nbsp;% \\fi

or some variation thereof\. The trick is that the file gets read twice\. With
normal LaTeX reading rules, the first two lines are comments and therefore
ignored\. The third line is the document preamble, the fourth line begins the
document body, and the sixth line ends the document, so LaTeX stops there —
non\-comments below that point in the file are never subjected to the normal
LaTeX reading rules\. Before that, however, the \\DocInput command on the fifth

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

59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
..
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
...
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
...
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [key {markup language}] ...

    ... [manpage thefile \\
            {file description}] ...

## <a name='subsection2'></a>Basic structure

The most simple document which can be written in docidx is

    [index_begin GROUPTITLE TITLE]
................................................................................

Not very useful, but valid\. This also shows us that all docidx documents consist
of only one part where we will list all keys and their references\.

A more useful index will contain at least keywords, or short 'keys', i\.e\. the
phrases which were indexed\. So:

    [index_begin GROUPTITLE TITLE]
    [__key markup__]
    [__key {semantic markup}]__]
    [__key {docidx markup}__]
    [__key {docidx language}__]
    [__key {docidx commands}__]
    [index_end]

In the above example the command __key__ is used to declare the keyword
phrases we wish to be part of the index\.

However a truly useful index does not only list the keyword phrases, but will
also contain references to documents associated with the keywords\. Here is a
made\-up index for all the manpages in the module
*[base64](\.\./\.\./\.\./\.\./index\.md\#base64)*:

    [index_begin tcllib/base64 {De- & Encoding}]
    [key base64]
    [__manpage base64__]
    [key encoding]
    [__manpage base64__]
    [__manpage uuencode__]
    [__manpage yencode__]
    [key uuencode]
    [__manpage uuencode__]
    [key yEnc]
    [__manpage yencode__]
    [key ydecode]
    [__manpage yencode__]
    [key yencode]
    [__manpage yencode__]
    [index_end]

In the above example the command
__[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ is used to insert references
to documents, using symbolic file names, with each command belonging to the last
__key__ command coming before it\.

The other command to insert references is
................................................................................
to be used before the __index\_begin__ command opening the document\.

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

    [__include FILE__]
    [__vset VAR VALUE__]
    [index_begin GROUPTITLE TITLE]
    ...
    [index_end]

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\.

    [index_begin GROUPTITLE TITLE]
    [__include FILE__]
    [__vset VAR VALUE__]
    ...
    [index_end]

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __index\_begin__ may contain only the templating commands __vset__
and __include__, a file included after a key may contain only manape or url
references, and other keys, etc\.

................................................................................
characters, namely __\[__ and __\]__\. These commands, __lb__ and
__rb__ respectively, are required because our use of \[ and \] to bracket
markup commands makes it impossible to directly use \[ and \] within the text\.

Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

    ...
    These commands, [cmd lb] and [cmd lb] respectively, are required
    because our use of [__lb__] and [__rb__] to bracket markup commands makes it
    impossible to directly use [__lb__] and [__rb__] within the text.
    ...

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[docidx language syntax](docidx\_lang\_syntax\.md)* specification as well\.
From here on out the *[docidx language command






|







 







|
|
|
|
|
|
|









|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|







 







|
|
|
|
|




|
|
|
|
|







 







|
|
|
|
|







59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
..
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
...
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
...
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [key {markup language}] ...

    ... [manpage thefile \
            {file description}] ...

## <a name='subsection2'></a>Basic structure

The most simple document which can be written in docidx is

    [index_begin GROUPTITLE TITLE]
................................................................................

Not very useful, but valid\. This also shows us that all docidx documents consist
of only one part where we will list all keys and their references\.

A more useful index will contain at least keywords, or short 'keys', i\.e\. the
phrases which were indexed\. So:

> \[index\_begin GROUPTITLE TITLE\]  
> \[__key markup__\]  
> \[__key \{semantic markup\}\]__\]  
> \[__key \{docidx markup\}__\]  
> \[__key \{docidx language\}__\]  
> \[__key \{docidx commands\}__\]  
> \[index\_end\]

In the above example the command __key__ is used to declare the keyword
phrases we wish to be part of the index\.

However a truly useful index does not only list the keyword phrases, but will
also contain references to documents associated with the keywords\. Here is a
made\-up index for all the manpages in the module
*[base64](\.\./\.\./\.\./\.\./index\.md\#base64)*:

> \[index\_begin tcllib/base64 \{De\- & Encoding\}\]  
> \[key base64\]  
> \[__manpage base64__\]  
> \[key encoding\]  
> \[__manpage base64__\]  
> \[__manpage uuencode__\]  
> \[__manpage yencode__\]  
> \[key uuencode\]  
> \[__manpage uuencode__\]  
> \[key yEnc\]  
> \[__manpage yencode__\]  
> \[key ydecode\]  
> \[__manpage yencode__\]  
> \[key yencode\]  
> \[__manpage yencode__\]  
> \[index\_end\]

In the above example the command
__[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ is used to insert references
to documents, using symbolic file names, with each command belonging to the last
__key__ command coming before it\.

The other command to insert references is
................................................................................
to be used before the __index\_begin__ command opening the document\.

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[index\_begin GROUPTITLE TITLE\]  
> \.\.\.  
> \[index\_end\]

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\.

> \[index\_begin GROUPTITLE TITLE\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \.\.\.  
> \[index\_end\]

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __index\_begin__ may contain only the templating commands __vset__
and __include__, a file included after a key may contain only manape or url
references, and other keys, etc\.

................................................................................
characters, namely __\[__ and __\]__\. These commands, __lb__ and
__rb__ respectively, are required because our use of \[ and \] to bracket
markup commands makes it impossible to directly use \[ and \] within the text\.

Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
> &nbsp;&nbsp;because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
> &nbsp;&nbsp;impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
> &nbsp;&nbsp;\.\.\.

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[docidx language syntax](docidx\_lang\_syntax\.md)* specification as well\.
From here on out the *[docidx language command

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

63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
..
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
...
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
...
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [division_start {Appendix 1}] ...

    ... [item thefile \\
            label {file description}] ...

## <a name='subsection2'></a>Basic structure

The most simple document which can be written in doctoc is

    [toc_begin GROUPTITLE TITLE]
................................................................................
Symbolic names are used to preserve the convertibility of this format to any
output format\. The actual name of any file will be inserted by the chosen
formatting engine when converting the input, based on a mapping from symbolic to
actual names given to the engine\.

Here a made up example for a table of contents of this document:

    [toc_begin Doctoc {Language Introduction}]
    [__item 1 DESCRIPTION__]
    [__item 1.1 {Basic structure}__]
    [__item 1.2 Items__]
    [__item 1.3 Divisions__]
    [__item 2 {FURTHER READING}__]
    [toc_end]

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

One thing of notice in the last example in the previous section is that the
referenced sections actually had a nested structure, something which was
expressed in the item labels, by using a common prefix for all the sections
nested under section 1\.
................................................................................

  - __division\_end__

    This command closes the last opened and not yet closed division\.

Using this we can recast the last example like this

    [toc_begin Doctoc {Language Introduction}]
    [__division_start DESCRIPTION__]
    [item 1 {Basic structure}]
    [item 2 Items]
    [item 3 Divisions]
    [__division_end__]
    [__division_start {FURTHER READING}__]
    [__division_end__]
    [toc_end]

Or, to demonstrate deeper nesting

    [toc_begin Doctoc {Language Introduction}]
    [__division_start DESCRIPTION__]
    [__division_start {Basic structure}__]
    [item 1 Do]
    [item 2 Re]
    [__division_end__]
    [__division_start Items__]
    [item a Fi]
    [item b Fo]
    [item c Fa]
    [__division_end__]
    [__division_start Divisions__]
    [item 1 Sub]
    [item 1 Zero]
    [__division_end__]
    [__division_end__]
    [__division_start {FURTHER READING}__]
    [__division_end__]
    [toc_end]

And do not forget, it is possible to freely mix items and divisions, and to have
empty divisions\.

    [toc_begin Doctoc {Language Introduction}]
    [item 1 Do]
    [__division_start DESCRIPTION__]
    [__division_start {Basic structure}__]
    [item 2 Re]
    [__division_end__]
    [item a Fi]
    [__division_start Items__]
    [item b Fo]
    [item c Fa]
    [__division_end__]
    [__division_start Divisions__]
    [__division_end__]
    [__division_end__]
    [__division_start {FURTHER READING}__]
    [__division_end__]
    [toc_end]

## <a name='subsection5'></a>Advanced structure

In all previous examples we fudged a bit regarding the markup actually allowed
to be used before the __toc\_begin__ command opening the document\.

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

    [__include FILE__]
    [__vset VAR VALUE__]
    [toc_begin GROUPTITLE TITLE]
    ...
    [toc_end]

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\.

    [toc_begin GROUPTITLE TITLE]
    [__include FILE__]
    [__vset VAR VALUE__]
    ...
    [toc_end]

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __toc\_begin__ may contain only the templating commands __vset__
and __include__, a file included in a division may contain only items or
divisions commands, etc\.

................................................................................
characters, namely __\[__ and __\]__\. These commands, __lb__ and
__rb__ respectively, are required because our use of \[ and \] to bracket
markup commands makes it impossible to directly use \[ and \] within the text\.

Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

    ...
    These commands, [cmd lb] and [cmd lb] respectively, are required
    because our use of [__lb__] and [__rb__] to bracket markup commands makes it
    impossible to directly use [__lb__] and [__rb__] within the text.
    ...

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification as well\.
From here on out the *[doctoc language command






|







 







|
|
|
|
|
|
|







 







|
|
|
|
|
|
|
|
|



|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|




|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|











|
|
|
|
|




|
|
|
|
|







 







|
|
|
|
|







63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
..
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
...
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
...
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [division_start {Appendix 1}] ...

    ... [item thefile \
            label {file description}] ...

## <a name='subsection2'></a>Basic structure

The most simple document which can be written in doctoc is

    [toc_begin GROUPTITLE TITLE]
................................................................................
Symbolic names are used to preserve the convertibility of this format to any
output format\. The actual name of any file will be inserted by the chosen
formatting engine when converting the input, based on a mapping from symbolic to
actual names given to the engine\.

Here a made up example for a table of contents of this document:

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__item 1 DESCRIPTION__\]  
> \[__item 1\.1 \{Basic structure\}__\]  
> \[__item 1\.2 Items__\]  
> \[__item 1\.3 Divisions__\]  
> \[__item 2 \{FURTHER READING\}__\]  
> \[toc\_end\]

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

One thing of notice in the last example in the previous section is that the
referenced sections actually had a nested structure, something which was
expressed in the item labels, by using a common prefix for all the sections
nested under section 1\.
................................................................................

  - __division\_end__

    This command closes the last opened and not yet closed division\.

Using this we can recast the last example like this

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__division\_start DESCRIPTION__\]  
> \[item 1 \{Basic structure\}\]  
> \[item 2 Items\]  
> \[item 3 Divisions\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]

Or, to demonstrate deeper nesting

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[__division\_start DESCRIPTION__\]  
> \[__division\_start \{Basic structure\}__\]  
> \[item 1 Do\]  
> \[item 2 Re\]  
> \[__division\_end__\]  
> \[__division\_start Items__\]  
> \[item a Fi\]  
> \[item b Fo\]  
> \[item c Fa\]  
> \[__division\_end__\]  
> \[__division\_start Divisions__\]  
> \[item 1 Sub\]  
> \[item 1 Zero\]  
> \[__division\_end__\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]

And do not forget, it is possible to freely mix items and divisions, and to have
empty divisions\.

> \[toc\_begin Doctoc \{Language Introduction\}\]  
> \[item 1 Do\]  
> \[__division\_start DESCRIPTION__\]  
> \[__division\_start \{Basic structure\}__\]  
> \[item 2 Re\]  
> \[__division\_end__\]  
> \[item a Fi\]  
> \[__division\_start Items__\]  
> \[item b Fo\]  
> \[item c Fa\]  
> \[__division\_end__\]  
> \[__division\_start Divisions__\]  
> \[__division\_end__\]  
> \[__division\_end__\]  
> \[__division\_start \{FURTHER READING\}__\]  
> \[__division\_end__\]  
> \[toc\_end\]

## <a name='subsection5'></a>Advanced structure

In all previous examples we fudged a bit regarding the markup actually allowed
to be used before the __toc\_begin__ command opening the document\.

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the table of contents\. I\.e\. it is possible to
write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[toc\_begin GROUPTITLE TITLE\]  
> \.\.\.  
> \[toc\_end\]

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\.

> \[toc\_begin GROUPTITLE TITLE\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \.\.\.  
> \[toc\_end\]

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __toc\_begin__ may contain only the templating commands __vset__
and __include__, a file included in a division may contain only items or
divisions commands, etc\.

................................................................................
characters, namely __\[__ and __\]__\. These commands, __lb__ and
__rb__ respectively, are required because our use of \[ and \] to bracket
markup commands makes it impossible to directly use \[ and \] within the text\.

Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
> &nbsp;&nbsp;because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
> &nbsp;&nbsp;impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
> &nbsp;&nbsp;\.\.\.

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification as well\.
From here on out the *[doctoc language command

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

1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools\(n\) 1\.5\.2 tcllib "Documentation tools")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.2  
package require doctools ?1\.5\.2?  

[__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1)  
[__::doctools::help__](#2)  
[__::doctools::search__ *path*](#3)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#4)  
[*objectName* __configure__](#5)  
[*objectName* __configure__ *option*](#6)  



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
[//000000001]: # (doctools \- Documentation tools)
[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools\(n\) 1\.5\.6 tcllib "Documentation tools")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.2  
package require doctools ?1\.5\.6?  

[__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1)  
[__::doctools::help__](#2)  
[__::doctools::search__ *path*](#3)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#4)  
[*objectName* __configure__](#5)  
[*objectName* __configure__ *option*](#6)  

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

68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
..
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
...
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
...
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
...
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
...
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
...
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
...
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
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [list_begin enumerated] ...

    ... [call [cmd foo] \\
            [arg bar]] ...

    ... [term {complex concept}] ...

    ... [opt "[arg key] [arg value]"] ...

## <a name='subsection2'></a>Basic structure
................................................................................
    [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*\.
................................................................................
and they can be used in any order\. However for __titledesc__ and
__moddesc__ only the last occurrence is taken\. For the other two the
specified information is accumulated, in the given order\. Regular text is not
allowed within the header\.

Given the above a less minimal example of a document is

    [manpage_begin NAME SECTION VERSION]
    [__copyright {YEAR AUTHOR}__]
    [__titledesc TITLE__]
    [__moddesc   MODULE_TITLE__]
    [__require   PACKAGE VERSION__]
    [__require   PACKAGE__]
    [description]
    [manpage_end]

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,
in the form of the __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ command\.

    [__comment { ... }__]
    [manpage_begin NAME SECTION VERSION]
    [copyright {YEAR AUTHOR}]
    [titledesc TITLE]
    [moddesc   MODULE_TITLE][__comment { ... }__]
    [require   PACKAGE VERSION]
    [require   PACKAGE]
    [description]
    [manpage_end]
    [__comment { ... }__]

## <a name='subsection3'></a>Advanced structure

In the simple examples of the last section we fudged a bit regarding the markup
actually allowed to be used before the __manpage\_begin__ command opening the
document\.

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the document\. I\.e\. it is possible to write

    [__include FILE__]
    [__vset VAR VALUE__]
    [manpage_begin NAME SECTION VERSION]
    [description]
    [manpage_end]

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\. I\.e\. for example in
the header as well\.

    [manpage_begin NAME SECTION VERSION]
    [__include FILE__]
    [__vset VAR VALUE__]
    [description]
    [manpage_end]

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __manpage\_begin__ may contain only the templating commands
__vset__ and __include__, a file included in the header may contain only
header commands, etc\.

................................................................................
The simplest way of structuring the body is through the introduction of
paragraphs\. The command for doing so is __para__\. Each occurrence of this
command closes the previous paragraph and automatically opens the next\. The
first paragraph is automatically opened at the beginning of the body, by
__description__\. In the same manner the last paragraph automatically ends at
__manpage\_end__\.

    [manpage_begin NAME SECTION VERSION]
    [description]
     ...
    [__para__]
     ...
    [__para__]
     ...
    [manpage_end]

Empty paragraphs are ignored\.

A structure coarser than paragraphs are sections, which allow the writer to
split a document into larger, and labeled, pieces\. The command for doing so is
__section__\. Each occurrence of this command closes the previous section and
automatically opens the next, including its first paragraph\. The first section
................................................................................
is automatically opened at the beginning of the body, by __description__
\(This section is labeled "DESCRIPTION"\)\. In the same manner the last section
automatically ends at __manpage\_end__\.

Empty sections are *not* ignored\. We are free to \(not\) use paragraphs within
sections\.

    [manpage_begin NAME SECTION VERSION]
    [description]
     ...
    [__section {Section A}__]
     ...
    [para]
     ...
    [__section {Section B}__]
     ...
    [manpage_end]

Between sections and paragraphs we have subsections, to split sections\. The
command for doing so is __subsection__\. Each occurrence of this command
closes the previous subsection and automatically opens the next, including its
first paragraph\. A subsection is automatically opened at the beginning of the
body, by __description__, and at the beginning of each section\. In the same
manner the last subsection automatically ends at __manpage\_end__\.

Empty subsections are *not* ignored\. We are free to \(not\) use paragraphs
within subsections\.

    [manpage_begin NAME SECTION VERSION]
    [description]
     ...
    [section {Section A}]
     ...
    [__subsection {Sub 1}__]
     ...
    [para]
     ...
    [__subsection {Sub 2}__]
     ...
    [section {Section B}]
     ...
    [manpage_end]

## <a name='subsection5'></a>Text markup

Having handled the overall structure a writer can impose on the document we now
take a closer at the text in a paragraph\.

While most often this is just the unadorned content of the document we do have
................................................................................
    Its argument is a widget name\.

The example demonstrating the use of text markup is an excerpt from the
*[doctools language command reference](doctools\_lang\_cmdref\.md)*, with
some highlighting added\. It shows their use within a block of text, as the
arguments of a list item command \(__call__\), and our ability to nest them\.

    ...
    [call [__cmd arg_def__] [__arg type__] [__arg name__] [__opt__ [__arg mode__]]]

    Text structure. List element. Argument list. Automatically closes the
    previous list element. Specifies the data-[__arg type__] of the described
    argument of a command, its [__arg name__] and its i/o-[__arg mode__]. The
    latter is optional.
    ...

## <a name='subsection6'></a>Escapes

Beyond the 20 commands for simple markup shown in the previous section we have
two more available which are technically simple markup\. However their function
is not the marking up of phrases as specific types of things, but the insertion
of characters, namely __\[__ and __\]__\. These commands, __lb__ and
__rb__ respectively, are required because our use of \[ and \] to bracket
markup commands makes it impossible to directly use \[ and \] within the text\.

Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

    ...
    These commands, [cmd lb] and [cmd lb] respectively, are required
    because our use of [__lb__] and [__rb__] to bracket markup commands makes it
    impossible to directly use [__lb__] and [__rb__] within the text.
    ...

## <a name='subsection7'></a>Cross\-references

The last two commands we have to discuss are for the declaration of
cross\-references between documents, explicit and implicit\. They are
__[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ and __see\_also__\. Both
take an arbitrary number of arguments, all of which have to be plain unmarked
................................................................................
whether she wants to have them at the beginning of the body, or at its end,
maybe near the place a keyword is actually defined by the main content, or
considers them as meta data which should be in the header, etc\.

Our example shows the sources for the cross\-references of this document, with
some highlighting added\. Incidentally they are found at the end of the body\.

    ...
    [__see_also doctools_intro__]
    [__see_also doctools_lang_syntax__]
    [__see_also doctools_lang_cmdref__]
    [__keywords markup {semantic markup}__]
    [__keywords {doctools markup} {doctools language}__]
    [__keywords {doctools syntax} {doctools commands}__]
    [manpage_end]

## <a name='subsection8'></a>Examples

Where ever we can write plain text we can write examples too\. For simple
examples we have the command __example__ which takes a single argument, the
text of the argument\. The example text must not contain markup\. If we wish to
have markup within an example we have to use the 2\-command combination
................................................................................
embed examples and lists within an example\. On the other hand, we *can* use
templating commands within example blocks to read their contents from a file
\(Remember section [Advanced structure](#subsection3)\)\.

The source for the very first example in this document \(see section
[Fundamentals](#subsection1)\), with some highlighting added, is

    [__example__ {
        ... [list_begin enumerated] ...
      }]

Using __example\_begin__ / __example\_end__ this would look like

    [__example_begin__]
        ... [list_begin enumerated] ...
      [__example_end__]

## <a name='subsection9'></a>Lists

Where ever we can write plain text we can write lists too\. The main commands are
__list\_begin__ to start a list, and __list\_end__ to close one\. The
opening command takes an argument specifying the type of list started it, and
this in turn determines which of the eight existing list item commands are
................................................................................
    is a specialized form of a term definition list where the term is the name
    of a configuration option for a widget, with its name and class in the
    option database\.

Our example is the source of the definition list in the previous paragraph, with
most of the content in the middle removed\.

    ...
    [__list_begin__ definitions]
    [__def__ [const arg]]

    ([cmd arg_def]) This opens an argument (declaration) list. It is a
    specialized form of a definition list where the term is an argument
    name, with its type and i/o-mode.

    [__def__ [const itemized]]

    ([cmd item])
    This opens a general itemized list.

    ...
    [__def__ [const tkoption]]

    ([cmd tkoption_def]) This opens a widget option (declaration) list. It
    is a specialized form of a definition list where the term is the name
    of a configuration option for a widget, with its name and class in the
    option database.

    [__list_end__]
    ...

Note that a list cannot begin in one \(sub\)section and end in another\.
Differently said, \(sub\)section breaks are not allowed within lists and list
items\. An example of this *illegal* construct is

    ...
    [list_begin itemized]
    [item]
    ...
    [__section {ILLEGAL WITHIN THE LIST}__]
    ...
    [list_end]
    ...

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[doctools language syntax](doctools\_lang\_syntax\.md)* specification as
well\. From here on out the *[doctools language command






|







 







|







 







|
|
|
|
|
|
|
|







|









|
|
|
|
|
|
|
|
|
|











|
|
|
|
|





|
|
|
|
|







 







|
|
|
|
|
|
|
|







 







|
|
|
|
|
|
|
|
|
|











|
|
|
|
|
|
|
|
|
|
|
|
|
|







 







|
|
|
|
|
|
|
|













|
|
|
|
|







 







|
|
|
|
|
|
|
|







 







|
|
|



|
|
|







 







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|





|
|
|
|
|
|
|
|







68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
..
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
...
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
...
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
...
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
...
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
...
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
...
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
Each markup command is a Tcl command surrounded by a matching pair of __\[__
and __\]__\. Inside of these delimiters the usual rules for a Tcl command
apply with regard to word quotation, nested commands, continuation lines, etc\.
I\.e\.

    ... [list_begin enumerated] ...

    ... [call [cmd foo] \
            [arg bar]] ...

    ... [term {complex concept}] ...

    ... [opt "[arg key] [arg value]"] ...

## <a name='subsection2'></a>Basic structure
................................................................................
    [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*\.
................................................................................
and they can be used in any order\. However for __titledesc__ and
__moddesc__ only the last occurrence is taken\. For the other two the
specified information is accumulated, in the given order\. Regular text is not
allowed within the header\.

Given the above a less minimal example of a document is

> \[manpage\_begin NAME SECTION VERSION\]  
> \[__copyright \{YEAR AUTHOR\}__\]  
> \[__titledesc TITLE__\]  
> \[__moddesc   MODULE\_TITLE__\]  
> \[__require   PACKAGE VERSION__\]  
> \[__require   PACKAGE__\]  
> \[description\]  
> \[manpage\_end\]

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,
in the form of the __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ command\.

> \[__comment \{ \.\.\. \}__\]  
> \[manpage\_begin NAME SECTION VERSION\]  
> \[copyright \{YEAR AUTHOR\}\]  
> \[titledesc TITLE\]  
> \[moddesc   MODULE\_TITLE\]\[__comment \{ \.\.\. \}__\]  
> \[require   PACKAGE VERSION\]  
> \[require   PACKAGE\]  
> \[description\]  
> \[manpage\_end\]  
> \[__comment \{ \.\.\. \}__\]

## <a name='subsection3'></a>Advanced structure

In the simple examples of the last section we fudged a bit regarding the markup
actually allowed to be used before the __manpage\_begin__ command opening the
document\.

Instead of only whitespace the two templating commands __include__ and
__vset__ are also allowed, to enable the writer to either set and/or import
configuration settings relevant to the document\. I\.e\. it is possible to write

> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
> \[manpage\_end\]

Even more important, these two commands are allowed anywhere where a markup
command is allowed, without regard for any other structure\. I\.e\. for example in
the header as well\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[__include FILE__\]  
> \[__vset VAR VALUE__\]  
> \[description\]  
> \[manpage\_end\]

The only restriction __include__ has to obey is that the contents of the
included file must be valid at the place of the inclusion\. I\.e\. a file included
before __manpage\_begin__ may contain only the templating commands
__vset__ and __include__, a file included in the header may contain only
header commands, etc\.

................................................................................
The simplest way of structuring the body is through the introduction of
paragraphs\. The command for doing so is __para__\. Each occurrence of this
command closes the previous paragraph and automatically opens the next\. The
first paragraph is automatically opened at the beginning of the body, by
__description__\. In the same manner the last paragraph automatically ends at
__manpage\_end__\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
> &nbsp;\.\.\.  
> \[__para__\]  
> &nbsp;\.\.\.  
> \[__para__\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]

Empty paragraphs are ignored\.

A structure coarser than paragraphs are sections, which allow the writer to
split a document into larger, and labeled, pieces\. The command for doing so is
__section__\. Each occurrence of this command closes the previous section and
automatically opens the next, including its first paragraph\. The first section
................................................................................
is automatically opened at the beginning of the body, by __description__
\(This section is labeled "DESCRIPTION"\)\. In the same manner the last section
automatically ends at __manpage\_end__\.

Empty sections are *not* ignored\. We are free to \(not\) use paragraphs within
sections\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
> &nbsp;\.\.\.  
> \[__section \{Section A\}__\]  
> &nbsp;\.\.\.  
> \[para\]  
> &nbsp;\.\.\.  
> \[__section \{Section B\}__\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]

Between sections and paragraphs we have subsections, to split sections\. The
command for doing so is __subsection__\. Each occurrence of this command
closes the previous subsection and automatically opens the next, including its
first paragraph\. A subsection is automatically opened at the beginning of the
body, by __description__, and at the beginning of each section\. In the same
manner the last subsection automatically ends at __manpage\_end__\.

Empty subsections are *not* ignored\. We are free to \(not\) use paragraphs
within subsections\.

> \[manpage\_begin NAME SECTION VERSION\]  
> \[description\]  
> &nbsp;\.\.\.  
> \[section \{Section A\}\]  
> &nbsp;\.\.\.  
> \[__subsection \{Sub 1\}__\]  
> &nbsp;\.\.\.  
> \[para\]  
> &nbsp;\.\.\.  
> \[__subsection \{Sub 2\}__\]  
> &nbsp;\.\.\.  
> \[section \{Section B\}\]  
> &nbsp;\.\.\.  
> \[manpage\_end\]

## <a name='subsection5'></a>Text markup

Having handled the overall structure a writer can impose on the document we now
take a closer at the text in a paragraph\.

While most often this is just the unadorned content of the document we do have
................................................................................
    Its argument is a widget name\.

The example demonstrating the use of text markup is an excerpt from the
*[doctools language command reference](doctools\_lang\_cmdref\.md)*, with
some highlighting added\. It shows their use within a block of text, as the
arguments of a list item command \(__call__\), and our ability to nest them\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[call \[__cmd arg\_def__\] \[__arg type__\] \[__arg name__\] \[__opt__ \[__arg mode__\]\]\]  
>   
> &nbsp;&nbsp;Text structure\. List element\. Argument list\. Automatically closes the  
> &nbsp;&nbsp;previous list element\. Specifies the data\-\[__arg type__\] of the described  
> &nbsp;&nbsp;argument of a command, its \[__arg name__\] and its i/o\-\[__arg mode__\]\. The  
> &nbsp;&nbsp;latter is optional\.  
> &nbsp;&nbsp;\.\.\.

## <a name='subsection6'></a>Escapes

Beyond the 20 commands for simple markup shown in the previous section we have
two more available which are technically simple markup\. However their function
is not the marking up of phrases as specific types of things, but the insertion
of characters, namely __\[__ and __\]__\. These commands, __lb__ and
__rb__ respectively, are required because our use of \[ and \] to bracket
markup commands makes it impossible to directly use \[ and \] within the text\.

Our example of their use are the sources of the last sentence in the previous
paragraph, with some highlighting added\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;These commands, \[cmd lb\] and \[cmd lb\] respectively, are required  
> &nbsp;&nbsp;because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it  
> &nbsp;&nbsp;impossible to directly use \[__lb__\] and \[__rb__\] within the text\.  
> &nbsp;&nbsp;\.\.\.

## <a name='subsection7'></a>Cross\-references

The last two commands we have to discuss are for the declaration of
cross\-references between documents, explicit and implicit\. They are
__[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ and __see\_also__\. Both
take an arbitrary number of arguments, all of which have to be plain unmarked
................................................................................
whether she wants to have them at the beginning of the body, or at its end,
maybe near the place a keyword is actually defined by the main content, or
considers them as meta data which should be in the header, etc\.

Our example shows the sources for the cross\-references of this document, with
some highlighting added\. Incidentally they are found at the end of the body\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__see\_also doctools\_intro__\]  
> &nbsp;&nbsp;\[__see\_also doctools\_lang\_syntax__\]  
> &nbsp;&nbsp;\[__see\_also doctools\_lang\_cmdref__\]  
> &nbsp;&nbsp;\[__keywords markup \{semantic markup\}__\]  
> &nbsp;&nbsp;\[__keywords \{doctools markup\} \{doctools language\}__\]  
> &nbsp;&nbsp;\[__keywords \{doctools syntax\} \{doctools commands\}__\]  
> &nbsp;&nbsp;\[manpage\_end\]

## <a name='subsection8'></a>Examples

Where ever we can write plain text we can write examples too\. For simple
examples we have the command __example__ which takes a single argument, the
text of the argument\. The example text must not contain markup\. If we wish to
have markup within an example we have to use the 2\-command combination
................................................................................
embed examples and lists within an example\. On the other hand, we *can* use
templating commands within example blocks to read their contents from a file
\(Remember section [Advanced structure](#subsection3)\)\.

The source for the very first example in this document \(see section
[Fundamentals](#subsection1)\), with some highlighting added, is

> \[__example__ \{  
> &nbsp;&nbsp;&nbsp;&nbsp;\.\.\. \[list\_begin enumerated\] \.\.\.  
> &nbsp;&nbsp;\}\]

Using __example\_begin__ / __example\_end__ this would look like

> \[__example\_begin__\]  
> &nbsp;&nbsp;&nbsp;&nbsp;\.\.\. \[list\_begin enumerated\] \.\.\.  
> &nbsp;&nbsp;\[__example\_end__\]

## <a name='subsection9'></a>Lists

Where ever we can write plain text we can write lists too\. The main commands are
__list\_begin__ to start a list, and __list\_end__ to close one\. The
opening command takes an argument specifying the type of list started it, and
this in turn determines which of the eight existing list item commands are
................................................................................
    is a specialized form of a term definition list where the term is the name
    of a configuration option for a widget, with its name and class in the
    option database\.

Our example is the source of the definition list in the previous paragraph, with
most of the content in the middle removed\.

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__list\_begin__ definitions\]  
> &nbsp;&nbsp;\[__def__ \[const arg\]\]  
>   
> &nbsp;&nbsp;\(\[cmd arg\_def\]\) This opens an argument \(declaration\) list\. It is a  
> &nbsp;&nbsp;specialized form of a definition list where the term is an argument  
> &nbsp;&nbsp;name, with its type and i/o\-mode\.  
>   
> &nbsp;&nbsp;\[__def__ \[const itemized\]\]  
>   
> &nbsp;&nbsp;\(\[cmd item\]\)  
> &nbsp;&nbsp;This opens a general itemized list\.  
>   
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__def__ \[const tkoption\]\]  
>   
> &nbsp;&nbsp;\(\[cmd tkoption\_def\]\) This opens a widget option \(declaration\) list\. It  
> &nbsp;&nbsp;is a specialized form of a definition list where the term is the name  
> &nbsp;&nbsp;of a configuration option for a widget, with its name and class in the  
> &nbsp;&nbsp;option database\.  
>   
> &nbsp;&nbsp;\[__list\_end__\]  
> &nbsp;&nbsp;\.\.\.

Note that a list cannot begin in one \(sub\)section and end in another\.
Differently said, \(sub\)section breaks are not allowed within lists and list
items\. An example of this *illegal* construct is

> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[list\_begin itemized\]  
> &nbsp;&nbsp;\[item\]  
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[__section \{ILLEGAL WITHIN THE LIST\}__\]  
> &nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;\[list\_end\]  
> &nbsp;&nbsp;\.\.\.

# <a name='section2'></a>FURTHER READING

Now that this document has been digested the reader, assumed to be a *writer*
of documentation should be fortified enough to be able to understand the formal
*[doctools language syntax](doctools\_lang\_syntax\.md)* specification as
well\. From here on out the *[doctools language command

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

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (mpexpand \- Documentation toolbox)
[//000000002]: # (Generated from file 'mpexpand\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2002 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2003 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (mpexpand\(n\) 1\.0 tcllib "Documentation toolbox")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (mpexpand \- Documentation toolbox)
[//000000002]: # (Generated from file 'mpexpand\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2002 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2003 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (mpexpand\(n\) 1\.0 tcllib "Documentation toolbox")

<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>

Changes to embedded/md/tcllib/files/modules/doctools2idx/export_docidx.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
...
246
247
248
249
250
251
252
253
[//000000001]: # (doctools::idx::export::docidx \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::docidx\(n\) 0\.1 tcllib "Documentation tools")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require doctools::idx::export::docidx ?0\.1?  

[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1)  

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

This package implements the doctools keyword index export plugin for the
generation of docidx markup\.
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
...
246
247
248
249
250
251
252
253
[//000000001]: # (doctools::idx::export::docidx \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::docidx\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require doctools::idx::export::docidx ?0\.2\.1?  

[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1)  

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

This package implements the doctools keyword index export plugin for the
generation of docidx markup\.
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_export.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
...
465
466
467
468
469
470
471
472
[//000000001]: # (doctools::idx::export \- Documentation tools)
[//000000002]: # (Generated from file 'idx\_export\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2018 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export\(n\) 0\.2 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require doctools::idx::export ?0\.2?  
package require Tcl 8\.4  
package require doctools::config  
package require doctools::idx::structure  
package require snit  
package require pluginmgr  

[__::doctools::idx::export__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
................................................................................

# <a name='category'></a>CATEGORY

Documentation tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2018 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|

|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
...
465
466
467
468
469
470
471
472
[//000000001]: # (doctools::idx::export \- Documentation tools)
[//000000002]: # (Generated from file 'idx\_export\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require doctools::idx::export ?0\.2\.1?  
package require Tcl 8\.4  
package require struct::map  
package require doctools::idx::structure  
package require snit  
package require pluginmgr  

[__::doctools::idx::export__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
................................................................................

# <a name='category'></a>CATEGORY

Documentation tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_export_html.md.

1
2
3
4
5
6
7
8
9
10
11
...
344
345
346
347
348
349
350
351
[//000000001]: # (doctools::idx::export::html \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::html\(n\) 0\.2 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
344
345
346
347
348
349
350
351
[//000000001]: # (doctools::idx::export::html \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::html\(n\) 0\.2 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_export_json.md.

1
2
3
4
5
6
7
8
9
10
11
...
253
254
255
256
257
258
259
260
[//000000001]: # (doctools::idx::export::json \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::json\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
253
254
255
256
257
258
259
260
[//000000001]: # (doctools::idx::export::json \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::json\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_export_nroff.md.

1
2
3
4
5
6
7
8
9
10
11
...
208
209
210
211
212
213
214
215
[//000000001]: # (doctools::idx::export::nroff \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::nroff\(n\) 0\.3 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
208
209
210
211
212
213
214
215
[//000000001]: # (doctools::idx::export::nroff \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::nroff\(n\) 0\.3 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_export_text.md.

1
2
3
4
5
6
7
8
9
10
11
...
192
193
194
195
196
197
198
199
[//000000001]: # (doctools::idx::export::text \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::text\(n\) 0\.2 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
192
193
194
195
196
197
198
199
[//000000001]: # (doctools::idx::export::text \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::text\(n\) 0\.2 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_export_wiki.md.

1
2
3
4
5
6
7
8
9
10
11
...
208
209
210
211
212
213
214
215
[//000000001]: # (doctools::idx::export::wiki \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::wiki\(n\) 0\.2 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
208
209
210
211
212
213
214
215
[//000000001]: # (doctools::idx::export::wiki \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::export::wiki\(n\) 0\.2 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_import.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
...
522
523
524
525
526
527
528
529
[//000000001]: # (doctools::idx::import \- Documentation tools)
[//000000002]: # (Generated from file 'idx\_import\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2018 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::import\(n\) 0\.2 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require doctools::idx::import ?0\.2?  
package require Tcl 8\.4  
package require doctools::config  
package require doctools::idx::structure  
package require snit  
package require pluginmgr  

[__::doctools::idx::import__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
................................................................................

# <a name='category'></a>CATEGORY

Documentation tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2018 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|

|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
...
522
523
524
525
526
527
528
529
[//000000001]: # (doctools::idx::import \- Documentation tools)
[//000000002]: # (Generated from file 'idx\_import\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::import\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require doctools::idx::import ?0\.2\.1?  
package require Tcl 8\.4  
package require struct::map  
package require doctools::idx::structure  
package require snit  
package require pluginmgr  

[__::doctools::idx::import__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
................................................................................

# <a name='category'></a>CATEGORY

Documentation tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_import_json.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
225
226
227
228
229
230
231
232
[//000000001]: # (doctools::idx::import::json \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::import::json\(n\) 0\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require doctools::idx::import::json ?0\.1?  
package require doctools::idx::structure  
package require json  

[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration*](#1)  

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

................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|
|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
225
226
227
228
229
230
231
232
[//000000001]: # (doctools::idx::import::json \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::import::json\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require doctools::idx::import::json ?0\.2\.1?  
package require doctools::idx::structure  
package require json  

[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration*](#1)  

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

................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2idx/idx_introduction.md.

131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
                                        ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
                                       ~~                   |               ~~
                    doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
                            |                               |                       |
            +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
            |               |                         |     |    |                  |               |                       |               |
    doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                            |                         |     |    |                  |
                    doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
                            docidx                    |     |    |                  docidx, json
                            json                      |     |    |                  |           \\
                            html                      |     |    |          doctools::idx::parse \\
                            nroff                     |     |    |                  |             \\
                            wiki                      |     |    |  +---------------+              json
                            text                      |     |    |  |               |
                                                    doctools::idx::structure        |
                                                                                    |
                                                                            +-------+---------------+
                                                                            |                       |
              doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat






|



|
|
|







131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
                                        ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
                                       ~~                   |               ~~
                    doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
                            |                               |                       |
            +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
            |               |                         |     |    |                  |               |                       |               |
    struct::map             =                         |     |    |                  =       doctools::include       struct::map      fileutil::paths
                            |                         |     |    |                  |
                    doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
                            docidx                    |     |    |                  docidx, json
                            json                      |     |    |                  |           \
                            html                      |     |    |          doctools::idx::parse \
                            nroff                     |     |    |                  |             \
                            wiki                      |     |    |  +---------------+              json
                            text                      |     |    |  |               |
                                                    doctools::idx::structure        |
                                                                                    |
                                                                            +-------+---------------+
                                                                            |                       |
              doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat

Changes to embedded/md/tcllib/files/modules/doctools2idx/import_docidx.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
204
205
206
207
208
209
210
211
[//000000001]: # (doctools::idx::import::docidx \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::import::docidx\(n\) 0\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require doctools::idx::import::docidx ?0\.1?  
package require doctools::idx::parse  
package require doctools::idx::structure  
package require doctools::msgcat  
package require doctools::tcl::parse  
package require fileutil  
package require logger  
package require snit  
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|
|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
204
205
206
207
208
209
210
211
[//000000001]: # (doctools::idx::import::docidx \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::idx::import::docidx\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require doctools::idx::import::docidx ?0\.2\.1?  
package require doctools::idx::parse  
package require doctools::idx::structure  
package require doctools::msgcat  
package require doctools::tcl::parse  
package require fileutil  
package require logger  
package require snit  
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/export_doctoc.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
...
274
275
276
277
278
279
280
281
[//000000001]: # (doctools::toc::export::doctoc \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::doctoc\(n\) 0\.1 tcllib "Documentation tools")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require doctools::toc::export::doctoc ?0\.1?  

[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1)  

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

This package implements the doctools table of contents export plugin for the
generation of doctoc markup\.
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
...
274
275
276
277
278
279
280
281
[//000000001]: # (doctools::toc::export::doctoc \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::doctoc\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require doctools::toc::export::doctoc ?0\.2\.1?  

[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1)  

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

This package implements the doctools table of contents export plugin for the
generation of doctoc markup\.
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/import_doctoc.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
233
234
235
236
237
238
239
240
[//000000001]: # (doctools::toc::import::doctoc \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::import::doctoc\(n\) 0\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require doctools::toc::import::doctoc ?0\.1?  
package require doctools::toc::parse  
package require doctools::toc::structure  
package require doctools::msgcat  
package require doctools::tcl::parse  
package require fileutil  
package require logger  
package require snit  
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|
|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
233
234
235
236
237
238
239
240
[//000000001]: # (doctools::toc::import::doctoc \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::import::doctoc\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require doctools::toc::import::doctoc ?0\.2\.1?  
package require doctools::toc::parse  
package require doctools::toc::structure  
package require doctools::msgcat  
package require doctools::tcl::parse  
package require fileutil  
package require logger  
package require snit  
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_export.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
...
479
480
481
482
483
484
485
486
[//000000001]: # (doctools::toc::export \- Documentation tools)
[//000000002]: # (Generated from file 'toc\_export\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2018 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export\(n\) 0\.2 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require doctools::toc::export ?0\.2?  
package require Tcl 8\.4  
package require doctools::config  
package require doctools::toc::structure  
package require snit  
package require pluginmgr  

[__::doctools::toc::export__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
................................................................................

# <a name='category'></a>CATEGORY

Documentation tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2018 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|

|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
...
479
480
481
482
483
484
485
486
[//000000001]: # (doctools::toc::export \- Documentation tools)
[//000000002]: # (Generated from file 'toc\_export\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require doctools::toc::export ?0\.2\.1?  
package require Tcl 8\.4  
package require struct::map  
package require doctools::toc::structure  
package require snit  
package require pluginmgr  

[__::doctools::toc::export__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
................................................................................

# <a name='category'></a>CATEGORY

Documentation tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_export_html.md.

1
2
3
4
5
6
7
8
9
10
11
...
333
334
335
336
337
338
339
340
[//000000001]: # (doctools::toc::export::html \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::html\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
333
334
335
336
337
338
339
340
[//000000001]: # (doctools::toc::export::html \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::html\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_export_json.md.

1
2
3
4
5
6
7
8
9
10
11
...
302
303
304
305
306
307
308
309
[//000000001]: # (doctools::toc::export::json \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::json\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
302
303
304
305
306
307
308
309
[//000000001]: # (doctools::toc::export::json \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::json\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_export_nroff.md.

1
2
3
4
5
6
7
8
9
10
11
...
238
239
240
241
242
243
244
245
[//000000001]: # (doctools::toc::export::nroff \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::nroff\(n\) 0\.2 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
238
239
240
241
242
243
244
245
[//000000001]: # (doctools::toc::export::nroff \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::nroff\(n\) 0\.2 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_export_text.md.

1
2
3
4
5
6
7
8
9
10
11
...
221
222
223
224
225
226
227
228
[//000000001]: # (doctools::toc::export::text \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::text\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
221
222
223
224
225
226
227
228
[//000000001]: # (doctools::toc::export::text \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::text\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_export_wiki.md.

1
2
3
4
5
6
7
8
9
10
11
...
230
231
232
233
234
235
236
237
[//000000001]: # (doctools::toc::export::wiki \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::wiki\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|







 







|
1
2
3
4
5
6
7
8
9
10
11
...
230
231
232
233
234
235
236
237
[//000000001]: # (doctools::toc::export::wiki \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::export::wiki\(n\) 0\.1 tcllib "Documentation tools")

<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
................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_import.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
...
539
540
541
542
543
544
545
546
[//000000001]: # (doctools::toc::import \- Documentation tools)
[//000000002]: # (Generated from file 'toc\_import\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2018 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::import\(n\) 0\.2 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require doctools::toc::import ?0\.2?  
package require Tcl 8\.4  
package require doctools::config  
package require doctools::toc::structure  
package require snit  
package require pluginmgr  

[__::doctools::toc::import__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
................................................................................

# <a name='category'></a>CATEGORY

Documentation tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2018 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|

|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
...
539
540
541
542
543
544
545
546
[//000000001]: # (doctools::toc::import \- Documentation tools)
[//000000002]: # (Generated from file 'toc\_import\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::import\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require doctools::toc::import ?0\.2\.1?  
package require Tcl 8\.4  
package require struct::map  
package require doctools::toc::structure  
package require snit  
package require pluginmgr  

[__::doctools::toc::import__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
................................................................................

# <a name='category'></a>CATEGORY

Documentation tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_import_json.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
274
275
276
277
278
279
280
281
[//000000001]: # (doctools::toc::import::json \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::import::json\(n\) 0\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require doctools::toc::import::json ?0\.1?  
package require doctools::toc::structure  
package require json  

[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration*](#1)  

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

................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|
|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
...
274
275
276
277
278
279
280
281
[//000000001]: # (doctools::toc::import::json \- Documentation tools)
[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (doctools::toc::import::json\(n\) 0\.2\.1 tcllib "Documentation tools")

<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>
................................................................................

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require doctools::toc::import::json ?0\.2\.1?  
package require doctools::toc::structure  
package require json  

[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration*](#1)  

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

................................................................................

# <a name='category'></a>CATEGORY

Text formatter plugin

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2009\-2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/doctools2toc/toc_introduction.md.

131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
                                        ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
                                       ~~                   |               ~~
                    doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
                            |                               |                       |
            +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
            |               |                         |     |    |                  |               |                       |               |
    doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
                            |                         |     |    |                  |
                    doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
                            doctoc                    |     |    |                  doctoc, json
                            json                      |     |    |                  |           \\
                            html                      |     |    |          doctools::toc::parse \\
                            nroff                     |     |    |                  |             \\
                            wiki                      |     |    |  +---------------+              json
                            text                      |     |    |  |               |
                                                    doctools::toc::structure        |
                                                                                    |
                                                                            +-------+---------------+
                                                                            |                       |
              doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat






|



|
|
|







131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
                                        ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
                                       ~~                   |               ~~
                    doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
                            |                               |                       |
            +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
            |               |                         |     |    |                  |               |                       |               |
    struct:map              =                         |     |    |                  =       doctools::include       struct::map      fileutil::paths
                            |                         |     |    |                  |
                    doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
                            doctoc                    |     |    |                  doctoc, json
                            json                      |     |    |                  |           \
                            html                      |     |    |          doctools::toc::parse \
                            nroff                     |     |    |                  |             \
                            wiki                      |     |    |  +---------------+              json
                            text                      |     |    |  |               |
                                                    doctools::toc::structure        |
                                                                                    |
                                                                            +-------+---------------+
                                                                            |                       |
              doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat

Changes to embedded/md/tcllib/files/modules/fileutil/multiop.md.

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
    Returns the current path type limiter\.

# <a name='section5'></a>EXAMPLES

The following examples assume that the variable __F__ contains a reference
to a multi\-file operation object\.

        $F do copy                       \\
    	the  *.dll                    \\
    	from c:/TDK/PrivateOpenSSL/bin \\
    	to   [installdir_of tls]

        $F do move      \\
    	the  *       \\
    	from /sources \\
    	into /scratch  \\
    	but not *.html

        # Alternatively use 'except for *.html'.

        $F do           \\
    	move         \\
    	the  index    \\
    	from /sources  \\
    	into /scratch   \\
    	as   pkgIndex.tcl

        $F do         \\
    	remove     \\
    	the *.txt  \\
    	in /scratch

Note that the fact that most commands just modify the object state allows us to
use more off forms as specifications instead of just nearly\-natural language
sentences\. For example the second example in this section can re\-arranged into:

        $F do            \\
    	from /sources \\
    	into /scratch  \\
    	but not *.html \\
    	move           \\
    	the  *

and the result is not only still a valid specification, but even stays
relatively readable\.

Further note that the information collected by the commands __but__,
__except__, and __as__ is automatically reset after the associated
__the__ was executed\. However no other state is reset in that manner,
allowing the user to avoid repetitions of unchanging information\. For example
the second and third examples of this section can be merged and rewritten into
the equivalent:

    $F do                   \\
        move                 \\
        the  *                \\
        from /sources          \\
        into /scratch           \\
        but not *.html not index \\
        the  index               \\
        as   pkgIndex.tcl

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *fileutil* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas






|
|
|


|
|
|
|




|
|
|
|
|


|
|
|






|
|
|
|
|












|
|
|
|
|
|
|







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
    Returns the current path type limiter\.

# <a name='section5'></a>EXAMPLES

The following examples assume that the variable __F__ contains a reference
to a multi\-file operation object\.

        $F do copy                       \
    	the  *.dll                    \
    	from c:/TDK/PrivateOpenSSL/bin \
    	to   [installdir_of tls]

        $F do move      \
    	the  *       \
    	from /sources \
    	into /scratch  \
    	but not *.html

        # Alternatively use 'except for *.html'.

        $F do           \
    	move         \
    	the  index    \
    	from /sources  \
    	into /scratch   \
    	as   pkgIndex.tcl

        $F do         \
    	remove     \
    	the *.txt  \
    	in /scratch

Note that the fact that most commands just modify the object state allows us to
use more off forms as specifications instead of just nearly\-natural language
sentences\. For example the second example in this section can re\-arranged into:

        $F do            \
    	from /sources \
    	into /scratch  \
    	but not *.html \
    	move           \
    	the  *

and the result is not only still a valid specification, but even stays
relatively readable\.

Further note that the information collected by the commands __but__,
__except__, and __as__ is automatically reset after the associated
__the__ was executed\. However no other state is reset in that manner,
allowing the user to avoid repetitions of unchanging information\. For example
the second and third examples of this section can be merged and rewritten into
the equivalent:

    $F do                   \
        move                 \
        the  *                \
        from /sources          \
        into /scratch           \
        but not *.html not index \
        the  index               \
        as   pkgIndex.tcl

# <a name='section6'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *fileutil* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas

Added embedded/md/tcllib/files/modules/fileutil/paths.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
[//000000001]: # (fileutil::paths \- )
[//000000002]: # (Generated from file 'paths\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (fileutil::paths\(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

fileutil::paths \- Manage search path pools

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

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [API](#section2)

  - [Bugs, Ideas, Feedback](#section3)

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

package require Tcl 8\.4  
package require fileutil::paths ?1?  

[__::fileutil::paths__ *poolName*](#1)  
[__poolName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*poolName* __add__ *path*](#3)  
[*poolName* __clear__](#4)  
[*poolName* __paths__](#5)  
[*poolName* __remove__ *path*](#6)  

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

Provides a snit class whose instances manage a pool of \(search\) paths\.

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

The main command provides construction of search path pools:

  - <a name='1'></a>__::fileutil::paths__ *poolName*

    Creates a new, empty pool of search paths with an associated global Tcl
    command whose name is *poolName*\. It may be used to invoke various
    operations on the pool\. It has the following general form:

      * <a name='2'></a>__poolName__ __method__ ?*arg arg \.\.\.*?

        __method__ and *arg*uments determine the exact behavior of the
        command\.

    If *poolName* is specified as __%AUTO%__ a unique name will be
    generated by the package itself\. The result of the command is the
    fully\-qualified name of the instance command\.

The following commands are possible for pool objects:

  - <a name='3'></a>*poolName* __add__ *path*

    Adds the *path* to the pool\. Nothing is done if the *path* is already
    known to the pool\. The result of the command is the empty string\.

  - <a name='4'></a>*poolName* __clear__

    Clears the entire pool\. In other words, removes all paths from it\. The
    result of the command is the empty string\.

  - <a name='5'></a>*poolName* __paths__

    Returns the list of all paths known to the pool, in the order they were
    added\.

  - <a name='6'></a>*poolName* __remove__ *path*

    Removes the *path* from the pool, if it is known to the pool\. Unknown
    paths are ignored without error\. The result of the command is the empty
    string\.

# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *fileutil* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

When proposing code changes, please provide *unified diffs*, i\.e the output of
__diff \-u__\.

Note further that *attachments* are strongly preferred over inlined patches\.
Attachments can be made by going to the __Edit__ form of the ticket
immediately after its creation, and then using the left\-most button in the
secondary navigation bar\.

Changes to embedded/md/tcllib/files/modules/grammar_aycock/aycock.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (grammar::aycock \- Aycock\-Horspool\-Earley parser generator for Tcl)
[//000000002]: # (Generated from file 'aycock\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2006 by Kevin B\. Kenny <[email protected]\.org>
Redistribution permitted under the terms of the Open Publication License <http://www\.opencontent\.org/openpub/>)
[//000000004]: # (grammar::aycock\(n\) 1\.0 tcllib "Aycock\-Horspool\-Earley parser generator for Tcl")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (grammar::aycock \- Aycock\-Horspool\-Earley parser generator for Tcl)
[//000000002]: # (Generated from file 'aycock\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2006 by Kevin B\. Kenny <[email protected]\.org>)
[//000000004]: # (Redistribution permitted under the terms of the Open Publication License <http://www\.opencontent\.org/openpub/>)
[//000000005]: # (grammar::aycock\(n\) 1\.0 tcllib "Aycock\-Horspool\-Earley parser generator for Tcl")

<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>

Changes to embedded/md/tcllib/files/modules/grammar_fa/dexec.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (grammar::fa::dexec \- Finite automaton operations and usage)
[//000000002]: # (Generated from file 'dexec\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2007 Bogdan <[email protected]\.sourceforge\.net>)
[//000000004]: # (grammar::fa::dexec\(n\) 0\.2 tcllib "Finite automaton operations and usage")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (grammar::fa::dexec \- Finite automaton operations and usage)
[//000000002]: # (Generated from file 'dexec\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2007 Bogdan <[email protected]\.sourceforge\.net>)
[//000000005]: # (grammar::fa::dexec\(n\) 0\.2 tcllib "Finite automaton operations and usage")

<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>

Changes to embedded/md/tcllib/files/modules/grammar_fa/fa.md.

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
...
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
    overwriting any existing definition\. This is the assignment operator for
    automatons\. It copies the automaton contained in the FA object *srcFA*
    over the automaton definition in *faName*\. The old contents of *faName*
    are deleted by this operation\.

    This operation is in effect equivalent to

        *faName* __deserialize__ [*srcFA* __serialize__]

  - <a name='6'></a>*faName* __\-\->__ *dstFA*

    This is the reverse assignment operator for automatons\. It copies the
    automation contained in the object *faName* over the automaton definition
    in the object *dstFA*\. The old contents of *dstFA* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *dstFA* __deserialize__ [*faName* __serialize__]

  - <a name='7'></a>*faName* __serialize__

    This method serializes the automaton stored in *faName*\. In other words it
    returns a tcl *value* completely describing that automaton\. This allows,
    for example, the transfer of automatons over arbitrary channels,
    persistence, etc\. This method is also the basis for both the copy
................................................................................
    very simple way :\)

        Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
        (...) is the start state.

    a possible serialization is

        grammar::fa \\
        {yellow red green red/yellow} \\
        {Drive     {0 0 {yellow     Brake}} \\
         Brake     {0 0 {red        Stop}} \\
         Stop      {1 0 {red/yellow Attention}} \\
         Attention {0 0 {green      Drive}}}

    A possible one, because I did not care about creation order here

  - <a name='8'></a>*faName* __deserialize__ *serialization*

    This is the complement to __serialize__\. It replaces the automaton






|










|







 







|
|
|
|
|







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
...
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
    overwriting any existing definition\. This is the assignment operator for
    automatons\. It copies the automaton contained in the FA object *srcFA*
    over the automaton definition in *faName*\. The old contents of *faName*
    are deleted by this operation\.

    This operation is in effect equivalent to

    > *faName* __deserialize__ \[*srcFA* __serialize__\]

  - <a name='6'></a>*faName* __\-\->__ *dstFA*

    This is the reverse assignment operator for automatons\. It copies the
    automation contained in the object *faName* over the automaton definition
    in the object *dstFA*\. The old contents of *dstFA* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *dstFA* __deserialize__ \[*faName* __serialize__\]

  - <a name='7'></a>*faName* __serialize__

    This method serializes the automaton stored in *faName*\. In other words it
    returns a tcl *value* completely describing that automaton\. This allows,
    for example, the transfer of automatons over arbitrary channels,
    persistence, etc\. This method is also the basis for both the copy
................................................................................
    very simple way :\)

        Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
        (...) is the start state.

    a possible serialization is

        grammar::fa \
        {yellow red green red/yellow} \
        {Drive     {0 0 {yellow     Brake}} \
         Brake     {0 0 {red        Stop}} \
         Stop      {1 0 {red/yellow Attention}} \
         Attention {0 0 {green      Drive}}}

    A possible one, because I did not care about creation order here

  - <a name='8'></a>*faName* __deserialize__ *serialization*

    This is the complement to __serialize__\. It replaces the automaton

Changes to embedded/md/tcllib/files/modules/grammar_peg/peg.md.

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
...
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
    overwriting any existing definition\. This is the assignment operator for
    grammars\. It copies the grammar contained in the grammar object *srcPEG*
    over the grammar definition in *pegName*\. The old contents of *pegName*
    are deleted by this operation\.

    This operation is in effect equivalent to

    *pegName* __deserialize__ [*srcPEG* __serialize__]

  - <a name='5'></a>*pegName* __\-\->__ *dstPEG*

    This is the reverse assignment operator for grammars\. It copies the
    automation contained in the object *pegName* over the grammar definition
    in the object *dstPEG*\. The old contents of *dstPEG* are deleted by this
    operation\.

    This operation is in effect equivalent to

    *dstPEG* __deserialize__ [*pegName* __serialize__]

  - <a name='6'></a>*pegName* __serialize__

    This method serializes the grammar stored in *pegName*\. In other words it
    returns a tcl *value* completely describing that grammar\. This allows, for
    example, the transfer of grammars over arbitrary channels, persistence, etc\.
    This method is also the basis for both the copy constructor and the
................................................................................
    MulOp      <- '*' / '/'
    Factor     <- Term (AddOp Term)*
    AddOp      <- '+'/'-'
    Term       <- Number

    a possible serialization is

    grammar::peg \\
    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
     Factor     {x Term {* {x AddOp Term}}} \\
     Term       Number \\
     MulOp      {/ * /} \\
     AddOp      {/ + -} \\
     Number     {x {? Sign} {+ Digit}} \\
     Sign       {/ + -} \\
     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\
    } \\
    {Expression value     Factor     value \\
     Term       value     MulOp      value \\
     AddOp      value     Number     value \\
     Sign       value     Digit      value \\
    }
    Expression

    A possible one, because the order of the nonterminals in the dictionary is
    not relevant\.

  - <a name='7'></a>*pegName* __deserialize__ *serialization*






|










|







 







|
|
|
|
|
|
|
|
|
|
|
|
|
|







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
...
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
    overwriting any existing definition\. This is the assignment operator for
    grammars\. It copies the grammar contained in the grammar object *srcPEG*
    over the grammar definition in *pegName*\. The old contents of *pegName*
    are deleted by this operation\.

    This operation is in effect equivalent to

    > *pegName* __deserialize__ \[*srcPEG* __serialize__\]

  - <a name='5'></a>*pegName* __\-\->__ *dstPEG*

    This is the reverse assignment operator for grammars\. It copies the
    automation contained in the object *pegName* over the grammar definition
    in the object *dstPEG*\. The old contents of *dstPEG* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *dstPEG* __deserialize__ \[*pegName* __serialize__\]

  - <a name='6'></a>*pegName* __serialize__

    This method serializes the grammar stored in *pegName*\. In other words it
    returns a tcl *value* completely describing that grammar\. This allows, for
    example, the transfer of grammars over arbitrary channels, persistence, etc\.
    This method is also the basis for both the copy constructor and the
................................................................................
    MulOp      <- '*' / '/'
    Factor     <- Term (AddOp Term)*
    AddOp      <- '+'/'-'
    Term       <- Number

    a possible serialization is

    grammar::peg \
    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \
     Factor     {x Term {* {x AddOp Term}}} \
     Term       Number \
     MulOp      {/ * /} \
     AddOp      {/ + -} \
     Number     {x {? Sign} {+ Digit}} \
     Sign       {/ + -} \
     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \
    } \
    {Expression value     Factor     value \
     Term       value     MulOp      value \
     AddOp      value     Number     value \
     Sign       value     Digit      value \
    }
    Expression

    A possible one, because the order of the nonterminals in the dictionary is
    not relevant\.

  - <a name='7'></a>*pegName* __deserialize__ *serialization*

Changes to embedded/md/tcllib/files/modules/hook/hook.md.

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
events, and via callback options like the text widget's __\-yscrollcommand__
option\. Tk events are available only in Tk, and callback options require tight
coupling between the modules sending and receiving the notification\.

Loose coupling between sender and receiver is often desirable, however\. In
Model/View/Controller terms, a View can send a command \(stemming from user
input\) to the Controller, which updates the Model\. The Model can then call a
hook *to which all relevant Views subscribe\.* The Model is decoupled from the
Views, and indeed need not know whether any Views actually exist\. At present,
Tcl/Tk has no standard mechanism for implementing loose coupling of this kind\.
This package defines a new command, __hook__, which implements just such a
mechanism\.

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

The __hook__ command manages a collection of hook bindings\. A hook binding
has four elements:

  1. A *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*: the name of the entity






|
|
|
|
|







78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
events, and via callback options like the text widget's __\-yscrollcommand__
option\. Tk events are available only in Tk, and callback options require tight
coupling between the modules sending and receiving the notification\.

Loose coupling between sender and receiver is often desirable, however\. In
Model/View/Controller terms, a View can send a command \(stemming from user
input\) to the Controller, which updates the Model\. The Model can then call a
hook *to which all relevant* *Views subscribe\.* The Model is decoupled from
the Views, and indeed need not know whether any Views actually exist\. At
present, Tcl/Tk has no standard mechanism for implementing loose coupling of
this kind\. This package defines a new command, __hook__, which implements
just such a mechanism\.

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

The __hook__ command manages a collection of hook bindings\. A hook binding
has four elements:

  1. A *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*: the name of the entity

Changes to embedded/md/tcllib/files/modules/httpd/httpd.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
...
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
...
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
[//000000001]: # (tool \- Tcl Web Server)
[//000000002]: # (Generated from file 'httpd\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2018 Sean Woods <[email protected]\.com>)
[//000000004]: # (tool\(n\) 4\.1\.1 tcllib "Tcl Web Server")

<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

tool \- A TclOO and coroutine based web server

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

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [Minimal Example](#section2)

  - [Class ::httpd::server](#section3)

  - [Class ::httpd::reply](#section4)

  - [Reply Method Ensembles](#section5)

  - [Reply Method Ensemble: http\_info](#section6)

  - [Reply Method Ensemble: request](#section7)

  - [Reply Method Ensemble: reply](#section8)

  - [Reply Methods](#section9)

  - [Class ::httpd::content](#section10)

  - [Class ::httpd::content\.cgi](#section11)

  - [Class ::httpd::content\.file](#section12)

  - [Class ::httpd::content\.proxy](#section13)





  - [Class ::httpd::content\.scgi](#section14)



  - [Class ::httpd::content\.websocket](#section15)

  - [SCGI Server Functions](#section16)


  - [Class ::httpd::reply\.scgi](#section17)


  - [Class ::httpd::server\.scgi](#section18)




  - [AUTHORS](#section19)

  - [Bugs, Ideas, Feedback](#section20)

  - [Keywords](#keywords)

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.6  
package require httpd ?4\.1\.1?  
package require sha1  
package require dicttool  
package require oo::meta  
package require oo::dialect  
package require tool  
package require coroutine  
package require fileutil  
package require fileutil::magic::filetype  
package require websocket  
package require mime  
package require cron  
package require uri  
package require Markdown  

[constructor ?port ?port?? ?myaddr ?ipaddr?&#124;all? ?server\_string ?string?? ?server\_name ?string??](#1)  
[method __add\_uri__ *pattern* *dict*](#2)  












































[method __connect__ *sock* *ip* *port*](#3)  

[method __Connect__ *uuid* *sock* *ip*](#4)  
[method __[counter](\.\./counter/counter\.md)__ *which*](#5)  
[method __CheckTimeout__](#6)  

[method __dispatch__ *header\_dict*](#7)  





[method __[log](\.\./log/log\.md)__ *args*](#8)  

[method __port\_listening__](#9)  
[method __PrefixNormalize__ *prefix*](#10)  

[method __start__](#11)  
[method __stop__](#12)  


[method __template__ *page*](#13)  
[method __TemplateSearch__ *page*](#14)  


[method __Validate\_Connection__ *sock* *ip*](#15)  
[method __ENSEMBLE::add__ *field* *element*](#16)  
[method __ENSEMBLE::dump__](#17)  
[method __ENSEMBLE::get__ *field*](#18)  
[method __ENSEMBLE::reset__](#19)  
[method __ENSEMBLE::remove__ *field* *element*](#20)  
[method __ENSEMBLE::replace__ *keyvaluelist*](#21)  
[method __ENSEMBLE::reset__](#22)  
[method __ENSEMBLE::set__ *field* *value*](#23)  
[method __http\_info::netstring__](#24)  
[method __request::parse__ *string*](#25)  
[method __reply::output__](#26)  
[method __close__](#27)  
[method __HttpHeaders__ *sock* *?debug?*](#28)  
[method __dispatch__ *newsock* *datastate*](#29)  
[method __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ *code* *?message?* *?errorInfo?*](#30)  

[method __content__](#31)  

















[method __EncodeStatus__ *status*](#32)  
[method FormData](#33)  
[method MimeParse *mimetext*](#34)  










[method __DoOutput__](#35)  
[method PostData *length*](#36)  
[method __puts__ *string*](#37)  
[method __reset__](#38)  
[method __timeOutCheck__](#39)  
[method __[timestamp](\.\./\.\./\.\./\.\./index\.md\#timestamp)__](#40)  
[method __TransferComplete__ *args*](#41)  
[method __Url\_Decode__ *string*](#42)  
[method cgi\_info](#43)  
[option __path__](#44)  
[option __[prefix](\.\./\.\./\.\./\.\./index\.md\#prefix)__](#45)  
[method proxy\_info](#46)  
[method scgi\_info](#47)  



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

This module implements a web server, suitable for embedding in an application\.
The server is object oriented, and contains all of the fundamentals needed for a
full service website\.

# <a name='section2'></a>Minimal Example

Starting a web service requires starting a class of type __httpd::server__,
and providing that server with one or more URIs to service, and
__httpd::reply__ derived classes to generate them\.

    tool::define ::reply.hello {
      method content {} {
        my puts "<HTML><HEAD><TITLE>IRM Dispatch Server</TITLE></HEAD><BODY>"
        my puts "<h1>Hello World!</h1>"
        my puts </BODY></HTML>
      }
    }
    ::docserver::server create HTTPD port 8015 myaddr 127.0.0.1

    HTTPD add_uri /* [list mixin reply.hello]

# <a name='section3'></a>Class ::httpd::server



This class is the root object of the webserver\. It is responsible for opening
the socket and providing the initial connection negotiation\.







  - <a name='1'></a>constructor ?port ?port?? ?myaddr ?ipaddr?&#124;all? ?server\_string ?string?? ?server\_name ?string??



    Build a new server object\. ?port? is the port to listen on



  - <a name='2'></a>method __add\_uri__ *pattern* *dict*


    Set the hander for a URI pattern\. Information given in the *dict* is
    stored in the data structure the __dispatch__ method uses\. If a field
    called *mixin* is given, that class will be mixed into the reply object
    immediately after construction\.


  - <a name='3'></a>method __connect__ *sock* *ip* *port*


    Reply to an open socket\. This method builds a coroutine to manage the
    remainder of the connection\. The coroutine's operations are driven by the
    __Connect__ method\.


  - <a name='4'></a>method __Connect__ *uuid* *sock* *ip*


    This method reads HTTP headers, and then consults the __dispatch__
    method to determine if the request is valid, and/or what kind of reply to
    generate\. Under normal cases, an object of class __::http::reply__ is
    created\. Fields the server are looking for in particular are: class: A class
    to use instead of the server's own *reply\_class* mixin: A class to be
    mixed into the new object after construction\. All other fields are passed
    along to the __http\_info__ structure of the reply object\. After the
    class is created and the mixin is mixed in, the server invokes the reply
    objects __dispatch__ method\. This action passes control of the socket to
    the reply object\. The reply object manages the rest of the transaction,
    including closing the socket\.

  - <a name='5'></a>method __[counter](\.\./counter/counter\.md)__ *which*


    Increment an internal counter\.


  - <a name='6'></a>method __CheckTimeout__


    Check open connections for a time out event\.


  - <a name='7'></a>method __dispatch__ *header\_dict*


    Given a key/value list of information, return a data structure describing
    how the server should reply\.


  - <a name='8'></a>method __[log](\.\./log/log\.md)__ *args*

    Log an event\. The input for args is free form\. This method is intended to be
    replaced by the user, and is a noop for a stock http::server object\.






  - <a name='9'></a>method __port\_listening__

    Return the actual port that httpd is listening on\.


  - <a name='10'></a>method __PrefixNormalize__ *prefix*

    For the stock version, trim trailing /'s and \*'s from a prefix\. This method
    can be replaced by the end user to perform any other transformations needed
    for the application\.

  - <a name='11'></a>method __start__

    Open the socket listener\.


  - <a name='12'></a>method __stop__

    Shut off the socket listener, and destroy any pending replies\.

  - <a name='13'></a>method __template__ *page*

    Return a template for the string *page*

  - <a name='14'></a>method __TemplateSearch__ *page*

    Perform a search for the template that best matches *page*\. This can
    include local file searches, in\-memory structures, or even database lookups\.
    The stock implementation simply looks for files with a \.tml or \.html
    extension in the ?doc\_root? directory\.

  - <a name='15'></a>method __Validate\_Connection__ *sock* *ip*

    Given a socket and an ip address, return true if this connection should be
    terminated, or false if it should be allowed to continue\. The stock
    implementation always returns 0\. This is intended for applications to be
    able to implement black lists and/or provide security based on IP address\.

# <a name='section4'></a>Class ::httpd::reply


A class which shephards a request through the process of generating a reply\. The
socket associated with the reply is available at all times as the *chan*
variable\. The process of generating a reply begins with an __httpd::server__
generating a __http::class__ object, mixing in a set of behaviors and then
invoking the reply object's __dispatch__ method\. In normal operations the
__dispatch__ method:
................................................................................

  1. Invokes the __content__ method for the object, generating an call to
     the __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ method if an exception
     is raised\.

  1. Invokes the __output__ method for the object

# <a name='section5'></a>Reply Method Ensembles

The __http::reply__ class and its derivatives maintain several variables as
dictionaries internally\. Access to these dictionaries is managed through a
dedicated ensemble\. The ensemble implements most of the same behaviors as the
__[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__ command\. Each ensemble implements
the following methods above, beyond, or modifying standard dicts:

  - <a name='16'></a>method __ENSEMBLE::add__ *field* *element*

    Add *element* to a list stored in *field*, but only if it is not already
    present om the list\.

  - <a name='17'></a>method __ENSEMBLE::dump__

    Return the current contents of the data structure as a key/value list\.

  - <a name='18'></a>method __ENSEMBLE::get__ *field*

    Return the value of the field *field*, or an empty string if it does not
    exist\.

  - <a name='19'></a>method __ENSEMBLE::reset__

    Return a key/value list of the default contents for this data structure\.

  - <a name='20'></a>method __ENSEMBLE::remove__ *field* *element*

    Remove all instances of *element* from the list stored in *field*\.

  - <a name='21'></a>method __ENSEMBLE::replace__ *keyvaluelist*

    Replace the internal dict with the contents of *keyvaluelist*

  - <a name='22'></a>method __ENSEMBLE::reset__

    Replace the internal dict with the default state\.

  - <a name='23'></a>method __ENSEMBLE::set__ *field* *value*

    Set the value of *field* to *value*\.

# <a name='section6'></a>Reply Method Ensemble: http\_info

Manages HTTP headers passed in by the server\. Ensemble Methods:

  - <a name='24'></a>method __http\_info::netstring__

    Return the contents of this data structure as a netstring encoded block\.

# <a name='section7'></a>Reply Method Ensemble: request

Managed data from MIME headers of the request\.

  - <a name='25'></a>method __request::parse__ *string*

    Replace the contents of the data structure with information encoded in a
    MIME formatted block of text \(*string*\)\.

# <a name='section8'></a>Reply Method Ensemble: reply

Manage the headers sent in the reply\.

  - <a name='26'></a>method __reply::output__

    Return the contents of this data structure as a MIME encoded block
    appropriate for an HTTP response\.

# <a name='section9'></a>Reply Methods

  - <a name='27'></a>method __close__

    Terminate the transaction, and close the socket\.

  - <a name='28'></a>method __HttpHeaders__ *sock* *?debug?*

    Stream MIME headers from the socket *sock*, stopping at an empty line\.
    Returns the stream as a block of text\.

  - <a name='29'></a>method __dispatch__ *newsock* *datastate*

    Take over control of the socket *newsock*, and store that as the *chan*
    variable for the object\. This method runs through all of the steps of
    reading HTTP headers, generating content, and closing the connection\. \(See
    class writetup\)\.

  - <a name='30'></a>method __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ *code* *?message?* *?errorInfo?*

    Generate an error message of the specified *code*, and display the
    *message* as the reason for the exception\. *errorInfo* is passed in from
    calls, but how or if it should be displayed is a prerogative of the
    developer\.

  - <a name='31'></a>method __content__

    Generate the content for the reply\. This method is intended to be replaced
    by the mixin\. Developers have the option of streaming output to a buffer via
    the __puts__ method of the reply, or simply populating the
    *reply\_body* variable of the object\. The information returned by the
    __content__ method is not interpreted in any way\. If an exception is
    thrown \(via the __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ command in
    Tcl, for example\) the caller will auto\-generate a 500 \{Internal Error\}
    message\. A typical implementation of __content__ look like:

    tool::define ::test::content.file {
    	superclass ::httpd::content.file
    	# Return a file
    	# Note: this is using the content.file mixin which looks for the reply_file variable
    	# and will auto-compute the Content-Type
    	method content {} {
    	  my reset
        set doc_root [my http_info get doc_root]
        my variable reply_file
        set reply_file [file join $doc_root index.html]
    	}
    }
    tool::define ::test::content.time {
      # return the current system time
    	method content {} {
    		my variable reply_body
        my reply set Content-Type text/plain
    		set reply_body [clock seconds]
    	}
    }
    tool::define ::test::content.echo {
    	method content {} {
    		my variable reply_body
        my reply set Content-Type [my request get CONTENT_TYPE]
    		set reply_body [my PostData [my request get CONTENT_LENGTH]]
    	}
    }
    tool::define ::test::content.form_handler {
    	method content {} {
    	  set form [my FormData]
    	  my reply set Content-Type {text/html; charset=UTF-8}
        my puts [my html header {My Dynamic Page}]
        my puts "<BODY>"
        my puts "You Sent<p>"
        my puts "<TABLE>"
        foreach {f v} $form {
          my puts "<TR><TH>$f</TH><TD><verbatim>$v</verbatim></TD>"
        }
        my puts "</TABLE><p>"
        my puts "Send some info:<p>"
        my puts "<FORM action=/[my http_info get REQUEST_PATH] method POST>"
        my puts "<TABLE>"
        foreach field {name rank serial_number} {
          set line "<TR><TH>$field</TH><TD><input name=\"$field\" "
          if {[dict exists $form $field]} {
            append line " value=\"[dict get $form $field]\"""
          }
          append line " /></TD></TR>"
................................................................................
          my puts $line
        }
        my puts "</TABLE>"
        my puts [my html footer]
    	}
    }




































































  - <a name='32'></a>method __EncodeStatus__ *status*

    Formulate a standard HTTP status header from he string provided\.

  - <a name='33'></a>method FormData











    For GET requests, converts the QUERY\_DATA header into a key/value list\. For
    POST requests, reads the Post data and converts that information to a
    key/value list for application/x\-www\-form\-urlencoded posts\. For multipart
    posts, it composites all of the MIME headers of the post to a singular
    key/value list, and provides MIME\_\* information as computed by the
    __[mime](\.\./mime/mime\.md)__ package, including the MIME\_TOKEN, which
    can be fed back into the mime package to read out the contents\.

  - <a name='34'></a>method MimeParse *mimetext*

    Converts a block of mime encoded text to a key/value list\. If an exception
    is encountered, the method will generate its own call to the
    __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ method, and immediately
    invoke the __output__ method to produce an error code and close the
    connection\.

  - <a name='35'></a>method __DoOutput__

    Generates the the HTTP reply, and streams that reply back across *chan*\.

  - <a name='36'></a>method PostData *length*

    Stream *length* bytes from the *chan* socket, but only of the request is
    a POST or PUSH\. Returns an empty string otherwise\.





  - <a name='37'></a>method __puts__ *string*

    Appends the value of *string* to the end of *reply\_body*, as well as a
    trailing newline character\.







  - <a name='38'></a>method __reset__

    Clear the contents of the *reply\_body* variable, and reset all headers in
    the __reply__ structure back to the defaults for this object\.

  - <a name='39'></a>method __timeOutCheck__

................................................................................

  - <a name='40'></a>method __[timestamp](\.\./\.\./\.\./\.\./index\.md\#timestamp)__

    Return the current system time in the format:

    %a, %d %b %Y %T %Z







  - <a name='41'></a>method __TransferComplete__ *args*

    Intended to be invoked from __chan copy__ as a callback\. This closes
    every channel fed to it on the command line, and then destroys the object\.


    ###
    # Output the body
    ###
    chan configure $sock -translation binary -blocking 0 -buffering full -buffersize 4096
    chan configure $chan -translation binary -blocking 0 -buffering full -buffersize 4096
    if {$length} {
      ###

      # Send any POST/PUT/etc content
      ###

      chan copy $sock $chan -size $SIZE -command [info coroutine]
      yield
    }
    catch {close $sock}
    chan flush $chan




  - <a name='42'></a>method __Url\_Decode__ *string*

    De\-httpizes a string\.

# <a name='section10'></a>Class ::httpd::content

The httpd module includes several ready to use implementations of content mixins
for common use cases\. Options are passed in to the __add\_uri__ method of the
server\.




# <a name='section11'></a>Class ::httpd::content\.cgi


An implementation to relay requests to process which will accept post data
streamed in vie stdin, and sent a reply streamed to stdout\.
















































































  - <a name='43'></a>method cgi\_info

    Mandatory method to be replaced by the end user\. If needed, activates the
    process to proxy, and then returns a list of three values: *exec* \- The
    arguments to send to exec to fire off the responding process, minus the
    stdin/stdout redirection\.


# <a name='section12'></a>Class ::httpd::content\.file


An implementation to deliver files from the local file system\.


  - <a name='44'></a>option __path__


    The root directory on the local file system to be exposed via http\.











  - <a name='45'></a>option __[prefix](\.\./\.\./\.\./\.\./index\.md\#prefix)__



    The prefix of the URI portion to ignore when calculating relative file
    paths\.



































































# <a name='section13'></a>Class ::httpd::content\.proxy

An implementation to relay requests to another HTTP server, and relay the
results back across the request channel\.














  - <a name='46'></a>method proxy\_info

    Mandatory method to be replaced by the end user\. If needed, activates the
    process to proxy, and then returns a list of three values: *proxyhost* \-
    The hostname where the proxy is located *proxyport* \- The port to connect
    to *proxyscript* \- A pre\-amble block of text to send prior to the mirrored
    request


# <a name='section14'></a>Class ::httpd::content\.scgi


An implementation to relay requests to a server listening on a socket expecting
SCGI encoded requests, and relay the results back across the request channel\.


  - <a name='47'></a>method scgi\_info

    Mandatory method to be replaced by the end user\. If needed, activates the
    process to proxy, and then returns a list of three values: *scgihost* \-
    The hostname where the scgi listener is located *scgiport* \- The port to
    connect to *scgiscript* \- The contents of the *SCRIPT\_NAME* header to be
    sent












































# <a name='section15'></a>Class ::httpd::content\.websocket

A placeholder for a future implementation to manage requests that can expect to
be promoted to a Websocket\. Currently it is an empty class\.


# <a name='section16'></a>SCGI Server Functions


The HTTP module also provides an SCGI server implementation, as well as an HTTP
implementation\. To use the SCGI functions, create an object of the
__http::server\.scgi__ class instead of the __http::server__ class\.


# <a name='section17'></a>Class ::httpd::reply\.scgi


An modified __http::reply__ implementation that understands how to deal with
netstring encoded headers\.


# <a name='section18'></a>Class ::httpd::server\.scgi


A modified __http::server__ which is tailored to replying to request
according to the SCGI standard instead of the HTTP standard\.

































# <a name='section19'></a>AUTHORS

Sean Woods

# <a name='section20'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *network* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

When proposing code changes, please provide *unified diffs*, i\.e the output of
|


|










|











|

|

|

|

|

|

|

|

|

|

|

>
>
>
>
|

>
>
|

<
>

<
>

<
>

>
>
|

|










<
|
<
<
<
|









<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
|
|
|
>
|
>
>
>
>
>
|
>
|
|
>
|
|
>
>
|
|
>
>
|
<
<
<
<
<
<
<
<
<
<
|
|
<
<
<
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
<
<
>
>
>
>
>
>
>
>
>
>
|
<
<
|
<
<
<
<
<
<
<
<
<
>
>













|






|
>
|

<
>
>

<
<
>
>
>
>
>
>

<
>
>

<
>
>

<
>

<
<
<
<
>

<
>

<
<
<
>

<
>

<
<
<
|
<
<
<
<
<
<
<

<
>

<
>

<
>

<
>

<
>

<
<
>

|

<
<
>
>
>
>
>

|

<
>

|

<
<
<
<
|

<
>

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
>







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
|
|
|
|

|






|




|







|






|



|








|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|



<
>
>
>
>
>
>
>
>
>
>









|
<
<
<
<
<
<
<
<
<
<
<
<




>
>
>
>
|




>
>
>
>
>
>







 







>
>
>
>
>
>
|

<
<
>

<
<
<
<
<
|
<
>
|
<
>
|
<
|
<
<
>

>
>
|

|

|

|
|
|
>
>
>

<
>

<
<
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

<
<
<
<
>

<
>

<
>

<
>

<
>

>
>
>
>
>
>
>
>
>
|
>
>

<
<
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

<
<
>

>
>
>
>
>
>
>
>
>
>
>
>
|

<
<
<
<
<
>

<
>

<
<
>

|

<
<
<
<
<
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

<
<
>

<
>

<
<
<
>

<
>

<
<
>

<
>

<
<
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|



|







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
...
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
...
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
[//000000001]: # (httpd \- Tcl Web Server)
[//000000002]: # (Generated from file 'httpd\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2018 Sean Woods <[email protected]\.com>)
[//000000004]: # (httpd\(n\) 4\.3\.3 tcllib "Tcl Web Server")

<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

httpd \- A TclOO and coroutine based web server

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

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [Minimal Example](#section2)

  - [Classes](#section3)

      - [Class httpd::mime](#subsection1)

      - [Class httpd::reply](#subsection2)

      - [Class httpd::server](#subsection3)

      - [Class httpd::server::dispatch](#subsection4)

      - [Class httpd::content\.redirect](#subsection5)

      - [Class httpd::content\.cache](#subsection6)

      - [Class httpd::content\.template](#subsection7)

      - [Class httpd::content\.file](#subsection8)

      - [Class httpd::content\.exec](#subsection9)

      - [Class httpd::content\.proxy](#subsection10)

      - [Class httpd::content\.cgi](#subsection11)

      - [Class httpd::protocol\.scgi](#subsection12)

      - [Class httpd::content\.scgi](#subsection13)

      - [Class httpd::server\.scgi](#subsection14)

      - [Class httpd::content\.websocket](#subsection15)


      - [Class httpd::plugin](#subsection16)


      - [Class httpd::plugin\.dict\_dispatch](#subsection17)


      - [Class httpd::reply\.memchan](#subsection18)

      - [Class httpd::plugin\.local\_memchan](#subsection19)

  - [AUTHORS](#section4)

  - [Bugs, Ideas, Feedback](#section5)

  - [Keywords](#keywords)

  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.6  

package require uuid  



package require clay  
package require coroutine  
package require fileutil  
package require fileutil::magic::filetype  
package require websocket  
package require mime  
package require cron  
package require uri  
package require Markdown  



[method __ChannelCopy__ *in* *out* ?*args*?](#1)  
[method __html\_header__ ?*title* ____? ?*args*?](#2)  
[method __html\_footer__ ?*args*?](#3)  
[method __http\_code\_string__ *code*](#4)  
[method __HttpHeaders__ *sock* ?*debug* ____?](#5)  
[method __HttpHeaders\_Default__](#6)  
[method __HttpServerHeaders__](#7)  
[method __MimeParse__ *mimetext*](#8)  
[method __Url\_Decode__ *data*](#9)  
[method __Url\_PathCheck__ *urlsuffix*](#10)  
[method __wait__ *mode* *sock*](#11)  
[variable __ChannelRegister__](#12)  
[variable __reply__](#13)  
[variable __request__](#14)  
[delegate __<server>__](#15)  
[method __constructor__ *ServerObj* ?*args*?](#16)  
[method __destructor__ ?*dictargs*?](#17)  
[method __ChannelRegister__ ?*args*?](#18)  
[method __close__](#19)  
[method __Log\_Dispatched__](#20)  
[method __dispatch__ *newsock* *datastate*](#21)  
[method __Dispatch__](#22)  
[method __html\_header__ *title* ?*args*?](#23)  
[method __html\_footer__ ?*args*?](#24)  
[method __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ *code* ?*msg* ____? ?*errorInfo* ____?](#25)  
[method __content__](#26)  
[method __EncodeStatus__ *status*](#27)  
[method __[log](\.\./log/log\.md)__ *type* ?*info* ____?](#28)  
[method __CoroName__](#29)  
[method __DoOutput__](#30)  
[method __FormData__](#31)  
[method __PostData__ *length*](#32)  
[method __Session\_Load__](#33)  
[method __puts__ *line*](#34)  
[method __RequestFind__ *field*](#35)  
[method __request__ *subcommand* ?*args*?](#36)  
[method __reply__ *subcommand* ?*args*?](#37)  
[method __reset__](#38)  
[method __timeOutCheck__](#39)  
[method __[timestamp](\.\./\.\./\.\./\.\./index\.md\#timestamp)__](#40)  
[variable __template__](#41)  
[variable __url\_patterns__](#42)  
[method __constructor__ *args* ?*port* __auto__? ?*myaddr* __127\.0\.0\.1__? ?*string* __auto__? ?*name* __auto__? ?*doc\_root* ____? ?*reverse\_dns* __0__? ?*configuration\_file* ____? ?*protocol* __HTTP/1\.1__?](#43)  
[method __destructor__ ?*dictargs*?](#44)  
[method __connect__ *sock* *ip* *port*](#45)  
[method __ServerHeaders__ *ip* *http\_request* *mimetxt*](#46)  
[method __Connect__ *uuid* *sock* *ip*](#47)  
[method __[counter](\.\./counter/counter\.md)__ *which*](#48)  
[method __CheckTimeout__](#49)  
[method __[debug](\.\./debug/debug\.md)__ ?*args*?](#50)  
[method __dispatch__ *data*](#51)  
[method __Dispatch\_Default__ *reply*](#52)  
[method __Dispatch\_Local__ *data*](#53)  
[method __Headers\_Local__ *varname*](#54)  
[method __Headers\_Process__ *varname*](#55)  
[method __HostName__ *ipaddr*](#56)  
[method __[log](\.\./log/log\.md)__ ?*args*?](#57)  
[method __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ *slot* ?*class* ____?](#58)  
[method __port\_listening__](#59)  
[method __PrefixNormalize__ *prefix*](#60)  
[method __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ *filename*](#61)  
[method __start__](#62)  
[method __stop__](#63)  
[method __SubObject \{\} db__](#64)  
[method __SubObject \{\} default__](#65)  
[method __template__ *page*](#66)  
[method __TemplateSearch__ *page*](#67)  
[method __Thread\_start__](#68)  
[method __Uuid\_Generate__](#69)  
[method __Validate\_Connection__ *sock* *ip*](#70)  










[method __reset__](#71)  
[method __content__](#72)  



[method __Dispatch__](#73)  
[method __content__](#74)  
[method __FileName__](#75)  
[method __DirectoryListing__ *local\_file*](#76)  
[method __content__](#77)  
[method __Dispatch__](#78)  
[variable __exename__](#79)  
[method __CgiExec__ *execname* *script* *arglist*](#80)  
[method __Cgi\_Executable__ *script*](#81)  
[method __proxy\_channel__](#82)  
[method __proxy\_path__](#83)  
[method __ProxyRequest__ *chana* *chanb*](#84)  
[method __ProxyReply__ *chana* *chanb* ?*args*?](#85)  
[method __Dispatch__](#86)  
[method __FileName__](#87)  
[method __proxy\_channel__](#88)  
[method __ProxyRequest__ *chana* *chanb*](#89)  
[method __ProxyReply__ *chana* *chanb* ?*args*?](#90)  
[method __DirectoryListing__ *local\_file*](#91)  
[method __EncodeStatus__ *status*](#92)  


[method __scgi\_info__](#93)  
[method __proxy\_channel__](#94)  
[method __ProxyRequest__ *chana* *chanb*](#95)  
[method __ProxyReply__ *chana* *chanb* ?*args*?](#96)  
[method __[debug](\.\./debug/debug\.md)__ ?*args*?](#97)  
[method __Connect__ *uuid* *sock* *ip*](#98)  
[method __Dispatch\_Dict__ *data*](#99)  
[method __uri \{\} add__ *vhosts* *patterns* *info*](#100)  
[method __uri \{\} direct__ *vhosts* *patterns* *info* *body*](#101)  
[method __output__](#102)  
[method __DoOutput__](#103)  


[method __close__](#104)  









[method __local\_memchan__ *command* ?*args*?](#105)  
[method __Connect\_Local__ *uuid* *sock* ?*args*?](#106)  

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

This module implements a web server, suitable for embedding in an application\.
The server is object oriented, and contains all of the fundamentals needed for a
full service website\.

# <a name='section2'></a>Minimal Example

Starting a web service requires starting a class of type __httpd::server__,
and providing that server with one or more URIs to service, and
__httpd::reply__ derived classes to generate them\.

    oo::class create ::reply.hello {
      method content {} {
        my puts "<HTML><HEAD><TITLE>IRM Dispatch Server</TITLE></HEAD><BODY>"
        my puts "<h1>Hello World!</h1>"
        my puts </BODY></HTML>
      }
    }
    ::httpd::server create HTTPD port 8015 myaddr 127.0.0.1 doc_root ~/htdocs
    HTTPD plugin dispatch httpd::server::dispatch
    HTTPD uri add * /hello [list mixin reply.hello]


The bare module does have facilities to hose a files from a file system\. Files
that end in a \.tml will be substituted in the style of Tclhttpd:



    <!-- hello.tml -->
    [my html_header {Hello World!}]
    Your Server is running.
    <p>
    The time is now [clock format [clock seconds]]
    [my html_footer]


A complete example of an httpd server is in the /examples directory of Tcllib\.
It also show how to dispatch URIs to other processes via SCGI and HTTP proxies\.


    cd ~/tcl/sandbox/tcllib
    tclsh examples/httpd.tcl


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





## <a name='subsection1'></a>Class  httpd::mime


A metaclass for MIME handling behavior across a live socket




__Methods__


  - <a name='1'></a>method __ChannelCopy__ *in* *out* ?*args*?




  - <a name='2'></a>method __html\_header__ ?*title* ____? ?*args*?









    Returns a block of HTML


  - <a name='3'></a>method __html\_footer__ ?*args*?


  - <a name='4'></a>method __http\_code\_string__ *code*


  - <a name='5'></a>method __HttpHeaders__ *sock* ?*debug* ____?


  - <a name='6'></a>method __HttpHeaders\_Default__



  - <a name='7'></a>method __HttpServerHeaders__

  - <a name='8'></a>method __MimeParse__ *mimetext*



    Converts a block of mime encoded text to a key/value list\. If an exception
    is encountered, the method will generate its own call to the
    __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ method, and immediately
    invoke the __output__ method to produce an error code and close the
    connection\.

  - <a name='9'></a>method __Url\_Decode__ *data*


    De\-httpizes a string\.

  - <a name='10'></a>method __Url\_PathCheck__ *urlsuffix*





  - <a name='11'></a>method __wait__ *mode* *sock*


## <a name='subsection2'></a>Class  httpd::reply
























*ancestors*: __httpd::mime__

A class which shephards a request through the process of generating a reply\. The
socket associated with the reply is available at all times as the *chan*
variable\. The process of generating a reply begins with an __httpd::server__
generating a __http::class__ object, mixing in a set of behaviors and then
invoking the reply object's __dispatch__ method\. In normal operations the
__dispatch__ method:
................................................................................

  1. Invokes the __content__ method for the object, generating an call to
     the __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ method if an exception
     is raised\.

  1. Invokes the __output__ method for the object

































































































Developers have the option of streaming output to a buffer via the __puts__
method of the reply, or simply populating the *reply\_body* variable of the
object\. The information returned by the __content__ method is not
interpreted in any way\. If an exception is thrown \(via the
__[error](\.\./\.\./\.\./\.\./index\.md\#error)__ command in Tcl, for example\) the
caller will auto\-generate a 500 \{Internal Error\} message\. A typical
implementation of __content__ look like:

    clay::define ::test::content.file {
    	superclass ::httpd::content.file
    	# Return a file
    	# Note: this is using the content.file mixin which looks for the reply_file variable
    	# and will auto-compute the Content-Type
    	method content {} {
    	  my reset
        set doc_root [my request get DOCUMENT_ROOT]
        my variable reply_file
        set reply_file [file join $doc_root index.html]
    	}
    }
    clay::define ::test::content.time {
      # return the current system time
    	method content {} {
    		my variable reply_body
        my reply set Content-Type text/plain
    		set reply_body [clock seconds]
    	}
    }
    clay::define ::test::content.echo {
    	method content {} {
    		my variable reply_body
        my reply set Content-Type [my request get CONTENT_TYPE]
    		set reply_body [my PostData [my request get CONTENT_LENGTH]]
    	}
    }
    clay::define ::test::content.form_handler {
    	method content {} {
    	  set form [my FormData]
    	  my reply set Content-Type {text/html; charset=UTF-8}
        my puts [my html_header {My Dynamic Page}]
        my puts "<BODY>"
        my puts "You Sent<p>"
        my puts "<TABLE>"
        foreach {f v} $form {
          my puts "<TR><TH>$f</TH><TD><verbatim>$v</verbatim></TD>"
        }
        my puts "</TABLE><p>"
        my puts "Send some info:<p>"
        my puts "<FORM action=/[my request get REQUEST_PATH] method POST>"
        my puts "<TABLE>"
        foreach field {name rank serial_number} {
          set line "<TR><TH>$field</TH><TD><input name=\"$field\" "
          if {[dict exists $form $field]} {
            append line " value=\"[dict get $form $field]\"""
          }
          append line " /></TD></TR>"
................................................................................
          my puts $line
        }
        my puts "</TABLE>"
        my puts [my html footer]
    	}
    }

__Variable__

  - <a name='12'></a>variable __ChannelRegister__

  - <a name='13'></a>variable __reply__

    A dictionary which will converted into the MIME headers of the reply

  - <a name='14'></a>variable __request__

    A dictionary containing the SCGI transformed HTTP headers for the request

__Delegate__

  - <a name='15'></a>delegate __<server>__

    The server object which spawned this reply

__Methods__

  - <a name='16'></a>method __constructor__ *ServerObj* ?*args*?

  - <a name='17'></a>method __destructor__ ?*dictargs*?

    clean up on exit

  - <a name='18'></a>method __ChannelRegister__ ?*args*?

    Registers a channel to be closed by the close method

  - <a name='19'></a>method __close__

    Close channels opened by this object

  - <a name='20'></a>method __Log\_Dispatched__

    Record a dispatch event

  - <a name='21'></a>method __dispatch__ *newsock* *datastate*

    Accept the handoff from the server object of the socket *newsock* and feed
    it the state *datastate*\. Fields the *datastate* are looking for in
    particular are:

    \* __mixin__ \- A key/value list of slots and classes to be mixed into the
    object prior to invoking __Dispatch__\.

    \* __http__ \- A key/value list of values to populate the object's
    *request* ensemble

    All other fields are passed along to the __clay__ structure of the
    object\.

  - <a name='22'></a>method __Dispatch__

  - <a name='23'></a>method __html\_header__ *title* ?*args*?

  - <a name='24'></a>method __html\_footer__ ?*args*?

  - <a name='25'></a>method __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ *code* ?*msg* ____? ?*errorInfo* ____?

  - <a name='26'></a>method __content__

    REPLACE ME: This method is the "meat" of your application\. It writes to the
    result buffer via the "puts" method and can tweak the headers via "clay put
    header\_reply"

  - <a name='27'></a>method __EncodeStatus__ *status*

    Formulate a standard HTTP status header from he string provided\.


  - <a name='28'></a>method __[log](\.\./log/log\.md)__ *type* ?*info* ____?

  - <a name='29'></a>method __CoroName__

  - <a name='30'></a>method __DoOutput__

    Generates the the HTTP reply, streams that reply back across *chan*, and
    destroys the object\.

  - <a name='31'></a>method __FormData__

    For GET requests, converts the QUERY\_DATA header into a key/value list\. For
    POST requests, reads the Post data and converts that information to a
    key/value list for application/x\-www\-form\-urlencoded posts\. For multipart
    posts, it composites all of the MIME headers of the post to a singular
    key/value list, and provides MIME\_\* information as computed by the
    __[mime](\.\./mime/mime\.md)__ package, including the MIME\_TOKEN, which
    can be fed back into the mime package to read out the contents\.

  - <a name='32'></a>method __PostData__ *length*













    Stream *length* bytes from the *chan* socket, but only of the request is
    a POST or PUSH\. Returns an empty string otherwise\.

  - <a name='33'></a>method __Session\_Load__

    Manage session data

  - <a name='34'></a>method __puts__ *line*

    Appends the value of *string* to the end of *reply\_body*, as well as a
    trailing newline character\.

  - <a name='35'></a>method __RequestFind__ *field*

  - <a name='36'></a>method __request__ *subcommand* ?*args*?

  - <a name='37'></a>method __reply__ *subcommand* ?*args*?

  - <a name='38'></a>method __reset__

    Clear the contents of the *reply\_body* variable, and reset all headers in
    the __reply__ structure back to the defaults for this object\.

  - <a name='39'></a>method __timeOutCheck__

................................................................................

  - <a name='40'></a>method __[timestamp](\.\./\.\./\.\./\.\./index\.md\#timestamp)__

    Return the current system time in the format:

    %a, %d %b %Y %T %Z

## <a name='subsection3'></a>Class  httpd::server

*ancestors*: __httpd::mime__

__Variable__

  - <a name='41'></a>variable __template__



  - <a name='42'></a>variable __url\_patterns__






__Methods__


  - <a name='43'></a>method __constructor__ *args* ?*port* __auto__? ?*myaddr* __127\.0\.0\.1__? ?*string* __auto__? ?*name* __auto__? ?*doc\_root* ____? ?*reverse\_dns* __0__? ?*configuration\_file* ____? ?*protocol* __HTTP/1\.1__?


  - <a name='44'></a>method __destructor__ ?*dictargs*?




  - <a name='45'></a>method __connect__ *sock* *ip* *port*

    Reply to an open socket\. This method builds a coroutine to manage the
    remainder of the connection\. The coroutine's operations are driven by the
    __Connect__ method\.

  - <a name='46'></a>method __ServerHeaders__ *ip* *http\_request* *mimetxt*

  - <a name='47'></a>method __Connect__ *uuid* *sock* *ip*

    This method reads HTTP headers, and then consults the __dispatch__
    method to determine if the request is valid, and/or what kind of reply to
    generate\. Under normal cases, an object of class __::http::reply__ is
    created, and that class's __dispatch__ method\. This action passes
    control of the socket to the reply object\. The reply object manages the rest
    of the transaction, including closing the socket\.


  - <a name='48'></a>method __[counter](\.\./counter/counter\.md)__ *which*



    Increment an internal counter\.

  - <a name='49'></a>method __CheckTimeout__

    Check open connections for a time out event\.

  - <a name='50'></a>method __[debug](\.\./debug/debug\.md)__ ?*args*?

  - <a name='51'></a>method __dispatch__ *data*

    Given a key/value list of information, return a data structure describing
    how the server should reply\.

  - <a name='52'></a>method __Dispatch\_Default__ *reply*

    Method dispatch method of last resort before returning a 404 NOT FOUND
    error\. The default behavior is to look for a file in *DOCUMENT\_ROOT* which
    matches the query\.

  - <a name='53'></a>method __Dispatch\_Local__ *data*

    Method dispatch method invoked prior to invoking methods implemented by
    plugins\. If this method returns a non\-empty dictionary, that structure will
    be passed to the reply\. The default is an empty implementation\.

  - <a name='54'></a>method __Headers\_Local__ *varname*

    Introspect and possibly modify a data structure destined for a reply\. This
    method is invoked before invoking Header methods implemented by plugins\. The
    default implementation is empty\.

  - <a name='55'></a>method __Headers\_Process__ *varname*

    Introspect and possibly modify a data structure destined for a reply\. This
    method is built dynamically by the
    __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ method\.

  - <a name='56'></a>method __HostName__ *ipaddr*

    Convert an ip address to a host name\. If the server/ reverse\_dns flag is
    false, this method simply returns the IP address back\. Internally, this
    method uses the *dns* module from tcllib\.

  - <a name='57'></a>method __[log](\.\./log/log\.md)__ ?*args*?

    Log an event\. The input for args is free form\. This method is intended to be
    replaced by the user, and is a noop for a stock http::server object\.

  - <a name='58'></a>method __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ *slot* ?*class* ____?

    Incorporate behaviors from a plugin\. This method dynamically rebuilds the
    __Dispatch__ and __Headers__ method\. For every plugin, the server
    looks for the following entries in *clay plugin/*:

    *load* \- A script to invoke in the server's namespace during the
    __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ method invokation\.

    *dispatch* \- A script to stitch into the server's __Dispatch__ method\.

    *headers* \- A script to stitch into the server's __Headers__ method\.

    *thread* \- A script to stitch into the server's __Thread\_start__
    method\.

  - <a name='59'></a>method __port\_listening__

    Return the actual port that httpd is listening on\.

  - <a name='60'></a>method __PrefixNormalize__ *prefix*

    For the stock version, trim trailing /'s and \*'s from a prefix\. This method
    can be replaced by the end user to perform any other transformations needed
    for the application\.

  - <a name='61'></a>method __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ *filename*

  - <a name='62'></a>method __start__

    Open the socket listener\.

  - <a name='63'></a>method __stop__





    Shut off the socket listener, and destroy any pending replies\.


  - <a name='64'></a>method __SubObject \{\} db__


  - <a name='65'></a>method __SubObject \{\} default__


  - <a name='66'></a>method __template__ *page*


    Return a template for the string *page*

  - <a name='67'></a>method __TemplateSearch__ *page*

    Perform a search for the template that best matches *page*\. This can
    include local file searches, in\-memory structures, or even database lookups\.
    The stock implementation simply looks for files with a \.tml or \.html
    extension in the ?doc\_root? directory\.

  - <a name='68'></a>method __Thread\_start__

    Built by the __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ method\.
    Called by the __start__ method\. Intended to allow plugins to spawn
    worker threads\.



  - <a name='69'></a>method __Uuid\_Generate__

    Generate a GUUID\. Used to ensure every request has a unique ID\. The default
    implementation is:

    return [::clay::uuid generate]

  - <a name='70'></a>method __Validate\_Connection__ *sock* *ip*

    Given a socket and an ip address, return true if this connection should be
    terminated, or false if it should be allowed to continue\. The stock
    implementation always returns 0\. This is intended for applications to be
    able to implement black lists and/or provide security based on IP address\.

## <a name='subsection4'></a>Class  httpd::server::dispatch

*ancestors*: __httpd::server__

Provide a backward compadible alias

## <a name='subsection5'></a>Class  httpd::content\.redirect

__Methods__

  - <a name='71'></a>method __reset__

  - <a name='72'></a>method __content__

## <a name='subsection6'></a>Class  httpd::content\.cache

__Methods__

  - <a name='73'></a>method __Dispatch__

## <a name='subsection7'></a>Class  httpd::content\.template

__Methods__

  - <a name='74'></a>method __content__

## <a name='subsection8'></a>Class  httpd::content\.file

Class to deliver Static content When utilized, this class is fed a local
filename by the dispatcher

__Methods__

  - <a name='75'></a>method __FileName__

  - <a name='76'></a>method __DirectoryListing__ *local\_file*

  - <a name='77'></a>method __content__

  - <a name='78'></a>method __Dispatch__

## <a name='subsection9'></a>Class  httpd::content\.exec

__Variable__

  - <a name='79'></a>variable __exename__

__Methods__

  - <a name='80'></a>method __CgiExec__ *execname* *script* *arglist*

  - <a name='81'></a>method __Cgi\_Executable__ *script*

## <a name='subsection10'></a>Class  httpd::content\.proxy



*ancestors*: __httpd::content\.exec__

Return data from an proxy process

__Methods__

  - <a name='82'></a>method __proxy\_channel__

  - <a name='83'></a>method __proxy\_path__

  - <a name='84'></a>method __ProxyRequest__ *chana* *chanb*

  - <a name='85'></a>method __ProxyReply__ *chana* *chanb* ?*args*?

  - <a name='86'></a>method __Dispatch__






## <a name='subsection11'></a>Class  httpd::content\.cgi


*ancestors*: __httpd::content\.proxy__



__Methods__

  - <a name='87'></a>method __FileName__






  - <a name='88'></a>method __proxy\_channel__

  - <a name='89'></a>method __ProxyRequest__ *chana* *chanb*

  - <a name='90'></a>method __ProxyReply__ *chana* *chanb* ?*args*?

  - <a name='91'></a>method __DirectoryListing__ *local\_file*

    For most CGI applications a directory list is vorboten

## <a name='subsection12'></a>Class  httpd::protocol\.scgi

Return data from an SCGI process

__Methods__

  - <a name='92'></a>method __EncodeStatus__ *status*

## <a name='subsection13'></a>Class  httpd::content\.scgi

*ancestors*: __httpd::content\.proxy__

__Methods__

  - <a name='93'></a>method __scgi\_info__

  - <a name='94'></a>method __proxy\_channel__

  - <a name='95'></a>method __ProxyRequest__ *chana* *chanb*

  - <a name='96'></a>method __ProxyReply__ *chana* *chanb* ?*args*?

## <a name='subsection14'></a>Class  httpd::server\.scgi

*ancestors*: __httpd::server__

Act as an SCGI Server

__Methods__

  - <a name='97'></a>method __[debug](\.\./debug/debug\.md)__ ?*args*?

  - <a name='98'></a>method __Connect__ *uuid* *sock* *ip*

## <a name='subsection15'></a>Class  httpd::content\.websocket



Upgrade a connection to a websocket


## <a name='subsection16'></a>Class  httpd::plugin




httpd plugin template


## <a name='subsection17'></a>Class  httpd::plugin\.dict\_dispatch



A rudimentary plugin that dispatches URLs from a dict data structure


__Methods__



  - <a name='99'></a>method __Dispatch\_Dict__ *data*

    Implementation of the dispatcher

  - <a name='100'></a>method __uri \{\} add__ *vhosts* *patterns* *info*

  - <a name='101'></a>method __uri \{\} direct__ *vhosts* *patterns* *info* *body*

## <a name='subsection18'></a>Class  httpd::reply\.memchan

*ancestors*: __httpd::reply__

__Methods__

  - <a name='102'></a>method __output__

  - <a name='103'></a>method __DoOutput__

  - <a name='104'></a>method __close__

## <a name='subsection19'></a>Class  httpd::plugin\.local\_memchan

__Methods__

  - <a name='105'></a>method __local\_memchan__ *command* ?*args*?

  - <a name='106'></a>method __Connect\_Local__ *uuid* *sock* ?*args*?

    A modified connection method that passes simple GET request to an object and
    pulls data directly from the reply\_body data variable in the object Needed
    because memchan is bidirectional, and we can't seem to communicate that the
    server is one side of the link and the reply is another

# <a name='section4'></a>AUTHORS

Sean Woods

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *network* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

When proposing code changes, please provide *unified diffs*, i\.e the output of

Changes to embedded/md/tcllib/files/modules/imap4/imap4.md.

31
32
33
34
35
36
37


38
39
40
41
42
43
44
45
46
47
48
49
...
509
510
511
512
513
514
515




  - [REFERENCES](#section5)

  - [Bugs, Ideas, Feedback](#section6)

  - [See Also](#seealso)

  - [Keywords](#keywords)



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

package require Tcl 8\.5  
package require imap4 ?0\.5\.2?  

[__::imap4::open__ *hostname* ?*port*?](#1)  
[__::imap4::starttls__ *chan*](#2)  
[__::imap4::login__ *chan* *user* *pass*](#3)  
[__::imap4::folders__ *chan* ?*\-inline*? ?*mboxref*? ?*mboxname*?](#4)  
[__::imap4::select__ *chan* ?*mailbox*?](#5)  
[__::imap4::examine__ *chan* ?*mailbox*?](#6)  
................................................................................
# <a name='keywords'></a>KEYWORDS

[email](\.\./\.\./\.\./\.\./index\.md\#email), [imap](\.\./\.\./\.\./\.\./index\.md\#imap),
[internet](\.\./\.\./\.\./\.\./index\.md\#internet),
[mail](\.\./\.\./\.\./\.\./index\.md\#mail), [net](\.\./\.\./\.\./\.\./index\.md\#net),
[rfc3501](\.\./\.\./\.\./\.\./index\.md\#rfc3501),
[ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), [tls](\.\./\.\./\.\./\.\./index\.md\#tls)










>
>




|







 







>
>
>
>
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
...
511
512
513
514
515
516
517
518
519
520
521
  - [REFERENCES](#section5)

  - [Bugs, Ideas, Feedback](#section6)

  - [See Also](#seealso)

  - [Keywords](#keywords)

  - [Category](#category)

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

package require Tcl 8\.5  
package require imap4 ?0\.5\.3?  

[__::imap4::open__ *hostname* ?*port*?](#1)  
[__::imap4::starttls__ *chan*](#2)  
[__::imap4::login__ *chan* *user* *pass*](#3)  
[__::imap4::folders__ *chan* ?*\-inline*? ?*mboxref*? ?*mboxname*?](#4)  
[__::imap4::select__ *chan* ?*mailbox*?](#5)  
[__::imap4::examine__ *chan* ?*mailbox*?](#6)  
................................................................................
# <a name='keywords'></a>KEYWORDS

[email](\.\./\.\./\.\./\.\./index\.md\#email), [imap](\.\./\.\./\.\./\.\./index\.md\#imap),
[internet](\.\./\.\./\.\./\.\./index\.md\#internet),
[mail](\.\./\.\./\.\./\.\./index\.md\#mail), [net](\.\./\.\./\.\./\.\./index\.md\#net),
[rfc3501](\.\./\.\./\.\./\.\./index\.md\#rfc3501),
[ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), [tls](\.\./\.\./\.\./\.\./index\.md\#tls)

# <a name='category'></a>CATEGORY

Networking

Changes to embedded/md/tcllib/files/modules/jpeg/jpeg.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[//000000001]: # (jpeg \- JPEG image manipulation)
[//000000002]: # (Generated from file 'jpeg\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004\-2005, Code: Aaron Faupell <[email protected]\.sourceforge\.net>  
Copyright &copy; 2007, Code:  Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2004\-2009, Doc:  Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2011, Code: Pat Thoyts <[email protected]\.sourceforge\.net>)
[//000000004]: # (jpeg\(n\) 0\.5 tcllib "JPEG image manipulation")

<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>


|
|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[//000000001]: # (jpeg \- JPEG image manipulation)
[//000000002]: # (Generated from file 'jpeg\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004\-2005, Code: Aaron Faupell <[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2007, Code:  Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (Copyright &copy; 2004\-2009, Doc:  Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000006]: # (Copyright &copy; 2011, Code: Pat Thoyts <[email protected]\.sourceforge\.net>)
[//000000007]: # (jpeg\(n\) 0\.5 tcllib "JPEG image manipulation")

<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>

Changes to embedded/md/tcllib/files/modules/json/json.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (json \- JSON)
[//000000002]: # (Generated from file 'json\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2006 ActiveState Software Inc\.  
Copyright &copy; 2009 Thomas Maeder, Glue Software Engineering AG)
[//000000004]: # (json\(n\) 1\.3\.4 tcllib "JSON")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (json \- JSON)
[//000000002]: # (Generated from file 'json\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2006 ActiveState Software Inc\.)
[//000000004]: # (Copyright &copy; 2009 Thomas Maeder, Glue Software Engineering AG)
[//000000005]: # (json\(n\) 1\.3\.4 tcllib "JSON")

<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>

Changes to embedded/md/tcllib/files/modules/ldap/ldap.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (ldap \- LDAP client)
[//000000002]: # (Generated from file 'ldap\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2004 Jochen Loewer <[email protected]\.de>  
Copyright &copy; 2006 Michael Schlenker <[email protected]\.sourceforge\.net>)
[//000000004]: # (ldap\(n\) 1\.9\.2 tcllib "LDAP client")

<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>


|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (ldap \- LDAP client)
[//000000002]: # (Generated from file 'ldap\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2004 Jochen Loewer <[email protected]\.de>)
[//000000005]: # (Copyright &copy; 2006 Michael Schlenker <[email protected]\.sourceforge\.net>)
[//000000006]: # (ldap\(n\) 1\.9\.2 tcllib "LDAP client")

<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>

Changes to embedded/md/tcllib/files/modules/math/bignum.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::bignum \- Tcl Math Library)
[//000000002]: # (Generated from file 'bignum\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Salvatore Sanfilippo <antirez at invece dot org>  
Copyright &copy; 2004 Arjen Markus <arjenmarkus at users dot sourceforge dot net>)
[//000000004]: # (math::bignum\(n\) 3\.1 tcllib "Tcl Math Library")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::bignum \- Tcl Math Library)
[//000000002]: # (Generated from file 'bignum\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Salvatore Sanfilippo <antirez at invece dot org>)
[//000000004]: # (Copyright &copy; 2004 Arjen Markus <arjenmarkus at users dot sourceforge dot net>)
[//000000005]: # (math::bignum\(n\) 3\.1 tcllib "Tcl Math Library")

<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>

Changes to embedded/md/tcllib/files/modules/math/exact.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::exact \- Tcl Math Library)
[//000000002]: # (Generated from file 'exact\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2015 Kevin B\. Kenny <[email protected]\.org>
Redistribution permitted under the terms of the Open Publication License <http://www\.opencontent\.org/openpub/>)
[//000000004]: # (math::exact\(n\) 1\.0\.1 tcllib "Tcl Math Library")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::exact \- Tcl Math Library)
[//000000002]: # (Generated from file 'exact\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2015 Kevin B\. Kenny <[email protected]\.org>)
[//000000004]: # (Redistribution permitted under the terms of the Open Publication License <http://www\.opencontent\.org/openpub/>)
[//000000005]: # (math::exact\(n\) 1\.0\.1 tcllib "Tcl Math Library")

<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>

Changes to embedded/md/tcllib/files/modules/math/interpolate.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::interpolate \- Tcl Math Library)
[//000000002]: # (Generated from file 'interpolate\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Arjen Markus <[email protected]\.sourceforge\.net>  
Copyright &copy; 2004 Kevn B\. Kenny <[email protected]\.sourceforge\.net>)
[//000000004]: # (math::interpolate\(n\) 1\.1 tcllib "Tcl Math Library")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::interpolate \- Tcl Math Library)
[//000000002]: # (Generated from file 'interpolate\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Arjen Markus <[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2004 Kevn B\. Kenny <[email protected]\.sourceforge\.net>)
[//000000005]: # (math::interpolate\(n\) 1\.1 tcllib "Tcl Math Library")

<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>

Changes to embedded/md/tcllib/files/modules/math/linalg.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (math::linearalgebra \- Tcl Math Library)
[//000000002]: # (Generated from file 'linalg\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004\-2008 Arjen Markus <[email protected]\.sourceforge\.net>  
Copyright &copy; 2004 Ed Hume <http://www\.hume\.com/contact\.us\.htm>  
Copyright &copy; 2008 Michael Buadin <[email protected]\.sourceforge\.net>)
[//000000004]: # (math::linearalgebra\(n\) 1\.1\.5 tcllib "Tcl Math Library")

<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>


|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (math::linearalgebra \- Tcl Math Library)
[//000000002]: # (Generated from file 'linalg\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004\-2008 Arjen Markus <[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2004 Ed Hume <http://www\.hume\.com/contact\.us\.htm>)
[//000000005]: # (Copyright &copy; 2008 Michael Buadin <[email protected]\.sourceforge\.net>)
[//000000006]: # (math::linearalgebra\(n\) 1\.1\.5 tcllib "Tcl Math Library")

<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>

Changes to embedded/md/tcllib/files/modules/math/math_geometry.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[//000000001]: # (math::geometry \- Tcl Math Library)
[//000000002]: # (Generated from file 'math\_geometry\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2001 by Ideogramic ApS and other parties  
Copyright &copy; 2010 by Andreas Kupries  
Copyright &copy; 2010 by Kevin Kenny  
Copyright &copy; 2018 by Arjen Markus)
[//000000004]: # (math::geometry\(n\) 1\.3\.0 tcllib "Tcl Math Library")

<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>


|
|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[//000000001]: # (math::geometry \- Tcl Math Library)
[//000000002]: # (Generated from file 'math\_geometry\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2001 by Ideogramic ApS and other parties)
[//000000004]: # (Copyright &copy; 2010 by Andreas Kupries)
[//000000005]: # (Copyright &copy; 2010 by Kevin Kenny)
[//000000006]: # (Copyright &copy; 2018 by Arjen Markus)
[//000000007]: # (math::geometry\(n\) 1\.3\.0 tcllib "Tcl Math Library")

<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>

Changes to embedded/md/tcllib/files/modules/math/numtheory.md.

49
50
51
52
53
54
55

56
57
58
59
60
61
62
...
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
[__math::numtheory::legendre__ *a* *p*](#11)  
[__math::numtheory::jacobi__ *a* *b*](#12)  
[__math::numtheory::gcd__ *m* *n*](#13)  
[__math::numtheory::lcm__ *m* *n*](#14)  
[__math::numtheory::numberPrimesGauss__ *N*](#15)  
[__math::numtheory::numberPrimesLegendre__ *N*](#16)  
[__math::numtheory::numberPrimesLegendreModified__ *N*](#17)  


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

This package is for collecting various number\-theoretic operations, with a
slight bias to prime numbers\.

  - <a name='1'></a>__math::numtheory::isprime__ *N* ?*option* *value* \.\.\.?
................................................................................

  - <a name='15'></a>__math::numtheory::numberPrimesGauss__ *N*

    Estimate the number of primes according the formula by Gauss\.

      * integer *N* \(in\)

        Number in question

  - <a name='16'></a>__math::numtheory::numberPrimesLegendre__ *N*

    Estimate the number of primes according the formula by Legendre\.

      * integer *N* \(in\)

        Number in question

  - <a name='17'></a>__math::numtheory::numberPrimesLegendreModified__ *N*

    Estimate the number of primes according the modified formula by Legendre\.

      * integer *N* \(in\)

        Number in question














# <a name='section2'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *math :: numtheory* of the
[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report
any ideas for enhancements you may have for either package and/or documentation\.






>







 







|







|







|
>
>
>
>
>
>
>
>
>
>
>
>
>







49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
...
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
[__math::numtheory::legendre__ *a* *p*](#11)  
[__math::numtheory::jacobi__ *a* *b*](#12)  
[__math::numtheory::gcd__ *m* *n*](#13)  
[__math::numtheory::lcm__ *m* *n*](#14)  
[__math::numtheory::numberPrimesGauss__ *N*](#15)  
[__math::numtheory::numberPrimesLegendre__ *N*](#16)  
[__math::numtheory::numberPrimesLegendreModified__ *N*](#17)  
[__math::numtheory::differenceNumberPrimesLegendreModified__ *lower* *upper*](#18)  

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

This package is for collecting various number\-theoretic operations, with a
slight bias to prime numbers\.

  - <a name='1'></a>__math::numtheory::isprime__ *N* ?*option* *value* \.\.\.?
................................................................................

  - <a name='15'></a>__math::numtheory::numberPrimesGauss__ *N*

    Estimate the number of primes according the formula by Gauss\.

      * integer *N* \(in\)

        Number in question, should be larger than 0

  - <a name='16'></a>__math::numtheory::numberPrimesLegendre__ *N*

    Estimate the number of primes according the formula by Legendre\.

      * integer *N* \(in\)

        Number in question, should be larger than 0

  - <a name='17'></a>__math::numtheory::numberPrimesLegendreModified__ *N*

    Estimate the number of primes according the modified formula by Legendre\.

      * integer *N* \(in\)

        Number in question, should be larger than 0

  - <a name='18'></a>__math::numtheory::differenceNumberPrimesLegendreModified__ *lower* *upper*

    Estimate the number of primes between tow limits according the modified
    formula by Legendre\.

      * integer *lower* \(in\)

        Lower limit for the primes, should be larger than 0

      * integer *upper* \(in\)

        Upper limit for the primes, should be larger than 0

# <a name='section2'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *math :: numtheory* of the
[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report
any ideas for enhancements you may have for either package and/or documentation\.

Changes to embedded/md/tcllib/files/modules/math/optimize.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::optimize \- Tcl Math Library)
[//000000002]: # (Generated from file 'optimize\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Arjen Markus <[email protected]\.sourceforge\.net>  
Copyright &copy; 2004,2005 Kevn B\. Kenny <[email protected]\.sourceforge\.net>)
[//000000004]: # (math::optimize\(n\) 1\.0 tcllib "Tcl Math Library")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::optimize \- Tcl Math Library)
[//000000002]: # (Generated from file 'optimize\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004 Arjen Markus <[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2004,2005 Kevn B\. Kenny <[email protected]\.sourceforge\.net>)
[//000000005]: # (math::optimize\(n\) 1\.0 tcllib "Tcl Math Library")

<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>

Added embedded/md/tcllib/files/modules/math/quasirandom.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
[//000000001]: # (math::quasirandom \- Tcl Math Library)
[//000000002]: # (Generated from file 'quasirandom\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (math::quasirandom\(n\) 1 tcllib "Tcl Math Library")

<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

math::quasirandom \- Quasi\-random points for integration and Monte Carlo type
methods

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

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [COMMANDS](#section2)

  - [TODO](#section3)

  - [References](#section4)

  - [Keywords](#keywords)

  - [Category](#category)

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

package require Tcl 8\.5  
package require TclOO  
package require math::quasirandom 1  

[__::math::quasirandom::qrpoint create__ *NAME* *DIM* ?ARGS?](#1)  
[__gen next__](#2)  
[__gen set\-start__ *index*](#3)  
[__gen set\-evaluations__ *number*](#4)  
[__gen integral__ *func* *minmax* *args*](#5)  

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

In many applications pseudo\-random numbers and pseudo\-random points in a
\(limited\) sample space play an important role\. For instance in any type of Monte
Carlo simulation\. Pseudo\-random numbers, however, may be too random and as a
consequence a large number of data points is required to reduce the error or
fluctuation in the results to the desired value\.

Quasi\-random numbers can be used as an alternative: instead of "completely"
arbitrary points, points are generated that are diverse enough to cover the
entire sample space in a more or less uniform way\. As a consequence convergence
to the limit can be much faster, when such quasi\-random numbers are well\-chosen\.

The package defines a *[class](\.\./\.\./\.\./\.\./index\.md\#class)* "qrpoint" that
creates a command to generate quasi\-random points in 1, 2 or more dimensions\.
The command can either generate separate points, so that they can be used in a
user\-defined algorithm or use these points to calculate integrals of functions
defined over 1, 2 or more dimensions\. It also holds several other common
algorithms\. \(NOTE: these are not implemented yet\)

One particular characteristic of the generators is that there are no tuning
parameters involved, which makes the use particularly simple\.

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

A quasi\-random point generator is created using the *qrpoint* class:

  - <a name='1'></a>__::math::quasirandom::qrpoint create__ *NAME* *DIM* ?ARGS?

    This command takes the following arguments:

      * string *NAME*

        The name of the command to be created \(alternatively: the *new*
        subcommand will generate a unique name\)

      * integer/string *DIM*

        The number of dimensions or one of: "circle", "disk", "sphere" or "ball"

      * strings *ARGS*

        Zero or more key\-value pairs\. The supported options are:

          + *\-start index*: The index for the next point to be generated
            \(default: 1\)

          + *\-evaluations number*: The number of evaluations to be used by
            default \(default: 100\)

The points that are returned lie in the hyperblock \[0,1\[^n \(n the number of
dimensions\) or on the unit circle, within the unit disk, on the unit sphere or
within the unit ball\.

Each generator supports the following subcommands:

  - <a name='2'></a>__gen next__

    Return the coordinates of the next quasi\-random point

  - <a name='3'></a>__gen set\-start__ *index*

    Reset the index for the next quasi\-random point\. This is useful to control
    which list of points is returned\. Returns the new or the current value, if
    no value is given\.

  - <a name='4'></a>__gen set\-evaluations__ *number*

    Reset the default number of evaluations in compound algorithms\. Note that
    the actual number is the smallest 4\-fold larger or equal to the given
    number\. \(The 4\-fold plays a role in the detailed integration routine\.\)

  - <a name='5'></a>__gen integral__ *func* *minmax* *args*

    Calculate the integral of the given function over the block \(or the circle,
    sphere etc\.\)

      * string *func*

        The name of the function to be integrated

      * list *minmax*

        List of pairs of minimum and maximum coordinates\. This can be used to
        map the quasi\-random coordinates to the desired hyper\-block\.

        If the space is a circle, disk etc\. then this argument should be a
        single value, the radius\. The circle, disk, etc\. is centred at the
        origin\. If this is not what is required, then a coordinate
        transformation should be made within the function\.

      * strings *args*

        Zero or more key\-value pairs\. The following options are supported:

          + *\-evaluations number*: The number of evaluations to be used\. If
            not specified use the default of the generator object\.

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

Implement other algorithms and variants

Implement more unit tests\.

Comparison to pseudo\-random numbers for integration\.

# <a name='section4'></a>References

Various algorithms exist for generating quasi\-random numbers\. The generators
created in this package are based on:
[http://extremelearning\.com\.au/unreasonable\-effectiveness\-of\-quasirandom\-sequences/](http://extremelearning\.com\.au/unreasonable\-effectiveness\-of\-quasirandom\-sequences/)

# <a name='keywords'></a>KEYWORDS

[mathematics](\.\./\.\./\.\./\.\./index\.md\#mathematics),
[quasi\-random](\.\./\.\./\.\./\.\./index\.md\#quasi\_random)

# <a name='category'></a>CATEGORY

Mathematics

Changes to embedded/md/tcllib/files/modules/math/symdiff.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::calculus::symdiff \- Symbolic differentiation for Tcl)
[//000000002]: # (Generated from file 'symdiff\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2010 by Kevin B\. Kenny <[email protected]\.org>
Redistribution permitted under the terms of the Open Publication License <http://www\.opencontent\.org/openpub/>)
[//000000004]: # (math::calculus::symdiff\(n\) 1\.0\.1 tcllib "Symbolic differentiation for Tcl")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (math::calculus::symdiff \- Symbolic differentiation for Tcl)
[//000000002]: # (Generated from file 'symdiff\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2010 by Kevin B\. Kenny <[email protected]\.org>)
[//000000004]: # (Redistribution permitted under the terms of the Open Publication License <http://www\.opencontent\.org/openpub/>)
[//000000005]: # (math::calculus::symdiff\(n\) 1\.0\.1 tcllib "Symbolic differentiation for Tcl")

<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>

Changes to embedded/md/tcllib/files/modules/mime/mime.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
[//000000001]: # (mime \- Mime)
[//000000002]: # (Generated from file 'mime\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 1999\-2000 Marshall T\. Rose)
[//000000004]: # (mime\(n\) 1\.6 tcllib "Mime")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require mime ?1\.6?  

[__::mime::initialize__ ?__\-canonical__ *type/subtype* ?__\-param__ \{*key value*\}\.\.\.? ?__\-encoding__ *value*? ?__\-header__ \{*key value*\}\.\.\.?? \(__\-file__ *name* &#124; __\-string__ *value* &#124; __\-parts__ \{*token1* \.\.\. *tokenN*\}\)](#1)  
[__::mime::finalize__ *token* ?__\-subordinates__ __all__ &#124; __dynamic__ &#124; __none__?](#2)  
[__::mime::getproperty__ *token* ?*property* &#124; __\-names__?](#3)  
[__::mime::getheader__ *token* ?*key* &#124; __\-names__?](#4)  
[__::mime::setheader__ *token* *key value* ?__\-mode__ __write__ &#124; __append__ &#124; __delete__?](#5)  
[__::mime::getbody__ *token* ?__\-decode__? ?__\-command__ *callback* ?__\-blocksize__ *octets*??](#6)  



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
..
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
[//000000001]: # (mime \- Mime)
[//000000002]: # (Generated from file 'mime\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 1999\-2000 Marshall T\. Rose)
[//000000004]: # (mime\(n\) 1\.6\.1 tcllib "Mime")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require mime ?1\.6\.1?  

[__::mime::initialize__ ?__\-canonical__ *type/subtype* ?__\-param__ \{*key value*\}\.\.\.? ?__\-encoding__ *value*? ?__\-header__ \{*key value*\}\.\.\.?? \(__\-file__ *name* &#124; __\-string__ *value* &#124; __\-parts__ \{*token1* \.\.\. *tokenN*\}\)](#1)  
[__::mime::finalize__ *token* ?__\-subordinates__ __all__ &#124; __dynamic__ &#124; __none__?](#2)  
[__::mime::getproperty__ *token* ?*property* &#124; __\-names__?](#3)  
[__::mime::getheader__ *token* ?*key* &#124; __\-names__?](#4)  
[__::mime::setheader__ *token* *key value* ?__\-mode__ __write__ &#124; __append__ &#124; __delete__?](#5)  
[__::mime::getbody__ *token* ?__\-decode__? ?__\-command__ *callback* ?__\-blocksize__ *octets*??](#6)  

Changes to embedded/md/tcllib/files/modules/mime/smtp.md.

179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
# <a name='section3'></a>EXAMPLE

    proc send_simple_message {recipient email_server subject body} {
        package require smtp
        package require mime

        set token [mime::initialize -canonical text/plain \\
    	-string $body]
        mime::setheader $token Subject $subject
        smtp::sendmessage $token \\
    	-recipients $recipient -servers $email_server
        mime::finalize $token
    }

    send_simple_message [email protected] localhost \\
        "This is the subject." "This is the message."

# <a name='section4'></a>TLS Security Considerations

This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to
handle the security for __https__ urls and other socket connections\.







|


|




|







179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
# <a name='section3'></a>EXAMPLE

    proc send_simple_message {recipient email_server subject body} {
        package require smtp
        package require mime

        set token [mime::initialize -canonical text/plain \
    	-string $body]
        mime::setheader $token Subject $subject
        smtp::sendmessage $token \
    	-recipients $recipient -servers $email_server
        mime::finalize $token
    }

    send_simple_message [email protected] localhost \
        "This is the subject." "This is the message."

# <a name='section4'></a>TLS Security Considerations

This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to
handle the security for __https__ urls and other socket connections\.

Changes to embedded/md/tcllib/files/modules/namespacex/namespacex.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (namespacex \- Namespace utility commands)
[//000000002]: # (Generated from file 'namespacex\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 200? Neil Madden \(http://wiki\.tcl\.tk/12790\)  
Copyright &copy; 200? Various \(http://wiki\.tcl\.tk/1489\)  
Copyright &copy; 2010 Documentation, Andreas Kupries)
[//000000004]: # (namespacex\(n\) 0\.2 tcllib "Namespace utility commands")

<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>


|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (namespacex \- Namespace utility commands)
[//000000002]: # (Generated from file 'namespacex\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 200? Neil Madden \(http://wiki\.tcl\.tk/12790\))
[//000000004]: # (Copyright &copy; 200? Various \(http://wiki\.tcl\.tk/1489\))
[//000000005]: # (Copyright &copy; 2010 Documentation, Andreas Kupries)
[//000000006]: # (namespacex\(n\) 0\.2 tcllib "Namespace utility commands")

<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>

Changes to embedded/md/tcllib/files/modules/oauth/oauth.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
[//000000001]: # (oauth \- oauth)
[//000000002]: # (Generated from file 'oauth\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2014 Javi P\. <[email protected]\.es>)
[//000000004]: # (oauth\(n\) 1\.0\.2 tcllib "oauth")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require oauth ?1\.0\.2?  

[__::oauth::config__](#1)  
[__::oauth::config__ ?*options*\.\.\.?](#2)  
[__::oauth::header__ *baseURL* ?*postQuery*?](#3)  
[__::oauth::query__ *baseURL* ?*postQuery*?](#4)  

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



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
..
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
[//000000001]: # (oauth \- oauth)
[//000000002]: # (Generated from file 'oauth\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2014 Javi P\. <[email protected]\.es>)
[//000000004]: # (oauth\(n\) 1\.0\.3 tcllib "oauth")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require oauth ?1\.0\.3?  

[__::oauth::config__](#1)  
[__::oauth::config__ ?*options*\.\.\.?](#2)  
[__::oauth::header__ *baseURL* ?*postQuery*?](#3)  
[__::oauth::query__ *baseURL* ?*postQuery*?](#4)  

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

Changes to embedded/md/tcllib/files/modules/pki/pki.md.

201
202
203
204
205
206
207




208
209
210
211
212
213
214
    to specify as a boolean value whether or not we can be used a certificate
    authority \(CA\)\. The *caDepth* argument indicates how many children CAs can
    be children of this CA in a depth\-wise fashion\. A value of "0" for the
    *caDepth* argument means that this CA cannot sign a CA certificate and
    have the result be valid\. A value of "\-1" indicates infinite depth\.

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





# <a name='section4'></a>REFERENCES

# <a name='section5'></a>AUTHORS

Roy Keene







>
>
>
>







201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
    to specify as a boolean value whether or not we can be used a certificate
    authority \(CA\)\. The *caDepth* argument indicates how many children CAs can
    be children of this CA in a depth\-wise fashion\. A value of "0" for the
    *caDepth* argument means that this CA cannot sign a CA certificate and
    have the result be valid\. A value of "\-1" indicates infinite depth\.

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





# <a name='section4'></a>REFERENCES

# <a name='section5'></a>AUTHORS

Roy Keene

Changes to embedded/md/tcllib/files/modules/png/png.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (png \- Image manipulation)
[//000000002]: # (Generated from file 'png\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004, Code: Aaron Faupell <[email protected]\.sourceforge\.net>  
Copyright &copy; 2004, Doc:  Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (png\(n\) 0\.3 tcllib "Image manipulation")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (png \- Image manipulation)
[//000000002]: # (Generated from file 'png\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2004, Code: Aaron Faupell <[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2004, Doc:  Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (png\(n\) 0\.3 tcllib "Image manipulation")

<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>

Changes to embedded/md/tcllib/files/modules/pop3/pop3.md.

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
suitable for POP3 servers which expect SSL connections only\. These will
generally be listening on port 995\.

    package require tls
    tls::init -cafile /path/to/ca/cert -keyfile ...

    # Create secured pop3 channel
    pop3::open -socketcmd tls::socket \\
    	$thehost $theuser $thepassword

    ...

The second method, option __\-stls__, will connect to the standard POP3 port
and then perform an STARTTLS handshake\. This will only work for POP3 servers
which have this capability\. The package will confirm that the server supports
................................................................................
STARTTLS and the handshake was performed correctly before proceeding with
authentication\.

    package require tls
    tls::init -cafile /path/to/ca/cert -keyfile ...

    # Create secured pop3 channel
    pop3::open -stls 1 \\
    	$thehost $theuser $thepassword

    ...

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and






|







 







|







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
suitable for POP3 servers which expect SSL connections only\. These will
generally be listening on port 995\.

    package require tls
    tls::init -cafile /path/to/ca/cert -keyfile ...

    # Create secured pop3 channel
    pop3::open -socketcmd tls::socket \
    	$thehost $theuser $thepassword

    ...

The second method, option __\-stls__, will connect to the standard POP3 port
and then perform an STARTTLS handshake\. This will only work for POP3 servers
which have this capability\. The package will confirm that the server supports
................................................................................
STARTTLS and the handshake was performed correctly before proceeding with
authentication\.

    package require tls
    tls::init -cafile /path/to/ca/cert -keyfile ...

    # Create secured pop3 channel
    pop3::open -stls 1 \
    	$thehost $theuser $thepassword

    ...

# <a name='section5'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and

Changes to embedded/md/tcllib/files/modules/pop3d/pop3d.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
...
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
[//000000001]: # (pop3d \- Tcl POP3 Server Package)
[//000000002]: # (Generated from file 'pop3d\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2002\-2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2005 Reinhard Max  <[email protected]\.de>)
[//000000004]: # (pop3d\(n\) 1\.1\.0 tcllib "Tcl POP3 Server Package")

<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>
................................................................................

The option __\-socket__ \(see [Options](#section2)\) enables users of the
package to override how the server opens its listening socket\. The envisioned
main use is the specification of the __tls::socket__ command, see package
__[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__, to secure the communication\.

    package require tls
    tls::init \\
    	...

    pop3d::new S -socket tls::socket
    ...

# <a name='section6'></a>References



|
|
|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
13
...
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
[//000000001]: # (pop3d \- Tcl POP3 Server Package)
[//000000002]: # (Generated from file 'pop3d\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2002\-2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2005 Reinhard Max  <[email protected]\.de>)
[//000000005]: # (pop3d\(n\) 1\.1\.0 tcllib "Tcl POP3 Server Package")

<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>
................................................................................

The option __\-socket__ \(see [Options](#section2)\) enables users of the
package to override how the server opens its listening socket\. The envisioned
main use is the specification of the __tls::socket__ command, see package
__[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__, to secure the communication\.

    package require tls
    tls::init \
    	...

    pop3d::new S -socket tls::socket
    ...

# <a name='section6'></a>References

Changes to embedded/md/tcllib/files/modules/practcl/practcl.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
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
[//000000001]: # (practcl \- The The Proper Rational API for C to Tool Command Language Module)
[//000000002]: # (Generated from file 'practcl\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2016\-2018 Sean Woods <[email protected]\.com>)
[//000000004]: # (practcl\(n\) 0\.11 tcllib "The The Proper Rational API for C to Tool Command Language Module")

<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>
................................................................................

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [COMMANDS](#section2)

  - [Bugs, Ideas, Feedback](#section3)

  - [Keywords](#keywords)

  - [Category](#category)

  - [Copyright](#copyright)

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

package require TclOO 1\.0  
package require practcl 0\.11  

[__CPUTS__ *varname* *body* ?*body*\.\.\.?](#1)  
[__practcl::\_isdirectory__ *path*](#2)  
[__practcl::object__ *parent* ?*keyvaluelist*?](#3)  
[__practcl::library__ ?*keyvaluelist*?](#4)  
[__practcl::exe__ ?*keyvaluelist*?](#5)  
[__practcl::product__ *parent* ?*keyvaluelist*?](#6)  
[__practcl::cheader__ *parent* ?*keyvaluelist*?](#7)  
[__practcl::csource__ *parent* ?*keyvaluelist*?](#8)  
[__practcl::module__ *parent* ?*keyvaluelist*?](#9)  
[__practcl::submodule__ *parent* ?*keyvaluelist*?](#10)  

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

The Practcl module is a tool for integrating large modules for C API Tcl code
that requires custom Tcl types and TclOO objects\.

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

  - <a name='1'></a>__CPUTS__ *varname* *body* ?*body*\.\.\.?

    Appends blocks of text to a buffer\. This command tries to reduce the number
    of line breaks between bodies\.

  - <a name='2'></a>__practcl::\_isdirectory__ *path*

    Returns true if *path* is a directory, using the test

  - <a name='3'></a>__practcl::object__ *parent* ?*keyvaluelist*?

    A generic Practcl object

  - <a name='4'></a>__practcl::library__ ?*keyvaluelist*?

    A Practcl object representing a library container

  - <a name='5'></a>__practcl::exe__ ?*keyvaluelist*?

    A Practcl object representing a wrapped executable

  - <a name='6'></a>__practcl::product__ *parent* ?*keyvaluelist*?

    A Practcl object representing a compiled product

  - <a name='7'></a>__practcl::cheader__ *parent* ?*keyvaluelist*?

    A Practcl object representing an externally generated c header

  - <a name='8'></a>__practcl::csource__ *parent* ?*keyvaluelist*?

    A Practcl object representing an externally generated c source file

  - <a name='9'></a>__practcl::module__ *parent* ?*keyvaluelist*?

    A Practcl object representing a dynamically generated C/H/Tcl suite

  - <a name='10'></a>__practcl::submodule__ *parent* ?*keyvaluelist*?

    A Practcl object representing a dynamically generated C/H/Tcl suite,
    subordinate to a module

# <a name='section3'></a>Bugs, Ideas, Feedback












































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *practcl* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

When proposing code changes, please provide *unified diffs*, i\.e the output of



|







 







|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







1
2
3
4
5
6
7
8
9
10
11
12
..
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
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
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
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
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
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
[//000000001]: # (practcl \- The The Proper Rational API for C to Tool Command Language Module)
[//000000002]: # (Generated from file 'practcl\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2016\-2018 Sean Woods <[email protected]\.com>)
[//000000004]: # (practcl\(n\) 0\.16\.3 tcllib "The The Proper Rational API for C to Tool Command Language Module")

<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>
................................................................................

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [Commands](#section2)

  - [Classes](#section3)

      - [Class practcl::doctool](#subsection1)

      - [Class practcl::metaclass](#subsection2)

      - [Class practcl::toolset](#subsection3)

      - [Class practcl::toolset\.gcc](#subsection4)

      - [Class practcl::toolset\.msvc](#subsection5)

      - [Class practcl::make\_obj](#subsection6)

      - [Class practcl::object](#subsection7)

      - [Class practcl::dynamic](#subsection8)

      - [Class practcl::product](#subsection9)

      - [Class practcl::product\.cheader](#subsection10)

      - [Class practcl::product\.csource](#subsection11)

      - [Class practcl::product\.clibrary](#subsection12)

      - [Class practcl::product\.dynamic](#subsection13)

      - [Class practcl::product\.critcl](#subsection14)

      - [Class practcl::module](#subsection15)

      - [Class practcl::project](#subsection16)

      - [Class practcl::library](#subsection17)

      - [Class practcl::tclkit](#subsection18)

      - [Class practcl::distribution](#subsection19)

      - [Class practcl::distribution\.snapshot](#subsection20)

      - [Class practcl::distribution\.fossil](#subsection21)

      - [Class practcl::distribution\.git](#subsection22)

      - [Class practcl::subproject](#subsection23)

      - [Class practcl::subproject\.source](#subsection24)

      - [Class practcl::subproject\.teapot](#subsection25)

      - [Class practcl::subproject\.kettle](#subsection26)

      - [Class practcl::subproject\.critcl](#subsection27)

      - [Class practcl::subproject\.sak](#subsection28)

      - [Class practcl::subproject\.practcl](#subsection29)

      - [Class practcl::subproject\.binary](#subsection30)

      - [Class practcl::subproject\.tea](#subsection31)

      - [Class practcl::subproject\.library](#subsection32)

      - [Class practcl::subproject\.external](#subsection33)

      - [Class practcl::subproject\.core](#subsection34)

  - [Bugs, Ideas, Feedback](#section4)

  - [Keywords](#keywords)

  - [Category](#category)

  - [Copyright](#copyright)

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

package require TclOO 1\.0  

[proc __practcl::cat__ *fname*](#1)  
[proc __practcl::docstrip__ *text*](#2)  
[proc __putb__ ?*map*? *text*](#3)  
[proc __[Proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *name* *arglist* *body*](#4)  
[proc __noop__ ?*args*?](#5)  
[proc __practcl::debug__ ?*args*?](#6)  
[proc __practcl::doexec__ ?*args*?](#7)  
[proc __practcl::doexec\_in__ *path* ?*args*?](#8)  
[proc __practcl::dotclexec__ ?*args*?](#9)  
[proc __practcl::domake__ *path* ?*args*?](#10)  
[proc __practcl::domake\.tcl__ *path* ?*args*?](#11)  
[proc __practcl::fossil__ *path* ?*args*?](#12)  
[proc __practcl::fossil\_status__ *dir*](#13)  
[proc __practcl::os__](#14)  
[proc __practcl::mkzip__ *exename* *barekit* *vfspath*](#15)  
[proc __practcl::sort\_dict__ *list*](#16)  
[proc __practcl::local\_os__](#17)  
[proc __practcl::config\.tcl__ *path*](#18)  
[proc __practcl::read\_configuration__ *path*](#19)  
[proc __practcl::tcllib\_require__ *pkg* ?*args*?](#20)  
[proc __practcl::platform::tcl\_core\_options__ *os*](#21)  
[proc __practcl::platform::tk\_core\_options__ *os*](#22)  
[proc __practcl::read\_rc\_file__ *filename* ?*localdat* ____?](#23)  
[proc __practcl::read\_sh\_subst__ *line* *info*](#24)  
[proc __practcl::read\_sh\_file__ *filename* ?*localdat* ____?](#25)  
[proc __practcl::read\_Config\.sh__ *filename*](#26)  
[proc __practcl::read\_Makefile__ *filename*](#27)  
[proc __practcl::cputs__ *varname* ?*args*?](#28)  
[proc __practcl::tcl\_to\_c__ *body*](#29)  
[proc __practcl::\_tagblock__ *text* ?*style* __tcl__? ?*note* ____?](#30)  
[proc __practcl::de\_shell__ *data*](#31)  
[proc __practcl::grep__ *pattern* ?*files* ____?](#32)  
[proc __practcl::file\_lexnormalize__ *sp*](#33)  
[proc __practcl::file\_relative__ *base* *dst*](#34)  
[proc __practcl::findByPattern__ *basedir* *patterns*](#35)  
[proc __practcl::log__ *fname* *comment*](#36)  
[proc __practcl::\_pkgindex\_simpleIndex__ *path*](#37)  
[proc __practcl::\_pkgindex\_directory__ *path*](#38)  
[proc __practcl::\_pkgindex\_path\_subdir__ *path*](#39)  
[proc __practcl::pkgindex\_path__ ?*args*?](#40)  
[proc __practcl::installDir__ *d1* *d2*](#41)  
[proc __practcl::copyDir__ *d1* *d2* ?*toplevel* __1__?](#42)  
[proc __practcl::buildModule__ *modpath*](#43)  
[proc __practcl::installModule__ *modpath* *DEST*](#44)  
[proc __practcl::trigger__ ?*args*?](#45)  
[proc __practcl::depends__ ?*args*?](#46)  
[proc __practcl::target__ *name* *info* ?*action* ____?](#47)  
[method __constructor__](#48)  
[method __argspec__ *argspec*](#49)  
[method __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *block*](#50)  
[method __keyword\.Annotation__ *resultvar* *commentblock* *type* *name* *body*](#51)  
[method __keyword\.Class__ *resultvar* *commentblock* *name* *body*](#52)  
[method __keyword\.class__ *resultvar* *commentblock* *name* *body*](#53)  
[method __keyword\.Class\_Method__ *resultvar* *commentblock* *name* ?*args*?](#54)  
[method __keyword\.method__ *resultvar* *commentblock* *name* ?*args*?](#55)  
[method __keyword\.proc__ *commentblock* *name* *argspec*](#56)  
[method __reset__](#57)  
[method __Main__](#58)  
[method __section\.method__ *keyword* *method* *minfo*](#59)  
[method __section\.annotation__ *type* *name* *iinfo*](#60)  
[method __section\.class__ *class\_name* *class\_info*](#61)  
[method __section\.command__ *procinfo*](#62)  
[method __[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ ?__header *value*__? ?__footer *value*__? ?__authors *list*__?](#63)  
[method __scan\_text__ *text*](#64)  
[method __scan\_file__ *filename*](#65)  
[method __\_MorphPatterns__](#66)  
[method __[define](\.\./\.\./\.\./\.\./index\.md\#define)__ *submethod* ?*args*?](#67)  
[method __graft__ ?*args*?](#68)  
[method __initialize__](#69)  
[method __link__ *command* ?*args*?](#70)  
[method __morph__ *classname*](#71)  
[method __script__ *script*](#72)  
[method __select__](#73)  
[method __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ *filename*](#74)  
[classmethod __select__ *object*](#75)  
[method __config\.sh__](#76)  
[method __BuildDir__ *PWD*](#77)  
[method __MakeDir__ *srcdir*](#78)  
[method __read\_configuration__](#79)  
[method __build\-cflags__ *PROJECT* *DEFS* *namevar* *versionvar* *defsvar*](#80)  
[method __critcl__ ?*args*?](#81)  
[method __Autoconf__](#82)  
[method __BuildDir__ *PWD*](#83)  
[method __ConfigureOpts__](#84)  
[method __MakeDir__ *srcdir*](#85)  
[method __make \{\} autodetect__](#86)  
[method __make \{\} clean__](#87)  
[method __make \{\} compile__](#88)  
[method __make \{\} install__ *DEST*](#89)  
[method __build\-compile\-sources__ *PROJECT* *COMPILE* *CPPCOMPILE* *INCLUDES*](#90)  
[method __build\-Makefile__ *path* *PROJECT*](#91)  
[method __build\-library__ *outfile* *PROJECT*](#92)  
[method __build\-tclsh__ *outfile* *PROJECT* ?*path* __auto__?](#93)  
[method __BuildDir__ *PWD*](#94)  
[method __make \{\} autodetect__](#95)  
[method __make \{\} clean__](#96)  
[method __make \{\} compile__](#97)  
[method __make \{\} install__ *DEST*](#98)  
[method __MakeDir__ *srcdir*](#99)  
[method __NmakeOpts__](#100)  
[method __constructor__ *module\_object* *name* *info* ?*action\_body* ____?](#101)  
[method __[do](\.\./\.\./\.\./\.\./index\.md\#do)__](#102)  
[method __check__](#103)  
[method __output__](#104)  
[method __reset__](#105)  
[method __triggers__](#106)  
[method __constructor__ *parent* ?*args*?](#107)  
[method __child__ *method*](#108)  
[method __go__](#109)  
[method __cstructure__ *name* *definition* ?*argdat* ____?](#110)  
[method __include__ *header*](#111)  
[method __include\_dir__ ?*args*?](#112)  
[method __include\_directory__ ?*args*?](#113)  
[method __c\_header__ *body*](#114)  
[method __c\_code__ *body*](#115)  
[method __c\_function__ *header* *body* ?*info* ____?](#116)  
[method __c\_tcloomethod__ *name* *body* ?*arginfo* ____?](#117)  
[method __cmethod__ *name* *body* ?*arginfo* ____?](#118)  
[method __c\_tclproc\_nspace__ *nspace*](#119)  
[method __c\_tclcmd__ *name* *body* ?*arginfo* ____?](#120)  
[method __c\_tclproc\_raw__ *name* *body* ?*arginfo* ____?](#121)  
[method __tcltype__ *name* *argdat*](#122)  
[method __project\-compile\-products__](#123)  
[method __implement__ *path*](#124)  
[method __initialize__](#125)  
[method __linktype__](#126)  
[method __generate\-cfile\-constant__](#127)  
[method __generate\-cfile\-header__](#128)  
[method __generate\-cfile\-tclapi__](#129)  
[method __generate\-loader\-module__](#130)  
[method __Collate\_Source__ *CWD*](#131)  
[method __select__](#132)  
[classmethod __select__ *object*](#133)  
[method __code__ *section* *body*](#134)  
[method __Collate\_Source__ *CWD*](#135)  
[method __project\-compile\-products__](#136)  
[method __generate\-debug__ ?*spaces* ____?](#137)  
[method __generate\-cfile\-constant__](#138)  
[method __generate\-cfile\-public\-structure__](#139)  
[method __generate\-cfile\-header__](#140)  
[method __generate\-cfile\-global__](#141)  
[method __generate\-cfile\-private\-typedef__](#142)  
[method __generate\-cfile\-private\-structure__](#143)  
[method __generate\-cfile\-functions__](#144)  
[method __generate\-cfile\-tclapi__](#145)  
[method __generate\-hfile\-public\-define__](#146)  
[method __generate\-hfile\-public\-macro__](#147)  
[method __generate\-hfile\-public\-typedef__](#148)  
[method __generate\-hfile\-public\-structure__](#149)  
[method __generate\-hfile\-public\-headers__](#150)  
[method __generate\-hfile\-public\-function__](#151)  
[method __generate\-hfile\-public\-includes__](#152)  
[method __generate\-hfile\-public\-verbatim__](#153)  
[method __generate\-loader\-external__](#154)  
[method __generate\-loader\-module__](#155)  
[method __generate\-stub\-function__](#156)  
[method __IncludeAdd__ *headervar* ?*args*?](#157)  
[method __generate\-tcl\-loader__](#158)  
[method __generate\-tcl\-pre__](#159)  
[method __generate\-tcl\-post__](#160)  
[method __linktype__](#161)  
[method __Ofile__ *filename*](#162)  
[method __project\-static\-packages__](#163)  
[method __toolset\-include\-directory__](#164)  
[method __target__ *method* ?*args*?](#165)  
[method __project\-compile\-products__](#166)  
[method __generate\-loader\-module__](#167)  
[method __project\-compile\-products__](#168)  
[method __linker\-products__ *configdict*](#169)  
[method __initialize__](#170)  
[variable __make\_object__](#171)  
[method __\_MorphPatterns__](#172)  
[method __add__ ?*args*?](#173)  
[method __install\-headers__ ?*args*?](#174)  
[method __make \{\} \_preamble__](#175)  
[method __make \{\} pkginfo__](#176)  
[method __make \{\} objects__](#177)  
[method __make \{\} object__ *name*](#178)  
[method __make \{\} reset__](#179)  
[method __make \{\} trigger__ ?*args*?](#180)  
[method __make \{\} depends__ ?*args*?](#181)  
[method __make \{\} filename__ *name*](#182)  
[method __make \{\} target__ *name* *Info* *body*](#183)  
[method __make \{\} todo__](#184)  
[method __make \{\} do__](#185)  
[method __child__ *which*](#186)  
[method __generate\-c__](#187)  
[method __generate\-h__](#188)  
[method __generate\-loader__](#189)  
[method __initialize__](#190)  
[method __implement__ *path*](#191)  
[method __linktype__](#192)  
[method __\_MorphPatterns__](#193)  
[method __constructor__ ?*args*?](#194)  
[method __add\_object__ *object*](#195)  
[method __add\_project__ *pkg* *info* ?*oodefine* ____?](#196)  
[method __add\_tool__ *pkg* *info* ?*oodefine* ____?](#197)  
[method __build\-tclcore__](#198)  
[method __child__ *which*](#199)  
[method __linktype__](#200)  
[method __project__ *pkg* ?*args*?](#201)  
[method __tclcore__](#202)  
[method __tkcore__](#203)  
[method __[tool](\.\./tool/tool\.md)__ *pkg* ?*args*?](#204)  
[method __clean__ *PATH*](#205)  
[method __project\-compile\-products__](#206)  
[method __go__](#207)  
[method __generate\-decls__ *pkgname* *path*](#208)  
[method __implement__ *path*](#209)  
[method __generate\-make__ *path*](#210)  
[method __linktype__](#211)  
[method __package\-ifneeded__ ?*args*?](#212)  
[method __shared\_library__ ?*filename* ____?](#213)  
[method __static\_library__ ?*filename* ____?](#214)  
[method __build\-tclkit\_main__ *PROJECT* *PKG\_OBJS*](#215)  
[method __Collate\_Source__ *CWD*](#216)  
[method __wrap__ *PWD* *exename* *vfspath* ?*args*?](#217)  
[classmethod __Sandbox__ *object*](#218)  
[classmethod __select__ *object*](#219)  
[classmethod __claim\_option__](#220)  
[classmethod __claim\_object__ *object*](#221)  
[classmethod __claim\_path__ *path*](#222)  
[method __scm\_info__](#223)  
[method __DistroMixIn__](#224)  
[method __Sandbox__](#225)  
[method __SrcDir__](#226)  
[method __ScmTag__](#227)  
[method __ScmClone__](#228)  
[method __ScmUnpack__](#229)  
[method __ScmUpdate__](#230)  
[method __Unpack__](#231)  
[classmethod __claim\_object__ *object*](#232)  
[classmethod __claim\_option__](#233)  
[classmethod __claim\_path__ *path*](#234)  
[method __ScmUnpack__](#235)  
[classmethod __claim\_object__ *obj*](#236)  
[classmethod __claim\_option__](#237)  
[classmethod __claim\_path__ *path*](#238)  
[method __scm\_info__](#239)  
[method __ScmClone__](#240)  
[method __ScmTag__](#241)  
[method __ScmUnpack__](#242)  
[method __ScmUpdate__](#243)  
[classmethod __claim\_object__ *obj*](#244)  
[classmethod __claim\_option__](#245)  
[classmethod __claim\_path__ *path*](#246)  
[method __ScmTag__](#247)  
[method __ScmUnpack__](#248)  
[method __ScmUpdate__](#249)  
[method __\_MorphPatterns__](#250)  
[method __BuildDir__ *PWD*](#251)  
[method __child__ *which*](#252)  
[method __compile__](#253)  
[method __go__](#254)  
[method __install__ ?*args*?](#255)  
[method __linktype__](#256)  
[method __linker\-products__ *configdict*](#257)  
[method __linker\-external__ *configdict*](#258)  
[method __linker\-extra__ *configdict*](#259)  
[method __env\-bootstrap__](#260)  
[method __env\-exec__](#261)  
[method __env\-install__](#262)  
[method __env\-load__](#263)  
[method __env\-present__](#264)  
[method __sources__](#265)  
[method __[update](\.\./\.\./\.\./\.\./index\.md\#update)__](#266)  
[method __unpack__](#267)  
[method __env\-bootstrap__](#268)  
[method __env\-present__](#269)  
[method __linktype__](#270)  
[method __env\-bootstrap__](#271)  
[method __env\-install__](#272)  
[method __env\-present__](#273)  
[method __install__ *DEST*](#274)  
[method __kettle__ *path* ?*args*?](#275)  
[method __install__ *DEST*](#276)  
[method __install__ *DEST*](#277)  
[method __env\-bootstrap__](#278)  
[method __env\-install__](#279)  
[method __env\-present__](#280)  
[method __install__ *DEST*](#281)  
[method __install\-module__ *DEST* ?*args*?](#282)  
[method __env\-bootstrap__](#283)  
[method __env\-install__](#284)  
[method __install__ *DEST*](#285)  
[method __install\-module__ *DEST* ?*args*?](#286)  
[method __clean__](#287)  
[method __env\-install__](#288)  
[method __project\-compile\-products__](#289)  
[method __ComputeInstall__](#290)  
[method __go__](#291)  
[method __linker\-products__ *configdict*](#292)  
[method __project\-static\-packages__](#293)  
[method __BuildDir__ *PWD*](#294)  
[method __compile__](#295)  
[method __Configure__](#296)  
[method __install__ *DEST*](#297)  
[method __install__ *DEST*](#298)  
[method __install__ *DEST*](#299)  
[method __env\-bootstrap__](#300)  
[method __env\-present__](#301)  
[method __env\-install__](#302)  
[method __go__](#303)  
[method __linktype__](#304)  

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

The Practcl module is a tool for integrating large modules for C API Tcl code
that requires custom Tcl types and TclOO objects\.

The concept with Practcl is that is a single file package that can assist any
tcl based project with distribution, compilation, linking, VFS preparation,
executable assembly, and installation\. Practcl also allows one project to invoke
the build system from another project, allowing complex projects such as a
statically linked basekit to be assembled with relative ease\.

Practcl ships as a single file, and aside from a Tcl 8\.6 interpreter, has no
external dependencies\.

Making a practcl project

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

  - <a name='1'></a>proc __practcl::cat__ *fname*

    Concatenate a file

  - <a name='2'></a>proc __practcl::docstrip__ *text*

    Strip the global comments from tcl code\. Used to prevent the documentation
    markup comments from clogging up files intended for distribution in machine
    readable format\.

  - <a name='3'></a>proc __putb__ ?*map*? *text*

    Append a line of text to a variable\. Optionally apply a string mapping\.

  - <a name='4'></a>proc __[Proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *name* *arglist* *body*

    Generate a proc if no command already exists by that name

  - <a name='5'></a>proc __noop__ ?*args*?

    A command to do nothing\. A handy way of negating an instruction without
    having to comment it completely out\. It's also a handy attachment point for
    an object to be named later

  - <a name='6'></a>proc __practcl::debug__ ?*args*?

  - <a name='7'></a>proc __practcl::doexec__ ?*args*?

    Drop in a static copy of Tcl

  - <a name='8'></a>proc __practcl::doexec\_in__ *path* ?*args*?

  - <a name='9'></a>proc __practcl::dotclexec__ ?*args*?

  - <a name='10'></a>proc __practcl::domake__ *path* ?*args*?

  - <a name='11'></a>proc __practcl::domake\.tcl__ *path* ?*args*?

  - <a name='12'></a>proc __practcl::fossil__ *path* ?*args*?

  - <a name='13'></a>proc __practcl::fossil\_status__ *dir*

  - <a name='14'></a>proc __practcl::os__

  - <a name='15'></a>proc __practcl::mkzip__ *exename* *barekit* *vfspath*

    Build a zipfile\. On tcl8\.6 this invokes the native Zip implementation on
    older interpreters this invokes zip via exec

  - <a name='16'></a>proc __practcl::sort\_dict__ *list*

    Dictionary sort a key/value list\. Needed because pre tcl8\.6 does not have
    *lsort \-stride 2*

  - <a name='17'></a>proc __practcl::local\_os__

  - <a name='18'></a>proc __practcl::config\.tcl__ *path*

    Detect local platform

  - <a name='19'></a>proc __practcl::read\_configuration__ *path*

  - <a name='20'></a>proc __practcl::tcllib\_require__ *pkg* ?*args*?

    Try to load a package, and failing that retrieve tcllib

  - <a name='21'></a>proc __practcl::platform::tcl\_core\_options__ *os*

  - <a name='22'></a>proc __practcl::platform::tk\_core\_options__ *os*

  - <a name='23'></a>proc __practcl::read\_rc\_file__ *filename* ?*localdat* ____?

    Read a stylized key/value list stored in a file

  - <a name='24'></a>proc __practcl::read\_sh\_subst__ *line* *info*

    Converts a XXX\.sh file into a series of Tcl variables

  - <a name='25'></a>proc __practcl::read\_sh\_file__ *filename* ?*localdat* ____?

  - <a name='26'></a>proc __practcl::read\_Config\.sh__ *filename*

    A simpler form of read\_sh\_file tailored to pulling data from
    \(tcl&#124;tk\)Config\.sh

  - <a name='27'></a>proc __practcl::read\_Makefile__ *filename*

    A simpler form of read\_sh\_file tailored to pulling data from a Makefile

  - <a name='28'></a>proc __practcl::cputs__ *varname* ?*args*?

    Append arguments to a buffer The command works like puts in that each call
    will also insert a line feed\. Unlike puts, blank links in the interstitial
    are suppressed

  - <a name='29'></a>proc __practcl::tcl\_to\_c__ *body*

  - <a name='30'></a>proc __practcl::\_tagblock__ *text* ?*style* __tcl__? ?*note* ____?

  - <a name='31'></a>proc __practcl::de\_shell__ *data*

  - <a name='32'></a>proc __practcl::grep__ *pattern* ?*files* ____?

    Search for the pattern *pattern* amongst $files

  - <a name='33'></a>proc __practcl::file\_lexnormalize__ *sp*

  - <a name='34'></a>proc __practcl::file\_relative__ *base* *dst*

    Calculate a relative path between base and dst

    Example:

        ::practcl::file_relative ~/build/tcl/unix ~/build/tcl/library
        > ../library

  - <a name='35'></a>proc __practcl::findByPattern__ *basedir* *patterns*

  - <a name='36'></a>proc __practcl::log__ *fname* *comment*

    Record an event in the practcl log

  - <a name='37'></a>proc __practcl::\_pkgindex\_simpleIndex__ *path*

  - <a name='38'></a>proc __practcl::\_pkgindex\_directory__ *path*

    Return true if the pkgindex file contains any statement other than "package
    ifneeded" and/or if any package ifneeded loads a DLL

  - <a name='39'></a>proc __practcl::\_pkgindex\_path\_subdir__ *path*

    Helper function for ::practcl::pkgindex\_path

  - <a name='40'></a>proc __practcl::pkgindex\_path__ ?*args*?

    Index all paths given as though they will end up in the same virtual file
    system

  - <a name='41'></a>proc __practcl::installDir__ *d1* *d2*

    Delete the contents of *d2*, and then recusively Ccopy the contents of
    *d1* to *d2*\.

  - <a name='42'></a>proc __practcl::copyDir__ *d1* *d2* ?*toplevel* __1__?

    Recursively copy the contents of *d1* to *d2*

  - <a name='43'></a>proc __practcl::buildModule__ *modpath*

  - <a name='44'></a>proc __practcl::installModule__ *modpath* *DEST*

  - <a name='45'></a>proc __practcl::trigger__ ?*args*?

    Trigger build targets, and recompute dependencies

    Internals:

        ::practcl::LOCAL make trigger {*}$args
        foreach {name obj} [::practcl::LOCAL make objects] {
          set ::make($name) [$obj do]
        }

  - <a name='46'></a>proc __practcl::depends__ ?*args*?

    Calculate if a dependency for any of the arguments needs to be fulfilled or
    rebuilt\.

    Internals:

        ::practcl::LOCAL make depends {*}$args

  - <a name='47'></a>proc __practcl::target__ *name* *info* ?*action* ____?

    Declare a build product\. This proc is just a shorthand for
    *::practcl::LOCAL make task $name $info $action*

    Registering a build product with this command will create an entry in the
    global array, and populate a value in the global array\.

    Internals:

        set obj [::practcl::LOCAL make task $name $info $action]
        set ::make($name) 0
        set filename [$obj define get filename]
        if {$filename ne {}} {
          set ::target($name) $filename
        }

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

## <a name='subsection1'></a>Class  practcl::doctool

    { set authors {
       {John Doe} {[email protected]}
       {Tom RichardHarry} {[email protected]}
     }
     # Create the object
     ::practcl::doctool create AutoDoc
     set fout [open [file join $moddir module.tcl] w]
     foreach file [glob [file join $srcdir *.tcl]] {
       set content [::practcl::cat [file join $srcdir $file]]
        # Scan the file
        AutoDoc scan_text $content
        # Strip the comments from the distribution
        puts $fout [::practcl::docstrip $content]
     }
     # Write out the manual page
     set manout [open [file join $moddir module.man] w]
     dict set args header [string map $modmap [::practcl::cat [file join $srcdir manual.txt]]]
     dict set args footer [string map $modmap [::practcl::cat [file join $srcdir footer.txt]]]
     dict set args authors $authors
     puts $manout [AutoDoc manpage {*}$args]
     close $manout


    }

Tool for build scripts to dynamically generate manual files from comments in
source code files

__Methods__

  - <a name='48'></a>method __constructor__

  - <a name='49'></a>method __argspec__ *argspec*

    Process an argument list into an informational dict\. This method also
    understands non\-positional arguments expressed in the notation of Tip 471
    [https://core\.tcl\-lang\.org/tips/doc/trunk/tip/479\.md](https://core\.tcl\-lang\.org/tips/doc/trunk/tip/479\.md)\.

    The output will be a dictionary of all of the fields and whether the fields
    are __positional__, __mandatory__, and whether they have a
    __default__ value\.

    Example:

    my argspec {a b {c 10}}

    > a {positional 1 mandatory 1} b {positional 1 mandatory 1} c {positional 1 mandatory 0 default 10}

  - <a name='50'></a>method __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *block*

    Convert a block of comments into an informational dictionary\. If lines in
    the comment start with a single word ending in a colon, all subsequent lines
    are appended to a dictionary field of that name\. If no fields are given, all
    of the text is appended to the __description__ field\.

    Example:

    my comment {Does something cool}
    > description {Does something cool}

    my comment {
    title : Something really cool
    author : Sean Woods
    author : John Doe
    description :
    This does something really cool!
    }
    > description {This does something really cool!}
      title {Something really cool}
      author {Sean Woods
      John Doe}

  - <a name='51'></a>method __keyword\.Annotation__ *resultvar* *commentblock* *type* *name* *body*

  - <a name='52'></a>method __keyword\.Class__ *resultvar* *commentblock* *name* *body*

    Process an oo::objdefine call that modifies the class object itself

  - <a name='53'></a>method __keyword\.class__ *resultvar* *commentblock* *name* *body*

    Process an oo::define, clay::define, etc statement\.

  - <a name='54'></a>method __keyword\.Class\_Method__ *resultvar* *commentblock* *name* ?*args*?

    Process a statement for a clay style class method

  - <a name='55'></a>method __keyword\.method__ *resultvar* *commentblock* *name* ?*args*?

    Process a statement for a tcloo style object method

  - <a name='56'></a>method __keyword\.proc__ *commentblock* *name* *argspec*

    Process a proc statement

  - <a name='57'></a>method __reset__

    Reset the state of the object and its embedded coroutine

  - <a name='58'></a>method __Main__

    Main body of the embedded coroutine for the object

  - <a name='59'></a>method __section\.method__ *keyword* *method* *minfo*

    Generate the manual page text for a method or proc

  - <a name='60'></a>method __section\.annotation__ *type* *name* *iinfo*

  - <a name='61'></a>method __section\.class__ *class\_name* *class\_info*

    Generate the manual page text for a class

  - <a name='62'></a>method __section\.command__ *procinfo*

    Generate the manual page text for the commands section

  - <a name='63'></a>method __[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ ?__header *value*__? ?__footer *value*__? ?__authors *list*__?

    Generate the manual page\. Returns the completed text suitable for saving in
    \.man file\. The header argument is a block of doctools text to go in before
    the machine generated section\. footer is a block of doctools text to go in
    after the machine generated section\. authors is a list of individual authors
    and emails in the form of AUTHOR EMAIL ?AUTHOR EMAIL?\.\.\.

  - <a name='64'></a>method __scan\_text__ *text*

    Scan a block of text

  - <a name='65'></a>method __scan\_file__ *filename*

    Scan a file of text

## <a name='subsection2'></a>Class  practcl::metaclass

The metaclass for all practcl objects

__Methods__

  - <a name='66'></a>method __\_MorphPatterns__

  - <a name='67'></a>method __[define](\.\./\.\./\.\./\.\./index\.md\#define)__ *submethod* ?*args*?

  - <a name='68'></a>method __graft__ ?*args*?

  - <a name='69'></a>method __initialize__

  - <a name='70'></a>method __link__ *command* ?*args*?

  - <a name='71'></a>method __morph__ *classname*

  - <a name='72'></a>method __script__ *script*

  - <a name='73'></a>method __select__

  - <a name='74'></a>method __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ *filename*

## <a name='subsection3'></a>Class  practcl::toolset

Ancestor\-less class intended to be a mixin which defines a family of build
related behaviors that are modified when targetting either gcc or msvc

__Class Methods__

  - <a name='75'></a>classmethod __select__ *object*

    Perform the selection for the toolset mixin

__Methods__

  - <a name='76'></a>method __config\.sh__

    find or fake a key/value list describing this project

  - <a name='77'></a>method __BuildDir__ *PWD*

    Compute the location where the product will be built

  - <a name='78'></a>method __MakeDir__ *srcdir*

    Return where the Makefile is located relative to *srcdir*\. For this
    implementation the MakeDir is always srcdir\.

  - <a name='79'></a>method __read\_configuration__

    Read information about the build process for this package\. For this
    implementation, data is sought in the following locations in the following
    order: config\.tcl \(generated by practcl\.\) PKGConfig\.sh\. The Makefile

    If the Makefile needs to be consulted, but does not exist, the Configure
    method is invoked

  - <a name='80'></a>method __build\-cflags__ *PROJECT* *DEFS* *namevar* *versionvar* *defsvar*

    method DEFS This method populates 4 variables: name \- The name of the
    package version \- The version of the package defs \- C flags passed to the
    compiler includedir \- A list of paths to feed to the compiler for finding
    headers

  - <a name='81'></a>method __critcl__ ?*args*?

    Invoke critcl in an external process

## <a name='subsection4'></a>Class  practcl::toolset\.gcc

*ancestors*: __practcl::toolset__

__Methods__

  - <a name='82'></a>method __Autoconf__

  - <a name='83'></a>method __BuildDir__ *PWD*

  - <a name='84'></a>method __ConfigureOpts__

  - <a name='85'></a>method __MakeDir__ *srcdir*

    Detect what directory contains the Makefile template

  - <a name='86'></a>method __make \{\} autodetect__

  - <a name='87'></a>method __make \{\} clean__

  - <a name='88'></a>method __make \{\} compile__

  - <a name='89'></a>method __make \{\} install__ *DEST*

  - <a name='90'></a>method __build\-compile\-sources__ *PROJECT* *COMPILE* *CPPCOMPILE* *INCLUDES*

  - <a name='91'></a>method __build\-Makefile__ *path* *PROJECT*

  - <a name='92'></a>method __build\-library__ *outfile* *PROJECT*

    Produce a static or dynamic library

  - <a name='93'></a>method __build\-tclsh__ *outfile* *PROJECT* ?*path* __auto__?

    Produce a static executable

## <a name='subsection5'></a>Class  practcl::toolset\.msvc

*ancestors*: __practcl::toolset__

__Methods__

  - <a name='94'></a>method __BuildDir__ *PWD*

    MSVC always builds in the source directory

  - <a name='95'></a>method __make \{\} autodetect__

    Do nothing

  - <a name='96'></a>method __make \{\} clean__

  - <a name='97'></a>method __make \{\} compile__

  - <a name='98'></a>method __make \{\} install__ *DEST*

  - <a name='99'></a>method __MakeDir__ *srcdir*

    Detect what directory contains the Makefile template

  - <a name='100'></a>method __NmakeOpts__

## <a name='subsection6'></a>Class  practcl::make\_obj

*ancestors*: __practcl::metaclass__

A build deliverable object\. Normally an object file, header, or tcl script which
must be compiled or generated in some way

__Methods__

  - <a name='101'></a>method __constructor__ *module\_object* *name* *info* ?*action\_body* ____?

  - <a name='102'></a>method __[do](\.\./\.\./\.\./\.\./index\.md\#do)__

  - <a name='103'></a>method __check__

  - <a name='104'></a>method __output__

  - <a name='105'></a>method __reset__

  - <a name='106'></a>method __triggers__

## <a name='subsection7'></a>Class  practcl::object

*ancestors*: __practcl::metaclass__

A generic Practcl object

__Methods__

  - <a name='107'></a>method __constructor__ *parent* ?*args*?

  - <a name='108'></a>method __child__ *method*

  - <a name='109'></a>method __go__

## <a name='subsection8'></a>Class  practcl::dynamic

Dynamic blocks do not generate their own \.c files, instead the contribute to the
amalgamation of the main library file

__Methods__

  - <a name='110'></a>method __cstructure__ *name* *definition* ?*argdat* ____?

    Parser functions

  - <a name='111'></a>method __include__ *header*

  - <a name='112'></a>method __include\_dir__ ?*args*?

  - <a name='113'></a>method __include\_directory__ ?*args*?

  - <a name='114'></a>method __c\_header__ *body*

  - <a name='115'></a>method __c\_code__ *body*

  - <a name='116'></a>method __c\_function__ *header* *body* ?*info* ____?

  - <a name='117'></a>method __c\_tcloomethod__ *name* *body* ?*arginfo* ____?

  - <a name='118'></a>method __cmethod__ *name* *body* ?*arginfo* ____?

    Alias to classic name

  - <a name='119'></a>method __c\_tclproc\_nspace__ *nspace*

  - <a name='120'></a>method __c\_tclcmd__ *name* *body* ?*arginfo* ____?

  - <a name='121'></a>method __c\_tclproc\_raw__ *name* *body* ?*arginfo* ____?

    Alias to classic name

  - <a name='122'></a>method __tcltype__ *name* *argdat*

  - <a name='123'></a>method __project\-compile\-products__

    Module interactions

  - <a name='124'></a>method __implement__ *path*

  - <a name='125'></a>method __initialize__

    Practcl internals

  - <a name='126'></a>method __linktype__

  - <a name='127'></a>method __generate\-cfile\-constant__

  - <a name='128'></a>method __generate\-cfile\-header__

  - <a name='129'></a>method __generate\-cfile\-tclapi__

    Generate code that provides implements Tcl API calls

  - <a name='130'></a>method __generate\-loader\-module__

    Generate code that runs when the package/module is initialized into the
    interpreter

  - <a name='131'></a>method __Collate\_Source__ *CWD*

  - <a name='132'></a>method __select__

    Once an object marks itself as some flavor of dynamic, stop trying to morph
    it into something else

## <a name='subsection9'></a>Class  practcl::product

A deliverable for the build system

__Class Methods__

  - <a name='133'></a>classmethod __select__ *object*

__Methods__

  - <a name='134'></a>method __code__ *section* *body*

  - <a name='135'></a>method __Collate\_Source__ *CWD*

  - <a name='136'></a>method __project\-compile\-products__

  - <a name='137'></a>method __generate\-debug__ ?*spaces* ____?

  - <a name='138'></a>method __generate\-cfile\-constant__

  - <a name='139'></a>method __generate\-cfile\-public\-structure__

    Populate const static data structures

  - <a name='140'></a>method __generate\-cfile\-header__

  - <a name='141'></a>method __generate\-cfile\-global__

  - <a name='142'></a>method __generate\-cfile\-private\-typedef__

  - <a name='143'></a>method __generate\-cfile\-private\-structure__

  - <a name='144'></a>method __generate\-cfile\-functions__

    Generate code that provides subroutines called by Tcl API methods

  - <a name='145'></a>method __generate\-cfile\-tclapi__

    Generate code that provides implements Tcl API calls

  - <a name='146'></a>method __generate\-hfile\-public\-define__

  - <a name='147'></a>method __generate\-hfile\-public\-macro__

  - <a name='148'></a>method __generate\-hfile\-public\-typedef__

  - <a name='149'></a>method __generate\-hfile\-public\-structure__

  - <a name='150'></a>method __generate\-hfile\-public\-headers__

  - <a name='151'></a>method __generate\-hfile\-public\-function__

  - <a name='152'></a>method __generate\-hfile\-public\-includes__

  - <a name='153'></a>method __generate\-hfile\-public\-verbatim__

  - <a name='154'></a>method __generate\-loader\-external__

  - <a name='155'></a>method __generate\-loader\-module__

  - <a name='156'></a>method __generate\-stub\-function__

  - <a name='157'></a>method __IncludeAdd__ *headervar* ?*args*?

  - <a name='158'></a>method __generate\-tcl\-loader__

  - <a name='159'></a>method __generate\-tcl\-pre__

    This methods generates any Tcl script file which is required to
    pre\-initialize the C library

  - <a name='160'></a>method __generate\-tcl\-post__

  - <a name='161'></a>method __linktype__

  - <a name='162'></a>method __Ofile__ *filename*

  - <a name='163'></a>method __project\-static\-packages__

    Methods called by the master project

  - <a name='164'></a>method __toolset\-include\-directory__

    Methods called by the toolset

  - <a name='165'></a>method __target__ *method* ?*args*?

## <a name='subsection10'></a>Class  practcl::product\.cheader

*ancestors*: __practcl::product__

A product which generated from a C header file\. Which is to say, nothing\.

__Methods__

  - <a name='166'></a>method __project\-compile\-products__

  - <a name='167'></a>method __generate\-loader\-module__

## <a name='subsection11'></a>Class  practcl::product\.csource

*ancestors*: __practcl::product__

A product which generated from a C source file\. Normally an object \(\.o\) file\.

__Methods__

  - <a name='168'></a>method __project\-compile\-products__

## <a name='subsection12'></a>Class  practcl::product\.clibrary

*ancestors*: __practcl::product__

A product which is generated from a compiled C library\. Usually a \.a or a \.dylib
file, but in complex cases may actually just be a conduit for one project to
integrate the source code of another

__Methods__

  - <a name='169'></a>method __linker\-products__ *configdict*

## <a name='subsection13'></a>Class  practcl::product\.dynamic

*ancestors*: __practcl::dynamic__ __practcl::product__

A product which is generated from C code that itself is generated by practcl or
some other means\. This C file may or may not produce its own \.o file, depending
on whether it is eligible to become part of an amalgamation

__Methods__

  - <a name='170'></a>method __initialize__

## <a name='subsection14'></a>Class  practcl::product\.critcl

*ancestors*: __practcl::dynamic__ __practcl::product__

A binary product produced by critcl\. Note: The implementation is not written
yet, this class does nothing\.

## <a name='subsection15'></a>Class  practcl::module

*ancestors*: __practcl::object__ __practcl::product\.dynamic__

In the end, all C code must be loaded into a module This will either be a
dynamically loaded library implementing a tcl extension, or a compiled in
segment of a custom shell/app

__Variable__

  - <a name='171'></a>variable __make\_object__

__Methods__

  - <a name='172'></a>method __\_MorphPatterns__

  - <a name='173'></a>method __add__ ?*args*?

  - <a name='174'></a>method __install\-headers__ ?*args*?

  - <a name='175'></a>method __make \{\} \_preamble__

  - <a name='176'></a>method __make \{\} pkginfo__

  - <a name='177'></a>method __make \{\} objects__

    Return a dictionary of all handles and associated objects

  - <a name='178'></a>method __make \{\} object__ *name*

    Return the object associated with handle *name*

  - <a name='179'></a>method __make \{\} reset__

    Reset all deputy objects

  - <a name='180'></a>method __make \{\} trigger__ ?*args*?

    Exercise the triggers method for all handles listed

  - <a name='181'></a>method __make \{\} depends__ ?*args*?

    Exercise the check method for all handles listed

  - <a name='182'></a>method __make \{\} filename__ *name*

    Return the file name of the build product for the listed handle

  - <a name='183'></a>method __make \{\} target__ *name* *Info* *body*

  - <a name='184'></a>method __make \{\} todo__

    Return a list of handles for object which return true for the do method

  - <a name='185'></a>method __make \{\} do__

    For each target exercise the action specified in the *action* definition
    if the *do* method returns true

  - <a name='186'></a>method __child__ *which*

  - <a name='187'></a>method __generate\-c__

    This methods generates the contents of an amalgamated \.c file which
    implements the loader for a batch of tools

  - <a name='188'></a>method __generate\-h__

    This methods generates the contents of an amalgamated \.h file which
    describes the public API of this module

  - <a name='189'></a>method __generate\-loader__

  - <a name='190'></a>method __initialize__

  - <a name='191'></a>method __implement__ *path*

  - <a name='192'></a>method __linktype__

## <a name='subsection16'></a>Class  practcl::project

*ancestors*: __practcl::module__

A toplevel project that is a collection of other projects

__Methods__

  - <a name='193'></a>method __\_MorphPatterns__

  - <a name='194'></a>method __constructor__ ?*args*?

  - <a name='195'></a>method __add\_object__ *object*

  - <a name='196'></a>method __add\_project__ *pkg* *info* ?*oodefine* ____?

  - <a name='197'></a>method __add\_tool__ *pkg* *info* ?*oodefine* ____?

  - <a name='198'></a>method __build\-tclcore__

    Compile the Tcl core\. If the define *tk* is true, compile the Tk core as
    well

  - <a name='199'></a>method __child__ *which*

  - <a name='200'></a>method __linktype__

  - <a name='201'></a>method __project__ *pkg* ?*args*?

    Exercise the methods of a sub\-object

  - <a name='202'></a>method __tclcore__

  - <a name='203'></a>method __tkcore__

  - <a name='204'></a>method __[tool](\.\./tool/tool\.md)__ *pkg* ?*args*?

## <a name='subsection17'></a>Class  practcl::library

*ancestors*: __practcl::project__

A toplevel project that produces a library

__Methods__

  - <a name='205'></a>method __clean__ *PATH*

  - <a name='206'></a>method __project\-compile\-products__

  - <a name='207'></a>method __go__

  - <a name='208'></a>method __generate\-decls__ *pkgname* *path*

  - <a name='209'></a>method __implement__ *path*

  - <a name='210'></a>method __generate\-make__ *path*

    Backward compadible call

  - <a name='211'></a>method __linktype__

  - <a name='212'></a>method __package\-ifneeded__ ?*args*?

    Create a "package ifneeded" Args are a list of aliases for which this
    package will answer to

  - <a name='213'></a>method __shared\_library__ ?*filename* ____?

  - <a name='214'></a>method __static\_library__ ?*filename* ____?

## <a name='subsection18'></a>Class  practcl::tclkit

*ancestors*: __practcl::library__

A toplevel project that produces a self\-contained executable

__Methods__

  - <a name='215'></a>method __build\-tclkit\_main__ *PROJECT* *PKG\_OBJS*

  - <a name='216'></a>method __Collate\_Source__ *CWD*

  - <a name='217'></a>method __wrap__ *PWD* *exename* *vfspath* ?*args*?

    Wrap an executable

## <a name='subsection19'></a>Class  practcl::distribution

Standalone class to manage code distribution This class is intended to be mixed
into another class \(Thus the lack of ancestors\)

__Class Methods__

  - <a name='218'></a>classmethod __Sandbox__ *object*

  - <a name='219'></a>classmethod __select__ *object*

  - <a name='220'></a>classmethod __claim\_option__

  - <a name='221'></a>classmethod __claim\_object__ *object*

  - <a name='222'></a>classmethod __claim\_path__ *path*

__Methods__

  - <a name='223'></a>method __scm\_info__

  - <a name='224'></a>method __DistroMixIn__

  - <a name='225'></a>method __Sandbox__

  - <a name='226'></a>method __SrcDir__

  - <a name='227'></a>method __ScmTag__

  - <a name='228'></a>method __ScmClone__

  - <a name='229'></a>method __ScmUnpack__

  - <a name='230'></a>method __ScmUpdate__

  - <a name='231'></a>method __Unpack__

## <a name='subsection20'></a>Class  practcl::distribution\.snapshot

*ancestors*: __practcl::distribution__

A file distribution from zip, tarball, or other non\-scm archive format

__Class Methods__

  - <a name='232'></a>classmethod __claim\_object__ *object*

  - <a name='233'></a>classmethod __claim\_option__

  - <a name='234'></a>classmethod __claim\_path__ *path*

__Methods__

  - <a name='235'></a>method __ScmUnpack__

## <a name='subsection21'></a>Class  practcl::distribution\.fossil

*ancestors*: __practcl::distribution__

A file distribution based on fossil

__Class Methods__

  - <a name='236'></a>classmethod __claim\_object__ *obj*

    Check for markers in the metadata

  - <a name='237'></a>classmethod __claim\_option__

  - <a name='238'></a>classmethod __claim\_path__ *path*

    Check for markers in the source root

__Methods__

  - <a name='239'></a>method __scm\_info__

  - <a name='240'></a>method __ScmClone__

    Clone the source

  - <a name='241'></a>method __ScmTag__

  - <a name='242'></a>method __ScmUnpack__

  - <a name='243'></a>method __ScmUpdate__

## <a name='subsection22'></a>Class  practcl::distribution\.git

*ancestors*: __practcl::distribution__

A file distribution based on git

__Class Methods__

  - <a name='244'></a>classmethod __claim\_object__ *obj*

  - <a name='245'></a>classmethod __claim\_option__

  - <a name='246'></a>classmethod __claim\_path__ *path*

__Methods__

  - <a name='247'></a>method __ScmTag__

  - <a name='248'></a>method __ScmUnpack__

  - <a name='249'></a>method __ScmUpdate__

## <a name='subsection23'></a>Class  practcl::subproject

*ancestors*: __practcl::module__

A subordinate project

__Methods__

  - <a name='250'></a>method __\_MorphPatterns__

  - <a name='251'></a>method __BuildDir__ *PWD*

  - <a name='252'></a>method __child__ *which*

  - <a name='253'></a>method __compile__

  - <a name='254'></a>method __go__

  - <a name='255'></a>method __install__ ?*args*?

    Install project into the local build system

  - <a name='256'></a>method __linktype__

  - <a name='257'></a>method __linker\-products__ *configdict*

  - <a name='258'></a>method __linker\-external__ *configdict*

  - <a name='259'></a>method __linker\-extra__ *configdict*

  - <a name='260'></a>method __env\-bootstrap__

    Methods for packages/tools that can be downloaded possibly built and used
    internally by this Practcl process Load the facility into the interpreter

  - <a name='261'></a>method __env\-exec__

    Return a file path that exec can call

  - <a name='262'></a>method __env\-install__

    Install the tool into the local environment

  - <a name='263'></a>method __env\-load__

    Do whatever is necessary to get the tool into the local environment

  - <a name='264'></a>method __env\-present__

    Check if tool is available for load/already loaded

  - <a name='265'></a>method __sources__

  - <a name='266'></a>method __[update](\.\./\.\./\.\./\.\./index\.md\#update)__

  - <a name='267'></a>method __unpack__

## <a name='subsection24'></a>Class  practcl::subproject\.source

*ancestors*: __practcl::subproject__ __practcl::library__

A project which the kit compiles and integrates the source for itself

__Methods__

  - <a name='268'></a>method __env\-bootstrap__

  - <a name='269'></a>method __env\-present__

  - <a name='270'></a>method __linktype__

## <a name='subsection25'></a>Class  practcl::subproject\.teapot

*ancestors*: __practcl::subproject__

a copy from the teapot

__Methods__

  - <a name='271'></a>method __env\-bootstrap__

  - <a name='272'></a>method __env\-install__

  - <a name='273'></a>method __env\-present__

  - <a name='274'></a>method __install__ *DEST*

## <a name='subsection26'></a>Class  practcl::subproject\.kettle

*ancestors*: __practcl::subproject__

__Methods__

  - <a name='275'></a>method __kettle__ *path* ?*args*?

  - <a name='276'></a>method __install__ *DEST*

## <a name='subsection27'></a>Class  practcl::subproject\.critcl

*ancestors*: __practcl::subproject__

__Methods__

  - <a name='277'></a>method __install__ *DEST*

## <a name='subsection28'></a>Class  practcl::subproject\.sak

*ancestors*: __practcl::subproject__

__Methods__

  - <a name='278'></a>method __env\-bootstrap__

  - <a name='279'></a>method __env\-install__

  - <a name='280'></a>method __env\-present__

  - <a name='281'></a>method __install__ *DEST*

  - <a name='282'></a>method __install\-module__ *DEST* ?*args*?

## <a name='subsection29'></a>Class  practcl::subproject\.practcl

*ancestors*: __practcl::subproject__

__Methods__

  - <a name='283'></a>method __env\-bootstrap__

  - <a name='284'></a>method __env\-install__

  - <a name='285'></a>method __install__ *DEST*

  - <a name='286'></a>method __install\-module__ *DEST* ?*args*?

## <a name='subsection30'></a>Class  practcl::subproject\.binary

*ancestors*: __practcl::subproject__

A subordinate binary package

__Methods__

  - <a name='287'></a>method __clean__

  - <a name='288'></a>method __env\-install__

  - <a name='289'></a>method __project\-compile\-products__

  - <a name='290'></a>method __ComputeInstall__

  - <a name='291'></a>method __go__

  - <a name='292'></a>method __linker\-products__ *configdict*

  - <a name='293'></a>method __project\-static\-packages__

  - <a name='294'></a>method __BuildDir__ *PWD*

  - <a name='295'></a>method __compile__

  - <a name='296'></a>method __Configure__

  - <a name='297'></a>method __install__ *DEST*

## <a name='subsection31'></a>Class  practcl::subproject\.tea

*ancestors*: __practcl::subproject\.binary__

A subordinate TEA based binary package

## <a name='subsection32'></a>Class  practcl::subproject\.library

*ancestors*: __practcl::subproject\.binary__ __practcl::library__

A subordinate C library built by this project

__Methods__

  - <a name='298'></a>method __install__ *DEST*

## <a name='subsection33'></a>Class  practcl::subproject\.external

*ancestors*: __practcl::subproject\.binary__

A subordinate external C library

__Methods__

  - <a name='299'></a>method __install__ *DEST*

## <a name='subsection34'></a>Class  practcl::subproject\.core

*ancestors*: __practcl::subproject\.binary__

__Methods__

  - <a name='300'></a>method __env\-bootstrap__

  - <a name='301'></a>method __env\-present__

  - <a name='302'></a>method __env\-install__

  - <a name='303'></a>method __go__

  - <a name='304'></a>method __linktype__

# <a name='section4'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *practcl* of the [Tcllib
Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas
for enhancements you may have for either package and/or documentation\.

When proposing code changes, please provide *unified diffs*, i\.e the output of

Changes to embedded/md/tcllib/files/modules/pt/pt_peg_container.md.

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
    This method assigns the contents of the PEG object *source* to ourselves,
    overwriting the existing definition\. This is the assignment operator for
    grammars\.

    This operation is in effect equivalent to

        *objectName* __deserialize =__ [*source* __serialize__]

  - <a name='9'></a>*objectName* __\-\->__ *destination*

    This method assigns our contents to the PEG object *destination*,
    overwriting the existing definition\. This is the reverse assignment operator
    for grammars\.

    This operation is in effect equivalent to

        *destination* __deserialize =__ [*objectName* __serialize__]

  - <a name='10'></a>*objectName* __serialize__ ?*format*?

    This method returns our grammar in some textual form usable for transfer,
    persistent storage, etc\. If no *format* is not specified the returned
    result is the canonical serialization of the grammar, as specified in the
    section [PEG serialization format](#section2)\.






|









|







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
    This method assigns the contents of the PEG object *source* to ourselves,
    overwriting the existing definition\. This is the assignment operator for
    grammars\.

    This operation is in effect equivalent to

    > *objectName* __deserialize =__ \[*source* __serialize__\]

  - <a name='9'></a>*objectName* __\-\->__ *destination*

    This method assigns our contents to the PEG object *destination*,
    overwriting the existing definition\. This is the reverse assignment operator
    for grammars\.

    This operation is in effect equivalent to

    > *destination* __deserialize =__ \[*objectName* __serialize__\]

  - <a name='10'></a>*objectName* __serialize__ ?*format*?

    This method returns our grammar in some textual form usable for transfer,
    persistent storage, etc\. If no *format* is not specified the returned
    result is the canonical serialization of the grammar, as specified in the
    section [PEG serialization format](#section2)\.

Changes to embedded/md/tcllib/files/modules/pt/pt_peg_export.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
[//000000001]: # (pt::peg::export \- Parser Tools)
[//000000002]: # (Generated from file 'pt\_peg\_export\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (pt::peg::export\(n\) 1 tcllib "Parser Tools")

<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>
................................................................................

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require snit  
package require configuration  
package require pt::peg  
package require pluginmgr  
package require pt::peg::export ?1?  

[__::pt::peg::export__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
[*objectName* __export serial__ *serial* ?*format*?](#4)  
[*objectName* __export object__ *object* ?*format*?](#5)  
[*objectName* __configuration names__](#6)  



|







 







|


|







1
2
3
4
5
6
7
8
9
10
11
12
..
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
[//000000001]: # (pt::peg::export \- Parser Tools)
[//000000002]: # (Generated from file 'pt\_peg\_export\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (pt::peg::export\(n\) 1\.0\.1 tcllib "Parser Tools")

<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>
................................................................................

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require snit  
package require struct::map  
package require pt::peg  
package require pluginmgr  
package require pt::peg::export ?1\.0\.1?  

[__::pt::peg::export__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
[*objectName* __export serial__ *serial* ?*format*?](#4)  
[*objectName* __export object__ *object* ?*format*?](#5)  
[*objectName* __configuration names__](#6)  

Changes to embedded/md/tcllib/files/modules/pt/pt_peg_import.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52

53
54
55
56
57
58
59
60
61
62
63
64
[//000000001]: # (pt::peg::import \- Parser Tools)
[//000000002]: # (Generated from file 'pt\_peg\_import\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (pt::peg::import\(n\) 1 tcllib "Parser Tools")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  

package require snit  
package require configuration  
package require pt::peg  
package require pluginmgr  
package require pt::peg::import ?1?  

[__::pt::peg::import__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
[*objectName* __import text__ *text* ?*format*?](#4)  
[*objectName* __import file__ *path* ?*format*?](#5)  
[*objectName* __import object text__ *object* *text* ?*format*?](#6)  



|







 







>

|


|







1
2
3
4
5
6
7
8
9
10
11
12
..
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
[//000000001]: # (pt::peg::import \- Parser Tools)
[//000000002]: # (Generated from file 'pt\_peg\_import\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (pt::peg::import\(n\) 1\.0\.1 tcllib "Parser Tools")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.5  
package require Tcl 8\.5  
package require snit  
package require fileutil::paths  
package require pt::peg  
package require pluginmgr  
package require pt::peg::import ?1\.0\.1?  

[__::pt::peg::import__ *objectName*](#1)  
[__objectName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*objectName* __destroy__](#3)  
[*objectName* __import text__ *text* ?*format*?](#4)  
[*objectName* __import file__ *path* ?*format*?](#5)  
[*objectName* __import object text__ *object* *text* ?*format*?](#6)  

Changes to embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md.

246
247
248
249
250
251
252
253

254
255
256
257
258
259
260
  - __[pt::tclparam::configuration::snit](pt\_tclparam\_config\_snit\.md)__

    Generated parsers are classes based on the
    __[snit](\.\./snit/snit\.md)__ package, i\.e\. snit::type's\.

  - __[pt::tclparam::configuration::tcloo](pt\_tclparam\_config\_tcloo\.md)__

    Generated parsers are classes based on the __OO__ package\.


# <a name='section4'></a>Tcl/PARAM code representation of parsing expression grammars

The Tcl/PARAM representation of parsing expression grammars is Tcl code whose
execution will parse input per the grammar\. The code is based on the virtual
machine documented in the *[PackRat Machine Specification](pt\_param\.md)*,
using its instructions and a few more to handle control flow\.






|
>







246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
  - __[pt::tclparam::configuration::snit](pt\_tclparam\_config\_snit\.md)__

    Generated parsers are classes based on the
    __[snit](\.\./snit/snit\.md)__ package, i\.e\. snit::type's\.

  - __[pt::tclparam::configuration::tcloo](pt\_tclparam\_config\_tcloo\.md)__

    Generated parsers are classes based on the
    __[OO](\.\./\.\./\.\./\.\./index\.md\#oo)__ package\.

# <a name='section4'></a>Tcl/PARAM code representation of parsing expression grammars

The Tcl/PARAM representation of parsing expression grammars is Tcl code whose
execution will parse input per the grammar\. The code is based on the virtual
machine documented in the *[PackRat Machine Specification](pt\_param\.md)*,
using its instructions and a few more to handle control flow\.

Changes to embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md.

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
system the current package is a part of\.

This package is an adjunct to
__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__, to make the use of
this highly configurable package easier by providing a canned configuration\.
When applied this configuration causes the package
__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ to generate
__OO__\-based parser packages\.

It is a supporting package in the Core Layer of Parser Tools\.

![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png)

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

  - <a name='1'></a>__::pt::tclparam::configuration::tcloo__ __def__ *name* *pkg* *version* *cmdprefix*

    The command applies the configuration provided by this package to the
    *cmdprefix*, causing the creation of __OO__\-based parsers whose class

    is *name*, in package *pkg* with *version*\.

    The use of a command prefix as API allows application of the configuration
    to not only __[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__
    \(__pt::peg::to::tclparam configure__\), but also export manager instances
    and PEG containers \(__$export configuration set__ and __\[$container
    exporter\] configuration set__ respectively\)\.







|










|
>
|







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
system the current package is a part of\.

This package is an adjunct to
__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__, to make the use of
this highly configurable package easier by providing a canned configuration\.
When applied this configuration causes the package
__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ to generate
__[OO](\.\./\.\./\.\./\.\./index\.md\#oo)__\-based parser packages\.

It is a supporting package in the Core Layer of Parser Tools\.

![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png)

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

  - <a name='1'></a>__::pt::tclparam::configuration::tcloo__ __def__ *name* *pkg* *version* *cmdprefix*

    The command applies the configuration provided by this package to the
    *cmdprefix*, causing the creation of
    __[OO](\.\./\.\./\.\./\.\./index\.md\#oo)__\-based parsers whose class is
    *name*, in package *pkg* with *version*\.

    The use of a command prefix as API allows application of the configuration
    to not only __[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__
    \(__pt::peg::to::tclparam configure__\), but also export manager instances
    and PEG containers \(__$export configuration set__ and __\[$container
    exporter\] configuration set__ respectively\)\.

Changes to embedded/md/tcllib/files/modules/rcs/rcs.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (rcs \- RCS low level utilities)
[//000000002]: # (Generated from file 'rcs\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2005, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2005, Colin McCormack <[email protected]\.sourceforge\.net>)
[//000000004]: # (rcs\(n\) 2\.0\.2 tcllib "RCS low level utilities")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (rcs \- RCS low level utilities)
[//000000002]: # (Generated from file 'rcs\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2005, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (Copyright &copy; 2005, Colin McCormack <[email protected]\.sourceforge\.net>)
[//000000005]: # (rcs\(n\) 2\.0\.2 tcllib "RCS low level utilities")

<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>

Changes to embedded/md/tcllib/files/modules/sha1/sha1.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
[//000000001]: # (sha1 \- SHA\-x Message\-Digest Algorithm)
[//000000002]: # (Generated from file 'sha1\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2005, Pat Thoyts <[email protected]\.sourceforge\.net>)
[//000000004]: # (sha1\(n\) 2\.0\.3 tcllib "SHA\-x Message\-Digest Algorithm")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.2  
package require sha1 ?2\.0\.3?  

[__::sha1::sha1__ ?__\-hex&#124;\-bin__? \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#1)  
[__::sha1::hmac__ *key* *string*](#2)  
[__::sha1::hmac__ ?__\-hex&#124;\-bin__? __\-key key__ \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#3)  
[__::sha1::SHA1Init__](#4)  
[__::sha1::SHA1Update__ *token* *data*](#5)  
[__::sha1::SHA1Final__ *token*](#6)  



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
..
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
[//000000001]: # (sha1 \- SHA\-x Message\-Digest Algorithm)
[//000000002]: # (Generated from file 'sha1\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2005, Pat Thoyts <[email protected]\.sourceforge\.net>)
[//000000004]: # (sha1\(n\) 2\.0\.4 tcllib "SHA\-x Message\-Digest Algorithm")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.2  
package require sha1 ?2\.0\.4?  

[__::sha1::sha1__ ?__\-hex&#124;\-bin__? \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#1)  
[__::sha1::hmac__ *key* *string*](#2)  
[__::sha1::hmac__ ?__\-hex&#124;\-bin__? __\-key key__ \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#3)  
[__::sha1::SHA1Init__](#4)  
[__::sha1::SHA1Update__ *token* *data*](#5)  
[__::sha1::SHA1Final__ *token*](#6)  

Changes to embedded/md/tcllib/files/modules/sha1/sha256.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
[//000000001]: # (sha256 \- SHA\-x Message\-Digest Algorithm)
[//000000002]: # (Generated from file 'sha256\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2008, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (sha256\(n\) 1\.0\.3 tcllib "SHA\-x Message\-Digest Algorithm")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.2  
package require sha256 ?1\.0\.3?  

[__::sha2::sha256__ ?__\-hex&#124;\-bin__? \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#1)  
[__::sha2::sha224__ ?__\-hex&#124;\-bin__? \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#2)  
[__::sha2::hmac__ *key* *string*](#3)  
[__::sha2::hmac__ ?__\-hex&#124;\-bin__? __\-key key__ \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#4)  
[__::sha2::SHA256Init__](#5)  
[__::sha2::SHA224Init__](#6)  



|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
..
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
[//000000001]: # (sha256 \- SHA\-x Message\-Digest Algorithm)
[//000000002]: # (Generated from file 'sha256\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2008, Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (sha256\(n\) 1\.0\.4 tcllib "SHA\-x Message\-Digest Algorithm")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.2  
package require sha256 ?1\.0\.4?  

[__::sha2::sha256__ ?__\-hex&#124;\-bin__? \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#1)  
[__::sha2::sha224__ ?__\-hex&#124;\-bin__? \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#2)  
[__::sha2::hmac__ *key* *string*](#3)  
[__::sha2::hmac__ ?__\-hex&#124;\-bin__? __\-key key__ \[ __\-channel channel__ &#124; __\-file filename__ &#124; ?__\-\-__? *string* \]](#4)  
[__::sha2::SHA256Init__](#5)  
[__::sha2::SHA224Init__](#6)  

Changes to embedded/md/tcllib/files/modules/soundex/soundex.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (soundex \- Soundex)
[//000000002]: # (Generated from file 'soundex\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; ????, Algorithm: Donald E\. Knuth  
Copyright &copy; 2003, Documentation: Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 1998, Tcl port: Evan Rempel <[email protected]\.ca>)
[//000000004]: # (soundex\(n\) 1\.0 tcllib "Soundex")

<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>


|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (soundex \- Soundex)
[//000000002]: # (Generated from file 'soundex\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; ????, Algorithm: Donald E\. Knuth)
[//000000004]: # (Copyright &copy; 2003, Documentation: Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (Copyright &copy; 1998, Tcl port: Evan Rempel <[email protected]\.ca>)
[//000000006]: # (soundex\(n\) 1\.0 tcllib "Soundex")

<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>

Changes to embedded/md/tcllib/files/modules/struct/graph.md.

1
2
3
4
5
6
7
8
9
10
11
12
..
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
...
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
...
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
...
446
447
448
449
450
451
452








453
454
455
456
457
458
459
...
588
589
590
591
592
593
594
595
596



597
598
599
600
601
602
603
604
...
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
...
867
868
869
870
871
872
873
874
[//000000001]: # (struct::graph \- Tcl Data Structures)
[//000000002]: # (Generated from file 'graph\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2002\-2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (struct::graph\(n\) 2\.4\.1 tcllib "Tcl Data Structures")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require struct::graph ?2\.4\.1?  
package require struct::list ?1\.5?  
package require struct::set ?2\.2\.3?  

[__::struct::graph__ ?*graphName*? ?__=__&#124;__:=__&#124;__as__&#124;__deserialize__ *source*?](#1)  
[__graphName__ *option* ?*arg arg \.\.\.*?](#2)  
[*graphName* __=__ *sourcegraph*](#3)  
[*graphName* __\-\->__ *destgraph*](#4)  
................................................................................
    This is the *assignment* operator for graph objects\. It copies the graph
    contained in the graph object *sourcegraph* over the graph data in
    *graphName*\. The old contents of *graphName* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *graphName* __deserialize__ [*sourcegraph* __serialize__]

    The operation assumes that the *sourcegraph* provides the method
    __serialize__ and that this method returns a valid graph serialization\.

  - <a name='4'></a>*graphName* __\-\->__ *destgraph*

    This is the *reverse assignment* operator for graph objects\. It copies the
    graph contained in the graph object *graphName* over the graph data in the
    object *destgraph*\. The old contents of *destgraph* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *destgraph* __deserialize__ [*graphName* __serialize__]

    The operation assumes that the *destgraph* provides the method
    __deserialize__ and that this method takes a graph serialization\.

  - <a name='5'></a>*graphName* __append__ *key* *value*

    Appends a *value* to one of the keyed values associated with the graph\.
................................................................................
    containing all arcs is returned\. Restrictions can limit the list of returned
    arcs based on the nodes that are connected by the arc, on the keyed values
    associated with the arc, or both\. A general filter command can be used as
    well\. The restrictions that involve connected nodes take a variable number
    of nodes as argument, specified after the name of the restriction itself\.

    The restrictions imposed by either __\-in__, __\-out__, __\-adj__,
    __\-inner__, or __\-embedded__ are applied first\. Specifying more than
    one of them is illegal\.

    After that the restrictions set via __\-key__ \(and __\-value__\) are
    applied\. Specifying more than one __\-key__ \(and __\-value__\) is
    illegal\. Specifying __\-value__ alone, without __\-key__ is illegal as
    well\.

    Any restriction set through __\-filter__ is applied last\. Specifying more
................................................................................
        nodes\.

      * __\-embedding__

        Return a list of all arcs adjacent to exactly one of the nodes in the
        set\. This is the set of arcs connecting the subgraph spawned by the
        specified nodes to the rest of the graph\.









      * __\-key__ *key*

        Limit the list of arcs that are returned to those arcs that have an
        associated key *key*\.

      * __\-value__ *value*
................................................................................

    Return a list of nodes in the graph\. Restrictions can limit the list of
    returned nodes based on neighboring nodes, or based on the keyed values
    associated with the node\. The restrictions that involve neighboring nodes
    have a list of nodes as argument, specified after the name of the
    restriction itself\.

    The possible restrictions are the same as for method __arcs__\. The exact
    meanings change slightly, as they operate on nodes instead of arcs\. The



    command recognizes:

      * __\-in__

        Return a list of all nodes with at least one outgoing arc ending in a
        node found in the specified set of nodes\. Alternatively specified as the
        set of source nodes for the __\-in__ arcs of the node set\. The
        *incoming neighbours*\.
................................................................................

    *Note:* The order of the nodes in the serialization has no relevance, nor
    has the order of the arcs per node\.

        # A possible serialization for the graph structure
        #
        #        d -----> %2
        #       /         ^ \\
        #      /         /   \\
        #     /         b     \\
        #    /         /       \\
        #  %1 <- a - %0         e
        #    ^         \\      /
        #     \\        c     /
        #      \\        \\  /
        #       \\        v v
        #        f ------ %3
        # is
................................................................................

# <a name='category'></a>CATEGORY

Data structures

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2002\-2009 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>


|
|







 







|







 







|













|







 







|
|







 







>
>
>
>
>
>
>
>







 







|
|
>
>
>
|







 







|
|
|
|







 







|
1
2
3
4
5
6
7
8
9
10
11
12
..
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
...
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
...
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
...
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
...
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
...
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
...
878
879
880
881
882
883
884
885
[//000000001]: # (struct::graph \- Tcl Data Structures)
[//000000002]: # (Generated from file 'graph\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2002\-2009,2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (struct::graph\(n\) 2\.4\.2 tcllib "Tcl Data Structures")

<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>
................................................................................
  - [Category](#category)

  - [Copyright](#copyright)

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

package require Tcl 8\.4  
package require struct::graph ?2\.4\.2?  
package require struct::list ?1\.5?  
package require struct::set ?2\.2\.3?  

[__::struct::graph__ ?*graphName*? ?__=__&#124;__:=__&#124;__as__&#124;__deserialize__ *source*?](#1)  
[__graphName__ *option* ?*arg arg \.\.\.*?](#2)  
[*graphName* __=__ *sourcegraph*](#3)  
[*graphName* __\-\->__ *destgraph*](#4)  
................................................................................
    This is the *assignment* operator for graph objects\. It copies the graph
    contained in the graph object *sourcegraph* over the graph data in
    *graphName*\. The old contents of *graphName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *graphName* __deserialize__ \[*sourcegraph* __serialize__\]

    The operation assumes that the *sourcegraph* provides the method
    __serialize__ and that this method returns a valid graph serialization\.

  - <a name='4'></a>*graphName* __\-\->__ *destgraph*

    This is the *reverse assignment* operator for graph objects\. It copies the
    graph contained in the graph object *graphName* over the graph data in the
    object *destgraph*\. The old contents of *destgraph* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *destgraph* __deserialize__ \[*graphName* __serialize__\]

    The operation assumes that the *destgraph* provides the method
    __deserialize__ and that this method takes a graph serialization\.

  - <a name='5'></a>*graphName* __append__ *key* *value*

    Appends a *value* to one of the keyed values associated with the graph\.
................................................................................
    containing all arcs is returned\. Restrictions can limit the list of returned
    arcs based on the nodes that are connected by the arc, on the keyed values
    associated with the arc, or both\. A general filter command can be used as
    well\. The restrictions that involve connected nodes take a variable number
    of nodes as argument, specified after the name of the restriction itself\.

    The restrictions imposed by either __\-in__, __\-out__, __\-adj__,
    __\-inner__, or __\-embedding__ are applied first\. Specifying more
    than one of them is illegal\.

    After that the restrictions set via __\-key__ \(and __\-value__\) are
    applied\. Specifying more than one __\-key__ \(and __\-value__\) is
    illegal\. Specifying __\-value__ alone, without __\-key__ is illegal as
    well\.

    Any restriction set through __\-filter__ is applied last\. Specifying more
................................................................................
        nodes\.

      * __\-embedding__

        Return a list of all arcs adjacent to exactly one of the nodes in the
        set\. This is the set of arcs connecting the subgraph spawned by the
        specified nodes to the rest of the graph\.

    *Attention*: After the above options any word with a leading dash which is
    not a valid option is treated as a node name instead of an invalid option to
    error out on\. This condition holds until either a valid option terminates
    the list of nodes, or the end of the command is reached, whichever comes
    first\.

    The remaining filter options are:

      * __\-key__ *key*

        Limit the list of arcs that are returned to those arcs that have an
        associated key *key*\.

      * __\-value__ *value*
................................................................................

    Return a list of nodes in the graph\. Restrictions can limit the list of
    returned nodes based on neighboring nodes, or based on the keyed values
    associated with the node\. The restrictions that involve neighboring nodes
    have a list of nodes as argument, specified after the name of the
    restriction itself\.

    The possible restrictions are the same as for method __arcs__\. Note that
    while the exact meanings change slightly, as they operate on nodes instead
    of arcs, the general behaviour is the same, especially when it comes to the
    handling of words with a leading dash in node lists\.

    The command recognizes:

      * __\-in__

        Return a list of all nodes with at least one outgoing arc ending in a
        node found in the specified set of nodes\. Alternatively specified as the
        set of source nodes for the __\-in__ arcs of the node set\. The
        *incoming neighbours*\.
................................................................................

    *Note:* The order of the nodes in the serialization has no relevance, nor
    has the order of the arcs per node\.

        # A possible serialization for the graph structure
        #
        #        d -----> %2
        #       /         ^ \
        #      /         /   \
        #     /         b     \
        #    /         /       \
        #  %1 <- a - %0         e
        #    ^         \\      /
        #     \\        c     /
        #      \\        \\  /
        #       \\        v v
        #        f ------ %3
        # is
................................................................................

# <a name='category'></a>CATEGORY

Data structures

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2002\-2009,2019 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>

Changes to embedded/md/tcllib/files/modules/struct/graphops.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (struct::graph::op \- Tcl Data Structures)
[//000000002]: # (Generated from file 'graphops\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2008 Alejandro Paz <[email protected]\.com>  
Copyright &copy; 2008 \(docs\) Andreas Kupries <andreas\[email protected]\.sourceforge\.net>  
Copyright &copy; 2009 Michal Antoniewski <antoniewski\[email protected]\.com>)
[//000000004]: # (struct::graph::op\(n\) 0\.11\.3 tcllib "Tcl Data Structures")

<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>


|
|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
[//000000001]: # (struct::graph::op \- Tcl Data Structures)
[//000000002]: # (Generated from file 'graphops\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2008 Alejandro Paz <[email protected]\.com>)
[//000000004]: # (Copyright &copy; 2008 \(docs\) Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (Copyright &copy; 2009 Michal Antoniewski <antoniewski\[email protected]\.com>)
[//000000006]: # (struct::graph::op\(n\) 0\.11\.3 tcllib "Tcl Data Structures")

<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>

Changes to embedded/md/tcllib/files/modules/struct/matrix.md.

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
    This is the assignment operator for matrix objects\. It copies the matrix
    contained in the matrix object *sourcematrix* over the matrix data in
    *matrixName*\. The old contents of *matrixName* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *matrixName* __deserialize__ [*sourcematrix* __serialize__]

  - <a name='4'></a>*matrixName* __\-\->__ *destmatrix*

    This is the reverse assignment operator for matrix objects\. It copies the
    matrix contained in the matrix object *matrixName* over the matrix data in
    the object *destmatrix*\. The old contents of *destmatrix* are deleted by
    this operation\.

    This operation is in effect equivalent to

        *destmatrix* __deserialize__ [*matrixName* __serialize__]

  - <a name='5'></a>*matrixName* __add column__ ?*values*?

    Extends the matrix by one column and then acts like __set column__ \(see
    below\) on this new column if there were *values* supplied\. Without
    *values* the new cells will be set to the empty string\. The new column is
    appended immediately behind the last existing column\.






|










|







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
    This is the assignment operator for matrix objects\. It copies the matrix
    contained in the matrix object *sourcematrix* over the matrix data in
    *matrixName*\. The old contents of *matrixName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *matrixName* __deserialize__ \[*sourcematrix* __serialize__\]

  - <a name='4'></a>*matrixName* __\-\->__ *destmatrix*

    This is the reverse assignment operator for matrix objects\. It copies the
    matrix contained in the matrix object *matrixName* over the matrix data in
    the object *destmatrix*\. The old contents of *destmatrix* are deleted by
    this operation\.

    This operation is in effect equivalent to

    > *destmatrix* __deserialize__ \[*matrixName* __serialize__\]

  - <a name='5'></a>*matrixName* __add column__ ?*values*?

    Extends the matrix by one column and then acts like __set column__ \(see
    below\) on this new column if there were *values* supplied\. Without
    *values* the new cells will be set to the empty string\. The new column is
    appended immediately behind the last existing column\.

Changes to embedded/md/tcllib/files/modules/struct/struct_list.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (struct::list \- Tcl Data Structures)
[//000000002]: # (Generated from file 'struct\_list\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2005 by Kevin B\. Kenny\. All rights reserved  
Copyright &copy; 2003\-2012 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000004]: # (struct::list\(n\) 1\.8\.4 tcllib "Tcl Data Structures")

<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>


|
|
|







1
2
3
4
5
6
7
8
9
10
11
12
13
[//000000001]: # (struct::list \- Tcl Data Structures)
[//000000002]: # (Generated from file 'struct\_list\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2003\-2005 by Kevin B\. Kenny\. All rights reserved)
[//000000004]: # (Copyright &copy; 2003\-2012 Andreas Kupries <andreas\[email protected]\.sourceforge\.net>)
[//000000005]: # (struct::list\(n\) 1\.8\.4 tcllib "Tcl Data Structures")

<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>

Added embedded/md/tcllib/files/modules/struct/struct_map.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
[//000000001]: # (struct::map \- )
[//000000002]: # (Generated from file 'struct\_map\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (struct::map\(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

struct::map \- Manage key/value maps

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

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [API](#section2)

  - [Bugs, Ideas, Feedback](#section3)

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

package require struct::map ?1?  

[__::struct::map__ *mapName*](#1)  
[__mapName__ __method__ ?*arg arg \.\.\.*?](#2)  
[*mapName* __get__](#3)  
[*mapName* __names__](#4)  
[*mapName* __set__ *name* ?*value*?](#5)  
[*mapName* __unset__ ?*pattern*\.\.\.?](#6)  

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

Provides a snit class whose instances manage a key/value map\. In other words, an
object wrapper around Tcl arrays\.

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

The main command provides construction of maps:

  - <a name='1'></a>__::struct::map__ *mapName*

    Creates a new, empty map with an associated global Tcl command whose name is
    *mapName*\. It may be used to invoke various operations on the map\. It has
    the following general form:

      * <a name='2'></a>__mapName__ __method__ ?*arg arg \.\.\.*?

        __method__ and *arg*uments determine the exact behavior of the
        command\.

    If *mapName* is specified as __%AUTO%__ a unique name will be
    generated by the package itself\. The result of the command is the
    fully\-qualified name of the instance command\.

The following commands are possible for map objects:

  - <a name='3'></a>*mapName* __get__

    Returns the entire map as a Tcl dictionary\.

  - <a name='4'></a>*mapName* __names__

    Returns the list of all keys known to the map, in arbitrary order\.

  - <a name='5'></a>*mapName* __set__ *name* ?*value*?

    Sets key *name* to the specified *value*, if the value specified\.
    Returns the value for the key\. Throws an error if the key is not known\.

  - <a name='6'></a>*mapName* __unset__ ?*pattern*\.\.\.?

    Removes all keys matching at least one of the glob *pattern*s from the
    map\. If no pattern is specified all keys are removed\. In other words, the
    default pattern is __\*__\. The result of the command is the empty string\.

# <a name='section3'></a>Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and
other problems\. Please report such in the category *struct :: list* of the
[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report
any ideas for enhancements you may have for either package and/or documentation\.

When proposing code changes, please provide *unified diffs*, i\.e the output of
__diff \-u__\.

Note further that *attachments* are strongly preferred over inlined patches\.
Attachments can be made by going to the __Edit__ form of the ticket
immediately after its creation, and then using the left\-most button in the
secondary navigation bar\.

Changes to embedded/md/tcllib/files/modules/struct/struct_tree.md.

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
    This is the assignment operator for tree objects\. It copies the tree
    contained in the tree object *sourcetree* over the tree data in
    *treeName*\. The old contents of *treeName* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *treeName* __deserialize__ [*sourcetree* __serialize__]

  - <a name='5'></a>*treeName* __\-\->__ *desttree*

    This is the reverse assignment operator for tree objects\. It copies the tree
    contained in the tree object *treeName* over the tree data in the object
    *desttree*\. The old contents of *desttree* are deleted by this
    operation\.

    This operation is in effect equivalent to

        *desttree* __deserialize__ [*treeName* __serialize__]

  - <a name='6'></a>*treeName* __ancestors__ *node*

    This method extends the method __parent__ and returns a list containing
    all ancestor nodes to the specified *node*\. The immediate ancestor, in
    other words, parent node, is the first element in that list, its parent the
    second element, and so on until the root node is reached, making it the last






|










|







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
    This is the assignment operator for tree objects\. It copies the tree
    contained in the tree object *sourcetree* over the tree data in
    *treeName*\. The old contents of *treeName* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *treeName* __deserialize__ \[*sourcetree* __serialize__\]

  - <a name='5'></a>*treeName* __\-\->__ *desttree*

    This is the reverse assignment operator for tree objects\. It copies the tree
    contained in the tree object *treeName* over the tree data in the object
    *desttree*\. The old contents of *desttree* are deleted by this
    operation\.

    This operation is in effect equivalent to

    > *desttree* __deserialize__ \[*treeName* __serialize__\]

  - <a name='6'></a>*treeName* __ancestors__ *node*

    This method extends the method __parent__ and returns a list containing
    all ancestor nodes to the specified *node*\. The immediate ancestor, in
    other words, parent node, is the first element in that list, its parent the
    second element, and so on until the root node is reached, making it the last

Changes to embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md.

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
...
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
...
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330



331
332
333
334
335
336
337
...
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
...
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
...
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
...
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
...
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
    been acknowledged \(via the *OK* button\) and validated by a data checker\.
    If the entered data have been rejected \(via the *Cancel* button\) the
    __argument\_dialogbox__ returns __cancel__\.

    A small example illustrates how the __argument\_dialogbox__ can be
    employed:

        set DialogResult [__tepam::argument_dialogbox__ \
           __-title__ "Itinerary selection" \
           __-file__ {*-label "Itinerary report" -variable report_file*} \
           __-frame__ {*-label "Itinerary start"*} \
              __-comment__ {*-text "Specify your itinerary start location"*} \
              __-entry__ {*-label "City" -variable start_city -type string*} \
              __-entry__ {*-label "Street" -variable start_street -type string -optional 1*} \
              __-entry__ {*-label "Street number" -variable start_street_nbr -type integer -optional 1*} \
           __-frame__ {*-label "Itinerary destination"*} \
              __-comment__ {*-text "Specify your itinerary destination"*} \
              __-entry__ {*-label "City" -variable dest_city -type string*} \
              __-entry__ {*-label "Street" -variable dest_street -type string -optional 1*} \
              __-entry__ {*-label "Street number" -variable dest_street_nbr -type integer -optional 1*} \
           __-frame__ {} \
           __-checkbutton__ {*-label "Don't use highways" -variable no_highway*}

    \] This example opens a dialog box that has the title *Itinerary
    selection*\. A first entry widget in this box allows selecting a report
    file\. It follows two frames to define respectively an itinerary start and
    end location\. Each of these locations that are described with a comment has
    three entry widgets to specify respectively the city, street and the street
    number\. Bellow the second frame there is a check button that allows
    specifying if eventual highways should be ignored\.

  - <a name='2'></a>__tepam::argument\_dialogbox__ \{*item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?*\}

    Sometimes it is simpler to provide all the data entry item definitions in
    form of a single list to __argument\_dialogbox__, and not as individual
    arguments\. The second format that is supported by __argument\_dialogbox__
    corresponds exactly to the first one, except that all item definitions are
    packed into a single list that is provided to __argument\_dialogbox__\.
    The previous example can therefore also be written in the following way:

        set DialogResult [__tepam::argument_dialogbox {__
           __-title__ "Itinerary selection"
           __-file__ {*-label "Itinerary report" -variable report_file*}
           ...
           __-checkbutton__ {*-label "Don't use highways" -variable no_highway*}

    __\}__\]

The commands __argument\_dialogbox__ as well as
__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ are exported from the
namespace __tepam__\. To use these commands without the __tepam::__
namespace prefix, it is sufficient to import them into the main namespace:

    __namespace import tepam::*__

    set DialogResult [__argument_dialogbox__ \
       -title "Itinerary selection"
       ...

The following subsections explain the different argument item types that are
accepted by the __argument\_dialogbox__, classified into three groups\. The
first data entry item definition format will be used in the remaining document,
knowing that this format can always be transformed into the second format by
putting all arguments into a single list that is then provided to
__argument\_dialogbox__\.

## <a name='subsection1'></a>Context Definition Items

The first item group allows specifying some context aspects of an argument
dialog box\. These items are taking a simple character string as item attribute:

    tepam::argument_dialogbox \
       __-<argument_name>__ *string* \
       ...

The following items are classified into this group:

  - \-title *string*

    The dialog box window title which is by default *Dialog* can be changed
    with the *\-title* item:

    tepam::argument_dialogbox \
       __-title__ "System configuration" \
       ...

  - \-window *string*

    The argument dialog box uses by default *\.dialog* as dialog top level
    window\. This path can be changed with the *\-window* item:

    tepam::argument_dialogbox \
       __-window__ .dialog \
       ...

  - \-parent *string*

    By defining a parent window, the argument dialog box will be displayed
    beside this one\. Without explicit parent window definition, the top\-level
    window will be considered as parent window\.

    tepam::argument_dialogbox \
       __-parent__ .my_appl \
       ...

  - \-context *string*

    If a context is defined the dialog box state, e\.g\. the entered data as well
    as the window size and position, is restored the next time the argument
    dialog box is called\. The assignment of a context allows saving the dialog
    box state in its context to distinguish between different usages of the
    argument dialog box\.

    tepam::argument_dialogbox \
       __-context__ destination_definitions \
       ...

## <a name='subsection2'></a>Formatting and Display Options

Especially for big, complex forms it becomes important that the different data
entry widgets are graphically well organized and commented to provide an
immediate and clear overview to the user\. A couple of items allow structuring
and commenting the dialog boxes\.

The items of this classification group require as item attributes a definition
list, which contains itself attribute name and value pairs:

    tepam::argument_dialogbox \
       ...
       __-<argument_name>__ { *
          ?-<attribute_name> <attribute_value>?
          ?-<attribute_name> <attribute_value>?
          ?...?*
       }
       ...




The following items are classified into this group:

  - \-frame *list*

    The *\-frame* item allows packing all following entry widgets into a
    labeled frame, until a next frame item is defined or until the last entry
................................................................................

      * \-label *string*

        An optional frame label can be specified with the *\-label* statement\.

    Example:

    tepam::argument_dialogbox \
       ...
       __-frame__ {*-label "Destination address"*}
       ...

    To close an open frame without opening a new one, an empty list has to be
    provided to the *\-frame* statement\.

    tepam::argument_dialogbox \
       ...
       __-frame__ {}
       ...

  - \-sep \[const \{\{\}\}\]

    Entry widgets can be separated with the *\-sep* statement which doesn't
    require additional definitions\. The related definition list has to exist,
    but its content is ignored\.

    tepam::argument_dialogbox \
       ...
       __-sep__ {}
       ...

  - \-comment *string*

    Comments and descriptions can be added with the *\-text* attribute of the
    *\-comment* item\. Please note that each entry widget itself can also
    contain a *\-text* attribute for comments and descriptions\. But the
    *\-comment* item allows for example adding a description between two
    frames\.

    tepam::argument_dialogbox \
       ...
       __-comment__ {*-text "Specify bellow the destination address"*}
       ...

  - \-yscroll __0__&#124;__1__&#124;__auto__

    This attribute allows controlling an eventual vertical scrollbar\. Setting it
    to __0__ will permanently disable the scrollbar, setting it to __1__
    will enable it\. By default it is set to __auto__\. The scrollbar is
    enabled in this mode only if the vertical data entry form size exceeds 66%
    of the screen height\.

    tepam::argument_dialogbox \
       ...
       __-yscroll__ __auto__
       ...

## <a name='subsection3'></a>Global Custom Data Validation

This item group allows specifying global custom checks to validate the entered
data\.

  - \-validatecommand *script*

    Custom data checks can be performed via validation commands that are defined
    with the *\-validatecommand* item\. Example:

    tepam::argument_dialogbox \
       -entry {-label "Your comment" -variable YourCom} \
       __-validatecommand__ {IllegalWordDetector $YourCom}

    The validation command is executed in the context of the calling procedure,
    once all the basic data checks have been performed and data variables are
    assigned\. All data is accessed via the data variables\. Note that there is
    also an entry widget specific attribute *\-validatecommand* that allows
    declaring custom checks for specific data entries\.

................................................................................

## <a name='subsection4'></a>Data Entry Widget Items

Data entry widgets are created with the widget items\. These items require as
item attributes a definition list, which contains itself attribute name and
value pairs:

    tepam::argument_dialogbox \
       ...
       __-<argument_name>__ { *
          ?-<attribute_name> <attribute_value>?
          ?-<attribute_name> <attribute_value>?
          ?...?*
       }
       ...




The attribute list can contain various attributes to describe and comment an
entry widget and to constrain its entered value\. All entry widgets are accepting
a common set of attributes that are described in the section [Entry Widget Item
Attributes](#subsection5)\.

TEPAM defines a rich set of entry widgets\. If necessary, this set can be
................................................................................
SPECIFIC ENTRY WIDGETS](#section3)\):

  - \-entry *list*

    The *\-entry* item generates the simplest but most universal data entry
    widget\. It allows entering any kind of data in form of single line strings\.

    tepam::argument_dialogbox \
       __-entry__ {-label Name -variable Entry}

  - \-text *list*

    The *\-text* item generates a multi line text entry widget\. The widget
    height can be selected with the *\-height* attribute\.

    tepam::argument_dialogbox \
       __-text__ {-label Name -variable Text -height 5}

  - \-checkbox *list*

    A group of check boxes is created with the *\-checkbox* item\. The number of
    check boxes and their option values are specified with a list assigned to
    the *\-choices* attribute or via a variable declared with the
    *\-choicevariable* attribute:

    tepam::argument_dialogbox \
       __-checkbox__ {-label "Font sytle" -variable FontStyle \
                   -choices {bold italic underline} -default italic}

    If the labels of the check boxes should differ from the option values, their
    labels can be defined with the *\-choicelabels* attribute:

    tepam::argument_dialogbox \
       __-checkbox__ {-label "Font sytle" -variable FontStyle \
                  -choices {bold italic underline} \
                  -choicelabels {Bold Italic Underline} \
                  -default italic}

    In contrast to a radio box group, a check box group allows selecting
    simultaneously several choice options\. The selection is stored for this
    reason inside the defined variable in form of a list, even if only one
    choice option has been selected\.

  - \-radiobox *list*
................................................................................
    the *\-choices* attribute or via a variable declared with the
    *\-choicevariable* attribute\.

    In contrast to a check box group, a radio box group allows selecting
    simultaneously only one choice option\. The selected option value is stored
    directly, and not in form of a list, inside the defined variable\.

    tepam::argument_dialogbox \
       __-radiobox__ {-label "Text adjustment" -variable Adjustment \
                  -choices {left center right} -default left}

    If the labels of the radio boxes should differ from the option values, their
    labels can be defined with the *\-choicelabels* attribute:

    tepam::argument_dialogbox \
       __-radiobox__ {-label "Text adjustment" -variable Adjustment \
                  -choices {left center right} \
                  -choicelabels {Left Center Right} -default left}

  - \-checkbutton *list*

    The *\-checkbutton* entry widget allows activating or deactivating a single
    choice option\. The result written into the variable will either be __0__
    if the check button was not activated or __1__ if it was activated\. An
    eventually provided default value has also to be either __0__ or
    __1__\.

    tepam::argument_dialogbox \
       __-checkbutton__ {-label Capitalize -variable Capitalize -default 1}

Several types of list and combo boxes are available to handle selection lists\.

  - \-combobox *list*

    The combobox is a combination of a normal entry widget together with a
    drop\-down list box\. The combobox allows selecting from this drop\-down list
    box a single element\. The list of the available elements can be provided
    either as a list to the *\-choices* attribute, or via a variable that is
    specified with the *\-choicevariable* attribute\.

    tepam::argument_dialogbox \
       __-combobox__ {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}

    And here is an example of using a variable to define the selection list:

    set TextSizes {8 9 10 12 15 18}
    tepam::argument_dialogbox \
       __-combobox__ {-label "Text size" -variable Size -choicevariable TextSizes -default 12}

  - \-listbox *list*

    In contrast to the combo box, the list box is always displayed by the
    *listbox* entry widget\. Only one element is selectable unless the
    *\-multiple\_selection* attribute is set\. The list box height can be
    selected with the *\-height* attribute\. If the height is not explicitly
    defined, the list box height is automatically adapted to the argument dialog
    box size\. The first example uses a variable to define the available choices:

    set set AvailableSizes
    for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}

    tepam::argument_dialogbox \
       __-listbox__ {-label "Distance" -variable Distance \
                 -choicevariable AvailableSizes -default 6 -height 5}

    Here is a multi\-element selection example\. Please note that also the default
    selection can contain multiple elements:

    tepam::argument_dialogbox \
       __-listbox__ {-label "Text styles" -variable Styles \
                 -choices {bold italic underline overstrike} \
                 -choicelabels {Bold Italic Underline Overstrike} \
                 -default {bold underline} -multiple_selection 1 \
                 -height 3}

  - \-disjointlistbox *list*

    A disjoint list box has to be used instead of a normal list box if the
    selection order is important\. The disjoint list box entry widget has in fact
    two list boxes, one to select elements and one to display the selected
    elements in the chosen order\.

    Disjoint listboxes allow always selecting multiple elements\. With the
    exception of the *\-multiple\_selection* attribute, disjointed list boxes
    are accepting the same attributes as the normal listbox, e\.g\. *\-height,
    \-choices, \-choicevariable, \-default*\.

    tepam::argument_dialogbox \
       __-disjointlistbox__ {-label "Preferred scripting languages" -variable Languages \
                 -comment "Please select your preferred languages in the order" \
                 -choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \
                 -default {Tcl Perl Python}}

The file and directory selectors are building a next group of data entry
widgets\. A paragraph of section [Entry Widget Item
Attributes](#subsection5) explains the widget specific attributes that allow
specifying the targeted file types, active directory etc\.

  - \-file *list*

    The item *\-file* creates a group composed by an entry widget together with
    a button that allows opening a file browser\. The data type *file* is
    automatically selected for this entry if no data type has been explicitly
    defined with the *\-type* attribute\.

    tepam::argument_dialogbox \
       __-file__ {-label "Image file" -variable ImageF \
              -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
              -initialfile "picture.gif"}

  - \-existingfile *list*

    The item *\-existingfile* creates a group composed by an entry widget
    together with a button that allows opening a browser to select an existing
    file\. The data type *existingfile* is automatically selected for this
    entry if no data type has been explicitly defined with the *\-type*
    attribute\.

    tepam::argument_dialogbox \
       __-existingfile__ {-label "Image file" -variable ImageF \
                      -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
                      -initialfile "picture.gif"}

  - \-directory *list*

    The item *\-directory* creates a group composed by an entry widget together
    with a button that allows opening a directory browser\. The data type
    *directory* is automatically selected for this entry if no data type has
    been explicitly defined with the *\-type* attribute\.

    tepam::argument_dialogbox \
       __-directory__ {-label "Report directory" -variable ReportDir}

  - \-existingdirectory *list*

    The item *\-existingdirectory* creates a group composed by an entry widget
    together with a button that allows opening a browser to select an existing
    directory\. The data type *existingdirectory* is automatically selected for
    this entry if no data type has been explicitly defined with the *\-type*
    attribute\.

    tepam::argument_dialogbox \
       __-existingdirectory__ {-label "Report directory" -variable ReportDir}

Finally, there is a last group of some other special data entry widgets\.

  - \-color *list*

    The color selector is composed by an entry widget together with a button
    that allows opening a color browser\. The data type *color* is
    automatically selected for this entry widget type if no data type has been
    explicitly defined with the *\-type* attribute\.

    tepam::argument_dialogbox \
       __-color__ {-label "Background color" -variable Color -default red}

  - \-font *list*

    The font selector is composed by an entry widget together with a button that
    allows opening a font browser\. The data type *font* is automatically
    selected for this entry widget type if no data type has been explicitly
    defined with the *\-type* attribute\. The entry widget displays an example
................................................................................
    If no default font is provided via the *\-default* attribute, the default
    font of the label widget to display the selected font will be used as
    default selected font\. If the font family of this label widget is not part
    of the available families the first available family is used as default\. If
    the font size of this label widget is not part of the available sizes the
    next close available size is selected as default size\.

    tepam::argument_dialogbox \
       __-font__ {-label "Font" -variable Font \
              -font_sizes {8 10 12 16} \
              -default {Arial 20 italic}}

## <a name='subsection5'></a>Entry Widget Item Attributes

All the entry widget items are accepting the following attributes:

  - \-text *string*

    Eventual descriptions and comments specified with the *\-text* attribute
    are displayed above the entry widget\.

    tepam::argument_dialogbox \
       -entry {__-text "Please enter your name bellow"__ -variable Name}

  - \-label *string*

    The label attribute creates left to the entry widget a label using the
    provided string as label text:

    tepam::argument_dialogbox \
       -entry {__-label Name__ -variable Name}

  - \-variable *string*

    All entry widgets require a specified variable\. After accepting the entered
    information with the OK button, the entry widget data is stored inside the
    defined variables\.

    tepam::argument_dialogbox \
       -existingdirectory {-label "Report directory" __-variable ReportDir__}

  - \-default *string*

    Eventual default data for the entry widgets can be provided via the
    *\-default* attribute\. The default value is overridden if an argument
    dialog box with a defined context is called another time\. The value
    acknowledged in a previous call will be used in this case as default value\.

    tepam::argument_dialogbox \
       -checkbox {-label "Font sytle" -variable FontStyle \
                   -choices {bold italic underline} __-default italic__}

  - \-optional __0__&#124;__1__

    Data can be specified as optional or mandatory with the *\-optional*
    attribute that requires either __0__ \(mandatory\) or __1__ \(optional\)
    as attribute data\.

    In case an entry is optional and no data has been entered, e\.g\. the entry
    contains an empty character string, the entry will be considered as
    undefined and the assigned variable will not be defined\.

    tepam::argument_dialogbox \
       -entry {-label "City" -variable start_city -type string} \
       -entry {-label "Street" -variable start_street -type string __-optional 0__} \
       -entry {-label "Street number" -variable start_street_nbr -type integer __-optional 1__} \

  - \-type *string*

    If the data type is defined with the *\-type* attribute the argument dialog
    box will automatically perform a data type check after acknowledging the
    entered values and before the dialog box is closed\. If a type incompatible
    value is found an error message box appears and the user can correct the
................................................................................
    __[tepam::procedure](tepam\_procedure\.md)__ \(see the
    *tepam::procedure reference manual*\)\.

    Some entry widgets like the file and directory widgets, as well as the color
    and font widgets are specifying automatically the default data type if no
    type has been specified explicitly with the *\-type* attribute\.

    tepam::argument_dialogbox \
       __-entry__ {-label "Street number" -variable start_street_nbr __-type integer__} \

  - \-range *string*

    Values can be constrained with the *\-range* attribute\. The valid range is
    defined with a list containing the minimum valid value and a maximum valid
    value\.

    The *\-range* attribute has to be used only for numerical arguments, like
    integers and doubles\.

    tepam::argument_dialogbox \
       -entry {-label Month -variable Month -type integer __-range {1 12}__}

  - \-validatecommand *string*

    Custom argument value validations can be performed via specific validation
    commands that are defined with the *\-validatecommand* attribute\. The
    provided validation command can be a complete script in which the pattern
    *%P* is placeholder for the argument value that has to be validated\.

    tepam::argument_dialogbox \
       -entry {-label "Your comment" -variable YourCom \
               __-validatecommand__ "IllegalWordDetector %P"}

    While the purpose of this custom argument validation attribute is the
    validation of a specific argument, there is also a global data validation
    attribute *\-validatecommand* that allows performing validation that
    involves multiple arguments\.

  - \-validatecommand\_error\_text *string*
................................................................................

  - \-choices *string*

    Choice lists can directly be defined with the *\-choices* attribute\. This
    way to define choice lists is especially adapted for smaller, fixed
    selection lists\.

    tepam::argument_dialogbox \
       -listbox {-label "Text styles" -variable Styles \
                 __-choices {bold italic underline}__ -default underline

  - \-choicelabels *string* *\(only check and radio buttons\)*

    If the labels of the check and radio boxes should differ from the option
    values, they can be defined with the *\-choicelabels* attribute:

    tepam::argument_dialogbox \
       -checkbox {-label "Font sytle" -variable FontStyle \
                  -choices {bold italic underline} \
                  __-choicelabels {Bold Italic Underline}__

  - \-choicevariable *string*

    Another way to define the choice lists is using the *\-choicevariable*
    attribute\. This way to define choice lists is especially adapted for huge
    and eventually variable selection lists\.

    set TextSizes {8 9 10 12 15 18}
    tepam::argument_dialogbox \
       -combobox {-label "Text size" -variable Size __-choicevariable TextSizes__}

  - \-multiple\_selection __0__&#124;__1__

    The list box item \(__\-listbox__\) allows by default selecting only one
    list element\. By setting the *\-multiple\_selection* attribute to __1__,
    multiple elements can be selected\.

    tepam::argument_dialogbox \
       -listbox {-label "Text styles" -variable Styles \
                 -choices {bold italic underline} -default underline \
                 __-multiple_selection 1__ -height 3}

Some additional attributes are supported by the file and directory selection
widgets\.

  - \-filetypes *string*

    The file type attribute is used by the __\-file__ and
    __\-existingfile__ items to define the file endings that are searched by
    the file browser\.

    tepam::argument_dialogbox \
       -file {-label "Image file" -variable ImageF \
              __-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}__}

  - \-initialfile *string*

    The initial file used by the file browsers of the __\-file__ and
    __\-existingfile__ widgets are by default the file defined with the
    *\-default* attribute, unless a file is specified with the *\-initialfile*
    attribute\.

    tepam::argument_dialogbox \
       -file {-variable ImageF __-initialfile "picture.gif"__}

  - \-activedir *string*

    The *\-activedir* attribute will override the default active search
    directory used by the file browsers of all file and directory entry widgets\.
    The default active search directory is defined by the directory of a
    specified initial file \(*\-initialfile*\) if defined, and otherwise by the
    directory of the default file/directory, specified with the *\-default*
    attribute\.

    tepam::argument_dialogbox \
       -file "-variable ImageF __-activedir $pwd__"

Finally, there is a last attribute supported by some widgets:

  - \-height *string*

    All widgets containing a selection list \(__\-listbox__,
    __\-disjointlistbox__, __\-font__\) as well as the multi line
    __\-text__ widget are accepting the *\-height* attribute that defines
    the number of displayed rows of the selection lists\.

    tepam::argument_dialogbox \
       -listbox {-label "Text size" -variable Size \
                 -choices {8 9 10 12 15 18} -default 12 __-height 3__}

    If the no height has been explicitly specified the height of the widget will
    be dynamically adapted to the argument dialog box size\.

# <a name='section3'></a>APPLICATION SPECIFIC ENTRY WIDGETS

An application specific entry widget can be made available to the argument
dialog box by adding a dedicated procedure to the __tepam__ namespace\. This
procedure has three arguments; the first one is the widget path, the second one
a subcommand and the third argument has various purposes:

    *proc* tepam::ad_form(<WidgetName>) {W Command {Par ""}} {
       *upvar Option Option; # if required*
       *variable argument_dialogbox; # if required*
       switch $Command {
          "create" <CreateCommandSequence>
          "set_choice" <SetChoiceCommandSequence>
          "set" <SetCommandv>
          "get" <GetCommandSequence>
       }
    }



__Argument\_dialogbox__ takes care about the *\-label* and *\-text*
attributes for all entry widgets\. For any data entry widget it creates a frame
into which the data entry widget components can be placed\. The path to this
frame is provided via the *W* argument\.

The entry widget procedure has to support 3 mandatory and an optional command






|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

|
|
|
|
|
|
|










|
|
|
|
|
<
<






|
|
|
|
|













|
|
|








|
|
|






|
|
|







|
|
|









|
|
|











|
|
|
|
|
|
<
<
>
>
>







 







|
|
|
|




|
|
|
|







|
|
|
|









|
|
|
|









|
|
|
|











|
|
|







 







|
|
|
|
|
|
<
<
>
>
>







 







|
|






|
|








|
|
|




|
|
|
|
|







 







|
|
|




|
|
|
|









|
|











|
|



|
|
|










|
|
|
|
|
|




|
|
|
|
|
|













|
|
|
|
|













|
|
|
|









|
|
|
|








|
|









|
|










|
|







 







|
|
|
|










|
|






|
|







|
|








|
|
|











|
|
|
|







 







|
|










|
|








|
|
|







 







|
|
|






|
|
|
|







|
|
|







|
|
|
|










|
|
|








|
|










|
|










|
|
|











|
|
|
|
|
|
|
|
<
<
>
>







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
...
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
...
315
316
317
318
319
320
321
322
323
324
325
326
327


328
329
330
331
332
333
334
335
336
337
...
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
...
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
...
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
...
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
...
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
    been acknowledged \(via the *OK* button\) and validated by a data checker\.
    If the entered data have been rejected \(via the *Cancel* button\) the
    __argument\_dialogbox__ returns __cancel__\.

    A small example illustrates how the __argument\_dialogbox__ can be
    employed:

    > set DialogResult \[__tepam::argument\_dialogbox__ \\  
    > &nbsp;&nbsp;&nbsp;__\-title__ "Itinerary selection" \\  
    > &nbsp;&nbsp;&nbsp;__\-file__ \{*\-label "Itinerary report" \-variable report\_file*\} \\  
    > &nbsp;&nbsp;&nbsp;__\-frame__ \{*\-label "Itinerary start"*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-comment__ \{*\-text "Specify your itinerary start location"*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "City" \-variable start\_city \-type string*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "Street" \-variable start\_street \-type string \-optional 1*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "Street number" \-variable start\_street\_nbr \-type integer \-optional 1*\} \\  
    > &nbsp;&nbsp;&nbsp;__\-frame__ \{*\-label "Itinerary destination"*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-comment__ \{*\-text "Specify your itinerary destination"*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "City" \-variable dest\_city \-type string*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "Street" \-variable dest\_street \-type string \-optional 1*\} \\  
    > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;__\-entry__ \{*\-label "Street number" \-variable dest\_street\_nbr \-type integer \-optional 1*\} \\  
    > &nbsp;&nbsp;&nbsp;__\-frame__ \{\} \\  
    > &nbsp;&nbsp;&nbsp;__\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}\]

    This example opens a dialog box that has the title *Itinerary selection*\.
    A first entry widget in this box allows selecting a report file\. It follows
    two frames to define respectively an itinerary start and end location\. Each
    of these locations that are described with a comment has three entry widgets
    to specify respectively the city, street and the street number\. Bellow the
    second frame there is a check button that allows specifying if eventual
    highways should be ignored\.

  - <a name='2'></a>__tepam::argument\_dialogbox__ \{*item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?*\}

    Sometimes it is simpler to provide all the data entry item definitions in
    form of a single list to __argument\_dialogbox__, and not as individual
    arguments\. The second format that is supported by __argument\_dialogbox__
    corresponds exactly to the first one, except that all item definitions are
    packed into a single list that is provided to __argument\_dialogbox__\.
    The previous example can therefore also be written in the following way:

    > set DialogResult \[__tepam::argument\_dialogbox \{__  
    > &nbsp;&nbsp;&nbsp;__\-title__ "Itinerary selection"  
    > &nbsp;&nbsp;&nbsp;__\-file__ \{*\-label "Itinerary report" \-variable report\_file*\}  
    > &nbsp;&nbsp;&nbsp;\.\.\.  
    > &nbsp;&nbsp;&nbsp;__\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\} __\}__\]



The commands __argument\_dialogbox__ as well as
__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ are exported from the
namespace __tepam__\. To use these commands without the __tepam::__
namespace prefix, it is sufficient to import them into the main namespace:

> __namespace import tepam::\*__  
>   
> set DialogResult \[__argument\_dialogbox__ \\  
> &nbsp;&nbsp;&nbsp;\-title "Itinerary selection"  
> &nbsp;&nbsp;&nbsp;\.\.\.

The following subsections explain the different argument item types that are
accepted by the __argument\_dialogbox__, classified into three groups\. The
first data entry item definition format will be used in the remaining document,
knowing that this format can always be transformed into the second format by
putting all arguments into a single list that is then provided to
__argument\_dialogbox__\.

## <a name='subsection1'></a>Context Definition Items

The first item group allows specifying some context aspects of an argument
dialog box\. These items are taking a simple character string as item attribute:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-<argument\_name>__ *string* \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

The following items are classified into this group:

  - \-title *string*

    The dialog box window title which is by default *Dialog* can be changed
    with the *\-title* item:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-title__ "System configuration" \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-window *string*

    The argument dialog box uses by default *\.dialog* as dialog top level
    window\. This path can be changed with the *\-window* item:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-window__ \.dialog \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-parent *string*

    By defining a parent window, the argument dialog box will be displayed
    beside this one\. Without explicit parent window definition, the top\-level
    window will be considered as parent window\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-parent__ \.my\_appl \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-context *string*

    If a context is defined the dialog box state, e\.g\. the entered data as well
    as the window size and position, is restored the next time the argument
    dialog box is called\. The assignment of a context allows saving the dialog
    box state in its context to distinguish between different usages of the
    argument dialog box\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;__\-context__ destination\_definitions \\  
> &nbsp;&nbsp;&nbsp;\.\.\.

## <a name='subsection2'></a>Formatting and Display Options

Especially for big, complex forms it becomes important that the different data
entry widgets are graphically well organized and commented to provide an
immediate and clear overview to the user\. A couple of items allow structuring
and commenting the dialog boxes\.

The items of this classification group require as item attributes a definition
list, which contains itself attribute name and value pairs:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-<argument\_name>__ \{   
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\-<attribute\_name> <attribute\_value>?*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\-<attribute\_name> <attribute\_value>?*  
> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*?\.\.\.?*  


>   
> &nbsp;&nbsp;&nbsp;\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

The following items are classified into this group:

  - \-frame *list*

    The *\-frame* item allows packing all following entry widgets into a
    labeled frame, until a next frame item is defined or until the last entry
................................................................................

      * \-label *string*

        An optional frame label can be specified with the *\-label* statement\.

    Example:

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{*\-label "Destination address"*\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

    To close an open frame without opening a new one, an empty list has to be
    provided to the *\-frame* statement\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-frame__ \{\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-sep \[const \{\{\}\}\]

    Entry widgets can be separated with the *\-sep* statement which doesn't
    require additional definitions\. The related definition list has to exist,
    but its content is ignored\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-sep__ \{\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-comment *string*

    Comments and descriptions can be added with the *\-text* attribute of the
    *\-comment* item\. Please note that each entry widget itself can also
    contain a *\-text* attribute for comments and descriptions\. But the
    *\-comment* item allows for example adding a description between two
    frames\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-comment__ \{*\-text "Specify bellow the destination address"*\}  
> &nbsp;&nbsp;&nbsp;\.\.\.

  - \-yscroll __0__&#124;__1__&#124;__auto__

    This attribute allows controlling an eventual vertical scrollbar\. Setting it
    to __0__ will permanently disable the scrollbar, setting it to __1__
    will enable it\. By default it is set to __auto__\. The scrollbar is
    enabled in this mode only if the vertical data entry form size exceeds 66%
    of the screen height\.

> tepam::argument\_dialogbox \\  
> &nbsp;&nbsp;&nbsp;\.\.\.  
> &nbsp;&nbsp;&nbsp;__\-yscroll__ __auto__  
> &nbsp;&nbsp;&nbsp;\.\.\.

## <a name='subsection3'></a>Global Custom Data Validation

This item group allows specifying global custom checks to validate the entered
data\.

  - \-validatecommand *script*

    Custom data checks can be performed via validation commands that are defined
    with the *\-valid