1RCS: @(#) $Id: README,v 1.3 2003/11/28 22:42:03 andreas_kupries Exp $ 2 3Welcome to the tklib, the Tk Standard Library. This package is 4intended to be a collection of Tcl packages that provide utility 5functions useful to a large collection of Tcl programmers. 6 7The home web site for this code is http://tcllib.sourceforge.net/ . 8At this web site, you will find mailing lists, web forums, databases 9for bug reports and feature requests, the CVS repository (browsable on 10the web, or read-only accessible via CVS ), and more. 11 12Please note that tklib depends on tcllib, the Tcl Standard Library. 13This is true for both installation and runtime. 14 15 16The structure of the tklib source hierarchy is: 17 18tklib 19 +- modules 20 +- <module1> 21 +- <module2> 22 +- ... 23 24 25The install hierarchy is: 26 27.../lib/tklib 28 +- <module1> 29 +- <module2> 30 +- ... 31 32There are some base requirements that a module must meet before it 33will be added to tklib: 34 35* the module must be a proper Tcl package 36* the module must use a namespace for its commands and variables 37* the name of the package must be the same as the name of the 38 namespace 39* the module must reside in a subdirectory of the modules directory in 40 the source hierarchy, and that subdirectory must have the same name 41 as the package and namespace 42* the module must be released under the BSD License, the terms of 43 which can be found in the toplevel tklib source directory in the file 44 license.terms 45* the module should have both documentation ([*]) and a test suite 46 (in the form of a group of *.test files in the module directory). 47 48 [*] Possible forms: doctools, TMML/XML, nroff (man), or HTML. 49 The first format is the most prefered as it can be processed with 50 tools provided by tcllib (See module doctools there). The first 51 two are prefered in general as they are semantic markup and thus 52 easier to convert into other formats. 53 54* the module must have either documentation or a test suite. It can 55 not have neither. 56* the module should adhere to Tcl coding standards 57 58When adding a module to tklib, be sure to add it to the files listed below. 59 60* installed_modules.tcl 61 62 contains a table listing all modules to be installed, modules 63 excluded, and names the actions to be taken during installation 64 of each module. Add a line to this table naming your module and 65 its actions. 66 67 Three actions have to be specified, for the package itself, its 68 documentation, and the examples demonstrating it. 69 70 The _null action can be used everywhere and signals that there is 71 nothing to do. Although it is possible to use it for the package 72 action it does make no sense there, as that means that no package 73 code is installed. 74 75 Other package actions are _tcl, _tci, and _text. The first causes 76 the installer to copy all .tcl files from the source directory for 77 the module into the appropriate module directory. _tci does all that 78 and also expects a tclIndex file to copy. _tex is like _tcl, however 79 it also copies all .tex files found in the source directory for the 80 module. 81 82 There is currently only one true documentation action. This action 83 is _doc. It converts all documentation in doctools format into the 84 format chosen by the user for installation and copies the result 85 into the appropriate directory. 86 87 There is currently one true action for examples, _exa. It copies all 88 files in the source directory for examples into the directory chosen 89 by the user as destination for examples. 90 91Each module source directory should have no subdirectories (other than 92the CVS directory), and should contain the following files: 93 94* source code *.tcl 95* package index pkgIndex.tcl 96* tests *.test 97* documentation *.man, *.n, *.xml 98 99If you do not follow this directory structure, the tklib Makefile 100will fail to locate the files from the new module. 101