Tcl Library Source Code

Check-in [3d68643631]
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:Applied Arjen Markus' corrections and feedback.
Timelines: family | ancestors | descendants | both | doc-overhaul
Files: files | file ages | folders
SHA3-256: 3d68643631f1f208e93b2eb49e074147045cc6efa73abf941cfa43b1750fc496
User & Date: aku 2019-03-20 18:23:07
Context
2019-03-20
18:43
Reworked section explaining use of critcl by build system based on feedback from Arjen Markus. check-in: c58a3c19ac user: aku tags: doc-overhaul
18:23
Applied Arjen Markus' corrections and feedback. check-in: 3d68643631 user: aku tags: doc-overhaul
2019-03-17
19:59
Squash and replace unwanted smart quotes. check-in: 590e67f11c user: aku tags: doc-overhaul
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to devdoc/parts/b_critcl.inc.

4
5
6
7
8
9
10
11
12
13
14
15
16

17
18
19
20
21
22
23
[syscmd critcl]-based C code whose use will boost the performance of
the packages using them. As these accelerators are optional they are
not installed by default.

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

[para] To install Tcllib with the accelerators in a unix-type
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 {






|




|
>







4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[syscmd critcl]-based C code whose use will boost the performance of
the packages using them. As these accelerators are optional they are
not installed by default.

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

[para] To install Tcllib with the accelerators in a Unix-type
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 {

Changes to devdoc/parts/b_tooling.inc.

28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
..
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
..
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
The second form is required on Windows (without a Unix emulation),
except if the Tcl installation is configured to handle [file .tcl]
files on a double-click.

[enum]

In a unix-type environment, i.e. Linux, BSD and related, including OS
X, and Windows using some kind of unix-emulation like [syscmd MSYS],
[syscmd Cygwin], etc.) it is also possible to use

[example {
    ./configure
    make install
}]
................................................................................

[para] This will non-interactively install all packages, applications
found in Tcllib, and their manpages, in directories derived from what
[syscmd configure] found out about the system.

[list_end]

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

[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
................................................................................
targets found in [file Makefile.in].

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

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

[para][emph Attention] The installer will overwrite an existing
installation of a Tcllib with the same version without asking back
after the initial confirmation is given.

Further if the user chooses the same directory as chosen for/by
previous installations then these will be overwritten as well.






|







 







|







 







|








28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
..
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
..
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
The second form is required on Windows (without a Unix emulation),
except if the Tcl installation is configured to handle [file .tcl]
files on a double-click.

[enum]

In a Unix-type environment, i.e. Linux, BSD and related, including OS
X, and Windows using some kind of unix-emulation like [syscmd MSYS],
[syscmd Cygwin], etc.) it is also possible to use

[example {
    ./configure
    make install
}]
................................................................................

[para] This will non-interactively install all packages, applications
found in Tcllib, and their manpages, in directories derived from what
[syscmd configure] found out about the system.

[list_end]

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

[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
................................................................................
targets found in [file Makefile.in].

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

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

[para][emph Attention] The installer will overwrite an existing
installation of a Tcllib with the same version without asking back
after the initial confirmation is given.

Further if the user chooses the same directory as chosen for/by
previous installations then these will be overwritten as well.

Changes to devdoc/parts/d_branchflow.inc.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
..
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
and this exactly the case in the
[uri https://github.com/tcltk/tcllib/ {github mirror}] of Tcllib.

[para] In support of debugging, like searching for when an issue
appeared via bisection, each commit on this branch must pass the
entire testsuite of the collection.

[para] As fossil has no mechanism to enfore this 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
................................................................................
trunk developers are allowed to commit intermediate broken states of
their work. Only at the end, when the branch is considered ready for
merging will it be necessary to perform full validation.

[subsection {Version numbers}]

In Tcllib all changes to a package have to come with an increment of
its version number. With what part is incremented (patchlevel, minor,
major version) dependent 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
defered 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 association
version increments:

[list_begin definitions]
[def [term {D - documentation}]] No increment






|







 







|
|



|







10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
..
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
and this exactly the case in the
[uri https://github.com/tcltk/tcllib/ {github mirror}] of Tcllib.

[para] In support of debugging, like searching for when an issue
appeared via bisection, each commit on this branch must pass the
entire testsuite of the collection.

[para] As fossil has no mechanism to enforce this 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
................................................................................
trunk developers are allowed to commit intermediate broken states of
their work. Only at the end, when the branch is considered ready for
merging will it be necessary to perform full validation.

[subsection {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".

[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 association
version increments:

[list_begin definitions]
[def [term {D - documentation}]] No increment

Changes to devdoc/parts/d_dirlayout.inc.

31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
..
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
..
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
...
139
140
141
142
143
144
145
146
147
148
149
[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.

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

[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]]
................................................................................
[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 logner 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 .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]






|







 







|







 







|







 







|



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
..
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
..
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
...
139
140
141
142
143
144
145
146
147
148
149
[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.

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

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

Changes to devdoc/parts/d_documentation.inc.

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
..
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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/dptlite] 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.

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

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






|






|



|

|







 







|







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
..
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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.

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

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

Changes to devdoc/parts/d_maintain.inc.

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
..
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
       [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 immediatel 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].

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

       [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 above).

       [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






|







 







|





|






|







17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
..
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
       [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].

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

Changes to devdoc/parts/d_testing.inc.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
..
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
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 }]
................................................................................

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






|



|

|







 







|









|







 







|







9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
..
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
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 }]
................................................................................

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

Changes to devdoc/parts/d_testwrite.inc.

1
2
3
4
5
6
7
8
9
10
..
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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.
................................................................................
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. Equals one test case checking the behavior when the
	specified node is not a node a graph.

[para]  This often gives rise to code in the implementation which
	explicitly checks the assumption and throws a nice error.
	Instead of letting the algorithm fails later in some weird
	non-deterministic way.

[para]  It 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.


|







 







|
|


|
|


|







1
2
3
4
5
6
7
8
9
10
..
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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.
................................................................................
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.

Changes to devdoc/parts/rm_distribute.inc.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
[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/1246]
[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.







|







13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
[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.

Changes to 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
[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 accepts it as an application found in the
PATH (be it starkit or starpack).

[para] Tcllib requires 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 their directions please file a ticket against the
[term Critcl] project, and not Tcllib.
|










|










|


|

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
[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 accepts it as an application found in the
PATH (be it starkit or starpack).

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

Changes to devdoc/parts/rq_tcl.inc.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
..
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 possibilites use whatever you are comfortable
with, as long as it provides 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
................................................................................

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






|
|







 







|


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
..
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
................................................................................

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

Changes to devdoc/tcl_community_communication.man.

148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
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 leave people hurt, stop. There is no amount of
being "right" that makes up for someone leaving out 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.






|
|







148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
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.

Changes to devdoc/tcllib_releasemgr.man.

2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[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, his
or her 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.






|
|







2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[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.

Changes to devdoc/tcllib_sources.man.

28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
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 and 
[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






|
|







28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
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