Tcl Library Source Code

Check-in [6612c2b8a8]
Bounty program for improvements to Tcl and certain Tcl packages.

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

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

 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 +- +- +- ... The install hierarchy is: .../lib/tcllib +- +- +- ... 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.  < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < <     

  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) 

 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] 

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.

CVS Repository

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.

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.

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.

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.

• 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 after the release was executed.
 < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < <     

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   >  1  todo: finalize release, make candidate official 

   >  1  todo: open a candidate for release 

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

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

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

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

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

Recap

The CVS repository for Tcllib contains two main branches, the HEAD for development, and RELEASES as the staging area for official releases.

Dependencies

Creation of a new official release

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

1. Retrieve the sources at the current head from the CVS repository, using a command like
CVSROOT=:pserver:[email protected]:/cvsroot/tcllib 	  cvs -d${CVSROOT} co tcllib Vary this command according to taste as long as the overall meaning is not changed. Compression options and the like. 2. Tag these sources with a new branch tag for the new release of tcllib, like cvs -d${CVSROOT} rtag tcllib
3. Commit the changes, then update the working directory.
4. Use a tclsh to run the sak tool with the argument gendist, like
tclsh /path/to/tcllib/sak.tcl gendist
5. This results in the creation of a tcllib-VERSION directory in the current working directory, and of two archives, .zip, and .tar.gz. A starkit will be created if sdx is present in the PATH. If additionally a file named tclkit is present in the current working directory a starpack will be created too, using this tclkit as the runtime.
6. Now follow the instructions in the Sourceforge site documentation for uploading the archives generated by the last step to ftp://upload.sourceforge.net/incoming, and follow the procedures for creating packages and releases at Sourceforge.

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

 < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < <     

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

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

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

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

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

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

Tcl Library Source Code

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

Tcl Library Source Code

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

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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 "")
# NAME tcl\_community\_communication \- Tcl Community \- Kind Communication # Table Of Contents - [Table Of Contents](#toc) - [Description](#section1) - [Signatories](#section2) - [Authors](#section3) # 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\. # Signatories - Sean "the Hypnotoad" Woods - Andreas Kupries # Authors - Primary Sean "the Hypnotoad" Woods - Light editing Andreas Kupries 

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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 "")
# NAME tcllib\_devguide \- Tcllib \- The Developer's Guide # 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) # SYNOPSIS [__[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action*](#1) [__[Application](\.\./\.\./\.\./index\.md\#application)__ *name*](#2) [__Exclude__ *name*](#3) # 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\. # Commitments ## 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\. ## 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\. # Branching and Workflow ## 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\. ## 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\. ## 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\. ## 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 | grep tags__ * __fossil branch list | 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\. ## 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\. # Structural Overview ## 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\. ## 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\. ## 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" ???? ## 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\. # 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\. ## 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"\. ## 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\. ## 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$$\. ## 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 ... ## 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\. # 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\. ## 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\. ## 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\. ## 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\. ## 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\. # 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\. # 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: - __[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\. - __[Application](\.\./\.\./\.\./index\.md\#application)__ *name* Install the application with *name*, found in "apps"\. - __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\. 

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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 "")
# NAME tcllib\_install\_guide \- Tcllib \- The Installer's Guide # 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) # 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\. # 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\. ## 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)*\. ## 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\. # 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*$$\. ## 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\. ## 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\. ## 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__\. ## 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\. 

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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 "")
# NAME tcllib\_license \- Tcllib \- License # Table Of Contents - [Table Of Contents](#toc) - [Description](#section1) - [License](#section2) # 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\. # 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\. 

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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 "")
# NAME tcllib\_releasemgr \- Tcllib \- The Release Manager's Guide # 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) # 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\. # 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)\. # Tasks ## Start a release candidate todo: open a candidate for release ## 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\. ## Make it official todo: finalize release, make candidate official ## 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\. 

     > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >  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 "")
# NAME tcllib\_sources \- Tcllib \- How To Get The Sources # Table Of Contents - [Table Of Contents](#toc) - [Description](#section1) - [Source Location](#section2) - [Retrieval](#section3) - [Source Code Management](#section4) # 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\. # Source Location The official repository for Tcllib can be found at [http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib) # 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\. # Source Code Management For the curious $$or a developer\-to\-be$$, the sources are managed by the [Fossil SCM](http://www\.fossil\-scm\.org)\. Binaries for popular platforms can be found directly at its [download page](http://www\.fossil\-scm\.org/download\.html)\. With that tool available the full history can be retrieved via: fossil clone http://core.tcl-lang.org/tcllib tcllib.fossil followed by mkdir tcllib cd tcllib fossil open ../tcllib.fossil to get a checkout of the head of the trunk\. 

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

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

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

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

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

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

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

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

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

Changes to idoc/man/toc.n.

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

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

tcl_community_communication(n) 1 tcllib ""

Name

tcl_community_communication - Tcl Community - Kind Communication

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

Signatories

• Andreas Kupries

Authors

Primary

Light editing

Andreas Kupries



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

tcllib_devguide(n) 1 tcllib ""

Name

tcllib_devguide - Tcllib - The Developer's Guide

Synopsis

Description

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.

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

1. Tcllib - How To Get The Sources and

2. Tcllib - The Installer's Guide

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.

Commitments

Contributor

As a contributor to Tcllib you are committing yourself to:

1. keep the guidelines written down in Tcl Community - Kind Communication in your mind. The main point to take away from there is to be kind to each other.

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.

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 (as any contributor) in your mind. The main point to take away from there is to be kind to each other.

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

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

3. When stepping down without a replacement maintainer taking over the relevant packages have to be flagged as unmaintained.

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

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

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

2. Reviewing the aforementioned tickets, rejecting or applying them

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

4. Follow the Branching and Workflow of this guide.

Branching and Workflow

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, CRIMP, Kinetcl, etc.

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

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

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.

Trunk

The management and use of branches is an important part of working with a Distributed Version Control System (DVCS) like fossil.

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

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.

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 | grep tags
fossil branch list | 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.

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.

2. Merge the latest state of the trunk (see next definition).

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

4. Now merge to the trunk using

fossil update trunk     fossil merge --integrate YOUR_BRANCH
5. At this point the checkout should be in the same state as at the end of point (3) above, because we resolved any issues with the trunk already. Thus a simple

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

2. Merge to trunk

3. Validate again

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

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.

2. The package index ("pkgIndex.tcl")

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

Structural Overview

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.

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

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 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. Not relevant any longer with the switch to the fossil SCM.

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

????

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.

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 providing management operations, for example setting a list of standard Tcl shells to use.

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

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.

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

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

Help

Invoke the tool as

./sak.tcl help test

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

Documentation Tooling

The standard format used for documentation of packages and other things in Tcllib is 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.

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.

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.

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.

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.

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

2. Connected graph

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

2. Graph without weights at all.

3. 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, a writeup on how the Sqlite database engine is tested. Another article of interest might be 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.

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.

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:

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.

Application name

Install the application with name, found in "apps".

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.



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

tcllib_install_guide(n) 1 tcllib ""

Name

tcllib_install_guide - Tcllib - The Installer's Guide

Description

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.

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.

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

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.

2. Optionally, the critcl package (C embedding) for 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.

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

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, or the vendor of your distribution, and not Tcllib.

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

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.

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.

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, 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 has to be installed, and its tclsh should be placed on the (Unix) or associated with ".tcl" files (Windows).

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

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 is installed and available as well.

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

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.

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



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

Name

Description

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.

The collection is under the BSD 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.



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

tcllib_releasemgr(n) 1 tcllib ""

Name

tcllib_releasemgr - Tcllib - The Release Manager's Guide

Description

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.

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 first, if that was not done already. Here we assume that the sources are already available in a directory of your choice.

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.

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.

Start a release candidate

todo: open a candidate for release

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.

Make it official

todo: finalize release, make candidate official

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.

An existing event should be used as template.

2. Update a number of web locations:

3. Past Releases

4. http://www.tcl-lang.org/home/release.txt

5. http://www.tcl-lang.org/software/tcllib/*.tml

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

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

3. ***TODO*** mailing lists and other places to send notes to.



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

tcllib_sources(n) 1 tcllib ""

Name

tcllib_sources - Tcllib - How To Get The Sources

Description

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.

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.

2. Tcllib - The Developer's Guide.

respectively.

Source Location

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

Retrieval

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

2. Go to the "Timeline".

3. Choose the revision you wish to have.

5. On that page, choose either the "ZIP" or "Tarball" link to get a copy of this revision in the format of your choice.

Source Code Management

For the curious (or a developer-to-be), the sources are managed by the Fossil SCM. Binaries for popular platforms can be found directly at its download page.

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 idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html.

 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 ... 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241  [keywords {doctools language}] [keywords {doctools markup}] [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]

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

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   | |  176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 ... 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241  [keywords {doctools language}] [keywords {doctools markup}] [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end]

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

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 

Changes to idoc/www/tcllib/toc.html.

 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465  
Space insertation and removal
tcl::transform::zlib zlib (de)compression
tclDES Implementation of the DES and triple-DES ciphers
tclDESjr Implementation of the DES and triple-DES ciphers
tcldocstrip Tcl-based Docstrip Processor
tcllib_ip IPv4 and IPv6 address manipulation
tclrep/machineparameters Compute double precision machine parameters.
tepam An introduction into TEPAM, Tcl's Enhanced Procedure and Argument ManagerSpace insertation and removal
tcl::transform::zlib zlib (de)compression
tcl_community_communication Tcl Community - Kind Communication
tclDES Implementation of the DES and triple-DES ciphers
tclDESjr Implementation of the DES and triple-DES ciphers
tcldocstrip Tcl-based Docstrip Processor
tcllib_devguide Tcllib - The Developer's Guide
tcllib_install_guide Tcllib - The Installer's Guide
tcllib_ip IPv4 and IPv6 address manipulation
tcllib_releasemgr Tcllib - The Release Manager's Guide
tcllib_sources Tcllib - How To Get The Sources
tclrep/machineparameters Compute double precision machine parameters.
tepam An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
  > > > > | | > > > > > > > > > > > > > > > > > > > >  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   

Changes to installer.tcl.

 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292   # Starpack. No defaults for location. } else { # Starkit, or unwrapped. Derive defaults location from the # location of the executable running the installer, or the # location of its library. # For a starkit [info library] is inside the running # tclkit. Detect this and derive the lcoation from the # location of the executable itself for that case. if {[string match [info nameofexecutable]* [info library]]} { # Starkit set libdir [file join [file dirname [file dirname [info nameofexecutable]]] lib] } else { # Unwrapped.   |  278 279 280 281 282 283 284 285 286 287 288 289 290 291 292   # Starpack. No defaults for location. } else { # Starkit, or unwrapped. Derive defaults location from the # location of the executable running the installer, or the # location of its library. # For a starkit [info library] is inside the running # tclkit. Detect this and derive the location from the # location of the executable itself for that case. if {[string match [info nameofexecutable]* [info library]]} { # Starkit set libdir [file join [file dirname [file dirname [info nameofexecutable]]] lib] } else { # Unwrapped. 

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

Changes to modules/aes/aes.man.

 160 161 162 163 164 165 166 167 168  [list_end] [section AUTHORS] Thorsten Schloermann, Pat Thoyts [vset CATEGORY aes] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  160 161 162 163 164 165 166 167 168  [list_end] [section AUTHORS] Thorsten Schloermann, Pat Thoyts [vset CATEGORY aes] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/amazon-s3/S3.man.

 1442 1443 1444 1445 1446 1447 1448 1449 1450  each moving on to the next unstarted task as it finishes each. This is still being designed, and it is intended primarily to be run on Amazon's Elastic Compute Cloud. [include ../common-text/tls-security-notes.inc] [vset CATEGORY amazon-s3] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  1442 1443 1444 1445 1446 1447 1448 1449 1450  each moving on to the next unstarted task as it finishes each. This is still being designed, and it is intended primarily to be run on Amazon's Elastic Compute Cloud. [include ../common-text/tls-security-notes.inc] [vset CATEGORY amazon-s3] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/amazon-s3/xsxp.man.

 129 130 131 132 133 134 135 136 137  [call [cmd xsxp::prettyprint] [arg pxml] [opt [arg chan]]] This outputs to [arg chan] (default stdout) a pretty-printed version of [arg pxml]. [list_end] [vset CATEGORY amazon-s3] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  129 130 131 132 133 134 135 136 137  [call [cmd xsxp::prettyprint] [arg pxml] [opt [arg chan]]] This outputs to [arg chan] (default stdout) a pretty-printed version of [arg pxml]. [list_end] [vset CATEGORY amazon-s3] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/asn/asn.man.

 456 457 458 459 460 461 462 463 464  [section EXAMPLES] Examples for the usage of this package can be found in the implementation of package [package ldap]. [vset CATEGORY asn] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  456 457 458 459 460 461 462 463 464  [section EXAMPLES] Examples for the usage of this package can be found in the implementation of package [package ldap]. [vset CATEGORY asn] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/base32/base32.man.

 67 68 69 70 71 72 73 74 75   5 F 14 O 23 X 6 G 15 P 24 Y 7 H 16 Q 25 Z 8 I 17 R 26 2 }] [vset CATEGORY base32] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  67 68 69 70 71 72 73 74 75   5 F 14 O 23 X 6 G 15 P 24 Y 7 H 16 Q 25 Z 8 I 17 R 26 2 }] [vset CATEGORY base32] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/base32/base32core.man.

 58 59 60 61 62 63 64 65 66  [enum] The length of the input is not a multiple of eight, [enum] The padding appears not at the end of input, but in the middle, [enum] The padding has not of length six, four, three, or one characters, [list_end] [list_end] [vset CATEGORY base32] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  58 59 60 61 62 63 64 65 66  [enum] The length of the input is not a multiple of eight, [enum] The padding appears not at the end of input, but in the middle, [enum] The padding has not of length six, four, three, or one characters, [list_end] [list_end] [vset CATEGORY base32] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/base32/base32hex.man.

 70 71 72 73 74 75 76 77 78   5 5 14 E 23 N 6 6 15 F 24 O 7 7 16 G 25 P 8 8 17 H 26 Q }] [vset CATEGORY base32] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  70 71 72 73 74 75 76 77 78   5 5 14 E 23 N 6 6 15 F 24 O 7 7 16 G 25 P 8 8 17 H 26 Q }] [vset CATEGORY base32] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/base64/ascii85.man.

 67 68 69 70 71 72 73 74 75  [list_begin enum] [enum] [uri http://en.wikipedia.org/wiki/Ascii85] [enum] Postscript Language Reference Manual, 3rd Edition, page 131. [uri http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf] [list_end] [vset CATEGORY base64] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  67 68 69 70 71 72 73 74 75  [list_begin enum] [enum] [uri http://en.wikipedia.org/wiki/Ascii85] [enum] Postscript Language Reference Manual, 3rd Edition, page 131. [uri http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf] [list_end] [vset CATEGORY base64] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/base64/base64.man.

 62 63 64 65 66 67 68 69 70  % set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"] % set encoded [base64::encode $chemical] Q+KCiEjigoHigoBO4oKET+KCgg== % set caffeine [encoding convertfrom utf-8 [base64::decode$encoded]] }] [vset CATEGORY base64] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  62 63 64 65 66 67 68 69 70  % set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"] % set encoded [base64::encode $chemical] Q+KCiEjigoHigoBO4oKET+KCgg== % set caffeine [encoding convertfrom utf-8 [base64::decode$encoded]] }] [vset CATEGORY base64] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/base64/uuencode.man.

 89 90 91 92 93 94 95 96 97  [para] [example { % uuencode::uudecode $d {hello.txt 644 {Hello World}} }] [vset CATEGORY base64] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  89 90 91 92 93 94 95 96 97  [para] [example { % uuencode::uudecode$d {hello.txt 644 {Hello World}} }] [vset CATEGORY base64] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/base64/yencode.man.

 88 89 90 91 92 93 94 95 96  [section References] [list_begin enum] [enum] [uri http://www.yenc.org/yenc-draft.1.3.txt] [list_end] [vset CATEGORY base64] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  88 89 90 91 92 93 94 95 96  [section References] [list_begin enum] [enum] [uri http://www.yenc.org/yenc-draft.1.3.txt] [list_end] [vset CATEGORY base64] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/bee/bee.man.

 335 336 337 338 339 340 341 342 343  By wrapping an integer number into [const i]...[const e] the format makes sure that they are different from strings, which all begin with a digit. [section EXAMPLES] [vset CATEGORY bee] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  335 336 337 338 339 340 341 342 343  By wrapping an integer number into [const i]...[const e] the format makes sure that they are different from strings, which all begin with a digit. [section EXAMPLES] [vset CATEGORY bee] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/bench/bench.man.

 288 289 290 291 292 293 294 295 296  The benchmark could be executed, however the result from its body did not match the declared expectations. [list_end] [list_end] [vset CATEGORY bench] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  288 289 290 291 292 293 294 295 296  The benchmark could be executed, however the result from its body did not match the declared expectations. [list_end] [list_end] [vset CATEGORY bench] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/bench/bench_intro.man.

 83 84 85 86 87 88 89 90 91  [section {HISTORICAL NOTES}] This module and package have been derived from Jeff Hobbs' [syscmd tclbench] application for the benchmarking of the Tcl core and its ancestor [file runbench.tcl]. [vset CATEGORY bench] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  83 84 85 86 87 88 89 90 91  [section {HISTORICAL NOTES}] This module and package have been derived from Jeff Hobbs' [syscmd tclbench] application for the benchmarking of the Tcl core and its ancestor [file runbench.tcl]. [vset CATEGORY bench] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/bench/bench_lang_intro.man.

 145 146 147 148 149 150 151 152 153  to understand the formal [term {bench language specfication}]. It will also serve as the detailed specification and cheat sheet for all available commands and their syntax. [para] [vset CATEGORY bench] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  145 146 147 148 149 150 151 152 153  to understand the formal [term {bench language specfication}]. It will also serve as the detailed specification and cheat sheet for all available commands and their syntax. [para] [vset CATEGORY bench] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/bench/bench_lang_spec.man.

 124 125 126 127 128 129 130 131 132  responsibility is to create whatever resources are needed by the body to run without failing. [list_end] [list_end] [vset CATEGORY bench] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  124 125 126 127 128 129 130 131 132  responsibility is to create whatever resources are needed by the body to run without failing. [list_end] [list_end] [vset CATEGORY bench] [include ../common-text/feedback.inc] [manpage_end] 

 57 58 59 60 61 62 63 64 65  [para] and automatically detects which format is used by the input file. [list_end] [vset CATEGORY bench] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  57 58 59 60 61 62 63 64 65  [para] and automatically detects which format is used by the input file. [list_end] [vset CATEGORY bench] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/bench/bench_wcsv.man.

 46 47 48 49 50 51 52 53 54  For other formatting styles see the packages [package bench] and [package bench::out::text] which provide commands to format benchmark results in raw form, or for human consumption, respectively. [list_end] [vset CATEGORY bench] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  46 47 48 49 50 51 52 53 54  For other formatting styles see the packages [package bench] and [package bench::out::text] which provide commands to format benchmark results in raw form, or for human consumption, respectively. [list_end] [vset CATEGORY bench] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/bench/bench_wtext.man.

 47 48 49 50 51 52 53 54 55  For other formatting styles see the packages [package bench] and [package bench::out::csv] which provide commands to format benchmark results in raw form, or as importable CSV data, respectively. [list_end] [vset CATEGORY bench] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  47 48 49 50 51 52 53 54 55  For other formatting styles see the packages [package bench] and [package bench::out::csv] which provide commands to format benchmark results in raw form, or as importable CSV data, respectively. [list_end] [vset CATEGORY bench] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/bibtex/bibtex.man.

 172 173 174 175 176 177 178 179 180  replacement strings. This command has the correct signature for use as a [option -stringcommand] callback in an invokation of the command [cmd ::bibtex::parse]. [list_end] [vset CATEGORY bibtex] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  172 173 174 175 176 177 178 179 180  replacement strings. This command has the correct signature for use as a [option -stringcommand] callback in an invokation of the command [cmd ::bibtex::parse]. [list_end] [vset CATEGORY bibtex] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/blowfish/blowfish.man.

 156 157 158 159 160 161 162 163 164  [list_end] [section AUTHORS] Frank Pilhofer, Pat Thoyts [vset CATEGORY blowfish] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  156 157 158 159 160 161 162 163 164  [list_end] [section AUTHORS] Frank Pilhofer, Pat Thoyts [vset CATEGORY blowfish] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/cache/async.man.

 136 137 138 139 140 141 142 143 144  This method resets the state of either the specified [arg key] or of all keys known to the cache, making it unkown. This forces future [method get]-requests to reload the information from the provider. [list_end] [vset CATEGORY cache] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  136 137 138 139 140 141 142 143 144  This method resets the state of either the specified [arg key] or of all keys known to the cache, making it unkown. This forces future [method get]-requests to reload the information from the provider. [list_end] [vset CATEGORY cache] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/clock/iso8601.man.

 39 40 41 42 43 44 45 46 47  [option -locale], and [option -timezone] of the builtin command [cmd {clock scan}]. [list_end] [vset CATEGORY clock::iso8601] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  39 40 41 42 43 44 45 46 47  [option -locale], and [option -timezone] of the builtin command [cmd {clock scan}]. [list_end] [vset CATEGORY clock::iso8601] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/clock/rfc2822.man.

 19 20 21 22 23 24 25 26 27  This command parses an RFC2822 date string and returns the given date in seconds since epoch. An error is thrown if the command is unable to parse the date. [list_end] [vset CATEGORY clock::rfc2822] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  19 20 21 22 23 24 25 26 27  This command parses an RFC2822 date string and returns the given date in seconds since epoch. An error is thrown if the command is unable to parse the date. [list_end] [vset CATEGORY clock::rfc2822] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/cmdline/cmdline.man.

 196 197 198 199 200 201 202 203 204  This example, taken (and slightly modified) from the package [package fileutil], shows how to use cmdline. First, a list of options is created, then the 'args' list is passed to cmdline for processing. Subsequently, different options are checked to see if they have been passed to the script, and what their value is. [vset CATEGORY cmdline] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  196 197 198 199 200 201 202 203 204  This example, taken (and slightly modified) from the package [package fileutil], shows how to use cmdline. First, a list of options is created, then the 'args' list is passed to cmdline for processing. Subsequently, different options are checked to see if they have been passed to the script, and what their value is. [vset CATEGORY cmdline] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/comm/comm.man.

 1224 1225 1226 1227 1228 1229 1230 1231 1232  [para] Andreas Kupries <[email protected]> uses [package comm] and has built a simple nameserver as part of his Pool library. See [uri http://www.purl.org/net/akupries/soft/pool/index.htm]. [vset CATEGORY comm] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  1224 1225 1226 1227 1228 1229 1230 1231 1232  [para] Andreas Kupries <[email protected]> uses [package comm] and has built a simple nameserver as part of his Pool library. See [uri http://www.purl.org/net/akupries/soft/pool/index.htm]. [vset CATEGORY comm] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/comm/comm_wire.man.

 276 277 278 279 280 281 282 283 284   negotiated. IOW if v2 is used the client will not see a version reply during the negotiation handshake. }] [vset CATEGORY comm] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  276 277 278 279 280 281 282 283 284   negotiated. IOW if v2 is used the client will not see a version reply during the negotiation handshake. }] [vset CATEGORY comm] [include ../common-text/feedback.inc] [manpage_end] 

Name change from modules/doctools2base/include/feedback.inc to modules/common-text/feedback.inc.

Changes to modules/control/control.man.

 157 158 159 160 161 162 163 164 165  % catch a 1 % catch b 0 }] [vset CATEGORY control] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  157 158 159 160 161 162 163 164 165  % catch a 1 % catch b 0 }] [vset CATEGORY control] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/coroutine/coro_auto.man.

 38 39 40 41 42 43 44 45 46  [def [cmd global]] [def [cmd read]] [def [cmd update]] [def [cmd vwait]] [list_end] [vset CATEGORY coroutine] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  38 39 40 41 42 43 44 45 46  [def [cmd global]] [def [cmd read]] [def [cmd update]] [def [cmd vwait]] [list_end] [vset CATEGORY coroutine] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/coroutine/tcllib_coroutine.man.

 109 110 111 112 113 114 115 116 117  This command causes the coroutine calling it to wait for a write to the named namespace variable [arg varname]. [list_end] [vset CATEGORY coroutine] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  109 110 111 112 113 114 115 116 117  This command causes the coroutine calling it to wait for a write to the named namespace variable [arg varname]. [list_end] [vset CATEGORY coroutine] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/counter/counter.man.

 242 243 244 245 246 247 248 249 250  Resets the counter with the name [arg tag] to an initial state. The [arg args] determine the new characteristics of the counter. They have the same meaning as described for [cmd ::counter::init]. [list_end] [vset CATEGORY counter] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  242 243 244 245 246 247 248 249 250  Resets the counter with the name [arg tag] to an initial state. The [arg args] determine the new characteristics of the counter. They have the same meaning as described for [cmd ::counter::init]. [list_end] [vset CATEGORY counter] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/crc/cksum.man.

 123 124 125 126 127 128 129 130 131  2609532967 }] [section AUTHORS] Pat Thoyts [vset CATEGORY crc] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  123 124 125 126 127 128 129 130 131  2609532967 }] [section AUTHORS] Pat Thoyts [vset CATEGORY crc] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/crc/crc16.man.

 141 142 143 144 145 146 147 148 149  51675 }] [section AUTHORS] Pat Thoyts [vset CATEGORY crc] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  141 142 143 144 145 146 147 148 149  51675 }] [section AUTHORS] Pat Thoyts [vset CATEGORY crc] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/crc/crc32.man.

 144 145 146 147 148 149 150 151 152  3964322768 }] [section AUTHORS] Pat Thoyts [vset CATEGORY crc] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  144 145 146 147 148 149 150 151 152  3964322768 }] [section AUTHORS] Pat Thoyts [vset CATEGORY crc] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/crc/sum.man.

 100 101 102 103 104 105 106 107 108  13392 }] [section AUTHORS] Pat Thoyts [vset CATEGORY crc] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  100 101 102 103 104 105 106 107 108  13392 }] [section AUTHORS] Pat Thoyts [vset CATEGORY crc] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/cron/cron.man.

 178 179 180 181 182 183 184 185 186  [para] [arg newtime] is expressed in absolute milliseconds since the beginning of the epoch. [list_end] [para] [vset CATEGORY odie] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  178 179 180 181 182 183 184 185 186  [para] [arg newtime] is expressed in absolute milliseconds since the beginning of the epoch. [list_end] [para] [vset CATEGORY odie] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/csv/csv.man.

 239 240 241 242 243 244 245 246 247  d) (the empty string) }] instead. As can be seen only item (d) is different, now the empty string instead of a ". [vset CATEGORY csv] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  239 240 241 242 243 244 245 246 247  d) (the empty string) }] instead. As can be seen only item (d) is different, now the empty string instead of a ". [vset CATEGORY csv] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/debug/debug.man.

 239 240 241 242 243 244 245 246 247  [para] The result of the method is the specified text. [comment {= = == === ===== ======== ============= =====================}] [list_end] [vset CATEGORY debug] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  239 240 241 242 243 244 245 246 247  [para] The result of the method is the specified text. [comment {= = == === ===== ======== ============= =====================}] [list_end] [vset CATEGORY debug] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/debug/debug_caller.man.

 36 37 38 39 40 41 42 43 44  The main anticipiated use case for this is the exclusion of arguments expected to contain large Tcl values, i.e. long lists, large dictionaries, etc. to prevent them from overwhelming the narrative. [list_end] [vset CATEGORY debug] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  36 37 38 39 40 41 42 43 44  The main anticipiated use case for this is the exclusion of arguments expected to contain large Tcl values, i.e. long lists, large dictionaries, etc. to prevent them from overwhelming the narrative. [list_end] [vset CATEGORY debug] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/debug/debug_heartbeat.man.

 35 36 37 38 39 40 41 42 43  counter and the time in milliseconds since the last beat, thus providing insight into timing variationsn and deviations from the nominal [arg delta]. [list_end] [vset CATEGORY debug] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  35 36 37 38 39 40 41 42 43  counter and the time in milliseconds since the last beat, thus providing insight into timing variationsn and deviations from the nominal [arg delta]. [list_end] [vset CATEGORY debug] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/debug/debug_timestamp.man.

 26 27 28 29 30 31 32 33 34  last call, making it useful in a tag-specific prefix to automatically provide caller information for all uses of the tag. Or in a message, when only specific places need such detail. [list_end] [vset CATEGORY debug] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  26 27 28 29 30 31 32 33 34  last call, making it useful in a tag-specific prefix to automatically provide caller information for all uses of the tag. Or in a message, when only specific places need such detail. [list_end] [vset CATEGORY debug] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/defer/defer.man.

 94 95 96 97 98 99 100 101 102  [enum] [list_end] [section AUTHORS] Roy Keene [vset CATEGORY defer] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  94 95 96 97 98 99 100 101 102  [enum] [list_end] [section AUTHORS] Roy Keene [vset CATEGORY defer] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/des/des.man.

 198 199 200 201 202 203 204 205 206  [section "AUTHORS"] Jochen C Loewer, Mac Cody, Pat Thoyts [vset CATEGORY des] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  198 199 200 201 202 203 204 205 206  [section "AUTHORS"] Jochen C Loewer, Mac Cody, Pat Thoyts [vset CATEGORY des] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/des/tcldes.man.

 18 19 20 21 22 23 24 25 26  [para] The [package tclDES] package is a helper package for [package des]. [para] Please see the documentation of [package des] for details. [vset CATEGORY des] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  18 19 20 21 22 23 24 25 26  [para] The [package tclDES] package is a helper package for [package des]. [para] Please see the documentation of [package des] for details. [vset CATEGORY des] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/des/tcldesjr.man.

 18 19 20 21 22 23 24 25 26  [para] The [package tclDESjr] package is a helper package for [package des]. [para] Please see the documentation of [package des] for details. [vset CATEGORY des] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  18 19 20 21 22 23 24 25 26  [para] The [package tclDESjr] package is a helper package for [package des]. [para] Please see the documentation of [package des] for details. [vset CATEGORY des] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/dicttool/dicttool.man.

 70 71 72 73 74 75 76 77 78   } } }] [list_end] [vset CATEGORY dict] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  70 71 72 73 74 75 76 77 78   } } }] [list_end] [vset CATEGORY dict] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/dns/tcllib_dns.man.

 283 284 285 286 287 288 289 290 291  [list_end] [section AUTHORS] Pat Thoyts [vset CATEGORY dns] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  283 284 285 286 287 288 289 290 291  [list_end] [section AUTHORS] Pat Thoyts [vset CATEGORY dns] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/dns/tcllib_ip.man.

 443 444 445 446 447 448 449 450 451  [list_end] [section AUTHORS] Pat Thoyts [vset CATEGORY dns] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  443 444 445 446 447 448 449 450 451  [list_end] [section AUTHORS] Pat Thoyts [vset CATEGORY dns] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/changelog.man.

 79 80 81 82 83 84 85 86 87  command merges all of them into a single structure, and collapses multiple entries for the same date and author into a single entry. The new structure is returned as the result of the command. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  79 80 81 82 83 84 85 86 87  command merges all of them into a single structure, and collapses multiple entries for the same date and author into a single entry. The new structure is returned as the result of the command. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/cvs.man.

 93 94 95 96 97 98 99 100 101  logs. It takes this information and converts it into a text in the format of a ChangeLog as accepted and generated by [syscmd emacs]. The constructed text is returned as the result of the command. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  93 94 95 96 97 98 99 100 101  logs. It takes this information and converts it into a text in the format of a ChangeLog as accepted and generated by [syscmd emacs]. The constructed text is returned as the result of the command. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/docidx.man.

 402 403 404 405 406 407 408 409 410  This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  402 403 404 405 406 407 408 409 410  This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/docidx_intro.man.

 98 99 100 101 102 103 104 105 106  respectively. They are described in their own sets of documents, starting at the [term {doctoc introduction}] and the [term {doctools introduction}], respectively. [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  98 99 100 101 102 103 104 105 106  respectively. They are described in their own sets of documents, starting at the [term {doctoc introduction}] and the [term {doctools introduction}], respectively. [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/docidx_lang_cmdref.man.

 108 109 110 111 112 113 114 115 116  Templating. In this form the command is replaced by the value of the named document variable [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  108 109 110 111 112 113 114 115 116  Templating. In this form the command is replaced by the value of the named document variable [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/docidx_lang_faq.man.

 20 21 22 23 24 25 26 27 28  [section OVERVIEW] [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  20 21 22 23 24 25 26 27 28  [section OVERVIEW] [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/docidx_lang_intro.man.

 206 207 208 209 210 211 212 213 214  On the other hand, docidx is perfectly suited for the automatic generation from doctools documents, and this is the route Tcllib's easy and simple [syscmd dtplite] goes, creating an index for a set of documents behind the scenes, without the writer having to do so on their own. [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  206 207 208 209 210 211 212 213 214  On the other hand, docidx is perfectly suited for the automatic generation from doctools documents, and this is the route Tcllib's easy and simple [syscmd dtplite] goes, creating an index for a set of documents behind the scenes, without the writer having to do so on their own. [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/docidx_lang_syntax.man.

 112 113 114 115 116 117 118 119 120  [enum][cmd rb], or [enum][cmd vset] (1-argument form). [list_end] [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  112 113 114 115 116 117 118 119 120  [enum][cmd rb], or [enum][cmd vset] (1-argument form). [list_end] [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/docidx_plugin_apiref.man.

 413 414 415 416 417 418 419 420 421  [para] The formatted text is expected as the result of the command, and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  413 414 415 416 417 418 419 420 421  [para] The formatted text is expected as the result of the command, and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctoc.man.

 402 403 404 405 406 407 408 409 410  This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  402 403 404 405 406 407 408 409 410  This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctoc_intro.man.

 97 98 99 100 101 102 103 104 105  of [term {keyword indices}], and general documentation, respectively. They are described in their own sets of documents, starting at the [term {docidx introduction}] and the [term {doctools introduction}], respectively. [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  97 98 99 100 101 102 103 104 105  of [term {keyword indices}], and general documentation, respectively. They are described in their own sets of documents, starting at the [term {docidx introduction}] and the [term {doctools introduction}], respectively. [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctoc_lang_cmdref.man.

 119 120 121 122 123 124 125 126 127  Templating. In this form the command is replaced by the value of the named document variable [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  119 120 121 122 123 124 125 126 127  Templating. In this form the command is replaced by the value of the named document variable [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctoc_lang_faq.man.

 20 21 22 23 24 25 26 27 28  [section OVERVIEW] [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  20 21 22 23 24 25 26 27 28  [section OVERVIEW] [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctoc_lang_intro.man.

 289 290 291 292 293 294 295 296 297  On the other hand, doctoc is perfectly suited for the automatic generation from doctools documents, and this is the route Tcllib's easy and simple [syscmd dtplite] goes, creating a table of contents for a set of documents behind the scenes, without the writer having to do so on their own. [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  289 290 291 292 293 294 295 296 297  On the other hand, doctoc is perfectly suited for the automatic generation from doctools documents, and this is the route Tcllib's easy and simple [syscmd dtplite] goes, creating a table of contents for a set of documents behind the scenes, without the writer having to do so on their own. [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctoc_lang_syntax.man.

 97 98 99 100 101 102 103 104 105  division = DIVISION_START contents DIVISION_END }] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  97 98 99 100 101 102 103 104 105  division = DIVISION_START contents DIVISION_END }] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctoc_plugin_apiref.man.

 413 414 415 416 417 418 419 420 421  [para] The formatted text is expected as the result of the command, and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  413 414 415 416 417 418 419 420 421  [para] The formatted text is expected as the result of the command, and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctools.man.

 567 568 569 570 571 572 573 574 575  This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  567 568 569 570 571 572 573 574 575  This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctools_intro.man.

 95 96 97 98 99 100 101 102 103  respectively. They are described in their own sets of documents, starting at the [term {docidx introduction}] and the [term {doctoc introduction}], respectively. [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  95 96 97 98 99 100 101 102 103  respectively. They are described in their own sets of documents, starting at the [term {docidx introduction}] and the [term {doctoc introduction}], respectively. [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctools_lang_cmdref.man.

 462 463 464 465 466 467 468 469 470  Text markup. The argument is marked up as the name of a [term widget]. The text may have other markup already applied to it. Main use is the highlighting of widget names in free-form text. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  462 463 464 465 466 467 468 469 470  Text markup. The argument is marked up as the name of a [term widget]. The text may have other markup already applied to it. Main use is the highlighting of widget names in free-form text. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctools_lang_faq.man.

 20 21 22 23 24 25 26 27 28  [section OVERVIEW] [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  20 21 22 23 24 25 26 27 28  [section OVERVIEW] [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctools_lang_intro.man.

 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 ... 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 ... 609 610 611 612 613 614 615 616 617  [keywords {doctools language}] [keywords {doctools markup}] [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] }] This also shows us that all doctools documents are split into two parts, the [term header] and the [term body]. Everything coming before [lb][cmd description][rb] belongs to the header, and everything coming after belongs to the body, with the whole document bracketed by the ................................................................................ Remember that the whitespace is optional. The document [example { [manpage_begin NAME SECTION VERSION] [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] [require PACKAGE VERSION][require PACKAGE][description] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] }] has the same meaning as the example before. [para] ................................................................................ To be able to validate a document while writing it, it is also recommended to familiarize oneself with one of the applications for the processing and conversion of doctools documents, i.e. either Tcllib's easy and simple [syscmd dtplite], or Tclapps' ultra-configurable [syscmd dtp]. [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   | | |  69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 ... 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 ... 609 610 611 612 613 614 615 616 617  [keywords {doctools language}] [keywords {doctools markup}] [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] }] This also shows us that all doctools documents are split into two parts, the [term header] and the [term body]. Everything coming before [lb][cmd description][rb] belongs to the header, and everything coming after belongs to the body, with the whole document bracketed by the ................................................................................ Remember that the whitespace is optional. The document [example { [manpage_begin NAME SECTION VERSION] [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] [require PACKAGE VERSION][require PACKAGE][description] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] }] has the same meaning as the example before. [para] ................................................................................ To be able to validate a document while writing it, it is also recommended to familiarize oneself with one of the applications for the processing and conversion of doctools documents, i.e. either Tcllib's easy and simple [syscmd dtplite], or Tclapps' ultra-configurable [syscmd dtp]. [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctools_lang_syntax.man.

 134 135 136 137 138 139 140 141 142  enum_list = [ ] { ENUM paras } item_list = [ ] { ITEM paras } optd_list = [ ] { OPT_DEF paras } tkoptd_list = [ ] { TKOPTION_DEF paras } }] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  134 135 136 137 138 139 140 141 142  enum_list = [ ] { ENUM paras } item_list = [ ] { ITEM paras } optd_list = [ ] { OPT_DEF paras } tkoptd_list = [ ] { TKOPTION_DEF paras } }] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/doctools_plugin_apiref.man.

 470 471 472 473 474 475 476 477 478  [para] The formatted text is expected as the result of the command, and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  470 471 472 473 474 475 476 477 478  [para] The formatted text is expected as the result of the command, and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools/mpexpand.man.

 99 100 101 102 103 104 105 106 107  [section NOTES] [para] Possible future formats are plain text, pdf and postscript. [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  99 100 101 102 103 104 105 106 107  [section NOTES] [para] Possible future formats are plain text, pdf and postscript. [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2base/html_cssdefaults.man.

 32 33 34 35 36 37 38 39 40  This command returns the text of the default CSS style to use for HTML markup generated by the various HTML export plugins. [list_end] [vset CATEGORY doctools] [include include/feedback.inc] [manpage_end]   |  32 33 34 35 36 37 38 39 40  This command returns the text of the default CSS style to use for HTML markup generated by the various HTML export plugins. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2base/nroff_manmacros.man.

 32 33 34 35 36 37 38 39 40  This command returns the text of the default CSS style to use for NROFF generated by the various NROFF export plugins. [list_end] [vset CATEGORY doctools] [include include/feedback.inc] [manpage_end]   |  32 33 34 35 36 37 38 39 40  This command returns the text of the default CSS style to use for NROFF generated by the various NROFF export plugins. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2base/tcl_parse.man.

 176 177 178 179 180 181 182 183 184  [enum] All leaves of the tree are either Text or Command nodes. Word nodes cannot be leaves. [list_end] [vset CATEGORY doctools] [include include/feedback.inc] [manpage_end]   |  176 177 178 179 180 181 182 183 184  [enum] All leaves of the tree are either Text or Command nodes. Word nodes cannot be leaves. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2base/tcllib_msgcat.man.

 59 60 61 62 63 64 65 66 67  "doctools::msgcat::[arg prefix]::[var langcode]", with [arg prefix] the argument to the command, and the [var langcode] supplied by the result of [cmd msgcat::mcpreferences]. [list_end] [vset CATEGORY doctools] [include include/feedback.inc] [manpage_end]   |  59 60 61 62 63 64 65 66 67  "doctools::msgcat::[arg prefix]::[var langcode]", with [arg prefix] the argument to the command, and the [var langcode] supplied by the result of [cmd msgcat::mcpreferences]. [list_end] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/idx_container.man.

 288 289 290 291 292 293 294 295 296  In that case an error will be thrown if the container has no export manager attached to it. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  288 289 290 291 292 293 294 295 296  In that case an error will be thrown if the container has no export manager attached to it. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/idx_export.man.

 301 302 303 304 305 306 307 308 309   the command [cmd export]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  301 302 303 304 305 306 307 308 309   the command [cmd export]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/idx_import.man.

 387 388 389 390 391 392 393 394 395   the command [cmd import]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  387 388 389 390 391 392 393 394 395   the command [cmd import]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/idx_introduction.man.

 138 139 140 141 142 143 144 145 146  the [manpage {DocTools - Tables Of Contents}] and the [manpage {DocTools - General}], respectively. [section {Package Overview}] [include include/dependencies.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  138 139 140 141 142 143 144 145 146  the [manpage {DocTools - Tables Of Contents}] and the [manpage {DocTools - General}], respectively. [section {Package Overview}] [include include/dependencies.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/idx_parse.man.

 167 168 169 170 171 172 173 174 175  [list_end] [list_end] [include include/format/docidx.inc] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  167 168 169 170 171 172 173 174 175  [list_end] [list_end] [include include/format/docidx.inc] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/idx_structure.man.

 121 122 123 124 125 126 127 128 129  [sectref {Keyword index serialization format}]. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  121 122 123 124 125 126 127 128 129  [sectref {Keyword index serialization format}]. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/include/export/plugin.inc.

 47 48 49 50 51 52 53 54 55  [list_end] [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] [include ../../../doctools2base/include/feedback.inc] [manpage_end]   |  47 48 49 50 51 52 53 54 55  [list_end] [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] [include ../../../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/include/import/plugin.inc.

 48 49 50 51 52 53 54 55 56  [list_end] [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] [include ../../../doctools2base/include/feedback.inc] [manpage_end]   |  48 49 50 51 52 53 54 55 56  [list_end] [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] [include ../../../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2idx/include/msgcat.inc.

 38 39 40 41 42 43 44 45 46  [section API] This package has no exported API. [vset CATEGORY doctools] [include ../../doctools2base/include/feedback.inc] [manpage_end]   |  38 39 40 41 42 43 44 45 46  [section API] This package has no exported API. [vset CATEGORY doctools] [include ../../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/include/export/plugin.inc.

 47 48 49 50 51 52 53 54 55  [list_end] [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] [include ../../../doctools2base/include/feedback.inc] [manpage_end]   |  47 48 49 50 51 52 53 54 55  [list_end] [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] [include ../../../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/include/import/plugin.inc.

 48 49 50 51 52 53 54 55 56  [list_end] [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] [include ../../../doctools2base/include/feedback.inc] [manpage_end]   |  48 49 50 51 52 53 54 55 56  [list_end] [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] [include ../../../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/include/msgcat.inc.

 38 39 40 41 42 43 44 45 46  [section API] This package has no exported API. [vset CATEGORY doctools] [include ../../doctools2base/include/feedback.inc] [manpage_end]   |  38 39 40 41 42 43 44 45 46  [section API] This package has no exported API. [vset CATEGORY doctools] [include ../../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/toc_container.man.

 362 363 364 365 366 367 368 369 370  In that case an error will be thrown if the container has no export manager attached to it. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  362 363 364 365 366 367 368 369 370  In that case an error will be thrown if the container has no export manager attached to it. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/toc_export.man.

 299 300 301 302 303 304 305 306 307   the command [cmd export]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  299 300 301 302 303 304 305 306 307   the command [cmd export]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/toc_import.man.

 387 388 389 390 391 392 393 394 395   the command [cmd import]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  387 388 389 390 391 392 393 394 395   the command [cmd import]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/toc_introduction.man.

 135 136 137 138 139 140 141 142 143  the [manpage {DocTools - Keyword Indices}] and the [manpage {DocTools - General}], respectively. [section {Package Overview}] [include include/dependencies.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  135 136 137 138 139 140 141 142 143  the [manpage {DocTools - Keyword Indices}] and the [manpage {DocTools - General}], respectively. [section {Package Overview}] [include include/dependencies.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/toc_parse.man.

 167 168 169 170 171 172 173 174 175  [list_end] [list_end] [include include/format/doctoc.inc] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  167 168 169 170 171 172 173 174 175  [list_end] [list_end] [include include/format/doctoc.inc] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/doctools2toc/toc_structure.man.

 143 144 145 146 147 148 149 150 151  section [sectref {ToC serialization format}]. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  143 144 145 146 147 148 149 150 151  section [sectref {ToC serialization format}]. [list_end] [include include/serialization.inc] [vset CATEGORY doctools] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/dtplite/pkg_dtplite.man.

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

Changes to modules/exif/exif.man.

 72 73 74 75 76 77 78 79 80  [section ACKNOWLEDGEMENTS] This code is a direct translation of version 1.3 of exif.pl by Chris Breeze. See the source for full headers, references, etc. [vset CATEGORY exif] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  72 73 74 75 76 77 78 79 80  [section ACKNOWLEDGEMENTS] This code is a direct translation of version 1.3 of exif.pl by Chris Breeze. See the source for full headers, references, etc. [vset CATEGORY exif] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fileutil/fileutil.man.

 514 515 516 517 518 519 520 521 522  option to prevent the traverser from following symbolic links, like so: [include include/cross-index-trav.inc] [list_end] [vset CATEGORY fileutil] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  514 515 516 517 518 519 520 521 522  option to prevent the traverser from following symbolic links, like so: [include include/cross-index-trav.inc] [list_end] [vset CATEGORY fileutil] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fileutil/multi.man.

 48 49 50 51 52 53 54 55 56  The result of the command is the result generated by the last file command it executed. [list_end] [vset CATEGORY fileutil] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  48 49 50 51 52 53 54 55 56  The result of the command is the result generated by the last file command it executed. [list_end] [vset CATEGORY fileutil] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fileutil/multiop.man.

 394 395 396 397 398 399 400 401 402   into /scratch \\ but not *.html not index \\ the index \\ as pkgIndex.tcl }] [vset CATEGORY fileutil] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  394 395 396 397 398 399 400 401 402   into /scratch \\ but not *.html not index \\ the index \\ as pkgIndex.tcl }] [vset CATEGORY fileutil] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fileutil/paths.man.

 68 69 70 71 72 73 74 75 76  Unknown paths are ignored without error. The result of the command is the empty string. [list_end] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  68 69 70 71 72 73 74 75 76  Unknown paths are ignored without error. The result of the command is the empty string. [list_end] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fileutil/traverse.man.

 157 158 159 160 161 162 163 164 165  traverser from following symbolic links, like so: [include include/cross-index-trav.inc] [list_end] [vset CATEGORY fileutil] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  157 158 159 160 161 162 163 164 165  traverser from following symbolic links, like so: [include include/cross-index-trav.inc] [list_end] [vset CATEGORY fileutil] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ftp/ftp.man.

 432 433 434 435 436 437 438 439 440  [para] An update command placed in the procedure [cmd ::ftp::DisplayMsg] may run into persistent errors or infinite loops. The solution to this problem is to use [cmd {update idletasks}] instead of [cmd update]. [vset CATEGORY ftp] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  432 433 434 435 436 437 438 439 440  [para] An update command placed in the procedure [cmd ::ftp::DisplayMsg] may run into persistent errors or infinite loops. The solution to this problem is to use [cmd {update idletasks}] instead of [cmd update]. [vset CATEGORY ftp] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ftp/ftp_geturl.man.

 49 50 51 52 53 54 55 56 57  The attributes of the link, including the path it refers to. [list_end] [list_end] [vset CATEGORY ftp] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  49 50 51 52 53 54 55 56 57  The attributes of the link, including the path it refers to. [list_end] [list_end] [vset CATEGORY ftp] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ftpd/ftpd.man.

 271 272 273 274 275 276 277 278 279  Accessible to all callbacks and all filesystem commands (which are a special form of callback) and contains the handle of the socket channel which was active when the callback was invoked. [list_end] [vset CATEGORY ftpd] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  271 272 273 274 275 276 277 278 279  Accessible to all callbacks and all filesystem commands (which are a special form of callback) and contains the handle of the socket channel which was active when the callback was invoked. [list_end] [vset CATEGORY ftpd] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fumagic/cfront.man.

 63 64 65 66 67 68 69 70 71  The name of each new procedure is derived from the name of the file/directory used in its creation, with file/directory [file FOO] causing the creation of procedure [const ::fileutil::magic::/FOO::run]. [list_end] [vset CATEGORY {fileutil :: magic}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  63 64 65 66 67 68 69 70 71  The name of each new procedure is derived from the name of the file/directory used in its creation, with file/directory [file FOO] causing the creation of procedure [const ::fileutil::magic::/FOO::run]. [list_end] [vset CATEGORY {fileutil :: magic}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fumagic/cgen.man.

 55 56 57 58 59 60 61 62 63  The generated script makes extensive use of the commands provided by the recognizer runtime package [package fileutil::magic::rt] to perform its duties. [list_end] [vset CATEGORY {fileutil :: magic}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  55 56 57 58 59 60 61 62 63  The generated script makes extensive use of the commands provided by the recognizer runtime package [package fileutil::magic::rt] to perform its duties. [list_end] [vset CATEGORY {fileutil :: magic}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fumagic/filetypes.man.

 54 55 56 57 58 59 60 61 62  This site contains the current sources for the file command, including the magic definitions used by it. The latter were used by us to generate this recognizer. [list_end] [vset CATEGORY {fileutil :: magic}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  54 55 56 57 58 59 60 61 62  This site contains the current sources for the file command, including the magic definitions used by it. The latter were used by us to generate this recognizer. [list_end] [vset CATEGORY {fileutil :: magic}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/fumagic/rtcore.man.

 243 244 245 246 247 248 249 250 251  [def [const ledate]] see above, stored in small/little endian [def [const ldate]] 32-bit integer timestamp, stored in native endianess [def [const beldate]] see above, stored in big endian [def [const leldate]] see above, stored in small/little endian [list_end] [vset CATEGORY {fileutil :: magic}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  243 244 245 246 247 248 249 250 251  [def [const ledate]] see above, stored in small/little endian [def [const ldate]] 32-bit integer timestamp, stored in native endianess [def [const beldate]] see above, stored in big endian [def [const leldate]] see above, stored in small/little endian [list_end] [vset CATEGORY {fileutil :: magic}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/gpx/gpx.man.

 150 151 152 153 154 155 156 157 158  [list_end] [section AUTHOR] Keith Vetter [vset CATEGORY gpx] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  150 151 152 153 154 155 156 157 158  [list_end] [section AUTHOR] Keith Vetter [vset CATEGORY gpx] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_fa/dacceptor.man.

 94 95 96 97 98 99 100 101 102  [list_end] [para] [section EXAMPLES] [vset CATEGORY grammar_fa] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  94 95 96 97 98 99 100 101 102  [list_end] [para] [section EXAMPLES] [vset CATEGORY grammar_fa] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_fa/dexec.man.

 175 176 177 178 179 180 181 182 183  [list_end] [para] [section EXAMPLES] [vset CATEGORY grammar_fa] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  175 176 177 178 179 180 181 182 183  [list_end] [para] [section EXAMPLES] [vset CATEGORY grammar_fa] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_fa/fa.man.

 644 645 646 647 648 649 650 651 652  [para] Transducers are not handled by this package. They will get their own package in the future. [vset CATEGORY grammar_fa] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  644 645 646 647 648 649 650 651 652  [para] Transducers are not handled by this package. They will get their own package in the future. [vset CATEGORY grammar_fa] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_fa/faop.man.

 472 473 474 475 476 477 478 479 480  [list_end] [para] [section EXAMPLES] [vset CATEGORY grammar_fa] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  472 473 474 475 476 477 478 479 480  [list_end] [para] [section EXAMPLES] [vset CATEGORY grammar_fa] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_me/gasm.man.

 431 432 433 434 435 436 437 438 439  [para] The command returns the empty string as its result. [list_end] [vset CATEGORY grammar_me] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  431 432 433 434 435 436 437 438 439  [para] The command returns the empty string as its result. [list_end] [vset CATEGORY grammar_me] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_me/me_ast.man.

 126 127 128 129 130 131 132 133 134  This new attribute is defined for all nodes, and contains the locations from attribute [term range] translated into line number and column index. Lines are counted from 1, columns are counted from 0. [list_end] [vset CATEGORY grammar_me] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  126 127 128 129 130 131 132 133 134  This new attribute is defined for all nodes, and contains the locations from attribute [term range] translated into line number and column index. Lines are counted from 1, columns are counted from 0. [list_end] [vset CATEGORY grammar_me] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_me/me_cpu.man.

 281 282 283 284 285 286 287 288 289  [call [arg meName] [method destroy]] This method deletes the object and releases all resurces it claimed. [list_end] [vset CATEGORY grammar_me] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  281 282 283 284 285 286 287 288 289  [call [arg meName] [method destroy]] This method deletes the object and releases all resurces it claimed. [list_end] [vset CATEGORY grammar_me] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_me/me_cpucore.man.

 366 367 368 369 370 371 372 373 374  [para] [term nc], the nonterminal cache is keyed by nonterminal name and location, each value a four-element list containing current location, match status, semantic value, and error status, in this order. [vset CATEGORY grammar_me] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  366 367 368 369 370 371 372 373 374  [para] [term nc], the nonterminal cache is keyed by nonterminal name and location, each value a four-element list containing current location, match status, semantic value, and error status, in this order. [vset CATEGORY grammar_me] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_me/me_intro.man.

 86 87 88 89 90 91 92 93 94  Core functionality for state manipulation and stepping used in the bytecode based implementation of ME virtual machines. [list_end] [para] [vset CATEGORY grammar_me] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  86 87 88 89 90 91 92 93 94  Core functionality for state manipulation and stepping used in the bytecode based implementation of ME virtual machines. [list_end] [para] [vset CATEGORY grammar_me] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_me/me_tcl.man.

 335 336 337 338 339 340 341 342 343  The command takes the marker as argument as it comes from the Tcl stack, not the machine state. It replaces [term ias_mpop]. [list_end] [para] [vset CATEGORY grammar_me] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  335 336 337 338 339 340 341 342 343  The command takes the marker as argument as it comes from the Tcl stack, not the machine state. It replaces [term ias_mpop]. [list_end] [para] [vset CATEGORY grammar_me] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_me/me_util.man.

 75 76 77 78 79 80 81 82 83  If a [arg root] node is specified the AST is generated from that node downward. Otherwise the root of the tree object is used as the starting point. [list_end] [vset CATEGORY grammar_me] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  75 76 77 78 79 80 81 82 83  If a [arg root] node is specified the AST is generated from that node downward. Otherwise the root of the tree object is used as the starting point. [list_end] [vset CATEGORY grammar_me] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_me/me_vm.man.

 655 656 657 658 659 660 661 662 663  This instruction pops an entry from the AST Marker stack [term MS] and discards it. [list_end] [vset CATEGORY grammar_me] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  655 656 657 658 659 660 661 662 663  This instruction pops an entry from the AST Marker stack [term MS] and discards it. [list_end] [vset CATEGORY grammar_me] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_peg/peg.man.

 713 714 715 716 717 718 719 720 721  [enum] [uri {http://scifac.ru.ac.za/compilers/} \ {Compilers and Compiler Generators}], an online book using CoCo/R, a generator for recursive descent parsers. [list_end] [vset CATEGORY grammar_peg] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  713 714 715 716 717 718 719 720 721  [enum] [uri {http://scifac.ru.ac.za/compilers/} \ {Compilers and Compiler Generators}], an online book using CoCo/R, a generator for recursive descent parsers. [list_end] [vset CATEGORY grammar_peg] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/grammar_peg/peg_interp.man.

 114 115 116 117 118 119 120 121 122  described in section [sectref-external {AST VALUES}] of document [term grammar::me_ast]. [list_end] [para] [vset CATEGORY grammar_peg] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  114 115 116 117 118 119 120 121 122  described in section [sectref-external {AST VALUES}] of document [term grammar::me_ast]. [list_end] [para] [vset CATEGORY grammar_peg] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/hook/hook.man.

 367 368 369 370 371 372 373 374 375  All bindings involving [widget .view] are deleted. [section Credits] Hook has been designed and implemented by William H. Duquette. [vset CATEGORY hook] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  367 368 369 370 371 372 373 374 375  All bindings involving [widget .view] are deleted. [section Credits] Hook has been designed and implemented by William H. Duquette. [vset CATEGORY hook] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/html/html.man.

 468 469 470 471 472 473 474 475 476  [enum] XHTML11 [enum] XHTMLB [list_end] [list_end] [vset CATEGORY html] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  468 469 470 471 472 473 474 475 476  [enum] XHTML11 [enum] XHTMLB [list_end] [list_end] [vset CATEGORY html] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/htmlparse/htmlparse.man.

 258 259 260 261 262 263 264 265 266  [cmd ::htmlparse::2tree]. It removes all nodes representing forms and form elements. Its only argument is the name of the tree to cut down. [list_end] [vset CATEGORY htmlparse] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  258 259 260 261 262 263 264 265 266  [cmd ::htmlparse::2tree]. It removes all nodes representing forms and form elements. Its only argument is the name of the tree to cut down. [list_end] [vset CATEGORY htmlparse] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/http/autoproxy.man.

 208 209 210 211 212 213 214 215 216  At this time only Basic authentication (1) (2) is supported. It is planned to add support for Digest (2) and NTLM in the future. [section AUTHORS] Pat Thoyts [vset CATEGORY {http :: autoproxy}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  208 209 210 211 212 213 214 215 216  At this time only Basic authentication (1) (2) is supported. It is planned to add support for Digest (2) and NTLM in the future. [section AUTHORS] Pat Thoyts [vset CATEGORY {http :: autoproxy}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/httpd/httpd.man.

 57 58 59 60 61 62 63 64 65  [include build/reply.man] [include build/content.man] [section AUTHORS] Sean Woods [vset CATEGORY network] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  57 58 59 60 61 62 63 64 65  [include build/reply.man] [include build/content.man] [section AUTHORS] Sean Woods [vset CATEGORY network] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ident/ident.man.

 46 47 48 49 50 51 52 53 54  to the RFC. A detailed error message is returned under the [const error] key. [list_end] [list_end] [vset CATEGORY ident] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  46 47 48 49 50 51 52 53 54  to the RFC. A detailed error message is returned under the [const error] key. [list_end] [list_end] [vset CATEGORY ident] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/imap4/imap4.man.

 358 359 360 361 362 363 364 365 366 367 368  Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, March 2003, [uri http://www.rfc-editor.org/rfc/rfc3501.txt] [para] OpenSSL, [uri http://www.openssl.org/] [vset CATEGORY imap4] [include ../doctools2base/include/feedback.inc] Only a small part of rfc3501 implemented. [manpage_end]   |  358 359 360 361 362 363 364 365 366 367 368  Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, March 2003, [uri http://www.rfc-editor.org/rfc/rfc3501.txt] [para] OpenSSL, [uri http://www.openssl.org/] [vset CATEGORY imap4] [include ../common-text/feedback.inc] Only a small part of rfc3501 implemented. [manpage_end] 

Changes to modules/inifile/ini.man.

 92 93 94 95 96 97 98 99 100  Reads and sets the comment character. Lines that begin with this character are treated as comments. When comments are written out each line is preceded by this character. The default is [const \;]. [list_end] [vset CATEGORY inifile] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  92 93 94 95 96 97 98 99 100  Reads and sets the comment character. Lines that begin with this character are treated as comments. When comments are written out each line is preceded by this character. The default is [const \;]. [list_end] [vset CATEGORY inifile] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/interp/deleg_method.man.

 41 42 43 44 45 46 47 48 49  returns the result from the remote method as its own result. If however the option [option -async] was specified then the generated method will not wait for a result and return immediately. [list_end] [vset CATEGORY interp] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  41 42 43 44 45 46 47 48 49  returns the result from the remote method as its own result. If however the option [option -async] was specified then the generated method will not wait for a result and return immediately. [list_end] [vset CATEGORY interp] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/interp/deleg_proc.man.

 39 40 41 42 43 44 45 46 47  returns the result from the remote procedure as its own result. If however the option [option -async] was specified then the generated procedure will not wait for a result and return immediately. [list_end] [vset CATEGORY interp] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  39 40 41 42 43 44 45 46 47  returns the result from the remote procedure as its own result. If however the option [option -async] was specified then the generated procedure will not wait for a result and return immediately. [list_end] [vset CATEGORY interp] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/interp/tcllib_interp.man.

 66 67 68 69 70 71 72 73 74  [para] The result of the command is the empty string. [list_end] [vset CATEGORY interp] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  66 67 68 69 70 71 72 73 74  [para] The result of the command is the empty string. [list_end] [vset CATEGORY interp] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/irc/irc.man.

 232 233 234 235 236 237 238 239 240  [call [cmd msg]] Returns the message portion of the command (the part after the :). [list_end] [vset CATEGORY irc] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  232 233 234 235 236 237 238 239 240  [call [cmd msg]] Returns the message portion of the command (the part after the :). [list_end] [vset CATEGORY irc] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/javascript/javascript.man.

 88 89 90 91 92 93 94 95 96  checked. The [arg parentName] argument is the name of the child's parent html checkbox object. The [arg childName] argument is the name of child html checkbox object to create. [list_end] [vset CATEGORY javascript] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  88 89 90 91 92 93 94 95 96  checked. The [arg parentName] argument is the name of the child's parent html checkbox object. The [arg childName] argument is the name of child html checkbox object to create. [list_end] [vset CATEGORY javascript] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/jpeg/jpeg.man.

 188 189 190 191 192 193 194 195 196  can only work with files cant write exif data gps exif data not parsed makernote data not yet implemented [vset CATEGORY jpeg] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  188 189 190 191 192 193 194 195 196  can only work with files cant write exif data gps exif data not parsed makernote data not yet implemented [vset CATEGORY jpeg] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/json/json.man.

 106 107 108 109 110 111 112 113 114  }] [section RELATED] To write json, instead of parsing it, see package [package json::write]. [vset CATEGORY json] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  106 107 108 109 110 111 112 113 114  }] [section RELATED] To write json, instead of parsing it, see package [package json::write]. [vset CATEGORY json] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/json/json_write.man.

 84 85 86 87 88 89 90 91 92  [para] [section RELATED] To parse json, instead of writing it, see package [package json]. [vset CATEGORY json] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  84 85 86 87 88 89 90 91 92  [para] [section RELATED] To parse json, instead of writing it, see package [package json]. [vset CATEGORY json] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/lambda/lambda.man.

 81 82 83 84 85 86 87 88 89  [list_end] [section AUTHORS] Andreas Kupries [vset CATEGORY lambda] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  81 82 83 84 85 86 87 88 89  [list_end] [section AUTHORS] Andreas Kupries [vset CATEGORY lambda] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/lazyset/lazyset.man.

 72 73 74 75 76 77 78 79 80   puts $simple }] [section AUTHORS] Roy Keene [vset CATEGORY utility] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  72 73 74 75 76 77 78 79 80   puts$simple }] [section AUTHORS] Roy Keene [vset CATEGORY utility] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ldap/ldap.man.

 541 542 543 544 545 546 547 548 549   puts "" } ldap::unbind $handle ldap::disconnect$handle }] [vset CATEGORY ldap] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  541 542 543 544 545 546 547 548 549   puts "" } ldap::unbind $handle ldap::disconnect$handle }] [vset CATEGORY ldap] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ldap/ldapx.man.

 766 767 768 769 770 771 772 773 774   liout destroy liin destroy }] [section References] [vset CATEGORY ldap] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  766 767 768 769 770 771 772 773 774   liout destroy liin destroy }] [section References] [vset CATEGORY ldap] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/log/log.man.

 281 282 283 284 285 286 287 288 289  [emph Note] that by default all messages with levels [const warning] down to [const debug] are suppressed. This is done intentionally, because (we believe that) in most situations debugging output is not wanted. Most people wish to have such output only when actually debugging an application. [vset CATEGORY log] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  281 282 283 284 285 286 287 288 289  [emph Note] that by default all messages with levels [const warning] down to [const debug] are suppressed. This is done intentionally, because (we believe that) in most situations debugging output is not wanted. Most people wish to have such output only when actually debugging an application. [vset CATEGORY log] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/log/logger.man.

 389 390 391 392 393 394 395 396 397   # install as logproc ${log}::logproc debug log_local_var } ] [vset CATEGORY logger] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  389 390 391 392 393 394 395 396 397   # install as logproc${log}::logproc debug log_local_var } ] [vset CATEGORY logger] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/log/loggerAppender.man.

 57 58 59 60 61 62 63 64 65  See [cmd ::logger::appender::colorConsole] for a description of the applicable options. [list_end] [vset CATEGORY logger] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  57 58 59 60 61 62 63 64 65  See [cmd ::logger::appender::colorConsole] for a description of the applicable options. [list_end] [vset CATEGORY logger] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/log/loggerUtils.man.

 141 142 143 144 145 146 147 148 149   logger::utils::applyAppender -appender console set log [logger::init applyAppender-3] ${log}::error "this is an error" }] [list_end] [vset CATEGORY logger] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  141 142 143 144 145 146 147 148 149   logger::utils::applyAppender -appender console set log [logger::init applyAppender-3]${log}::error "this is an error" }] [list_end] [vset CATEGORY logger] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/markdown/markdown.man.

 45 46 47 48 49 50 51 52 53  [call [cmd ::Markdown::reset_lang_counter]] Reset the language counters. [list_end] [vset CATEGORY textutil] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  45 46 47 48 49 50 51 52 53  [call [cmd ::Markdown::reset_lang_counter]] Reset the language counters. [list_end] [vset CATEGORY textutil] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/bigfloat.man.

 424 425 426 427 428 429 430 431 432  set sinProduct [lb]mul [lb]sin $angle1[rb] [lb]sin$angle2[rb][rb] set cosProduct [lb]mul [lb]cos $angle1[rb] [lb]cos$angle2[rb][rb] set angle3 [lb]asin [lb]add [lb]mul $sinProduct [lb]cos$opposite3[rb][rb] $cosProduct[rb][rb] puts "angle3 : [lb]tostr [lb]rad2deg$angle3[rb][rb]" [example_end] [vset CATEGORY {math :: bignum :: float}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  424 425 426 427 428 429 430 431 432  set sinProduct [lb]mul [lb]sin $angle1[rb] [lb]sin$angle2[rb][rb] set cosProduct [lb]mul [lb]cos $angle1[rb] [lb]cos$angle2[rb][rb] set angle3 [lb]asin [lb]add [lb]mul $sinProduct [lb]cos$opposite3[rb][rb] $cosProduct[rb][rb] puts "angle3 : [lb]tostr [lb]rad2deg$angle3[rb][rb]" [example_end] [vset CATEGORY {math :: bignum :: float}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/bignum.man.

 220 221 222 223 224 225 226 227 228  [call [cmd ::math::bignum::bits] [arg bignum]] Return the number of bits needed to represent bignum in radix 2. [list_end] [para] [vset CATEGORY {math :: bignum}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  220 221 222 223 224 225 226 227 228  [call [cmd ::math::bignum::bits] [arg bignum]] Return the number of bits needed to represent bignum in radix 2. [list_end] [para] [vset CATEGORY {math :: bignum}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/calculus.man.

 443 444 445 446 447 448 449 450 451   set length 100.0 set y [lb]::math::calculus::boundaryValueSecondOrder \ coeffs force {0.0 1.0} [lb]list $length 0.0[rb] 100[rb] [example_end] [vset CATEGORY {math :: calculus}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  443 444 445 446 447 448 449 450 451   set length 100.0 set y [lb]::math::calculus::boundaryValueSecondOrder \ coeffs force {0.0 1.0} [lb]list$length 0.0[rb] 100[rb] [example_end] [vset CATEGORY {math :: calculus}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/combinatorics.man.

 100 101 102 103 104 105 106 107 108  Results are returned as a floating point number precise to better than nine significant digits provided that [arg w] and [arg z] are both at least 1. [list_end] [vset CATEGORY math] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  100 101 102 103 104 105 106 107 108  Results are returned as a floating point number precise to better than nine significant digits provided that [arg w] and [arg z] are both at least 1. [list_end] [vset CATEGORY math] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/constants.man.

 128 129 130 131 132 133 134 135 136  [def [const onesixth]] One sixth (0.1666....) [def [const huge]] (Approximately) largest number [def [const tiny]] (Approximately) smallest number not equal zero [def [const eps]] Smallest number such that 1+eps != 1 [list_end] [vset CATEGORY {math :: constants}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  128 129 130 131 132 133 134 135 136  [def [const onesixth]] One sixth (0.1666....) [def [const huge]] (Approximately) largest number [def [const tiny]] (Approximately) smallest number not equal zero [def [const eps]] Smallest number such that 1+eps != 1 [list_end] [vset CATEGORY {math :: constants}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/decimal.man.

 191 192 193 194 195 196 197 198 199  Rounds [emph decimal] to [emph digits] number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow the result is the same as for round-down. [list_end] [para] [vset CATEGORY decimal] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  191 192 193 194 195 196 197 198 199  Rounds [emph decimal] to [emph digits] number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow the result is the same as for round-down. [list_end] [para] [vset CATEGORY decimal] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/fourier.man.

 126 127 128 129 130 131 132 133 134  [arg_def list in_data] List of data (amplitudes) [list_end] [para] [list_end] [vset CATEGORY {math :: fourier}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  126 127 128 129 130 131 132 133 134  [arg_def list in_data] List of data (amplitudes) [list_end] [para] [list_end] [vset CATEGORY {math :: fourier}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/fuzzy.man.

 125 126 127 128 129 130 131 132 133  APL QUOTE QUAD 8(3):16-23, March 1978. [para] D. Knuth, Art of Computer Programming, Vol. 1, Problem 1.2.4-5. [vset CATEGORY {math :: fuzzy}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  125 126 127 128 129 130 131 132 133  APL QUOTE QUAD 8(3):16-23, March 1978. [para] D. Knuth, Art of Computer Programming, Vol. 1, Problem 1.2.4-5. [vset CATEGORY {math :: fuzzy}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/interpolate.man.

 291 292 293 294 295 296 297 298 299  0.8: 4.11 0.9: 3.95675857843 1.0: 4.12 }] As you can see, the values at the abscissae are reproduced perfectly. [vset CATEGORY {math :: interpolate}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  291 292 293 294 295 296 297 298 299  0.8: 4.11 0.9: 3.95675857843 1.0: 4.12 }] As you can see, the values at the abscissae are reproduced perfectly. [vset CATEGORY {math :: interpolate}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/linalg.man.

 960 961 962 963 964 965 966 967 968  namespace eval compute { rename ::scale scaleTk scaleTk .scale ... } }] [vset CATEGORY {math :: linearalgebra}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  960 961 962 963 964 965 966 967 968  namespace eval compute { rename ::scale scaleTk scaleTk .scale ... } }] [vset CATEGORY {math :: linearalgebra}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/machineparameters.man.

 183 184 185 186 187 188 189 190 191  [call [arg objectname] [method print]] Print machine parameters on standard output. [list_end] [vset CATEGORY math] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  183 184 185 186 187 188 189 190 191  [call [arg objectname] [method print]] Print machine parameters on standard output. [list_end] [vset CATEGORY math] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/math.man.

 118 119 120 121 122 123 124 125 126  [call [cmd ::math::sum] [arg value] [opt [arg {value ...}]]] Return the sum of one or more numeric values. [list_end] [vset CATEGORY math] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  118 119 120 121 122 123 124 125 126  [call [cmd ::math::sum] [arg value] [opt [arg {value ...}]]] Return the sum of one or more numeric values. [list_end] [vset CATEGORY math] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/math_geometry.man.

 607 608 609 610 611 612 613 614 615  [list_begin enumerated] [enum] [uri http:/wiki.tcl.tk/12070 {Polygon Intersection}] [enum] [uri http://en.wikipedia.org/wiki/Line-line_intersection] [enum] [uri http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/] [list_end] [vset CATEGORY {math :: geometry}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  607 608 609 610 611 612 613 614 615  [list_begin enumerated] [enum] [uri http:/wiki.tcl.tk/12070 {Polygon Intersection}] [enum] [uri http://en.wikipedia.org/wiki/Line-line_intersection] [enum] [uri http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/] [list_end] [vset CATEGORY {math :: geometry}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/numtheory.dtx.

 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775  % \section*{Closings} % % \begin{tcl} %<*man> [list_end] [vset CATEGORY {math :: numtheory}] [include ../doctools2base/include/feedback.inc] [manpage_end] % % \end{tcl} % % \begin{tcl} %testsuiteCleanup % \end{tcl}   |  1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775  % \section*{Closings} % % \begin{tcl} %<*man> [list_end] [vset CATEGORY {math :: numtheory}] [include ../common-text/feedback.inc] [manpage_end] % % \end{tcl} % % \begin{tcl} %testsuiteCleanup % \end{tcl} 

Changes to modules/math/numtheory.man.

 197 198 199 200 201 202 203 204 205  [arg_def integer N in] Number in question [list_end] [list_end] [vset CATEGORY {math :: numtheory}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  197 198 199 200 201 202 203 204 205  [arg_def integer N in] Number in question [list_end] [list_end] [vset CATEGORY {math :: numtheory}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/optimize.man.

 317 318 319 320 321 322 323 324 325  [para] The theory of linear programming is the subject of many a text book and the Simplex algorithm that is implemented here is the best-known method to solve this type of problems, but it is not the only one. [vset CATEGORY {math :: optimize}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  317 318 319 320 321 322 323 324 325  [para] The theory of linear programming is the subject of many a text book and the Simplex algorithm that is implemented here is the best-known method to solve this type of problems, but it is not the only one. [vset CATEGORY {math :: optimize}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/pca.man.

 128 129 130 131 132 133 134 135 136  [section EXAMPLE] TODO: NIST example [vset CATEGORY PCA] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  128 129 130 131 132 133 134 135 136  [section EXAMPLE] TODO: NIST example [vset CATEGORY PCA] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/polynomials.man.

 211 212 213 214 215 216 217 218 219  To recognise that a polynomial definition is indeed a correct definition, it consists of a list of two elements: the keyword "POLYNOMIAL" and the list of coefficients in descending order. The latter makes it easier to implement Horner's rule. [vset CATEGORY {math :: polynomials}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  211 212 213 214 215 216 217 218 219  To recognise that a polynomial definition is indeed a correct definition, it consists of a list of two elements: the keyword "POLYNOMIAL" and the list of coefficients in descending order. The latter makes it easier to implement Horner's rule. [vset CATEGORY {math :: polynomials}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/qcomplex.man.

 294 295 296 297 298 299 300 301 302  The complex power to be used [list_end] [list_end] [vset CATEGORY {math :: complexnumbers}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  294 295 296 297 298 299 300 301 302  The complex power to be used [list_end] [list_end] [vset CATEGORY {math :: complexnumbers}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/rational_funcs.man.

 178 179 180 181 182 183 184 185 186  [section "REMARKS ON THE IMPLEMENTATION"] The implementation of the rational functions relies on the math::polynomials package. For further remarks see the documentation on that package. [vset CATEGORY {math :: rationalfunctions}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  178 179 180 181 182 183 184 185 186  [section "REMARKS ON THE IMPLEMENTATION"] The implementation of the rational functions relies on the math::polynomials package. For further remarks see the documentation on that package. [vset CATEGORY {math :: rationalfunctions}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/roman.man.

 43 44 45 46 47 48 49 50 51   [list_end] Of these commands both [emph toroman] and [emph tointeger] are exported for easier use. The other two are not, as they could interfer or be confused with existing Tcl commands. [vset CATEGORY {math :: roman}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  43 44 45 46 47 48 49 50 51   [list_end] Of these commands both [emph toroman] and [emph tointeger] are exported for easier use. The other two are not, as they could interfer or be confused with existing Tcl commands. [vset CATEGORY {math :: roman}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/romberg.man.

 332 333 334 335 336 337 338 339 340  foreach { value error } [romberg_sine f -1.0 1.0] break puts [format "integral is %.6g +/- %.6g" $value$error] integral is 3.97746 +/- 2.3557e-010 }] [vset CATEGORY {math :: calculus}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  332 333 334 335 336 337 338 339 340  foreach { value error } [romberg_sine f -1.0 1.0] break puts [format "integral is %.6g +/- %.6g" $value$error] integral is 3.97746 +/- 2.3557e-010 }] [vset CATEGORY {math :: calculus}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/special.man.

 464 465 466 467 468 469 470 471 472  [para] Much information about these functions can be found in: [para] Abramowitz and Stegun: [emph "Handbook of Mathematical Functions"] (Dover, ISBN 486-61272-4) [vset CATEGORY {math :: special}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  464 465 466 467 468 469 470 471 472  [para] Much information about these functions can be found in: [para] Abramowitz and Stegun: [emph "Handbook of Mathematical Functions"] (Dover, ISBN 486-61272-4) [vset CATEGORY {math :: special}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/statistics.man.

 1631 1632 1633 1634 1635 1636 1637 1638 1639  Both time series show a significant periodic component [item] The histograms are not very useful in identifying the nature of the time series - they do not show the periodic nature. [list_end] [vset CATEGORY {math :: statistics}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  1631 1632 1633 1634 1635 1636 1637 1638 1639  Both time series show a significant periodic component [item] The histograms are not very useful in identifying the nature of the time series - they do not show the periodic nature. [list_end] [vset CATEGORY {math :: statistics}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/symdiff.man.

 64 65 66 67 68 69 70 71 72  ==> (($c * (($a * $x) +$b)) + ($a * (($c * $x) +$d))) math::calculus::symdiff::jacobian {x {$a *$x + $b *$y} y {$c *$x + $d *$y}} ==> {{$a} {$b}} {{$c} {$d}} }] [vset CATEGORY {math :: calculus}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  64 65 66 67 68 69 70 71 72  ==> (($c * (($a * $x) +$b)) + ($a * (($c * $x) +$d))) math::calculus::symdiff::jacobian {x {$a *$x + $b *$y} y {$c *$x + $d *$y}} ==> {{$a} {$b}} {{$c} {$d}} }] [vset CATEGORY {math :: calculus}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/math/trig.man.

 187 188 189 190 191 192 193 194 195  [list_begin arguments] [arg_def float angle] Angle (in degrees) [list_end] [list_end] [vset CATEGORY {math :: trig}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  187 188 189 190 191 192 193 194 195  [list_begin arguments] [arg_def float angle] Angle (in degrees) [list_end] [list_end] [vset CATEGORY {math :: trig}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/md4/md4.man.

 160 161 162 163 164 165 166 167 168   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY md4] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  160 161 162 163 164 165 166 167 168   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY md4] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/md5/md5.man.

 166 167 168 169 170 171 172 173 174   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY md5] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  166 167 168 169 170 171 172 173 174   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY md5] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/md5crypt/md5crypt.man.

 77 78 79 80 81 82 83 84 85  [example { % md5crypt::md5crypt password [md5crypt::salt] $1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb. }] [vset CATEGORY md5crypt] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  77 78 79 80 81 82 83 84 85  [example { % md5crypt::md5crypt password [md5crypt::salt]$1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb. }] [vset CATEGORY md5crypt] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/mime/mime.man.

 398 399 400 401 402 403 404 405 406  [para] See [uri {/tktview?name=447037} {Ticket 447037}] for additional information. [list_end] [vset CATEGORY mime] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  398 399 400 401 402 403 404 405 406  [para] See [uri {/tktview?name=447037} {Ticket 447037}] for additional information. [list_end] [vset CATEGORY mime] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/mime/smtp.man.

 199 200 201 202 203 204 205 206 207 208 209 210   J. Myers, "SMTP Service Extension for Authentication", RFC 2554, March 1999. ([uri http://www.rfc-editor.org/rfc/rfc2554.txt]) [list_end] [vset CATEGORY smtp] [include ../doctools2base/include/feedback.inc] [keywords mail mail email smtp mime tls \ {rfc 821} {rfc 822} {rfc 2821} {rfc 3207} {rfc 2554} internet net] [manpage_end]   |  199 200 201 202 203 204 205 206 207 208 209 210   J. Myers, "SMTP Service Extension for Authentication", RFC 2554, March 1999. ([uri http://www.rfc-editor.org/rfc/rfc2554.txt]) [list_end] [vset CATEGORY smtp] [include ../common-text/feedback.inc] [keywords mail mail email smtp mime tls \ {rfc 821} {rfc 822} {rfc 2821} {rfc 3207} {rfc 2554} internet net] [manpage_end] 

Changes to modules/multiplexer/multiplexer.man.

 122 123 124 125 126 127 128 129 130  EOF: The channel connecting us to the client, its ip-address, and its ip-port. [list_end] [list_end] [vset CATEGORY multiplexer] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  122 123 124 125 126 127 128 129 130  EOF: The channel connecting us to the client, its ip-address, and its ip-port. [list_end] [list_end] [vset CATEGORY multiplexer] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/namespacex/namespacex.man.

 166 167 168 169 170 171 172 173 174  a child namespace of namespace [arg prefix]. Returns the corresponding list of relative names of child namespaces. [list_end] [vset CATEGORY namespacex] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  166 167 168 169 170 171 172 173 174  a child namespace of namespace [arg prefix]. Returns the corresponding list of relative names of child namespaces. [list_end] [vset CATEGORY namespacex] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ncgi/ncgi.man.

 305 306 307 308 309 310 311 312 313  puts -nonewline $fh$filedata close $fh }] [para] [vset CATEGORY ncgi] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  305 306 307 308 309 310 311 312 313  puts -nonewline$fh $filedata close$fh }] [para] [vset CATEGORY ncgi] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nettool/nettool.man.

 135 136 137 138 139 140 141 142 143  Return a fully qualified path to a folder where [arg appname] should store it's data. The path is not created, only computed, by this command. [list_end] [para] [vset CATEGORY odie] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  135 136 137 138 139 140 141 142 143  Return a fully qualified path to a folder where [arg appname] should store it's data. The path is not created, only computed, by this command. [list_end] [para] [vset CATEGORY odie] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nmea/nmea.man.

 94 95 96 97 98 99 100 101 102   puts "unknown data type $name" } }] [list_end] [vset CATEGORY nmea] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  94 95 96 97 98 99 100 101 102   puts "unknown data type$name" } }] [list_end] [vset CATEGORY nmea] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nns/nns_auto.man.

 111 112 113 114 115 116 117 118 119  [para] Another loss of the connection, be it during or after re-entering the remembered information simply restarts the timer and subsequent reconnection attempts. [vset CATEGORY nameserv] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  111 112 113 114 115 116 117 118 119  [para] Another loss of the connection, be it during or after re-entering the remembered information simply restarts the timer and subsequent reconnection attempts. [vset CATEGORY nameserv] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nns/nns_client.man.

 330 331 332 333 334 335 336 337 338  its connection to the name service. Based on package [package uevent]. [def 0.1] Initial implementation of the client. [list_end] [vset CATEGORY nameserv] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  330 331 332 333 334 335 336 337 338  its connection to the name service. Based on package [package uevent]. [def 0.1] Initial implementation of the client. [list_end] [vset CATEGORY nameserv] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nns/nns_common.man.

 39 40 41 42 43 44 45 46 47  The result returned by the command is the id of the default TCP/IP port a nameservice server will listen on, and a name service client will try to connect to. [list_end] [vset CATEGORY nameserv] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  39 40 41 42 43 44 45 46 47  The result returned by the command is the id of the default TCP/IP port a nameservice server will listen on, and a name service client will try to connect to. [list_end] [vset CATEGORY nameserv] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nns/nns_intro.man.

 120 121 122 123 124 125 126 127 128  [para] Developers wishing to modify and/or extend or to just understand the internals of the nameservice facility however are strongly advised to read it. [vset CATEGORY nameserv] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  120 121 122 123 124 125 126 127 128  [para] Developers wishing to modify and/or extend or to just understand the internals of the nameservice facility however are strongly advised to read it. [vset CATEGORY nameserv] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nns/nns_protocol.man.

 174 175 176 177 178 179 180 181 182  The argument coming before the response tells the client whether the names in the response were added or removed from the service. [list_end] [vset CATEGORY nameserv] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  174 175 176 177 178 179 180 181 182  The argument coming before the response tells the client whether the names in the response were added or removed from the service. [list_end] [vset CATEGORY nameserv] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nns/nns_server.man.

 137 138 139 140 141 142 143 144 145  Changed name of -local switch to -localonly. [def 0.1] Initial implementation of the server. [list_end] [vset CATEGORY nameserv] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  137 138 139 140 141 142 143 144 145  Changed name of -local switch to -localonly. [def 0.1] Initial implementation of the server. [list_end] [vset CATEGORY nameserv] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/nntp/nntp.man.

 330 331 332 333 334 335 336 337 338   Date: [clock format [clock seconds] -format "%a, %d % b %y %H:%M:%S GMT" -gmt true] Test message body" }] [vset CATEGORY nntp] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  330 331 332 333 334 335 336 337 338   Date: [clock format [clock seconds] -format "%a, %d % b %y %H:%M:%S GMT" -gmt true] Test message body" }] [vset CATEGORY nntp] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ntp/ntp_time.man.

 123 124 125 126 127 128 129 130 131  time::getsntp -command on_time pool.ntp.org }] [section AUTHORS] Pat Thoyts [vset CATEGORY ntp] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  123 124 125 126 127 128 129 130 131  time::getsntp -command on_time pool.ntp.org }] [section AUTHORS] Pat Thoyts [vset CATEGORY ntp] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/oauth/oauth.man.

 183 184 185 186 187 188 189 190 191  follow_request_sent => false notifications => false}] [list_end] [para] [vset CATEGORY oauth] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  183 184 185 186 187 188 189 190 191  follow_request_sent => false notifications => false}] [list_end] [para] [vset CATEGORY oauth] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/oometa/oometa.man.

 143 144 145 146 147 148 149 150 151 152  is faster than [cmd {my meta getnull}] [opt [arg field]] [opt [arg ...]] [arg field]], because it performs a search instead directly instead of producing the recursive merge product between the class metadata, the local [emph meta] variable, and THEN performing the search. [list_end] [vset CATEGORY tcloo] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  143 144 145 146 147 148 149 150 151 152  is faster than [cmd {my meta getnull}] [opt [arg field]] [opt [arg ...]] [arg field]], because it performs a search instead directly instead of producing the recursive merge product between the class metadata, the local [emph meta] variable, and THEN performing the search. [list_end] [vset CATEGORY tcloo] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ooutil/ooutil.man.

 157 158 159 160 161 162 163 164 165  [list_end] [section AUTHORS] Donal Fellows, Andreas Kupries [vset CATEGORY oo::util] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  157 158 159 160 161 162 163 164 165  [list_end] [section AUTHORS] Donal Fellows, Andreas Kupries [vset CATEGORY oo::util] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/otp/otp.man.

 87 88 89 90 91 92 93 94 95   "Secure Hash Standard", National Institute of Standards and Technology, U.S. Department Of Commerce, April 1995. ([uri http://www.itl.nist.gov/fipspubs/fip180-1.htm]) [list_end] [vset CATEGORY otp] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  87 88 89 90 91 92 93 94 95   "Secure Hash Standard", National Institute of Standards and Technology, U.S. Department Of Commerce, April 1995. ([uri http://www.itl.nist.gov/fipspubs/fip180-1.htm]) [list_end] [vset CATEGORY otp] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/page/page_intro.man.

 27 28 29 30 31 32 33 34 35  The packages implementing the plugins are not documented as regular packages, as they cannot be loaded into a general interpreter, like tclsh, without extensive preparation of the interpreter. Preparation which is done for them by the plugin manager. [vset CATEGORY page] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  27 28 29 30 31 32 33 34 35  The packages implementing the plugins are not documented as regular packages, as they cannot be loaded into a general interpreter, like tclsh, without extensive preparation of the interpreter. Preparation which is done for them by the plugin manager. [vset CATEGORY page] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/page/page_pluginmgr.man.

 792 793 794 795 796 797 798 799 800  [section FEATURES] The plugin manager currently checks the plugins for only one feature, [const timeable]. A plugin supporting this feature is assumed to be able to collect timing statistics on request. [vset CATEGORY page] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  792 793 794 795 796 797 798 799 800  [section FEATURES] The plugin manager currently checks the plugins for only one feature, [const timeable]. A plugin supporting this feature is assumed to be able to collect timing statistics on request. [vset CATEGORY page] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/page/page_util_flow.man.

 88 89 90 91 92 93 94 95 96  This is the variadic arguments form of the method [method visitl], see above. [list_end] [vset CATEGORY page] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  88 89 90 91 92 93 94 95 96  This is the variadic arguments form of the method [method visitl], see above. [list_end] [vset CATEGORY page] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/page/page_util_norm_lemon.man.

 43 44 45 46 47 48 49 50 51  [para] The exact operations performed are left undocumented for the moment. [list_end] [vset CATEGORY page] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  43 44 45 46 47 48 49 50 51  [para] The exact operations performed are left undocumented for the moment. [list_end] [vset CATEGORY page] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/page/page_util_norm_peg.man.

 97 98 99 100 101 102 103 104 105  The order matters, to shed as much nodes as possible early, and to avoid unnecessary work later. [list_end] [list_end] [vset CATEGORY page] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  97 98 99 100 101 102 103 104 105  The order matters, to shed as much nodes as possible early, and to avoid unnecessary work later. [list_end] [list_end] [vset CATEGORY page] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/page/page_util_peg.man.

 100 101 102 103 104 105 106 107 108  See the package [package grammar::peg] for the exact syntax of [arg pe]. [list_end] [vset CATEGORY page] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  100 101 102 103 104 105 106 107 108  See the package [package grammar::peg] for the exact syntax of [arg pe]. [list_end] [vset CATEGORY page] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/page/page_util_quote.man.

 54 55 56 57 58 59 60 61 62  converts it into a string which is accepted by the Tcl parser when used within a Tcl comment. The string is returned as the result of this command. [list_end] [vset CATEGORY page] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  54 55 56 57 58 59 60 61 62  converts it into a string which is accepted by the Tcl parser when used within a Tcl comment. The string is returned as the result of this command. [list_end] [vset CATEGORY page] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/pki/pki.man.

 294 295 296 297 298 299 300 301 302  [enum] [list_end] [section AUTHORS] Roy Keene [vset CATEGORY rsa] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  294 295 296 297 298 299 300 301 302  [enum] [list_end] [section AUTHORS] Roy Keene [vset CATEGORY rsa] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/pluginmgr/pluginmgr.man.

 419 420 421 422 423 424 425 426 427  Its purpose is give a user of the plugin management the ability to define commands, packages, etc. a chosen plugin may need while being loaded. [list_end] [vset CATEGORY pluginmgr] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  419 420 421 422 423 424 425 426 427  Its purpose is give a user of the plugin management the ability to define commands, packages, etc. a chosen plugin may need while being loaded. [list_end] [vset CATEGORY pluginmgr] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/png/png.man.

 147 148 149 150 151 152 153 154 155  Takes a list of scanlines in the Tk_GetColor format and writes the represented image to [arg file]. [list_end] [vset CATEGORY png] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  147 148 149 150 151 152 153 154 155  Takes a list of scanlines in the Tk_GetColor format and writes the represented image to [arg file]. [list_end] [vset CATEGORY png] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/pop3/pop3.man.

 266 267 268 269 270 271 272 273 274   pop3::open -stls 1 \\ $thehost$theuser $thepassword ... }] [vset CATEGORY pop3] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  266 267 268 269 270 271 272 273 274   pop3::open -stls 1 \\$thehost $theuser$thepassword ... }] [vset CATEGORY pop3] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/pop3d/pop3d.man.

 265 266 267 268 269 270 271 272 273  [list_begin enumerated] [enum] [uri http://www.rfc-editor.org/rfc/rfc1939.txt {RFC 1939}] [enum] [uri http://www.rfc-editor.org/rfc/rfc2449.txt {RFC 2449}] [list_end] [vset CATEGORY pop3d] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  265 266 267 268 269 270 271 272 273  [list_begin enumerated] [enum] [uri http://www.rfc-editor.org/rfc/rfc1939.txt {RFC 1939}] [enum] [uri http://www.rfc-editor.org/rfc/rfc2449.txt {RFC 2449}] [list_end] [vset CATEGORY pop3d] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/pop3d/pop3d_dbox.man.

 156 157 158 159 160 161 162 163 164  call will fail. If [method stat] was not called before this call, [method get] will assume that there are zero messages in the mailbox. [list_end] [vset CATEGORY pop3d] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  156 157 158 159 160 161 162 163 164  call will fail. If [method stat] was not called before this call, [method get] will assume that there are zero messages in the mailbox. [list_end] [vset CATEGORY pop3d] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/pop3d/pop3d_udb.man.

 104 105 106 107 108 109 110 111 112  remembered internally so that it can be used in the next call of [arg dbName] [method save] without an argument. [list_end] [vset CATEGORY pop3d] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  104 105 106 107 108 109 110 111 112  remembered internally so that it can be used in the next call of [arg dbName] [method save] without an argument. [list_end] [vset CATEGORY pop3d] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/practcl/practcl.man.

 55 56 57 58 59 60 61 62 63  [call [cmd practcl::submodule] [arg "parent"] [opt [arg "keyvaluelist"]]] A Practcl object representing a dynamically generated C/H/Tcl suite, subordinate to a module [list_end] [vset CATEGORY practcl] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  55 56 57 58 59 60 61 62 63  [call [cmd practcl::submodule] [arg "parent"] [opt [arg "keyvaluelist"]]] A Practcl object representing a dynamically generated C/H/Tcl suite, subordinate to a module [list_end] [vset CATEGORY practcl] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/processman/processman.man.

 66 67 68 69 70 71 72 73 74  Start a child process, identified by [arg id]. [arg cmd] is the name of the command to execute. [arg args] are arguments to pass to that command. [list_end] [para] [vset CATEGORY odie] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  66 67 68 69 70 71 72 73 74  Start a child process, identified by [arg id]. [arg cmd] is the name of the command to execute. [arg args] are arguments to pass to that command. [list_end] [para] [vset CATEGORY odie] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/profiler/profiler.man.

 113 114 115 116 117 118 119 120 121  [const avgRuntime]. The return result is a list of lists, where each sublist consists of a function name and the value of [arg key] for that function. [list_end] [vset CATEGORY profiler] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  113 114 115 116 117 118 119 120 121  [const avgRuntime]. The return result is a list of lists, where each sublist consists of a function name and the value of [arg key] for that function. [list_end] [vset CATEGORY profiler] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/pt/include/feedback.inc.

 1 2 3  [comment {--- Standard trailer for all manpages in this module --}] [vset CATEGORY pt] [include ../../doctools2base/include/feedback.inc]   |  1 2 3  [comment {--- Standard trailer for all manpages in this module --}] [vset CATEGORY pt] [include ../../common-text/feedback.inc] 

Changes to modules/rc4/rc4.man.

 112 113 114 115 116 117 118 119 120   rc4::rc4 -in $socket -command [list ::Finish$ApplicationState] }] [section "AUTHORS"] Pat Thoyts [vset CATEGORY rc4] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  112 113 114 115 116 117 118 119 120   rc4::rc4 -in $socket -command [list ::Finish$ApplicationState] }] [section "AUTHORS"] Pat Thoyts [vset CATEGORY rc4] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/rcs/rcs.man.

 322 323 324 325 326 327 328 329 330  [example {{{d 1 2} {d 4 1} {a 4 {The named is the mother of all things. }} {a 11 {They both may be called deep and profound. Deeper and more profound, The door of all subtleties!}}}}] [vset CATEGORY rcs] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  322 323 324 325 326 327 328 329 330  [example {{{d 1 2} {d 4 1} {a 4 {The named is the mother of all things. }} {a 11 {They both may be called deep and profound. Deeper and more profound, The door of all subtleties!}}}}] [vset CATEGORY rcs] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/report/report.man.

 468 469 470 471 472 473 474 475 476   +---+-------------------+-------+-------+--------+ % % # alternate way of doing the above % m format 2string r }] [vset CATEGORY report] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  468 469 470 471 472 473 474 475 476   +---+-------------------+-------+-------+--------+ % % # alternate way of doing the above % m format 2string r }] [vset CATEGORY report] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/rest/rest.man.

 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559   package require tls http::register https 443 ::tls::socket }] [include ../common-text/tls-security-notes.inc] [vset CATEGORY rest] [include ../doctools2base/include/feedback.inc] [comment { TOKENS the value is substituted into the url at call time. tokens in the form of %name:default_value% will be an optional argument with a default value. }] [manpage_end]   |  545 546 547 548 549 550 551 552 553 554 555 556 557 558 559   package require tls http::register https 443 ::tls::socket }] [include ../common-text/tls-security-notes.inc] [vset CATEGORY rest] [include ../common-text/feedback.inc] [comment { TOKENS the value is substituted into the url at call time. tokens in the form of %name:default_value% will be an optional argument with a default value. }] [manpage_end] 

Changes to modules/ripemd/ripemd128.man.

 183 184 185 186 187 188 189 190 191   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY ripemd] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  183 184 185 186 187 188 189 190 191   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY ripemd] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/ripemd/ripemd160.man.

 167 168 169 170 171 172 173 174 175   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY ripemd] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  167 168 169 170 171 172 173 174 175   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY ripemd] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/sasl/gtoken.man.

 19 20 21 22 23 24 25 26 27  [include ../common-text/tls-security-notes.inc] [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  19 20 21 22 23 24 25 26 27  [include ../common-text/tls-security-notes.inc] [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/sasl/ntlm.man.

 28 29 30 31 32 33 34 35 36  [list_end] [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  28 29 30 31 32 33 34 35 36  [list_end] [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/sasl/sasl.man.

 332 333 334 335 336 337 338 339 340  [list_end] [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  332 333 334 335 336 337 338 339 340  [list_end] [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/sasl/scram.man.

 28 29 30 31 32 33 34 35 36  [list_end] [section AUTHORS] Sergei Golovan [vset CATEGORY sasl] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  28 29 30 31 32 33 34 35 36  [list_end] [section AUTHORS] Sergei Golovan [vset CATEGORY sasl] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/sha1/sha1.man.

 175 176 177 178 179 180 181 182 183   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY sha1] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  175 176 177 178 179 180 181 182 183   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY sha1] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/sha1/sha256.man.

 187 188 189 190 191 192 193 194 195   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY sha1] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  187 188 189 190 191 192 193 194 195   Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY sha1] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/smtpd/smtpd.man.

 286 287 288 289 290 291 292 293 294  This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file [file license.terms] for more details. [vset CATEGORY smtpd] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  286 287 288 289 290 291 292 293 294  This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file [file license.terms] for more details. [vset CATEGORY smtpd] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/snit/snit.man.

 2831 2832 2833 2834 2835 2836 2837 2838 2839  Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, Brian Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, and Anton Kovalenko. If I've forgotten anyone, my apologies; let me know and I'll add your name to the list. [vset CATEGORY snit] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  2831 2832 2833 2834 2835 2836 2837 2838 2839  Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, Brian Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, and Anton Kovalenko. If I've forgotten anyone, my apologies; let me know and I'll add your name to the list. [vset CATEGORY snit] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/snit/snitfaq.man.

 4106 4107 4108 4109 4110 4111 4112 4113 4114   mylib::propagate -background to {comp1 comp2 comp3} mylib::propagate -foreground to {comp1 comp2 comp3} } }] [vset CATEGORY snit] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  4106 4107 4108 4109 4110 4111 4112 4113 4114   mylib::propagate -background to {comp1 comp2 comp3} mylib::propagate -foreground to {comp1 comp2 comp3} } }] [vset CATEGORY snit] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/soundex/soundex.man.

 37 38 39 40 41 42 43 44 45  [example { % ::soundex::knuth Knuth K530 }] [vset CATEGORY soundex] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  37 38 39 40 41 42 43 44 45  [example { % ::soundex::knuth Knuth K530 }] [vset CATEGORY soundex] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/stooop/stooop.man.

 215 216 217 218 219 220 221 222 223  [list_end] [section EXAMPLES] Please see the full HTML documentation in [uri stooop_man.html]. [vset CATEGORY stooop] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  215 216 217 218 219 220 221 222 223  [list_end] [section EXAMPLES] Please see the full HTML documentation in [uri stooop_man.html]. [vset CATEGORY stooop] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/stooop/switched.man.

 320 321 322 323 324 325 326 327 328   ... } }] [list_end] [vset CATEGORY stooop] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  320 321 322 323 324 325 326 327 328   ... } }] [list_end] [vset CATEGORY stooop] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/string/token.man.

 89 90 91 92 93 94 95 96 97  [para] Further note that all regex patterns are implicitly prefixed with the constraint escape [const \A] to ensure that a match starts exactly at the character index found in [arg startvar]. [list_end] [vset CATEGORY textutil] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  89 90 91 92 93 94 95 96 97  [para] Further note that all regex patterns are implicitly prefixed with the constraint escape [const \A] to ensure that a match starts exactly at the character index found in [arg startvar]. [list_end] [vset CATEGORY textutil] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/string/token_shell.man.

 133 134 135 136 137 138 139 140 141  [para] Whitespace may occur before the first word, or after the last word. Whitespace must occur between adjacent words. [list_end] [list_end] [vset CATEGORY textutil] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  133 134 135 136 137 138 139 140 141  [para] Whitespace may occur before the first word, or after the last word. Whitespace must occur between adjacent words. [list_end] [list_end] [vset CATEGORY textutil] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/stringprep/stringprep.man.

 143 144 145 146 147 148 149 150 151  [list_end] [section "AUTHORS"] Sergei Golovan [vset CATEGORY stringprep] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  143 144 145 146 147 148 149 150 151  [list_end] [section "AUTHORS"] Sergei Golovan [vset CATEGORY stringprep] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/stringprep/stringprep_data.man.

 13 14 15 16 17 18 19 20 21  The [package stringprep::data] package is a helper for [package stringprep], providing it with the data tables needed to perform its functions. It is an [emph internal] package which should not be accessed on its own. Because of that it has no publicly documented API either. Its implementation is generated by a script. [vset CATEGORY stringprep] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  13 14 15 16 17 18 19 20 21  The [package stringprep::data] package is a helper for [package stringprep], providing it with the data tables needed to perform its functions. It is an [emph internal] package which should not be accessed on its own. Because of that it has no publicly documented API either. Its implementation is generated by a script. [vset CATEGORY stringprep] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/stringprep/unicode.man.

 75 76 77 78 79 80 81 82 83  [list_end] [section "AUTHORS"] Sergei Golovan [vset CATEGORY stringprep] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  75 76 77 78 79 80 81 82 83  [list_end] [section "AUTHORS"] Sergei Golovan [vset CATEGORY stringprep] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/stringprep/unicode_data.man.

 13 14 15 16 17 18 19 20 21  The [package unicode::data] package is a helper for [package unicode], providing it with the data tables needed to perform its functions. It is an [emph internal] package which should not be accessed on its own. Because of that it has no publicly documented API either. Its implementation is generated by a script. [vset CATEGORY stringprep] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  13 14 15 16 17 18 19 20 21  The [package unicode::data] package is a helper for [package unicode], providing it with the data tables needed to perform its functions. It is an [emph internal] package which should not be accessed on its own. Because of that it has no publicly documented API either. Its implementation is generated by a script. [vset CATEGORY stringprep] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/struct/disjointset.man.

 228 229 230 231 232 233 234 235 236  [call [arg disjointsetName] [method destroy]] Destroys the disjoint set object and all associated memory. [list_end] [vset CATEGORY {struct :: disjointset}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  228 229 230 231 232 233 234 235 236  [call [arg disjointsetName] [method destroy]] Destroys the disjoint set object and all associated memory. [list_end] [vset CATEGORY {struct :: disjointset}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/struct/graph.man.

 956 957 958 959 960 961 962 963 964  Both methods [method arcs] and [method nodes] have been extended with the ability to select arcs and nodes based on an arbitrary filtering criterium. [list_end] [vset CATEGORY {struct :: graph}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  956 957 958 959 960 961 962 963 964  Both methods [method arcs] and [method nodes] have been extended with the ability to select arcs and nodes based on an arbitrary filtering criterium. [list_end] [vset CATEGORY {struct :: graph}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/struct/graph1.man.

 367 368 369 370 371 372 373 374 375  node appended. For a pre-order walk, all nodes are [const enter]ed, for a post-order all nodes are left. In a both-order walk the first visit of a node [const enter]s it, the second visit [const leave]s it. [list_end] [vset CATEGORY {struct :: graph}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  367 368 369 370 371 372 373 374 375  node appended. For a pre-order walk, all nodes are [const enter]ed, for a post-order all nodes are left. In a both-order walk the first visit of a node [const enter]s it, the second visit [const leave]s it. [list_end] [vset CATEGORY {struct :: graph}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/struct/graphops.man.

 1311 1312 1313 1314 1315 1316 1317 1318 1319  [enum] [uri http://www.csc.kth.se/~viggo/wwwcompendium/node128.html {K-Center problem}] [enum] [uri http://en.wikipedia.org/wiki/Breadth-first_search {BFS}] [enum] [uri http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree {Minimum Degree Spanning Tree}] [enum] [uri http://en.wikipedia.org/wiki/Approximation_algorithm {Approximation algorithm}] [list_end] [vset CATEGORY {struct :: graph}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  1311 1312 1313 1314 1315 1316 1317 1318 1319  [enum] [uri http://www.csc.kth.se/~viggo/wwwcompendium/node128.html {K-Center problem}] [enum] [uri http://en.wikipedia.org/wiki/Breadth-first_search {BFS}] [enum] [uri http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree {Minimum Degree Spanning Tree}] [enum] [uri http://en.wikipedia.org/wiki/Approximation_algorithm {Approximation algorithm}] [list_end] [vset CATEGORY {struct :: graph}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/struct/matrix.man.

 531 532 533 534 535 536 537 538 539   +---+-------------------+-------+-------+--------+ % % # alternate way of doing the above % r printmatrix m }] [vset CATEGORY {struct :: matrix}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  531 532 533 534 535 536 537 538 539   +---+-------------------+-------+-------+--------+ % % # alternate way of doing the above % r printmatrix m }] [vset CATEGORY {struct :: matrix}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/struct/matrix1.man.

 373 374 375 376 377 378 379 380 381   +---+-------------------+-------+-------+--------+ % % # alternate way of doing the above % r printmatrix m }] [vset CATEGORY {struct :: matrix}] [include ../doctools2base/include/feedback.inc] [manpage_end]   |  373 374 375 376 377 378 379 380 381   +---+-------------------+-------+-------+--------+ % % # alternate way of doing the above % r printmatrix m }] [vset CATEGORY {struct :: matrix}] [include ../common-text/feedback.inc] [manpage_end] 

Changes to modules/struct/pool.man.

 435 436 437 438 439 440 441 442 443