Index: .github/CONTRIBUTING.md ================================================================== --- .github/CONTRIBUTING.md +++ .github/CONTRIBUTING.md @@ -1,17 +1,17 @@ -Hello. +Hello. __Attention please__ You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where development takes place. +This is __not__ the location where Tcllib development takes place. -We are not tracking issues entered here. With the exception of the +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) +[official location of the sources](https://core.tcl-lang.org/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) instead. Thank you for your consideration. Index: .github/ISSUE_TEMPLATE.md ================================================================== --- .github/ISSUE_TEMPLATE.md +++ .github/ISSUE_TEMPLATE.md @@ -1,17 +1,17 @@ -Hello. +Hello. __Attention please__ You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where development takes place. +This is __not__ the location where Tcllib development takes place. -We are not tracking issues entered here. With the exception of the +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) +[official location of the sources](https://core.tcl-lang.org/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) instead. Thank you for your consideration. Index: .github/PULL_REQUEST_TEMPLATE.md ================================================================== --- .github/PULL_REQUEST_TEMPLATE.md +++ .github/PULL_REQUEST_TEMPLATE.md @@ -1,17 +1,17 @@ -Hello. +Hello. __Attention please__ You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where development takes place. +This is __not__ the location where Tcllib development takes place. -We are not tracking issues entered here. With the exception of the +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) +[official location of the sources](https://core.tcl-lang.org/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) instead. Thank you for your consideration. DELETED INSTALL.txt Index: INSTALL.txt ================================================================== --- INSTALL.txt +++ /dev/null @@ -1,77 +0,0 @@ -How to install Tcllib -===================== - -Introduction ------------- - -The tcllib distribution, whether a snapshot directly from CVS, or -officially released, offers a single method for installing tcllib, -based on Tcl itself. - -This is based on the assumption that for tcllib to be of use Tcl has -to be present, and therefore can be used. - -This single method however can be used in a variety of ways. - -0 For an unwrapped (= directory) distribution or CVS snapshot - - a. either call the application 'installer.tcl' directly, - b or use - - % configure ; make install - - The latter is provided for people which are used to - this method and more comfortable with it. In end this - boils down into a call of 'installer.tcl' too. - -1. A starpack distribution (window-only) is a self-extracting - installer which internally uses the aforementioned installer. - -2. A starkit distribution is very much like a starpack, but - required an external interpreyter to run. This can be any tcl - interpreter which has all the packages to support starkits - (tclvfs, memchan, trf). - -3. A distribution in a tarball has to be unpacked first, then any - of the methods described in (0) can be used. - - -Usage of the installer ----------------------- - -The installer selects automatically either a gui based mode, or a -command line based mode. If the package Tk is present and can be -loaded, then the GUI mode is entered, else the system falls back to -the command line. - -Note that it is possible to specify options on the command line even -if the installer ultimatively selects a gui mode. In that case the -hardwired defaults and the options determine the data presented to the -user for editing. - -Command line help can be asked for by using the option -help when -running the installer (3) or the distribution itself in the case of -(1) or (2). - -The installer will select a number of defaults for the locations of -packages, examples, and documentation, and also the format of the -documentation. The user can overide these defaults in the GUI, or by -specifying additional options. - -The defaults depend on the platform detected (unix/windows) and the -executable used to run the installer. In the case of a starpack -distribution (1) this means that _no defaults_ are possible for the -various locations as the executable is part of the distribution and -has no knowledge of its environment. - -In all other cases the intepreter executable is outside of the -distribution, which means that its location can be used to determine -sensible defaults. - -Notes ------ - -The installer will overwrite an existing installation of tcllib 1.6 -without asking back after the initial confirmation is given. And if -the user chooses the same directory as for tcllib 1.4, or 1.3, etc. -then the installer will overwrite that too. DELETED README Index: README ================================================================== --- README +++ /dev/null @@ -1,96 +0,0 @@ -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. DELETED README.developer Index: README.developer ================================================================== --- README.developer +++ /dev/null @@ -1,396 +0,0 @@ -RCS: @(#) $Id: README.developer,v 1.6 2009/06/02 22:49:55 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 - - Developer - -working on Tcllib to help him with his tasks, i.e. making the tasks easier -to perform. It is our hope that this will improve the quality of even -non-released revisions of Tcllib, and make the work of the release -manager easier as well. - -Audience --------- - -The intended audience are, first and foremost, developers beginning to -work on Tcllib. To an experienced developer this document will be less -of a guide and more of a reference. Anybody else interested in working -on Tcllib is invited as well. - - -Directory hierarchy and file basics ------------------------------------- - -The main directories under the tcllib top directory are - - modules/ - examples/ -and apps/ - -Each directory FOO under modules/ represents one package, sometimes -more. In the case of the latter the packages are usually related in -some way. Examples are the base64, math, and struct modules, with -loose (base64) to strong (math) relations between the packages. - -Examples associated with a module FOO, if there are any, are placed -into the directory - - examples/FOO - -Any type of distributable application can be found under apps/, -together with their documentation, if any. Note that the apps/ -directory is currently not split into sub-directories. - -Regarding the files in Tcllib, the most common types found are - - .tcl Tcl code for a package. - - .man Documentation for a package, in doctools format. - - .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 tclchecker to check the use of commands - of a Tcllib package X without having to scan the - implementation of X, i.e. its .tcl files. - - -Adding a new module -------------------- - -Assuming that FOO is the name of the new module, and T is the toplevel -directory of the Tcllib sources - -(1) Create the directory T/modules/FOO and put all the files of - the module into it. Note: - - * The file 'pkgIndex.tcl' is required. - - * Implementation files should have the extension '.tcl', - naturally. - - * If available, documentation should be in doctools format, - and the files should have the extension '.man' for SAK to - recognize them. - - * If available the testsuite(s) should use 'tcltest' and the - general format as used by the other modules in Tcllib - (declaration of minimally needed Tcl, tcltest, supporting - packages, etc.). The file(s) should have the extension - '.test' for SAK to recognize them. - - Note that an empty testsuite, or a testsuite which does not - perform any tests is less than useful and will not be - accepted. - - * If available the benchmark(s) should use 'bench' and the - general format as used by the other modules in Tcllib. The - file(s) should have the extension '.bench' for SAK to - recognize them. - - * Other files can be named and placed as the module sees fit. - -(2) If the new module has an example application A which is - polished enough for general use, put this application into the - file "T/apps/A.tcl", and its documentation into the file - "T/apps/A.man". While documentation for the application is - optional, it is preferred. - - For examples which are not full-fledged applications, a - skeleton, or not really polished for use, etc., create the - directory T/examples/FOO/ and put them there. - - A key difference is what happens to them on installation, and - what the target audience is. - - The examples are for developers using packages in Tcllib, - whereas the applications are also for users of Tcllib which do - not have an interest in developing for and with it. As such, - they are installed as regular commands, accessible through the - PATH, and example files are not installed. - -(3) To make Tcllib's installer aware of FOO, edit the file - - T/support/installation/modules.tcl - - Add a line 'Module FOO $impaction $docaction $exaction'. The - various actions describe to the installer how to install the - implementation files, the documentation, and the examples. - - Add a line 'Application A' for any application A which was - added to T/apps for FOO. - - The following actions are available: - - Implementation - - _tcl - Copy all .tcl files in T/modules/FOO into the installation. - _tcr - See above, does it for .tcl files in subdirectories as well. - _tci - _tcl + Copying of a tclIndex - special to modules 'math', 'control'. - _msg - _tcl + Copying of subdir 'msgs' - special to modules 'dns', 'log'. - _doc - _tcl + Copying of subdir 'mpformats' - special to module 'doctools'. - _tex - _tcl + Copying of .tex files - special to module 'textutil'. - - The _null action, see below, is available in principle - too, but a module without implementation does not make - sense. - - Documentation - - _null - Module has no documentation, do nothing. - _man - Process the .man files in T/modules/FOO and - install the results (nroff and/or HTML) in the - proper location, as given to the installer. - - Examples - - _null - Module has no examples, do nothing - _exa - Copy the directory T/examples/FOO - (recursively) to the install location for - examples. - - -Testing modules ---------------- - -To run the testsuite of a module FOO in tcllib use the 'test run' -argument of sak.tcl, like so: - - % pwd - /the/tcllib/toplevel/directory - - % ./sak.tcl test run FOO -or % ./sak.tcl test run modules/FOO - -To run the testsuites of all modules either invoke 'test run' without a -module name, or use 'make test'. The latter assumes that configure was -run for Tcllib before, i.e.: - - % ./sak.tcl test run -or % ./sak.tcl test run - % make test - -In all of the above cases the result will be a combination of progress -display and testsuite log, showing for each module the tests that pass -or failed and how many of each in a summary at the end. - -To get a detailed log, it is necessary to invoke 'test run' with -additional options. - -First example: - % ./sak.tcl test run -l LOG FOO - -This shows the same short log on the terminal, and writes a detailed -log to the file LOG.log, and excerpts to other files (LOG.summary, -LOG.failures, etc.). - -Second example: - % ./sak.tcl test run -v FOO - % make test > LOG - -This writes the detailed log to stdout, or to the file LOG, instead of -the short log. In all cases, the detailed log contains a list of all -test cases executed, which failed, and how they failed (expected -versus actual results). - -Note: -The commands - % make test -and % make test > LOG - -are able to generate different output (short vs long log) because the -Makefile target contains code which detects that stdout has been -redirected to a file and acts accordingly. - -Non-developers should reports problems in Tcllib's bug tracker. -Information about its location and the relevant category can be found -in the section 'BUGS, IDEAS, FEEDBACK' of the manpage of the module -and/or package. - -Module documentation --------------------- - -The main format used for the documentation of packages in Tcllib is -'doctools', the support packages of which are part of Tcllib, see the -module 'doctools'. - -To convert this documentation to HTML or nroff manpages, or some other -format use the 'doc' argument of sak.tcl, like so: - - % pwd - /the/tcllib/toplevel/directory - - % ./sak.tcl doc html FOO -or % ./sak.tcl doc html modules/FOO - -The result of the conversion can be found in the newly-created 'doc' -directory in the current working directory. - -The set of formats the documentation can be converted into can be -queried via - - % ./sak.tcl help doc - - -To convert the documentation of all modules either invoke 'test run' -without a module name, or use 'make html-doc', etc.. The latter -assumes that configure was run for Tcllib before, i.e.: - - % ./sak.tcl doc html - % make html-doc - -Note the special format 'validate'. Using this format does not convert -the documentation to anything (and the sub-directory 'doc' will not be -created), it just checks that the documentation is syntactically -correct. I.e. - - % ./sak.tcldoc validate modules/FOO - % ./sak.tcldoc validate - - -Validating modules ------------------- - -Running the testsuite of a module, or checking the syntax of its -documentation (see the previous sections) are two forms of validation. - -The 'validate' command of sak.tcl provides a few more. The online -documentation of this command is available via - - % ./sak.tcl help validate - -The validated parts are man pages, testsuites, version information, -and syntax. The latter only if various static syntax checkers are -available on the PATH, like TclDevKit's tclchecker. - -Note that testsuite validation is not the execution of the testsuites, -only if a package has a testsuite or not. - -It is strongly recommended to validate a module before committing any -type of change made to it. - -It is recommended to validate all modules before committing any type -of change made to one of them. We have package inter-dependencies -between packages in Tcllib, thus changing one package may break -others, and just validating the changed package will not catch such -problems. - - -Writing Tests -------------- - -While a previous section talked about running the testsuite 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 methodologies for writing -tests and testsuites. - -First there are "drudgery" tests. Written to check absolutely basic -assumptions which should never fail. - -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. - -** The BellmanFord command in struct::graph::ops takes a - _startnode_ as argument, and this node should be a node of the - graph. equals one test case checking the behavior when the - specified node is not a node a graph. - - This often gives rise to code in the implementation which - explicitly checks the assumption and throws a nice error. - Instead of letting the algorithm fails later in some weird - non-deterministic way. - - Such checks cannot be done always. The graph argument for - example is just a command in itself, and while we expect it to - exhibit a certain interface, i.e. 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 (1) and (3) 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 our 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 cases forcing a specific direction of the decision, for -all possible directions. - -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. - -So, if you, dear reader, now believe that writing tests for an -algorithm takes at least as much time as coding the algorithm, and -often more time, then you are completely right. It does. Much more -time. See for example also http://sqlite.org/testing.html, a writeup -on how the Sqlite database engine is tested. - - - -An interesting connection is to documentation. In one direction, the -properties you are checking with black-box testing are properties -which should be documented in the algorithm man page. And conversely, -if you have documentation of properties of an algorithm then this is a -good reference to base 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 test for 'startnode not in input -graph' serving as reminder to put in a check for this into the code. Index: README.md ================================================================== --- README.md +++ README.md @@ -1,17 +1,44 @@ - -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. +# 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.tk/tcllib/reportlist) +[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) instead. + +# Welcome + +Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a +package itself. It is a collection of (semi-independent) Tcl packages +that provide utility functions useful to a large collection of Tcl +programmers. + +At our [home site](http://core.tcl-lang.org/tcllib) you will find the +official fossil repository used to manage our sources, together with +the bug tracker. This is also the main location for releases to +download from. + +We have a +[secondary download location](https://sourceforge.net/projects/tcllib/files) +where the Tcllib sources were hosted in the past. SourceForge is also +where our [mailing lists](https://sourceforge.net/p/tcllib/mailman) +are (still) hosted. + +Another location to find these sources at is the +[github mirror](https://github.com/tcltk/tcllib). + +Please note the :warning: at the top. + +# Guides To Tcllib + + * [Tcl Community - Kind Communication](embedded/www/tcllib/files/devdoc/tcl_community_communication.html) + * [License](embedded/www/tcllib/files/devdoc/tcllib_license.html) + * [How To Get The Sources](embedded/www/tcllib/files/devdoc/tcllib_sources.html) + * [How To Build And Install Tcllib](embedded/www/tcllib/files/devdoc/tcllib_installer.html) + * [The Developer's Guide](embedded/www/tcllib/files/devdoc/tcllib_devguide.html) + * [The Release Manager's Guide](embedded/www/tcllib/files/devdoc/tcllib_releasemgr.html) DELETED README.releasemgr Index: README.releasemgr ================================================================== --- README.releasemgr +++ /dev/null @@ -1,65 +0,0 @@ -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 Index: apps/dtplite.man ================================================================== --- apps/dtplite.man +++ apps/dtplite.man @@ -441,7 +441,7 @@ of doctoc and docidx markup. [list_end] [vset CATEGORY doctools] -[include ../modules/doctools2base/include/feedback.inc] +[include ../modules/common-text/feedback.inc] [manpage_end] Index: apps/nns.man ================================================================== --- apps/nns.man +++ apps/nns.man @@ -137,7 +137,7 @@ requests. [list_end] [vset CATEGORY nameserv] -[include ../modules/doctools2base/include/feedback.inc] +[include ../modules/common-text/feedback.inc] [manpage_end] Index: apps/nnsd.man ================================================================== --- apps/nnsd.man +++ apps/nnsd.man @@ -85,7 +85,7 @@ specifies the TCP port the server has to listen on for requests. [list_end] [vset CATEGORY nameserv] -[include ../modules/doctools2base/include/feedback.inc] +[include ../modules/common-text/feedback.inc] [manpage_end] Index: apps/nnslog.man ================================================================== --- apps/nnslog.man +++ apps/nnslog.man @@ -87,7 +87,7 @@ requests. [list_end] [vset CATEGORY nameserv] -[include ../modules/doctools2base/include/feedback.inc] +[include ../modules/common-text/feedback.inc] [manpage_end] Index: apps/page.man ================================================================== --- apps/page.man +++ apps/page.man @@ -461,7 +461,7 @@ 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] +[include ../modules/common-text/feedback.inc] [manpage_end] Index: apps/tcldocstrip.man ================================================================== --- apps/tcldocstrip.man +++ apps/tcldocstrip.man @@ -191,7 +191,7 @@ written after the actual content of a generated file. [list_end] [vset CATEGORY docstrip] -[include ../modules/doctools2base/include/feedback.inc] +[include ../modules/common-text/feedback.inc] [manpage_end] ADDED devdoc/README.developer Index: devdoc/README.developer ================================================================== --- /dev/null +++ devdoc/README.developer @@ -0,0 +1,396 @@ +RCS: @(#) $Id: README.developer,v 1.6 2009/06/02 22:49:55 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 + + Developer + +working on Tcllib to help him with his tasks, i.e. making the tasks easier +to perform. It is our hope that this will improve the quality of even +non-released revisions of Tcllib, and make the work of the release +manager easier as well. + +Audience +-------- + +The intended audience are, first and foremost, developers beginning to +work on Tcllib. To an experienced developer this document will be less +of a guide and more of a reference. Anybody else interested in working +on Tcllib is invited as well. + + +Directory hierarchy and file basics +------------------------------------ + +The main directories under the tcllib top directory are + + modules/ + examples/ +and apps/ + +Each directory FOO under modules/ represents one package, sometimes +more. In the case of the latter the packages are usually related in +some way. Examples are the base64, math, and struct modules, with +loose (base64) to strong (math) relations between the packages. + +Examples associated with a module FOO, if there are any, are placed +into the directory + + examples/FOO + +Any type of distributable application can be found under apps/, +together with their documentation, if any. Note that the apps/ +directory is currently not split into sub-directories. + +Regarding the files in Tcllib, the most common types found are + + .tcl Tcl code for a package. + + .man Documentation for a package, in doctools format. + + .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 tclchecker to check the use of commands + of a Tcllib package X without having to scan the + implementation of X, i.e. its .tcl files. + + +Adding a new module +------------------- + +Assuming that FOO is the name of the new module, and T is the toplevel +directory of the Tcllib sources + +(1) Create the directory T/modules/FOO and put all the files of + the module into it. Note: + + * The file 'pkgIndex.tcl' is required. + + * Implementation files should have the extension '.tcl', + naturally. + + * If available, documentation should be in doctools format, + and the files should have the extension '.man' for SAK to + recognize them. + + * If available the testsuite(s) should use 'tcltest' and the + general format as used by the other modules in Tcllib + (declaration of minimally needed Tcl, tcltest, supporting + packages, etc.). The file(s) should have the extension + '.test' for SAK to recognize them. + + Note that an empty testsuite, or a testsuite which does not + perform any tests is less than useful and will not be + accepted. + + * If available the benchmark(s) should use 'bench' and the + general format as used by the other modules in Tcllib. The + file(s) should have the extension '.bench' for SAK to + recognize them. + + * Other files can be named and placed as the module sees fit. + +(2) If the new module has an example application A which is + polished enough for general use, put this application into the + file "T/apps/A.tcl", and its documentation into the file + "T/apps/A.man". While documentation for the application is + optional, it is preferred. + + For examples which are not full-fledged applications, a + skeleton, or not really polished for use, etc., create the + directory T/examples/FOO/ and put them there. + + A key difference is what happens to them on installation, and + what the target audience is. + + The examples are for developers using packages in Tcllib, + whereas the applications are also for users of Tcllib which do + not have an interest in developing for and with it. As such, + they are installed as regular commands, accessible through the + PATH, and example files are not installed. + +(3) To make Tcllib's installer aware of FOO, edit the file + + T/support/installation/modules.tcl + + Add a line 'Module FOO $impaction $docaction $exaction'. The + various actions describe to the installer how to install the + implementation files, the documentation, and the examples. + + Add a line 'Application A' for any application A which was + added to T/apps for FOO. + + The following actions are available: + + Implementation + + _tcl - Copy all .tcl files in T/modules/FOO into the installation. + _tcr - See above, does it for .tcl files in subdirectories as well. + _tci - _tcl + Copying of a tclIndex - special to modules 'math', 'control'. + _msg - _tcl + Copying of subdir 'msgs' - special to modules 'dns', 'log'. + _doc - _tcl + Copying of subdir 'mpformats' - special to module 'doctools'. + _tex - _tcl + Copying of .tex files - special to module 'textutil'. + + The _null action, see below, is available in principle + too, but a module without implementation does not make + sense. + + Documentation + + _null - Module has no documentation, do nothing. + _man - Process the .man files in T/modules/FOO and + install the results (nroff and/or HTML) in the + proper location, as given to the installer. + + Examples + + _null - Module has no examples, do nothing + _exa - Copy the directory T/examples/FOO + (recursively) to the install location for + examples. + + +Testing modules +--------------- + +To run the testsuite of a module FOO in tcllib use the 'test run' +argument of sak.tcl, like so: + + % pwd + /the/tcllib/toplevel/directory + + % ./sak.tcl test run FOO +or % ./sak.tcl test run modules/FOO + +To run the testsuites of all modules either invoke 'test run' without a +module name, or use 'make test'. The latter assumes that configure was +run for Tcllib before, i.e.: + + % ./sak.tcl test run +or % ./sak.tcl test run + % make test + +In all of the above cases the result will be a combination of progress +display and testsuite log, showing for each module the tests that pass +or failed and how many of each in a summary at the end. + +To get a detailed log, it is necessary to invoke 'test run' with +additional options. + +First example: + % ./sak.tcl test run -l LOG FOO + +This shows the same short log on the terminal, and writes a detailed +log to the file LOG.log, and excerpts to other files (LOG.summary, +LOG.failures, etc.). + +Second example: + % ./sak.tcl test run -v FOO + % make test > LOG + +This writes the detailed log to stdout, or to the file LOG, instead of +the short log. In all cases, the detailed log contains a list of all +test cases executed, which failed, and how they failed (expected +versus actual results). + +Note: +The commands + % make test +and % make test > LOG + +are able to generate different output (short vs long log) because the +Makefile target contains code which detects that stdout has been +redirected to a file and acts accordingly. + +Non-developers should reports problems in Tcllib's bug tracker. +Information about its location and the relevant category can be found +in the section 'BUGS, IDEAS, FEEDBACK' of the manpage of the module +and/or package. + +Module documentation +-------------------- + +The main format used for the documentation of packages in Tcllib is +'doctools', the support packages of which are part of Tcllib, see the +module 'doctools'. + +To convert this documentation to HTML or nroff manpages, or some other +format use the 'doc' argument of sak.tcl, like so: + + % pwd + /the/tcllib/toplevel/directory + + % ./sak.tcl doc html FOO +or % ./sak.tcl doc html modules/FOO + +The result of the conversion can be found in the newly-created 'doc' +directory in the current working directory. + +The set of formats the documentation can be converted into can be +queried via + + % ./sak.tcl help doc + + +To convert the documentation of all modules either invoke 'test run' +without a module name, or use 'make html-doc', etc.. The latter +assumes that configure was run for Tcllib before, i.e.: + + % ./sak.tcl doc html + % make html-doc + +Note the special format 'validate'. Using this format does not convert +the documentation to anything (and the sub-directory 'doc' will not be +created), it just checks that the documentation is syntactically +correct. I.e. + + % ./sak.tcldoc validate modules/FOO + % ./sak.tcldoc validate + + +Validating modules +------------------ + +Running the testsuite of a module, or checking the syntax of its +documentation (see the previous sections) are two forms of validation. + +The 'validate' command of sak.tcl provides a few more. The online +documentation of this command is available via + + % ./sak.tcl help validate + +The validated parts are man pages, testsuites, version information, +and syntax. The latter only if various static syntax checkers are +available on the PATH, like TclDevKit's tclchecker. + +Note that testsuite validation is not the execution of the testsuites, +only if a package has a testsuite or not. + +It is strongly recommended to validate a module before committing any +type of change made to it. + +It is recommended to validate all modules before committing any type +of change made to one of them. We have package inter-dependencies +between packages in Tcllib, thus changing one package may break +others, and just validating the changed package will not catch such +problems. + + +Writing Tests +------------- + +While a previous section talked about running the testsuite 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 methodologies for writing +tests and testsuites. + +First there are "drudgery" tests. Written to check absolutely basic +assumptions which should never fail. + +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. + +** The BellmanFord command in struct::graph::ops takes a + _startnode_ as argument, and this node should be a node of the + graph. equals one test case checking the behavior when the + specified node is not a node a graph. + + This often gives rise to code in the implementation which + explicitly checks the assumption and throws a nice error. + Instead of letting the algorithm fails later in some weird + non-deterministic way. + + Such checks cannot be done always. The graph argument for + example is just a command in itself, and while we expect it to + exhibit a certain interface, i.e. 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 (1) and (3) 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 our 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 cases forcing a specific direction of the decision, for +all possible directions. + +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. + +So, if you, dear reader, now believe that writing tests for an +algorithm takes at least as much time as coding the algorithm, and +often more time, then you are completely right. It does. Much more +time. See for example also http://sqlite.org/testing.html, a writeup +on how the Sqlite database engine is tested. + + + +An interesting connection is to documentation. In one direction, the +properties you are checking with black-box testing are properties +which should be documented in the algorithm man page. And conversely, +if you have documentation of properties of an algorithm then this is a +good reference to base 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 test for 'startnode not in input +graph' serving as reminder to put in a check for this into the code. DELETED devdoc/cvs.branches.fig Index: devdoc/cvs.branches.fig ================================================================== --- devdoc/cvs.branches.fig +++ /dev/null @@ -1,32 +0,0 @@ -#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 Index: devdoc/devguide.html ================================================================== --- devdoc/devguide.html +++ /dev/null @@ -1,50 +0,0 @@ - - -

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 Index: devdoc/installation.txt ================================================================== --- devdoc/installation.txt +++ /dev/null @@ -1,85 +0,0 @@ -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 ADDED devdoc/parts/b_critcl.inc Index: devdoc/parts/b_critcl.inc ================================================================== --- /dev/null +++ devdoc/parts/b_critcl.inc @@ -0,0 +1,38 @@ + +While the majority of Tcllib consists of packages written in pure Tcl +a number of packages also have [term accelerators] associated with them. + +These are [syscmd critcl]-based C packages whose use will boost the +performance of the packages using them. + +These accelerators are optional, and they are not installed by +default. + +[para] To build the accelerators the normally optional dependency on + [syscmd critcl] becomes required. + +[para] To build and install Tcllib with the accelerators in a + Unix-like environment invoke: + +[example { + ./configure + make critcl # This builds the shared library holding + # the accelerators + make install +}] + +[para] The underlying tool is [file sak.tcl] in the toplevel directory +of Tcllib and the command [cmd {make critcl}] is just a wrapper around + +[example { + ./sak.tcl critcl +}] + +[para] Therefore in a Windows environment instead invoke + +[example { + ./sak.tcl critcl + ./installer.tcl +}] + +from within a DOS window, i.e. [syscmd cmd.exe]. ADDED devdoc/parts/b_tooling.inc Index: devdoc/parts/b_tooling.inc ================================================================== --- /dev/null +++ devdoc/parts/b_tooling.inc @@ -0,0 +1,109 @@ + +The core of Tcllib's build system is the script [file installer.tcl] +found in the toplevel directory of a checkout or release. + +[para] The + [example { + configure ; make install + }] + setup available to + developers on Unix-like systems is just a wrapper around it. + + To go beyond the standard embodied in the wrapper it is + necessary to directly invoke this script. + +[para] On Windows system using it directly is the only way to invoke + it. + +[para] For basic help invoke it as + + [example { + ./installer.tcl -help + }] + + This will print a short list of all the available options to + the standard output channel. + +[para] The commands associated with the various [term install] targets + in the [term Makefile.in] for Unix can be used as additional + examples on how to use this tool as well. + +[para] The installer can operate in GUI and CLI modes. + + By default it chooses the mode automatically, based on if the + Tcl package [package Tk] can be used or not. + + The option [option -no-gui] can be used to force CLI mode. + +[para] Note that it is possible to specify options on the command line + even if the installer ultimatively selects GUI mode. In that + case the hardwired defaults and the options determine the data + presented to the user for editing. + +[para] The installer will select a number of defaults for the + locations of packages, examples, and documentation, and also + the format of the documentation. The user can overide these + defaults in the GUI, or by specifying additional options. + + The defaults depend on the platform detected (Unix/Windows) and + on the [syscmd tclsh] executable used to run the installer. + +[para][emph Options] + +[list_begin options] +[opt_def -help] + +Show the list of options explained here on the standard output channel +and exit. + +[opt_def +excluded] + +Include deprecated packages in the installation. + +[opt_def -no-gui] + +Force command line operation of the installer + +[opt_def -no-wait] + +In CLI mode the installer will by default ask the user to confirm that +the chosen configuration (destination paths, things to install) is +correct before performing any action. Using this option causes the +installer to skip this query and immediately jump to installation. + +[opt_def -app-path [arg path]] +[opt_def -example-path [arg path]] +[opt_def -html-path [arg path]] +[opt_def -nroff-path [arg path]] +[opt_def -pkg-path [arg path]] + +Declare the destination paths for the applications, examples, html +documentation, nroff manpages, and packages. The defaults are derived +from the location of the [syscmd tclsh] used to run the installer. + +[opt_def -dry-run] +[opt_def -simulate] + +Run the installer without modifying the destination directories. + +[opt_def -apps] +[opt_def -no-apps] +[opt_def -examples] +[opt_def -no-examples] +[opt_def -pkgs] +[opt_def -no-pkgs] +[opt_def -html] +[opt_def -no-html] +[opt_def -nroff] +[opt_def -no-nroff] + +(De)activate the installation of applications, examples, packages, +html documentation, and nroff manpages. + +[para] Applications, examples, and packages are installed by default. + +[para] On Windows the html documentation is installed by default. + +[para] On Unix the nroff manpages are installed by default. + +[list_end] ADDED devdoc/parts/b_unix.inc Index: devdoc/parts/b_unix.inc ================================================================== --- /dev/null +++ devdoc/parts/b_unix.inc @@ -0,0 +1,22 @@ + +For [term Unix]-like environments Tcllib comes with the standard set +of files to make + +[example { + ./configure + make install +}] + +a suitable way of installing it. + +This is a standard non-interactive install automatically figuring out +where to place everything, i.e. packages, applications, and the +manpages. + +[para] To get a graphical installer invoke + +[example { + ./installer.tcl +}] + +instead. ADDED devdoc/parts/b_windows.inc Index: devdoc/parts/b_windows.inc ================================================================== --- /dev/null +++ devdoc/parts/b_windows.inc @@ -0,0 +1,18 @@ + +In a Windows environment we have the [cmd installer.tcl] script to +perform installation. + +[para] If the desired [syscmd tclsh] is associated [file .tcl] files + then double-clicking / opening the [cmd installer.tcl] is + enough to invoke it in graphical mode. + + This assumes that [term Tk] is installed and available as well. + +[para] Without [term Tk] the only way to invoke the installer are to + open a DOS window, i.e. [syscmd cmd.exe], and then to invoke + +[example { + ./installer.tcl +}] + +inside it. ADDED devdoc/parts/d_bf_branchcmds.inc Index: devdoc/parts/d_bf_branchcmds.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_branchcmds.inc @@ -0,0 +1,29 @@ + +In the hope of engendering good work practices now a few example +operations which will come up with branches, and their associated +fossil command (sequences). + +[list_begin definitions] + +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] +[def [emph Awareness]] +[include d_op_aware.inc] + +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] +[def [emph {Clean checkouts}]] +[include d_op_clean.inc] + +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] +[def [emph {Starting a new branch}]] +[include d_op_branch_open.inc] + +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] +[def [emph {Merging a branch into trunk}]] +[include d_op_branch_close.inc] + +[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] +[def [emph {Merging from trunk}]] +[include d_op_branch_import.inc] + +[list_end] + ADDED devdoc/parts/d_bf_branches.inc Index: devdoc/parts/d_bf_branches.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_branches.inc @@ -0,0 +1,37 @@ + +Given the constraints placed on the [term trunk] branch of the +repository it is (strongly) recommended to perform any development +going beyond trivial changes on a non-trunk branch. + +[para] Outside of the trunk developers are allowed to commit + intermediate broken states of their work. + + Only at the end of a development cycle, when the relevant + branch is considered ready for merging, will it be necessary to + perform full the set of validations ensuring that the merge to + come will create a good commit on trunk. + +[para] Note that while a review from a second developer is not a + required condition for merging a branch it is recommended to + seek out such an independent opinion as a means of + cross-checking the work. + +[para] It also recommended to give any new branch a name which aids in + determining additional details about it. Examples of good + things to stick into a branch name would be + +[list_begin itemized] +[item] Developer (nick)name +[item] Ticket hash/reference +[item] One or two keywords applicable to the work +[item] ... +[list_end] + +[para] Further, while most development branches are likely quite + short-lived, no prohibitions exist against making longer-lived + branches. + + Creators should however be mindful that the longer such a + branch exists without merges the more divergent they will tend + to be, with an associated increase in the effort which will + have to be spent on either merging from and merging to trunk. ADDED devdoc/parts/d_bf_dependencies.inc Index: devdoc/parts/d_bf_dependencies.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_dependencies.inc @@ -0,0 +1,61 @@ + +Regarding packages and dependencies between them Tcllib occupies a +middle position between two extremes: + +[list_begin enumerated] + +[enum] On one side a strongly interdependent set of packages, usually + by a single author, for a single project. Looking at my + (Andreas Kupries) own work examples of such are + [uri https://core.tcl.tk/akupries/marpa/index Marpa], + [uri https://core.tcl.tk/akupries/crimp/index CRIMP], + [uri https://core.tcl.tk/akupries/kinetcl/index Kinetcl], etc. + +[para] For every change the author of the project handles all the + modifications cascading from any incompatibilities it + introduced to the system. + +[enum] On the other side, the world of semi-independent projects by + many different authors where authors know what packages their + own creations depend on, yet usually do not know who else + depends on them. + +[para] The best thing an author making an (incompatible) change to + their project can do is to for one announce such changes in + some way, and for two use versioning to distinguish the code + before and after the change. + +[para] The world is then responsible for adapting, be it by updating + their own projects to the new version, or by sticking to the + old. + +[list_end] + +As mentioned already, Tcllib lives in the middle of that. + +[para] While we as maintainers cannot be aware of all users of + Tcllib's packages, and thus have to rely on the mechanisms + touched on in point 2 above for that, the dependencies between + the packages contained in Tcllib are a different matter. + +[para] As we are collectively responsible for the usability of Tcllib + in toto to the outside world, it behooves us to be individually + mindful even of Tcllib packages we are not directly + maintaining, when they depend on packages under our + maintainership. + + This may be as simple as coordinating with the maintainers of + the affected packages. + + It may also require us to choose how to adapt affected packages + which do not have maintainers, i.e. modify them to use our + changed package properly, or modify them to properly depend on + the unchanged version of our package. + +[para] Note that the above is not only a chore but an opportunity as + well. + + Additional insight can be had by forcing ourselves to look at + our package and the planned change(s) from an outside + perspective, to consider the ramifications of our actions on + others in general, and on dependent packages in particular. ADDED devdoc/parts/d_bf_trunk.inc Index: devdoc/parts/d_bf_trunk.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_trunk.inc @@ -0,0 +1,30 @@ + +The management and use of branches is an important part of working +with a [term {Distributed Version Control System}] ([term DVCS]) like +[uri https://www.fossil-scm.org/ fossil]. + +[para] For Tcllib the main branch of the collection is + [term trunk]. In [term git] this branch would be called + [term master], and this is exactly the case in the + [uri https://github.com/tcltk/tcllib/ {github mirror}] of + Tcllib. + +[para] To properly support debugging [emph {each commit}] on this + branch [emph {has to pass the entire testsuite}] of the + collection. Using bisection to determine when an issue appeared + is an example of an action made easier by this constraint. + +[para] This is part of our collective responsibility for the usability + of Tcllib in toto to the outside world. + + As [term fossil] has no mechanism to enforce this condition + this is handled on the honor system for developers and maintainers. + +[para] To make the task easier Tcllib comes with a tool + ([file sak.tcl]) providing a number of commands in + support. These commands are explained in the following sections + of this guide. + +[para] While it is possible and allowed to commit directly to trunk + remember the above constraint regarding the testsuite, and the + coming notes about other possible issues with a commit. ADDED devdoc/parts/d_bf_versions.inc Index: devdoc/parts/d_bf_versions.inc ================================================================== --- /dev/null +++ devdoc/parts/d_bf_versions.inc @@ -0,0 +1,44 @@ +In Tcllib all changes to a package have to come with an increment of +its version number. What part is incremented (patchlevel, minor, major +version) depends on the kind of change made. With multiple changes in +a commit the highest "wins". + +[para] When working in a development branch the version change can be + deferred until it is time to merge, and then has to cover all + the changes in the branch. + +[para] Below a list of the kinds of changes and their associated + version increments: + +[list_begin definitions] +[def [term {D - documentation}]] No increment +[def [term {T - testsuite}]] No increment +[def [term {B - bugfix}]] Patchlevel +[def [term {I - implementation tweak}]] Patchlevel +[def [term {P - performance tweak}]] Patchlevel +[def [term {E - backward-compatible extension}]] Minor +[def [term {API - incompatible change}]] Major +[list_end] + +[para] Note that a commit containing a version increment has to + mention the new version number in its commit message, as well + as the kind of change which caused it. + +[para] Note further that the version number of a package currently + exists in three places. An increment has to update all of them: + +[list_begin enumerated] +[enum] The package implementation. +[enum] The package index ([file pkgIndex.tcl]) +[enum] The package documentation. +[list_end] + +[para] The [file sak.tcl] command [cmd {validate version}] helps + finding discrepancies between the first two. + + All the other [cmd validate] methods are also of interest to + any developer. Invoke it with + + [example { sak.tcl help validate }] + + to see their documentation. ADDED devdoc/parts/d_branchflow.inc Index: devdoc/parts/d_branchflow.inc ================================================================== --- /dev/null +++ devdoc/parts/d_branchflow.inc @@ -0,0 +1,19 @@ +[comment {===================================================================}] +[subsection {Package Dependencies}] +[include d_bf_dependencies.inc] + +[comment {===================================================================}] +[subsection Trunk] +[include d_bf_trunk.inc] + +[comment {===================================================================}] +[subsection Branches] +[include d_bf_branches.inc] + +[comment {===================================================================}] +[subsection {Working with Branches}] +[include d_bf_branchcmds.inc] + +[comment {===================================================================}] +[subsection {Version numbers}] +[include d_bf_versions.inc] ADDED devdoc/parts/d_contrib.inc Index: devdoc/parts/d_contrib.inc ================================================================== --- /dev/null +++ devdoc/parts/d_contrib.inc @@ -0,0 +1,18 @@ + +As a contributor to Tcllib you are committing yourself to: + +[list_begin enumerated] + +[enum] keep the guidelines written down in + [term {Tcl Community - Kind Communication}] in your mind. + The main point to take away from there is + [emph {to be kind to each other}]. + +[enum] Your contributions getting distributed under a BSD/MIT license. + For the details see [term {Tcllib - License}] + +[list_end] + +Contributions are made by entering tickets into our tracker, providing +patches, bundles or branches of code for inclusion, or posting to the +Tcllib related mailing lists. ADDED devdoc/parts/d_dirlayout.inc Index: devdoc/parts/d_dirlayout.inc ================================================================== --- /dev/null +++ devdoc/parts/d_dirlayout.inc @@ -0,0 +1,149 @@ + +[subsection {Main Directories}] + +The main directories in the Tcllib toplevel directory and of interest +to a developer are: + +[list_begin definitions] + +[def [file modules]] + +Each child directory represents one or more packages. + +In the case of the latter the packages are usually related in some +way. Examples are [file base64], [file math], and [file struct], with +loose (base64) to strong (math) relations between the packages in the +directory. + +[def [file apps]] + +This directory contains all the installable applications, with their +documentation. Note that this directory is currently [emph not] split +into sub-directories. + +[def [file examples]] + +Each child directory [file foo] contains one or more example +application for the packages in [file modules/foo]. These examples are +generally not polished enough to be considered for installation. + +[list_end] + +[subsection {More Directories}] + +[list_begin definitions] + +[def [file config]] + +This directory contains files supporting the Unix build system, +i.e. [file configure] and [file Makefile.in]. + +[def [file devdoc]] + +This directories contains the doctools sources for the global +documentation, like this document and its sibling guides. + +[def [file embedded]] + +This directory contains the entire documentation formatted for +[term HTML] and styled to properly mix into the web site generated by +fossil for the repository. + +[para] This is the documentation accessible from the Tcllib home +directory, represented in the repository as [file embedded/index.md]. + +[def [file idoc]] + +This directory contains the entire documentation formatted for +[term nroff] and [term HTML], the latter without any styling. +This is the documentation which will be installed. + +[def [file support]] + +This directory contains the sources of internal packages and utilities +used in the implementation of the [file installer.tcl] and +[file sak.tcl] scripts/tools. + +[list_end] + +[subsection {Top Files}] + +[list_begin definitions] +[def [file aclocal.m4]] +[def [file configure]] +[def [file configure.in]] +[def [file Makefile.in]] + +These four files comprise the Unix build system layered on top of the +[file installer.tcl] script. + +[def [file installer.tcl]] + +The Tcl-based installation script/tool. + +[def [file project.shed]] + +Configuration file for [term {Sean Wood}]'s [syscmd PracTcl] +buildsystem. + +[def [file sak.tcl]] +This is the main tool for developers and release managers, the +[term {Swiss Army Knife}] of management operations on the collection. + +[def [file ChangeLog]] + +The log of changes to the global support, when the sources were held +in [term CVS]. Not relevant any longer with the switch to the +[term fossil] SCM. + +[def [file license.terms]] + +The license in plain ASCII. See also [term {Tcllib - License}] for the +nicely formatted form. The text is identical. + +[def [file README.md]] +[def [file .github/CONTRIBUTING.md]] +[def [file .github/ISSUE_TEMPLATE.md]] +[def [file .github/PULL_REQUEST_TEMPLATE.md]] + +These markdown-formatted documents are used and shown by the github +mirror of these sources, pointing people back to the official location +and issue trackers. + +[def [file DESCRIPTION.txt]] +[def [file STATUS]] +[def [file tcllib.spec]] +[def [file tcllib.tap]] +[def [file tcllib.yml]] + +???? + +[list_end] + +[subsection {File Types}] + +The most common file types, by file extension, are: + +[list_begin definitions] + +[def [file .tcl]] +Tcl code for a package, application, or example. + +[def [file .man]] +Doctools-formatted documentation, usually for a package. + +[def [file .test]] +Test suite for a package, or part of. +Based on [package tcltest]. + +[def [file .bench]] +Performance benchmarks for a package, or part of. +Based on [file modules/bench]. + +[def [file .pcx]] +Syntax rules for [term TclDevKit]'s [syscmd tclchecker]. Using these +rules allows the checker to validate the use of commands of a Tcllib +package [package foo] without having to scan the [file .tcl] files +implementing it. + +[list_end] ADDED devdoc/parts/d_documentation.inc Index: devdoc/parts/d_documentation.inc ================================================================== --- /dev/null +++ devdoc/parts/d_documentation.inc @@ -0,0 +1,76 @@ + +The standard format used for documentation of packages and other +things in Tcllib is [term doctools]. + +Its supporting packages are a part of Tcllib, see the directories +[file modules/doctools] and [file modules/dtplite]. The latter is +an application package, with the actual application +[file apps/dtplite] a light wrapper around it. + +[para] Tcllib developers gain access to these through the [cmd doc] +method of the [file sak.tcl] tool, another (internal) wrapper around +the [file modules/dtplite] application package. + +[comment {===================================================================}] +[subsection {Generate documentation for a specific module}] + +Invoke either + +[example { ./sak.tcl doc html foo }] + +or + +[example { ./sak.tcl doc html modules/foo }] + +to generate HTML for the documentation found in the module [file foo]. + +Instead of [const html] any other supported format can be used here, +of course. + +[para] The generated formatted documentation will be placed into a +directory [file doc] in the current working directory. + +[comment {===================================================================}] +[subsection {Generate documentation for all modules}] + +Invoke the tool without a module name, i.e. + +[example { ./sak.tcl doc html }] + +to generate HTML for the documentation found in all modules. + +Instead of [const html] any other supported format can be used here, +of course. + +[para] The generated formatted documentation will be placed into a +directory [file doc] in the current working directory. + +[comment {===================================================================}] +[subsection {Available output formats, help}] + +Invoke the tool as + +[example { ./sak.tcl help doc }] + +to see the entire set of supported output formats which can be +generated. + +[comment {===================================================================}] +[subsection {Validation without output}] + +Note the special format [const validate]. + +[para] Using this value as the name of the format to generate forces +the tool to simply check that the documentation is syntactically +correct, without generating actual output. + +[para] Invoke it as either + +[example { ./sak.tcl doc validate (modules/)foo }] + +or + +[example { ./sak.tcl doc validate }] + +to either check the packages of a specific module or check all of +them. ADDED devdoc/parts/d_installation.inc Index: devdoc/parts/d_installation.inc ================================================================== --- /dev/null +++ devdoc/parts/d_installation.inc @@ -0,0 +1,94 @@ +A last thing to consider when adding a new package to the collection +is installation. + +[para] How to [emph use] the [file installer.tcl] script is documented +in [term {Tcllib - The Installer's Guide}]. + +[para] Here we document how to extend said installer so that it may +install new package(s) and/or application(s). + +[para] In most cases only a single file has to be modified, the +[file support/installation/modules.tcl] holding one command per module +and application to install. + +[para] The relevant commands are: + +[list_begin definitions] + +[call [cmd Module] [arg name] \ + [arg code-action] \ + [arg doc-action] \ + [arg example-action]] + +Install the packages of module [arg name], found in +[file modules/[arg name]]. + +[para] The [arg code-action] is responsible for installing the +packages and their index. The system currently provides + +[list_begin definitions] + +[def [cmd _tcl]] Copy all [file .tcl] files found in +[file modules/[arg name]] into the installation. + +[def [cmd _tcr]] As [cmd _tcl], copy the [file .tcl] files found in +the subdirectories of [file modules/[arg name]] as well. + +[def [cmd _tci]] As [cmd _tcl], and copy the [file tclIndex.tcl] file +as well. + +[def [cmd _msg]] As [cmd _tcl], and copy the subdirectory [file msgs] +as well. + +[def [cmd _doc]] As [cmd _tcl], and copy the subdirectory +[file mpformats] as well. + +[def [cmd _tex]] As [cmd _tcl], and copy [file .tex] files as well. + +[list_end] + +[para] The [arg doc-action] is responsible for installing the package +documentation. The system currently provides + +[list_begin definitions] +[def [cmd _null]] No documentation available, do nothing. + +[def [cmd _man]] Process the [file .man] files found in +[file modules/[arg name]] and install the results (nroff and/or HTML) +in the proper location, as given to the installer. + +[para] This is actually a fallback, normally the installer uses the +pre-made formatted documentation found under [file idoc]. + +[list_end] + +[para] The [arg example-action] is responsible for installing the +examples. The system currently provides + +[list_begin definitions] +[def [cmd _null]] No examples available, do nothing. + +[def [cmd _exa]] Copy the the directory [file examples/[arg name]] +recursively to the install location for examples. + +[list_end] + +[call [cmd Application] [arg name]] + +Install the application with [arg name], found in [file apps]. + + +[call [cmd Exclude] [arg name]] + +This command signals to the installer which of the listed modules to +[emph not] install. I.e. they name the deprecated modules of Tcllib. + +[list_end] + +[para] If, and only if the above actions are not suitable for the new +module then a second file has to be modified, +[file support/installation/actions.tcl]. + +[para] This file contains the implementations of the available +actions, and is the place where any custom action needed to handle the +special circumstances of module has to be added. ADDED devdoc/parts/d_maintain.inc Index: devdoc/parts/d_maintain.inc ================================================================== --- /dev/null +++ devdoc/parts/d_maintain.inc @@ -0,0 +1,71 @@ + +When contributing one or more packages for full inclusion into Tcllib +you are committing yourself to + +[list_begin enumerated] + +[enum] Keep the guidelines written down in + [term {Tcl Community - Kind Communication}] + (as any contributor) in your mind. The main point to take away + from there is [emph {to be kind to each other}]. + +[enum] Your packages getting distributed under a BSD/MIT license. For + the details see [term {Tcllib - License}] + +[enum] Maintenance of the new packages for a period of two years under + the following rules, and responsibilities: + + [list_begin enumerated] + + [enum] A maintainer may step down after the mandatory period as + they see fit. + + [enum] A maintainer may step down before the end of the + mandatory period, under the condition that a replacement + maintainer is immediately available and has agreed to + serve the remainder of the period, plus their own + mandatory period (see below). + + [enum] When stepping down without a replacement maintainer + taking over the relevant packages have to be flagged as + [const unmaintained]. + + [enum] When a replacement mantainer is brought in for a package + it is (kept) marked as [const maintained] (again). + + [para] A replacement maintainer is bound by the same rules as + the original maintainer, except that the mandatory + period of maintenance is shortened to one year. + + [enum] For any [const unmaintained] package a contributor + interested in becoming its maintainer can become so by + flagging them as [const maintained] with their name and + contact information, committing themselves to the rules + of a replacement maintainer (see previous point). + + [enum] For any already [const maintained] package a contributor + interested in becoming a co-maintainer can become so + with the agreement of the existing maintainer(s), + committing themselves to the rules of a replacement + maintainer (see two points previous). + + [list_end] + + [para] The responsibilities as a maintainer include: + + [list_begin enumerated] + + [enum] Watching Tcllib's ticket tracker for bugs, bug fixes, + and feature requests related to the new packages. + + [enum] Reviewing the aforementioned tickets, rejecting or + applying them + + [enum] Coordination and discussion with ticket submitter during + the development and/or application of bug fixes. + + [list_end] + +[enum] Follow the [sectref {Branching and Workflow}] of this guide. + +[list_end] ADDED devdoc/parts/d_op_aware.inc Index: devdoc/parts/d_op_aware.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_aware.inc @@ -0,0 +1,57 @@ + +When developing we have to keep ourselves aware of the context of our +work. On what branch are we ? What files have we changed ? What new +files are not yet known to the repository ? What has happened remotely +since we used our checkout ? + +The answers to these questions become especially important when using +a long-lived checkout and coming back to it after some time away. + +[para] Commands to answer questions like the above are: + +[list_begin definitions] + +[def [cmd {fossil pull}]] + + Get all changes done on the remote since the last pull or sync + from it. This has to be done first, before any of the commands + below. + +[para] Even if the commit in our checkout refers to the branch we want + right now control operations committed to the remote may have + changed that from underneath us. + +[def [cmd {fossil info | grep tags}]] +[def [cmd {fossil branch list | grep '\*'}]] + + Two different ways of determining the branch our checkout is + on. + +[def [cmd {fossil timeline}]] + + What have we (and others) done recently ? + +[para] [emph Attention], this information is very likely outdated, the + more the longer we did not use this checkout. + + Run [cmd {fossil pull}] first to get latest information from + the remote repository of the project. + +[def [cmd {fossil timeline current}]] + + Place the commit our checkout is based on at the top of the + timeline. + +[def [cmd {fossil changes}]] + + Lists the files we have changed compared to the commit the + checkout is based on. + +[def [cmd {fossil extra}]] + + Lists the files we have in the checkout the repository does not + know about. This may be leftover chaff from our work, or + something we have forgotten to [cmd {fossil add}] to the + repository yet. + +[list_end] ADDED devdoc/parts/d_op_branch_close.inc Index: devdoc/parts/d_op_branch_close.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_branch_close.inc @@ -0,0 +1,73 @@ + +Be aware of where you are (see first definition). + +[para] Ensure that you have clean checkout (see second definition). + + In the full-blown sequence (zig-zag) it is [emph required], due + to the merging from trunk. In the shorter sequence it is only + desired. That said, keeping the checkout clean before + any major operations is a good habit to have, in my opinion. + +[para] The full-blown sequencing with checks all the way is to + +[list_begin enumerated] + +[enum] Validate the checkout, i.e. last commit on your branch. Run the + full test suite and other validations, fix all the issues which + have cropped up. + +[enum] Merge the latest state of the [term trunk] (see next definition). + +[enum] Validate the checkout again. The incoming trunk changes may + have broken something now. Do any required fixes. + +[enum] Now merge to the trunk using + +[example { + fossil update trunk + fossil merge --integrate YOUR_BRANCH +}] + +[enum] At this point the checkout should be in the same state as at + the end of point (3) above, because we resolved any issues with + the trunk already. Thus a simple + +[example { + fossil commit ... +}] + + should be sufficient now to commit the merge back and close the + branch (due to the [option --integrate] we used on the merge). + +[para] The more paranoid may validate the checkout a third time before + commiting. +[list_end] + +[para] I call this a [term {zig-zag merge}] because of how the arrows + look in the timeline, from trunk to feature branch for the + first merge, and then back for the final merge. + +[para] A less paranoid can do what I call a [term {simple merge}], + which moves step (2) after step (4) and skips step (3) + entirely. The resulting shorter sequence is + +[list_begin enumerated] +[enum] Validate +[enum] Merge to trunk +[enum] Validate again +[enum] Commit to trunk +[list_end] + +The last step after either zig-zag or plain merge is to + +[example { + fossil sync +}] + +This saves our work to the remote side, and further gives us any other +work done while we were doing our merge. It especially allows us to +check if we raced somebody else, resulting in a split trunk. + +[para] When that happens we should coordinate with the other developer + on who fixes the split, to ensure that we do not race each + other again. ADDED devdoc/parts/d_op_branch_import.inc Index: devdoc/parts/d_op_branch_import.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_branch_import.inc @@ -0,0 +1,32 @@ + +Be aware of where you are (see first definition). + +[para] Ensure that you have clean checkout (see second definition). + It is [emph required]. + +[para] In most situations you want to import the latest commit of + branch [term trunk] (or other origin). To get it use + +[example { + fossil pull +}] + +[para] With that done we can now import this commit into our current + branch with + +[example { + fossil merge trunk +}] + +[para] Even if [syscmd fossil] does not report any conflicts it is a + good idea to check that the operation has not broken the new + and/or changed functionality we are working on. + +[para] With the establishment of a good merge we then save the state + with + +[example { + fossil commit ... +}] + +before continuing development. ADDED devdoc/parts/d_op_branch_open.inc Index: devdoc/parts/d_op_branch_open.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_branch_open.inc @@ -0,0 +1,59 @@ + +Be aware of where you are (see first definition). + +[para] Ensure that you have clean checkout (see second definition). + It is [emph required]. + +[para] In most situations you want to be on branch [term trunk], and + you want to be on the latest commit for it. To get there use + +[example { + fossil pull + fossil update trunk +}] + +If some other branch is desired as the starting point for the coming +work replace [term trunk] in the commands above with the name of that +branch. + +[para] With the base line established we now have two ways of creating + the new branch, with differing (dis)advantages. + + The simpler way is to + +[example { + fossil branch new NAME_OF_NEW_BRANCH +}] + +and start developing. The advantage here is that you cannot forget to +create the branch. The disadvantages are that we have a branch commit +unchanged from where we branched from, and that we have to use +high-handed techniques like hiding or shunning to get rid of the +commit should we decide to abandon the work before the first actual +commit on the branch. + +[para] The other way of creating the branch is to start developing, +and then on the first commit use the option [option --branch] to tell +[syscmd fossil] that we are starting a branch now. I.e. run + +[example { + fossil commit --branch NAME_OF_NEW_BRANCH ... +}] + +where [term ...] are any other options used to supply the commit +message, files to commit, etc. + +[para] The (dis)advantages are now reversed. + +[para] We have no superflous commit, only what is actually + developed. The work is hidden until we commit to make our first + commit. + +[para] We may forget to use [option {--branch NAME_OF_NEW_BRANCH}] and + then have to correct that oversight via the fossil web + interface (I am currently unaware of ways of doing such from + the command line, although some magic incantantion of + [cmd {fossil tag create}] may work). + +[para] It helps to keep awareness, like checking before any commit + that we are on the desired branch. ADDED devdoc/parts/d_op_clean.inc Index: devdoc/parts/d_op_clean.inc ================================================================== --- /dev/null +++ devdoc/parts/d_op_clean.inc @@ -0,0 +1,14 @@ + +Be aware of where you are (see first definition). + +[para] For pretty much all the operation recipes below a clean + checkout is at least desired, often required. + To check that a checkout is clean invoke + +[example { + fossil changes + fossil extra +}] + +How to clean up when uncommitted changes of all sorts are found is +context-specific and outside of the scope of this guide. ADDED devdoc/parts/d_testing.inc Index: devdoc/parts/d_testing.inc ================================================================== --- /dev/null +++ devdoc/parts/d_testing.inc @@ -0,0 +1,90 @@ + +Testsuites in Tcllib are based on Tcl's standard test package +[package tcltest], plus utilities found in the directory +[file modules/devtools] + +[para] Tcllib developers invoke the suites through the +[cmd {test run}] method of the [file sak.tcl] tool, with other methods +of [cmd test] providing management operations, for example setting a +list of standard Tcl shells to use. + +[comment {===================================================================}] +[subsection {Invoke the testsuites of a specific module}] + +Invoke either + +[example { ./sak.tcl test run foo }] + +or + +[example { ./sak.tcl test run modules/foo }] + +to invoke the testsuites found in a specific module [file foo]. + +[comment {===================================================================}] +[subsection {Invoke the testsuites of all modules}] + +Invoke the tool without a module name, i.e. + +[example { ./sak.tcl test run }] + +to invoke the testsuites of all modules. + +[comment {===================================================================}] +[subsection {Detailed Test Logs}] + +In all the previous examples the test runner will write a combination +of progress display and testsuite log to the standard output, showing +for each module only the tests that passed or failed and how many of +each in a summary at the end. + +[para] To get a detailed log, it is necessary to invoke the test +runner with additional options. + +[para] For one: + +[example { + ./sak.tcl test run --log LOG foo +}] + +While this shows the same short log on the terminal as before, it also +writes a detailed log to the file [file LOG.log], and excerpts to +other files ([file LOG.summary], [file LOG.failures], etc.). + +[para] For two: + +[example { + ./sak.tcl test run -v foo +}] + +This writes the detailed log to the standard output, instead of the +short log. + +[para] Regardless of form, the detailed log contains a list of all test +cases executed, which failed, and how they failed (expected versus +actual results). + +[comment {===================================================================}] +[subsection {Shell Selection}] + +By default the test runner will use all the Tcl shells specified via +[cmd {test add}] to invoke the specified testsuites, if any. If no +such are specified it will fall back to the Tcl shell used to run the +tool itself. + +[para] Use option [option --shell] to explicitly specify the Tcl shell +to use, like + +[example { + ./sak.tcl test run --shell /path/to/tclsh ... +}] + +[comment {===================================================================}] +[subsection Help] + +Invoke the tool as + +[example { ./sak.tcl help test }] + +to see the detailed help for all methods of [cmd test], and the +associated options. ADDED devdoc/parts/d_testwrite.inc Index: devdoc/parts/d_testwrite.inc ================================================================== --- /dev/null +++ devdoc/parts/d_testwrite.inc @@ -0,0 +1,119 @@ + +While previous sections talked about running the testsuites for a +module and the packages therein, this has no meaning if the module in +question has no testsuites at all. + +[para] This section gives a very basic overview on possible +methodologies for writing tests and testsuites. + +[para] First there are "drudgery" tests. Written to check absolutely +basic assumptions which should never fail. + +[para] For example for a command FOO taking two arguments, three tests +calling it with zero, one, and three arguments. The basic checks that +the command fails if it has not enough arguments, or too many. + +[para] After that come the tests checking things based on our +knowledge of the command, about its properties and assumptions. Some +examples based on the graph operations added during Google's Summer of +Code 2009 are: + +[list_begin itemized] + +[item] The BellmanFord command in struct::graph::ops takes a + [arg startnode] as argument, and this node should be a node of + the graph. This equals one test case checking the behavior when the + specified node is not a node of the graph. + +[para] This often gives rise to code in the implementation which + explicitly checks the assumption and throws an understandable error, + instead of letting the algorithm fail later in some weird + non-deterministic way. + +[para] It is not always possible to do such checks. The graph argument + for example is just a command in itself, and while we expect + it to exhibit a certain interface, i.e. a set of sub-commands + aka methods, we cannot check that it has them, except by + actually trying to use them. That is done by the algorithm + anyway, so an explicit check is just overhead we can get by + without. + +[item] IIRC one of the distinguishing characteristic of either + BellmanFord and/or Johnson is that they are able to handle + negative weights. Whereas Dijkstra requires positive weights. + +[para] This induces (at least) three testcases ... Graph with all + positive weights, all negative, and a mix of positive and + negative weights. + + Thinking further does the algorithm handle the weight + [const 0] as well ? Another test case, or several, if we mix + zero with positive and negative weights. + +[item] The two algorithms we are currently thinking about are about + distances between nodes, and distance can be 'Inf'inity, + i.e. nodes may not be connected. This means that good test + cases are + + [list_begin enumerated] + [enum] Strongly connected graph + [enum] Connected graph + [enum] Disconnected graph. + [list_end] + + [para] At the extremes of strongly connected and disconnected + we have the fully connected graphs and graphs without edges, + only nodes, i.e. completely disconnected. + +[item] IIRC both of the algorithms take weighted arcs, and fill in a + default if arcs are left unweighted in the input graph. + + [para] This also induces three test cases: + + [list_begin enumerated] + [enum] Graph will all arcs with explicit weights. + [enum] Graph without weights at all. + [enum] Graph with mixture of weighted and unweighted graphs. + [list_end] +[list_end] + +[para] What was described above via examples is called +[term black-box] testing. Test cases are designed and written based on +the developer's knowledge of the properties of the algorithm and its +inputs, without referencing a particular implementation. + +[para] Going further, a complement to [term black-box] testing is +[term white-box]. For this we know the implementation of the +algorithm, we look at it and design our tests cases so that they force +the code through all possible paths in the implementation. Wherever a +decision is made we have a test case forcing a specific direction of +the decision, for all possible combinations and directions. It is easy +to get a combinatorial explosion in the number of needed test-cases. + +[para] In practice I often hope that the black-box tests I have made +are enough to cover all the paths, obviating the need for white-box +tests. + +[para] The above should be enough to make it clear that writing tests +for an algorithm takes at least as much time as coding the algorithm, +and often more time. Much more time. + +See for example also [uri http://sqlite.org/testing.html], a writeup +on how the Sqlite database engine is tested. Another article of +interest might be [uri https://www.researchgate.net/publication/298896236]. +While geared to a particular numerical algorithm it still shows that +even a simple-looking algorithm can lead to an incredible number of +test cases. + +[para] An interesting connection is to documentation. In one +direction, the properties checked with black-box testing are exactly +the properties which should be documented in the algorithm's man +page. And conversely, the documentation of the properties of an +algorithm makes a good reference to base the black-box tests on. + +[para] In practice test cases and documentation often get written +together, cross-influencing each other. And the actual writing of test +cases is a mix of black and white box, possibly influencing the +implementation while writing the tests. Like writing a test for a +condition like [term {startnode not in input graph}] serving as +reminder to put a check for this condition into the code. ADDED devdoc/parts/rm_distribute.inc Index: devdoc/parts/rm_distribute.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_distribute.inc @@ -0,0 +1,39 @@ + +With the release made it has to be published and the world notified of +its existence. + +[list_begin enumerated] + +[enum] Create a proper fossil event for the release, via + [uri http://core.tcl-lang.org/tcllib/eventedit]. + +[para] An [uri http://core.tcl-lang.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817 {existing event}] should be used as template. + +[enum] Update a number of web locations: + +[list_begin enumerated] +[enum] [uri http://core.tcl-lang.org/tcllib/doc/trunk/embedded/index.md {Home page}] +[enum] [uri http://core.tcl-lang.org/tcllib/wiki?name=Downloads Downloads] +[enum] [uri http://core.tcl-lang.org/tcllib/wiki?name=Past+Releases {Past Releases}] +[enum] [uri http://www.tcl-lang.org/home/release.txt ] +[enum] [uri http://www.tcl-lang.org/software/tcllib/*.tml] +[enum] [uri http://wiki.tcl-lang.org/page/Tcllib] +[list_end] + +The first location maps to the file [file embedded/index.md] in the +repository itself, as such it can edited as part of the release +process. This is where reference to the new fossil event is added, as +the new current release. + +[para] The next two locations are in the fossil tcllib wiki and +require admin or wiki write permissions for +[uri http://core.tcl-lang.org/tcllib]. + +[para] The last two locations require ssh access to +[uri http://www.tcl-lang.org] and permission to edit +files in the web area. + + +[enum] ***TODO*** mailing lists and other places to send notes to. + +[list_end] ADDED devdoc/parts/rm_final.inc Index: devdoc/parts/rm_final.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_final.inc @@ -0,0 +1,1 @@ +todo: finalize release, make candidate official ADDED devdoc/parts/rm_start.inc Index: devdoc/parts/rm_start.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_start.inc @@ -0,0 +1,1 @@ +todo: open a candidate for release ADDED devdoc/parts/rm_tooling.inc Index: devdoc/parts/rm_tooling.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_tooling.inc @@ -0,0 +1,18 @@ + +The [file sak.tcl] script in the toplevel directory of a Tcllib +checkout is the one tool used by the release manager to perform its +[sectref Tasks]. + +[para] The main commands to be used are + +[example { + sak.tcl validate + sak.tcl test run + sak.tcl review + sak.tcl readme + sak.tcl localdoc + sak.tcl release +}] + +More detail will be provided in the explanations of the various +[sectref Tasks]. ADDED devdoc/parts/rm_work.inc Index: devdoc/parts/rm_work.inc ================================================================== --- /dev/null +++ devdoc/parts/rm_work.inc @@ -0,0 +1,7 @@ +todo: test, validate and check that the candidate is worthy of release +fix testsuites, possibly fix packages, documentation +regenerate docs +coordinate with package maintainers wrt fixes + +big thing: going over the packages, classify changes since last +release to generate a nice readme. ADDED devdoc/parts/rq_critcl.inc Index: devdoc/parts/rq_critcl.inc ================================================================== --- /dev/null +++ devdoc/parts/rq_critcl.inc @@ -0,0 +1,35 @@ + +[subsection Critcl] + +The [syscmd critcl] tool is an [emph optional] dependency. + +[para] It is only required when trying to build the C-based +[term accelerators] for a number of packages, as explained in +[sectref {Critcl & Accelerators}] + +[para] Tcllib's build system looks for it in the [variable PATH], +using the name [syscmd critcl]. This is for Unix. + +On Windows on the other hand the search is more complex. First we look +for a proper application [syscmd critcl.exe]. When that is not found +we look for a combination of interpreter ([syscmd tclkitsh.exe], +[syscmd tclsh.exe]) and starkit ([syscmd critcl.kit], [syscmd critcl]) +instead. [emph Note] that the choice of starkit can be overriden via +the environment variable [variable CRITCL]. + +[para] Tcllib requires Critcl version 2 or higher. + +[para] The github repository providing releases of version 2 and +higher, and the associated sources, can be found at +[uri http://andreas-kupries.github.com/critcl]. + +[para] Any branch of the repository can be used (if not using the +prebuild starkit or starpack), although the use of the stable branch +[emph master] is recommended. + +[para] At the above url is also an explanation on how to build and +install Critcl, including a list of its dependencies. + +[para] Its instructions will not be repeated here. If there are +problems with these directions please file a ticket against the +[term Critcl] project, and not Tcllib. ADDED devdoc/parts/rq_tcl.inc Index: devdoc/parts/rq_tcl.inc ================================================================== --- /dev/null +++ devdoc/parts/rq_tcl.inc @@ -0,0 +1,46 @@ + +[subsection Tcl] + +As we are installing a number of Tcl packages and applications it +should be pretty much obvious that a working installation of Tcl +itself is needed, and I will not belabor the point. + +[para] Out of the many possibilities use whatever you are comfortable +with, as long as it provides at the very least Tcl 8.2, or higher. + +This may be a Tcl installation provided by your operating system +distribution, from a distribution-independent vendor, or built by +yourself. + +[para] [emph Note] that the packages in Tcllib have begun to require +8.4, 8.5, and even 8.6. Older versions of Tcl will not be able to use +such packages. Trying to use them will result in +[emph {package not found}] errors, as their package index files will +not register them in versions of the core unable to use them. + +[para] Myself, I used (and still use) +[uri http://www.activestate.com ActiveState's] +ActiveTcl 8.5 distribution during development, as I am most familiar +with it. + +[para] [emph {(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, maintaining ActiveTcl and TclDevKit for them).}]. +I am currently working for SUSE Software Canada ULC, although not in +Tcl-related areas. + +[para] This distribution can be found at +[uri http://www.activestate.com/activetcl]. Retrieve the archive of +ActiveTcl 8.5 (or higher) for your platform and install it as directed +by ActiveState. + +[para] For those wishing to build and install Tcl on their own, the +relevant sources can be found at + +[list_begin definitions] +[def Tcl] [uri http://core.tcl-lang.org/tcl/] +[list_end] + +together with the necessary instructions on how to build it. + +[para] If there are problems with building, installing, or using Tcl, +please file a ticket against [term Tcl], or the vendor of your +distribution, and [emph not] [term Tcllib]. ADDED devdoc/parts/welcome.inc Index: devdoc/parts/welcome.inc ================================================================== --- /dev/null +++ devdoc/parts/welcome.inc @@ -0,0 +1,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 Index: devdoc/releaseguide.html ================================================================== --- devdoc/releaseguide.html +++ /dev/null @@ -1,72 +0,0 @@ - - -

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:anonymous@cvs.tcllib.sourceforge.net:/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. -

ADDED devdoc/tcl_community_communication.man Index: devdoc/tcl_community_communication.man ================================================================== --- /dev/null +++ devdoc/tcl_community_communication.man @@ -0,0 +1,178 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin tcl_community_communication n 1] +[titledesc {Tcl Community - Kind Communication}] +[description] + +The Tcl Community encourages contributions from anyone who wishes to +advance the development of: + +[list_begin itemized] +[item] The Tcl Language +[item] Tcl derived languages +[item] Tcl related libraries +[item] Tcl extensions +[item] External Projects that Integrate Tcl +[list_end] + +[para] We welcome those contributions from anyone. We are blind to +gender, race, religion, cultural background, cybernetic nature, and +any other demographic characteristics, as well as personal political +views. + +[para] A community lives and dies by communications. And occasionally +our communications are peppered with patterns that are harsh, +unfriendly, unwelcoming and/or otherwise unkind. As a volunteer +community, we need all of the help we can get. Therefore, we ask all +contributors to make a conscious effort, in Tcl Community discussions, +to communicate in ways that are welcoming. Ways that are +friendly. Ways that are, in a word: kind. + +[para] These guidelines suggest specific ways to accomplish that goal. + +[para] Please note: for the balance of this document any reference to +"People", "Persons", "anybody" or "somebody" can refer to any sentient +being, not merely corporeal members of the species Homo Sapien. + +[list_begin definitions] + +[def {We are a Sanctuary not a Clubhouse}] + +The Tcl Community is a collective of amateurs and professionals who +code, test, and use tools. Our community is open to all. There is no +velvet rope. There is no bouncer at the door. There are no secret +handshakes. Any sentient being who enters our midst is welcome. If +someone is ever asked to leave, it is only because they are being +disruptive to the functioning of the community. + +[def {We Merit Ideas, Not People}] + +A good idea can come from anyone, regardless of how little time they +have been with us. A bad idea can come from anyone, regardless of how +much time or how little time they have been with us. We judge a +concept by how it stands up to scrutiny of logic, implementation, and +regression testing. We don’t judge ideas based on who had the idea +first, who agrees with the idea, or who disagrees with it. + +[def {Treat Everyone with Respect}] + +Everyone is deserving of respect and courtesy at all times. + +[def {Refer to people by the names they use.}] + +If grammar requires you to state a gender for a person, honor their +preferences about their gender identity. If you are unsure as to the +gender of an individual, ask. If someone had to guess about your +gender and got it wrong, please correct them and do not take it +personally. + +[def {Do not take a harsh tone towards other participants.}] + +Do not make personal attacks against anyone (participant or not.) + +[para] Criticize statements and actions, never people. + +[def {Don’t Take Things Personally}] + +When in doubt, assume the best in people. A criticism of your +statements is not a personal attack on you. + +[def {Persons, not People}] + +Stereotypes are an unhelpful tool on many accounts. They are generally +oversimplified. They are usually flat out wrong. And even if "right" +they are of absolutely no utility in determining the capabilities, +motivations, or fitness of an individual. + +[para] Don’t use them in Tcl Community communications. + +[def {Mistakes Happen}] + +The human condition is a series of trials and errors. Progress is when +we get one more trial than error. Being wrong or making a mistake is +the default state of humanity. Accept the errors of your fellow +sentient beings, and be aware that you are also fallible. + +[def {Keep it Real}] + +Please respond to what people actually say. We are all amazing +individuals, but none among us are mind readers. If you find yourself +responding to what you imagine someone is thinking, odds are you are +going to be wrong. + +[para] If you must criticize someone, stick to things they have +actually done. Never criticize for something you speculate they have +done. Or imagine they have done. Or something someone who shares some +attribute with them has done in the past. + +[para] Keep discussions about any non-Tcl subjects to what can be +stated factually and without emotion or judgement. + +[def {When Trouble Arises, Don’t Escalate}] + +If you feel you are being personally attacked or offended, take the +high road. Punching back in a public forum will only makes things +worse. Address the matter in a private correspondence. Be +polite. Express your feelings, but note that you are expressing your +feelings. When writing, look for a way to calm matters down. And when +in doubt, sleep on your letter before pressing send. And when not in +doubt, sleep on it for another day after that. + +[para] If you are a spectator to a fight in progress, politely request +the two parties take the matter to a more private forum. + +[def {Always get the Last Word: I’m Sorry}] + +If an personal argument does arise, be the first to apologize. An +apology does not concede a logical point. It merely acknowledges that +at some point the discussion left either logic, community decency, or +both. Return to the topic when cooler heads can prevail. + +[def {Nobody is Keeping Score}] + +There is no prize for being right. There is no cost for being wrong. A +hard sell is not going to advance your idea along any more than a +logical argument. You aren’t running for office. This isn’t debate +club. If you find yourself continuing a discussion beyond where a +topic can be logically discussed, stop. + +[def {No Evangelizing}] + +The Tcl Community is not the place to promote your chosen operating +system, political outlook, religion, marketing scheme, or economic +model. Period. + +[para] (And if you do bring it up, be prepared to have your chosen +topic discussed logically. And odds are, not favorably.) + +[def {Respect the Community}] + +If the Community has come to a decision on a course of action, please +stop arguing. + +[para] If someone complains about how you are expressing your ideas, +listen. + +[para] If your words are hurting people, stop. There is no amount of +being "right" that makes up for someone leaving our midst because they +felt insulted, threatened, or ignored. + +[list_end] + +By following these guidelines, we will build our community, encourage +more contribution to our projects, and our discussions will be +friendlier and reach conclusions more easily. + +[para] Thank You. + +[section Signatories] +[list_begin itemized] +[item] Sean "the Hypnotoad" Woods +[item] Andreas Kupries +[list_end] + +[section Authors] +[list_begin definitions] +[def Primary] Sean "the Hypnotoad" Woods +[def {Light editing}] Andreas Kupries +[list_end] +[manpage_end] ADDED devdoc/tcllib_devguide.man Index: devdoc/tcllib_devguide.man ================================================================== --- /dev/null +++ devdoc/tcllib_devguide.man @@ -0,0 +1,62 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin tcllib_devguide n 1] +[titledesc {Tcllib - The Developer's Guide}] +[description] +[include parts/welcome.inc] + +[para] + +This document is a guide for developers working on Tcllib, +i.e. maintainers fixing bugs, extending the collection's +functionality, etc. + +[para] + +Please read + +[list_begin enum] +[enum] [term {Tcllib - How To Get The Sources}] and +[enum] [term {Tcllib - The Installer's Guide}] +[list_end] + +first, if that was not done already. + +[para] Here we assume that the sources are already available in a +directory of your choice, and that you not only know how to build and +install them, but also have all the necessary requisites to actually +do so. The guide to the sources in particular also explains which +source code management system is used, where to find it, how to set it +up, etc. + +[comment {===================================================================}] +[section Commitments] +[subsection Contributor][include parts/d_contrib.inc] +[subsection Maintainer][include parts/d_maintain.inc] + +[comment {===================================================================}] +[section {Branching and Workflow}] +[include parts/d_branchflow.inc] + +[comment {===================================================================}] +[section {Structural Overview}] +[include parts/d_dirlayout.inc] + +[comment {===================================================================}] +[section {Testsuite Tooling}] +[include parts/d_testing.inc] + +[comment {===================================================================}] +[section {Documentation Tooling}] +[include parts/d_documentation.inc] + +[comment {===================================================================}] +[section {Notes On Writing A Testsuite}] +[include parts/d_testwrite.inc] + +[comment {===================================================================}] +[section {Installation Tooling}] +[include parts/d_installation.inc] + +[comment {===================================================================}] +[manpage_end] + ADDED devdoc/tcllib_installer.man Index: devdoc/tcllib_installer.man ================================================================== --- /dev/null +++ devdoc/tcllib_installer.man @@ -0,0 +1,90 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin tcllib_install_guide n 1] +[titledesc {Tcllib - The Installer's Guide}] +[description] +[include parts/welcome.inc] + +[para] + +The audience of this document is anyone wishing to build and install +the packages found in Tcllib, for either themselves, or others. + +[para] + +For developers intending to work on the packages themselves we +additionally provide + +[list_begin enum] +[enum] [term {Tcllib - The Developer's Guide}]. +[list_end] + +[para] + +Please read [term {Tcllib - How To Get The Sources}] first, if that +was not done already. Here we assume that the sources are already +available in a directory of your choice. + +[para] + +[comment {===================================================================}] +[section Requisites] + +Before Tcllib can be build and used a number of requisites must be installed. + +These are: + +[list_begin enumerated] +[enum] The scripting language Tcl. + For details see [sectref Tcl]. +[enum] Optionally, the [package critcl] package (C embedding) for [syscmd Tcl]. + For details see [sectref CriTcl]. +[list_end] + +This list assumes that the machine where Tcllib is to be installed is +essentially clean. Of course, if parts of the dependencies listed +below are already installed the associated steps can be skipped. It is +still recommended to read their sections though, to validate that the +dependencies they talk about are indeed installed. + +[include parts/rq_tcl.inc] +[include parts/rq_critcl.inc] + +[comment {= build instructions ==============================================}] +[section {Build & Installation Instructions}] + +As Tcllib is mainly a bundle of packages written in pure Tcl building +it is the same as installing it. The exceptions to this have their own +subsection, [sectref {Critcl & Accelerators}], later on. + +[para] Before that however comes the standard case, differentiated by + the platforms with material differences in the instruction, i.e. + [term Unix]-like, versus [term Windows]. + +[para] Regarding the latter it should also be noted that it is + possible set up an [term Unix]-like environment using projects + like [term MSYS], [term Cygwin], and others. In that case the + user has the choice of which instructions to follow. + +[para] Regardless of environment or platform, a suitable [term Tcl] + has to be installed, and its [syscmd tclsh] should be placed on + the [variable PATH] ([term Unix]) or associated with + [file .tcl] files ([term Windows]). + +[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%] +[subsection {Installing on Unix}] +[include parts/b_unix.inc] + +[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%] +[subsection {Installing on Windows}] +[include parts/b_windows.inc] + +[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%] +[subsection {Critcl & Accelerators}] +[include parts/b_critcl.inc] + +[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%] +[subsection Tooling] +[include parts/b_tooling.inc] + +[manpage_end] + ADDED devdoc/tcllib_license.man Index: devdoc/tcllib_license.man ================================================================== --- /dev/null +++ devdoc/tcllib_license.man @@ -0,0 +1,61 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin tcllib_license n 1] +[titledesc {Tcllib - License}] +[description] +[include parts/welcome.inc] + +[para] The collection is under the BSD license. + +[section License] + +[para] + +This software is copyrighted by Ajuba Solutions and other parties. +The following terms apply to all files associated with the software +unless explicitly disclaimed in individual files. + +[para] + +The authors hereby grant permission to use, copy, modify, distribute, +and license this software and its documentation for any purpose, +provided that existing copyright notices are retained in all copies +and that this notice is included verbatim in any distributions. No +written agreement, license, or royalty fee is required for any of the +authorized uses. Modifications to this software may be copyrighted by +their authors and need not follow the licensing terms described here, +provided that the new terms are clearly indicated on the first page of +each file where they apply. + +[para] + +IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY +FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY +DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + +[para] + +THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, +INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND +NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND +THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE +MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. + +[para] + +GOVERNMENT USE: If you are acquiring this software on behalf of the +U.S. government, the Government shall have only "Restricted Rights" in +the software and related documentation as defined in the Federal +Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you +are acquiring the software on behalf of the Department of Defense, the +software shall be classified as "Commercial Computer Software" and the +Government shall have only "Restricted Rights" as defined in Clause +252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the +authors grant the U.S. Government and others acting in its behalf +permission to use and distribute the software in accordance with the +terms specified in this license. + +[manpage_end] + ADDED devdoc/tcllib_releasemgr.man Index: devdoc/tcllib_releasemgr.man ================================================================== --- /dev/null +++ devdoc/tcllib_releasemgr.man @@ -0,0 +1,45 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin tcllib_releasemgr n 1] +[titledesc {Tcllib - The Release Manager's Guide}] +[description] +[include parts/welcome.inc] + +[para] + +The audience of this document is the release manager for Tcllib, their +deputies, and anybody else interested in the task of creating +an official release of Tcllib for distribution. + +[para] + +Please read [term {Tcllib - How To Get The Sources}] first, if that +was not done already. Here we assume that the sources are already +available in a directory of your choice. + +[para] + +[comment {===================================================================}] +[section Tools] +[include parts/rm_tooling.inc] + +[comment {===================================================================}] +[section Tasks] + +[comment {===================================================================}] +[subsection {Start a release candidate}] +[include parts/rm_start.inc] + +[comment {===================================================================}] +[subsection {Ready the candidate}] +[include parts/rm_work.inc] + +[comment {===================================================================}] +[subsection {Make it official}] +[include parts/rm_final.inc] + +[comment {===================================================================}] +[subsection {Distribute the release}] +[include parts/rm_distribute.inc] + +[manpage_end] + ADDED devdoc/tcllib_sources.man Index: devdoc/tcllib_sources.man ================================================================== --- /dev/null +++ devdoc/tcllib_sources.man @@ -0,0 +1,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] Index: embedded/index.md ================================================================== --- embedded/index.md +++ embedded/index.md @@ -1,22 +1,31 @@

Tcl Library Source Code

-Packages -- [Table Of Contents](md/toc.md) -- [Keyword Index](md/index.md) +Packages - [Table Of Contents](md/toc.md) +    +[Keyword Index](md/index.md)
+## 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/). ADDED embedded/md/tcllib/files/devdoc/tcl_community_communication.md Index: embedded/md/tcllib/files/devdoc/tcl_community_communication.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcl_community_communication.md @@ -0,0 +1,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 "") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
+ +# 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 ADDED embedded/md/tcllib/files/devdoc/tcllib_devguide.md Index: embedded/md/tcllib/files/devdoc/tcllib_devguide.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_devguide.md @@ -0,0 +1,1043 @@ + +[//000000001]: # (tcllib\_devguide \- ) +[//000000002]: # (Generated from file 'tcllib\_devguide\.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcllib\_devguide\(n\) 1 tcllib "") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
+ +# 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\. ADDED embedded/md/tcllib/files/devdoc/tcllib_installer.md Index: embedded/md/tcllib/files/devdoc/tcllib_installer.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_installer.md @@ -0,0 +1,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 "") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
+ +# 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\. ADDED embedded/md/tcllib/files/devdoc/tcllib_license.md Index: embedded/md/tcllib/files/devdoc/tcllib_license.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_license.md @@ -0,0 +1,69 @@ + +[//000000001]: # (tcllib\_license \- ) +[//000000002]: # (Generated from file 'tcllib\_license\.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcllib\_license\(n\) 1 tcllib "") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
+ +# 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\. ADDED embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md Index: embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md @@ -0,0 +1,124 @@ + +[//000000001]: # (tcllib\_releasemgr \- ) +[//000000002]: # (Generated from file 'tcllib\_releasemgr\.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcllib\_releasemgr\(n\) 1 tcllib "") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
+ +# 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\. ADDED embedded/md/tcllib/files/devdoc/tcllib_sources.md Index: embedded/md/tcllib/files/devdoc/tcllib_sources.md ================================================================== --- /dev/null +++ embedded/md/tcllib/files/devdoc/tcllib_sources.md @@ -0,0 +1,85 @@ + +[//000000001]: # (tcllib\_sources \- ) +[//000000002]: # (Generated from file 'tcllib\_sources\.man' by tcllib/doctools with format 'markdown') +[//000000003]: # (tcllib\_sources\(n\) 1 tcllib "") + +
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
+ +# 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\. Index: embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md +++ embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md @@ -94,11 +94,11 @@ [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] - [include ../doctools2base/include/feedback.inc] + [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 @@ -145,11 +145,11 @@ [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] + [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 Index: embedded/md/tcllib/toc.md ================================================================== --- embedded/md/tcllib/toc.md +++ embedded/md/tcllib/toc.md @@ -713,18 +713,30 @@ - [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 ADDED idoc/man/files/devdoc/tcl_community_communication.n Index: idoc/man/files/devdoc/tcl_community_communication.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcl_community_communication.n @@ -0,0 +1,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 Index: idoc/man/files/devdoc/tcllib_devguide.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_devguide.n @@ -0,0 +1,1307 @@ +'\" +'\" Generated from file 'tcllib_devguide\&.man' by tcllib/doctools with format 'nroff' +'\" +.TH "tcllib_devguide" n 1 tcllib "" +.\" The -*- nroff -*- definitions below are for supplemental macros used +.\" in Tcl/Tk manual entries. +.\" +.\" .AP type name in/out ?indent? +.\" Start paragraph describing an argument to a library procedure. +.\" type is type of argument (int, etc.), in/out is either "in", "out", +.\" or "in/out" to describe whether procedure reads or modifies arg, +.\" and indent is equivalent to second arg of .IP (shouldn't ever be +.\" needed; use .AS below instead) +.\" +.\" .AS ?type? ?name? +.\" Give maximum sizes of arguments for setting tab stops. Type and +.\" name are examples of largest possible arguments that will be passed +.\" to .AP later. If args are omitted, default tab stops are used. +.\" +.\" .BS +.\" Start box enclosure. From here until next .BE, everything will be +.\" enclosed in one large box. +.\" +.\" .BE +.\" End of box enclosure. +.\" +.\" .CS +.\" Begin code excerpt. +.\" +.\" .CE +.\" End code excerpt. +.\" +.\" .VS ?version? ?br? +.\" Begin vertical sidebar, for use in marking newly-changed parts +.\" of man pages. The first argument is ignored and used for recording +.\" the version when the .VS was added, so that the sidebars can be +.\" found and removed when they reach a certain age. If another argument +.\" is present, then a line break is forced before starting the sidebar. +.\" +.\" .VE +.\" End of vertical sidebar. +.\" +.\" .DS +.\" Begin an indented unfilled display. +.\" +.\" .DE +.\" End of indented unfilled display. +.\" +.\" .SO ?manpage? +.\" Start of list of standard options for a Tk widget. The manpage +.\" argument defines where to look up the standard options; if +.\" omitted, defaults to "options". The options follow on successive +.\" lines, in three columns separated by tabs. +.\" +.\" .SE +.\" End of list of standard options for a Tk widget. +.\" +.\" .OP cmdName dbName dbClass +.\" Start of description of a specific option. cmdName gives the +.\" option's name as specified in the class command, dbName gives +.\" the option's name in the option database, and dbClass gives +.\" the option's class in the option database. +.\" +.\" .UL arg1 arg2 +.\" Print arg1 underlined, then print arg2 normally. +.\" +.\" .QW arg1 ?arg2? +.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). +.\" +.\" .PQ arg1 ?arg2? +.\" Print an open parenthesis, arg1 in quotes, then arg2 normally +.\" (for trailing punctuation) and then a closing parenthesis. +.\" +.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +.\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +.\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +.\" # BS - start boxed text +.\" # ^y = starting y location +.\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +.\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +.\" # VS - start vertical sidebar +.\" # ^Y = starting y location +.\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +.\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +.\" # Special macro to handle page bottom: finish off current +.\" # box/sidebar if in box/sidebar mode, then invoked standard +.\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +.\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +.\" # DE - end display +.de DE +.fi +.RE +.sp +.. +.\" # SO - start of list of standard options +.de SO +'ie '\\$1'' .ds So \\fBoptions\\fR +'el .ds So \\fB\\$1\\fR +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 5.5c 11c +.ft B +.. +.\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\*(So manual entry for details on the standard options. +.. +.\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +.\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +.\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.\" # UL - underline word +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.\" # QW - apply quotation marks to word +.de QW +.ie '\\*(lq'"' ``\\$1''\\$2 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\$2 +.. +.\" # PQ - apply parens and quotation marks to word +.de PQ +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 +.\"" fix emacs highlighting +.el (\\*(lq\\$1\\*(rq\\$2)\\$3 +.. +.\" # QR - quoted range +.de QR +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 +.. +.\" # MT - "empty" string +.de MT +.QW "" +.. +.BS +.SH NAME +tcllib_devguide \- Tcllib - The Developer's Guide +.SH SYNOPSIS +\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR +.sp +\fBApplication\fR \fIname\fR +.sp +\fBExclude\fR \fIname\fR +.sp +.BE +.SH DESCRIPTION +Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a +package itself\&. It is a collection of (semi-independent) \fITcl\fR +packages that provide utility functions useful to a large collection +of Tcl programmers\&. +.PP +This document is a guide for developers working on Tcllib, +i\&.e\&. maintainers fixing bugs, extending the collection's +functionality, etc\&. +.PP +Please read +.IP [1] +\fITcllib - How To Get The Sources\fR and +.IP [2] +\fITcllib - The Installer's Guide\fR +.PP +first, if that was not done already\&. +.PP +Here we assume that the sources are already available in a +directory of your choice, and that you not only know how to build and +install them, but also have all the necessary requisites to actually +do so\&. The guide to the sources in particular also explains which +source code management system is used, where to find it, how to set it +up, etc\&. +.SH COMMITMENTS +.SS CONTRIBUTOR +As a contributor to Tcllib you are committing yourself to: +.IP [1] +keep the guidelines written down in +\fITcl Community - Kind Communication\fR in your mind\&. +The main point to take away from there is +\fIto be kind to each other\fR\&. +.IP [2] +Your contributions getting distributed under a BSD/MIT license\&. +For the details see \fITcllib - License\fR +.PP +Contributions are made by entering tickets into our tracker, providing +patches, bundles or branches of code for inclusion, or posting to the +Tcllib related mailing lists\&. +.SS MAINTAINER +When contributing one or more packages for full inclusion into Tcllib +you are committing yourself to +.IP [1] +Keep the guidelines written down in +\fITcl Community - Kind Communication\fR +(as any contributor) in your mind\&. The main point to take away +from there is \fIto be kind to each other\fR\&. +.IP [2] +Your packages getting distributed under a BSD/MIT license\&. For +the details see \fITcllib - License\fR +.IP [3] +Maintenance of the new packages for a period of two years under +the following rules, and responsibilities: +.RS +.IP [1] +A maintainer may step down after the mandatory period as +they see fit\&. +.IP [2] +A maintainer may step down before the end of the +mandatory period, under the condition that a replacement +maintainer is immediately available and has agreed to +serve the remainder of the period, plus their own +mandatory period (see below)\&. +.IP [3] +When stepping down without a replacement maintainer +taking over the relevant packages have to be flagged as +\fBunmaintained\fR\&. +.IP [4] +When a replacement mantainer is brought in for a package +it is (kept) marked as \fBmaintained\fR (again)\&. +.sp +A replacement maintainer is bound by the same rules as +the original maintainer, except that the mandatory +period of maintenance is shortened to one year\&. +.IP [5] +For any \fBunmaintained\fR package a contributor +interested in becoming its maintainer can become so by +flagging them as \fBmaintained\fR with their name and +contact information, committing themselves to the rules +of a replacement maintainer (see previous point)\&. +.IP [6] +For any already \fBmaintained\fR package a contributor +interested in becoming a co-maintainer can become so +with the agreement of the existing maintainer(s), +committing themselves to the rules of a replacement +maintainer (see two points previous)\&. +.RE +.sp +The responsibilities as a maintainer include: +.RS +.IP [1] +Watching Tcllib's ticket tracker for bugs, bug fixes, +and feature requests related to the new packages\&. +.IP [2] +Reviewing the aforementioned tickets, rejecting or +applying them +.IP [3] +Coordination and discussion with ticket submitter during +the development and/or application of bug fixes\&. +.RE +.IP [4] +Follow the \fBBranching and Workflow\fR of this guide\&. +.PP +.SH "BRANCHING AND WORKFLOW" +.SS "PACKAGE DEPENDENCIES" +Regarding packages and dependencies between them Tcllib occupies a +middle position between two extremes: +.IP [1] +On one side a strongly interdependent set of packages, usually +by a single author, for a single project\&. Looking at my +(Andreas Kupries) own work examples of such are +\fIMarpa\fR [https://core\&.tcl\&.tk/akupries/marpa/index], +\fICRIMP\fR [https://core\&.tcl\&.tk/akupries/crimp/index], +\fIKinetcl\fR [https://core\&.tcl\&.tk/akupries/kinetcl/index], etc\&. +.sp +For every change the author of the project handles all the +modifications cascading from any incompatibilities it +introduced to the system\&. +.IP [2] +On the other side, the world of semi-independent projects by +many different authors where authors know what packages their +own creations depend on, yet usually do not know who else +depends on them\&. +.sp +The best thing an author making an (incompatible) change to +their project can do is to for one announce such changes in +some way, and for two use versioning to distinguish the code +before and after the change\&. +.sp +The world is then responsible for adapting, be it by updating +their own projects to the new version, or by sticking to the +old\&. +.PP +As mentioned already, Tcllib lives in the middle of that\&. +.PP +While we as maintainers cannot be aware of all users of +Tcllib's packages, and thus have to rely on the mechanisms +touched on in point 2 above for that, the dependencies between +the packages contained in Tcllib are a different matter\&. +.PP +As we are collectively responsible for the usability of Tcllib +in toto to the outside world, it behooves us to be individually +mindful even of Tcllib packages we are not directly +maintaining, when they depend on packages under our +maintainership\&. +This may be as simple as coordinating with the maintainers of +the affected packages\&. +It may also require us to choose how to adapt affected packages +which do not have maintainers, i\&.e\&. modify them to use our +changed package properly, or modify them to properly depend on +the unchanged version of our package\&. +.PP +Note that the above is not only a chore but an opportunity as +well\&. +Additional insight can be had by forcing ourselves to look at +our package and the planned change(s) from an outside +perspective, to consider the ramifications of our actions on +others in general, and on dependent packages in particular\&. +.SS TRUNK +The management and use of branches is an important part of working +with a \fIDistributed Version Control System\fR (\fIDVCS\fR) like +\fIfossil\fR [https://www\&.fossil-scm\&.org/]\&. +.PP +For Tcllib the main branch of the collection is +\fItrunk\fR\&. In \fIgit\fR this branch would be called +\fImaster\fR, and this is exactly the case in the +\fIgithub mirror\fR [https://github\&.com/tcltk/tcllib/] of +Tcllib\&. +.PP +To properly support debugging \fIeach commit\fR on this +branch \fIhas to pass the entire testsuite\fR of the +collection\&. Using bisection to determine when an issue appeared +is an example of an action made easier by this constraint\&. +.PP +This is part of our collective responsibility for the usability +of Tcllib in toto to the outside world\&. +As \fIfossil\fR has no mechanism to enforce this condition +this is handled on the honor system for developers and maintainers\&. +.PP +To make the task easier Tcllib comes with a tool +("\fIsak\&.tcl\fR") providing a number of commands in +support\&. These commands are explained in the following sections +of this guide\&. +.PP +While it is possible and allowed to commit directly to trunk +remember the above constraint regarding the testsuite, and the +coming notes about other possible issues with a commit\&. +.SS BRANCHES +Given the constraints placed on the \fItrunk\fR branch of the +repository it is (strongly) recommended to perform any development +going beyond trivial changes on a non-trunk branch\&. +.PP +Outside of the trunk developers are allowed to commit +intermediate broken states of their work\&. +Only at the end of a development cycle, when the relevant +branch is considered ready for merging, will it be necessary to +perform full the set of validations ensuring that the merge to +come will create a good commit on trunk\&. +.PP +Note that while a review from a second developer is not a +required condition for merging a branch it is recommended to +seek out such an independent opinion as a means of +cross-checking the work\&. +.PP +It also recommended to give any new branch a name which aids in +determining additional details about it\&. Examples of good +things to stick into a branch name would be +.IP \(bu +Developer (nick)name +.IP \(bu +Ticket hash/reference +.IP \(bu +One or two keywords applicable to the work +.IP \(bu +\&.\&.\&. +.PP +.PP +Further, while most development branches are likely quite +short-lived, no prohibitions exist against making longer-lived +branches\&. +Creators should however be mindful that the longer such a +branch exists without merges the more divergent they will tend +to be, with an associated increase in the effort which will +have to be spent on either merging from and merging to trunk\&. +.SS "WORKING WITH BRANCHES" +In the hope of engendering good work practices now a few example +operations which will come up with branches, and their associated +fossil command (sequences)\&. +.TP +\fIAwareness\fR +When developing we have to keep ourselves aware of the context of our +work\&. On what branch are we ? What files have we changed ? What new +files are not yet known to the repository ? What has happened remotely +since we used our checkout ? +The answers to these questions become especially important when using +a long-lived checkout and coming back to it after some time away\&. +.sp +Commands to answer questions like the above are: +.RS +.TP +\fBfossil pull\fR +Get all changes done on the remote since the last pull or sync +from it\&. This has to be done first, before any of the commands +below\&. +.sp +Even if the commit in our checkout refers to the branch we want +right now control operations committed to the remote may have +changed that from underneath us\&. +.TP +\fBfossil info | grep tags\fR +.TP +\fBfossil branch list | grep '\\*'\fR +Two different ways of determining the branch our checkout is +on\&. +.TP +\fBfossil timeline\fR +What have we (and others) done recently ? +.sp +\fIAttention\fR, this information is very likely outdated, the +more the longer we did not use this checkout\&. +Run \fBfossil pull\fR first to get latest information from +the remote repository of the project\&. +.TP +\fBfossil timeline current\fR +Place the commit our checkout is based on at the top of the +timeline\&. +.TP +\fBfossil changes\fR +Lists the files we have changed compared to the commit the +checkout is based on\&. +.TP +\fBfossil extra\fR +Lists the files we have in the checkout the repository does not +know about\&. This may be leftover chaff from our work, or +something we have forgotten to \fBfossil add\fR to the +repository yet\&. +.RE +.TP +\fIClean checkouts\fR +Be aware of where you are (see first definition)\&. +.sp +For pretty much all the operation recipes below a clean +checkout is at least desired, often required\&. +To check that a checkout is clean invoke +.CS + + + fossil changes + fossil extra + +.CE +.IP +How to clean up when uncommitted changes of all sorts are found is +context-specific and outside of the scope of this guide\&. +.TP +\fIStarting a new branch\fR +Be aware of where you are (see first definition)\&. +.sp +Ensure that you have clean checkout (see second definition)\&. +It is \fIrequired\fR\&. +.sp +In most situations you want to be on branch \fItrunk\fR, and +you want to be on the latest commit for it\&. To get there use +.CS + + + fossil pull + fossil update trunk + +.CE +.IP +If some other branch is desired as the starting point for the coming +work replace \fItrunk\fR in the commands above with the name of that +branch\&. +.sp +With the base line established we now have two ways of creating +the new branch, with differing (dis)advantages\&. +The simpler way is to +.CS + + + fossil branch new NAME_OF_NEW_BRANCH + +.CE +.IP +and start developing\&. The advantage here is that you cannot forget to +create the branch\&. The disadvantages are that we have a branch commit +unchanged from where we branched from, and that we have to use +high-handed techniques like hiding or shunning to get rid of the +commit should we decide to abandon the work before the first actual +commit on the branch\&. +.sp +The other way of creating the branch is to start developing, +and then on the first commit use the option \fB--branch\fR to tell +\fBfossil\fR that we are starting a branch now\&. I\&.e\&. run +.CS + + + fossil commit --branch NAME_OF_NEW_BRANCH \&.\&.\&. + +.CE +.IP +where \fI\&.\&.\&.\fR are any other options used to supply the commit +message, files to commit, etc\&. +.sp +The (dis)advantages are now reversed\&. +.sp +We have no superflous commit, only what is actually +developed\&. The work is hidden until we commit to make our first +commit\&. +.sp +We may forget to use \fB--branch NAME_OF_NEW_BRANCH\fR and +then have to correct that oversight via the fossil web +interface (I am currently unaware of ways of doing such from +the command line, although some magic incantantion of +\fBfossil tag create\fR may work)\&. +.sp +It helps to keep awareness, like checking before any commit +that we are on the desired branch\&. +.TP +\fIMerging a branch into trunk\fR +Be aware of where you are (see first definition)\&. +.sp +Ensure that you have clean checkout (see second definition)\&. +In the full-blown sequence (zig-zag) it is \fIrequired\fR, due +to the merging from trunk\&. In the shorter sequence it is only +desired\&. That said, keeping the checkout clean before +any major operations is a good habit to have, in my opinion\&. +.sp +The full-blown sequencing with checks all the way is to +.RS +.IP [1] +Validate the checkout, i\&.e\&. last commit on your branch\&. Run the +full test suite and other validations, fix all the issues which +have cropped up\&. +.IP [2] +Merge the latest state of the \fItrunk\fR (see next definition)\&. +.IP [3] +Validate the checkout again\&. The incoming trunk changes may +have broken something now\&. Do any required fixes\&. +.IP [4] +Now merge to the trunk using +.CS + + + fossil update trunk + fossil merge --integrate YOUR_BRANCH + +.CE +.IP [5] +At this point the checkout should be in the same state as at +the end of point (3) above, because we resolved any issues with +the trunk already\&. Thus a simple +.CS + + + fossil commit \&.\&.\&. + +.CE +.IP +should be sufficient now to commit the merge back and close the +branch (due to the \fB--integrate\fR we used on the merge)\&. +.sp +The more paranoid may validate the checkout a third time before +commiting\&. +.RE +.sp +I call this a \fIzig-zag merge\fR because of how the arrows +look in the timeline, from trunk to feature branch for the +first merge, and then back for the final merge\&. +.sp +A less paranoid can do what I call a \fIsimple merge\fR, +which moves step (2) after step (4) and skips step (3) +entirely\&. The resulting shorter sequence is +.RS +.IP [1] +Validate +.IP [2] +Merge to trunk +.IP [3] +Validate again +.IP [4] +Commit to trunk +.RE +.IP +The last step after either zig-zag or plain merge is to +.CS + + + fossil sync + +.CE +.IP +This saves our work to the remote side, and further gives us any other +work done while we were doing our merge\&. It especially allows us to +check if we raced somebody else, resulting in a split trunk\&. +.sp +When that happens we should coordinate with the other developer +on who fixes the split, to ensure that we do not race each +other again\&. +.TP +\fIMerging from trunk\fR +Be aware of where you are (see first definition)\&. +.sp +Ensure that you have clean checkout (see second definition)\&. +It is \fIrequired\fR\&. +.sp +In most situations you want to import the latest commit of +branch \fItrunk\fR (or other origin)\&. To get it use +.CS + + + fossil pull + +.CE +.sp +With that done we can now import this commit into our current +branch with +.CS + + + fossil merge trunk + +.CE +.sp +Even if \fBfossil\fR does not report any conflicts it is a +good idea to check that the operation has not broken the new +and/or changed functionality we are working on\&. +.sp +With the establishment of a good merge we then save the state +with +.CS + + + fossil commit \&.\&.\&. + +.CE +.IP +before continuing development\&. +.PP +.SS "VERSION NUMBERS" +In Tcllib all changes to a package have to come with an increment of +its version number\&. What part is incremented (patchlevel, minor, major +version) depends on the kind of change made\&. With multiple changes in +a commit the highest "wins"\&. +.PP +When working in a development branch the version change can be +deferred until it is time to merge, and then has to cover all +the changes in the branch\&. +.PP +Below a list of the kinds of changes and their associated +version increments: +.TP +\fID - documentation\fR +No increment +.TP +\fIT - testsuite\fR +No increment +.TP +\fIB - bugfix\fR +Patchlevel +.TP +\fII - implementation tweak\fR +Patchlevel +.TP +\fIP - performance tweak\fR +Patchlevel +.TP +\fIE - backward-compatible extension\fR +Minor +.TP +\fIAPI - incompatible change\fR +Major +.PP +.PP +Note that a commit containing a version increment has to +mention the new version number in its commit message, as well +as the kind of change which caused it\&. +.PP +Note further that the version number of a package currently +exists in three places\&. An increment has to update all of them: +.IP [1] +The package implementation\&. +.IP [2] +The package index ("\fIpkgIndex\&.tcl\fR") +.IP [3] +The package documentation\&. +.PP +.PP +The "\fIsak\&.tcl\fR" command \fBvalidate version\fR helps +finding discrepancies between the first two\&. +All the other \fBvalidate\fR methods are also of interest to +any developer\&. Invoke it with +.CS + + sak\&.tcl help validate +.CE +to see their documentation\&. +.SH "STRUCTURAL OVERVIEW" +.SS "MAIN DIRECTORIES" +The main directories in the Tcllib toplevel directory and of interest +to a developer are: +.TP +"\fImodules\fR" +Each child directory represents one or more packages\&. +In the case of the latter the packages are usually related in some +way\&. Examples are "\fIbase64\fR", "\fImath\fR", and "\fIstruct\fR", with +loose (base64) to strong (math) relations between the packages in the +directory\&. +.TP +"\fIapps\fR" +This directory contains all the installable applications, with their +documentation\&. Note that this directory is currently \fInot\fR split +into sub-directories\&. +.TP +"\fIexamples\fR" +Each child directory "\fIfoo\fR" contains one or more example +application for the packages in "\fImodules/foo\fR"\&. These examples are +generally not polished enough to be considered for installation\&. +.PP +.SS "MORE DIRECTORIES" +.TP +"\fIconfig\fR" +This directory contains files supporting the Unix build system, +i\&.e\&. "\fIconfigure\fR" and "\fIMakefile\&.in\fR"\&. +.TP +"\fIdevdoc\fR" +This directories contains the doctools sources for the global +documentation, like this document and its sibling guides\&. +.TP +"\fIembedded\fR" +This directory contains the entire documentation formatted for +\fIHTML\fR and styled to properly mix into the web site generated by +fossil for the repository\&. +.sp +This is the documentation accessible from the Tcllib home +directory, represented in the repository as "\fIembedded/index\&.md\fR"\&. +.TP +"\fIidoc\fR" +This directory contains the entire documentation formatted for +\fInroff\fR and \fIHTML\fR, the latter without any styling\&. +This is the documentation which will be installed\&. +.TP +"\fIsupport\fR" +This directory contains the sources of internal packages and utilities +used in the implementation of the "\fIinstaller\&.tcl\fR" and +"\fIsak\&.tcl\fR" scripts/tools\&. +.PP +.SS "TOP FILES" +.TP +"\fIaclocal\&.m4\fR" +.TP +"\fIconfigure\fR" +.TP +"\fIconfigure\&.in\fR" +.TP +"\fIMakefile\&.in\fR" +These four files comprise the Unix build system layered on top of the +"\fIinstaller\&.tcl\fR" script\&. +.TP +"\fIinstaller\&.tcl\fR" +The Tcl-based installation script/tool\&. +.TP +"\fIproject\&.shed\fR" +Configuration file for \fISean Wood\fR's \fBPracTcl\fR +buildsystem\&. +.TP +"\fIsak\&.tcl\fR" +This is the main tool for developers and release managers, the +\fISwiss Army Knife\fR of management operations on the collection\&. +.TP +"\fIChangeLog\fR" +The log of changes to the global support, when the sources were held +in \fICVS\fR\&. Not relevant any longer with the switch to the +\fIfossil\fR SCM\&. +.TP +"\fIlicense\&.terms\fR" +The license in plain ASCII\&. See also \fITcllib - License\fR for the +nicely formatted form\&. The text is identical\&. +.TP +"\fIREADME\&.md\fR" +.TP +"\fI\&.github/CONTRIBUTING\&.md\fR" +.TP +"\fI\&.github/ISSUE_TEMPLATE\&.md\fR" +.TP +"\fI\&.github/PULL_REQUEST_TEMPLATE\&.md\fR" +These markdown-formatted documents are used and shown by the github +mirror of these sources, pointing people back to the official location +and issue trackers\&. +.TP +"\fIDESCRIPTION\&.txt\fR" +.TP +"\fISTATUS\fR" +.TP +"\fItcllib\&.spec\fR" +.TP +"\fItcllib\&.tap\fR" +.TP +"\fItcllib\&.yml\fR" +???? +.PP +.SS "FILE TYPES" +The most common file types, by file extension, are: +.TP +"\fI\&.tcl\fR" +Tcl code for a package, application, or example\&. +.TP +"\fI\&.man\fR" +Doctools-formatted documentation, usually for a package\&. +.TP +"\fI\&.test\fR" +Test suite for a package, or part of\&. +Based on \fBtcltest\fR\&. +.TP +"\fI\&.bench\fR" +Performance benchmarks for a package, or part of\&. +Based on "\fImodules/bench\fR"\&. +.TP +"\fI\&.pcx\fR" +Syntax rules for \fITclDevKit\fR's \fBtclchecker\fR\&. Using these +rules allows the checker to validate the use of commands of a Tcllib +package \fBfoo\fR without having to scan the "\fI\&.tcl\fR" files +implementing it\&. +.PP +.SH "TESTSUITE TOOLING" +Testsuites in Tcllib are based on Tcl's standard test package +\fBtcltest\fR, plus utilities found in the directory +"\fImodules/devtools\fR" +.PP +Tcllib developers invoke the suites through the +\fBtest run\fR method of the "\fIsak\&.tcl\fR" tool, with other methods +of \fBtest\fR providing management operations, for example setting a +list of standard Tcl shells to use\&. +.SS "INVOKE THE TESTSUITES OF A SPECIFIC MODULE" +Invoke either +.CS + + \&./sak\&.tcl test run foo +.CE +or +.CS + + \&./sak\&.tcl test run modules/foo +.CE +to invoke the testsuites found in a specific module "\fIfoo\fR"\&. +.SS "INVOKE THE TESTSUITES OF ALL MODULES" +Invoke the tool without a module name, i\&.e\&. +.CS + + \&./sak\&.tcl test run +.CE +to invoke the testsuites of all modules\&. +.SS "DETAILED TEST LOGS" +In all the previous examples the test runner will write a combination +of progress display and testsuite log to the standard output, showing +for each module only the tests that passed or failed and how many of +each in a summary at the end\&. +.PP +To get a detailed log, it is necessary to invoke the test +runner with additional options\&. +.PP +For one: +.CS + + + \&./sak\&.tcl test run --log LOG foo + +.CE +While this shows the same short log on the terminal as before, it also +writes a detailed log to the file "\fILOG\&.log\fR", and excerpts to +other files ("\fILOG\&.summary\fR", "\fILOG\&.failures\fR", etc\&.)\&. +.PP +For two: +.CS + + + \&./sak\&.tcl test run -v foo + +.CE +This writes the detailed log to the standard output, instead of the +short log\&. +.PP +Regardless of form, the detailed log contains a list of all test +cases executed, which failed, and how they failed (expected versus +actual results)\&. +.SS "SHELL SELECTION" +By default the test runner will use all the Tcl shells specified via +\fBtest add\fR to invoke the specified testsuites, if any\&. If no +such are specified it will fall back to the Tcl shell used to run the +tool itself\&. +.PP +Use option \fB--shell\fR to explicitly specify the Tcl shell +to use, like +.CS + + + \&./sak\&.tcl test run --shell /path/to/tclsh \&.\&.\&. + +.CE +.SS HELP +Invoke the tool as +.CS + + \&./sak\&.tcl help test +.CE +to see the detailed help for all methods of \fBtest\fR, and the +associated options\&. +.SH "DOCUMENTATION TOOLING" +The standard format used for documentation of packages and other +things in Tcllib is \fIdoctools\fR\&. +Its supporting packages are a part of Tcllib, see the directories +"\fImodules/doctools\fR" and "\fImodules/dtplite\fR"\&. The latter is +an application package, with the actual application +"\fIapps/dtplite\fR" a light wrapper around it\&. +.PP +Tcllib developers gain access to these through the \fBdoc\fR +method of the "\fIsak\&.tcl\fR" tool, another (internal) wrapper around +the "\fImodules/dtplite\fR" application package\&. +.SS "GENERATE DOCUMENTATION FOR A SPECIFIC MODULE" +Invoke either +.CS + + \&./sak\&.tcl doc html foo +.CE +or +.CS + + \&./sak\&.tcl doc html modules/foo +.CE +to generate HTML for the documentation found in the module "\fIfoo\fR"\&. +Instead of \fBhtml\fR any other supported format can be used here, +of course\&. +.PP +The generated formatted documentation will be placed into a +directory "\fIdoc\fR" in the current working directory\&. +.SS "GENERATE DOCUMENTATION FOR ALL MODULES" +Invoke the tool without a module name, i\&.e\&. +.CS + + \&./sak\&.tcl doc html +.CE +to generate HTML for the documentation found in all modules\&. +Instead of \fBhtml\fR any other supported format can be used here, +of course\&. +.PP +The generated formatted documentation will be placed into a +directory "\fIdoc\fR" in the current working directory\&. +.SS "AVAILABLE OUTPUT FORMATS, HELP" +Invoke the tool as +.CS + + \&./sak\&.tcl help doc +.CE +to see the entire set of supported output formats which can be +generated\&. +.SS "VALIDATION WITHOUT OUTPUT" +Note the special format \fBvalidate\fR\&. +.PP +Using this value as the name of the format to generate forces +the tool to simply check that the documentation is syntactically +correct, without generating actual output\&. +.PP +Invoke it as either +.CS + + \&./sak\&.tcl doc validate (modules/)foo +.CE +or +.CS + + \&./sak\&.tcl doc validate +.CE +to either check the packages of a specific module or check all of +them\&. +.SH "NOTES ON WRITING A TESTSUITE" +While previous sections talked about running the testsuites for a +module and the packages therein, this has no meaning if the module in +question has no testsuites at all\&. +.PP +This section gives a very basic overview on possible +methodologies for writing tests and testsuites\&. +.PP +First there are "drudgery" tests\&. Written to check absolutely +basic assumptions which should never fail\&. +.PP +For example for a command FOO taking two arguments, three tests +calling it with zero, one, and three arguments\&. The basic checks that +the command fails if it has not enough arguments, or too many\&. +.PP +After that come the tests checking things based on our +knowledge of the command, about its properties and assumptions\&. Some +examples based on the graph operations added during Google's Summer of +Code 2009 are: +.IP \(bu +The BellmanFord command in struct::graph::ops takes a +\fIstartnode\fR as argument, and this node should be a node of +the graph\&. This equals one test case checking the behavior when the +specified node is not a node of the graph\&. +.sp +This often gives rise to code in the implementation which +explicitly checks the assumption and throws an understandable error, +instead of letting the algorithm fail later in some weird +non-deterministic way\&. +.sp +It is not always possible to do such checks\&. The graph argument +for example is just a command in itself, and while we expect +it to exhibit a certain interface, i\&.e\&. a set of sub-commands +aka methods, we cannot check that it has them, except by +actually trying to use them\&. That is done by the algorithm +anyway, so an explicit check is just overhead we can get by +without\&. +.IP \(bu +IIRC one of the distinguishing characteristic of either +BellmanFord and/or Johnson is that they are able to handle +negative weights\&. Whereas Dijkstra requires positive weights\&. +.sp +This induces (at least) three testcases \&.\&.\&. Graph with all +positive weights, all negative, and a mix of positive and +negative weights\&. +Thinking further does the algorithm handle the weight +\fB0\fR as well ? Another test case, or several, if we mix +zero with positive and negative weights\&. +.IP \(bu +The two algorithms we are currently thinking about are about +distances between nodes, and distance can be 'Inf'inity, +i\&.e\&. nodes may not be connected\&. This means that good test +cases are +.RS +.IP [1] +Strongly connected graph +.IP [2] +Connected graph +.IP [3] +Disconnected graph\&. +.RE +.sp +At the extremes of strongly connected and disconnected +we have the fully connected graphs and graphs without edges, +only nodes, i\&.e\&. completely disconnected\&. +.IP \(bu +IIRC both of the algorithms take weighted arcs, and fill in a +default if arcs are left unweighted in the input graph\&. +.sp +This also induces three test cases: +.RS +.IP [1] +Graph will all arcs with explicit weights\&. +.IP [2] +Graph without weights at all\&. +.IP [3] +Graph with mixture of weighted and unweighted graphs\&. +.RE +.PP +.PP +What was described above via examples is called +\fIblack-box\fR testing\&. Test cases are designed and written based on +the developer's knowledge of the properties of the algorithm and its +inputs, without referencing a particular implementation\&. +.PP +Going further, a complement to \fIblack-box\fR testing is +\fIwhite-box\fR\&. For this we know the implementation of the +algorithm, we look at it and design our tests cases so that they force +the code through all possible paths in the implementation\&. Wherever a +decision is made we have a test case forcing a specific direction of +the decision, for all possible combinations and directions\&. It is easy +to get a combinatorial explosion in the number of needed test-cases\&. +.PP +In practice I often hope that the black-box tests I have made +are enough to cover all the paths, obviating the need for white-box +tests\&. +.PP +The above should be enough to make it clear that writing tests +for an algorithm takes at least as much time as coding the algorithm, +and often more time\&. Much more time\&. +See for example also \fIhttp://sqlite\&.org/testing\&.html\fR, a writeup +on how the Sqlite database engine is tested\&. Another article of +interest might be \fIhttps://www\&.researchgate\&.net/publication/298896236\fR\&. +While geared to a particular numerical algorithm it still shows that +even a simple-looking algorithm can lead to an incredible number of +test cases\&. +.PP +An interesting connection is to documentation\&. In one +direction, the properties checked with black-box testing are exactly +the properties which should be documented in the algorithm's man +page\&. And conversely, the documentation of the properties of an +algorithm makes a good reference to base the black-box tests on\&. +.PP +In practice test cases and documentation often get written +together, cross-influencing each other\&. And the actual writing of test +cases is a mix of black and white box, possibly influencing the +implementation while writing the tests\&. Like writing a test for a +condition like \fIstartnode not in input graph\fR serving as +reminder to put a check for this condition into the code\&. +.SH "INSTALLATION TOOLING" +A last thing to consider when adding a new package to the collection +is installation\&. +.PP +How to \fIuse\fR the "\fIinstaller\&.tcl\fR" script is documented +in \fITcllib - The Installer's Guide\fR\&. +.PP +Here we document how to extend said installer so that it may +install new package(s) and/or application(s)\&. +.PP +In most cases only a single file has to be modified, the +"\fIsupport/installation/modules\&.tcl\fR" holding one command per module +and application to install\&. +.PP +The relevant commands are: +.TP +\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR +Install the packages of module \fIname\fR, found in +"\fImodules/\fIname\fR\fR"\&. +.sp +The \fIcode-action\fR is responsible for installing the +packages and their index\&. The system currently provides +.RS +.TP +\fB_tcl\fR +Copy all "\fI\&.tcl\fR" files found in +"\fImodules/\fIname\fR\fR" into the installation\&. +.TP +\fB_tcr\fR +As \fB_tcl\fR, copy the "\fI\&.tcl\fR" files found in +the subdirectories of "\fImodules/\fIname\fR\fR" as well\&. +.TP +\fB_tci\fR +As \fB_tcl\fR, and copy the "\fItclIndex\&.tcl\fR" file +as well\&. +.TP +\fB_msg\fR +As \fB_tcl\fR, and copy the subdirectory "\fImsgs\fR" +as well\&. +.TP +\fB_doc\fR +As \fB_tcl\fR, and copy the subdirectory +"\fImpformats\fR" as well\&. +.TP +\fB_tex\fR +As \fB_tcl\fR, and copy "\fI\&.tex\fR" files as well\&. +.RE +.sp +The \fIdoc-action\fR is responsible for installing the package +documentation\&. The system currently provides +.RS +.TP +\fB_null\fR +No documentation available, do nothing\&. +.TP +\fB_man\fR +Process the "\fI\&.man\fR" files found in +"\fImodules/\fIname\fR\fR" and install the results (nroff and/or HTML) +in the proper location, as given to the installer\&. +.sp +This is actually a fallback, normally the installer uses the +pre-made formatted documentation found under "\fIidoc\fR"\&. +.RE +.sp +The \fIexample-action\fR is responsible for installing the +examples\&. The system currently provides +.RS +.TP +\fB_null\fR +No examples available, do nothing\&. +.TP +\fB_exa\fR +Copy the the directory "\fIexamples/\fIname\fR\fR" +recursively to the install location for examples\&. +.RE +.TP +\fBApplication\fR \fIname\fR +Install the application with \fIname\fR, found in "\fIapps\fR"\&. +.TP +\fBExclude\fR \fIname\fR +This command signals to the installer which of the listed modules to +\fInot\fR install\&. I\&.e\&. they name the deprecated modules of Tcllib\&. +.PP +.PP +If, and only if the above actions are not suitable for the new +module then a second file has to be modified, +"\fIsupport/installation/actions\&.tcl\fR"\&. +.PP +This file contains the implementations of the available +actions, and is the place where any custom action needed to handle the +special circumstances of module has to be added\&. ADDED idoc/man/files/devdoc/tcllib_installer.n Index: idoc/man/files/devdoc/tcllib_installer.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_installer.n @@ -0,0 +1,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 Index: idoc/man/files/devdoc/tcllib_license.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_license.n @@ -0,0 +1,321 @@ +'\" +'\" Generated from file 'tcllib_license\&.man' by tcllib/doctools with format 'nroff' +'\" +.TH "tcllib_license" n 1 tcllib "" +.\" The -*- nroff -*- definitions below are for supplemental macros used +.\" in Tcl/Tk manual entries. +.\" +.\" .AP type name in/out ?indent? +.\" Start paragraph describing an argument to a library procedure. +.\" type is type of argument (int, etc.), in/out is either "in", "out", +.\" or "in/out" to describe whether procedure reads or modifies arg, +.\" and indent is equivalent to second arg of .IP (shouldn't ever be +.\" needed; use .AS below instead) +.\" +.\" .AS ?type? ?name? +.\" Give maximum sizes of arguments for setting tab stops. Type and +.\" name are examples of largest possible arguments that will be passed +.\" to .AP later. If args are omitted, default tab stops are used. +.\" +.\" .BS +.\" Start box enclosure. From here until next .BE, everything will be +.\" enclosed in one large box. +.\" +.\" .BE +.\" End of box enclosure. +.\" +.\" .CS +.\" Begin code excerpt. +.\" +.\" .CE +.\" End code excerpt. +.\" +.\" .VS ?version? ?br? +.\" Begin vertical sidebar, for use in marking newly-changed parts +.\" of man pages. The first argument is ignored and used for recording +.\" the version when the .VS was added, so that the sidebars can be +.\" found and removed when they reach a certain age. If another argument +.\" is present, then a line break is forced before starting the sidebar. +.\" +.\" .VE +.\" End of vertical sidebar. +.\" +.\" .DS +.\" Begin an indented unfilled display. +.\" +.\" .DE +.\" End of indented unfilled display. +.\" +.\" .SO ?manpage? +.\" Start of list of standard options for a Tk widget. The manpage +.\" argument defines where to look up the standard options; if +.\" omitted, defaults to "options". The options follow on successive +.\" lines, in three columns separated by tabs. +.\" +.\" .SE +.\" End of list of standard options for a Tk widget. +.\" +.\" .OP cmdName dbName dbClass +.\" Start of description of a specific option. cmdName gives the +.\" option's name as specified in the class command, dbName gives +.\" the option's name in the option database, and dbClass gives +.\" the option's class in the option database. +.\" +.\" .UL arg1 arg2 +.\" Print arg1 underlined, then print arg2 normally. +.\" +.\" .QW arg1 ?arg2? +.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). +.\" +.\" .PQ arg1 ?arg2? +.\" Print an open parenthesis, arg1 in quotes, then arg2 normally +.\" (for trailing punctuation) and then a closing parenthesis. +.\" +.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +.\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +.\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +.\" # BS - start boxed text +.\" # ^y = starting y location +.\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +.\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +.\" # VS - start vertical sidebar +.\" # ^Y = starting y location +.\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +.\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +.\" # Special macro to handle page bottom: finish off current +.\" # box/sidebar if in box/sidebar mode, then invoked standard +.\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +.\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +.\" # DE - end display +.de DE +.fi +.RE +.sp +.. +.\" # SO - start of list of standard options +.de SO +'ie '\\$1'' .ds So \\fBoptions\\fR +'el .ds So \\fB\\$1\\fR +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 5.5c 11c +.ft B +.. +.\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\*(So manual entry for details on the standard options. +.. +.\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +.\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +.\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.\" # UL - underline word +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.\" # QW - apply quotation marks to word +.de QW +.ie '\\*(lq'"' ``\\$1''\\$2 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\$2 +.. +.\" # PQ - apply parens and quotation marks to word +.de PQ +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 +.\"" fix emacs highlighting +.el (\\*(lq\\$1\\*(rq\\$2)\\$3 +.. +.\" # QR - quoted range +.de QR +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 +.. +.\" # MT - "empty" string +.de MT +.QW "" +.. +.BS +.SH NAME +tcllib_license \- Tcllib - License +.SH DESCRIPTION +Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a +package itself\&. It is a collection of (semi-independent) \fITcl\fR +packages that provide utility functions useful to a large collection +of Tcl programmers\&. +.PP +The collection is under the BSD license\&. +.SH LICENSE +.PP +This software is copyrighted by Ajuba Solutions and other parties\&. +The following terms apply to all files associated with the software +unless explicitly disclaimed in individual files\&. +.PP +The authors hereby grant permission to use, copy, modify, distribute, +and license this software and its documentation for any purpose, +provided that existing copyright notices are retained in all copies +and that this notice is included verbatim in any distributions\&. No +written agreement, license, or royalty fee is required for any of the +authorized uses\&. Modifications to this software may be copyrighted by +their authors and need not follow the licensing terms described here, +provided that the new terms are clearly indicated on the first page of +each file where they apply\&. +.PP +IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY +FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY +DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE\&. +.PP +THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, +INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND +NON-INFRINGEMENT\&. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND +THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE +MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS\&. +.PP +GOVERNMENT USE: If you are acquiring this software on behalf of the +U\&.S\&. government, the Government shall have only "Restricted Rights" in +the software and related documentation as defined in the Federal +Acquisition Regulations (FARs) in Clause 52\&.227\&.19 (c) (2)\&. If you +are acquiring the software on behalf of the Department of Defense, the +software shall be classified as "Commercial Computer Software" and the +Government shall have only "Restricted Rights" as defined in Clause +252\&.227-7013 (c) (1) of DFARs\&. Notwithstanding the foregoing, the +authors grant the U\&.S\&. Government and others acting in its behalf +permission to use and distribute the software in accordance with the +terms specified in this license\&. ADDED idoc/man/files/devdoc/tcllib_releasemgr.n Index: idoc/man/files/devdoc/tcllib_releasemgr.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_releasemgr.n @@ -0,0 +1,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 Index: idoc/man/files/devdoc/tcllib_sources.n ================================================================== --- /dev/null +++ idoc/man/files/devdoc/tcllib_sources.n @@ -0,0 +1,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\&. Index: idoc/man/files/modules/doctools/doctools_lang_intro.n ================================================================== --- idoc/man/files/modules/doctools/doctools_lang_intro.n +++ idoc/man/files/modules/doctools/doctools_lang_intro.n @@ -332,11 +332,11 @@ [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] -[include \&.\&./doctools2base/include/feedback\&.inc] +[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 @@ -391,11 +391,11 @@ [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] +[include \&.\&./common-text/feedback\&.inc] [manpage_end] .CE has the same meaning as the example before\&. .PP Index: idoc/man/toc.n ================================================================== --- idoc/man/toc.n +++ idoc/man/toc.n @@ -1339,22 +1339,40 @@ \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 ADDED idoc/www/tcllib/files/devdoc/tcl_community_communication.html Index: idoc/www/tcllib/files/devdoc/tcl_community_communication.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcl_community_communication.html @@ -0,0 +1,251 @@ + +tcl_community_communication - + + + + +
[ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

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

+
+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_devguide.html Index: idoc/www/tcllib/files/devdoc/tcllib_devguide.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_devguide.html @@ -0,0 +1,982 @@ + +tcllib_devguide - + + + + +
[ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

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.

+

Please read

+
    +

  1. Tcllib - How To Get The Sources and

    2. +

  2. Tcllib - The Installer's Guide

    3. +
+

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.

    2. +

  2. Your contributions getting distributed under a BSD/MIT license. + For the details see Tcllib - License

    3. +
+

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.

    2. +

  2. Your packages getting distributed under a BSD/MIT license. For + the details see Tcllib - License

    3. +

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

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

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

      4. +

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

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

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

      7. +
    +

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

    2. Reviewing the aforementioned tickets, rejecting or + applying them

      3. +

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

      4. +
    +
    4. +

  4. Follow the Branching and Workflow of this guide.

    5. +
+
+
+

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

  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.

    3. +
+

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.

+

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.

    2. +

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

    3. +

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

    4. +

  4. Now merge to the trunk using

    +
    +    fossil update trunk
+    fossil merge --integrate YOUR_BRANCH
+
    +
    5. +

  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.

    6. +
+

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

  2. Merge to trunk

    3. +

  3. Validate again

    4. +

  4. Commit to trunk

    5. +
+

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

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

    3. +

  3. The package documentation.

    4. +
+

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.

+
"license.terms"
+

The license in plain ASCII. See also Tcllib - License 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 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. +

    2. Connected graph

      3. +

    3. Disconnected graph.

      4. +
    +

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

    2. Graph without weights at all.

      3. +

    3. Graph with mixture of weighted and unweighted graphs.

      4. +
    +
    • +
+

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.

+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_installer.html Index: idoc/www/tcllib/files/devdoc/tcllib_installer.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_installer.html @@ -0,0 +1,392 @@ + +tcllib_install_guide - + + + + +
[ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

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.

    2. +
+

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

  2. Optionally, the critcl package (C embedding) for Tcl. + For details see CriTcl.

    3. +
+

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

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

+
+
+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_license.html Index: idoc/www/tcllib/files/devdoc/tcllib_license.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_license.html @@ -0,0 +1,162 @@ + +tcllib_license - + + + + +
[ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcllib_license(n) 1 tcllib ""

+

Name

+

tcllib_license - Tcllib - License

+
+ +

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.

+
+

License

+

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

+

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

+

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

+

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

+

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

+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html Index: idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html @@ -0,0 +1,199 @@ + +tcllib_releasemgr - + + + + +
[ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

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.

+
+

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.

    +

    An existing event should be used as template.

    2. +

  2. Update a number of web locations:

    +
      +

    1. Home page

      2. +

    2. Downloads

      3. +

    3. Past Releases

      4. +

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

      5. +

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

      6. +

    6. http://wiki.tcl-lang.org/page/Tcllib

      7. +
    +

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

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

    4. +
+
+
+
ADDED idoc/www/tcllib/files/devdoc/tcllib_sources.html Index: idoc/www/tcllib/files/devdoc/tcllib_sources.html ================================================================== --- /dev/null +++ idoc/www/tcllib/files/devdoc/tcllib_sources.html @@ -0,0 +1,169 @@ + +tcllib_sources - + + + + +
[ + Tcllib Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

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

  2. Tcllib - The Developer's Guide.

    3. +
+

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:

+
    +

  1. Log into this site, as "anonymous", using the semi-random password in the captcha.

    2. +

  2. Go to the "Timeline".

    3. +

  3. Choose the revision you wish to have.

    4. +

  4. Follow its link to its detailed information page.

    5. +

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

    6. +
+
+

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.

+
+
Index: idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html ================================================================== --- idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html +++ idoc/www/tcllib/files/modules/doctools/doctools_lang_intro.html @@ -178,11 +178,11 @@ [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[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 @@ -229,11 +229,11 @@ 

     [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]
+[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, Index: idoc/www/tcllib/toc.html ================================================================== --- idoc/www/tcllib/toc.html +++ idoc/www/tcllib/toc.html @@ -1439,25 +1439,49 @@ 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_license +Tcllib - License + + +tcllib_releasemgr +Tcllib - The Release Manager's Guide + + +tcllib_sources +Tcllib - How To Get The Sources + tclrep/machineparameters Compute double precision machine parameters. Index: installer.tcl ================================================================== --- installer.tcl +++ installer.tcl @@ -280,11 +280,11 @@ # 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 + # 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] Index: license.terms ================================================================== --- license.terms +++ license.terms @@ -1,38 +1,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 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. +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. +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 +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. +terms specified in this license. Index: modules/aes/aes.man ================================================================== --- modules/aes/aes.man +++ modules/aes/aes.man @@ -162,7 +162,7 @@ [section AUTHORS] Thorsten Schloermann, Pat Thoyts [vset CATEGORY aes] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/amazon-s3/S3.man ================================================================== --- modules/amazon-s3/S3.man +++ modules/amazon-s3/S3.man @@ -1444,7 +1444,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/amazon-s3/xsxp.man ================================================================== --- modules/amazon-s3/xsxp.man +++ modules/amazon-s3/xsxp.man @@ -131,7 +131,7 @@ version of [arg pxml]. [list_end] [vset CATEGORY amazon-s3] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/asn/asn.man ================================================================== --- modules/asn/asn.man +++ modules/asn/asn.man @@ -458,7 +458,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/base32/base32.man ================================================================== --- modules/base32/base32.man +++ modules/base32/base32.man @@ -69,7 +69,7 @@ 7 H 16 Q 25 Z 8 I 17 R 26 2 }] [vset CATEGORY base32] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/base32/base32core.man ================================================================== --- modules/base32/base32core.man +++ modules/base32/base32core.man @@ -60,7 +60,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/base32/base32hex.man ================================================================== --- modules/base32/base32hex.man +++ modules/base32/base32hex.man @@ -72,7 +72,7 @@ 7 7 16 G 25 P 8 8 17 H 26 Q }] [vset CATEGORY base32] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/base64/ascii85.man ================================================================== --- modules/base64/ascii85.man +++ modules/base64/ascii85.man @@ -69,7 +69,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/base64/base64.man ================================================================== --- modules/base64/base64.man +++ modules/base64/base64.man @@ -64,7 +64,7 @@ Q+KCiEjigoHigoBO4oKET+KCgg== % set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]] }] [vset CATEGORY base64] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/base64/uuencode.man ================================================================== --- modules/base64/uuencode.man +++ modules/base64/uuencode.man @@ -91,7 +91,7 @@ % uuencode::uudecode $d {hello.txt 644 {Hello World}} }] [vset CATEGORY base64] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/base64/yencode.man ================================================================== --- modules/base64/yencode.man +++ modules/base64/yencode.man @@ -90,7 +90,7 @@ [list_begin enum] [enum] [uri http://www.yenc.org/yenc-draft.1.3.txt] [list_end] [vset CATEGORY base64] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bee/bee.man ================================================================== --- modules/bee/bee.man +++ modules/bee/bee.man @@ -337,7 +337,7 @@ a digit. [section EXAMPLES] [vset CATEGORY bee] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bench/bench.man ================================================================== --- modules/bench/bench.man +++ modules/bench/bench.man @@ -290,7 +290,7 @@ [list_end] [list_end] [vset CATEGORY bench] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bench/bench_intro.man ================================================================== --- modules/bench/bench_intro.man +++ modules/bench/bench_intro.man @@ -85,7 +85,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bench/bench_lang_intro.man ================================================================== --- modules/bench/bench_lang_intro.man +++ modules/bench/bench_lang_intro.man @@ -147,7 +147,7 @@ available commands and their syntax. [para] [vset CATEGORY bench] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bench/bench_lang_spec.man ================================================================== --- modules/bench/bench_lang_spec.man +++ modules/bench/bench_lang_spec.man @@ -126,7 +126,7 @@ [list_end] [list_end] [vset CATEGORY bench] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bench/bench_read.man ================================================================== --- modules/bench/bench_read.man +++ modules/bench/bench_read.man @@ -59,7 +59,7 @@ and automatically detects which format is used by the input file. [list_end] [vset CATEGORY bench] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bench/bench_wcsv.man ================================================================== --- modules/bench/bench_wcsv.man +++ modules/bench/bench_wcsv.man @@ -48,7 +48,7 @@ results in raw form, or for human consumption, respectively. [list_end] [vset CATEGORY bench] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bench/bench_wtext.man ================================================================== --- modules/bench/bench_wtext.man +++ modules/bench/bench_wtext.man @@ -49,7 +49,7 @@ results in raw form, or as importable CSV data, respectively. [list_end] [vset CATEGORY bench] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/bibtex/bibtex.man ================================================================== --- modules/bibtex/bibtex.man +++ modules/bibtex/bibtex.man @@ -174,7 +174,7 @@ [cmd ::bibtex::parse]. [list_end] [vset CATEGORY bibtex] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/blowfish/blowfish.man ================================================================== --- modules/blowfish/blowfish.man +++ modules/blowfish/blowfish.man @@ -158,7 +158,7 @@ [section AUTHORS] Frank Pilhofer, Pat Thoyts [vset CATEGORY blowfish] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/cache/async.man ================================================================== --- modules/cache/async.man +++ modules/cache/async.man @@ -138,7 +138,7 @@ [method get]-requests to reload the information from the provider. [list_end] [vset CATEGORY cache] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/clock/iso8601.man ================================================================== --- modules/clock/iso8601.man +++ modules/clock/iso8601.man @@ -41,7 +41,7 @@ of the builtin command [cmd {clock scan}]. [list_end] [vset CATEGORY clock::iso8601] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/clock/rfc2822.man ================================================================== --- modules/clock/rfc2822.man +++ modules/clock/rfc2822.man @@ -21,7 +21,7 @@ if the command is unable to parse the date. [list_end] [vset CATEGORY clock::rfc2822] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/cmdline/cmdline.man ================================================================== --- modules/cmdline/cmdline.man +++ modules/cmdline/cmdline.man @@ -198,7 +198,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/comm/comm.man ================================================================== --- modules/comm/comm.man +++ modules/comm/comm.man @@ -1226,7 +1226,7 @@ Andreas Kupries 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/comm/comm_wire.man ================================================================== --- modules/comm/comm_wire.man +++ modules/comm/comm_wire.man @@ -278,7 +278,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] ADDED modules/common-text/feedback.inc Index: modules/common-text/feedback.inc ================================================================== --- /dev/null +++ modules/common-text/feedback.inc @@ -0,0 +1,23 @@ +[section {Bugs, Ideas, Feedback}] +[vset TRACKER http://core.tcl.tk/tcllib/reportlist] +[vset LABEL {Tcllib Trackers}] + +This document, and the package it describes, will undoubtedly contain +bugs and other problems. + +Please report such in the category [emph [vset CATEGORY]] of the +[uri [vset TRACKER] [vset LABEL]]. + +Please also report any ideas for enhancements you may have for either +package and/or documentation. + +[para] +When proposing code changes, please provide [emph {unified diffs}], +i.e the output of [const {diff -u}]. + +[para] +Note further that [emph attachments] are strongly preferred over +inlined patches. Attachments can be made by going to the [const Edit] +form of the ticket immediately after its creation, and then using the +left-most button in the secondary navigation bar. + Index: modules/control/control.man ================================================================== --- modules/control/control.man +++ modules/control/control.man @@ -159,7 +159,7 @@ % catch b 0 }] [vset CATEGORY control] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/coroutine/coro_auto.man ================================================================== --- modules/coroutine/coro_auto.man +++ modules/coroutine/coro_auto.man @@ -40,7 +40,7 @@ [def [cmd update]] [def [cmd vwait]] [list_end] [vset CATEGORY coroutine] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/coroutine/tcllib_coroutine.man ================================================================== --- modules/coroutine/tcllib_coroutine.man +++ modules/coroutine/tcllib_coroutine.man @@ -111,7 +111,7 @@ the named namespace variable [arg varname]. [list_end] [vset CATEGORY coroutine] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/counter/counter.man ================================================================== --- modules/counter/counter.man +++ modules/counter/counter.man @@ -244,7 +244,7 @@ the same meaning as described for [cmd ::counter::init]. [list_end] [vset CATEGORY counter] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/crc/cksum.man ================================================================== --- modules/crc/cksum.man +++ modules/crc/cksum.man @@ -125,7 +125,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY crc] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/crc/crc16.man ================================================================== --- modules/crc/crc16.man +++ modules/crc/crc16.man @@ -143,7 +143,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY crc] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/crc/crc32.man ================================================================== --- modules/crc/crc32.man +++ modules/crc/crc32.man @@ -146,7 +146,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY crc] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/crc/sum.man ================================================================== --- modules/crc/sum.man +++ modules/crc/sum.man @@ -102,7 +102,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY crc] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/cron/cron.man ================================================================== --- modules/cron/cron.man +++ modules/cron/cron.man @@ -180,7 +180,7 @@ [list_end] [para] [vset CATEGORY odie] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/csv/csv.man ================================================================== --- modules/csv/csv.man +++ modules/csv/csv.man @@ -241,7 +241,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/debug/debug.man ================================================================== --- modules/debug/debug.man +++ modules/debug/debug.man @@ -241,7 +241,7 @@ [comment {= = == === ===== ======== ============= =====================}] [list_end] [vset CATEGORY debug] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/debug/debug_caller.man ================================================================== --- modules/debug/debug_caller.man +++ modules/debug/debug_caller.man @@ -38,7 +38,7 @@ dictionaries, etc. to prevent them from overwhelming the narrative. [list_end] [vset CATEGORY debug] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/debug/debug_heartbeat.man ================================================================== --- modules/debug/debug_heartbeat.man +++ modules/debug/debug_heartbeat.man @@ -37,7 +37,7 @@ nominal [arg delta]. [list_end] [vset CATEGORY debug] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/debug/debug_timestamp.man ================================================================== --- modules/debug/debug_timestamp.man +++ modules/debug/debug_timestamp.man @@ -28,7 +28,7 @@ when only specific places need such detail. [list_end] [vset CATEGORY debug] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/defer/defer.man ================================================================== --- modules/defer/defer.man +++ modules/defer/defer.man @@ -96,7 +96,7 @@ [section AUTHORS] Roy Keene [vset CATEGORY defer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/des/des.man ================================================================== --- modules/des/des.man +++ modules/des/des.man @@ -200,7 +200,7 @@ Jochen C Loewer, Mac Cody, Pat Thoyts [vset CATEGORY des] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/des/tcldes.man ================================================================== --- modules/des/tcldes.man +++ modules/des/tcldes.man @@ -20,7 +20,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/des/tcldesjr.man ================================================================== --- modules/des/tcldesjr.man +++ modules/des/tcldesjr.man @@ -20,7 +20,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/dicttool/dicttool.man ================================================================== --- modules/dicttool/dicttool.man +++ modules/dicttool/dicttool.man @@ -72,7 +72,7 @@ }] [list_end] [vset CATEGORY dict] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/dns/tcllib_dns.man ================================================================== --- modules/dns/tcllib_dns.man +++ modules/dns/tcllib_dns.man @@ -285,7 +285,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY dns] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/dns/tcllib_ip.man ================================================================== --- modules/dns/tcllib_ip.man +++ modules/dns/tcllib_ip.man @@ -445,7 +445,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY dns] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/changelog.man ================================================================== --- modules/doctools/changelog.man +++ modules/doctools/changelog.man @@ -81,7 +81,7 @@ new structure is returned as the result of the command. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/cvs.man ================================================================== --- modules/doctools/cvs.man +++ modules/doctools/cvs.man @@ -95,7 +95,7 @@ constructed text is returned as the result of the command. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/docidx.man ================================================================== --- modules/doctools/docidx.man +++ modules/doctools/docidx.man @@ -404,7 +404,7 @@ Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/docidx_intro.man ================================================================== --- modules/doctools/docidx_intro.man +++ modules/doctools/docidx_intro.man @@ -100,7 +100,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/docidx_lang_cmdref.man ================================================================== --- modules/doctools/docidx_lang_cmdref.man +++ modules/doctools/docidx_lang_cmdref.man @@ -110,7 +110,7 @@ named document variable [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/docidx_lang_faq.man ================================================================== --- modules/doctools/docidx_lang_faq.man +++ modules/doctools/docidx_lang_faq.man @@ -22,7 +22,7 @@ [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/docidx_lang_intro.man ================================================================== --- modules/doctools/docidx_lang_intro.man +++ modules/doctools/docidx_lang_intro.man @@ -208,7 +208,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/docidx_lang_syntax.man ================================================================== --- modules/doctools/docidx_lang_syntax.man +++ modules/doctools/docidx_lang_syntax.man @@ -114,7 +114,7 @@ [list_end] [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/docidx_plugin_apiref.man ================================================================== --- modules/doctools/docidx_plugin_apiref.man +++ modules/doctools/docidx_plugin_apiref.man @@ -415,7 +415,7 @@ to simply return its argument without change. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctoc.man ================================================================== --- modules/doctools/doctoc.man +++ modules/doctools/doctoc.man @@ -404,7 +404,7 @@ Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_intro.man ================================================================== --- modules/doctools/doctoc_intro.man +++ modules/doctools/doctoc_intro.man @@ -99,7 +99,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_lang_cmdref.man ================================================================== --- modules/doctools/doctoc_lang_cmdref.man +++ modules/doctools/doctoc_lang_cmdref.man @@ -121,7 +121,7 @@ named document variable [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_lang_faq.man ================================================================== --- modules/doctools/doctoc_lang_faq.man +++ modules/doctools/doctoc_lang_faq.man @@ -22,7 +22,7 @@ [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_lang_intro.man ================================================================== --- modules/doctools/doctoc_lang_intro.man +++ modules/doctools/doctoc_lang_intro.man @@ -291,7 +291,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_lang_syntax.man ================================================================== --- modules/doctools/doctoc_lang_syntax.man +++ modules/doctools/doctoc_lang_syntax.man @@ -99,7 +99,7 @@ contents DIVISION_END }] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_plugin_apiref.man ================================================================== --- modules/doctools/doctoc_plugin_apiref.man +++ modules/doctools/doctoc_plugin_apiref.man @@ -415,7 +415,7 @@ to simply return its argument without change. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctools.man ================================================================== --- modules/doctools/doctools.man +++ modules/doctools/doctools.man @@ -569,7 +569,7 @@ Wippler's [syscmd wikit] application. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctools_intro.man ================================================================== --- modules/doctools/doctools_intro.man +++ modules/doctools/doctools_intro.man @@ -97,7 +97,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctools_lang_cmdref.man ================================================================== --- modules/doctools/doctools_lang_cmdref.man +++ modules/doctools/doctools_lang_cmdref.man @@ -464,7 +464,7 @@ it. Main use is the highlighting of widget names in free-form text. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctools_lang_faq.man ================================================================== --- modules/doctools/doctools_lang_faq.man +++ modules/doctools/doctools_lang_faq.man @@ -22,7 +22,7 @@ [include include/placeholder.inc] [include include/examples.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctools_lang_intro.man ================================================================== --- modules/doctools/doctools_lang_intro.man +++ modules/doctools/doctools_lang_intro.man @@ -71,11 +71,11 @@ [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[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 @@ -134,11 +134,11 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] }] has the same meaning as the example before. @@ -611,7 +611,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctools_lang_syntax.man ================================================================== --- modules/doctools/doctools_lang_syntax.man +++ modules/doctools/doctools_lang_syntax.man @@ -136,7 +136,7 @@ optd_list = [ ] { OPT_DEF paras } tkoptd_list = [ ] { TKOPTION_DEF paras } }] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/doctools_plugin_apiref.man ================================================================== --- modules/doctools/doctools_plugin_apiref.man +++ modules/doctools/doctools_plugin_apiref.man @@ -472,7 +472,7 @@ to simply return its argument without change. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools/mpexpand.man ================================================================== --- modules/doctools/mpexpand.man +++ modules/doctools/mpexpand.man @@ -101,7 +101,7 @@ [para] Possible future formats are plain text, pdf and postscript. [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2base/html_cssdefaults.man ================================================================== --- modules/doctools2base/html_cssdefaults.man +++ modules/doctools2base/html_cssdefaults.man @@ -34,7 +34,7 @@ markup generated by the various HTML export plugins. [list_end] [vset CATEGORY doctools] -[include include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] DELETED modules/doctools2base/include/feedback.inc Index: modules/doctools2base/include/feedback.inc ================================================================== --- modules/doctools2base/include/feedback.inc +++ /dev/null @@ -1,23 +0,0 @@ -[section {Bugs, Ideas, Feedback}] -[vset TRACKER http://core.tcl.tk/tcllib/reportlist] -[vset LABEL {Tcllib Trackers}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph [vset CATEGORY]] of the -[uri [vset TRACKER] [vset LABEL]]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[para] -When proposing code changes, please provide [emph {unified diffs}], -i.e the output of [const {diff -u}]. - -[para] -Note further that [emph attachments] are strongly preferred over -inlined patches. Attachments can be made by going to the [const Edit] -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar. - Index: modules/doctools2base/nroff_manmacros.man ================================================================== --- modules/doctools2base/nroff_manmacros.man +++ modules/doctools2base/nroff_manmacros.man @@ -34,7 +34,7 @@ generated by the various NROFF export plugins. [list_end] [vset CATEGORY doctools] -[include include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2base/tcl_parse.man ================================================================== --- modules/doctools2base/tcl_parse.man +++ modules/doctools2base/tcl_parse.man @@ -178,7 +178,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2base/tcllib_msgcat.man ================================================================== --- modules/doctools2base/tcllib_msgcat.man +++ modules/doctools2base/tcllib_msgcat.man @@ -61,7 +61,7 @@ result of [cmd msgcat::mcpreferences]. [list_end] [vset CATEGORY doctools] -[include include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/idx_container.man ================================================================== --- modules/doctools2idx/idx_container.man +++ modules/doctools2idx/idx_container.man @@ -290,7 +290,7 @@ [list_end] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/idx_export.man ================================================================== --- modules/doctools2idx/idx_export.man +++ modules/doctools2idx/idx_export.man @@ -303,7 +303,7 @@ [list_end] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/idx_import.man ================================================================== --- modules/doctools2idx/idx_import.man +++ modules/doctools2idx/idx_import.man @@ -389,7 +389,7 @@ [list_end] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/idx_introduction.man ================================================================== --- modules/doctools2idx/idx_introduction.man +++ modules/doctools2idx/idx_introduction.man @@ -140,7 +140,7 @@ [section {Package Overview}] [include include/dependencies.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/idx_parse.man ================================================================== --- modules/doctools2idx/idx_parse.man +++ modules/doctools2idx/idx_parse.man @@ -169,7 +169,7 @@ [include include/format/docidx.inc] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/idx_structure.man ================================================================== --- modules/doctools2idx/idx_structure.man +++ modules/doctools2idx/idx_structure.man @@ -123,7 +123,7 @@ [list_end] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/include/export/plugin.inc ================================================================== --- modules/doctools2idx/include/export/plugin.inc +++ modules/doctools2idx/include/export/plugin.inc @@ -49,7 +49,7 @@ [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] -[include ../../../doctools2base/include/feedback.inc] +[include ../../../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/include/import/plugin.inc ================================================================== --- modules/doctools2idx/include/import/plugin.inc +++ modules/doctools2idx/include/import/plugin.inc @@ -50,7 +50,7 @@ [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] -[include ../../../doctools2base/include/feedback.inc] +[include ../../../common-text/feedback.inc] [manpage_end] Index: modules/doctools2idx/include/msgcat.inc ================================================================== --- modules/doctools2idx/include/msgcat.inc +++ modules/doctools2idx/include/msgcat.inc @@ -40,7 +40,7 @@ This package has no exported API. [vset CATEGORY doctools] -[include ../../doctools2base/include/feedback.inc] +[include ../../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/include/export/plugin.inc ================================================================== --- modules/doctools2toc/include/export/plugin.inc +++ modules/doctools2toc/include/export/plugin.inc @@ -49,7 +49,7 @@ [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] -[include ../../../doctools2base/include/feedback.inc] +[include ../../../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/include/import/plugin.inc ================================================================== --- modules/doctools2toc/include/import/plugin.inc +++ modules/doctools2toc/include/import/plugin.inc @@ -50,7 +50,7 @@ [include config/[vset CONFIG].inc] [include ../serialization.inc] [vset CATEGORY doctools] -[include ../../../doctools2base/include/feedback.inc] +[include ../../../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/include/msgcat.inc ================================================================== --- modules/doctools2toc/include/msgcat.inc +++ modules/doctools2toc/include/msgcat.inc @@ -40,7 +40,7 @@ This package has no exported API. [vset CATEGORY doctools] -[include ../../doctools2base/include/feedback.inc] +[include ../../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/toc_container.man ================================================================== --- modules/doctools2toc/toc_container.man +++ modules/doctools2toc/toc_container.man @@ -364,7 +364,7 @@ [list_end] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/toc_export.man ================================================================== --- modules/doctools2toc/toc_export.man +++ modules/doctools2toc/toc_export.man @@ -301,7 +301,7 @@ [list_end] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/toc_import.man ================================================================== --- modules/doctools2toc/toc_import.man +++ modules/doctools2toc/toc_import.man @@ -389,7 +389,7 @@ [list_end] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/toc_introduction.man ================================================================== --- modules/doctools2toc/toc_introduction.man +++ modules/doctools2toc/toc_introduction.man @@ -137,7 +137,7 @@ [section {Package Overview}] [include include/dependencies.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/toc_parse.man ================================================================== --- modules/doctools2toc/toc_parse.man +++ modules/doctools2toc/toc_parse.man @@ -169,7 +169,7 @@ [include include/format/doctoc.inc] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/doctools2toc/toc_structure.man ================================================================== --- modules/doctools2toc/toc_structure.man +++ modules/doctools2toc/toc_structure.man @@ -145,7 +145,7 @@ [list_end] [include include/serialization.inc] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/dtplite/pkg_dtplite.man ================================================================== --- modules/dtplite/pkg_dtplite.man +++ modules/dtplite/pkg_dtplite.man @@ -443,7 +443,7 @@ of doctoc and docidx markup. [list_end] [vset CATEGORY doctools] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/exif/exif.man ================================================================== --- modules/exif/exif.man +++ modules/exif/exif.man @@ -74,7 +74,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fileutil/fileutil.man ================================================================== --- modules/fileutil/fileutil.man +++ modules/fileutil/fileutil.man @@ -516,7 +516,7 @@ [include include/cross-index-trav.inc] [list_end] [vset CATEGORY fileutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fileutil/multi.man ================================================================== --- modules/fileutil/multi.man +++ modules/fileutil/multi.man @@ -50,7 +50,7 @@ command it executed. [list_end] [vset CATEGORY fileutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fileutil/multiop.man ================================================================== --- modules/fileutil/multiop.man +++ modules/fileutil/multiop.man @@ -396,7 +396,7 @@ the index \\ as pkgIndex.tcl }] [vset CATEGORY fileutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fileutil/paths.man ================================================================== --- modules/fileutil/paths.man +++ modules/fileutil/paths.man @@ -70,7 +70,7 @@ The result of the command is the empty string. [list_end] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fileutil/traverse.man ================================================================== --- modules/fileutil/traverse.man +++ modules/fileutil/traverse.man @@ -159,7 +159,7 @@ [include include/cross-index-trav.inc] [list_end] [vset CATEGORY fileutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ftp/ftp.man ================================================================== --- modules/ftp/ftp.man +++ modules/ftp/ftp.man @@ -434,7 +434,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ftp/ftp_geturl.man ================================================================== --- modules/ftp/ftp_geturl.man +++ modules/ftp/ftp_geturl.man @@ -51,7 +51,7 @@ [list_end] [list_end] [vset CATEGORY ftp] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ftpd/ftpd.man ================================================================== --- modules/ftpd/ftpd.man +++ modules/ftpd/ftpd.man @@ -273,7 +273,7 @@ channel which was active when the callback was invoked. [list_end] [vset CATEGORY ftpd] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fumagic/cfront.man ================================================================== --- modules/fumagic/cfront.man +++ modules/fumagic/cfront.man @@ -65,7 +65,7 @@ causing the creation of procedure [const ::fileutil::magic::/FOO::run]. [list_end] [vset CATEGORY {fileutil :: magic}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fumagic/cgen.man ================================================================== --- modules/fumagic/cgen.man +++ modules/fumagic/cgen.man @@ -57,7 +57,7 @@ perform its duties. [list_end] [vset CATEGORY {fileutil :: magic}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fumagic/filetypes.man ================================================================== --- modules/fumagic/filetypes.man +++ modules/fumagic/filetypes.man @@ -56,7 +56,7 @@ generate this recognizer. [list_end] [vset CATEGORY {fileutil :: magic}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/fumagic/rtcore.man ================================================================== --- modules/fumagic/rtcore.man +++ modules/fumagic/rtcore.man @@ -245,7 +245,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/gpx/gpx.man ================================================================== --- modules/gpx/gpx.man +++ modules/gpx/gpx.man @@ -152,7 +152,7 @@ [section AUTHOR] Keith Vetter [vset CATEGORY gpx] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_fa/dacceptor.man ================================================================== --- modules/grammar_fa/dacceptor.man +++ modules/grammar_fa/dacceptor.man @@ -96,7 +96,7 @@ [para] [section EXAMPLES] [vset CATEGORY grammar_fa] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_fa/dexec.man ================================================================== --- modules/grammar_fa/dexec.man +++ modules/grammar_fa/dexec.man @@ -177,7 +177,7 @@ [para] [section EXAMPLES] [vset CATEGORY grammar_fa] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_fa/fa.man ================================================================== --- modules/grammar_fa/fa.man +++ modules/grammar_fa/fa.man @@ -646,7 +646,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_fa/faop.man ================================================================== --- modules/grammar_fa/faop.man +++ modules/grammar_fa/faop.man @@ -474,7 +474,7 @@ [para] [section EXAMPLES] [vset CATEGORY grammar_fa] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_me/gasm.man ================================================================== --- modules/grammar_me/gasm.man +++ modules/grammar_me/gasm.man @@ -433,7 +433,7 @@ The command returns the empty string as its result. [list_end] [vset CATEGORY grammar_me] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_me/me_ast.man ================================================================== --- modules/grammar_me/me_ast.man +++ modules/grammar_me/me_ast.man @@ -128,7 +128,7 @@ column index. Lines are counted from 1, columns are counted from 0. [list_end] [vset CATEGORY grammar_me] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_me/me_cpu.man ================================================================== --- modules/grammar_me/me_cpu.man +++ modules/grammar_me/me_cpu.man @@ -283,7 +283,7 @@ This method deletes the object and releases all resurces it claimed. [list_end] [vset CATEGORY grammar_me] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_me/me_cpucore.man ================================================================== --- modules/grammar_me/me_cpucore.man +++ modules/grammar_me/me_cpucore.man @@ -368,7 +368,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_me/me_intro.man ================================================================== --- modules/grammar_me/me_intro.man +++ modules/grammar_me/me_intro.man @@ -88,7 +88,7 @@ [list_end] [para] [vset CATEGORY grammar_me] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_me/me_tcl.man ================================================================== --- modules/grammar_me/me_tcl.man +++ modules/grammar_me/me_tcl.man @@ -337,7 +337,7 @@ [list_end] [para] [vset CATEGORY grammar_me] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_me/me_util.man ================================================================== --- modules/grammar_me/me_util.man +++ modules/grammar_me/me_util.man @@ -77,7 +77,7 @@ starting point. [list_end] [vset CATEGORY grammar_me] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_me/me_vm.man ================================================================== --- modules/grammar_me/me_vm.man +++ modules/grammar_me/me_vm.man @@ -657,7 +657,7 @@ discards it. [list_end] [vset CATEGORY grammar_me] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_peg/peg.man ================================================================== --- modules/grammar_peg/peg.man +++ modules/grammar_peg/peg.man @@ -715,7 +715,7 @@ {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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/grammar_peg/peg_interp.man ================================================================== --- modules/grammar_peg/peg_interp.man +++ modules/grammar_peg/peg_interp.man @@ -116,7 +116,7 @@ [list_end] [para] [vset CATEGORY grammar_peg] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/hook/hook.man ================================================================== --- modules/hook/hook.man +++ modules/hook/hook.man @@ -369,7 +369,7 @@ [section Credits] Hook has been designed and implemented by William H. Duquette. [vset CATEGORY hook] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/html/html.man ================================================================== --- modules/html/html.man +++ modules/html/html.man @@ -470,7 +470,7 @@ [list_end] [list_end] [vset CATEGORY html] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/htmlparse/htmlparse.man ================================================================== --- modules/htmlparse/htmlparse.man +++ modules/htmlparse/htmlparse.man @@ -260,7 +260,7 @@ form elements. Its only argument is the name of the tree to cut down. [list_end] [vset CATEGORY htmlparse] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/http/autoproxy.man ================================================================== --- modules/http/autoproxy.man +++ modules/http/autoproxy.man @@ -210,7 +210,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY {http :: autoproxy}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/httpd/httpd.man ================================================================== --- modules/httpd/httpd.man +++ modules/httpd/httpd.man @@ -59,7 +59,7 @@ [section AUTHORS] Sean Woods [vset CATEGORY network] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ident/ident.man ================================================================== --- modules/ident/ident.man +++ modules/ident/ident.man @@ -48,7 +48,7 @@ [list_end] [list_end] [vset CATEGORY ident] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/imap4/imap4.man ================================================================== --- modules/imap4/imap4.man +++ modules/imap4/imap4.man @@ -360,9 +360,9 @@ [para] OpenSSL, [uri http://www.openssl.org/] [vset CATEGORY imap4] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] Only a small part of rfc3501 implemented. [manpage_end] Index: modules/inifile/ini.man ================================================================== --- modules/inifile/ini.man +++ modules/inifile/ini.man @@ -94,7 +94,7 @@ is [const \;]. [list_end] [vset CATEGORY inifile] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/interp/deleg_method.man ================================================================== --- modules/interp/deleg_method.man +++ modules/interp/deleg_method.man @@ -43,7 +43,7 @@ method will not wait for a result and return immediately. [list_end] [vset CATEGORY interp] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/interp/deleg_proc.man ================================================================== --- modules/interp/deleg_proc.man +++ modules/interp/deleg_proc.man @@ -41,7 +41,7 @@ procedure will not wait for a result and return immediately. [list_end] [vset CATEGORY interp] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/interp/tcllib_interp.man ================================================================== --- modules/interp/tcllib_interp.man +++ modules/interp/tcllib_interp.man @@ -68,7 +68,7 @@ The result of the command is the empty string. [list_end] [vset CATEGORY interp] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/irc/irc.man ================================================================== --- modules/irc/irc.man +++ modules/irc/irc.man @@ -234,7 +234,7 @@ Returns the message portion of the command (the part after the :). [list_end] [vset CATEGORY irc] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/javascript/javascript.man ================================================================== --- modules/javascript/javascript.man +++ modules/javascript/javascript.man @@ -90,7 +90,7 @@ of child html checkbox object to create. [list_end] [vset CATEGORY javascript] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/jpeg/jpeg.man ================================================================== --- modules/jpeg/jpeg.man +++ modules/jpeg/jpeg.man @@ -190,7 +190,7 @@ cant write exif data gps exif data not parsed makernote data not yet implemented [vset CATEGORY jpeg] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/json/json.man ================================================================== --- modules/json/json.man +++ modules/json/json.man @@ -108,7 +108,7 @@ [section RELATED] To write json, instead of parsing it, see package [package json::write]. [vset CATEGORY json] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/json/json_write.man ================================================================== --- modules/json/json_write.man +++ modules/json/json_write.man @@ -86,7 +86,7 @@ [section RELATED] To parse json, instead of writing it, see package [package json]. [vset CATEGORY json] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/lambda/lambda.man ================================================================== --- modules/lambda/lambda.man +++ modules/lambda/lambda.man @@ -83,7 +83,7 @@ [section AUTHORS] Andreas Kupries [vset CATEGORY lambda] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/lazyset/lazyset.man ================================================================== --- modules/lazyset/lazyset.man +++ modules/lazyset/lazyset.man @@ -74,7 +74,7 @@ [section AUTHORS] Roy Keene [vset CATEGORY utility] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ldap/ldap.man ================================================================== --- modules/ldap/ldap.man +++ modules/ldap/ldap.man @@ -543,7 +543,7 @@ ldap::unbind $handle ldap::disconnect $handle }] [vset CATEGORY ldap] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ldap/ldapx.man ================================================================== --- modules/ldap/ldapx.man +++ modules/ldap/ldapx.man @@ -768,7 +768,7 @@ }] [section References] [vset CATEGORY ldap] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/log/log.man ================================================================== --- modules/log/log.man +++ modules/log/log.man @@ -283,7 +283,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/log/logger.man ================================================================== --- modules/log/logger.man +++ modules/log/logger.man @@ -391,7 +391,7 @@ ${log}::logproc debug log_local_var } ] [vset CATEGORY logger] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/log/loggerAppender.man ================================================================== --- modules/log/loggerAppender.man +++ modules/log/loggerAppender.man @@ -59,7 +59,7 @@ applicable options. [list_end] [vset CATEGORY logger] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/log/loggerUtils.man ================================================================== --- modules/log/loggerUtils.man +++ modules/log/loggerUtils.man @@ -143,7 +143,7 @@ ${log}::error "this is an error" }] [list_end] [vset CATEGORY logger] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/markdown/markdown.man ================================================================== --- modules/markdown/markdown.man +++ modules/markdown/markdown.man @@ -47,7 +47,7 @@ Reset the language counters. [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/bigfloat.man ================================================================== --- modules/math/bigfloat.man +++ modules/math/bigfloat.man @@ -426,7 +426,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/bignum.man ================================================================== --- modules/math/bignum.man +++ modules/math/bignum.man @@ -222,7 +222,7 @@ [list_end] [para] [vset CATEGORY {math :: bignum}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/calculus.man ================================================================== --- modules/math/calculus.man +++ modules/math/calculus.man @@ -445,7 +445,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/combinatorics.man ================================================================== --- modules/math/combinatorics.man +++ modules/math/combinatorics.man @@ -102,7 +102,7 @@ least 1. [list_end] [vset CATEGORY math] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/constants.man ================================================================== --- modules/math/constants.man +++ modules/math/constants.man @@ -130,7 +130,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/decimal.man ================================================================== --- modules/math/decimal.man +++ modules/math/decimal.man @@ -193,7 +193,7 @@ [list_end] [para] [vset CATEGORY decimal] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/fourier.man ================================================================== --- modules/math/fourier.man +++ modules/math/fourier.man @@ -128,7 +128,7 @@ [para] [list_end] [vset CATEGORY {math :: fourier}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/fuzzy.man ================================================================== --- modules/math/fuzzy.man +++ modules/math/fuzzy.man @@ -127,7 +127,7 @@ D. Knuth, Art of Computer Programming, Vol. 1, Problem 1.2.4-5. [vset CATEGORY {math :: fuzzy}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/interpolate.man ================================================================== --- modules/math/interpolate.man +++ modules/math/interpolate.man @@ -293,7 +293,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/linalg.man ================================================================== --- modules/math/linalg.man +++ modules/math/linalg.man @@ -962,7 +962,7 @@ scaleTk .scale ... } }] [vset CATEGORY {math :: linearalgebra}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/machineparameters.man ================================================================== --- modules/math/machineparameters.man +++ modules/math/machineparameters.man @@ -185,7 +185,7 @@ Print machine parameters on standard output. [list_end] [vset CATEGORY math] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/math.man ================================================================== --- modules/math/math.man +++ modules/math/math.man @@ -120,7 +120,7 @@ Return the sum of one or more numeric values. [list_end] [vset CATEGORY math] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/math_geometry.man ================================================================== --- modules/math/math_geometry.man +++ modules/math/math_geometry.man @@ -609,7 +609,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/numtheory.dtx ================================================================== --- modules/math/numtheory.dtx +++ modules/math/numtheory.dtx @@ -1763,11 +1763,11 @@ % \begin{tcl} %<*man> [list_end] [vset CATEGORY {math :: numtheory}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] % % \end{tcl} % % \begin{tcl} Index: modules/math/numtheory.man ================================================================== --- modules/math/numtheory.man +++ modules/math/numtheory.man @@ -199,7 +199,7 @@ [list_end] [list_end] [vset CATEGORY {math :: numtheory}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/optimize.man ================================================================== --- modules/math/optimize.man +++ modules/math/optimize.man @@ -319,7 +319,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/pca.man ================================================================== --- modules/math/pca.man +++ modules/math/pca.man @@ -130,7 +130,7 @@ TODO: NIST example [vset CATEGORY PCA] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/polynomials.man ================================================================== --- modules/math/polynomials.man +++ modules/math/polynomials.man @@ -213,7 +213,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/qcomplex.man ================================================================== --- modules/math/qcomplex.man +++ modules/math/qcomplex.man @@ -296,7 +296,7 @@ [list_end] [list_end] [vset CATEGORY {math :: complexnumbers}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/rational_funcs.man ================================================================== --- modules/math/rational_funcs.man +++ modules/math/rational_funcs.man @@ -180,7 +180,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/roman.man ================================================================== --- modules/math/roman.man +++ modules/math/roman.man @@ -45,7 +45,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/romberg.man ================================================================== --- modules/math/romberg.man +++ modules/math/romberg.man @@ -334,7 +334,7 @@ integral is 3.97746 +/- 2.3557e-010 }] [vset CATEGORY {math :: calculus}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/special.man ================================================================== --- modules/math/special.man +++ modules/math/special.man @@ -466,7 +466,7 @@ [para] Abramowitz and Stegun: [emph "Handbook of Mathematical Functions"] (Dover, ISBN 486-61272-4) [vset CATEGORY {math :: special}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/statistics.man ================================================================== --- modules/math/statistics.man +++ modules/math/statistics.man @@ -1633,7 +1633,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/symdiff.man ================================================================== --- modules/math/symdiff.man +++ modules/math/symdiff.man @@ -66,7 +66,7 @@ y {$c * $x + $d * $y}} ==> {{$a} {$b}} {{$c} {$d}} }] [vset CATEGORY {math :: calculus}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/math/trig.man ================================================================== --- modules/math/trig.man +++ modules/math/trig.man @@ -189,7 +189,7 @@ [list_end] [list_end] [vset CATEGORY {math :: trig}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/md4/md4.man ================================================================== --- modules/md4/md4.man +++ modules/md4/md4.man @@ -162,7 +162,7 @@ ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY md4] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/md5/md5.man ================================================================== --- modules/md5/md5.man +++ modules/md5/md5.man @@ -168,7 +168,7 @@ ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY md5] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/md5crypt/md5crypt.man ================================================================== --- modules/md5crypt/md5crypt.man +++ modules/md5crypt/md5crypt.man @@ -79,7 +79,7 @@ % md5crypt::md5crypt password [md5crypt::salt] $1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb. }] [vset CATEGORY md5crypt] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/mime/mime.man ================================================================== --- modules/mime/mime.man +++ modules/mime/mime.man @@ -400,7 +400,7 @@ See [uri {/tktview?name=447037} {Ticket 447037}] for additional information. [list_end] [vset CATEGORY mime] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/mime/smtp.man ================================================================== --- modules/mime/smtp.man +++ modules/mime/smtp.man @@ -201,10 +201,10 @@ ([uri http://www.rfc-editor.org/rfc/rfc2554.txt]) [list_end] [vset CATEGORY smtp] -[include ../doctools2base/include/feedback.inc] +[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] Index: modules/multiplexer/multiplexer.man ================================================================== --- modules/multiplexer/multiplexer.man +++ modules/multiplexer/multiplexer.man @@ -124,7 +124,7 @@ [list_end] [list_end] [vset CATEGORY multiplexer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/namespacex/namespacex.man ================================================================== --- modules/namespacex/namespacex.man +++ modules/namespacex/namespacex.man @@ -168,7 +168,7 @@ Returns the corresponding list of relative names of child namespaces. [list_end] [vset CATEGORY namespacex] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ncgi/ncgi.man ================================================================== --- modules/ncgi/ncgi.man +++ modules/ncgi/ncgi.man @@ -307,7 +307,7 @@ }] [para] [vset CATEGORY ncgi] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nettool/nettool.man ================================================================== --- modules/nettool/nettool.man +++ modules/nettool/nettool.man @@ -137,7 +137,7 @@ The path is not created, only computed, by this command. [list_end] [para] [vset CATEGORY odie] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nmea/nmea.man ================================================================== --- modules/nmea/nmea.man +++ modules/nmea/nmea.man @@ -96,7 +96,7 @@ }] [list_end] [vset CATEGORY nmea] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nns/nns_auto.man ================================================================== --- modules/nns/nns_auto.man +++ modules/nns/nns_auto.man @@ -113,7 +113,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nns/nns_client.man ================================================================== --- modules/nns/nns_client.man +++ modules/nns/nns_client.man @@ -332,7 +332,7 @@ [def 0.1] Initial implementation of the client. [list_end] [vset CATEGORY nameserv] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nns/nns_common.man ================================================================== --- modules/nns/nns_common.man +++ modules/nns/nns_common.man @@ -41,7 +41,7 @@ will try to connect to. [list_end] [vset CATEGORY nameserv] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nns/nns_intro.man ================================================================== --- modules/nns/nns_intro.man +++ modules/nns/nns_intro.man @@ -122,7 +122,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nns/nns_protocol.man ================================================================== --- modules/nns/nns_protocol.man +++ modules/nns/nns_protocol.man @@ -176,7 +176,7 @@ names in the response were added or removed from the service. [list_end] [vset CATEGORY nameserv] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nns/nns_server.man ================================================================== --- modules/nns/nns_server.man +++ modules/nns/nns_server.man @@ -139,7 +139,7 @@ [def 0.1] Initial implementation of the server. [list_end] [vset CATEGORY nameserv] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/nntp/nntp.man ================================================================== --- modules/nntp/nntp.man +++ modules/nntp/nntp.man @@ -332,7 +332,7 @@ Test message body" }] [vset CATEGORY nntp] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ntp/ntp_time.man ================================================================== --- modules/ntp/ntp_time.man +++ modules/ntp/ntp_time.man @@ -125,7 +125,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY ntp] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/oauth/oauth.man ================================================================== --- modules/oauth/oauth.man +++ modules/oauth/oauth.man @@ -185,7 +185,7 @@ [list_end] [para] [vset CATEGORY oauth] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/oometa/oometa.man ================================================================== --- modules/oometa/oometa.man +++ modules/oometa/oometa.man @@ -145,8 +145,8 @@ between the class metadata, the local [emph meta] variable, and THEN performing the search. [list_end] [vset CATEGORY tcloo] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ooutil/ooutil.man ================================================================== --- modules/ooutil/ooutil.man +++ modules/ooutil/ooutil.man @@ -159,7 +159,7 @@ [section AUTHORS] Donal Fellows, Andreas Kupries [vset CATEGORY oo::util] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/otp/otp.man ================================================================== --- modules/otp/otp.man +++ modules/otp/otp.man @@ -89,7 +89,7 @@ ([uri http://www.itl.nist.gov/fipspubs/fip180-1.htm]) [list_end] [vset CATEGORY otp] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/page/page_intro.man ================================================================== --- modules/page/page_intro.man +++ modules/page/page_intro.man @@ -29,7 +29,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/page/page_pluginmgr.man ================================================================== --- modules/page/page_pluginmgr.man +++ modules/page/page_pluginmgr.man @@ -794,7 +794,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/page/page_util_flow.man ================================================================== --- modules/page/page_util_flow.man +++ modules/page/page_util_flow.man @@ -90,7 +90,7 @@ above. [list_end] [vset CATEGORY page] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/page/page_util_norm_lemon.man ================================================================== --- modules/page/page_util_norm_lemon.man +++ modules/page/page_util_norm_lemon.man @@ -45,7 +45,7 @@ The exact operations performed are left undocumented for the moment. [list_end] [vset CATEGORY page] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/page/page_util_norm_peg.man ================================================================== --- modules/page/page_util_norm_peg.man +++ modules/page/page_util_norm_peg.man @@ -99,7 +99,7 @@ [list_end] [list_end] [vset CATEGORY page] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/page/page_util_peg.man ================================================================== --- modules/page/page_util_peg.man +++ modules/page/page_util_peg.man @@ -102,7 +102,7 @@ [arg pe]. [list_end] [vset CATEGORY page] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/page/page_util_quote.man ================================================================== --- modules/page/page_util_quote.man +++ modules/page/page_util_quote.man @@ -56,7 +56,7 @@ this command. [list_end] [vset CATEGORY page] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/pki/pki.man ================================================================== --- modules/pki/pki.man +++ modules/pki/pki.man @@ -296,7 +296,7 @@ [section AUTHORS] Roy Keene [vset CATEGORY rsa] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/pluginmgr/pluginmgr.man ================================================================== --- modules/pluginmgr/pluginmgr.man +++ modules/pluginmgr/pluginmgr.man @@ -421,7 +421,7 @@ loaded. [list_end] [vset CATEGORY pluginmgr] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/png/png.man ================================================================== --- modules/png/png.man +++ modules/png/png.man @@ -149,7 +149,7 @@ to [arg file]. [list_end] [vset CATEGORY png] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/pop3/pop3.man ================================================================== --- modules/pop3/pop3.man +++ modules/pop3/pop3.man @@ -268,7 +268,7 @@ ... }] [vset CATEGORY pop3] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/pop3d/pop3d.man ================================================================== --- modules/pop3d/pop3d.man +++ modules/pop3d/pop3d.man @@ -267,7 +267,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/pop3d/pop3d_dbox.man ================================================================== --- modules/pop3d/pop3d_dbox.man +++ modules/pop3d/pop3d_dbox.man @@ -158,7 +158,7 @@ that there are zero messages in the mailbox. [list_end] [vset CATEGORY pop3d] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/pop3d/pop3d_udb.man ================================================================== --- modules/pop3d/pop3d_udb.man +++ modules/pop3d/pop3d_udb.man @@ -106,7 +106,7 @@ [arg dbName] [method save] without an argument. [list_end] [vset CATEGORY pop3d] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/practcl/practcl.man ================================================================== --- modules/practcl/practcl.man +++ modules/practcl/practcl.man @@ -57,7 +57,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/processman/processman.man ================================================================== --- modules/processman/processman.man +++ modules/processman/processman.man @@ -68,7 +68,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/profiler/profiler.man ================================================================== --- modules/profiler/profiler.man +++ modules/profiler/profiler.man @@ -115,7 +115,7 @@ that function. [list_end] [vset CATEGORY profiler] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/pt/include/feedback.inc ================================================================== --- modules/pt/include/feedback.inc +++ modules/pt/include/feedback.inc @@ -1,3 +1,3 @@ [comment {--- Standard trailer for all manpages in this module --}] [vset CATEGORY pt] -[include ../../doctools2base/include/feedback.inc] +[include ../../common-text/feedback.inc] Index: modules/rc4/rc4.man ================================================================== --- modules/rc4/rc4.man +++ modules/rc4/rc4.man @@ -114,7 +114,7 @@ [section "AUTHORS"] Pat Thoyts [vset CATEGORY rc4] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/rcs/rcs.man ================================================================== --- modules/rcs/rcs.man +++ modules/rcs/rcs.man @@ -324,7 +324,7 @@ }} {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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/report/report.man ================================================================== --- modules/report/report.man +++ modules/report/report.man @@ -470,7 +470,7 @@ % # alternate way of doing the above % m format 2string r }] [vset CATEGORY report] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/rest/rest.man ================================================================== --- modules/rest/rest.man +++ modules/rest/rest.man @@ -547,11 +547,11 @@ }] [include ../common-text/tls-security-notes.inc] [vset CATEGORY rest] -[include ../doctools2base/include/feedback.inc] +[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. Index: modules/ripemd/ripemd128.man ================================================================== --- modules/ripemd/ripemd128.man +++ modules/ripemd/ripemd128.man @@ -185,7 +185,7 @@ ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY ripemd] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/ripemd/ripemd160.man ================================================================== --- modules/ripemd/ripemd160.man +++ modules/ripemd/ripemd160.man @@ -169,7 +169,7 @@ ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY ripemd] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/sasl/gtoken.man ================================================================== --- modules/sasl/gtoken.man +++ modules/sasl/gtoken.man @@ -21,7 +21,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/sasl/ntlm.man ================================================================== --- modules/sasl/ntlm.man +++ modules/sasl/ntlm.man @@ -30,7 +30,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/sasl/sasl.man ================================================================== --- modules/sasl/sasl.man +++ modules/sasl/sasl.man @@ -334,7 +334,7 @@ [section AUTHORS] Pat Thoyts [vset CATEGORY sasl] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/sasl/scram.man ================================================================== --- modules/sasl/scram.man +++ modules/sasl/scram.man @@ -30,7 +30,7 @@ [section AUTHORS] Sergei Golovan [vset CATEGORY sasl] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/sha1/sha1.man ================================================================== --- modules/sha1/sha1.man +++ modules/sha1/sha1.man @@ -177,7 +177,7 @@ ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY sha1] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/sha1/sha256.man ================================================================== --- modules/sha1/sha256.man +++ modules/sha1/sha256.man @@ -189,7 +189,7 @@ ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] [vset CATEGORY sha1] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/smtpd/smtpd.man ================================================================== --- modules/smtpd/smtpd.man +++ modules/smtpd/smtpd.man @@ -288,7 +288,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/snit/snit.man ================================================================== --- modules/snit/snit.man +++ modules/snit/snit.man @@ -2833,7 +2833,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/snit/snitfaq.man ================================================================== --- modules/snit/snitfaq.man +++ modules/snit/snitfaq.man @@ -4108,7 +4108,7 @@ mylib::propagate -foreground to {comp1 comp2 comp3} } }] [vset CATEGORY snit] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/soundex/soundex.man ================================================================== --- modules/soundex/soundex.man +++ modules/soundex/soundex.man @@ -39,7 +39,7 @@ % ::soundex::knuth Knuth K530 }] [vset CATEGORY soundex] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/stooop/stooop.man ================================================================== --- modules/stooop/stooop.man +++ modules/stooop/stooop.man @@ -217,7 +217,7 @@ [section EXAMPLES] Please see the full HTML documentation in [uri stooop_man.html]. [vset CATEGORY stooop] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/stooop/switched.man ================================================================== --- modules/stooop/switched.man +++ modules/stooop/switched.man @@ -322,7 +322,7 @@ }] [list_end] [vset CATEGORY stooop] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/string/token.man ================================================================== --- modules/string/token.man +++ modules/string/token.man @@ -91,7 +91,7 @@ exactly at the character index found in [arg startvar]. [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/string/token_shell.man ================================================================== --- modules/string/token_shell.man +++ modules/string/token_shell.man @@ -135,7 +135,7 @@ [list_end] [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/stringprep/stringprep.man ================================================================== --- modules/stringprep/stringprep.man +++ modules/stringprep/stringprep.man @@ -145,7 +145,7 @@ [section "AUTHORS"] Sergei Golovan [vset CATEGORY stringprep] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/stringprep/stringprep_data.man ================================================================== --- modules/stringprep/stringprep_data.man +++ modules/stringprep/stringprep_data.man @@ -15,7 +15,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/stringprep/unicode.man ================================================================== --- modules/stringprep/unicode.man +++ modules/stringprep/unicode.man @@ -77,7 +77,7 @@ [section "AUTHORS"] Sergei Golovan [vset CATEGORY stringprep] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/stringprep/unicode_data.man ================================================================== --- modules/stringprep/unicode_data.man +++ modules/stringprep/unicode_data.man @@ -15,7 +15,7 @@ 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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/disjointset.man ================================================================== --- modules/struct/disjointset.man +++ modules/struct/disjointset.man @@ -230,7 +230,7 @@ Destroys the disjoint set object and all associated memory. [list_end] [vset CATEGORY {struct :: disjointset}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/graph.man ================================================================== --- modules/struct/graph.man +++ modules/struct/graph.man @@ -958,7 +958,7 @@ criterium. [list_end] [vset CATEGORY {struct :: graph}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/graph1.man ================================================================== --- modules/struct/graph1.man +++ modules/struct/graph1.man @@ -369,7 +369,7 @@ a node [const enter]s it, the second visit [const leave]s it. [list_end] [vset CATEGORY {struct :: graph}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/graphops.man ================================================================== --- modules/struct/graphops.man +++ modules/struct/graphops.man @@ -1313,7 +1313,7 @@ [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] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/matrix.man ================================================================== --- modules/struct/matrix.man +++ modules/struct/matrix.man @@ -533,7 +533,7 @@ % # alternate way of doing the above % r printmatrix m }] [vset CATEGORY {struct :: matrix}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/matrix1.man ================================================================== --- modules/struct/matrix1.man +++ modules/struct/matrix1.man @@ -375,7 +375,7 @@ % # alternate way of doing the above % r printmatrix m }] [vset CATEGORY {struct :: matrix}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/pool.man ================================================================== --- modules/struct/pool.man +++ modules/struct/pool.man @@ -437,7 +437,7 @@ # or return a 'Server busy' message to the client. } }] [vset CATEGORY {struct :: pool}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/prioqueue.man ================================================================== --- modules/struct/prioqueue.man +++ modules/struct/prioqueue.man @@ -105,7 +105,7 @@ Return the number of items in the prioqueue. [list_end] [vset CATEGORY {struct :: prioqueue}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/queue.man ================================================================== --- modules/struct/queue.man +++ modules/struct/queue.man @@ -90,7 +90,7 @@ Return the number of items in the queue. [list_end] [vset CATEGORY {struct :: queue}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/record.man ================================================================== --- modules/struct/record.man +++ modules/struct/record.man @@ -387,7 +387,7 @@ }] [para] [vset CATEGORY {struct :: record}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/skiplist.man ================================================================== --- modules/struct/skiplist.man +++ modules/struct/skiplist.man @@ -80,7 +80,7 @@ current node appended. [list_end] [vset CATEGORY {struct :: skiplist}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/stack.man ================================================================== --- modules/struct/stack.man +++ modules/struct/stack.man @@ -102,7 +102,7 @@ Return the number of items on the stack. [list_end] [vset CATEGORY {struct :: stack}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/struct_list.man ================================================================== --- modules/struct/struct_list.man +++ modules/struct/struct_list.man @@ -824,7 +824,7 @@ [uri http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz]. [list_end] [vset CATEGORY {struct :: list}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/struct_map.man ================================================================== --- modules/struct/struct_map.man +++ modules/struct/struct_map.man @@ -69,7 +69,7 @@ The result of the command is the empty string. [list_end] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/struct_set.man ================================================================== --- modules/struct/struct_set.man +++ modules/struct/struct_set.man @@ -130,7 +130,7 @@ [list_end] [section REFERENCES] [vset CATEGORY {struct :: set}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/struct_tree.man ================================================================== --- modules/struct/struct_tree.man +++ modules/struct/struct_tree.man @@ -786,7 +786,7 @@ # generated name. The name is returned # as the result of the command. }] [vset CATEGORY {struct :: tree}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/struct/struct_tree1.man ================================================================== --- modules/struct/struct_tree1.man +++ modules/struct/struct_tree1.man @@ -286,7 +286,7 @@ [list_end] [list_end] [vset CATEGORY {struct :: tree}] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/tar/tar.man ================================================================== --- modules/tar/tar.man +++ modules/tar/tar.man @@ -163,7 +163,7 @@ }] [list_end] [vset CATEGORY tar] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/ansi_cattr.man ================================================================== --- modules/term/ansi_cattr.man +++ modules/term/ansi_cattr.man @@ -77,7 +77,7 @@ [call [cmd ::term::ansi::code::attr::nostrike]] Strike-through off. [call [cmd ::term::ansi::code::attr::reset]] Reset all attributes to their default values. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/ansi_cctrl.man ================================================================== --- modules/term/ansi_cctrl.man +++ modules/term/ansi_cctrl.man @@ -193,7 +193,7 @@ Format the block of text for display at the specified location. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/ansi_cmacros.man ================================================================== --- modules/term/ansi_cmacros.man +++ modules/term/ansi_cmacros.man @@ -60,7 +60,7 @@ the command. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/ansi_code.man ================================================================== --- modules/term/ansi_code.man +++ modules/term/ansi_code.man @@ -40,7 +40,7 @@ sequence [arg code]. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/ansi_ctrlu.man ================================================================== --- modules/term/ansi_ctrlu.man +++ modules/term/ansi_ctrlu.man @@ -73,7 +73,7 @@ the number of rows (aka lines) available for display. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/ansi_send.man ================================================================== --- modules/term/ansi_send.man +++ modules/term/ansi_send.man @@ -260,7 +260,7 @@ Show the block of text at the specified location. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/imenu.man ================================================================== --- modules/term/imenu.man +++ modules/term/imenu.man @@ -149,7 +149,7 @@ The interaction with the object is terminated. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/ipager.man ================================================================== --- modules/term/ipager.man +++ modules/term/ipager.man @@ -148,7 +148,7 @@ The interaction with the object is terminated. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/receive.man ================================================================== --- modules/term/receive.man +++ modules/term/receive.man @@ -71,7 +71,7 @@ If not specified [arg chan] defaults to [const stdin]. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/term.man ================================================================== --- modules/term/term.man +++ modules/term/term.man @@ -14,7 +14,7 @@ commands, in the vein of ncurses or similar packages. Currently nothing has been implemented however. I.e. this package is empty. It can be loaded, yet provides nothing. [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/term_bind.man ================================================================== --- modules/term/term_bind.man +++ modules/term/term_bind.man @@ -118,7 +118,7 @@ In other words, the set of recognized strings has to form a [term {prefix code}]. [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/term/term_send.man ================================================================== --- modules/term/term_send.man +++ modules/term/term_send.man @@ -30,7 +30,7 @@ destination channel is fixed to [emph stdout]. [list_end] [vset CATEGORY term] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/textutil/adjust.man ================================================================== --- modules/textutil/adjust.man +++ modules/textutil/adjust.man @@ -202,7 +202,7 @@ create properly wrapped paragraphs with arbitrary indentations. [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/textutil/expander.man ================================================================== --- modules/textutil/expander.man +++ modules/textutil/expander.man @@ -505,7 +505,7 @@ [cmd expander] was written by William H. Duquette; it is a repackaging of the central algorithm of the expand macro processing tool. [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/textutil/repeat.man ================================================================== --- modules/textutil/repeat.man +++ modules/textutil/repeat.man @@ -40,7 +40,7 @@ A convenience command. Returns a string of [arg num] spaces. [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/textutil/tabify.man ================================================================== --- modules/textutil/tabify.man +++ modules/textutil/tabify.man @@ -66,7 +66,7 @@ space, but not the other way around. [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/textutil/textutil.man ================================================================== --- modules/textutil/textutil.man +++ modules/textutil/textutil.man @@ -382,7 +382,7 @@ own longest common prefix. [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/textutil/textutil_split.man ================================================================== --- modules/textutil/textutil_split.man +++ modules/textutil/textutil_split.man @@ -50,7 +50,7 @@ The regular expression [arg regexp] defaults to "[lb]\\t \\r\\n[rb]+". [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/textutil/textutil_string.man ================================================================== --- modules/textutil/textutil_string.man +++ modules/textutil/textutil_string.man @@ -67,7 +67,7 @@ own longest common prefix. [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/textutil/trim.man ================================================================== --- modules/textutil/trim.man +++ modules/textutil/trim.man @@ -69,7 +69,7 @@ string is returned as the result of the command. [list_end] [vset CATEGORY textutil] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/tie/tie.man ================================================================== --- modules/tie/tie.man +++ modules/tie/tie.man @@ -529,7 +529,7 @@ $a($idx) ds getv idx ----------- ----------- }] [vset CATEGORY tie] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/tie/tie_std.man ================================================================== --- modules/tie/tie_std.man +++ modules/tie/tie_std.man @@ -29,7 +29,7 @@ They are automatically loaded and registered by [package tie] when it itself is requested, and as such there is no need to request them on their own, although it is possible to do so. [vset CATEGORY tie] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/tiff/tiff.man ================================================================== --- modules/tiff/tiff.man +++ modules/tiff/tiff.man @@ -168,7 +168,7 @@ [enum] Reading limited to uncompressed 8 bit rgb and 8 bit palletized images [enum] Writing limited to uncompressed 8 bit rgb [list_end] [vset CATEGORY tiff] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/tool/meta.man ================================================================== --- modules/tool/meta.man +++ modules/tool/meta.man @@ -159,7 +159,7 @@ [section AUTHORS] Donal Fellows, Andreas Kupries [vset CATEGORY oo::util] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/tool/tool.man ================================================================== --- modules/tool/tool.man +++ modules/tool/tool.man @@ -228,9 +228,9 @@ [section AUTHORS] Sean Woods [vset CATEGORY tcloo] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/tool/tool_dict_ensemble.man ================================================================== --- modules/tool/tool_dict_ensemble.man +++ modules/tool/tool_dict_ensemble.man @@ -1,34 +1,34 @@ -[comment {-*- tcl -*- doctools manpage}] -[manpage_begin tool::dict_ensemble n 0.4.2] -[keywords TOOL] -[copyright {2015 Sean Woods }] -[moddesc {Standardized OO Framework for development}] -[titledesc {Dictionary Tools}] -[category Utility] -[keywords TclOO] -[keywords TOOL] -[require tool [opt 0.4.2]] -[description] -[para] -The [cmd dict_ensemble] command is a keyword added by [package tool]. It defines -a public variable (stored as a dict), and an access function to manipulated and -access the values stored in that dict. -[list_begin definitions] - -[call [emph object] [arg ensemble] [cmd add] [arg field]]] [arg value] [arg {value ...}]] - -Adds elements to a list maintained with the [arg field] leaf of the dict maintained -my this ensemble. - - -Declares a variable [arg name] which will be initialized as an array, populated with [arg contents] for objects of this class, as well as any -objects for classes which are descendents of this class. - -[list_end] - -[section AUTHORS] -Sean Woods - -[vset CATEGORY tool] -[include ../doctools2base/include/feedback.inc] +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin tool::dict_ensemble n 0.4.2] +[keywords TOOL] +[copyright {2015 Sean Woods }] +[moddesc {Standardized OO Framework for development}] +[titledesc {Dictionary Tools}] +[category Utility] +[keywords TclOO] +[keywords TOOL] +[require tool [opt 0.4.2]] +[description] +[para] +The [cmd dict_ensemble] command is a keyword added by [package tool]. It defines +a public variable (stored as a dict), and an access function to manipulated and +access the values stored in that dict. +[list_begin definitions] + +[call [emph object] [arg ensemble] [cmd add] [arg field]]] [arg value] [arg {value ...}]] + +Adds elements to a list maintained with the [arg field] leaf of the dict maintained +my this ensemble. + + +Declares a variable [arg name] which will be initialized as an array, populated with [arg contents] for objects of this class, as well as any +objects for classes which are descendents of this class. + +[list_end] + +[section AUTHORS] +Sean Woods + +[vset CATEGORY tool] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/transfer/connect.man ================================================================== --- modules/transfer/connect.man +++ modules/transfer/connect.man @@ -162,7 +162,7 @@ [vset OBJCREATE {transfer::connect C}] [include include/secure.inc] [vset CATEGORY transfer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/transfer/copyops.man ================================================================== --- modules/transfer/copyops.man +++ modules/transfer/copyops.man @@ -157,7 +157,7 @@ [list_end][comment options] [list_end][comment definitions/api] [vset CATEGORY transfer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/transfer/ddest.man ================================================================== --- modules/transfer/ddest.man +++ modules/transfer/ddest.man @@ -116,7 +116,7 @@ [list_begin options] [include include/ddest_options.inc] [list_end] [vset CATEGORY transfer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/transfer/dsource.man ================================================================== --- modules/transfer/dsource.man +++ modules/transfer/dsource.man @@ -148,7 +148,7 @@ [list_begin options] [include include/dsource_options.inc] [list_end] [vset CATEGORY transfer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/transfer/receiver.man ================================================================== --- modules/transfer/receiver.man +++ modules/transfer/receiver.man @@ -176,11 +176,11 @@ [vset OBJCREATE {transfer::receiver R}] [include include/secure.inc] [vset CATEGORY transfer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [comment { This option specifies the command to invoke when the transmission of the information in the data source has been completed. The arguments given to this command are the same as given to the completion callback Index: modules/transfer/tqueue.man ================================================================== --- modules/transfer/tqueue.man +++ modules/transfer/tqueue.man @@ -168,7 +168,7 @@ additional data structure which keeps track of outstanding results as they may come back in a different order than the requests from the client, and releases them to the actual queue in the proper order. [vset CATEGORY transfer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/transfer/transmitter.man ================================================================== --- modules/transfer/transmitter.man +++ modules/transfer/transmitter.man @@ -178,7 +178,7 @@ [vset OBJCREATE {transfer::transmitter T}] [include include/secure.inc] [vset CATEGORY transfer] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/treeql/treeql.man ================================================================== --- modules/treeql/treeql.man +++ modules/treeql/treeql.man @@ -813,7 +813,7 @@ this package there. [list_end] [vset CATEGORY treeql] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/try/tcllib_throw.man ================================================================== --- modules/try/tcllib_throw.man +++ modules/try/tcllib_throw.man @@ -34,7 +34,7 @@ [para][example_begin] [cmd throw] {MYERROR CODE} "My error message" [example_end] [vset CATEGORY try] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/try/tcllib_try.man ================================================================== --- modules/try/tcllib_try.man +++ modules/try/tcllib_try.man @@ -117,7 +117,7 @@ puts "failed to open /some/file/name: it doesn't exist" } [example_end] [vset CATEGORY try] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/udpcluster/udpcluster.man ================================================================== --- modules/udpcluster/udpcluster.man +++ modules/udpcluster/udpcluster.man @@ -53,7 +53,7 @@ [para] This tool was originally known as nns::cluster, but as development progressed, it was clear that it wasn't interacting with any of the other facilities in NNS. [vset CATEGORY nameserv] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/uev/uevent.man ================================================================== --- modules/uev/uevent.man +++ modules/uev/uevent.man @@ -190,7 +190,7 @@ [comment ============================================================] [list_end] [vset CATEGORY uevent] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/uev/uevent_onidle.man ================================================================== --- modules/uev/uevent_onidle.man +++ modules/uev/uevent_onidle.man @@ -58,7 +58,7 @@ Examples of this type of deferal are buried in the (C-level) implementations all the Tk widgets, defering geometry calculations and window redraw activity in this manner. [vset CATEGORY uevent] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/units/units.man ================================================================== --- modules/units/units.man +++ modules/units/units.man @@ -386,7 +386,7 @@ [section "AUTHORS"] Robert W. Techentin [vset CATEGORY units] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/uri/uri.man ================================================================== --- modules/uri/uri.man +++ modules/uri/uri.man @@ -387,7 +387,7 @@ Original code (regular expressions) by Andreas Kupries. Modularisation by Steve Ball, also the split/join/resolve functionality. RFC 3986 conformance by Keith Nash. [vset CATEGORY uri] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/uri/urn-scheme.man ================================================================== --- modules/uri/urn-scheme.man +++ modules/uri/urn-scheme.man @@ -35,7 +35,7 @@ characters, and returns the modified urls as its result. [list_end] [vset CATEGORY uri] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/uuid/uuid.man ================================================================== --- modules/uuid/uuid.man +++ modules/uuid/uuid.man @@ -49,7 +49,7 @@ ([uri http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt]) [list_end] [vset CATEGORY uuid] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/valtype/include/vtype.inc ================================================================== --- modules/valtype/include/vtype.inc +++ modules/valtype/include/vtype.inc @@ -96,7 +96,7 @@ [include [vset CODES].inc] [list_end] [vset CATEGORY valtype] -[include ../../doctools2base/include/feedback.inc] +[include ../../common-text/feedback.inc] [manpage_end] Index: modules/valtype/valtype_common.man ================================================================== --- modules/valtype/valtype_common.man +++ modules/valtype/valtype_common.man @@ -104,7 +104,7 @@ [include include/c_lenpfx.inc] [list_end] [vset CATEGORY valtype] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/cat.man ================================================================== --- modules/virtchannel_base/cat.man +++ modules/virtchannel_base/cat.man @@ -42,7 +42,7 @@ channels, and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/facade.man ================================================================== --- modules/virtchannel_base/facade.man +++ modules/virtchannel_base/facade.man @@ -67,7 +67,7 @@ channel [arg chan], and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/halfpipe.man ================================================================== --- modules/virtchannel_base/halfpipe.man +++ modules/virtchannel_base/halfpipe.man @@ -75,7 +75,7 @@ A single argument is supplied, the handle of the channel. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/nullzero.man ================================================================== --- modules/virtchannel_base/nullzero.man +++ modules/virtchannel_base/nullzero.man @@ -38,7 +38,7 @@ This command creates a new nullzero channel and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/randseed.man ================================================================== --- modules/virtchannel_base/randseed.man +++ modules/virtchannel_base/randseed.man @@ -37,7 +37,7 @@ length the shorter of the two is padded with 0s before merging. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/std.man ================================================================== --- modules/virtchannel_base/std.man +++ modules/virtchannel_base/std.man @@ -37,7 +37,7 @@ future calls simply return this handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_fifo.man ================================================================== --- modules/virtchannel_base/tcllib_fifo.man +++ modules/virtchannel_base/tcllib_fifo.man @@ -37,7 +37,7 @@ This command creates a new fifo channel and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_fifo2.man ================================================================== --- modules/virtchannel_base/tcllib_fifo2.man +++ modules/virtchannel_base/tcllib_fifo2.man @@ -44,7 +44,7 @@ their handles, as a list containing two elements. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_memchan.man ================================================================== --- modules/virtchannel_base/tcllib_memchan.man +++ modules/virtchannel_base/tcllib_memchan.man @@ -39,7 +39,7 @@ This command creates a new memchan channel and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_null.man ================================================================== --- modules/virtchannel_base/tcllib_null.man +++ modules/virtchannel_base/tcllib_null.man @@ -39,7 +39,7 @@ This command creates a new null channel and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_random.man ================================================================== --- modules/virtchannel_base/tcllib_random.man +++ modules/virtchannel_base/tcllib_random.man @@ -40,7 +40,7 @@ internal feedback shift register of the generator. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_string.man ================================================================== --- modules/virtchannel_base/tcllib_string.man +++ modules/virtchannel_base/tcllib_string.man @@ -40,7 +40,7 @@ channel provides random read-only access to the [arg content] string. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_variable.man ================================================================== --- modules/virtchannel_base/tcllib_variable.man +++ modules/virtchannel_base/tcllib_variable.man @@ -41,7 +41,7 @@ variable [arg varname]. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_zero.man ================================================================== --- modules/virtchannel_base/tcllib_zero.man +++ modules/virtchannel_base/tcllib_zero.man @@ -39,7 +39,7 @@ This command creates a new zero channel and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_base/textwindow.man ================================================================== --- modules/virtchannel_base/textwindow.man +++ modules/virtchannel_base/textwindow.man @@ -33,7 +33,7 @@ Data written to this channel will appear in the associated [arg widget]. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_core/core.man ================================================================== --- modules/virtchannel_core/core.man +++ modules/virtchannel_core/core.man @@ -66,7 +66,7 @@ the assumption that the channel is being destroyed by Tcl. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_core/events.man ================================================================== --- modules/virtchannel_core/events.man +++ modules/virtchannel_core/events.man @@ -73,7 +73,7 @@ accordingly. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_core/transformcore.man ================================================================== --- modules/virtchannel_core/transformcore.man +++ modules/virtchannel_core/transformcore.man @@ -66,7 +66,7 @@ the assumption that the channel and transform are being destroyed by Tcl. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/adler32.man ================================================================== --- modules/virtchannel_transform/adler32.man +++ modules/virtchannel_transform/adler32.man @@ -64,7 +64,7 @@ [list_end] [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/hex.man ================================================================== --- modules/virtchannel_transform/hex.man +++ modules/virtchannel_transform/hex.man @@ -37,7 +37,7 @@ [arg chan] and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/identity.man ================================================================== --- modules/virtchannel_transform/identity.man +++ modules/virtchannel_transform/identity.man @@ -44,7 +44,7 @@ [arg chan] and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/limitsize.man ================================================================== --- modules/virtchannel_transform/limitsize.man +++ modules/virtchannel_transform/limitsize.man @@ -40,7 +40,7 @@ popping the transformation clears the EOF it generated as well. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/observe.man ================================================================== --- modules/virtchannel_transform/observe.man +++ modules/virtchannel_transform/observe.man @@ -44,7 +44,7 @@ [arg logw] are there the data is copied to. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/rot.man ================================================================== --- modules/virtchannel_transform/rot.man +++ modules/virtchannel_transform/rot.man @@ -51,7 +51,7 @@ through unchanged. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/spacer.man ================================================================== --- modules/virtchannel_transform/spacer.man +++ modules/virtchannel_transform/spacer.man @@ -39,7 +39,7 @@ defaults to a single space character (ASCII 32). [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/tcllib_zlib.man ================================================================== --- modules/virtchannel_transform/tcllib_zlib.man +++ modules/virtchannel_transform/tcllib_zlib.man @@ -40,7 +40,7 @@ compression, from [const 0] to [const 9], and defaults to [const 4]. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/vt_base64.man ================================================================== --- modules/virtchannel_transform/vt_base64.man +++ modules/virtchannel_transform/vt_base64.man @@ -38,7 +38,7 @@ [arg chan] and returns its handle. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/vt_counter.man ================================================================== --- modules/virtchannel_transform/vt_counter.man +++ modules/virtchannel_transform/vt_counter.man @@ -62,7 +62,7 @@ [list_end] [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/vt_crc32.man ================================================================== --- modules/virtchannel_transform/vt_crc32.man +++ modules/virtchannel_transform/vt_crc32.man @@ -64,7 +64,7 @@ [list_end] [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/vt_otp.man ================================================================== --- modules/virtchannel_transform/vt_otp.man +++ modules/virtchannel_transform/vt_otp.man @@ -47,7 +47,7 @@ the channel. [list_end] [vset CATEGORY virtchannel] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/websocket/websocket.man ================================================================== --- modules/websocket/websocket.man +++ modules/websocket/websocket.man @@ -379,7 +379,7 @@ [example_end] [include ../common-text/tls-security-notes.inc] [vset CATEGORY websocket] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/wip/wip.man ================================================================== --- modules/wip/wip.man +++ modules/wip/wip.man @@ -378,7 +378,7 @@ [section EXAMPLES] No examples yet. [vset CATEGORY wip] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/yaml/huddle.man ================================================================== --- modules/yaml/huddle.man +++ modules/yaml/huddle.man @@ -552,7 +552,7 @@ [para] now printing. [vset CATEGORY huddle] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/yaml/yaml.man ================================================================== --- modules/yaml/yaml.man +++ modules/yaml/yaml.man @@ -183,7 +183,7 @@ [para] Not enough character set of line feeds. Please use only "\n" as line breaks. [vset CATEGORY yaml] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/zip/decode.man ================================================================== --- modules/zip/decode.man +++ modules/zip/decode.man @@ -129,7 +129,7 @@ [para] The result of the command is the empty string. [list_end] [vset CATEGORY zipfile] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/zip/encode.man ================================================================== --- modules/zip/encode.man +++ modules/zip/encode.man @@ -86,7 +86,7 @@ a specific order of files in the archive, for example [file .epub]. [list_end] [vset CATEGORY zipfile] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: modules/zip/mkzip.man ================================================================== --- modules/zip/mkzip.man +++ modules/zip/mkzip.man @@ -98,7 +98,7 @@ [list_end] [list_end] [vset CATEGORY zipfile] -[include ../doctools2base/include/feedback.inc] +[include ../common-text/feedback.inc] [manpage_end] Index: support/devel/sak/localdoc/localdoc.tcl ================================================================== --- support/devel/sak/localdoc/localdoc.tcl +++ support/devel/sak/localdoc/localdoc.tcl @@ -42,14 +42,14 @@ puts "Reindex the documentation..." sak::doc::imake __dummy__ $excluded sak::doc::index __dummy__ $excluded puts "Removing old documentation..." - # but keep the main index around, manually created, edited, not to be touched + # Keep the main index around however, manually created, edited, + # not to be touched # TODO: catch errors and restore automatically file rename embedded/index.md e_index.md - file delete -force embedded file mkdir embedded/md # Put the saved main page back into place, early. file rename e_index.md embedded/index.md