BUGS, IDEAS, FEEDBACK

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category yaml of the -Tcllib SF Trackers. +Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

Index: examples/mime/mbot/README.txt ================================================================== --- examples/mime/mbot/README.txt +++ examples/mime/mbot/README.txt @@ -617,13 +617,13 @@ README The personal.tcl Mailbot February 2002 References - [1] + [1] - [2] + [2] [3] Author's Address Index: examples/mime/mbot/README.xml ================================================================== --- examples/mime/mbot/README.xml +++ examples/mime/mbot/README.xml @@ -46,14 +46,14 @@

This package requires: -Tcl version 8.3 +Tcl version 8.3 or later -tcl lib +tcl lib TclX version 8.0 or later

Index: modules/aes/aes.man ================================================================== --- modules/aes/aes.man +++ modules/aes/aes.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin aes n 1.1.1] +[see_also blowfish(n)] +[see_also des(n)] +[see_also md5(n)] +[see_also sha1(n)] +[keywords aes] +[keywords {block cipher}] +[keywords {data integrity}] +[keywords encryption] +[keywords security] [copyright {2005, Pat Thoyts }] [copyright {2012-2013, Andreas Kupries }] [moddesc {Advanced Encryption Standard (AES)}] [titledesc {Implementation of the AES block cipher}] [category {Hashes, checksums, and encryption}] @@ -37,11 +46,11 @@ this channel. [para] The [arg -key] option must be given. This parameter takes a binary -string of either 16, 24 or 32 bytes in length and is used to generate the +string of either 16, 24 or 32 bytes in length and is used to generate the key schedule. [para] The [arg -mode] and [arg -dir] options are optional and default to cbc @@ -148,24 +157,11 @@ Federal Information Processing Standards Publication 197, 2001 ([uri http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf]) [list_end] -[see_also des(n) md5(n) sha1(n) blowfish(n)] - [section AUTHORS] Thorsten Schloermann, Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph aes] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords aes {block cipher} security encryption {data integrity}] +[vset CATEGORY aes] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/amazon-s3/S3.man ================================================================== --- modules/amazon-s3/S3.man +++ modules/amazon-s3/S3.man @@ -1,24 +1,26 @@ [manpage_begin S3 n 1.0.0] +[keywords amazon] +[keywords cloud] +[keywords s3] [moddesc {Amazon S3 Web Service Utilities}] [titledesc {Amazon S3 Web Service Interface}] [category Networking] [copyright {Copyright 2006,2008 Darren New. All Rights Reserved. See LICENSE.TXT for terms.}] [require Tcl 8.5] [require sha1 1.0] [require md5 2.0] [require base64 2.3] [require xsxp 1.0] -[keywords amazon s3 cloud] [description] This package provides access to Amazon's Simple Storage Solution web service. [para] As a quick summary, Amazon Simple Storage Solution provides a for-fee web service allowing the storage of arbitrary data as -"resources" within "buckets" online. -See [uri http://www.amazonaws.com/] for details on that system. +"resources" within "buckets" online. +See [uri http://www.amazonaws.com/] for details on that system. Access to the service is via HTTP (SOAP or REST). Much of this documentation will not make sense if you're not familiar with the terms and functionality of the Amazon S3 service. [para] @@ -29,23 +31,23 @@ [para] Copyright 2006 Darren New. All Rights Reserved. NO WARRANTIES OF ANY TYPE ARE PROVIDED. COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS. -This software is licensed under essentially the same +This software is licensed under essentially the same terms as Tcl. See LICENSE.txt for the terms. [section "ERROR REPORTING"] -The error reporting from this package makes use of $errorCode to +The error reporting from this package makes use of $errorCode to provide more details on what happened than simply throwing an error. Any error caught by the S3 package (and we try to catch them all) will return with an $errorCode being a list having at least three elements. In all cases, the first element will be "S3". The second element will take on one of six values, with that element defining the value of the third and subsequent elements. S3::REST does not -throw an error, but rather returns a dictionary with the keys "error", +throw an error, but rather returns a dictionary with the keys "error", "errorInfo", and "errorCode" set. This allows for reliable background use. The possible second elements are these: [list_begin definitions] [def usage] The usage of the package is incorrect. For example, @@ -54,24 +56,24 @@ options has been specified. The third element of $errorCode supplies the name of the parameter that was wrong. The fourth usually provides the arguments that were actually supplied to the throwing proc, unless the usage error isn't confined to a single proc. -[def local] Something happened on the local system which threw +[def local] Something happened on the local system which threw an error. For example, a request to upload or download a file was made and the file permissions denied that sort of access. The third element of $errorCode is the original $errorCode. -[def socket] Something happened with the socket. It closed -prematurely, or some other condition of failure-to-communicate-with-Amazon +[def socket] Something happened with the socket. It closed +prematurely, or some other condition of failure-to-communicate-with-Amazon was detected. The third element of $errorCode is the original $errorCode, or sometimes the message from fcopy, or ...? [def remote] The Amazon web service returned an error code outside the 2xx range in the HTTP header. In other words, everything went as documented, except this particular case was documented not to work. -The third element is the dictionary returned from [cmd ::S3::REST]. +The third element is the dictionary returned from [cmd ::S3::REST]. Note that S3::REST itself never throws this error, but just returns the dictionary. Most of the higher-level commands throw for convenience, unless an argument indicates they should not. If something is documented as "not throwing an S3 remote error", it means a status return is set rather than throwing an error if Amazon returns a non-2XX HTTP result code. @@ -79,51 +81,50 @@ [def notyet] The user obeyed the documentation, but the author has not yet gotten around to implementing this feature. (Right now, only TLS support and sophisticated permissions fall into this category, as well as the S3::Acl command.) -[def xml] The service has returned invalid XML, or XML whose +[def xml] The service has returned invalid XML, or XML whose schema is unexpected. For the high-level commands that accept service XML as input for parsing, this may also be thrown. [list_end] - [section COMMANDS] -This package provides several separate levels of complexity. +This package provides several separate levels of complexity. [list_begin itemized] -[item] +[item] The lowest level simply takes arguments to be sent to the service, sends them, retrieves the result, and provides it to the caller. [emph Note:] This layer allows both synchronous and event-driven processing. It depends on the MD5 and SHA1 and base64 packages -from Tcllib (available at [uri http://core.tcl.tk/tcllib/]). -Note that [cmd S3::Configure] is required for [cmd S3::REST] to +from Tcllib (available at [uri http://core.tcl.tk/tcllib/]). +Note that [cmd S3::Configure] is required for [cmd S3::REST] to work due to the authentication portion, so we put that in the "lowest level." [item] The next layer parses the results of calls, allowing for functionality -such as uploading only changed files, synchronizing directories, -and so on. This layer depends on the [package TclXML] package as well as the +such as uploading only changed files, synchronizing directories, +and so on. This layer depends on the [package TclXML] package as well as the included [package xsxp] package. These packages are package required when these more-sophisticated routines are called, so nothing breaks if they are not correctly installed. [item] -Also included is a separate program that uses the library. +Also included is a separate program that uses the library. It provides code to parse $argv0 and $argv from the -command line, allowing invocation as a tclkit, etc. +command line, allowing invocation as a tclkit, etc. (Not yet implmented.) [item] Another separate program provides a GUI interface allowing drag-and-drop and other such functionality. (Not yet implemented.) [item] -Also built on this package is the OddJob program. It is -a separate program designed to allow distribution of +Also built on this package is the OddJob program. It is +a separate program designed to allow distribution of computational work units over Amazon's Elastic Compute Cloud web service. [list_end] @@ -132,11 +133,11 @@ pure Tcl using only that which comes from widely-available sources, such as Tcllib. [section "LOW LEVEL COMMANDS"] These commands do not require any packages not listed above. -They talk directly to the service, or they are utility or +They talk directly to the service, or they are utility or configuration routines. Note that the "xsxp" package was written to support this package, so it should be available wherever you got this package. [list_begin definitions] @@ -152,11 +153,11 @@ [opt "[option -default-separator] [arg string]"] \ [opt "[option -default-acl] [arg private|public-read|public-read-write|authenticated-read|keep|calc]"] \ [opt "[option -default-bucket] [arg bucketname]"] \ ] -There is one command for configuration, and that is [cmd S3::Configure]. +There is one command for configuration, and that is [cmd S3::Configure]. If called with no arguments, it returns a dictionary of key/value pairs listing all current settings. If called with one argument, it returns the value of that single argument. If called with two or more arguments, it must be called with pairs of arguments, and it applies the changes in order. There is only one set @@ -178,20 +179,20 @@ from the higher-level commands, but not to [cmd S3::REST] itself. That is, [cmd S3::REST] will always return httpstatus 500 if that's what it receives. Functions like [cmd S3::Put] will retry the PUT call, and will also retry the GET and HEAD calls used to do content comparison. Changing this to 0 will prevent retries and their associated delays. -In addition, socket errors (i.e., errors whose errorCode starts with +In addition, socket errors (i.e., errors whose errorCode starts with "S3 socket") will be similarly retried after backoffs. [def "[option -accesskeyid] [arg idstring]"] [def "[option -secretaccesskey] [arg idstring]"] Each defaults to an empty string. These must be set before any calls are made. This is your S3 ID. Once you sign up for an account, go to [uri http://www.amazonaws.com/], -sign in, go to the "Your Web Services Account" button, pick "AWS -Access Identifiers", and your access key ID and secret access keys +sign in, go to the "Your Web Services Account" button, pick "AWS +Access Identifiers", and your access key ID and secret access keys will be available. All [cmd S3::REST] calls are authenticated. Blame Amazon for the poor choice of names. [def "[option -service-access-point] [arg FQDN]"] Defaults to "s3.amazonaws.com". This is the fully-qualified domain @@ -201,49 +202,49 @@ the library at your own service. [def "[option -slop-seconds] [arg integer]"] When comparing dates between Amazon and the local machine, two dates within this many seconds of each other are considered -the same. Useful for clock drift correction, processing overhead -time, and so on. +the same. Useful for clock drift correction, processing overhead +time, and so on. [def "[option -use-tls] [arg boolean]"] Defaults to false. This is not yet implemented. If true, [cmd S3::REST] will negotiate a TLS connection to Amazon. If false, unencrypted connections are used. [def "[option -bucket-prefix] [arg string]"] Defaults to "TclS3". This string is used by [cmd S3::SuggestBucketName] if that command is passed an empty string as an argument. It is used -to distinguish different applications using the Amazon service. +to distinguish different applications using the Amazon service. Your application should always set this to keep from interfering with the buckets of other users of Amazon S3 or with other buckets of the same user. [def "[option -default-compare] [arg always|never|exists|missing|newer|date|checksum|different]"] -Defaults to "always." If no -compare is specified on -[cmd S3::Put], [cmd S3::Get], or [cmd S3::Delete], this comparison is used. +Defaults to "always." If no -compare is specified on +[cmd S3::Put], [cmd S3::Get], or [cmd S3::Delete], this comparison is used. See those commands for a description of the meaning. [def "[option -default-separator] [arg string]"] Defaults to "/". This is currently unused. It might make sense to use -this for [cmd S3::Push] and [cmd S3::Pull], but allowing resources to +this for [cmd S3::Push] and [cmd S3::Pull], but allowing resources to have slashes in their names that aren't marking directories would be problematic. Hence, this currently does nothing. [def "[option -default-acl] [arg private|public-read|public-read-write|authenticated-read|keep|calc]"] Defaults to an empty string. If no -acl argument is provided to [cmd S3::Put] or -[cmd S3::Push], this string is used +[cmd S3::Push], this string is used (given as the x-amz-acl header if not keep or calc). If this is also -empty, no x-amz-acl header is generated. +empty, no x-amz-acl header is generated. This is [emph not] used by [cmd S3::REST]. [def "[option -default-bucket] [arg bucketname]"] If no bucket is given to [cmd S3::GetBucket], [cmd S3::PutBucket], -[cmd S3::Get], [cmd S3::Put], +[cmd S3::Get], [cmd S3::Put], [cmd S3::Head], [cmd S3::Acl], -[cmd S3::Delete], [cmd S3::Push], +[cmd S3::Delete], [cmd S3::Push], [cmd S3::Pull], or [cmd S3::Toss], and if this configuration variable is not an empty string (and not simply "/"), then this value will be used for the bucket. This is useful if one program does a large amount of resource manipulation within a single bucket. @@ -250,28 +251,28 @@ [list_end] [para] [call [cmd S3::SuggestBucket] [opt [arg name]]] -The [cmd S3::SuggestBucket] command accepts an optional string as +The [cmd S3::SuggestBucket] command accepts an optional string as a prefix and returns a valid bucket containing the [arg name] argument and the Access Key ID. This makes the name unique to the owner and to the application (assuming the application picks a good [arg name] argument). -If no name is provided, -the name from [cmd S3::Configure] [arg -bucket-prefix] is used. +If no name is provided, +the name from [cmd S3::Configure] [arg -bucket-prefix] is used. If that too is empty (which is not the default), an error is thrown. [call [cmd S3::REST] [arg dict]] -The [cmd S3::REST] command takes as an argument a dictionary and +The [cmd S3::REST] command takes as an argument a dictionary and returns a dictionary. The return dictionary has the same keys as the input dictionary, and includes additional keys as the result. The presence or absence of keys in the input dictionary can control -the behavior of the routine. It never throws an error directly, but +the behavior of the routine. It never throws an error directly, but includes keys "error", "errorInfo", and "errorCode" if necessary. Some keys are required, some optional. The routine can run either -in blocking or non-blocking mode, based on the presense +in blocking or non-blocking mode, based on the presense of [option resultvar] in the input dictionary. This requires the [arg -accesskeyid] and [arg -secretaccesskey] to be configured via [cmd S3::Configure] before being called. [para] The possible input keys are these: @@ -287,11 +288,11 @@ resource name that is already URL-encoded. [def [opt "[option rtype] [arg torrent|acl]"]] This indicates a torrent or acl resource is being manipulated. Do not include this in the [option resource] key, or the -"?" separator will get URL-encoded. +"?" separator will get URL-encoded. [def [opt "[option parameters] [arg dict]"]] This optional dictionary provides parameters added to the URL for the transaction. The keys must be in the correct case (which is confusing in the Amazon documentation) and the @@ -301,31 +302,31 @@ [def [opt "[option headers] [arg dict]"]] This optional dictionary provides headers to be added to the HTTP request. The keys must be in [emph "lower case"] for the authentication to work. The values must not contain -embedded newlines or carriage returns. This is primarily +embedded newlines or carriage returns. This is primarily useful for adding x-amz-* headers. Since authentication is calculated by [cmd S3::REST], do not add that header here. Since content-type gets its own key, also do not add that header here. [def [opt "[option inbody] [arg contentstring]"]] This optional item, if provided, gives the content that will be sent. It is sent with a tranfer encoding of binary, and -only the low bytes are used, so use [lb]encoding convertto utf-8[rb] +only the low bytes are used, so use [lb]encoding convertto utf-8[rb] if the string is a utf-8 string. This is written all in one blast, so if you are using non-blocking mode and the [option inbody] is especially large, you may wind up blocking on the write socket. [def [opt "[option infile] [arg filename]"]] This optional item, if provided, and if [option inbody] is not provided, names the file from which the body of the HTTP message will be constructed. The file is opened for reading and sent progressively by [lb]fcopy[rb], so it should not block in non-blocking mode -even if the file is very large. The file is transfered in -binary mode, so the bytes on your disk will match the bytes +even if the file is very large. The file is transfered in +binary mode, so the bytes on your disk will match the bytes in your resource. Due to HTTP restrictions, it must be possible to use [lb]file size[rb] on this file to determine the size at the start of the transaction. [def [opt "[option S3chan] [arg channel]"]] @@ -335,11 +336,11 @@ [cmd S3::Configure], which is normally s3.amazonaws.com. If this is provided, the channel is not closed at the end of the transaction. [def [opt "[option outchan] [arg channel]"]] This optional item, if provided, indicates the already-open channel -to which the body returned from S3 should be written. That is, +to which the body returned from S3 should be written. That is, to retrieve a large resource, open a file, set the translation mode, and pass the channel as the value of the key outchan. Output will be written to the channel in pieces so memory does not fill up unnecessarily. The channel is not closed at the end of the transaction. @@ -347,85 +348,85 @@ This optional item, if provided, indicates that [cmd S3::REST] should run in non-blocking mode. The [arg varname] should be fully qualified with respect to namespaces and cannot be local to a proc. If provided, the result of the [cmd S3::REST] call is assigned to this variable once everything has completed; use trace or vwait to know when this has happened. -If this key is not provided, the result is simply returned from the +If this key is not provided, the result is simply returned from the call to [cmd S3::REST] and no calls to the eventloop are invoked from within this call. [def [opt "[option throwsocket] [arg throw|return]"]] This optional item, if provided, indicates that [cmd S3::REST] should throw an error if throwmode is throw and a socket error is encountered. -It indicates that [cmd S3::REST] should return the error code in the +It indicates that [cmd S3::REST] should return the error code in the returned dictionary if a socket error is encountered and this is set to return. If [option throwsocket] is set to [arg return] or -if the call is not blocking, then a socket error (i.e., an error +if the call is not blocking, then a socket error (i.e., an error whose error code starts with "S3 socket" will be returned in the dictionary as [option error], [option errorInfo], and [option errorCode]. If a foreground call is made (i.e., [option resultvar] is not provided), -and this option is not provided or is set to [arg throw], then +and this option is not provided or is set to [arg throw], then [cmd error] will be invoked instead. [list_end] [para] Once the call to [cmd S3::REST] completes, a new dict is returned, -either in the [arg resultvar] or as the result of execution. This dict is +either in the [arg resultvar] or as the result of execution. This dict is a copy of the original dict with the results added as new keys. The possible new keys are these: [list_begin definitions] [def "[option error] [arg errorstring]"] [def "[option errorInfo] [arg errorstring]"] [def "[option errorCode] [arg errorstring]"] If an error is caught, these three keys will be set in the result. -Note that [cmd S3::REST] does [emph not] consider a non-2XX HTTP +Note that [cmd S3::REST] does [emph not] consider a non-2XX HTTP return code as an error. The [option errorCode] value will be formatted according to the [sectref "ERROR REPORTING"] description. If these are present, other keys described here might not be. [def "[option httpstatus] [arg threedigits]"] -The three-digit code from the HTTP transaction. 2XX for good, +The three-digit code from the HTTP transaction. 2XX for good, 5XX for server error, etc. [def "[option httpmessage] [arg text]"] The textual result after the status code. "OK" or "Forbidden" or etc. [def "[option outbody] [arg contentstring]"] -If [arg outchan] was not specified, this key will hold a +If [arg outchan] was not specified, this key will hold a reference to the (unencoded) contents of the body returned. If Amazon returned an error (a la the httpstatus not a 2XX value), the error message will be in [option outbody] or written to [option outchan] as appropriate. [def "[option outheaders] [arg dict]"] This contains a dictionary of headers returned by Amazon. The keys are always lower case. It's mainly useful for finding the x-amz-meta-* headers, if any, although things -like last-modified and content-type are also useful. -The keys of this dictionary are always lower case. +like last-modified and content-type are also useful. +The keys of this dictionary are always lower case. Both keys and values are trimmed of extraneous whitespace. [list_end] [list_end] [section "HIGH LEVEL COMMANDS"] -The routines in this section all make use of one or more calls +The routines in this section all make use of one or more calls to [cmd S3::REST] to do their work, then parse and manage the data in a convenient way. All these commands throw errors as described in [sectref "ERROR REPORTING"] unless otherwise noted. [para] -In all these commands, all arguments are presented as name/value pairs, +In all these commands, all arguments are presented as name/value pairs, in any order. All the argument names start with a hyphen. [para] There are a few options that are common to many of the commands, and those common options are documented here. [list_begin definitions] [def "[option -blocking] [arg boolean]"] -If provided and specified as false, +If provided and specified as false, then any calls to [cmd S3:REST] will be non-blocking, and internally these routines will call [lb]vwait[rb] to get the results. In other words, these routines will return the same value, but they'll have event loops running while waiting for Amazon. @@ -445,15 +446,15 @@ command to list available buckets does not require this parameter.) This does not need to be URL-encoded, even if it contains special or non-ASCII characters. May or may not contain leading or trailing spaces - commands normalize the bucket. If this is not supplied, the value is taken from [cmd "S3::Configure -default-bucket"] -if that string isn't empty. Note that spaces and slashes are +if that string isn't empty. Note that spaces and slashes are always trimmed from both ends and the rest must leave a valid bucket. [def "[option -resource] [arg resourcename]"] -This specifies the resource of interest within the bucket. +This specifies the resource of interest within the bucket. It may or may not start with a slash - both cases are handled. This does not need to be URL-encoded, even if it contains special or non-ASCII characters. [def "[option -compare] [arg always|never|exists|missing|newer|date|checksum|different]"] @@ -471,14 +472,14 @@ [def [arg missing]] Copy the data only if the destination does not already exist. [def [arg newer]] -Copy the data if the destination is missing, or if the date on the source is -newer than the date on the destination by at -least [cmd "S3::Configure -slop-seconds"] seconds. If the source is -Amazon, the date is taken from the Last-Modified header. If the +Copy the data if the destination is missing, or if the date on the source is +newer than the date on the destination by at +least [cmd "S3::Configure -slop-seconds"] seconds. If the source is +Amazon, the date is taken from the Last-Modified header. If the source is local, it is taken as the mtime of the file. If the source data is specified in a string rather than a file, it is taken as right now, via [lb]clock seconds[rb]. [def [arg date]] @@ -489,24 +490,23 @@ of the resource, and copy the data if they're different. Copy the data also if the destination is missing. Note that this can be slow with large local files unless the C version of the MD5 support is available. [def [arg different]] -Copy the data if the destination does not exist. -If the destination exists and an actual file name was specified -(rather than a content string), +Copy the data if the destination does not exist. +If the destination exists and an actual file name was specified +(rather than a content string), and the date on the file differs from the date on the resource, -copy the data. -If the data is provided as a content string, the "date" is treated +copy the data. +If the data is provided as a content string, the "date" is treated as "right now", so it will likely always differ unless slop-seconds is large. If the dates are the same, the MD5 checksums are compared, and the data is copied if the checksums differ. [list_end] [para] Note that "newer" and "date" don't care about the contents, and "checksum" doesn't care about the dates, but "different" checks both. - [call [cmd S3::ListAllMyBuckets] \ [opt "[option -blocking] [arg boolean]"] \ [opt "[option -parse-xml] [arg xmlstring]"] \ [opt "[option -result-type] [arg REST|xml|pxml|dict|names|owner]"] \ @@ -514,14 +514,14 @@ This routine performs a GET on the Amazon S3 service, which is defined to return a list of buckets owned by the account identified by the authorization header. (Blame Amazon for the dumb names.) [list_begin definitions] -[def "[option -blocking] [arg boolean]"] +[def "[option -blocking] [arg boolean]"] See above for standard definition. -[def "[option -parse-xml] [arg xmlstring]"] +[def "[option -parse-xml] [arg xmlstring]"] See above for standard definition. [def "[option -result-type] [arg REST]"] The dictionary returned by [cmd S3::REST] is the return value of [cmd S3::ListAllMyBuckets]. In this case, a non-2XX httpstatus will not throw an error. You may not combine this with [arg -parse-xml]. @@ -536,11 +536,11 @@ [list_begin definitions] [def Owner/ID] The Amazon AWS ID (in hex) of the owner of the bucket. [def Owner/DisplayName] The Amazon AWS ID's Display Name. [def Bucket/Name] A list of names, one for each bucket. -[def Bucket/CreationDate] A list of dates, one for each bucket, +[def Bucket/CreationDate] A list of dates, one for each bucket, in the same order as Bucket/Name, in ISO format (as returned by Amazon). [list_end] [para] @@ -547,11 +547,11 @@ [def "[option -result-type] [arg names]"] A list of bucket names is returned with all other information stripped out. This is the default result type for this command. [def "[option -result-type] [arg owner]"] -A list containing two elements is returned. The first element is +A list containing two elements is returned. The first element is the owner's ID, and the second is the owner's display name. [list_end] [para] @@ -569,11 +569,11 @@ [opt "[option -bucket] [arg bucketname]"] \ [opt "[option -blocking] [arg boolean]"] \ ] This command deletes a bucket if it is empty and you have such permission. Note that Amazon's list of buckets is a global resource, requiring -far-flung synchronization. If you delete a bucket, it may be quite +far-flung synchronization. If you delete a bucket, it may be quite a few minutes (or hours) before you can recreate it, yielding "Conflict" errors until then. [call [cmd S3::GetBucket] \ [opt "[option -bucket] [arg bucketname]"] \ @@ -582,13 +582,13 @@ [opt "[option -max-count] [arg integer]"] \ [opt "[option -prefix] [arg prefixstring]" ] \ [opt "[option -delimiter] [arg delimiterstring]" ] \ [opt "[option -result-type] [arg REST|xml|pxml|names|dict]"] \ ] -This lists the contents of a bucket. That is, it returns a directory +This lists the contents of a bucket. That is, it returns a directory listing of resources within a bucket, rather than transfering any -user data. +user data. [list_begin definitions] [def "[option -bucket] [arg bucketname]"] The standard bucket argument. [def "[option -blocking] [arg boolean]"] The standard blocking argument. @@ -602,11 +602,11 @@ one call to [cmd S3::REST] will be made. Otherwise, enough calls will be made to exhaust the listing, buffering results in memory, so take care if you may have huge buckets. [def "[option -prefix] [arg prefixstring]"] -If present, restricts listing to resources with a particular prefix. One +If present, restricts listing to resources with a particular prefix. One leading / is stripped if present. [def "[option -delimiter] [arg delimiterstring]"] If present, specifies a delimiter for the listing. The presence of this will summarize multiple resources @@ -629,11 +629,11 @@ not specified, a list of all the bodies returned from the one or more calls to [cmd S3::REST] is returned. [def pxml] If [arg -max-count] is specified, the body returned -from [cmd S3::REST] is passed throught [cmd xsxp::parse] and then returned. +from [cmd S3::REST] is passed throught [cmd xsxp::parse] and then returned. If [arg -max-count] is not specified, a list of all the bodies returned from the one or more calls to [cmd S3::REST] are each passed through [cmd xsxp::parse] and then returned. @@ -656,14 +656,14 @@ [def IsTruncated] From the final call to [cmd S3::REST], so always false if [arg -max-count] is not specified. [def NextMarker] Always provided if IsTruncated is true, and calculated of Amazon does not provide it. May be empty if IsTruncated is false. -[def Key] A list of names of resources in the bucket matching the [arg -prefix] and [arg -delimiter] restrictions. +[def Key] A list of names of resources in the bucket matching the [arg -prefix] and [arg -delimiter] restrictions. [def LastModified] A list of times of resources in the bucket, in the same -order as Key, in the format returned by Amazon. (I.e., it is not parsed into +order as Key, in the format returned by Amazon. (I.e., it is not parsed into a seconds-from-epoch.) [def ETag] A list of entity tags (a.k.a. MD5 checksums) in the same order as Key. [def Size] A list of sizes in bytes of the resources, in the same order as Key. @@ -691,72 +691,72 @@ [opt "[option -x-amz-meta-*] [arg metadatatext]"] \ [opt "[option -compare] [arg comparemode]"] \ ] This command sends data to a resource on Amazon's servers for storage, -using the HTTP PUT command. It returns 0 if the [option -compare] mode +using the HTTP PUT command. It returns 0 if the [option -compare] mode prevented the transfer, 1 if the transfer worked, or throws an error -if the transfer was attempted but failed. +if the transfer was attempted but failed. Server 5XX errors and S3 socket errors are retried -according to [cmd "S3:Configure -retries"] settings before throwing an error; +according to [cmd "S3:Configure -retries"] settings before throwing an error; other errors throw immediately. [list_begin definitions] [def [option -bucket]] This specifies the bucket into which the resource will be written. Leading and/or trailing slashes are removed for you, as are spaces. [def [option -resource]] -This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. +This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. Spaces are not trimmed. [def [option -blocking]] The standard blocking flag. [def [option -file]] -If this is specified, the [arg filename] must exist, must be readable, +If this is specified, the [arg filename] must exist, must be readable, and must not be a special or directory file. [lb]file size[rb] must apply to it and must not change for the lifetime of the call. The default content-type is calculated based on the name and/or contents -of the file. Specifying this is an error if [option -content] is -also specified, but at least one of [option -file] or [option -content] must -be specified. (The file is allowed to not exist or not be readable if +of the file. Specifying this is an error if [option -content] is +also specified, but at least one of [option -file] or [option -content] must +be specified. (The file is allowed to not exist or not be readable if [option -compare] [arg never] is specified.) [def [option -content]] If this is specified, the [arg contentstring] is sent as the body of the resource. The content-type defaults to "application/octet-string". -Only the low bytes are sent, so non-ASCII should use the appropriate encoding -(such as [lb]encoding convertto utf-8[rb]) before passing it -to this routine, if necessary. Specifying this is an error if [option -file] -is also specified, but at least one of [option -file] or [option -content] must +Only the low bytes are sent, so non-ASCII should use the appropriate encoding +(such as [lb]encoding convertto utf-8[rb]) before passing it +to this routine, if necessary. Specifying this is an error if [option -file] +is also specified, but at least one of [option -file] or [option -content] must be specified. [def [option -acl]] This defaults to [cmd "S3::Configure -default-acl"] if not specified. It sets the x-amz-acl header on the PUT operation. If the value provided is [arg calc], the x-amz-acl header is calculated based on the I/O permissions of the file to be uploaded; it is an error to specify [arg calc] and [option -content]. If the value provided is [arg keep], the acl of the resource -is read before the PUT (or the default is used if the +is read before the PUT (or the default is used if the resource does not exist), then set back to what it -was after the PUT (if it existed). An error will occur if +was after the PUT (if it existed). An error will occur if the resource is successfully written but the kept ACL cannot -be then applied. This should never happen. -[emph Note:] [arg calc] is not currently fully implemented. +be then applied. This should never happen. +[emph Note:] [arg calc] is not currently fully implemented. [def [option -x-amz-meta-*]] -If any header starts with "-x-amz-meta-", its contents are added to the -PUT command to be stored as metadata with the resource. Again, no +If any header starts with "-x-amz-meta-", its contents are added to the +PUT command to be stored as metadata with the resource. Again, no encoding is performed, and the metadata should not contain characters like newlines, carriage returns, and so on. It is best to stick with -simple ASCII strings, or to fix the library in several places. +simple ASCII strings, or to fix the library in several places. [def [option -content-type]] -This overrides the content-type calculated by [option -file] or +This overrides the content-type calculated by [option -file] or sets the content-type for [option -content]. [def [option -compare]] This is the standard compare mode argument. [cmd S3::Put] returns 1 if the data was copied or 0 if the data was skipped due to @@ -775,15 +775,15 @@ [opt "[option -content] [arg contentvarname]"] \ [opt "[option -timestamp] [arg aws|now]"] \ [opt "[option -headers] [arg headervarname]"] \ ] This command retrieves data from a resource on Amazon's S3 servers, -using the HTTP GET command. It returns 0 if the [option -compare] mode +using the HTTP GET command. It returns 0 if the [option -compare] mode prevented the transfer, 1 if the transfer worked, or throws an error if the transfer was attempted but failed. Server 5XX errors and S3 socket errors are are retried -according to [cmd S3:Configure] settings before throwing an error; +according to [cmd S3:Configure] settings before throwing an error; other errors throw immediately. Note that this is always authenticated as the user configured in via [cmd "S3::Configure -accesskeyid"]. Use the Tcllib http for unauthenticated GETs. [list_begin definitions] @@ -790,43 +790,43 @@ [def [option -bucket]] This specifies the bucket from which the resource will be read. Leading and/or trailing slashes are removed for you, as are spaces. [def [option -resource]] -This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. +This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. Spaces are not trimmed. [def [option -blocking]] The standard blocking flag. [def [option -file]] -If this is specified, the body of the resource will be read into this file, -incrementally without pulling it entirely into memory first. The parent +If this is specified, the body of the resource will be read into this file, +incrementally without pulling it entirely into memory first. The parent directory must already exist. If the file already exists, it must be writable. If an error is thrown part-way through the process and the file already existed, it may be clobbered. If an error is thrown part-way through the process and the file did not already exist, any partial bits will be deleted. Specifying this is an error if [option -content] -is also specified, but at least one of [option -file] or [option -content] must +is also specified, but at least one of [option -file] or [option -content] must be specified. [def [option -timestamp]] This is only valid in conjunction with [option -file]. It may be specified as [arg now] or [arg aws]. The default is [arg now]. If [arg now], the file's modification date is left up to the system. If [arg aws], the file's mtime is set to match the Last-Modified header on the resource, synchronizing -the two appropriately for [option -compare] [arg date] or +the two appropriately for [option -compare] [arg date] or [option -compare] [arg newer]. [def [option -content]] If this is specified, the [arg contentvarname] is a variable in the caller's scope (not necessarily global) that receives the value of the body of the resource. No encoding is done, so if the resource (for example) represents a UTF-8 byte sequence, use [lb]encoding convertfrom utf-8[rb] to get a valid UTF-8 string. If this is specified, the [option -compare] is ignored unless -it is [arg never], in which case no assignment to [arg contentvarname] is +it is [arg never], in which case no assignment to [arg contentvarname] is performed. Specifying this is an error if [option -file] is also specified, but at least one of [option -file] or [option -content] must be specified. [def [option -compare]] This is the standard compare mode argument. [cmd S3::Get] returns @@ -864,30 +864,30 @@ [def [option -bucket]] This specifies the bucket from which the resource will be read. Leading and/or trailing slashes are removed for you, as are spaces. [def [option -resource]] -This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. +This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. Spaces are not trimmed. [def [option -blocking]] The standard blocking flag. [def [option -dict]] If specified, the resulting dictionary from the [cmd S3::REST] -call is assigned to the indicated (not necessarily global) variable +call is assigned to the indicated (not necessarily global) variable in the caller's scope. [def [option -headers]] If specified, the dictionary of headers from the result are assigned to the indicated (not necessarily global) variable in the caller's scope. [def [option -status]] -If specified, the indicated (not necessarily global) variable in +If specified, the indicated (not necessarily global) variable in the caller's scope is assigned a 2-element list. The first element is -the 3-digit HTTP status code, while the second element is +the 3-digit HTTP status code, while the second element is the HTTP message (such as "OK" or "Forbidden"). [list_end] [call [cmd S3::GetAcl] \ @@ -896,31 +896,31 @@ [option -resource] [arg resourcename] \ [opt "[option -result-type] [arg REST|xml|pxml]"] \ ] This command gets the ACL of the indicated resource or throws an -error if it is unavailable. +error if it is unavailable. [list_begin definitions] -[def "[option -blocking] [arg boolean]"] +[def "[option -blocking] [arg boolean]"] See above for standard definition. [def [option -bucket]] This specifies the bucket from which the resource will be read. Leading and/or trailing slashes are removed for you, as are spaces. [def [option -resource]] -This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. +This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. Spaces are not trimmed. [def "[option -parse-xml] [arg xml]"] The XML from a previous GetACL can be passed in to be parsed into dictionary form. In this case, -result-type must be pxml or dict. [def "[option -result-type] [arg REST]"] -The dictionary returned by [cmd S3::REST] is the return value of +The dictionary returned by [cmd S3::REST] is the return value of [cmd S3::GetAcl]. In this case, a non-2XX httpstatus will not throw an error. [def "[option -result-type] [arg xml]"] The raw XML of the body is returned as the result (with no encoding applied). @@ -927,11 +927,11 @@ [def "[option -result-type] [arg pxml]"] The XML of the body as parsed by [cmd xsxp::parse] is returned. [def "[option -result-type] [arg dict]"] -This fetches the ACL, parses it, and returns a dictionary of two elements. +This fetches the ACL, parses it, and returns a dictionary of two elements. [para] The first element has the key "owner" whose value is the canonical ID of the owner of the resource. @@ -955,35 +955,35 @@ ] This sets the ACL on the indicated resource. It returns the XML written to the ACL, or throws an error if anything went wrong. [list_begin definitions] -[def "[option -blocking] [arg boolean]"] +[def "[option -blocking] [arg boolean]"] See above for standard definition. [def [option -bucket]] This specifies the bucket from which the resource will be read. Leading and/or trailing slashes are removed for you, as are spaces. [def [option -resource]] -This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. +This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. Spaces are not trimmed. [def [option -owner]] If this is provided, it is assumed to match the owner of the resource. Otherwise, a GET may need to be issued against the resource to find -the owner. If you already have the owner (such as from a call +the owner. If you already have the owner (such as from a call to [cmd S3::GetAcl], you can pass the value of the "owner" key as the value of this option, and it will be used in the construction of the XML. [def [option -acl]] If this option is specified, it provides the ACL the caller wishes to write to the resource. If this is not supplied or is empty, the value is taken from [cmd "S3::Configure -default-acl"]. -The ACL is written with a PUT to the ?acl resource. +The ACL is written with a PUT to the ?acl resource. [para] If the value passed to this option starts with "<", it is taken to be a body to be PUT to the ACL resource. @@ -1000,11 +1000,11 @@ Otherwise, the value is assumed to be a dictionary formatted as the "acl" sub-entry within the dict returns by [cmd "S3::GetAcl -result-type dict"]. The proper XML is generated and applied to the resource. Note that a value containing "//" is assumed to be a group, a value containing "@" is assumed to be an AmazonCustomerByEmail, and otherwise the value is -assumed to be a canonical Amazon ID. +assumed to be a canonical Amazon ID. [para] Note that you cannot change the owner, so calling GetAcl on a resource owned by one user and applying it via PutAcl on a resource owned by @@ -1026,23 +1026,23 @@ [def [option -bucket]] This specifies the bucket from which the resource will be deleted. Leading and/or trailing slashes are removed for you, as are spaces. [def [option -resource]] -This is the full name of the resource within the bucket. A single -leading slash is removed, but not a trailing slash. +This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. Spaces are not trimmed. [def [option -blocking]] The standard blocking flag. [def [option -status]] -If specified, the indicated (not necessarily global) variable +If specified, the indicated (not necessarily global) variable in the caller's scope is set to a two-element list. The first element is the 3-digit HTTP status code. The second element is the HTTP message (such as "OK" or "Forbidden"). Note that -Amazon's DELETE result is 204 on success, that being the +Amazon's DELETE result is 204 on success, that being the code indicating no content in the returned body. [list_end] [para] @@ -1060,14 +1060,14 @@ ] This synchronises a local directory with a remote bucket by pushing the differences using [cmd S3::Put]. Note that if something has changed in the bucket but not locally, those changes could be lost. Thus, this is not a general -two-way synchronization primitive. (See [cmd S3::Sync] +two-way synchronization primitive. (See [cmd S3::Sync] for that.) Note too that resource names are case sensitive, so changing the case of a file on a Windows machine may lead -to otherwise-unnecessary transfers. +to otherwise-unnecessary transfers. Note that only regular files are considered, so devices, pipes, symlinks, and directories are not copied. [list_begin definitions] @@ -1080,14 +1080,14 @@ some of the files therein are readable, [cmd S3::Push] will PUT those files that are readable and return in its results the list of files that could not be opened. [def [option -prefix]] -This names the prefix that will be added to all resources. +This names the prefix that will be added to all resources. That is, it is the remote equivalent of [option -directory]. If it is not specified, the root of the bucket will be treated -as the remote directory. An example may clarify. +as the remote directory. An example may clarify. [example { S3::Push -bucket test -directory /tmp/xyz -prefix hello/world }] In this example, /tmp/xyz/pdq.html will be stored as http://s3.amazonaws.com/test/hello/world/pdq.html in Amazon's servers. Also, @@ -1099,11 +1099,11 @@ [def [option -blocking]] This is the standard blocking option. [def [option -compare]] If present, this is passed to each invocation of [cmd S3::Put]. -Naturally, [cmd "S3::Configure -default-compare"] is used +Naturally, [cmd "S3::Configure -default-compare"] is used if this is not specified. [def [option -x-amz-meta-*]] If present, this is passed to each invocation of [cmd S3::Put]. All copied files will have the same metadata. @@ -1121,11 +1121,11 @@ [def [option -error]] This controls the behavior of [cmd S3::Push] in the event that [cmd S3::Put] throws an error. Note that errors encountered on the local file system or in reading the list of resources in the remote bucket always throw errors. -This option allows control over "partial" errors, when some +This option allows control over "partial" errors, when some files were copied and some were not. [cmd S3::Delete] is always finished up, with errors simply recorded in the return result. [list_begin definitions] @@ -1138,11 +1138,11 @@ The calls to [cmd S3::Delete] are not started. [def continue] This is the default. Processing continues without throwing, recording the error in the return result, and resuming with the -next file in the local directory to be copied. +next file in the local directory to be copied. [list_end] [def [option -progress]] If this is specified and the indicated script prefix is not empty, the @@ -1162,46 +1162,46 @@ local list, the prefix will be invoked with [arg start] as the first additional argument and the common suffix as the second additional argument. When [cmd S3::Put] returns for that file, the prefix will be invoked with [arg copy] as the first additional argument, the common suffix as the second additional argument, and a third argument that will -be "copied" (if [cmd S3::Put] sent the resource), "skipped" (if +be "copied" (if [cmd S3::Put] sent the resource), "skipped" (if [cmd S3::Put] decided not to based on [option -compare]), or the errorCode that [cmd S3::Put] threw due to unexpected errors (in which case the third argument is a list that starts with "S3"). When all files have been transfered, the prefix may be invoked zero or more times with [arg delete] as the first additional argument and the suffix of the resource being deleted as the second additional argument, with a third argument being either an empty string (if the delete worked) or the errorCode from [cmd S3::Delete] if it failed. Finally, the prefix -will be invoked with [arg finished] as the first additional argument +will be invoked with [arg finished] as the first additional argument and the return value as the second additional argument. [list_end] -The return result from this command is a dictionary. They keys are the +The return result from this command is a dictionary. They keys are the suffixes (i.e., the common portion of the path after the [option -directory] and [option -prefix]), while the values are either "copied", "skipped" (if -[option -compare] indicated not to copy the file), or the errorCode +[option -compare] indicated not to copy the file), or the errorCode thrown by [cmd S3::Put], as appropriate. If [option -delete] was true, -there may also be entries for suffixes with the value "deleted" or -"notdeleted", indicating whether the attempted [cmd S3::Delete] +there may also be entries for suffixes with the value "deleted" or +"notdeleted", indicating whether the attempted [cmd S3::Delete] worked or not, respectively. There is one additional pair in the return result, whose key is the empty string and whose value is a nested dictionary. -The keys of this nested dictionary include "filescopied" (the number of +The keys of this nested dictionary include "filescopied" (the number of files successfully copied), "bytescopied" (the number of data bytes in -the files copied, excluding headers, metadata, etc), "compareskipped" (the +the files copied, excluding headers, metadata, etc), "compareskipped" (the number of files not copied due to [option -compare] mode), "errorskipped" (the number of files not copied due to thrown errors), "filesdeleted" (the number of resources deleted due to not having corresponding files -locally, or 0 if [option -delete] is false), and "filesnotdeleted" +locally, or 0 if [option -delete] is false), and "filesnotdeleted" (the number of resources whose deletion was attempted but failed). [para] Note that this is currently implemented somewhat inefficiently. It fetches the bucket listing (including timestamps and eTags), then calls [cmd S3::Put], which uses HEAD to find the timestamps -and eTags again. Correcting this with no API change +and eTags again. Correcting this with no API change is planned for a future upgrade. [para] [call [cmd S3::Pull] \ @@ -1214,26 +1214,26 @@ [opt "[option -timestamp] [arg aws|now]"] \ [opt "[option -error] [arg throw|break|continue]"] \ [opt "[option -progress] [arg scriptprefix]"] \ ] -This synchronises a remote bucket with a local directory by pulling the +This synchronises a remote bucket with a local directory by pulling the differences using [cmd S3::Get] If something has been changed locally but not -in the bucket, those difference may be lost. This is not a general two-way -synchronization mechanism. (See [cmd S3::Sync] for that.) +in the bucket, those difference may be lost. This is not a general two-way +synchronization mechanism. (See [cmd S3::Sync] for that.) This creates directories -if needed; new directories are created with default permissions. Note that -resource names are case sensitive, so changing the case of a file on a +if needed; new directories are created with default permissions. Note that +resource names are case sensitive, so changing the case of a file on a Windows machine may lead to otherwise-unnecessary transfers. Also, try not to store data in resources that end with a slash, or which are prefixes of resources that otherwise would start with a slash; i.e., don't use this if you store data in resources whose names have to be directories locally. [para] Note that this is currently implemented somewhat inefficiently. It fetches the bucket listing (including timestamps and eTags), then calls [cmd S3::Get], which uses HEAD to find the timestamps -and eTags again. Correcting this with no API change +and eTags again. Correcting this with no API change is planned for a future upgrade. [list_begin definitions] [def [option -bucket]] @@ -1240,27 +1240,27 @@ This names the bucket from which data will be pulled. [def [option -directory]] This names the local directory into which files will be written It must exist, be readable via [lb]glob[rb], writable for file creation, -and so on. If only some of the files therein are writable, +and so on. If only some of the files therein are writable, [cmd S3::Pull] will GET those files that are writable and return in its results the list of files that could not be opened. [def [option -prefix]] The prefix of resources that will be considered for retrieval. See [cmd S3::Push] for more details, examples, etc. (Of course, -[cmd S3::Pull] reads rather than writes, but the prefix is +[cmd S3::Pull] reads rather than writes, but the prefix is treated similarly.) [def [option -blocking]] This is the standard blocking option. [def [option -compare]] -This is passed to each invocation of [cmd S3::Get] if provided. -Naturally, [cmd "S3::Configure -default-compare"] is +This is passed to each invocation of [cmd S3::Get] if provided. +Naturally, [cmd "S3::Configure -default-compare"] is used if this is not provided. [def [option -timestamp]] This is passed to each invocation of [cmd S3::Get] if provided. @@ -1273,17 +1273,17 @@ [def [option -error]] See [cmd S3::Push] for a description of this option. [def [option -progress]] -See [cmd S3::Push] for a description of this option. +See [cmd S3::Push] for a description of this option. It differs slightly in that local directories may be included with a trailing slash to indicate they are directories. [list_end] -The return value from this command is a dictionary. It +The return value from this command is a dictionary. It is identical in form and meaning to the description of the return result of [cmd S3::Push]. It differs only in that directories may be included, with a trailing slash in their name, if they are empty and get deleted. @@ -1315,11 +1315,11 @@ [opt_def [option -error]] If this is "throw", [cmd S3::Toss] rethrows any errors it encounters. If this is "break", [cmd S3::Toss] returns with a normal return after the first error, recording that error in the return result. If this is "continue", which is -the default, [cmd S3::Toss] continues on and lists all +the default, [cmd S3::Toss] continues on and lists all errors in the return result. [opt_def [option -progress]] If this is specified and not an empty string, the script prefix will be invoked several times in the context of the caller @@ -1339,11 +1339,11 @@ The return value is a dictionary. The keys are the suffixes of files that [cmd S3::Toss] attempted to delete, and whose values are either the string "deleted" or "notdeleted". There is also one additional pair, whose key is the empty string and whose value is an embedded -dictionary. The keys of this embedded dictionary include +dictionary. The keys of this embedded dictionary include "filesdeleted" and "filesnotdeleted", each of which has integer values. [list_end] [section LIMITATIONS] @@ -1352,24 +1352,24 @@ [item] The pure-Tcl MD5 checking is slow. If you are processing files in the megabyte range, consider ensuring binary support is available. [item] The commands [cmd S3::Pull] and [cmd S3::Push] fetch a -directory listing which includes timestamps and MD5 hashes, +directory listing which includes timestamps and MD5 hashes, then invoke [cmd S3::Get] and [cmd S3::Put]. If -a complex [option -compare] mode is specified, [cmd S3::Get] and +a complex [option -compare] mode is specified, [cmd S3::Get] and [cmd S3::Put] will invoke a HEAD operation for each file to fetch timestamps and MD5 hashes of each resource again. It is expected that a future release of this package will solve this without any API changes. [item] The commands [cmd S3::Pull] and [cmd S3::Push] fetch a -directory listing without using [option -max-count]. The entire +directory listing without using [option -max-count]. The entire directory is pulled into memory at once. For very large buckets, this could be a performance problem. The author, at this time, does not plan to change this behavior. Welcome to Open Source. -[item] [cmd S3::Sync] is neither designed nor implemented yet. +[item] [cmd S3::Sync] is neither designed nor implemented yet. The intention would be to keep changes synchronised, so changes could be made to both the bucket and the local directory and be merged by [cmd S3::Sync]. [item] Nor is @@ -1378,22 +1378,22 @@ local files that are "public-read" or "public-read-write". Assistance figuring out TWAPI for this would be appreciated. The U**X semantics are difficult to map directly as well. See the source for details. Note that there are not tests for calc, since it isn't done yet. -[item] The HTTP processing is implemented within the library, +[item] The HTTP processing is implemented within the library, rather than using a "real" HTTP package. Hence, multi-line headers are not (yet) handled correctly. Do not include carriage returns or -linefeeds in x-amz-meta-* headers, content-type values, and so on. +linefeeds in x-amz-meta-* headers, content-type values, and so on. The author does not at this time expect to improve this. [item] Internally, [cmd S3::Push] and [cmd S3::Pull] and [cmd S3::Toss] are all very similar and should be refactored. -[item] The idea of using [option -compare] [arg never] -[option -delete] [arg true] to delete files that have been -deleted from one place but not the other yet not copying +[item] The idea of using [option -compare] [arg never] +[option -delete] [arg true] to delete files that have been +deleted from one place but not the other yet not copying changed files is untested. [list_end] [section "USAGE SUGGESTIONS"] @@ -1415,43 +1415,32 @@ [example_begin] S3::Pull -bucket sample -prefix of/interest -directory ./myfiles \ -compare never -delete true [example_end] - [section "FUTURE DEVELOPMENTS"] -The author intends to work on several additional projects related to +The author intends to work on several additional projects related to this package, in addition to finishing the unfinished features. [para] -First, a command-line program allowing browsing of buckets and +First, a command-line program allowing browsing of buckets and transfer of files from shell scripts and command prompts is useful. [para] Second, a GUI-based program allowing visual manipulation of bucket and resource trees not unlike Windows Explorer would be useful. -[para] +[para] Third, a command-line (and perhaps a GUI-based) program called -"OddJob" that will use S3 to synchronize computation amongst +"OddJob" that will use S3 to synchronize computation amongst multiple servers running OddJob. An S3 bucket will be set up with a number of scripts to run, and the OddJob program can be invoked on multiple machines to run scripts on all the machines, each moving on to the next unstarted task as it finishes each. This is still being designed, and it is intended primarily to be run on Amazon's Elastic Compute Cloud. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph amazon-s3] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY amazon-s3] +[include ../doctools2base/include/feedback.inc] [manpage_end] - Index: modules/amazon-s3/xsxp.man ================================================================== --- modules/amazon-s3/xsxp.man +++ modules/amazon-s3/xsxp.man @@ -1,23 +1,25 @@ [manpage_begin xsxp n 1.0] +[keywords dom] +[keywords parser] +[keywords xml] [moddesc {Amazon S3 Web Service Utilities}] [titledesc {eXtremely Simple Xml Parser}] [copyright {Copyright 2006 Darren New. All Rights Reserved.}] [category {Text processing}] [require Tcl 8.4] [require xml] -[keywords xml dom parser] [description] This package provides a simple interface to parse XML into a pure-value list. -It also provides accessor routines to pull out specific subtags, -not unlike DOM access. +It also provides accessor routines to pull out specific subtags, +not unlike DOM access. This package was written for and is used by Darren New's Amazon S3 access package. [para] This is pretty lame, but I needed something like this for S3, and at the time, TclDOM would not work with the new 8.5 Tcl -due to version number problems. +due to version number problems. [para] In addition, this is a pure-value implementation. There is no garbage to clean up in the event of a thrown error, for example. This simplifies the code for sufficiently small XML documents, which is what Amazon's S3 guarantees. @@ -24,18 +26,17 @@ [para] Copyright 2006 Darren New. All Rights Reserved. NO WARRANTIES OF ANY TYPE ARE PROVIDED. COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS. -This software is licensed under essentially the same +This software is licensed under essentially the same terms as Tcl. See LICENSE.txt for the terms. [section COMMANDS] The package implements five rather simple procedures. One parses, one is for debugging, and the rest pull various parts of the parsed document out for processing. - [list_begin definitions] [call [cmd xsxp::parse] [arg xml]] @@ -48,12 +49,12 @@ The second element is an array-get formatted list of key/value pairs. The keys are attribute names and the values are attribute values. This is an empty list if there are no attributes on the tag. [item] The third through end elements are the children of the node, if any. Each child is, recursively, a pxml. [item] Note that if the zero'th element, i.e. the tag name, is "%PCDATA", then -the attributes will be empty and the third element will be the text of the element. In addition, if an element's contents consists only of PCDATA, it will have only one child, and all the PCDATA will be concatenated. In other words, -this parser works poorly for XML with elements that contain both child tags and PCDATA. Since Amazon S3 does not do this (and for that matter most +the attributes will be empty and the third element will be the text of the element. In addition, if an element's contents consists only of PCDATA, it will have only one child, and all the PCDATA will be concatenated. In other words, +this parser works poorly for XML with elements that contain both child tags and PCDATA. Since Amazon S3 does not do this (and for that matter most uses of XML where XML is a poor choice don't do this), this is probably not a serious limitation. [list_end] [para] @@ -60,11 +61,11 @@ [call [cmd xsxp::fetch] [arg pxml] [arg path] [opt [arg part]]] [arg pxml] is a parsed XML, as returned from xsxp::parse. [arg path] is a list of element tag names. Each element is the name -of a child to look up, optionally followed by a +of a child to look up, optionally followed by a hash ("#") and a string of digits. An empty list or an initial empty element selects [arg pxml]. If no hash sign is present, the behavior is as if "#0" had been appended to that element. (In addition to a list, slashes can separate subparts where convenient.) [para] @@ -72,11 +73,11 @@ An element of [arg path] scans the children at the indicated level for the n'th instance of a child whose tag matches the part of the element before the hash sign. If an element is simply "#" followed by digits, that indexed child is selected, regardless of the tags in the children. Hence, an element of "#3" will always select -the fourth child of the node under consideration. +the fourth child of the node under consideration. [para] [arg part] defaults to "%ALL". It can be one of the following case-sensitive terms: [list_begin definitions] [def %ALL] returns the entire selected element. @@ -96,20 +97,20 @@ no PCDATA is found. [list_end] [para] -For example, to fetch the first bold text from the fifth paragraph of the body of your HTML file, +For example, to fetch the first bold text from the fifth paragraph of the body of your HTML file, [example {xsxp::fetch $pxml {html body p#4 b} %PCDATA}] [para] [call [cmd xsxp::fetchall] [arg pxml_list] [arg path] [opt [arg part]]] -This iterates over each PXML in [arg pxml_list] (which must be a list -of pxmls) selecting the indicated path from it, building a new list -with the selected data, and returning that new list. +This iterates over each PXML in [arg pxml_list] (which must be a list +of pxmls) selecting the indicated path from it, building a new list +with the selected data, and returning that new list. [para] For example, [arg pxml_list] might be the %CHILDREN of a particular element, and the [arg path] and [arg part] @@ -128,18 +129,8 @@ This outputs to [arg chan] (default stdout) a pretty-printed version of [arg pxml]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph amazon-s3] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY amazon-s3] +[include ../doctools2base/include/feedback.inc] [manpage_end] - Index: modules/asn/asn.man ================================================================== --- modules/asn/asn.man +++ modules/asn/asn.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin asn n 0.8] +[keywords asn] +[keywords ber] +[keywords cer] +[keywords der] +[keywords internet] +[keywords protocol] +[keywords x.208] +[keywords x.209] [copyright {2004 Andreas Kupries }] [copyright {2004 Jochen Loewer }] [copyright {2004-2011 Michael Schlenker }] [moddesc {ASN.1 processing}] [category Networking] @@ -31,11 +39,10 @@ [emph {A Layman's Guide to a Subset of ASN.1, BER, and DER}], an RSA Laboratories Technical Note by Burton S. Kaliski Jr. (Revised November 1, 1993). A text version of this note is part of the module sources and should be read by any implementor. - [section {PUBLIC API}] [subsection ENCODER] [list_begin definitions] @@ -62,128 +69,108 @@ [call [cmd ::asn::asnApplicationConstr] [arg appNumber] [arg evalue]...] Takes zero or more encoded values, packs them into an ASN application construct and returns its encoded binary form. - [call [cmd ::asn::asnApplication] [arg appNumber] [arg data]] Takes a single encoded value [arg data], packs it into an ASN application construct and returns its encoded binary form. - [call [cmd ::asn::asnChoice] [arg appNumber] [arg evalue]...] Takes zero or more encoded values, packs them into an ASN choice construct and returns its encoded binary form. - [call [cmd ::asn::asnChoiceConstr] [arg appNumber] [arg evalue]...] Takes zero or more encoded values, packs them into an ASN choice construct and returns its encoded binary form. - [call [cmd ::asn::asnInteger] [arg number]] Returns the encoded form of the specified integer [arg number]. - [call [cmd ::asn::asnEnumeration] [arg number]] Returns the encoded form of the specified enumeration id [arg number]. - [call [cmd ::asn::asnBoolean] [arg bool]] Returns the encoded form of the specified boolean value [arg bool]. - [call [cmd ::asn::asnContext] [arg context] [arg data]] Takes an encoded value and packs it into a constructed value with application tag, the [arg context] number. - [call [cmd ::asn::asnContextConstr] [arg context] [arg evalue]...] Takes zero or more encoded values and packs them into a constructed value with application tag, the [arg context] number. - [call [cmd ::asn::asnObjectIdentifier] [arg idlist]] Takes a list of at least 2 integers describing an object identifier (OID) value, and returns the encoded value. - [call [cmd ::asn::asnUTCTime] [arg utcstring]] Returns the encoded form of the specified UTC time string. - [call [cmd ::asn::asnNull]] Returns the NULL encoding. - [call [cmd ::asn::asnBitString] [arg string]] Returns the encoded form of the specified [arg string]. - [call [cmd ::asn::asnOctetString] [arg string]] Returns the encoded form of the specified [arg string]. - [call [cmd ::asn::asnNumericString] [arg string]] Returns the [arg string] encoded as ASN.1 NumericString. Raises an error if the [arg string] contains characters other than decimal numbers and space. - -[call [cmd ::asn::asnPrintableString] [arg string]] +[call [cmd ::asn::asnPrintableString] [arg string]] Returns the [arg string] encoding as ASN.1 PrintableString. Raises an error if the [arg string] contains characters which are not allowed by the Printable String datatype. The allowed characters are A-Z, a-z, 0-9, space, apostrophe, colon, parentheses, plus, minus, comma, period, forward slash, question mark, and the equals sign. - [call [cmd ::asn::asnIA5String] [arg string]] Returns the [arg string] encoded as ASN.1 IA5String. Raises an error if the [arg string] contains any characters outside of the US-ASCII range. - [call [cmd ::asn::asnBMPString] [arg string]] Returns the [arg string] encoded as ASN.1 Basic Multilingual Plane string (Which is essentialy big-endian UCS2). - [call [cmd ::asn::asnUTF8String] [arg string]] Returns the [arg string] encoded as UTF8 String. Note that some legacy applications such as Windows CryptoAPI do not like UTF8 strings. Use BMPStrings if you are not sure. - [call [cmd ::asn::asnString] [arg string]] Returns an encoded form of [arg string], choosing the most restricted ASN.1 string type possible. If the string contains non-ASCII characters, then there is more than one string type which can be used. See [cmd ::asn::defaultStringType]. - [call [cmd ::asn::defaultStringType] [opt [arg type]]] Selects the string type to use for the encoding of non-ASCII strings. Returns current default when called without argument. If the @@ -212,11 +199,10 @@ arguments refer to the same variable, it will always contain the extracted value after the call, and not the remainder of the input. [list_end] - [para] [list_begin definitions] [call [cmd ::asn::asnPeekByte] [arg data_var] [arg byte_var]] Retrieve the first byte of the data, without modifing [arg data_var]. @@ -225,44 +211,38 @@ [call [cmd ::asn::asnGetLength] [arg data_var] [arg length_var]] Decode the length information for a block of BER data. The tag has already to be removed from the data. - - [call [cmd ::asn::asnGetResponse] [arg chan] [arg data_var]] Reads an encoded ASN [emph sequence] from the channel [arg chan] and stores it into the variable named by [arg data_var]. - [call [cmd ::asn::asnGetInteger] [arg data_var] [arg int_var]] Assumes that an encoded integer value is at the front of the data stored in the variable named [arg data_var], extracts and stores it into the variable named by [arg int_var]. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetEnumeration] [arg data_var] [arg enum_var]] Assumes that an enumeration id is at the front of the data stored in the variable named [arg data_var], and stores it into the variable named by [arg enum_var]. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetOctetString] [arg data_var] [arg string_var]] Assumes that a string is at the front of the data stored in the variable named [arg data_var], and stores it into the variable named by [arg string_var]. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetString] [arg data_var] [arg string_var] [opt [arg type_var]]] Decodes a user-readable string. This is a convenience function which is able to automatically distinguish all supported ASN.1 string types @@ -285,37 +265,33 @@ create the appropriate function "asn::asnGetSome[var UnsupportedString]" in your application if neccessary. - [call [cmd ::asn::asnGetNumericString] [arg data_var] [arg string_var]] Assumes that a numeric string value is at the front of the data stored in the variable named [arg data_var], and stores it into the variable named by [arg string_var]. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetPrintableString] [arg data_var] [arg string_var]] Assumes that a printable string value is at the front of the data stored in the variable named [arg data_var], and stores it into the variable named by [arg string_var]. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetIA5String] [arg data_var] [arg string_var]] Assumes that a IA5 (ASCII) string value is at the front of the data stored in the variable named [arg data_var], and stores it into the variable named by [arg string_var]. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetBMPString] [arg data_var] [arg string_var]] Assumes that a BMP (two-byte unicode) string value is at the front of the data stored in the variable named [arg data_var], and stores it @@ -322,66 +298,59 @@ into the variable named by [arg string_var], converting it into a proper Tcl string. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetUTF8String] [arg data_var] [arg string_var]] Assumes that a UTF8 string value is at the front of the data stored in the variable named [arg data_var], and stores it into the variable named by [arg string_var], converting it into a proper Tcl string. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetUTCTime] [arg data_var] [arg utc_var]] Assumes that a UTC time value is at the front of the data stored in the -variable named [arg data_var], and stores it into the variable named +variable named [arg data_var], and stores it into the variable named by [arg utc_var]. The UTC time value is stored as a string, which has to be decoded with the usual clock scan commands. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetBitString] [arg data_var] [arg bits_var]] Assumes that a bit string value is at the front of the data stored in the -variable named [arg data_var], and stores it into the variable named +variable named [arg data_var], and stores it into the variable named by [arg bits_var] as a string containing only 0 and 1. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetObjectIdentifier] [arg data_var] [arg oid_var]] -Assumes that a object identifier (OID) value is at the front of the data -stored in the variable named [arg data_var], and stores it into the variable -named by [arg oid_var] as a list of integers. +Assumes that a object identifier (OID) value is at the front of the data +stored in the variable named [arg data_var], and stores it into the variable +named by [arg oid_var] as a list of integers. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetBoolean] [arg data_var] [arg bool_var]] Assumes that a boolean value is at the front of the data stored in the -variable named [arg data_var], and stores it into the variable named +variable named [arg data_var], and stores it into the variable named by [arg bool_var]. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands. - [call [cmd ::asn::asnGetNull] [arg data_var]] Assumes that a NULL value is at the front of the data stored in the variable named [arg data_var] and removes the bytes used to encode it from the data. - [call [cmd ::asn::asnGetSequence] [arg data_var] [arg sequence_var]] Assumes that an ASN sequence is at the front of the data stored in the variable named [arg data_var], and stores it into the variable named @@ -393,11 +362,10 @@ The data in [arg sequence_var] is encoded binary and has to be further decoded according to the definition of the sequence, using the decoder commands here. - [call [cmd ::asn::asnGetSet] [arg data_var] [arg set_var]] Assumes that an ASN set is at the front of the data stored in the variable named [arg data_var], and stores it into the variable named by [arg set_var]. Additionally removes all bytes associated with the @@ -407,11 +375,10 @@ [para] The data in [arg set_var] is encoded binary and has to be further decoded according to the definition of the set, using the decoder commands here. - [call [cmd ::asn::asnGetApplication] [arg data_var] [arg appNumber_var] [opt [arg content_var]] [opt [arg encodingType_var]]] Assumes that an ASN application construct is at the front of the data stored in the variable named [arg data_var], and stores its id into @@ -430,12 +397,11 @@ Otherwise it is the responsibility of the caller to decode the remainder of the application construct based on the id retrieved by this command, using the decoder commands of this package. - -[call [cmd ::asn::asnGetContext] [arg data_var] [arg contextNumber_var] [opt [arg content_var]] [opt [arg encodingType_var]]] +[call [cmd ::asn::asnGetContext] [arg data_var] [arg contextNumber_var] [opt [arg content_var]] [opt [arg encodingType_var]]] Assumes that an ASN context tag construct is at the front of the data stored in the variable named [arg data_var], and stores its id into the variable named by [arg contextNumber_var]. Additionally removes all bytes associated with the value from the data for further processing @@ -477,35 +443,22 @@ [call [cmd ::asn::asnTag] [arg tagnumber] [opt [arg class]] [opt [arg tagstyle]]] The [cmd ::asn::asnTag] can be used to create a tag value. The [arg tagnumber] gives the number of the tag, while the [arg class] gives one of the classes (UNIVERSAL,CONTEXT,APPLICATION or PRIVATE). The class may be abbreviated to just the first letter (U,C,A,P), -default is UNIVERSAL. +default is UNIVERSAL. The [arg tagstyle] is either C for Constructed encoding, or P for primitve encoding. It defaults to P. You can also use 1 instead of C and 0 instead of P for direct use of the values returned by [cmd ::asn::asnPeekTag]. [call [cmd ::asn::asnRetag] [arg data_var] [arg newTag]] Replaces the tag in front of the data in [arg data_var] with [arg newTag]. The new Tag can be created using the [cmd ::asn::asnTag] command. [list_end] - - [section EXAMPLES] Examples for the usage of this package can be found in the implementation of package [package ldap]. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph asn] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords asn x.208 ber x.209 der cer internet protocol] +[vset CATEGORY asn] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/base32/base32.man ================================================================== --- modules/base32/base32.man +++ modules/base32/base32.man @@ -1,16 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin base32 n 0.1] +[keywords base32] +[keywords rfc3548] [copyright {Public domain}] [moddesc {Base32 encoding}] [titledesc {base32 standard encoding}] [category {Text processing}] [require Tcl 8.4] [require base32::core [opt 0.1]] [require base32 [opt 0.1]] [description] -[keywords base32 rfc3548] [para] This package provides commands for encoding and decoding of strings into and out of the standard base32 encoding as specified in RFC 3548. @@ -47,11 +48,10 @@ [enum] padding appears not at the end of input, but in the middle, [enum] the padding has not of length six, four, three, or one characters, [list_end] [list_end] - [section {Code map}] The code map used to convert 5-bit sequences is shown below, with the numeric id of the bit sequences to the left and the character used to encode it to the right. It should be noted that the characters "0" and @@ -68,18 +68,8 @@ 6 G 15 P 24 Y 7 H 16 Q 25 Z 8 I 17 R 26 2 }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph base32] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY base32] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/base32/base32core.man ================================================================== --- modules/base32/base32core.man +++ modules/base32/base32core.man @@ -1,15 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin base32::core n 0.1] +[keywords base32] [copyright {Public domain}] [moddesc {Base32 encoding}] [titledesc {Expanding basic base32 maps}] [category {Text processing}] [require Tcl 8.4] [require base32::core [opt 0.1]] [description] -[keywords base32] [para] This package provides generic commands for the construction of full base32 mappings from a basic mapping listing just the codes and associated characters. The full mappings, regular and inverse, created @@ -20,11 +20,10 @@ This is in essence an internal package to be used by implementors of a base32 en- and decoder. A regular user has no need of this package at all. - [section API] [list_begin definitions] [call [cmd ::base32::core::define] [arg map] [arg forwvar] [arg backwvar] [arg ivar]] @@ -32,11 +31,10 @@ This command computes full forward and backward (inverse) mappings from the basic [arg map] and stores them in the variables named by [arg forwvar] and [arg backwvar] resp. It also constructs a regexp pattern for the detection of invalid characters in supposedly base32 encoded input and stores it in the variable named by [arg ivar]. - [call [cmd ::base32::core::valid] [arg string] [arg pattern] [arg mvar]] This command checks if the input [arg string] is a valid base32 encoded string, based on the [arg pattern] of invalid characters as @@ -61,18 +59,8 @@ [enum] The padding appears not at the end of input, but in the middle, [enum] The padding has not of length six, four, three, or one characters, [list_end] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph base32] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY base32] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/base32/base32hex.man ================================================================== --- modules/base32/base32hex.man +++ modules/base32/base32hex.man @@ -1,16 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin base32::hex n 0.1] +[keywords base32] +[keywords hex] +[keywords rfc3548] [copyright {Public domain}] [moddesc {Base32 encoding}] [titledesc {base32 extended hex encoding}] [category {Text processing}] [require Tcl 8.4] [require base32::core [opt 0.1]] [require base32::hex [opt 0.1]] [description] -[keywords base32 rfc3548 hex] [para] This package provides commands for encoding and decoding of strings into and out of the extended hex base32 encoding as specified in the RFC 3548bis draft. @@ -49,11 +51,10 @@ [enum] padding appears not at the end of input, but in the middle, [enum] the padding has not of length six, four, three, or one characters, [list_end] [list_end] - [section {Code map}] The code map used to convert 5-bit sequences is shown below, with the numeric id of the bit sequences to the left and the character used to encode it to the right. The important feature of the extended hex @@ -70,18 +71,8 @@ 6 6 15 F 24 O 7 7 16 G 25 P 8 8 17 H 26 Q }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph base32] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY base32] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/base64/ascii85.man ================================================================== --- modules/base64/ascii85.man +++ modules/base64/ascii85.man @@ -1,6 +1,8 @@ [manpage_begin ascii85 n 1.0] +[keywords ascii85] +[keywords encoding] [copyright "2010, Emiliano Gavil\u00e1n"] [moddesc {Text encoding & decoding binary data}] [titledesc {ascii85-encode/decode binary data}] [category {Text processing}] [require Tcl 8.4] @@ -26,11 +28,10 @@ [para] The command will throw an error for negative values of [arg maxlen], or if [arg maxlen] is not an integer number. - [call [cmd ::ascii85::decode] [arg "string"]] Ascii85 decodes the given [arg "string"] and returns the binary data. The decoder ignores whitespace in the string, as well as tabs and @@ -67,19 +68,8 @@ [enum] [uri http://en.wikipedia.org/wiki/Ascii85] [enum] Postscript Language Reference Manual, 3rd Edition, page 131. [uri http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph base64] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords encoding ascii85] +[vset CATEGORY base64] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/base64/base64.man ================================================================== --- modules/base64/base64.man +++ modules/base64/base64.man @@ -1,6 +1,8 @@ [manpage_begin base64 n 2.4.2] +[keywords base64] +[keywords encoding] [copyright {2000, Eric Melski}] [copyright {2001, Miguel Sofer}] [moddesc {Text encoding & decoding binary data}] [titledesc {base64-encode/decode binary data}] [category {Text processing}] @@ -31,11 +33,10 @@ [para] The command will throw an error for negative values of [arg maxlen], or if [arg maxlen] is not an integer number. - [call [cmd ::base64::decode] [arg "string"]] Base64 decodes the given [arg "string"] and returns the binary data. The decoder ignores whitespace in the string. @@ -62,20 +63,8 @@ % set encoded [base64::encode $chemical] Q+KCiEjigoHigoBO4oKET+KCgg== % set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]] }] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph base64] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords encoding base64] +[vset CATEGORY base64] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/base64/uuencode.man ================================================================== --- modules/base64/uuencode.man +++ modules/base64/uuencode.man @@ -1,6 +1,8 @@ [manpage_begin uuencode n 1.1.4] +[keywords encoding] +[keywords uuencode] [copyright {2002, Pat Thoyts}] [moddesc {Text encoding & decoding binary data}] [titledesc {UU-encode/decode binary data}] [category {Text processing}] [require Tcl 8] @@ -88,19 +90,8 @@ [example { % uuencode::uudecode $d {hello.txt 644 {Hello World}} }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph base64] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords encoding uuencode] +[vset CATEGORY base64] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/base64/yencode.man ================================================================== --- modules/base64/yencode.man +++ modules/base64/yencode.man @@ -1,6 +1,10 @@ [manpage_begin yencode n 1.1.2] +[keywords encoding] +[keywords ydecode] +[keywords yEnc] +[keywords yencode] [copyright {2002, Pat Thoyts}] [moddesc {Text encoding & decoding binary data}] [titledesc {Y-encode/decode binary data}] [category {Text processing}] [require Tcl 8.2] @@ -10,11 +14,11 @@ This package provides a Tcl-only implementation of the yEnc file encoding. This is a recently introduced method of encoding binary files for transmission through Usenet. This encoding packs binary data into a format that requires an 8-bit clean transmission layer but that -escapes characters special to the [term NNTP] posting protocols. See +escapes characters special to the [term NNTP] posting protocols. See [uri http://www.yenc.org/] for details concerning the algorithm. [list_begin definitions] [call [cmd ::yencode::encode] [arg string]] @@ -85,19 +89,8 @@ [list_begin enum] [enum] [uri http://www.yenc.org/yenc-draft.1.3.txt] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph base64] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords encoding yEnc yencode ydecode] +[vset CATEGORY base64] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bee/bee.man ================================================================== --- modules/bee/bee.man +++ modules/bee/bee.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bee n 0.1] +[keywords bee] +[keywords BitTorrent] +[keywords bittorrent] +[keywords serialization] +[keywords torrent] [copyright {2004 Andreas Kupries }] [moddesc {BitTorrent}] [titledesc {BitTorrent Serialization Format Encoder/Decoder}] [category Networking] [require Tcl 8.4] @@ -29,15 +34,13 @@ [call [cmd ::bee::encodeString] [arg string]] Returns the bee-encoding of the [arg string]. - [call [cmd ::bee::encodeNumber] [arg integer]] Returns the bee-encoding of the [arg integer] number. - [call [cmd ::bee::encodeListArgs] [arg value]...] Takes zero or more bee-encoded values and returns the bee-encoding of their list. @@ -45,38 +48,34 @@ [call [cmd ::bee::encodeList] [arg list]] Takes a list of bee-encoded values and returns the bee-encoding of the list. - [call [cmd ::bee::encodeDictArgs] [arg key] [arg value]...] Takes zero or more pairs of keys and values and returns the bee-encoding of the dictionary they form. The values are expected to be already bee-encoded, but the keys must not be. Their encoding will be done by the command itself. - [call [cmd ::bee::encodeDict] [arg dict]] Takes a dictionary list of string keys and bee-encoded values and returns the bee-encoding of the list. Note that the keys in the input must not be bee-encoded already. This will be done by the command -itself. +itself. [list_end] [para] - [subsection DECODER] The package provides two main decoder commands, one for decoding a string expected to contain a complete data structure, the other for the incremental decoding of bee-values arriving on a channel. The latter command is asynchronous and provides the completed decoded values to the user through a command callback. - [para] [list_begin definitions] [call [cmd ::bee::decode] [arg string] [opt [arg endvar]] [opt [arg start]]] @@ -99,11 +98,10 @@ [para] The optional [arg start] index defaults to [const 0], i.e. the beginning of the string. It is the index of the first character of the bee-encoded value to extract. - [call [cmd ::bee::decodeIndices] [arg string] [opt [arg endvar]] [opt [arg start]]] Takes the same arguments as [cmd ::bee::decode] and returns the same information in [arg endvar]. The result however is different. Instead @@ -168,11 +166,10 @@ find particular element. Using the actual keys makes this much easier. [list_end] [para] - [call [cmd ::bee::decodeChannel] [arg chan] \ [option -command] [arg cmdprefix] \ [opt [option -exact]] \ [opt "[option -prefix] [arg data]"] \ ] @@ -202,18 +199,16 @@ The decoder has reached eof on the channel [arg chan]. No further invocations of the callback will be made after this. The channel has already been closed at the time of the call, and the [arg token] is not valid anymore as well. - [call [cmd cmdprefix] [method error] [arg token] [arg message]] The decoder encountered an error, which is not eof. For example a malformed bee-value. The [arg message] provides details about the error. The decoder token is in the same state as for eof, i.e. invalid. The channel however is kept open. - [call [cmd cmdprefix] [method value] [arg token] [arg value]] The decoder received and successfully decoded a bee-value. @@ -256,11 +251,10 @@ [call [cmd ::bee::decodeCancel] [arg token]] This command cancels the decoder set up by [cmd ::bee::decodeChannel] and represented by the handle [arg token]. - [call [cmd ::bee::decodePush] [arg token] [arg string]] This command appends the [arg string] to the internal decoder buffer. It is the runtime equivalent of the option [option -prefix] of @@ -340,22 +334,10 @@ By wrapping an integer number into [const i]...[const e] the format makes sure that they are different from strings, which all begin with a digit. - [section EXAMPLES] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph bee] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords bee bittorrent serialization torrent BitTorrent] +[vset CATEGORY bee] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bench/bench.man ================================================================== --- modules/bench/bench.man +++ modules/bench/bench.man @@ -1,7 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bench n 0.4] +[see_also bench_intro] +[see_also bench_lang_intro] +[see_also bench_lang_spec] +[see_also bench_read] +[see_also bench_wcsv] +[see_also bench_wtext] +[keywords benchmark] +[keywords merging] +[keywords normalization] +[keywords performance] +[keywords testing] [copyright {2007-2008 Andreas Kupries }] [moddesc {Benchmarking/Performance tools}] [titledesc {bench - Processing benchmark suites}] [category {Benchmark tools}] [require Tcl 8.2] @@ -144,11 +155,10 @@ The benchmark results are in the format described in section [sectref {Result format}]. [para] The column is identified by an integer number. - [call [cmd ::bench::edit] [arg bench_result] [arg column] [arg newvalue]] This command renames a column in the specified benchmark result and returns the modified result. This means that the path of the Tcl interpreter in the identified column is changed to an arbitrary @@ -158,21 +168,18 @@ The benchmark results are in the format described in section [sectref {Result format}]. [para] The column is identified by an integer number. - [call [cmd ::bench::merge] [arg bench_result]...] This commands takes one or more benchmark results, merges them into one big result, and returns that as its result. [para] All benchmark results are in the format described in section [sectref {Result format}]. - - [call [cmd ::bench::norm] [arg bench_result] [arg column]] This command normalizes the timing results in the specified benchmark result and returns the modified result. This means that the cell @@ -195,12 +202,10 @@ [para] The benchmark results are in the format described in section [sectref {Result format}]. [para] The column is identified by an integer number. - - [call [cmd ::bench::out::raw] [arg bench_result]] This command formats the specified benchmark result for output to a file, socket, etc. This specific command does no formatting at all, @@ -284,26 +289,8 @@ not match the declared expectations. [list_end] [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph bench] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also bench_intro] -[see_also bench_lang_intro] -[see_also bench_lang_spec] -[see_also bench_wtext] -[see_also bench_wcsv] -[see_also bench_read] -[keywords testing performance benchmark merging normalization] +[vset CATEGORY bench] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bench/bench_intro.man ================================================================== --- modules/bench/bench_intro.man +++ modules/bench/bench_intro.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bench_intro n 1.0] +[see_also bench] +[see_also bench_lang_faq] +[see_also bench_lang_intro] +[see_also bench_lang_spec] +[keywords {bench language}] +[keywords benchmark] +[keywords performance] +[keywords testing] [copyright {2007 Andreas Kupries }] [moddesc {Benchmarking/Performance tools}] [titledesc {bench introduction}] [category {Benchmark tools}] [description] @@ -70,28 +78,14 @@ basic facilities to read and execute files containing benchmarks written in the bench language, and to manipulate benchmark results. [list_end] - [section {HISTORICAL NOTES}] This module and package have been derived from Jeff Hobbs' [syscmd tclbench] application for the benchmarking of the Tcl core and its ancestor [file runbench.tcl]. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph bench] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also bench_lang_intro] -[see_also bench_lang_spec] -[see_also bench_lang_faq] -[see_also bench] -[keywords testing performance benchmark {bench language}] +[vset CATEGORY bench] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bench/bench_lang_intro.man ================================================================== --- modules/bench/bench_lang_intro.man +++ modules/bench/bench_lang_intro.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bench_lang_intro n 1.0] +[see_also bench_intro] +[see_also bench_lang_spec] +[keywords {bench language}] +[keywords benchmark] +[keywords examples] +[keywords performance] +[keywords testing] [copyright {2007 Andreas Kupries }] [moddesc {Benchmarking/Performance tools}] [titledesc {bench language introduction}] [category {Benchmark tools}] [description] @@ -35,11 +42,10 @@ This code declares a benchmark named [const LABEL] which measures the time it takes to assign a value to a variable. The Tcl code doing this assignment is the [option -body] of the benchmark. - [subsection {Pre- and postprocessing}] Our next example demonstrates how to declare [term initialization] and [term cleanup] code, i.e. code computing information for the use of the [option -body], and for releasing such resources after the @@ -61,11 +67,10 @@ aes::Encrypt $key $p } [option -post] { aes::Final $key } [example_end] - [subsection {Advanced pre- and postprocessing}] Our last example again deals with initialization and cleanup code. To see the difference to the regular initialization and cleanup discussed @@ -131,11 +136,10 @@ } [option -ipost] { unset A B } [example_end] - [section {FURTHER READING}] Now that this document has been digested the reader, assumed to be a [term writer] of benchmarks, he should be fortified enough to be able to understand the formal [term {bench language specfication}]. It will @@ -142,18 +146,8 @@ also serve as the detailed specification and cheat sheet for all available commands and their syntax. [para] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph bench] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also bench_intro] -[see_also bench_lang_spec] -[keywords testing performance benchmark {bench language} examples] +[vset CATEGORY bench] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bench/bench_lang_spec.man ================================================================== --- modules/bench/bench_lang_spec.man +++ modules/bench/bench_lang_spec.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bench_lang_spec n 1.0] +[see_also bench_intro] +[see_also bench_lang_intro] +[keywords {bench language}] +[keywords benchmark] +[keywords performance] +[keywords specification] +[keywords testing] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {bench language specification}] [category {Benchmark tools}] [description] @@ -14,11 +21,10 @@ in alphabetical order, and the descriptions are relatively short. A beginner should read the more informally written [term {bench language introduction}] first. - [section Commands] [list_begin definitions] [call [cmd bench_rm] [arg path]...] @@ -26,11 +32,10 @@ then returns the empty string as its result. The command is [emph trusted], there is no checking if the specified files are outside of whatever restricted area the benchmarks are run in. - [call [cmd bench_tmpfile]] This command returns the path to a bench specific unique temporary file. The uniqueness means that multiple calls will return different @@ -48,11 +53,10 @@ [var \$TEMP] [def {Anything else}] The current working directory. [list_end] [para] - [call [cmd bench] [arg options]...] This command declares a single benchmark. Its result is the empty string. All parts of the benchmark are declared via options, and their @@ -121,20 +125,8 @@ to run without failing. [list_end] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph bench] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also bench_intro] -[see_also bench_lang_intro] -[keywords testing performance benchmark {bench language} specification] +[vset CATEGORY bench] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bench/bench_read.man ================================================================== --- modules/bench/bench_read.man +++ modules/bench/bench_read.man @@ -1,7 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bench::in n 0.1] +[see_also bench] +[see_also bench::out::csv] +[see_also bench::out::text] +[see_also bench_intro] +[keywords benchmark] +[keywords csv] +[keywords formatting] +[keywords {human readable}] +[keywords parsing] +[keywords performance] +[keywords reading] +[keywords testing] +[keywords text] [copyright {2007 Andreas Kupries }] [moddesc {Benchmarking/Performance tools}] [titledesc {bench::in - Reading benchmark results}] [category {Benchmark tools}] [require Tcl 8.2] @@ -45,25 +58,8 @@ and automatically detects which format is used by the input file. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph bench] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also bench_intro] -[see_also bench] -[see_also bench::out::csv] -[see_also bench::out::text] -[keywords testing performance benchmark formatting csv text {human readable}] -[keywords reading parsing] +[vset CATEGORY bench] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bench/bench_wcsv.man ================================================================== --- modules/bench/bench_wcsv.man +++ modules/bench/bench_wcsv.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bench::out::csv n 0.1.2] +[see_also bench] +[see_also bench::out::text] +[keywords benchmark] +[keywords csv] +[keywords formatting] +[keywords performance] +[keywords testing] [copyright {2007 Andreas Kupries }] [moddesc {Benchmarking/Performance tools}] [titledesc {bench::out::csv - Formatting benchmark results as CSV}] [category {Benchmark tools}] [require Tcl 8.2] @@ -8,11 +15,10 @@ [require bench::out::csv [opt 0.1.2]] [description] This package provides commands for fomatting of benchmark results into a CSV table importable by spread sheets. - [para] A reader interested in the generation or processing of such results should go and read [term {bench - Processing benchmark suites}] instead. @@ -24,11 +30,10 @@ to the formal [term {bench language specification}]. [para] [section {PUBLIC API}] - [list_begin definitions] [call [cmd ::bench::out::csv] [arg bench_result]] @@ -42,22 +47,8 @@ [package bench::out::text] which provide commands to format benchmark results in raw form, or for human consumption, respectively. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph bench] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also bench] -[see_also bench::out::text] -[keywords testing performance benchmark formatting csv] +[vset CATEGORY bench] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bench/bench_wtext.man ================================================================== --- modules/bench/bench_wtext.man +++ modules/bench/bench_wtext.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bench::out::text n 0.1.2] +[see_also bench] +[see_also bench::out::csv] +[keywords benchmark] +[keywords formatting] +[keywords {human readable}] +[keywords performance] +[keywords testing] +[keywords text] [copyright {2007 Andreas Kupries }] [moddesc {Benchmarking/Performance tools}] [titledesc {bench::out::text - Formatting benchmark results as human readable text}] [category {Benchmark tools}] [require Tcl 8.2] @@ -40,22 +48,8 @@ [package bench::out::csv] which provide commands to format benchmark results in raw form, or as importable CSV data, respectively. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph bench] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also bench] -[see_also bench::out::csv] -[keywords testing performance benchmark formatting text {human readable}] +[vset CATEGORY bench] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/bibtex/bibtex.man ================================================================== --- modules/bibtex/bibtex.man +++ modules/bibtex/bibtex.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin bibtex n 0.5] +[keywords bibliography] +[keywords bibtex] +[keywords parsing] +[keywords {text processing}] [copyright {2005 for documentation, Andreas Kupries }] [moddesc {bibtex}] [titledesc {Parse bibtex files}] [category {Text processing}] [require Tcl 8.4] @@ -22,11 +26,10 @@ input bibliography. Instead of performing an immediate parse returning a predefined format the command can also enter an event-based parsing style where all relevant entries in the input are reported through callback commands, in the style of SAX. - [call [cmd ::bibtex::parse] [arg text]] In this form the command will assume that the specified [arg text] is a bibliography in BibTeX format, parse it, and then return a list containing one element per record found in the bibliography. Note that @@ -33,11 +36,10 @@ comments, string definitions, preambles, etc. will not show up in the result. Each element will be a list containing record type, bibliography key and record data, in this order. The record data will be a dictionary, its keys the keys of the record, with the associated values. - [call [cmd ::bibtex::parse] \ [opt "[option -command] [arg cmd]"] \ [option -channel] [arg chan]] @@ -65,11 +67,10 @@ [para] [emph Note] that the parser will [emph not] close the channel after it has exhausted it. This is still the responsibility of the user of the parser. - [call [cmd ::bibtex::parse] \ [opt "[option -recordcommand] [arg recordcmd]"] \ [opt "[option -preamblecommand] [arg preamblecmd]"] \ [opt "[option -stringcommand] [arg stringcmd]"] \ @@ -105,33 +106,29 @@ record in the input. Its arguments are the record type, the bibliography key for the record, and a dictionary containing the keys and values describing the record. Any string macros known to the parser have already been expanded. - [def "[cmd preamblecmd] [arg token] [arg preambletext]"] This callback is invoked whenever the parser detects an @preamble block in the input. The only additional argument is the text found in the preamble block. By default such entries are ignored. - [def "[cmd stringcmd] [arg token] [arg stringdict]"] This callback is invoked whenever the parser detects an @string-based macro definition in the input. The argument is a dictionary with the macro names as keys and their replacement strings as values. By default such definitions are added to the parser state for use in future bibliography records. - [def "[cmd commentcmd] [arg token] [arg commenttext]"] This callback is invoked whenever the parser detects a comment in the input. The only additional argument is the comment text. By default such entries are ignored. - [def "[cmd progresscmd] [arg token] [arg percent]"] This callback is invoked during processing to tell the user about the progress which has been made. Its argument is the percentage of data @@ -141,24 +138,21 @@ [const -1] as the total number of entries is not known beforehand. [list_end] [para] - [call [cmd ::bibtex::wait] [arg token]] This command waits for the parser represented by the [arg token] to complete and then returns. The returned result is the empty string. - [call [cmd ::bibtex::destroy] [arg token]] This command cleans up all internal state associated with the parser represented by the handle [arg token], effectively destroying it. This command can be called from within the parser callbacks to terminate processing. - [call [cmd ::bibtex::addStrings] [arg token] [arg stringdict]] This command adds the macro definitions stored in the dictionary [arg stringdict] to the parser represented @@ -171,19 +165,8 @@ a [option -stringcommand] callback in an invokation of the command [cmd ::bibtex::parse]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph bibtex] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords bibtex parsing {text processing} bibliography] +[vset CATEGORY bibtex] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/blowfish/blowfish.man ================================================================== --- modules/blowfish/blowfish.man +++ modules/blowfish/blowfish.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin blowfish n 1.0.3] +[see_also 3des] +[see_also des] +[see_also rc4] +[keywords {block cipher}] +[keywords blowfish] +[keywords cryptography] +[keywords encryption] +[keywords security] [copyright {2003, Pat Thoyts }] [moddesc {Blowfish Block Cipher}] [titledesc {Implementation of the Blowfish block cipher}] [category {Hashes, checksums, and encryption}] [require Tcl 8.4] @@ -99,11 +107,10 @@ This should be called to clean up resources associated with [arg Key]. Once this function has been called the key may not be used again. [list_end] - [section "MODES OF OPERATION"] [list_begin definitions] [def "Electronic Code Book (ECB)"] @@ -147,24 +154,11 @@ Schneier, B. "Applied Cryptography, 2nd edition", 1996, ISBN 0-471-11709-9, pub. John Wiley & Sons. [list_end] -[see_also des 3des rc4] - [section AUTHORS] Frank Pilhofer, Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph blowfish] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords blowfish {block cipher} security encryption cryptography] +[vset CATEGORY blowfish] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/cache/async.man ================================================================== --- modules/cache/async.man +++ modules/cache/async.man @@ -1,12 +1,15 @@ [manpage_begin cache::async n 0.3] +[keywords asynchronous] +[keywords cache] +[keywords callback] +[keywords synchronous] [copyright {2008 Andreas Kupries }] [moddesc {In-memory caches}] [titledesc {Asynchronous in-memory cache}] [require Tcl 8.4] [require cache::async [opt 0.3]] -[keywords cache asynchronous synchronous callback] [description] This package provides objects which cache data in memory, and operate asynchronously with regard to request and responses. The objects are agnostic with regard to cache keys and values, and unknown methods are @@ -92,11 +95,10 @@ same [arg key] before it can respond. In that case the cache will issue only one data request to the provider, for the first of these, and suspend the others, and then notify all of them when the data becomes available. - [call [arg objectName] [method set] [arg key] [arg value]] [call [arg objectName] [method unset] [arg key]] These two methods are provided to allow users of the cache to make keys known to the cache, as either having a [arg value], or as @@ -120,33 +122,22 @@ This also means that these methods invoke the [arg donecmd] of all [method get]-requests waiting for information about the modified [arg key]. - [call [arg objectName] [method exists] [arg key]] This method queries the cache for knowledge about the [arg key] and returns a boolean value. The result is [const true] if the key is known, and [const false] otherwise. - [call [arg objectName] [method clear] [opt [arg key]]] This method resets the state of either the specified [arg key] or of all keys known to the cache, making it unkown. This forces future [method get]-requests to reload the information from the provider. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph cache] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY cache] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/clock/iso8601.man ================================================================== --- modules/clock/iso8601.man +++ modules/clock/iso8601.man @@ -40,18 +40,8 @@ [option -timezone] of the builtin command [cmd {clock scan}]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph clock::iso8601] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY clock::iso8601] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/clock/rfc2822.man ================================================================== --- modules/clock/rfc2822.man +++ modules/clock/rfc2822.man @@ -20,17 +20,8 @@ the given date in seconds since epoch. An error is thrown if the command is unable to parse the date. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph clock::rfc2822] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY clock::rfc2822] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/cmdline/cmdline.man ================================================================== --- modules/cmdline/cmdline.man +++ modules/cmdline/cmdline.man @@ -1,17 +1,19 @@ [manpage_begin cmdline n 1.3.3] +[keywords {argument processing}] +[keywords argv] +[keywords argv0] +[keywords {cmdline processing}] +[keywords {command line processing}] [moddesc {Command line and option processing}] [titledesc {Procedures to process command lines and options.}] [category {Programming tools}] -[keywords {cmdline processing} {argument processing} argv argv0] -[keywords {command line processing}] [require Tcl 8.2] [require cmdline [opt 1.3.3]] [description] This package provides commands to parse command lines and options. - [section {::argv handling}] One of the most common variables this package will be used with is [var ::argv], which holds the command line of the current @@ -22,11 +24,10 @@ [para] The commands in this package will [emph not] modify the [var ::argc] companion when called with [var ::argv]. Keeping the value consistent, if such is desired or required, is the responsibility of the caller. - [section API] [list_begin definitions] @@ -61,16 +62,14 @@ [arg valVar] refers to the variable to store either the value for the specified option into upon success or an error message in the case of failure. The stored value comes from the command line for .arg options, otherwise the value is 1. - [call [cmd ::cmdline::getKnownOpt] [arg argvVar] [arg optstring] [arg optVar] [arg valVar]] Like [cmd ::cmdline::getopt], but ignores any unknown options in the input. - [call [cmd ::cmdline::getoptions] [arg arglistVar] [arg optlist] [opt [arg usage]]] Processes the set of command line options found in the list variable named by [arg arglistVar] and fills in defaults for those not @@ -97,31 +96,27 @@ implicitly understood. The first two abort option processing and force the generation of the usage message, whereas the the last aborts option processing without an error, leaving all arguments coming after for regular processing, even if starting with a dash. - [para] The result of the command is a dictionary mapping all options to their values, be they user-specified or defaults. - [call [cmd ::cmdline::getKnownOptions] [arg arglistVar] [arg optlist] [opt [arg usage]]] Like [cmd ::cmdline::getoptions], but ignores any unknown options in the input. - [call [cmd ::cmdline::usage] [arg optlist] [opt [arg usage]]] Generates and returns an error message that lists the allowed flags. [arg optlist] is defined as for [cmd ::cmdline::getoptions]. The optional [arg usage]-argument contains a string to include in front of the generated message. If not present it defaults to "options:". - [call [cmd ::cmdline::getfiles] [arg patterns] [arg quiet]] Given a list of file [arg patterns] this command computes the set of valid files. On windows, file globbing is performed on each argument. @@ -133,11 +128,10 @@ This code also uses the full path for each file. If not given it prepends the current working directory to the filename. This ensures that these files will never conflict with files in a wrapped zip file. The last sentence refers to the pro-tools. - [call [cmd ::cmdline::getArgv0]] This command returns the "sanitized" version of [arg argv0]. It will strip off the leading path and removes the extension ".bin". The @@ -176,19 +170,8 @@ [package fileutil], shows how to use cmdline. First, a list of options is created, then the 'args' list is passed to cmdline for processing. Subsequently, different options are checked to see if they have been passed to the script, and what their value is. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph cmdline] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY cmdline] +[include ../doctools2base/include/feedback.inc] [manpage_end] - Index: modules/comm/comm.man ================================================================== --- modules/comm/comm.man +++ modules/comm/comm.man @@ -1,15 +1,25 @@ [manpage_begin comm n 4.6.2] +[see_also send(n)] +[keywords comm] +[keywords communication] +[keywords ipc] +[keywords message] +[keywords {remote communication}] +[keywords {remote execution}] +[keywords rpc] +[keywords secure] +[keywords send] +[keywords socket] +[keywords ssl] +[keywords tls] [copyright {1995-1998 The Open Group. All Rights Reserved.}] [copyright {2003-2004 ActiveState Corporation.}] [copyright {2006-2009 Andreas Kupries }] [moddesc {Remote communication}] [titledesc {A remote communication facility for Tcl (8.3 and later)}] [category {Programming tools}] -[see_also send(n)] -[keywords socket {remote execution} {remote communication} send] -[keywords communication ipc message rpc comm ssl tls secure] [require Tcl 8.3] [require comm [opt 4.6.2]] [description] [para] @@ -215,11 +225,10 @@ happens. Recycling the socket is done by invoking [cmd {::comm::comm abort}], which causes all active sends to terminate. - [subsection {Id/port Assignments}] [para] [package comm] uses a TCP port for endpoint [emph id]. The @@ -242,11 +251,10 @@ [option {-listen 0}], then it will not create a listening socket and will use an id of [const 0] for itself. Such a channel is only good for outgoing connections (although once a connection is established, it can carry send traffic in both directions). - As another special case, if the channel is configured with [option {-silent 0}], then the listening side will ignore connection attempts where the protocol negotiation phase failed, instead of @@ -293,11 +301,10 @@ interpreter. To change this use the option [option -events] to declare a list of the events whose scripts should be executed in the declared interpreter as well. The contents of this option are ignored if the communication channel is configured to execute received scripts in the current interpreter. - [subsection {Remote Interpreters}] [para] By default, each channel is restricted to accepting connections from @@ -411,11 +418,11 @@ [para] [example { % ::comm::comm hook connecting { if {[string match {*[02468]} $id]} { - error "Can't connect to even ids" + error "Can't connect to even ids" } } % ::comm::comm send 10000 puts ok Connect to remote failed: Can't connect to even ids % @@ -453,11 +460,10 @@ if {[string match 127.0.0.1 $addr]} { error "I don't talk to myself" } } }] - [def [const eval]] Variables: [var chan], [var id], [var cmd], and [var buffer]. @@ -562,11 +568,10 @@ A-OK }] [list_end] - [def [const reply]] Variables: [var chan], [var id], [var buffer], [var ret], and [var return()]. [para] @@ -600,11 +605,10 @@ [para] Any of these may be the empty string. Modifying these four variables can change the return value, whereas modifying [arg buffer] has no effect. - [def [const callback]] Variables: [var chan], [var id], [var buffer], [var ret], and [var return()]. @@ -692,19 +696,16 @@ # Create secured comm channel ::comm::comm new SECURE -socketcmd tls::socket -listen 1 ... }] - - [para] The sections [sectref {Execution Environment}] and [sectref Callbacks] are also relevant to the security of the system, providing means to restrict the execution to a specific environment, perform additional authentication, and the like. - [subsection {Blocking Semantics}] [para] @@ -1046,11 +1047,10 @@ Added a new hook for reply messages. Reworked method invocation to avoid the use of comm:* procedures; this also cut the invocation time down by 40%. Documented [cmd {comm config}] (as this manual page still listed the defunct [cmd {comm init}]!) - [def 3.3] Some minor bugs were corrected and the documentation was cleaned up. Added some examples for hooks. The return semantics of the [cmd eval] hook were changed. @@ -1112,11 +1112,10 @@ [para] [emph http://www.opengroup.org/~loverso/tcl-tk/#comm] - [section License] Please see the file [emph comm.LICENSE] that accompanied this source, or [uri http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html]. @@ -1123,11 +1122,10 @@ [para] This license for [package comm], new as of version 3.2, allows it to be used for free, without any licensing fee or royalty. - [section Bugs] [list_begin itemized] [item] @@ -1178,11 +1176,10 @@ [list_end] [para] This man page is bigger than the source file. - [section {On Using Old Versions Of Tcl}] [para] Tcl7.5 under Windows contains a bug that causes the interpreter to hang when EOF is reached on non-blocking sockets. This can be @@ -1203,11 +1200,10 @@ [para] Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recommended you use Tcl8.0p1 (or Tcl7.6p2). - [section {Related Work}] [para] Tcl-DP provides an RPC-based remote execution interface, but is a compiled Tcl extension. See [uri http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html]. @@ -1218,10 +1214,9 @@ [para] 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] [manpage_end] Index: modules/comm/comm_wire.man ================================================================== --- modules/comm/comm_wire.man +++ modules/comm/comm_wire.man @@ -1,13 +1,19 @@ [manpage_begin comm_wire n 3] +[see_also comm] +[keywords comm] +[keywords communication] +[keywords ipc] +[keywords message] +[keywords {remote communication}] +[keywords {remote execution}] +[keywords rpc] +[keywords socket] [copyright {2005 Docs. Andreas Kupries }] [moddesc {Remote communication}] [titledesc {The comm wire protocol}] [category {Programming tools}] -[keywords socket {remote execution} {remote communication}] -[keywords communication ipc message rpc comm] -[see_also comm] [require comm] [description] [para] @@ -69,11 +75,10 @@ it still allows arbitrary scripts. The interp has to contains aliases for the wanted commands, and only them for us to get a large security wall. }] - [section {Wire Protocol Version 3}] [subsection {Basic Layer}] The basic encoding for [emph all] data is UTF-8. Because of this binary data, including the NULL character, can be sent over the wire @@ -81,11 +86,11 @@ [subsection {Basic Message Layer}] On top of the [sectref {Basic Layer}] we have a -[term {message oriented}] exchange of data. +[term {message oriented}] exchange of data. The totality of all characters written to the channel is a Tcl list, with each element a separate [term message], each itself a list. The messages in the overall list are separated by EOL. Note that EOL characters can occur within the list as well. They can be @@ -101,11 +106,10 @@ [para] As a list each message is composed of [term words]. Their meaning depends on when the message was sent in the overall exchange. This is described in the upcoming sections. - [subsection {Negotiation Messages - Initial Handshake} ih] The command protocol is defined like this: @@ -144,11 +148,10 @@ However the handshake response containing the accepted version is sent before commNewComm is called (in commIncoming). - NOTE 2: This inconsistency has been fixed locally already, but not been committed yet. }] @@ -161,11 +164,10 @@ and the payload. The valid instructions are shown below. The transaction ids are used by the client to match any incoming replies to the command messages it sent. This means that a server has to copy the transaction id from a command message to the reply it sends for that message. - [list_begin definitions] [def [const send]] [def [const async]] @@ -211,11 +213,10 @@ [example { send [list array get $the_variable] }] [para] - These three instructions all invoke the script on the server side. Their difference is in the treatment of result values, and thus determines if a reply is expected. [list_begin definitions] @@ -252,25 +253,22 @@ {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}} }] [list_end] - [comment { Socket Miscellanea ------------------ It is possible to have two sockets between a client and a server. This happens if both sides connected to each other at the same time. - Current protocol versions ------------------------- V2 - V3 This is preferred version and uses UTF 8 encoding. This is actually the only version which will work IIU the code right. Because the server part of comm will @@ -279,18 +277,8 @@ IOW if v2 is used the client will not see a version reply during the negotiation handshake. }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph comm] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY comm] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/control/control.man ================================================================== --- modules/control/control.man +++ modules/control/control.man @@ -1,6 +1,21 @@ [manpage_begin control n 0.1.3] +[see_also break] +[see_also continue] +[see_also expr] +[see_also if] +[see_also join] +[see_also namespace] +[see_also return] +[see_also string] +[see_also while] +[keywords assert] +[keywords control] +[keywords do] +[keywords flow] +[keywords no-op] +[keywords structure] [moddesc {Tcl Control Flow Commands}] [titledesc {Procedures for control flow structures.}] [category {Programming tools}] [require Tcl 8.2] [require control [opt 0.1.3]] @@ -143,20 +158,8 @@ 1 % catch b 0 }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph control] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also expr if join namespace return string while break continue] -[keywords control flow structure no-op assert do] +[vset CATEGORY control] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/coroutine/coro_auto.man ================================================================== --- modules/coroutine/coro_auto.man +++ modules/coroutine/coro_auto.man @@ -1,17 +1,27 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin coroutine::auto n 1] +[keywords after] +[keywords channel] +[keywords coroutine] +[keywords events] +[keywords exit] +[keywords gets] +[keywords global] +[keywords {green threads}] +[keywords read] +[keywords threads] +[keywords update] +[keywords vwait] [copyright {2010-2011 Andreas Kupries }] [moddesc {Coroutine utilities}] [category Coroutine] [titledesc {Automatic event and IO coroutine awareness}] [require Tcl 8.6] [require coroutine::auto 1.1.1] [require coroutine 1.1] [description] -[keywords coroutine global exit after vwait update gets read] -[keywords channel threads {green threads} events] The [package coroutine::auto] package provides no commands or other directly visible functionality. Built on top of the package [package coroutine], it intercepts various @@ -28,17 +38,8 @@ [def [cmd read]] [def [cmd update]] [def [cmd vwait]] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph coroutine] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY coroutine] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/coroutine/tcllib_coroutine.man ================================================================== --- modules/coroutine/tcllib_coroutine.man +++ modules/coroutine/tcllib_coroutine.man @@ -1,16 +1,26 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin coroutine n 1] +[keywords after] +[keywords channel] +[keywords coroutine] +[keywords events] +[keywords exit] +[keywords gets] +[keywords global] +[keywords {green threads}] +[keywords read] +[keywords threads] +[keywords update] +[keywords vwait] [copyright {2010-2011 Andreas Kupries }] [moddesc {Coroutine utilities}] [category Coroutine] [titledesc {Coroutine based event and IO handling}] [require Tcl 8.6] [require coroutine 1.1] [description] -[keywords coroutine channel events threads {green threads}] -[keywords global exit after vwait update gets read] The [package coroutine] package provides coroutine-aware implementations of various event- and channel related commands. It can be in multiple modes: @@ -30,90 +40,70 @@ above is available through the package [package coroutine::auto], which intercepts the relevant builtin commands and changes their implementation dependending on the context they are run in, i.e. inside or outside of a coroutine. - [section API] All the commands listed below are synchronous with respect to the coroutine invoking them, i.e. this coroutine blocks until the result is available. The overall eventloop is not blocked however. - [list_begin definitions] [call [cmd {coroutine::util after}] [arg delay]] This command delays the coroutine invoking it by [arg delay] milliseconds. - [call [cmd {coroutine::util await}] [arg varname]...] This command is an extension form of the [cmd {coroutine::util vwait}] command (see below) which waits on a write to one of many named namespace variables. - [call [cmd {coroutine::util create}] [arg arg]...] This command creates a new coroutine with an automatically assigned name and causes it to run the code specified by the arguments. - [call [cmd {coroutine::util exit}] [opt [arg status]]] This command exits the current coroutine, causing it to return [arg status]. If no status was specified the default [arg 0] is returned. - [call [cmd {coroutine::util gets}] [arg chan] [opt [arg varname]]] This command reads a line from the channel [arg chan] and returns it either as its result, or, if a [arg varname] was specified, writes it to the named variable and returns the number of characters read. - [call [cmd {coroutine::util global}] [arg varname]...] This command imports the named global variables of the coroutine into the current scope. From the technical point of view these variables reside in level [const #1] of the Tcl stack. I.e. these are not the regular global variable in to the global namespace, and each coroutine can have their own set, independent of all others. - [call [cmd {coroutine::util read}] [option -nonewline] [arg chan] [opt [arg n]]] This command reads [arg n] characters from the channel [arg chan] and returns them as its result. If [arg n] is not specified the command will read the channel until EOF is reached. - [call [cmd {coroutine::util update}] [opt [const idletasks]]] This command causes the coroutine invoking it to run pending events or idle handlers before proceeding. - [call [cmd {coroutine::util vwait}] [arg varname]] This command causes the coroutine calling it to wait for a write to the named namespace variable [arg varname]. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph coroutine] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY coroutine] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/counter/counter.man ================================================================== --- modules/counter/counter.man +++ modules/counter/counter.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin counter n 2.0.4] +[keywords counting] +[keywords histogram] +[keywords statistics] +[keywords tallying] [moddesc {Counters and Histograms}] [titledesc {Procedures for counters and histograms}] [category {Data structures}] [require Tcl 8] [require counter [opt 2.0.4]] @@ -10,11 +14,10 @@ The [package counter] package provides a counter facility and can compute statistics and histograms over the collected data. [list_begin definitions] - [call [cmd ::counter::init] [arg {tag args}]] This defines a counter with the name [arg tag]. The [arg args] determines the characteristics of the counter. The [arg args] are @@ -72,11 +75,10 @@ [arg secsPerMinute] value seen by the package is used for all subsequent time-based histograms. [list_end] - [call [cmd ::counter::count] [arg tag] [opt [arg delta]] [opt [arg instance]]] Increment the counter identified by [arg tag]. The default increment is 1, although you can increment by any value, integer or real, by specifying [arg delta]. You must declare each counter with @@ -83,25 +85,22 @@ [cmd ::counter::init] to define the characteristics of counter before you start to use it. If the counter type is [option -group], then the counter identified by [arg instance] is incremented. - [call [cmd ::counter::start] [arg {tag instance}]] Record the starting time of an interval. The [arg tag] is the name of the counter defined as a [option -hist] value-based histogram. The [arg instance] is used to distinguish this interval from any other intervals that might be overlapping this one. - [call [cmd ::counter::stop] [arg {tag instance}]] Record the ending time of an interval. The delta time since the corresponding [cmd ::counter::start] call for [arg instance] is recorded in the histogram identified by [arg tag]. - [call [cmd ::counter::get] [arg {tag args}]] Return statistics about a counter identified by [arg tag]. The @@ -171,20 +170,17 @@ includes the total, the number of samples (N), and any type-specific information. This does not include the histogram array. [list_end] - [call [cmd ::counter::exists] [arg tag]] Returns 1 if the counter is defined. - [call [cmd ::counter::names]] Returns a list of all counters defined. - [call [cmd ::counter::histHtmlDisplay] [arg {tag args}]] Generate HTML to display a histogram for a counter. The [arg args] control the format of the display. They are: @@ -245,23 +241,10 @@ Resets the counter with the name [arg tag] to an initial state. The [arg args] determine the new characteristics of the counter. They have the same meaning as described for [cmd ::counter::init]. - - [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph counter] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords statistics histogram counting tallying] +[vset CATEGORY counter] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/crc/cksum.man ================================================================== --- modules/crc/cksum.man +++ modules/crc/cksum.man @@ -1,6 +1,15 @@ [manpage_begin cksum n 1.1.3] +[see_also crc32(n)] +[see_also sum(n)] +[keywords checksum] +[keywords cksum] +[keywords crc] +[keywords crc32] +[keywords {cyclic redundancy check}] +[keywords {data integrity}] +[keywords security] [copyright {2002, Pat Thoyts}] [moddesc {Cyclic Redundancy Checks}] [titledesc {Calculate a cksum(1) compatible checksum}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -69,15 +78,14 @@ Begins a new cksum context. Returns a token ID that must be used for the remaining functions. An optional seed may be specified if required. [call [cmd "::crc::CksumUpdate"] [arg "token"] [arg "data"]] -Add data to the checksum identified by token. Calling +Add data to the checksum identified by token. Calling [emph {CksumUpdate $token "abcd"}] is equivalent to calling -[emph {CksumUpdate $token "ab"}] followed by +[emph {CksumUpdate $token "ab"}] followed by [emph {CksumUpdate $token "cb"}]. See [sectref {EXAMPLES}]. - [call [cmd "::crc::CksumFinal"] [arg "token"]] Returns the checksum value and releases any resources held by this token. Once this command completes the token will be invalid. The @@ -112,24 +120,11 @@ % crc::CksumUpdate $tok "World!" % crc::CksumFinal $tok 2609532967 }] - -[see_also sum(n) crc32(n)] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph crc] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords cksum checksum crc crc32 {cyclic redundancy check} {data integrity} security] +[vset CATEGORY crc] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/crc/crc16.man ================================================================== --- modules/crc/crc16.man +++ modules/crc/crc16.man @@ -1,6 +1,17 @@ [manpage_begin crc16 n 1.1.2] +[see_also cksum(n)] +[see_also crc32(n)] +[see_also sum(n)] +[keywords checksum] +[keywords cksum] +[keywords crc] +[keywords crc16] +[keywords crc32] +[keywords {cyclic redundancy check}] +[keywords {data integrity}] +[keywords security] [copyright {2002, Pat Thoyts}] [moddesc {Cyclic Redundancy Checks}] [titledesc {Perform a 16bit Cyclic Redundancy Check}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -121,23 +132,11 @@ [example { % crc::crc16 -file crc16.tcl 51675 }] -[see_also sum(n) cksum(n) crc32(n)] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph crc] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords cksum checksum crc crc32 crc16 {cyclic redundancy check} {data integrity} security] +[vset CATEGORY crc] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/crc/crc32.man ================================================================== --- modules/crc/crc32.man +++ modules/crc/crc32.man @@ -1,6 +1,16 @@ [manpage_begin crc32 n 1.3] +[see_also cksum(n)] +[see_also crc16(n)] +[see_also sum(n)] +[keywords checksum] +[keywords cksum] +[keywords crc] +[keywords crc32] +[keywords {cyclic redundancy check}] +[keywords {data integrity}] +[keywords security] [copyright {2002, Pat Thoyts}] [moddesc {Cyclic Redundancy Checks}] [titledesc {Perform a 32bit Cyclic Redundancy Check}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -64,11 +74,11 @@ calculating the CRC of the next member. Note that the crc32 algorithm includes a final XOR step. If incremental processing is desired then this must be undone before using the output of the algorithm as the seed for further -processing. A simpler alternative is to use the +processing. A simpler alternative is to use the [sectref {PROGRAMMING INTERFACE}] which is intended for this mode of operation. [list_end] @@ -89,15 +99,14 @@ Begins a new CRC32 context. Returns a token ID that must be used for the remaining functions. An optional seed may be specified if required. [call [cmd "::crc::Crc32Update"] [arg "token"] [arg "data"]] -Add data to the checksum identified by token. Calling +Add data to the checksum identified by token. Calling [emph {Crc32Update $token "abcd"}] is equivalent to calling -[emph {Crc32Update $token "ab"}] followed by +[emph {Crc32Update $token "ab"}] followed by [emph {Crc32Update $token "cb"}]. See [sectref {EXAMPLES}]. - [call [cmd "::crc::Crc32Final"] [arg "token"]] Returns the checksum value and releases any resources held by this token. Once this command completes the token will be invalid. The @@ -132,23 +141,11 @@ % crc::Crc32Update $tok "World!" % crc::Crc32Final $tok 3964322768 }] -[see_also sum(n) cksum(n) crc16(n)] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph crc] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords cksum checksum crc crc32 {cyclic redundancy check} {data integrity} security] +[vset CATEGORY crc] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/crc/sum.man ================================================================== --- modules/crc/sum.man +++ modules/crc/sum.man @@ -1,6 +1,17 @@ [manpage_begin sum n 1.1.0] +[see_also cksum(n)] +[see_also crc32(n)] +[see_also sum(1)] +[keywords checksum] +[keywords cksum] +[keywords crc] +[keywords crc32] +[keywords {cyclic redundancy check}] +[keywords {data integrity}] +[keywords security] +[keywords sum] [copyright {2002, Pat Thoyts }] [moddesc {Cyclic Redundancy Checks}] [titledesc {Calculate a sum(1) compatible checksum}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -86,23 +97,11 @@ [example { % crc::sum -file sum.tcl 13392 }] -[see_also sum(1) cksum(n) crc32(n)] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph crc] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords sum cksum checksum crc crc32 {cyclic redundancy check} {data integrity} security] +[vset CATEGORY crc] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/csv/csv.man ================================================================== --- modules/csv/csv.man +++ modules/csv/csv.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*-}] [manpage_begin csv n 0.8] +[see_also matrix] +[see_also queue] +[keywords csv] +[keywords matrix] +[keywords package] +[keywords queue] +[keywords tcllib] [copyright {2002-2013 Andreas Kupries }] [moddesc {CSV processing}] [titledesc {Procedures to handle CSV data.}] [category {Text processing}] [require Tcl 8.4] @@ -105,11 +112,10 @@ If the option [option -alternate] is specified a slightly different syntax is used to parse the input. This syntax is explained below, in the section [sectref FORMAT]. - [call [cmd ::csv::split2matrix] [opt [option -alternate]] [arg "m line"] "{[arg sepChar] ,} {[arg expand] none}"] The same as [cmd ::csv::split], but appends the resulting list as a new row to the matrix [arg m], using the method [cmd "add row"]. The expansion mode specified via [arg expand] determines how the command @@ -161,11 +167,11 @@ [list_end] [section FORMAT] [para] -The format of regular CSV files is specified as +The format of regular CSV files is specified as [list_begin enumerated] [enum] Each record of a csv file (comma-separated values, as exported e.g. by @@ -233,21 +239,8 @@ }] instead. As can be seen only item (d) is different, now the empty string instead of a ". - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph csv] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also matrix queue] -[keywords csv matrix queue package tcllib] +[vset CATEGORY csv] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/debug/debug.man ================================================================== --- modules/debug/debug.man +++ modules/debug/debug.man @@ -1,13 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin debug n 1] +[keywords debug] +[keywords log] +[keywords narrative] +[keywords trace] [copyright {200?, Colin McCormack, Wub Server Utilities}] [copyright {2012, Andreas Kupries }] [moddesc {debug narrative}] [titledesc {debug narrative - core}] [category {debugging, tracing, and logging}] -[keywords debug trace log narrative] [require Tcl 8.5] [require debug [opt 1]] [description] Debugging areas of interest are represented by 'tags' which have @@ -38,11 +41,10 @@ should they exist, with each line in the message having the specified headers and trailers. [para] All these parts are [cmd subst]ableTcl scripts, which are substituted once per message before assembly. - [comment {= = == === ===== ======== ============= =====================}] [call [cmd debug] [method 2array]] This method returns a dictionary mapping the names of all debug tags @@ -214,17 +216,8 @@ [para] The result of the method is the specified text. [comment {= = == === ===== ======== ============= =====================}] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph debug] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY debug] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/debug/debug_caller.man ================================================================== --- modules/debug/debug_caller.man +++ modules/debug/debug_caller.man @@ -1,12 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin debug::caller n 1] +[keywords debug] +[keywords log] +[keywords narrative] +[keywords trace] [copyright {2012, Andreas Kupries }] [moddesc {debug narrative}] [titledesc {debug narrative - caller}] [category {debugging, tracing, and logging}] -[keywords debug trace log narrative] [require Tcl 8.5] [require debug::caller [opt 1]] [description] [para] @@ -25,17 +28,8 @@ OO system and rewrites these to their original form, for better readability. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph debug] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY debug] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/debug/debug_heartbeat.man ================================================================== --- modules/debug/debug_heartbeat.man +++ modules/debug/debug_heartbeat.man @@ -1,13 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin debug::heartbeat n 1] +[keywords debug] +[keywords heartbeat] +[keywords log] +[keywords narrative] +[keywords trace] [copyright {200?, Colin McCormack, Wub Server Utilities}] [copyright {2012, Andreas Kupries }] [moddesc {debug narrative}] [titledesc {debug narrative - heartbeat}] [category {debugging, tracing, and logging}] -[keywords debug trace log narrative heartbeat] [require Tcl 8.5] [require debug [opt 1]] [description] [para] @@ -30,17 +34,8 @@ providing insight into timing variationsn and deviations from the nominal [arg delta]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph debug] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY debug] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/debug/debug_timestamp.man ================================================================== --- modules/debug/debug_timestamp.man +++ modules/debug/debug_timestamp.man @@ -1,13 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin debug::timestamp n 1] +[keywords debug] +[keywords log] +[keywords narrative] +[keywords timestamps] +[keywords trace] [copyright {200?, Colin McCormack, Wub Server Utilities}] [copyright {2012, Andreas Kupries }] [moddesc {debug narrative}] [titledesc {debug narrative - timestamping}] [category {debugging, tracing, and logging}] -[keywords debug trace log narrative timestamps] [require Tcl 8.5] [require debug [opt 1]] [description] [para] @@ -22,17 +26,8 @@ provide caller information for all uses of the tag. Or in a message, when only specific places need such detail. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph debug] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY debug] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/des/des.man ================================================================== --- modules/des/des.man +++ modules/des/des.man @@ -1,7 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin des n 1.1] +[see_also aes(n)] +[see_also blowfish(n)] +[see_also md5(n)] +[see_also rc4(n)] +[see_also sha1(n)] +[keywords 3DES] +[keywords {block cipher}] +[keywords {data integrity}] +[keywords DES] +[keywords encryption] +[keywords security] [copyright {2005, Pat Thoyts }] [moddesc {Data Encryption Standard (DES)}] [titledesc {Implementation of the DES and triple-DES ciphers}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -19,11 +30,11 @@ [para] The tcllib implementation of DES and 3DES uses an implementation by Mac Cody and is available as a separate download from [lb]2[rb]. For anyone concerned about the details of exporting this code please see -the TclDES web pages. The tcllib specific code is a wrapper to the +the TclDES web pages. The tcllib specific code is a wrapper to the TclDES API that presents same API for the DES cipher as for other ciphers in the library. [section "COMMANDS"] @@ -54,11 +65,11 @@ [para] The [arg -mode] and [arg -dir] options are optional and default to cbc mode and encrypt respectively. The initialization vector [arg -iv] -takes an 8 byte binary argument. This defaults to all zeros. See +takes an 8 byte binary argument. This defaults to all zeros. See [sectref "MODES OF OPERATION"] for more about [arg -mode] and the use of the initialization vector. [para] @@ -183,26 +194,13 @@ "TclDES: munitions-grade Tcl scripting" [uri http://tcldes.sourceforge.net/] [list_end] -[see_also aes(n) blowfish(n) rc4(n) md5(n) sha1(n) ] - [section "AUTHORS"] -Jochen C Loewer, +Jochen C Loewer, Mac Cody, Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph des] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords DES 3DES {block cipher} security encryption {data integrity}] +[vset CATEGORY des] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/dns/tcllib_dns.man ================================================================== --- modules/dns/tcllib_dns.man +++ modules/dns/tcllib_dns.man @@ -1,6 +1,13 @@ [manpage_begin dns n 1.3.3] +[see_also resolver(5)] +[keywords DNS] +[keywords {domain name service}] +[keywords resolver] +[keywords {rfc 1034}] +[keywords {rfc 1035}] +[keywords {rfc 1886}] [copyright {2002, Pat Thoyts}] [moddesc {Domain Name Service}] [titledesc {Tcl Domain Name Service Client}] [category Networking] [require Tcl 8.2] @@ -26,14 +33,14 @@ command can handle DNS URIs or simple domain names as a query. [para] [emph Note:] The package defaults to using DNS over TCP -connections. If you wish to use UDP you will need to have the +connections. If you wish to use UDP you will need to have the [package tcludp] package installed and have a version that correctly handles binary data (> 1.0.4). -This is available at [uri http://tcludp.sourceforge.net/]. +This is available at [uri http://tcludp.sourceforge.net/]. If the [package udp] package is present then UDP will be used by default. [section COMMANDS] [list_begin definitions] @@ -47,20 +54,20 @@ [list_begin definitions] [def "[cmd -nameserver] [arg hostname] or [cmd -server] [arg hostname]"] Specify an alternative name server for this request. [def "[cmd -protocol] [arg tcp|udp]"] Specify the network protocol to use for this request. Can be one of - [arg tcp] or [arg udp]. + [arg tcp] or [arg udp]. [def "[cmd -port] [arg portnum]"] Specify an alternative port. [def "[cmd -search] [arg domainlist]"] [def "[cmd -timeout] [arg milliseconds]"] Override the default timeout. [def "[cmd -type] [arg TYPE]"] Specify the type of DNS record you are interested in. Valid values - are A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO, - MINFO, MX, TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and *. + are A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO, + MINFO, MX, TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and *. See RFC1035 for details about the return values. See [uri http://spf.pobox.com/] about SPF. See (3) about AAAA records and RFC2782 for details of SRV records. [def "[cmd -class] [arg CLASS]"] @@ -68,11 +75,11 @@ of IN for internet domain names, CS, CH, HS or * for any class. [def "[cmd -recurse] [arg boolean]"] Set to [arg false] if you do not want the name server to recursively act upon your request. Normally set to [arg true]. [def "[cmd -command] [arg procname]"] - Set a procedure to be called upon request completion. The procedure + Set a procedure to be called upon request completion. The procedure will be passed the token as its only argument. [list_end] [para] [call [cmd ::dns::configure] [opt [arg "options"]]] @@ -99,11 +106,10 @@ [def "[cmd -loglevel] [arg level]"] Set the log level used for emitting diagnostic messages from this package. The default is [term warn]. See the [package log] package for details of the available levels. [list_end] - [para] [call [cmd ::dns::name] [arg token]] Returns a list of all domain names returned as an answer to your query. @@ -141,20 +147,19 @@ [para] [call [cmd ::dns::cleanup] [arg token]] Remove all state variables associated with the request. - [para] [call [cmd ::dns::nameservers]] Attempts to return a list of the nameservers currently configured for the users system. On a unix machine this parses the /etc/resolv.conf file for nameservers (if it exists) and on Windows systems we examine certain parts of the registry. If no nameserver can be found then the loopback address (127.0.0.1) is used as a default. - + [list_end] [comment { ----------------------------------------------------------- }] [section EXAMPLES] @@ -201,11 +206,11 @@ ([uri http://www.ietf.org/rfc/rfc1034.txt]) [enum] Mockapetris, P., "Domain Names - Implementation and Specification", RFC 1035, November 1087. - ([uri http://www.ietf.org/rfc/rfc1035.txt]) + ([uri http://www.ietf.org/rfc/rfc1035.txt]) [enum] Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6", RFC 1886, December 1995. ([uri http://www.ietf.org/rfc/rfc1886.txt]) @@ -226,23 +231,11 @@ RFC 1995, August 1996, ([uri http://www.ietf.org/rfc/rfc1995.txt]) [list_end] -[see_also resolver(5)] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph dns] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords DNS resolver {domain name service} {rfc 1034} {rfc 1035} {rfc 1886}] +[vset CATEGORY dns] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/dns/tcllib_ip.man ================================================================== --- modules/dns/tcllib_ip.man +++ modules/dns/tcllib_ip.man @@ -1,6 +1,14 @@ [manpage_begin tcllib_ip n 1.2.1] +[see_also inet(3)] +[see_also ip(7)] +[see_also ipv6(7)] +[keywords {internet address}] +[keywords ip] +[keywords ipv4] +[keywords ipv6] +[keywords {rfc 3513}] [copyright {2004, Pat Thoyts}] [copyright {2005 Aamer Akhter }] [moddesc {Domain Name Service}] [titledesc {IPv4 and IPv6 address manipulation}] [category Networking] @@ -39,12 +47,12 @@ [call [cmd ::ip::normalize] [arg address]] Convert an IPv4 or IPv6 address into a fully expanded version. There are various shorthand ways to write internet addresses, missing out -redundant parts or digts.. This procedure is the opposite of -[cmd contract]. +redundant parts or digts.. This procedure is the opposite of +[cmd contract]. [call [cmd ::ip::contract] [arg address]] Convert a [cmd normalize]d internet address into a more compact form suitable for displaying to users. @@ -60,11 +68,10 @@ [call [cmd ::ip::mask] [arg address]] If the address supplied includes a mask then this is returned otherwise returns an empty string. - [call [cmd ::ip::prefixToNative] [arg prefix]] This command converts the string [arg prefix] from dotted form (/ format) to native (hex) form. Returns a list containing two elements, ipaddress and mask, in this order, in @@ -73,11 +80,10 @@ [para] [example { % ip::prefixToNative 1.1.1.0/24 0x01010100 0xffffff00 }] - [call [cmd ::ip::nativeToPrefix] [arg nativeList]|[arg native] \ [opt [option -ipv4]]] This command converts from native (hex) form to dotted form. @@ -105,11 +111,10 @@ [example { % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4 1.1.1.0/24 }] - [call [cmd ::ip::intToString] [arg number] [opt [option -ipv4]]] This command converts from an ip address specified as integer number to dotted form. @@ -116,11 +121,10 @@ [para] [example { ip::intToString 4294967295 255.255.255.255 }] - [call [cmd ::ip::toInteger] [arg ipaddr]] This command converts a dotted form ip into an integer number. @@ -128,21 +132,19 @@ [example { % ::ip::toInteger 1.1.1.0 16843008 }] - [call [cmd ::ip::toHex] [arg ipaddr]] This command converts dotted form ip into a hexadecimal number. [para] [example { % ::ip::toHex 1.1.1.0 0x01010100 }] - [call [cmd ::ip::maskToInt] [arg ipmask]] This command convert an ipmask in either dotted (255.255.255.0) form or mask length form (24) into an integer number. @@ -150,11 +152,10 @@ [para] [example { ::ip::maskToInt 24 4294967040 }] - [call [cmd ::ip::broadcastAddress] [arg prefix] [opt [option -ipv4]]] This commands returns a broadcast address in dotted form for the given route [arg prefix], either in the form "addr/mask", or in native @@ -165,12 +166,11 @@ ::ip::broadcastAddress 1.1.1.0/24 1.1.1.255 ::ip::broadcastAddress {0x01010100 0xffffff00} 0x010101ff -}] - +}] [call [cmd ::ip::maskToLength] \ [arg dottedMask]|[arg integerMask]|[arg hexMask] \ [opt [option -ipv4]]] @@ -196,11 +196,10 @@ [example { ::ip::lengthToMask 24 255.255.255.0 }] - [call [cmd ::ip::nextNet] [arg ipaddr] [arg ipmask] \ [opt [arg count]] \ [opt [option -ipv4]]] This command returns an ipaddress in the same position in the @@ -215,11 +214,10 @@ [para] The result is in hex form. - [call [cmd ::ip::isOverlap] [arg prefix] [arg prefix]...] This command checks if the given ip prefixes overlap. All arguments are in dotted "addr/mask" form. All arguments after the first prefix are compared against the first prefix. The result is a boolean @@ -231,11 +229,10 @@ 0 ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32 1 }] - [call [cmd ::ip::isOverlapNative] \ [opt [option -all]] \ [opt [option -inline]] \ [opt [option -ipv4]] \ @@ -284,11 +281,10 @@ % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}} 2 }] - [call [cmd ::ip::ipToLayer2Multicast] [arg ipaddr]] This command an converts ipv4 address in dotted form into a layer 2 multicast address, also in dotted form. @@ -295,11 +291,10 @@ [para] [example { % ::ip::ipToLayer2Multicast 224.0.0.2 01.00.5e.00.00.02 }] - [call [cmd ::ip::ipHostFromPrefix] [arg prefix] \ [opt "[option -exclude] [arg prefixExcludeList]"]] This command returns a host address from a prefix in the form @@ -315,11 +310,10 @@ %::ip::ipHostFromPrefix 1.1.1.1/32 1.1.1.1 }] - [call [cmd ::ip::reduceToAggregates] [arg prefixlist]] This command finds nets that overlap and filters out the more specific nets. The prefixes are in either addr/mask form or in native format. @@ -329,11 +323,10 @@ [para] [example { % ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8 2.1.1.0/24 1.1.1.1/32 } 1.0.0.0/8 2.1.1.0/24 }] - [call [cmd ::ip::longestPrefixMatch] [arg ipaddr] [arg prefixlist] \ [opt [option -ipv4]]] This command finds longest prefix match from set of prefixes, given a @@ -348,11 +341,10 @@ [example { % ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8 2.1.1.0/24 1.1.1.0/28 } 1.1.1.0/28 }] - [call [cmd ::ip::collapse] [arg prefixlist]] This commands takes a list of prefixes and returns a list prefixes with the largest possible subnet masks covering the input, in this manner collapsing adjacent prefixes into larger ranges. @@ -365,11 +357,10 @@ [para] [example { % ::ip::collapse {1.2.2.0/24 1.2.3.0/24} 1.2.2.0/23 }] - [call [cmd ::ip::subtract] [arg prefixlist]] This command takes a list of prefixes, some of which are prefixed by a dash. These latter [term negative] prefixes are used to punch holes @@ -427,23 +418,11 @@ RFC 3513, April 2003 ([uri http://www.ietf.org/rfc/rfc3513.txt]) [list_end] -[see_also inet(3) ip(7) ipv6(7)] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph dns] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {internet address} ip ipv4 ipv6 {rfc 3513}] +[vset CATEGORY dns] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/docstrip/docstrip.man ================================================================== --- modules/docstrip/docstrip.man +++ modules/docstrip/docstrip.man @@ -1,6 +1,13 @@ [manpage_begin docstrip n 1.2] +[see_also docstrip_util] +[keywords .dtx] +[keywords docstrip] +[keywords documentation] +[keywords LaTeX] +[keywords {literate programming}] +[keywords source] [copyright "2003\u20132010 Lars Hellstr\u00F6m\ "] [moddesc {Literate programming tool}] [titledesc {Docstrip style source code extraction}] [category {Documentation tools}] @@ -70,11 +77,10 @@ [enum] Chapter 14 of [emph {The LaTeX Companion}] (second edition), Addison-Wesley, 2004; ISBN 0-201-36299-6. [list_end] - [section {File format}] The basic unit [syscmd docstrip] operates on are the [emph lines] of a master source file. Extraction consists of selecting some of these @@ -296,11 +302,10 @@ stops at a line that is exactly "\endinput"; this is often used to avoid copying random whitespace at the end of a file. In the unlikely case that one wants such a code line, one can protect it with a verbatim guard. - [section Commands] The package defines two commands. [list_begin definitions] @@ -351,11 +356,10 @@ It should be remarked that the [arg terminals] are often called "options" in the context of the [syscmd docstrip] program, since these specify which optional code fragments should be included. - [call [cmd docstrip::sourcefrom] [arg filename] [arg terminals] [ opt "[arg option] [arg value] ..." ]] The [cmd sourcefrom] command is a docstripping emulation of [cmd source]. It opens the file [arg filename], reads it, closes it, @@ -365,11 +369,10 @@ [arg filename]. The options are passed on to [cmd fconfigure] to configure the file before its contents are read. The [option -metaprefix] is set to '#', all other [cmd extract] options have their default values. [list_end] - [section {Document structure}] The file format (as described above) determines whether a master source code file can be processed correctly by [syscmd docstrip], @@ -425,12 +428,6 @@ It is not necessary to use the tclldoc document class, but that does provide a number of features that are convenient for [file .dtx] files containing Tcl code. More information on this matter can be found in the references above. - - -[see_also docstrip_util] - -[keywords documentation source {literate programming} docstrip] -[keywords LaTeX .dtx] [manpage_end] Index: modules/docstrip/docstrip_util.man ================================================================== --- modules/docstrip/docstrip_util.man +++ modules/docstrip/docstrip_util.man @@ -1,6 +1,21 @@ [manpage_begin docstrip_util n 1.3] +[see_also docstrip] +[see_also doctools] +[see_also doctools_fmt] +[keywords .ddt] +[keywords catalogue] +[keywords diff] +[keywords docstrip] +[keywords doctools] +[keywords documentation] +[keywords {literate programming}] +[keywords module] +[keywords {package indexing}] +[keywords patch] +[keywords source] +[keywords {Tcl module}] [copyright "2003\u20132010 Lars Hellstr\u00F6m\ "] [moddesc {Literate programming tool}] [titledesc {Docstrip-related utilities}] [category {Documentation tools}] @@ -369,10 +384,25 @@ At the time of writing, no project has employed [package doctools] markup in master source files, so experience of what works well is not available. A source file could however look as follows [example { % [manpage_begin gcd n 1.0] +[see_also docstrip] +[see_also doctools] +[see_also doctools_fmt] +[keywords .ddt] +[keywords catalogue] +[keywords diff] +[keywords docstrip] +[keywords doctools] +[keywords documentation] +[keywords {literate programming}] +[keywords module] +[keywords {package indexing}] +[keywords patch] +[keywords source] +[keywords {Tcl module}] % [moddesc {Greatest Common Divisor}] % [require gcd [opt 1.0]] % [description] % % [list_begin definitions] @@ -561,12 +591,6 @@ type of a line and the second is the actual line contents. The type is [const -] for lines only in the "from" file, [const +] for lines that are only in the "to" file, and [const 0] for lines that are in both. [list_end] - -[see_also docstrip doctools doctools_fmt] - -[keywords documentation source {literate programming} docstrip] -[keywords doctools .ddt diff patch] -[keywords {package indexing} {Tcl module} module catalogue] [manpage_end] Index: modules/doctools/changelog.man ================================================================== --- modules/doctools/changelog.man +++ modules/doctools/changelog.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::changelog n 1.1] +[keywords changelog] +[keywords doctools] +[keywords emacs] [copyright {2003-2013 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Processing text in Emacs ChangeLog format}] [category {Documentation tools}] [require Tcl 8.2] @@ -9,11 +12,10 @@ [require doctools::changelog [opt 1.1]] [description] This package provides Tcl commands for the processing and reformatting of text in the [file ChangeLog] format generated by [syscmd emacs]. - [section API] [list_begin definitions] @@ -49,11 +51,10 @@ } {...} } }] - [call [cmd ::doctools::changelog::flatten] [arg entries]] This command converts a list of entries as generated by [cmd change::scan] above into a simpler list of plain text blocks each containing all the information of a @@ -69,11 +70,10 @@ [para] The other three arguments supply the information for the header of that document which is not available from the changelog itself. - [call [cmd ::doctools::changelog::merge] [arg entries]...] Each argument of the command is assumed to be a pre-parsed Changelog as generated by the command [cmd ::doctools::changelog::scan]. This command merges all of them into a single structure, and collapses @@ -80,18 +80,8 @@ multiple entries for the same date and author into a single entry. The new structure is returned as the result of the command. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords changelog emacs doctools] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/cvs.man ================================================================== --- modules/doctools/cvs.man +++ modules/doctools/cvs.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::cvs n 1] +[see_also {[uri}] +[see_also http://wiki.tcl.tk/log2changelog] +[keywords changelog] +[keywords cvs] +[keywords {cvs log}] +[keywords emacs] +[keywords log] [copyright {2003-2008 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Processing text in 'cvs log' format}] [category {Documentation tools}] [require Tcl 8.2] @@ -16,11 +23,10 @@ The commands [cmd ::doctools::cvs::scanLog] and [cmd ::doctools::cvs::toChangeLog] are derived from code found on the [uri http://wiki.tcl.tk {Tcl'ers Wiki}]. See the references at the end of the page. - [section API] [list_begin definitions] @@ -55,20 +61,18 @@ Each item in the list is a list containing two elements, the date of the entry, and its author, in this order. The date is formatted as [var year]/[var month]/[var day]. - [arg_def varname cvar in] Has to refer to an array variable. Keys are strings containing the date and author of log entries, in this order, separated by a comma. [para] The values are lists of comments made for the entry. - [arg_def varname fvar in] Has to refer to an array variable. Keys are strings containing date, author of a log entry, and a comment for that entry, in this @@ -79,11 +83,10 @@ The values are lists of the files the entry is touching. [list_end] [para] - [call [cmd ::doctools::cvs::toChangeLog] [arg evar] [arg cvar] [arg fvar]]] The three arguments for this command are the same as the last three arguments of the command [cmd ::doctools::cvs::scanLog]. This command however expects them to be filled with information about one or more @@ -91,19 +94,8 @@ format of a ChangeLog as accepted and generated by [syscmd emacs]. The constructed text is returned as the result of the command. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also [uri http://wiki.tcl.tk/log2changelog]] -[keywords changelog cvs log {cvs log} emacs] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/docidx.man ================================================================== --- modules/doctools/docidx.man +++ modules/doctools/docidx.man @@ -1,7 +1,24 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::idx n 1.0.4] +[see_also docidx_intro] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[see_also docidx_plugin_apiref] +[keywords conversion] +[keywords docidx] +[keywords documentation] +[keywords HTML] +[keywords index] +[keywords {keyword index}] +[keywords latex] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] +[keywords wiki] [copyright {2003-2010 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {docidx - Processing indices}] [category {Documentation tools}] [require Tcl 8.2] @@ -26,11 +43,10 @@ engine for some format, i.e. is a [term {plugin writer}] then reading and understanding the [term {docidx plugin API reference}] is an absolute necessity, as that document specifies the interaction between this package and its plugins, i.e. the formatting engines, in detail. - [section {PUBLIC API}] [subsection {PACKAGE COMMANDS}] [list_begin definitions] @@ -46,18 +62,16 @@ [para] The options and their values coming after the name of the object are used to set the initial configuration of the object. - [call [cmd ::doctools::idx::help]] This is a convenience command for applications wishing to provide their user with a short description of the available formatting commands and their meanings. It returns a string containing a standard help text. - [call [cmd ::doctools::idx::search] [arg path]] Whenever an object created by this the package has to map the name of a format to the file containing the code for its formatting engine it @@ -80,11 +94,10 @@ An error will be thrown if the [arg path] either does not exist, is not a directory, or is not readable. [list_end] - [subsection {OBJECT COMMAND}] All commands created by [cmd ::doctools::idx::new] have the following general form and may be used to invoke various operations on their docidx converter object. @@ -97,27 +110,24 @@ behavior of the command. See section [sectref {OBJECT METHODS}] for the detailed specifications. [list_end] - [subsection {OBJECT METHODS}] [list_begin definitions] [call [arg objectName] [method configure]] The method returns a list of all known options and their current values when called without any arguments. - [call [arg objectName] [method configure] [arg option]] The method behaves like the method [method cget] when called with a single argument and returns the value of the option specified by said argument. - [call [arg objectName] [method configure] [option -option] [arg value]...] The method reconfigures the specified [option option]s of the object, setting them to the associated [arg value]s, when called with an even @@ -126,11 +136,10 @@ [para] The legal options are described in the section [sectref {OBJECT CONFIGURATION}]. - [call [arg objectName] [method cget] [option -option]] This method expects a legal configuration option as argument and will return the current value of that option for the object the method was invoked for. @@ -138,15 +147,13 @@ [para] The legal configuration options are described in section [sectref {OBJECT CONFIGURATION}]. - [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method format] [arg text]] This method runs the [arg text] through the configured formatting engine and returns the generated string as its result. An error will @@ -155,11 +162,10 @@ [para] The method assumes that the [arg text] is in [term docidx] format as specified in the companion document [term docidx_fmt]. Errors will be thrown otherwise. - [call [arg objectName] [method map] [arg symbolic] [arg actual]] This methods add one entry to the per-object mapping from [arg symbolic] filenames to the [arg actual] uris. @@ -170,28 +176,25 @@ This command is described in more detail in the [term {docidx plugin API reference}] which specifies the interaction between the objects created by this package and index formatting engines. - [call [arg objectName] [method parameters]] This method returns a list containing the names of all engine parameters provided by the configured formatting engine. It will return an empty list if the object is not yet configured for a specific format. - [call [arg objectName] [method search] [arg path]] This method extends the per-object list of paths searched for index formatting engines. See also the command [cmd ::doctools::idx::search] on how to extend the per-package list of paths. Note that the path entered last will be searched first. For more details see section [sectref {FORMAT MAPPING}]. - [call [arg objectName] [method setparam] [arg name] [arg value]] This method sets the [arg name]d engine parameter to the specified [arg value]. @@ -201,19 +204,17 @@ format does not provide a parameter with the given [arg name]. The list of parameters provided by the configured formatting engine can be retrieved through the method [method parameters]. - [call [arg objectName] [method warnings]] This method returns a list containing all the warnings which were generated by the configured formatting engine during the last invocation of the method [method format]. [list_end] - [subsection {OBJECT CONFIGURATION}] All docidx objects understand the following configuration options: @@ -235,11 +236,10 @@ [para] The configured formatting engine should interpret the value as the name of the file containing the document which is currently processed. - [opt_def -format [arg text]] The argument of this option specifies the format to generate and by implication the formatting engine to use when converting text via the method [method format]. Its default value is the empty string. The @@ -257,11 +257,10 @@ The section [sectref {FORMAT MAPPING}] explains in detail how the package and object will look for engine implementations. [list_end] - [subsection {FORMAT MAPPING}] The package and object will perform the following algorithm when trying to map a format name [term foo] to a file containing an @@ -309,11 +308,10 @@ The mapping fails. [list_end] - [section {PREDEFINED ENGINES}] The package provides predefined formatting engines for the following formats. Some of the formatting engines support engine parameters. These will be explicitly highlighted. @@ -347,11 +345,10 @@ [para] This can be used to insert boilerplate header markup into the generated document. - [def meta] The value for this parameter has to be valid selfcontained HTML markup for the header section of a HTML document. The default value is the @@ -400,26 +397,8 @@ This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also docidx_intro] -[see_also docidx_lang_intro] -[see_also docidx_lang_syntax] -[see_also docidx_lang_cmdref] -[see_also docidx_plugin_apiref] -[keywords documentation manpage TMML HTML nroff conversion markup] -[keywords nroff latex wiki docidx index {keyword index}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/docidx_intro.man ================================================================== --- modules/doctools/docidx_intro.man +++ modules/doctools/docidx_intro.man @@ -1,7 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin docidx_intro n 1.0] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_faq] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[see_also docidx_plugin_apiref] +[see_also doctoc_intro] +[see_also doctools::idx] +[see_also doctools_intro] +[keywords index] +[keywords {keyword index}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {docidx introduction}] [category {Documentation tools}] [description] @@ -87,26 +99,8 @@ They are described in their own sets of documents, starting at the [term {doctoc introduction}] and the [term {doctools introduction}], respectively. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also docidx_lang_intro] -[see_also docidx_lang_syntax] -[see_also docidx_lang_cmdref] -[see_also docidx_lang_faq] -[see_also doctools::idx] -[see_also docidx_plugin_apiref] -[see_also doctools_intro] -[see_also doctoc_intro] -[keywords markup {semantic markup}] -[keywords index {keyword index}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/docidx_lang_cmdref.man ================================================================== --- modules/doctools/docidx_lang_cmdref.man +++ modules/doctools/docidx_lang_cmdref.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin docidx_lang_cmdref n 1.0] +[see_also docidx_intro] +[see_also docidx_lang_faq] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[keywords {docidx commands}] +[keywords {docidx language}] +[keywords {docidx markup}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {docidx language command reference}] [category {Documentation tools}] [description] @@ -13,11 +22,10 @@ As this document is intended to be a reference the commands are listed in alphabetical order, and the descriptions are relatively short. A beginner should read the much more informally written [term {docidx language introduction}] first. - [section Commands] [list_begin definitions] [call [cmd comment] [arg plaintext]] @@ -101,23 +109,8 @@ Templating. In this form the command is replaced by the value of the named document variable [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also docidx_intro] -[see_also docidx_lang_intro] -[see_also docidx_lang_syntax] -[see_also docidx_lang_faq] -[keywords markup {semantic markup}] -[keywords {docidx markup} {docidx language} {docidx commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/docidx_lang_faq.man ================================================================== --- modules/doctools/docidx_lang_faq.man +++ modules/doctools/docidx_lang_faq.man @@ -1,71 +1,28 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin docidx_lang_faq n 1.0] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[keywords {docidx commands}] +[keywords {docidx language}] +[keywords {docidx markup}] +[keywords {docidx syntax}] +[keywords examples] +[keywords faq] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {docidx language faq}] [category {Documentation tools}] [description] -[para] +[vset theformat docidx] [section OVERVIEW] -[subsection {What is this document?}] - -This document is currently mainly a placeholder, to be filled with -commonly asked questions about the docidx markup language and -companions, and their answers. - -[para] - -Please report any questions (and, if possible, answers) we should -consider for this document in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -[section EXAMPLES] - -[subsection {Where do I find docidx examples?}] - -We have no direct examples of documents written using docidx -markup. However the doctools processor [syscmd dtplite] does generate -keyword indices when processing a set of documents written in doctools -markup. The intermediate files use docidx markup and are not deleted -when generation completes. These files can therefore serve as -examples. - -[para] - -[syscmd dtplite] is distributed as part of Tcllib, so to get it you -need one of - -[list_begin enumerated] - -[enum] -A CVS snapshot of Tcllib. How to retrieve such a snapshot and the -tools required for this are described at -[uri http://sourceforge.net/cvs/?group_id=12883] - -[enum] -A Tcllib release archive. They are available at -[uri http://sourceforge.net/project/showfiles.php?group_id=12883] - -[list_end] - - - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report any such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -the package and/or the documentation. - -[see_also docidx_lang_intro] -[see_also docidx_lang_syntax] -[see_also docidx_lang_cmdref] -[keywords examples faq markup {semantic markup}] -[keywords {docidx markup} {docidx language}] -[keywords {docidx syntax} {docidx commands}] +[include include/placeholder.inc] +[include include/examples.inc] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/docidx_lang_intro.man ================================================================== --- modules/doctools/docidx_lang_intro.man +++ modules/doctools/docidx_lang_intro.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin docidx_lang_intro n 1.0] +[see_also docidx_intro] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_syntax] +[keywords {docidx commands}] +[keywords {docidx language}] +[keywords {docidx markup}] +[keywords {docidx syntax}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007-2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {docidx language introduction}] [category {Documentation tools}] [description] @@ -111,11 +120,10 @@ [cmd manpage] it uses explicit (possibly format-specific) urls to describe the location of the referenced document. As such this command is intended for the creation of references to external documents which could not be handled in any other way. - [subsection {Advanced structure}] In all previous examples we fudged a bit regarding the markup actually allowed to be used before the [cmd index_begin] command opening the document. @@ -151,11 +159,10 @@ the included file must be valid at the place of the inclusion. I.e. a file included before [cmd index_begin] may contain only the templating commands [cmd vset] and [cmd include], a file included after a key may contain only manape or url references, and other keys, etc. - [subsection Escapes] Beyond the 6 commands shown so far we have two more available. However their function is not the marking up of index structure, but @@ -175,11 +182,10 @@ These commands, [lb]cmd lb[rb] and [lb]cmd lb[rb] respectively, are required because our use of [lb][cmd lb][rb] and [lb][cmd rb][rb] to bracket markup commands makes it impossible to directly use [lb][cmd lb][rb] and [lb][cmd rb][rb] within the text. ... [example_end] - [section {FURTHER READING}] Now that this document has been digested the reader, assumed to be a [term writer] of documentation should be fortified enough to be able @@ -201,22 +207,8 @@ generation from doctools documents, and this is the route Tcllib's easy and simple [syscmd dtplite] goes, creating an index for a set of documents behind the scenes, without the writer having to do so on their own. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also docidx_intro] -[see_also docidx_lang_syntax] -[see_also docidx_lang_cmdref] -[keywords markup {semantic markup}] -[keywords {docidx markup} {docidx language}] -[keywords {docidx syntax} {docidx commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/docidx_lang_syntax.man ================================================================== --- modules/doctools/docidx_lang_syntax.man +++ modules/doctools/docidx_lang_syntax.man @@ -1,7 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin docidx_lang_syntax n 1.0] +[see_also docidx_intro] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_faq] +[see_also docidx_lang_intro] +[keywords {docidx commands}] +[keywords {docidx language}] +[keywords {docidx markup}] +[keywords {docidx syntax}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007-2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {docidx language syntax}] [category {Documentation tools}] [description] @@ -13,11 +23,10 @@ [term {docidx language command reference}]. A beginner should read the much more informally written [term {docidx language introduction}] first before trying to understand either this document or the command reference. - [section Fundamentals] In the broadest terms possible the [term {docidx markup language}] is like SGML and similar languages. A document written in this language @@ -61,11 +70,11 @@ The rules listed here specify only the syntax of docidx documents. The lexical level of the language was covered in the previous section. [para] -Regarding the syntax of the (E)BNF itself +Regarding the syntax of the (E)BNF itself [list_begin enumerated] [enum] The construct { X } stands for zero or more occurrences of X. [enum] @@ -76,11 +85,11 @@ [example { index = defs INDEX_BEGIN [ contents ] - INDEX_END + INDEX_END { } defs = { INCLUDE | VSET | } contents = keyword { keyword } @@ -104,23 +113,8 @@ [enum][cmd vset] (1-argument form). [list_end] [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also docidx_intro] -[see_also docidx_lang_intro] -[see_also docidx_lang_cmdref] -[see_also docidx_lang_faq] -[keywords markup {semantic markup}] -[keywords {docidx markup} {docidx language}] -[keywords {docidx syntax} {docidx commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/docidx_plugin_apiref.man ================================================================== --- modules/doctools/docidx_plugin_apiref.man +++ modules/doctools/docidx_plugin_apiref.man @@ -1,7 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin docidx_plugin_apiref n 1.0] +[see_also docidx_intro] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_faq] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[see_also doctools::idx] +[keywords {formatting engine}] +[keywords index] +[keywords {index formatter}] +[keywords keywords] +[keywords markup] +[keywords plugin] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {docidx plugin API reference}] [category {Documentation tools}] [description] @@ -28,12 +41,10 @@ [term {docidx language introduction}] and proceed from there to the formal specifications, i.e. the [term {docidx language syntax}] and the [term {docidx language command reference}]. - - [section OVERVIEW] The API for an index formatting engine consists of two major sections. [para] @@ -50,12 +61,10 @@ sequence while processing input. They, again, fall into two categories, management and formatting. Please see section [sectref {PLUGIN COMMANDS}] and its subsections for their detailed specification. - - [section {FRONTEND COMMANDS}] This section specifies the set of commands through which a plugin, also known as an index formatting engine, is able to query the @@ -165,21 +174,17 @@ in the output text. If [arg newbracket] is specified, it becomes the new bracket, and is returned. [list_end] - - [section {PLUGIN COMMANDS}] The plugin has to provide its own set of commands which will then be called by the frontend in a specific sequence while processing input. They fall into two categories, management and formatting. Their expected names, signatures, and responsibilities are specified in the following two subsections. - - [subsection {Management commands}] The management commands a plugin has to provide are used by the frontend to @@ -274,20 +279,18 @@ It has to initialize the general state of the plugin, beyond the initialization done during the load. No return value is expected, and any returned value is ignored. - [call [cmd idx_listvariables]] [emph Initialization/Shutdown] and [emph {Engine parameters}]. Second command is called after the plugin code has been loaded, i.e. immediately after [cmd idx_numpasses]. It has to return a list containing the names of the parameters the frontend can set to configure the engine. This list can be empty. - [call [cmd idx_numpasses]] [emph Initialization/Shutdown] and [emph {Pass management}]. First command called after the plugin code has been loaded. No other @@ -294,11 +297,10 @@ command of the engine will be called before it. It has to return the number of passes this engine requires to fully process the input document. This value has to be an integer number greater or equal to one. - [call [cmd idx_postprocess] [arg text]] [emph Initialization/Shutdown]. This command is called immediately after the last pass in a run. Its @@ -309,11 +311,10 @@ [para] Expected to return a value, the final result of formatting the input. - [call [cmd idx_setup] [arg n]] [emph Initialization/Shutdown] and [emph {Pass management}]. This command is called at the beginning of each pass over the input in a run. Its argument is the number of the pass which has begun. Passes @@ -320,11 +321,10 @@ are counted from [const 1] upward. The command has to set up the internal state of the plugin for this particular pass. No return value is expected, and any returned value is ignored. - [call [cmd idx_shutdown]] [emph Initialization/Shutdown]. This command is called at the end of every conversion run. It is the @@ -334,11 +334,10 @@ After the call the engine has to be in a state which allows the initiation of another run without fear that information from the last run is leaked into this new run. No return value is expected, and any returned value is ignored. - [call [cmd idx_varset] [arg varname] [arg text]] [emph {Engine parameters}]. This command is called by the frontend to set an engine parameter to a @@ -357,12 +356,10 @@ The values of all engine parameters have to persist between passes and runs. [list_end] - - [subsection {Formatting commands}] The formatting commands have to implement the formatting for the output format, for all the markup commands of the docidx markup @@ -417,25 +414,8 @@ and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] - - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also docidx_intro] -[see_also docidx_lang_intro] -[see_also docidx_lang_syntax] -[see_also docidx_lang_cmdref] -[see_also docidx_lang_faq] -[see_also doctools::idx] -[keywords markup {semantic markup} plugin keywords index] -[keywords {formatting engine} {index formatter}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctoc.man ================================================================== --- modules/doctools/doctoc.man +++ modules/doctools/doctoc.man @@ -1,7 +1,24 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::toc n 1.1.3] +[see_also doctoc_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[see_also doctoc_plugin_apiref] +[keywords conversion] +[keywords doctoc] +[keywords documentation] +[keywords HTML] +[keywords latex] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords {table of contents}] +[keywords TMML] +[keywords toc] +[keywords wiki] [copyright {2003-2010 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctoc - Processing tables of contents}] [category {Documentation tools}] [require Tcl 8.2] @@ -26,11 +43,10 @@ engine for some format, i.e. is a [term {plugin writer}] then reading and understanding the [term {doctoc plugin API reference}] is an absolute necessity, as that document specifies the interaction between this package and its plugins, i.e. the formatting engines, in detail. - [section {PUBLIC API}] [subsection {PACKAGE COMMANDS}] [list_begin definitions] @@ -46,18 +62,16 @@ [para] The options and their values coming after the name of the object are used to set the initial configuration of the object. - [call [cmd ::doctools::toc::help]] This is a convenience command for applications wishing to provide their user with a short description of the available formatting commands and their meanings. It returns a string containing a standard help text. - [call [cmd ::doctools::toc::search] [arg path]] Whenever an object created by this the package has to map the name of a format to the file containing the code for its formatting engine it @@ -80,11 +94,10 @@ An error will be thrown if the [arg path] either does not exist, is not a directory, or is not readable. [list_end] - [subsection {OBJECT COMMAND}] All commands created by [cmd ::doctools::toc::new] have the following general form and may be used to invoke various operations on their doctoc converter object. @@ -97,27 +110,24 @@ behavior of the command. See section [sectref {OBJECT METHODS}] for the detailed specifications. [list_end] - [subsection {OBJECT METHODS}] [list_begin definitions] [call [arg objectName] [method configure]] The method returns a list of all known options and their current values when called without any arguments. - [call [arg objectName] [method configure] [arg option]] The method behaves like the method [method cget] when called with a single argument and returns the value of the option specified by said argument. - [call [arg objectName] [method configure] [option -option] [arg value]...] The method reconfigures the specified [option option]s of the object, setting them to the associated [arg value]s, when called with an even @@ -126,11 +136,10 @@ [para] The legal options are described in the section [sectref {OBJECT CONFIGURATION}]. - [call [arg objectName] [method cget] [option -option]] This method expects a legal configuration option as argument and will return the current value of that option for the object the method was invoked for. @@ -138,15 +147,13 @@ [para] The legal configuration options are described in section [sectref {OBJECT CONFIGURATION}]. - [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method format] [arg text]] This method runs the [arg text] through the configured formatting engine and returns the generated string as its result. An error will @@ -155,11 +162,10 @@ [para] The method assumes that the [arg text] is in [term doctoc] format as specified in the companion document [term doctoc_fmt]. Errors will be thrown otherwise. - [call [arg objectName] [method map] [arg symbolic] [arg actual]] This methods add one entry to the per-object mapping from [arg symbolic] filenames to the [arg actual] uris. @@ -170,28 +176,25 @@ This command is described in more detail in the [term {doctoc plugin API reference}] which specifies the interaction between the objects created by this package and toc formatting engines. - [call [arg objectName] [method parameters]] This method returns a list containing the names of all engine parameters provided by the configured formatting engine. It will return an empty list if the object is not yet configured for a specific format. - [call [arg objectName] [method search] [arg path]] This method extends the per-object list of paths searched for toc formatting engines. See also the command [cmd ::doctools::toc::search] on how to extend the per-package list of paths. Note that the path entered last will be searched first. For more details see section [sectref {FORMAT MAPPING}]. - [call [arg objectName] [method setparam] [arg name] [arg value]] This method sets the [arg name]d engine parameter to the specified [arg value]. @@ -201,19 +204,17 @@ format does not provide a parameter with the given [arg name]. The list of parameters provided by the configured formatting engine can be retrieved through the method [method parameters]. - [call [arg objectName] [method warnings]] This method returns a list containing all the warnings which were generated by the configured formatting engine during the last invocation of the method [method format]. [list_end] - [subsection {OBJECT CONFIGURATION}] All doctoc objects understand the following configuration options: @@ -235,11 +236,10 @@ [para] The configured formatting engine should interpret the value as the name of the file containing the document which is currently processed. - [opt_def -format [arg text]] The argument of this option specifies the format to generate and by implication the formatting engine to use when converting text via the method [method format]. Its default value is the empty string. The @@ -257,11 +257,10 @@ The section [sectref {FORMAT MAPPING}] explains in detail how the package and object will look for engine implementations. [list_end] - [subsection {FORMAT MAPPING}] The package and object will perform the following algorithm when trying to map a format name [term foo] to a file containing an @@ -309,11 +308,10 @@ The mapping fails. [list_end] - [section {PREDEFINED ENGINES}] The package provides predefined formatting engines for the following formats. Some of the formatting engines support engine parameters. These will be explicitly highlighted. @@ -347,11 +345,10 @@ [para] This can be used to insert boilerplate header markup into the generated document. - [def meta] The value for this parameter has to be valid selfcontained HTML markup for the header section of a HTML document. The default value is the @@ -400,25 +397,8 @@ This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also doctoc_intro] -[see_also doctoc_lang_intro] -[see_also doctoc_lang_syntax] -[see_also doctoc_lang_cmdref] -[see_also doctoc_plugin_apiref] -[keywords documentation manpage TMML HTML nroff conversion markup] -[keywords nroff latex wiki doctoc toc {table of contents}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_intro.man ================================================================== --- modules/doctools/doctoc_intro.man +++ modules/doctools/doctoc_intro.man @@ -1,7 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctoc_intro n 1.0] +[see_also docidx_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_faq] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[see_also doctoc_plugin_apiref] +[see_also doctools::toc] +[see_also doctools_intro] +[keywords markup] +[keywords {semantic markup}] +[keywords {table of contents}] +[keywords toc] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctoc introduction}] [category {Documentation tools}] [description] @@ -86,26 +98,8 @@ They are described in their own sets of documents, starting at the [term {docidx introduction}] and the [term {doctools introduction}], respectively. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also doctoc_lang_intro] -[see_also doctoc_lang_syntax] -[see_also doctoc_lang_cmdref] -[see_also doctoc_lang_faq] -[see_also doctools::toc] -[see_also doctoc_plugin_apiref] -[see_also doctools_intro] -[see_also docidx_intro] -[keywords markup {semantic markup}] -[keywords toc {table of contents}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_lang_cmdref.man ================================================================== --- modules/doctools/doctoc_lang_cmdref.man +++ modules/doctools/doctoc_lang_cmdref.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctoc_lang_cmdref n 1.0] +[see_also doctoc_intro] +[see_also doctoc_lang_faq] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[keywords {doctoc commands}] +[keywords {doctoc language}] +[keywords {doctoc markup}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctoc language command reference}] [category {Documentation tools}] [description] @@ -14,14 +23,12 @@ in alphabetical order, and the descriptions are relatively short. A beginner should read the much more informally written [term {doctoc language introduction}] first. - [section Commands] [list_begin definitions] - [call [cmd comment] [arg plaintext]] Toc markup. The argument text is marked up as a comment standing outside of the actual text of the document. Main use is in free-form @@ -113,23 +120,8 @@ Templating. In this form the command is replaced by the value of the named document variable [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also doctoc_intro] -[see_also doctoc_lang_intro] -[see_also doctoc_lang_syntax] -[see_also doctoc_lang_faq] -[keywords markup {semantic markup}] -[keywords {doctoc markup} {doctoc language} {doctoc commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_lang_faq.man ================================================================== --- modules/doctools/doctoc_lang_faq.man +++ modules/doctools/doctoc_lang_faq.man @@ -1,71 +1,28 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctoc_lang_faq n 1.0] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[keywords {doctoc commands}] +[keywords {doctoc language}] +[keywords {doctoc markup}] +[keywords {doctoc syntax}] +[keywords examples] +[keywords faq] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctoc language faq}] [category {Documentation tools}] [description] -[para] +[vset theformat doctoc] [section OVERVIEW] -[subsection {What is this document?}] - -This document is currently mainly a placeholder, to be filled with -commonly asked questions about the doctoc markup language and -companions, and their answers. - -[para] - -Please report any questions (and, if possible, answers) we should -consider for this document in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -[section EXAMPLES] - -[subsection {Where do I find doctoc examples?}] - -We have no direct examples of documents written using doctoc -markup. However the doctools processor [syscmd dtplite] does generate -a table of contents when processing a set of documents written in -doctools markup. The intermediate file for it uses doctoc markup and -is not deleted when generation completes. Such files can therefore -serve as examples. - -[para] - -[syscmd dtplite] is distributed as part of Tcllib, so to get it you -need one of - -[list_begin enumerated] - -[enum] -A CVS snapshot of Tcllib. How to retrieve such a snapshot and the -tools required for this are described at -[uri http://sourceforge.net/cvs/?group_id=12883] - -[enum] -A Tcllib release archive. They are available at -[uri http://sourceforge.net/project/showfiles.php?group_id=12883] - -[list_end] - - - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report any such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -the package and/or the documentation. - -[see_also doctoc_lang_intro] -[see_also doctoc_lang_syntax] -[see_also doctoc_lang_cmdref] -[keywords examples faq markup {semantic markup}] -[keywords {doctoc markup} {doctoc language}] -[keywords {doctoc syntax} {doctoc commands}] +[include include/placeholder.inc] +[include include/examples.inc] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_lang_intro.man ================================================================== --- modules/doctools/doctoc_lang_intro.man +++ modules/doctools/doctoc_lang_intro.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctoc_lang_intro n 1.0] +[see_also doctoc_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_syntax] +[keywords {doctoc commands}] +[keywords {doctoc language}] +[keywords {doctoc markup}] +[keywords {doctoc syntax}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctoc language introduction}] [category {Documentation tools}] [description] @@ -58,11 +67,10 @@ [para] We will discuss the commands for each of these two possibilities in the next sections. - [subsection Items] Use the command [cmd item] to put an [term item] into a table of contents. This is essentially a reference to a section, subsection, @@ -195,11 +203,10 @@ [lb][cmd {division_start {FURTHER READING}}][rb] [lb][cmd {division_end}][rb] [lb]toc_end[rb] [example_end] - [subsection {Advanced structure}] In all previous examples we fudged a bit regarding the markup actually allowed to be used before the [cmd toc_begin] command opening the document. @@ -235,11 +242,10 @@ the included file must be valid at the place of the inclusion. I.e. a file included before [cmd toc_begin] may contain only the templating commands [cmd vset] and [cmd include], a file included in a division may contain only items or divisions commands, etc. - [subsection Escapes] Beyond the 6 commands shown so far we have two more available. However their function is not the marking up of toc structure, but the @@ -259,11 +265,10 @@ These commands, [lb]cmd lb[rb] and [lb]cmd lb[rb] respectively, are required because our use of [lb][cmd lb][rb] and [lb][cmd rb][rb] to bracket markup commands makes it impossible to directly use [lb][cmd lb][rb] and [lb][cmd rb][rb] within the text. ... [example_end] - [section {FURTHER READING}] Now that this document has been digested the reader, assumed to be a [term writer] of documentation should be fortified enough to be able @@ -285,22 +290,8 @@ generation from doctools documents, and this is the route Tcllib's easy and simple [syscmd dtplite] goes, creating a table of contents for a set of documents behind the scenes, without the writer having to do so on their own. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also doctoc_intro] -[see_also doctoc_lang_syntax] -[see_also doctoc_lang_cmdref] -[keywords markup {semantic markup}] -[keywords {doctoc markup} {doctoc language}] -[keywords {doctoc syntax} {doctoc commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_lang_syntax.man ================================================================== --- modules/doctools/doctoc_lang_syntax.man +++ modules/doctools/doctoc_lang_syntax.man @@ -1,7 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctoc_lang_syntax n 1.0] +[see_also doctoc_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_faq] +[see_also doctoc_lang_intro] +[keywords {doctoc commands}] +[keywords {doctoc language}] +[keywords {doctoc markup}] +[keywords {doctoc syntax}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007-2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctoc language syntax}] [category {Documentation tools}] [description] @@ -13,11 +23,10 @@ [term {doctoc language command reference}]. A beginner should read the much more informally written [term {doctoc language introduction}] first before trying to understand either this document or the command reference. - [section Fundamentals] In the broadest terms possible the [term {doctoc markup language}] is like SGML and similar languages. A document written in this language @@ -61,11 +70,11 @@ The rules listed here specify only the syntax of doctoc documents. The lexical level of the language was covered in the previous section. [para] -Regarding the syntax of the (E)BNF itself +Regarding the syntax of the (E)BNF itself [list_begin enumerated] [enum] The construct { X } stands for zero or more occurrences of X. [enum] @@ -76,11 +85,11 @@ [example { toc = defs TOC_BEGIN contents - TOC_END + TOC_END { } defs = { INCLUDE | VSET | } contents = { defs entry } [ defs ] @@ -89,23 +98,8 @@ division = DIVISION_START contents DIVISION_END }] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also doctoc_intro] -[see_also doctoc_lang_intro] -[see_also doctoc_lang_cmdref] -[see_also doctoc_lang_faq] -[keywords markup {semantic markup}] -[keywords {doctoc markup} {doctoc language}] -[keywords {doctoc syntax} {doctoc commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctoc_plugin_apiref.man ================================================================== --- modules/doctools/doctoc_plugin_apiref.man +++ modules/doctools/doctoc_plugin_apiref.man @@ -1,7 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctoc_plugin_apiref n 1.0] +[see_also doctoc_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_faq] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[see_also doctools::toc] +[keywords {formatting engine}] +[keywords markup] +[keywords plugin] +[keywords {semantic markup}] +[keywords {table of contents}] +[keywords toc] +[keywords {toc formatter}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctoc plugin API reference}] [category {Documentation tools}] [description] @@ -28,12 +41,10 @@ [term {doctoc language introduction}] and proceed from there to the formal specifications, i.e. the [term {doctoc language syntax}] and the [term {doctoc language command reference}]. - - [section OVERVIEW] The API for a toc formatting engine consists of two major sections. [para] @@ -50,12 +61,10 @@ sequence while processing input. They, again, fall into two categories, management and formatting. Please see section [sectref {PLUGIN COMMANDS}] and its subsections for their detailed specification. - - [section {FRONTEND COMMANDS}] This section specifies the set of commands through which a plugin, also known as a toc formatting engine, is able to query the @@ -173,12 +182,10 @@ called by the frontend in a specific sequence while processing input. They fall into two categories, management and formatting. Their expected names, signatures, and responsibilities are specified in the following two subsections. - - [subsection {Management commands}] The management commands a plugin has to provide are used by the frontend to @@ -272,20 +279,18 @@ It has to initialize the general state of the plugin, beyond the initialization done during the load. No return value is expected, and any returned value is ignored. - [call [cmd toc_listvariables]] [emph Initialization/Shutdown] and [emph {Engine parameters}]. Second command is called after the plugin code has been loaded, i.e. immediately after [cmd toc_numpasses]. It has to return a list containing the names of the parameters the frontend can set to configure the engine. This list can be empty. - [call [cmd toc_numpasses]] [emph Initialization/Shutdown] and [emph {Pass management}]. First command called after the plugin code has been loaded. No other @@ -292,11 +297,10 @@ command of the engine will be called before it. It has to return the number of passes this engine requires to fully process the input document. This value has to be an integer number greater or equal to one. - [call [cmd toc_postprocess] [arg text]] [emph Initialization/Shutdown]. This command is called immediately after the last pass in a run. Its @@ -307,11 +311,10 @@ [para] Expected to return a value, the final result of formatting the input. - [call [cmd toc_setup] [arg n]] [emph Initialization/Shutdown] and [emph {Pass management}]. This command is called at the beginning of each pass over the input in a run. Its argument is the number of the pass which has begun. Passes @@ -318,11 +321,10 @@ are counted from [const 1] upward. The command has to set up the internal state of the plugin for this particular pass. No return value is expected, and any returned value is ignored. - [call [cmd toc_shutdown]] [emph Initialization/Shutdown]. This command is called at the end of every conversion run. It is the @@ -332,11 +334,10 @@ After the call the engine has to be in a state which allows the initiation of another run without fear that information from the last run is leaked into this new run. No return value is expected, and any returned value is ignored. - [call [cmd toc_varset] [arg varname] [arg text]] [emph {Engine parameters}]. This command is called by the frontend to set an engine parameter to a @@ -355,12 +356,10 @@ The values of all engine parameters have to persist between passes and runs. [list_end] - - [subsection {Formatting commands}] The formatting commands have to implement the formatting for the output format, for all the markup commands of the doctoc markup @@ -415,25 +414,8 @@ and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] - - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also doctoc_intro] -[see_also doctoc_lang_intro] -[see_also doctoc_lang_syntax] -[see_also doctoc_lang_cmdref] -[see_also doctoc_lang_faq] -[see_also doctools::toc] -[keywords markup {semantic markup} plugin toc {table of contents}] -[keywords {formatting engine} {toc formatter}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctools.man ================================================================== --- modules/doctools/doctools.man +++ modules/doctools/doctools.man @@ -1,7 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools n 1.4.16] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[see_also doctools_plugin_apiref] +[keywords conversion] +[keywords documentation] +[keywords HTML] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] [copyright {2003-2013 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctools - Processing documents}] [category {Documentation tools}] [require Tcl 8.2] @@ -26,11 +38,10 @@ engine for some format, i.e. is a [term {plugin writer}] then reading and understanding the [term {doctools plugin API reference}] is an absolute necessity, as that document specifies the interaction between this package and its plugins, i.e. the formatting engines, in detail. - [section {PUBLIC API}] [subsection {PACKAGE COMMANDS}] [list_begin definitions] @@ -46,18 +57,16 @@ [para] The options and their values coming after the name of the object are used to set the initial configuration of the object. - [call [cmd ::doctools::help]] This is a convenience command for applications wishing to provide their user with a short description of the available formatting commands and their meanings. It returns a string containing a standard help text. - [call [cmd ::doctools::search] [arg path]] Whenever an object created by this the package has to map the name of a format to the file containing the code for its formatting engine it @@ -79,11 +88,10 @@ An error will be thrown if the [arg path] either does not exist, is not a directory, or is not readable. [list_end] - [subsection {OBJECT COMMAND}] All commands created by [cmd ::doctools::new] have the following general form and may be used to invoke various operations on their @@ -106,17 +114,15 @@ [call [arg objectName] [method configure]] The method returns a list of all known options and their current values when called without any arguments. - [call [arg objectName] [method configure] [arg option]] The method behaves like the method [method cget] when called with a single argument and returns the value of the option specified by said argument. - [call [arg objectName] [method configure] [option -option] [arg value]...] The method reconfigures the specified [option option]s of the object, setting them to the associated [arg value]s, when called with an even @@ -124,11 +130,10 @@ [para] The legal options are described in the section [sectref {OBJECT CONFIGURATION}]. - [call [arg objectName] [method cget] [option -option]] This method expects a legal configuration option as argument and will return the current value of that option for the object the method was @@ -137,15 +142,13 @@ [para] The legal configuration options are described in section [sectref {OBJECT CONFIGURATION}]. - [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method format] [arg text]] This method runs the [arg text] through the configured formatting engine and returns the generated string as its result. An error will @@ -154,11 +157,10 @@ [para] The method assumes that the [arg text] is in [term doctools] format as specified in the companion document [term doctools_fmt]. Errors will be thrown otherwise. - [call [arg objectName] [method map] [arg symbolic] [arg actual]] This methods add one entry to the per-object mapping from [arg symbolic] filenames to the [arg actual] uris. @@ -169,28 +171,25 @@ This command is described in more detail in the [term {doctools plugin API reference}] which specifies the interaction between the objects created by this package and doctools formatting engines. - [call [arg objectName] [method parameters]] This method returns a list containing the names of all engine parameters provided by the configured formatting engine. It will return an empty list if the object is not yet configured for a specific format. - [call [arg objectName] [method search] [arg path]] This method extends the per-object list of paths searched for doctools formatting engines. See also the command [cmd ::doctools::search] on how to extend the per-package list of paths. Note that the path entered last will be searched first. For more details see section [sectref {FORMAT MAPPING}]. - [call [arg objectName] [method setparam] [arg name] [arg value]] This method sets the [arg name]d engine parameter to the specified [arg value]. @@ -200,19 +199,17 @@ format does not provide a parameter with the given [arg name]. The list of parameters provided by the configured formatting engine can be retrieved through the method [method parameters]. - [call [arg objectName] [method warnings]] This method returns a list containing all the warnings which were generated by the configured formatting engine during the last invocation of the method [method format]. [list_end] - [subsection {OBJECT CONFIGURATION}] All doctools objects understand the following configuration options: @@ -235,11 +232,10 @@ [para] The configured formatting engine should interpret the value as the name of the file containing the document which is currently processed. - [opt_def -ibase [arg file]] The argument of this option is stored in the object and used as the base path for resolution of relative include paths. If this option is not set (empty string) the value of [option -file] is used instead. @@ -255,11 +251,10 @@ [para] The default value of this option is the empty string. - [opt_def -module [arg text]] The argument of this option is stored in the object and made available to the configured formatting engine through the command [cmd dt_module]. @@ -274,11 +269,10 @@ [para] The configured formatting engine should interpret the value as the name of the module the file containing the document which is currently processed belongs to. - [opt_def -format [arg text]] The argument of this option specifies the format to generate and by implication the formatting engine to use when converting text via the @@ -296,26 +290,23 @@ [para] The section [sectref {FORMAT MAPPING}] explains in detail how the package and object will look for engine implementations. - [opt_def -deprecated [arg boolean]] This option is a boolean flag. The object will generate warnings if this flag is set and the text given to method [method format] contains the deprecated markup command [cmd strong]. Its default value is [const FALSE]. In other words, no warnings will be generated. - [opt_def -copyright [arg text]] The argument of this option is stored in the object and made available to the configured formatting engine through the command [cmd dt_copyright]. - This command is described in more detail in the companion document [term doctools_api] which specifies the API between the object and formatting engines. @@ -325,20 +316,19 @@ [para] The configured formatting engine should interpret the value as a copyright assignment for the document which is currently processed, or -the package described by it. +the package described by it. [para] This information must be used if and only if the engine is unable to find any copyright assignments within the document itself. Such are specified by the formatting command [cmd copyright]. This command is described in more detail in the companion document [term doctools_fmt] which specifies the [term doctools] format itself. - [list_end] [subsection {FORMAT MAPPING}] @@ -391,11 +381,10 @@ The mapping fails. [list_end] - [section {PREDEFINED ENGINES}] The package provides predefined engines for the following formats. Some of the engines support parameters. These will be explained below as well. @@ -430,11 +419,10 @@ [para] This can be used to insert boilerplate header markup into the generated document. - [def meta] The value for this parameter has to be valid selfcontained HTML markup for the header section of a HTML document. The default value is the empty string. The value is inserted into the generated output just @@ -444,11 +432,10 @@ [para] This can be used to insert boilerplate meta data markup into the generated document, like references to a stylesheet, standard meta keywords, etc. - [def xref] The value for this parameter has to be a list of triples specifying cross-reference information. This information is used by the engine to @@ -478,47 +465,41 @@ The command will look for the patterns [const sa,][arg word], and [arg word], in this order. If this fails if it will convert [arg word] to all lowercase and try again. - [def "[cmd syscmd] [arg word]"] The command will look for the patterns [const sa,][arg word], and [arg word], in this order. If this fails if it will convert [arg word] to all lowercase and try again. - [def "[cmd term] [arg word]"] The command will look for the patterns [const kw,][arg word], [const sa,][arg word], and [arg word], in this order. If this fails if it will convert [arg word] to all lowercase and try again. - [def "[cmd package] [arg word]"] The command will look for the patterns [const sa,][arg word], [const kw,][arg word], and [arg word], in this order. If this fails if it will convert [arg word] to all lowercase and try again. - [def "[cmd see_also] [arg word]..."] The command will look for the patterns [const sa,][arg word], and [arg word], in this order, for each [arg word] given to the command. If this fails if it will convert [arg word] to all lowercase and try again. - [def "[cmd keywords] [arg word]..."] The command will look for the patterns [const kw,][arg word], and [arg word], in this order, for each [arg word] given to the command. If this fails if it will convert [arg word] to all lowercase and try again. - [list_end] [list_end] [para] @@ -554,25 +535,8 @@ This engine generates Wiki markup as understood by Jean Claude Wippler's [syscmd wikit] application. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also doctools_intro] -[see_also doctools_lang_intro] -[see_also doctools_lang_syntax] -[see_also doctools_lang_cmdref] -[see_also doctools_plugin_apiref] -[keywords documentation manpage TMML HTML nroff conversion markup] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctools_intro.man ================================================================== --- modules/doctools/doctools_intro.man +++ modules/doctools/doctools_intro.man @@ -1,7 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools_intro n 1.0] +[see_also docidx_intro] +[see_also doctoc_intro] +[see_also doctools] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[see_also doctools_plugin_apiref] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctools introduction}] [category {Documentation tools}] [description] @@ -86,25 +96,8 @@ They are described in their own sets of documents, starting at the [term {docidx introduction}] and the [term {doctoc introduction}], respectively. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also doctools_lang_intro] -[see_also doctools_lang_syntax] -[see_also doctools_lang_cmdref] -[see_also doctools_lang_faq] -[see_also doctools] -[see_also doctools_plugin_apiref] -[see_also doctoc_intro] -[see_also docidx_intro] -[keywords markup {semantic markup}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctools_lang_cmdref.man ================================================================== --- modules/doctools/doctools_lang_cmdref.man +++ modules/doctools/doctools_lang_cmdref.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools_lang_cmdref n 1.0] +[see_also doctools_intro] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007-2010 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctools language command reference}] [category {Documentation tools}] [description] @@ -13,11 +22,10 @@ As this document is intended to be a reference the commands are listed in alphabetical order, and the descriptions are relatively short. A beginner should read the much more informally written [term {doctools language introduction}] first. - [section Commands] [list_begin definitions] [call [cmd arg] [arg text]] @@ -56,17 +64,15 @@ It is expected that the formatted term is not only printed in place, but also in the table of contents of the document, or synopsis, depending on the output format. - [call [cmd category] [arg text]] Document information. Anywhere. This command registers its plain text arguments as the category this document belongs to. If this command is used multiple times the last value specified is used. - [call [cmd class] [arg text]] Text markup. The argument is marked up as the name of a [term class]. The text may have other markup already applied to @@ -251,17 +257,25 @@ [emph Deprecated]. Text structure. List element. Definition list. See [cmd def] for the canonical command to open a general list item in a definition list. [call [cmd manpage_begin] [arg command] [arg section] [arg version]] +[see_also doctools_intro] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords markup] +[keywords {semantic markup}] Document structure. The command to start a manpage. The arguments are the name of the [arg command] described by the manpage, the [arg section] of the manpages this manpage resides in, and the [arg version] of the module containing the command. All arguments have to be plain text, without markup. - [call [cmd manpage_end]] Document structure. Command to end a manpage/document. Anything in the document coming after this command is in error. @@ -351,11 +365,10 @@ [call [cmd sectref-external] [arg text]] Text markup. Like [cmd sectref], except that the section is assumed to be in a different document and therefore doesn't need to be identified, nor are any checks for existence made. Only the text to format is needed. - [call [cmd see_also] [arg args]] Document information. Anywhere. The command defines direct cross-references to other documents. Each argument is a plain text label identifying the @@ -450,23 +463,8 @@ [term widget]. The text may have other markup already applied to it. Main use is the highlighting of widget names in free-form text. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also doctools_intro] -[see_also doctools_lang_intro] -[see_also doctools_lang_syntax] -[see_also doctools_lang_faq] -[keywords markup {semantic markup}] -[keywords {doctools markup} {doctools language} {doctools commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctools_lang_faq.man ================================================================== --- modules/doctools/doctools_lang_faq.man +++ modules/doctools/doctools_lang_faq.man @@ -1,68 +1,28 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools_lang_faq n 1.0] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords examples] +[keywords faq] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctools language faq}] [category {Documentation tools}] [description] -[para] +[vset theformat doctools] [section OVERVIEW] -[subsection {What is this document?}] - -This document is currently mainly a placeholder, to be filled with -commonly asked questions about the doctools markup language and -companions, and their answers. - -[para] - -Please report any questions (and, if possible, answers) we should -consider for this document in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -[section EXAMPLES] - -[subsection {Where do I find doctools examples?}] - -The most examples of doctools markup currently known can be found in -the Tcllib and Tklib package bundles where basically the documentation -of all packages is written in it. - -In Tcllib you will also find the sources for the doctools -documentation themselves, which makes use of nearly all of the -available markup commands. - -You need one of - -[list_begin enumerated] - -[enum] -A CVS snapshot of Tcllib. How to retrieve such a snapshot and the -tools required for this are described at -[uri http://sourceforge.net/cvs/?group_id=12883] - -[enum] -A Tcllib release archive. They are available at -[uri http://sourceforge.net/project/showfiles.php?group_id=12883] - -[list_end] - - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report any such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -the package and/or the documentation. - -[see_also doctools_lang_intro] -[see_also doctools_lang_syntax] -[see_also doctools_lang_cmdref] -[keywords examples faq markup {semantic markup}] -[keywords {doctools markup} {doctools language}] -[keywords {doctools syntax} {doctools commands}] +[include include/placeholder.inc] +[include include/examples.inc] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctools_lang_intro.man ================================================================== --- modules/doctools/doctools_lang_intro.man +++ modules/doctools/doctools_lang_intro.man @@ -1,7 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools_lang_intro n 1.0] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctools language introduction}] [category {Documentation tools}] [description] @@ -43,19 +53,30 @@ [example { ... [opt "[arg key] [arg value]"] ... }] - [subsection {Basic structure}] The most simple document which can be written in doctools is [example { [manpage_begin NAME SECTION VERSION] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [description] - [manpage_end] + [vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] }] This also shows us that all doctools documents are split into two parts, the [term header] and the [term body]. Everything coming before [lb][cmd description][rb] belongs to the header, and everything coming @@ -97,10 +118,20 @@ Given the above a less minimal example of a document is [example_begin] [lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [lb][cmd {copyright {YEAR AUTHOR}}][rb] [lb][cmd {titledesc TITLE}][rb] [lb][cmd {moddesc MODULE_TITLE}][rb] [lb][cmd {require PACKAGE VERSION}][rb] [lb][cmd {require PACKAGE}][rb] @@ -110,13 +141,25 @@ Remember that the whitespace is optional. The document [example { [manpage_begin NAME SECTION VERSION] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] [require PACKAGE VERSION][require PACKAGE][description] - [manpage_end] + [vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] }] has the same meaning as the example before. [para] @@ -128,10 +171,20 @@ command. [example_begin] [lb][cmd {comment { ... }}][rb] [lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [lb]copyright {YEAR AUTHOR}[rb] [lb]titledesc TITLE[rb] [lb]moddesc MODULE_TITLE[rb][lb][cmd {comment { ... }}][rb] [lb]require PACKAGE VERSION[rb] [lb]require PACKAGE[rb] @@ -138,15 +191,24 @@ [lb]description[rb] [lb]manpage_end[rb] [lb][cmd {comment { ... }}][rb] [example_end] - [subsection {Advanced structure}] In the simple examples of the last section we fudged a bit regarding the markup actually allowed to be used before the [cmd manpage_begin] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] command opening the document. [para] Instead of only whitespace the two templating commands [cmd include] @@ -156,10 +218,20 @@ [example_begin] [lb][cmd {include FILE}][rb] [lb][cmd {vset VAR VALUE}][rb] [lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [lb]description[rb] [lb]manpage_end[rb] [example_end] Even more important, these two commands are allowed anywhere where a @@ -166,22 +238,41 @@ markup command is allowed, without regard for any other structure. I.e. for example in the header as well. [example_begin] [lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [lb][cmd {include FILE}][rb] [lb][cmd {vset VAR VALUE}][rb] [lb]description[rb] [lb]manpage_end[rb] [example_end] The only restriction [cmd include] has to obey is that the contents of the included file must be valid at the place of the inclusion. I.e. a file included before [cmd manpage_begin] may contain only the +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] templating commands [cmd vset] and [cmd include], a file included in the header may contain only header commands, etc. - [subsection {Text structure}] The body of the document consists mainly of text, possibly split into sections, subsections, and paragraphs, with parts marked up to @@ -202,10 +293,20 @@ of the body, by [cmd description]. In the same manner the last paragraph automatically ends at [cmd manpage_end]. [example_begin] [lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [lb]description[rb] ... [lb][cmd para][rb] ... [lb][cmd para][rb] @@ -231,10 +332,20 @@ Empty sections are [emph not] ignored. We are free to (not) use paragraphs within sections. [example_begin] [lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [lb]description[rb] ... [lb][cmd {section {Section A}}][rb] ... [lb]para[rb] @@ -258,10 +369,20 @@ Empty subsections are [emph not] ignored. We are free to (not) use paragraphs within subsections. [example_begin] [lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [lb]description[rb] ... [lb]section {Section A}[rb] ... [lb][cmd {subsection {Sub 1}}][rb] @@ -272,11 +393,10 @@ ... [lb]section {Section B}[rb] ... [lb]manpage_end[rb] [example_end] - [subsection {Text markup}] Having handled the overall structure a writer can impose on the document we now take a closer at the text in a paragraph. @@ -343,11 +463,10 @@ argument of a command, its [lb][cmd {arg name}][rb] and its i/o-[lb][cmd {arg mode}][rb]. The latter is optional. ... [example_end] - [subsection Escapes] Beyond the 20 commands for simple markup shown in the previous section we have two more available which are technically simple markup. @@ -369,11 +488,10 @@ These commands, [lb]cmd lb[rb] and [lb]cmd lb[rb] respectively, are required because our use of [lb][cmd lb][rb] and [lb][cmd rb][rb] to bracket markup commands makes it impossible to directly use [lb][cmd lb][rb] and [lb][cmd rb][rb] within the text. ... [example_end] - [subsection Cross-references] The last two commands we have to discuss are for the declaration of cross-references between documents, explicit and implicit. They are @@ -401,10 +519,20 @@ [para] All the cross-reference commands can occur anywhere in the document between [cmd manpage_begin] and [cmd manpage_end]. As such the writer +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] can choose whether she wants to have them at the beginning of the body, or at its end, maybe near the place a keyword is actually defined by the main content, or considers them as meta data which should be in the header, etc. @@ -422,11 +550,10 @@ [lb][cmd {keywords markup {semantic markup}}][rb] [lb][cmd {keywords {doctools markup} {doctools language}}][rb] [lb][cmd {keywords {doctools syntax} {doctools commands}}][rb] [lb]manpage_end[rb] [example_end] - [subsection Examples] Where ever we can write plain text we can write examples too. For simple examples we have the command [cmd example] which takes a single @@ -460,11 +587,10 @@ [example_begin] [lb][cmd example_begin][rb] ... [lb]list_begin enumerated[rb] ... [lb][cmd example_end][rb] [example_end] - [subsection Lists] Where ever we can write plain text we can write lists too. The main commands are [cmd list_begin] to start a list, and [cmd list_end] to @@ -576,11 +702,10 @@ ... [lb]list_end[rb] ... [example_end] - [section {FURTHER READING}] Now that this document has been digested the reader, assumed to be a [term writer] of documentation should be fortified enough to be able to understand the formal [term {doctools language syntax}] @@ -595,23 +720,8 @@ recommended to familiarize oneself with one of the applications for the processing and conversion of doctools documents, i.e. either Tcllib's easy and simple [syscmd dtplite], or Tclapps' ultra-configurable [syscmd dtp]. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also doctools_intro] -[see_also doctools_lang_syntax] -[see_also doctools_lang_cmdref] -[see_also doctools_lang_faq] -[keywords markup {semantic markup}] -[keywords {doctools markup} {doctools language}] -[keywords {doctools syntax} {doctools commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctools_lang_syntax.man ================================================================== --- modules/doctools/doctools_lang_syntax.man +++ modules/doctools/doctools_lang_syntax.man @@ -1,7 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools_lang_syntax n 1.0] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [copyright {2007 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctools language syntax}] [category {Documentation tools}] [description] @@ -13,11 +23,10 @@ [term {doctools language command reference}]. A beginner should read the much more informally written [term {doctools language introduction}] first before trying to understand either this document or the command reference. - [section Fundamentals] In the broadest terms possible the [term {doctools markup language}] is LaTeX-like, instead of like SGML and similar languages. A document @@ -62,11 +71,11 @@ documents. The lexical level of the language was covered in the previous section. [para] -Regarding the syntax of the (E)BNF itself +Regarding the syntax of the (E)BNF itself [list_begin enumerated] [enum] The construct { X } stands for zero or more occurrences of X. [enum] @@ -126,23 +135,8 @@ item_list = [ ] { ITEM paras } optd_list = [ ] { OPT_DEF paras } tkoptd_list = [ ] { TKOPTION_DEF paras } }] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also doctools_intro] -[see_also doctools_lang_intro] -[see_also doctools_lang_cmdref] -[see_also doctools_lang_faq] -[keywords markup {semantic markup}] -[keywords {doctools markup} {doctools language}] -[keywords {doctools syntax} {doctools commands}] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools/doctools_plugin_apiref.man ================================================================== --- modules/doctools/doctools_plugin_apiref.man +++ modules/doctools/doctools_plugin_apiref.man @@ -1,7 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools_plugin_apiref n 1.1] +[see_also doctools] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[keywords document] +[keywords formatter] +[keywords {formatting engine}] +[keywords manpage] +[keywords markup] +[keywords {semantic markup}] [copyright {2007-2010 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {doctools plugin API reference}] [category {Documentation tools}] [description] @@ -28,12 +40,10 @@ [term {doctools language introduction}] and proceed from there to the formal specifications, i.e. the [term {doctools language syntax}] and the [term {doctools language command reference}]. - - [section OVERVIEW] The API for a doctools formatting engine consists of two major sections. @@ -51,12 +61,10 @@ sequence while processing input. They, again, fall into two categories, management and formatting. Please see section [sectref {PLUGIN COMMANDS}] and its subsections for their detailed specification. - - [section {FRONTEND COMMANDS}] This section specifies the set of commands through which a plugin, also known as a doctools formatting engine, is able to query the @@ -231,12 +239,10 @@ called by the frontend in a specific sequence while processing input. They fall into two categories, management and formatting. Their expected names, signatures, and responsibilities are specified in the following two subsections. - - [subsection {Management commands}] The management commands a plugin has to provide are used by the frontend to @@ -330,20 +336,18 @@ It has to initialize the general state of the plugin, beyond the initialization done during the load. No return value is expected, and any returned value is ignored. - [call [cmd fmt_listvariables]] [emph Initialization/Shutdown] and [emph {Engine parameters}]. Second command is called after the plugin code has been loaded, i.e. immediately after [cmd fmt_numpasses]. It has to return a list containing the names of the parameters the frontend can set to configure the engine. This list can be empty. - [call [cmd fmt_numpasses]] [emph Initialization/Shutdown] and [emph {Pass management}]. First command called after the plugin code has been loaded. No other @@ -350,11 +354,10 @@ command of the engine will be called before it. It has to return the number of passes this engine requires to fully process the input document. This value has to be an integer number greater or equal to one. - [call [cmd fmt_postprocess] [arg text]] [emph Initialization/Shutdown]. This command is called immediately after the last pass in a run. Its @@ -365,11 +368,10 @@ [para] Expected to return a value, the final result of formatting the input. - [call [cmd fmt_setup] [arg n]] [emph Initialization/Shutdown] and [emph {Pass management}]. This command is called at the beginning of each pass over the input in a run. Its argument is the number of the pass which has begun. Passes @@ -376,11 +378,10 @@ are counted from [const 1] upward. The command has to set up the internal state of the plugin for this particular pass. No return value is expected, and any returned value is ignored. - [call [cmd fmt_shutdown]] [emph Initialization/Shutdown]. This command is called at the end of every conversion run. It is the @@ -390,11 +391,10 @@ After the call the engine has to be in a state which allows the initiation of another run without fear that information from the last run is leaked into this new run. No return value is expected, and any returned value is ignored. - [call [cmd fmt_varset] [arg varname] [arg text]] [emph {Engine parameters}]. This command is called by the frontend to set an engine parameter to a @@ -413,12 +413,10 @@ The values of all engine parameters have to persist between passes and runs. [list_end] - - [subsection {Formatting commands}] The formatting commands have to implement the formatting for the output format, for all the markup commands of the doctools markup @@ -473,25 +471,8 @@ and added to the output. If no special processing is required it has to simply return its argument without change. [list_end] - - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - -[see_also doctools_intro] -[see_also doctools_lang_intro] -[see_also doctools_lang_syntax] -[see_also doctools_lang_cmdref] -[see_also doctools_lang_faq] -[see_also doctools] -[keywords markup {semantic markup} manpage document] -[keywords {formatting engine} formatter] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] ADDED modules/doctools/include/examples.inc Index: modules/doctools/include/examples.inc ================================================================== --- /dev/null +++ modules/doctools/include/examples.inc @@ -0,0 +1,30 @@ + +[section EXAMPLES] + +[subsection "Where do I find [vset theformat] examples?"] + +We have no direct examples of documents written using [vset theformat] +markup. However the doctools processor [syscmd dtplite] does generate +a table of contents when processing a set of documents written in +doctools markup. The intermediate file for it uses [vset theformat] +markup and is not deleted when generation completes. Such files can +therefore serve as examples. + +[para] + +[syscmd dtplite] is distributed as part of Tcllib, so to get it you +need one of + +[list_begin enumerated] + +[enum] +A snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at + +[uri {/wiki?name=Development+Snapshots} {Development Snapshots}] + +[enum] +A Tcllib release archive. They are available at the [uri /home home] +page. + +[list_end] ADDED modules/doctools/include/placeholder.inc Index: modules/doctools/include/placeholder.inc ================================================================== --- /dev/null +++ modules/doctools/include/placeholder.inc @@ -0,0 +1,12 @@ + +[subsection {What is this document?}] + +This document is currently mainly a placeholder, to be filled with +commonly asked questions about the [vset theformat] markup language +and companions, and their answers. + +[para] + +Please report any questions (and, if possible, answers) we should +consider for this document as explained in the section +[sectref {Bugs, Ideas, Feedback}] below. Index: modules/doctools/mpexpand.man ================================================================== --- modules/doctools/mpexpand.man +++ modules/doctools/mpexpand.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin mpexpand n 1.0] +[see_also expander(n)] +[see_also format(n)] +[see_also formatter(n)] +[keywords conversion] +[keywords HTML] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] [copyright {2002 Andreas Kupries }] [copyright {2003 Andreas Kupries }] [moddesc {Documentation toolbox}] [titledesc {Markup processor}] [category {Documentation tools}] @@ -57,10 +66,19 @@ The processor generates Wiki markup as understood by [syscmd wikit]. [def [const list]] The processor extracts the information provided by [cmd manpage_begin]. +[see_also expander(n)] +[see_also format(n)] +[see_also formatter(n)] +[keywords conversion] +[keywords HTML] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] [def [const null]] The processor does not generate any output. @@ -82,8 +100,8 @@ [section NOTES] [para] Possible future formats are plain text, pdf and postscript. -[see_also expander(n) format(n) formatter(n)] -[keywords manpage TMML HTML nroff conversion markup] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2base/html_cssdefaults.man ================================================================== --- modules/doctools2base/html_cssdefaults.man +++ modules/doctools2base/html_cssdefaults.man @@ -1,14 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::html::cssdefaults n 0.1] +[keywords CSS] +[keywords doctools] +[keywords export] +[keywords HTML] +[keywords plugin] +[keywords style] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Default CSS style for HTML export plugins}] [category {Documentation tools}] [require Tcl 8.4] [require doctools::html::cssdefaults [opt 0.1]] -[keywords doctools export plugin HTML CSS style] [description] This package provides a single command providing access to the text of the default CSS style to use for HTML markup generated by the various HTML export plugins. @@ -27,10 +32,9 @@ This command returns the text of the default CSS style to use for HTML markup generated by the various HTML export plugins. [list_end] - [vset CATEGORY doctools] [include include/feedback.inc] [manpage_end] Index: modules/doctools2base/include/feedback.inc ================================================================== --- modules/doctools2base/include/feedback.inc +++ modules/doctools2base/include/feedback.inc @@ -1,8 +1,8 @@ [section {Bugs, Ideas, Feedback}] -[vset TRACKER http://sourceforge.net/tracker/?group_id=12883] -[vset LABEL {Tcllib SF Trackers}] +[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 Index: modules/doctools2base/nroff_manmacros.man ================================================================== --- modules/doctools2base/nroff_manmacros.man +++ modules/doctools2base/nroff_manmacros.man @@ -1,14 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::nroff::man_macros n 0.1] +[keywords doctools] +[keywords export] +[keywords macros] +[keywords man_macros] +[keywords nroff] +[keywords plugin] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Default CSS style for NROFF export plugins}] [category {Documentation tools}] [require Tcl 8.4] [require doctools::nroff::man_macros [opt 0.1]] -[keywords doctools export plugin nroff man_macros macros] [description] This package provides a single command providing access to the definition of the nroff [emph man] macro set to use for NROFF markup generated by the various NROFF export plugins. @@ -27,10 +32,9 @@ This command returns the text of the default CSS style to use for NROFF generated by the various NROFF export plugins. [list_end] - [vset CATEGORY doctools] [include include/feedback.inc] [manpage_end] Index: modules/doctools2base/tcl_parse.man ================================================================== --- modules/doctools2base/tcl_parse.man +++ modules/doctools2base/tcl_parse.man @@ -1,12 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::tcl::parse n 1] +[keywords command] +[keywords doctools] +[keywords parser] +[keywords subst] +[keywords {Tcl syntax}] +[keywords word] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Processing text in 'subst -novariables' format}] [category {Documentation tools}] -[keywords doctools parser subst command word {Tcl syntax}] [require Tcl 8.4] [require snit] [require fileutil] [require logger] [require struct::list] @@ -54,20 +59,17 @@ [para] In case of errors [arg tree] will be left in an undefined state. - [call [cmd ::doctools::tcl::parse] [method file] \ [arg tree] [arg path] [opt [arg root]]] The same as [method text], except that the text to parse is read from the file specified by [arg path]. - [list_end] - [section {Error format}] When the parser encounters a problem in the input it will throw an error using the format described @@ -106,11 +108,10 @@ [enum] The column the problem was found at (counted from 0 (zero)) [list_end] [list_end] - [section {Tree Structure}] After successfully parsing a string the generated tree will have the following structure: @@ -174,10 +175,9 @@ [enum] All leaves of the tree are either Text or Command nodes. Word nodes cannot be leaves. [list_end] - [vset CATEGORY doctools] [include include/feedback.inc] [manpage_end] Index: modules/doctools2base/tcllib_msgcat.man ================================================================== --- modules/doctools2base/tcllib_msgcat.man +++ modules/doctools2base/tcllib_msgcat.man @@ -1,18 +1,25 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::msgcat n 0.1] +[keywords {catalog package}] +[keywords docidx] +[keywords doctoc] +[keywords doctools] +[keywords i18n] +[keywords internationalization] +[keywords l10n] +[keywords localization] +[keywords {message catalog}] +[keywords {message package}] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Message catalog management for the various document parsers}] [category {Documentation tools}] [require Tcl 8.4] [require msgcat] [require doctools::msgcat [opt 0.1]] [description] -[keywords doctools docidx doctoc {message catalog}] -[keywords localization l10n internationalization i18n] -[keywords {catalog package} {message package}] The package [package doctools::msgcat] is a support module handling the selection of message catalogs for the various document processing packages in the doctools system version 2. As such it is an internal package a regular user (developer) should not be in direct contact @@ -52,10 +59,9 @@ "doctools::msgcat::[arg prefix]::[var langcode]", with [arg prefix] the argument to the command, and the [var langcode] supplied by the result of [cmd msgcat::mcpreferences]. [list_end] - [vset CATEGORY doctools] [include include/feedback.inc] [manpage_end] Index: modules/doctools2idx/container.man ================================================================== --- modules/doctools2idx/container.man +++ modules/doctools2idx/container.man @@ -1,28 +1,45 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::idx n 2] +[keywords conversion] +[keywords {docidx markup}] +[keywords documentation] +[keywords formatting] +[keywords generation] +[keywords HTML] +[keywords index] +[keywords json] +[keywords {keyword index}] +[keywords latex] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords parsing] +[keywords plugin] +[keywords reference] +[keywords {tcler's wiki}] +[keywords text] +[keywords TMML] +[keywords url] +[keywords wiki] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Holding keyword indices}] [category {Documentation tools}] [require doctools::idx [opt 2]] [require Tcl 8.4] [require doctools::idx::structure] [require snit] -[keywords {keyword index} index reference documentation manpage url] -[keywords {docidx markup} markup conversion formatting generation plugin] -[keywords json text nroff wiki {tcler's wiki} latex TMML HTML] -[keywords parsing] [description] This package provides a class to contain and programmatically manipulate keyword indices [para] This is one of the three public pillars the management of keyword -indices resides on. The other two pillars are +indices resides on. The other two pillars are [list_begin enum] [enum] [manpage {Exporting keyword indices}], and [enum] [manpage {Importing keyword indices}] [list_end] @@ -39,13 +56,11 @@ This is the only format directly known to this class. Conversions from and to any other format are handled by export and import manager objects. These may be attached to a container, but do not have to be, it is merely a convenience. - [section Concepts] [include include/concept.inc] - [section API] [subsection {Package commands}] [list_begin definitions] @@ -58,11 +73,10 @@ and [sectref {Object methods}]. The object command will be created under the current namespace if the [arg objectName] is not fully qualified, and in the specified namespace otherwise. [list_end] - [subsection {Object command}] All objects created by the [cmd ::doctools::idx] command have the following general form: @@ -77,11 +91,10 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] @@ -92,32 +105,28 @@ This method adds the keyword [arg name] to the index. If the keyword is already known nothing is done. The result of the method is the empty string. - [call [arg objectName] [method {key remove}] [arg name]] This method removes the keyword [arg name] from the index. If the keyword is already gone nothing is done. Any references for whom this keyword was the last association are removed as well. The result of the method is the empty string. - [call [arg objectName] [method {key references}] [arg name]] This method returns a list containing the names of all references associated with the keyword [arg name]. An error is thrown in the keyword is not known to the index. The order of the references in the list is undefined. - [call [arg objectName] [method keys]] This method returns a list containing the names of all keywords known to the index. The order of the keywords in the list is undefined. - [call [arg objectName] [method {reference add}] [arg type] [arg key] [arg name] [arg label]] This method adds the reference [arg name] to the index and associates it with the keyword [arg key]. @@ -140,72 +149,61 @@ [para] The [arg type] argument has be to one of [const manpage] or [const url]. - [call [arg objectName] [method {reference remove}] [arg name]] The reference [arg name] is removed from the index. All associations with keywords are released and the relevant reference labels removed. The result of the method is the empty string. - [call [arg objectName] [method {reference label}] [arg name]] This method returns the label associated with the reference [arg name]. An error is thrown if the reference is not known. - [call [arg objectName] [method {reference keys}] [arg name]] This method returns a list containing the names of all keywords associated with the reference [arg name]. An error is thrown in the reference is not known to the index. The order of the keywords in the list is undefined. - [call [arg objectName] [method {reference type}] [arg name]] This method returns the type of the reference [arg name]. An error is thrown in the reference is not known to the index. - [call [arg objectName] [method references]] This method returns a list containing the names of all references known to the index. The order of the references in the list is undefined. - [call [arg objectName] [method title]] Returns the currently defined title of the keyword index. - [call [arg objectName] [method title] [arg text]] Sets the title of the keyword index to [arg text], and returns it as the result of the command. - [call [arg objectName] [method label]] Returns the currently defined label of the keyword index. - [call [arg objectName] [method label] [arg text]] Sets the label of the keyword index to [arg text], and returns it as the result of the command. - [call [arg objectName] [method importer]] Returns the import manager object currently attached to the container, if any. - [call [arg objectName] [method importer] [arg object]] Attaches the [arg object] as import manager to the container, and returns it as the result of the command. @@ -219,16 +217,14 @@ It is expected that [arg object] provides a method named [method {import text}] which takes a text and a format name, and returns the canonical serialization of the keyword index contained in the text, assuming the given format. - [call [arg objectName] [method exporter]] Returns the export manager object currently attached to the container, if any. - [call [arg objectName] [method exporter] [arg object]] Attaches the [arg object] as export manager to the container, and returns it as the result of the command. @@ -244,11 +240,10 @@ and returns a text encoding keyword index stored in the container, in the given format. It is further expected that the [arg object] will use the container's method [method serialize] to obtain the serialization of the keyword index from which to generate the text. - [call [arg objectName] [method {deserialize =}] [arg data] [opt [arg format]]] This method replaces the contents of the index object with the index contained in the [arg data]. If no [arg format] was specified it is assumed to be the regular serialization of a keyword index. @@ -263,25 +258,23 @@ [para] The result of the method is the empty string. - [call [arg objectName] [method {deserialize +=}] [arg data] [opt [arg format]]] This method behaves like [method {deserialize =}] in its essentials, except that it merges the keyword index in the [arg data] to its -contents instead of replacing it. +contents instead of replacing it. The method will throw an error if merging is not possible, i.e. would produce an invalid index. The existing content is left unchanged in that case. [para] The result of the method is the empty string. - [call [arg objectName] [method serialize] [opt [arg format]]] This method returns the keyword index contained in the object. If no [arg format] is not specified the returned result is the canonical @@ -293,13 +286,11 @@ the data to the specified format. In that case an error will be thrown if the container has no export manager attached to it. - [list_end] - [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2idx/export.man ================================================================== --- modules/doctools2idx/export.man +++ modules/doctools2idx/export.man @@ -1,7 +1,26 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::idx::export n 0.1] +[keywords conversion] +[keywords docidx] +[keywords documentation] +[keywords export] +[keywords formatting] +[keywords generation] +[keywords HTML] +[keywords index] +[keywords json] +[keywords {keyword index}] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords plugin] +[keywords reference] +[keywords {tcler's wiki}] +[keywords text] +[keywords url] +[keywords wiki] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Exporting keyword indices}] [category {Documentation tools}] [require doctools::idx::export [opt 0.1]] @@ -8,23 +27,20 @@ [require Tcl 8.4] [require doctools::config] [require doctools::idx::structure] [require snit] [require pluginmgr] -[keywords {keyword index} index reference documentation manpage url] -[keywords markup conversion formatting export generation plugin] -[keywords json docidx text nroff wiki {tcler's wiki} HTML] [description] This package provides a class to manage the plugins for the export of keyword indices to other formats, i.e. their conversion to, for example [term docidx], [term HTML], etc. [para] This is one of the three public pillars the management of keyword -indices resides on. The other two pillars are +indices resides on. The other two pillars are [list_begin enum] [enum] [manpage {Importing keyword indices}], and [enum] [manpage {Holding keyword indices}] [list_end] @@ -81,13 +97,11 @@ [term {plugin writer}]s reading and understanding the section containing the [sectref {Export plugin API v2 reference}] is an absolute necessity, as it specifies the interaction between this package and its plugins in detail. - [section Concepts] [include include/concept.inc] - [section API] [subsection {Package commands}] [list_begin definitions] @@ -100,11 +114,10 @@ and [sectref {Object methods}]. The object command will be created under the current namespace if the [arg objectName] is not fully qualified, and in the specified namespace otherwise. [list_end] - [subsection {Object command}] All objects created by the [cmd ::doctools::idx::export] command have the following general form: @@ -119,19 +132,17 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method {export serial}] [arg serial] [opt [arg format]]] This method takes the canonical serialization of a keyword index stored in [arg serial] and converts it to the specified [arg format], @@ -153,11 +164,10 @@ [para] The plugin has to conform to the interface specified in section [sectref {Export plugin API v2 reference}]. - [call [arg objectName] [method {export object}] [arg object] [opt [arg format]]] This method is a convenient wrapper around the [method {export serial}] method described by the previous item. @@ -165,22 +175,19 @@ [method serialize] method returning the canonical serialization of a keyword index. It invokes that method, feeds the result into [method {export serial}] and returns the resulting string as its own result. - [call [arg objectName] [method {config names}]] This method returns a list containing the names of all configuration variables currently known to the object. - [call [arg objectName] [method {config get}]] This method returns a dictionary containing the names and values of all configuration variables currently known to the object. - [call [arg objectName] [method {config set}] [arg name] [opt [arg value]]] This method sets the configuration variable [arg name] to the specified [arg value] and returns the new value of the variable. @@ -195,20 +202,17 @@ Note that while the user can set the predefined configuration variables [const user] and [const format] doing so will have no effect, these values will be internally overriden when invoking an import plugin. - [call [arg objectName] [method {config unset}] [arg pattern]...] This method unsets all configuration variables matching the specified glob [arg pattern]s. If no pattern is specified it will unset all currently defined configuration variables. - [list_end] - [section {Export plugin API v2 reference}] Plugins are what this package uses to manage the support for any output format beyond the @@ -295,11 +299,10 @@ [enum] A single usage cycle of a plugin consists of the invokations of the command [cmd export]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] - [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2idx/import.man ================================================================== --- modules/doctools2idx/import.man +++ modules/doctools2idx/import.man @@ -1,7 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::idx::import n 0.1] +[keywords conversion] +[keywords docidx] +[keywords documentation] +[keywords import] +[keywords index] +[keywords json] +[keywords {keyword index}] +[keywords manpage] +[keywords markup] +[keywords parsing] +[keywords plugin] +[keywords reference] +[keywords url] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Importing keyword indices}] [category {Documentation tools}] [require doctools::idx::import [opt 0.1]] @@ -8,23 +21,20 @@ [require Tcl 8.4] [require doctools::config] [require doctools::idx::structure] [require snit] [require pluginmgr] -[keywords {keyword index} index reference documentation manpage url] -[keywords markup conversion import parsing plugin] -[keywords json docidx] [description] This package provides a class to manage the plugins for the import of keyword indices from other formats, i.e. their conversion from, for example [term docidx], [term json], etc. [para] This is one of the three public pillars the management of keyword -indices resides on. The other two pillars are +indices resides on. The other two pillars are [list_begin enum] [enum] [manpage {Exporting keyword indices}], and [enum] [manpage {Holding keyword indices}] [list_end] @@ -77,13 +87,11 @@ [term {plugin writer}]s reading and understanding the section containing the [sectref {Import plugin API v2 reference}] is an absolute necessity, as it specifies the interaction between this package and its plugins in detail. - [section Concepts] [include include/concept.inc] - [section API] [subsection {Package commands}] [list_begin definitions] @@ -96,11 +104,10 @@ and [sectref {Object methods}]. The object command will be created under the current namespace if the [arg objectName] is not fully qualified, and in the specified namespace otherwise. [list_end] - [subsection {Object command}] All objects created by the [cmd ::doctools::idx::import] command have the following general form: @@ -115,19 +122,17 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method {import text}] [arg text] [opt [arg format]]] This method takes the [arg text] and converts it from the specified [arg format] to the canonical serialization of a keyword index using @@ -149,20 +154,18 @@ [para] The plugin has to conform to the interface specified in section [sectref {Import plugin API v2 reference}]. - [call [arg objectName] [method {import file}] [arg path] [opt [arg format]]] This method is a convenient wrapper around the [method {import text}] method described by the previous item. It reads the contents of the specified file into memory, feeds the result into [method {import text}] and returns the resulting serialization as its own result. - [call [arg objectName] [method {import object text}] [arg object] \ [arg text] [opt [arg format]]] This method is a convenient wrapper around the [method {import text}] @@ -175,30 +178,26 @@ It imports the text using [method {import text}] and then feeds the resulting serialization into the [arg object] via [method deserialize]. This method returns the empty string as it result. - [call [arg objectName] [method {import object file}] [arg object] \ [arg path] [opt [arg format]]] This method behaves like [method {import object text}], except that it reads the text to convert from the specified file instead of being given it as argument. - [call [arg objectName] [method {config names}]] This method returns a list containing the names of all configuration variables currently known to the object. - [call [arg objectName] [method {config get}]] This method returns a dictionary containing the names and values of all configuration variables currently known to the object. - [call [arg objectName] [method {config set}] [arg name] [opt [arg value]]] This method sets the configuration variable [arg name] to the specified [arg value] and returns the new value of the variable. @@ -213,27 +212,24 @@ Note that while the user can set the predefined configuration variables [const user] and [const format] doing so will have no effect, these values will be internally overriden when invoking an import plugin. - [call [arg objectName] [method {config unset}] [arg pattern]...] This method unsets all configuration variables matching the specified glob [arg pattern]s. If no pattern is specified it will unset all currently defined configuration variables. - [call [arg objectName] [method includes]] This method returns a list containing the currently specified paths to use to search for include files when processing input. The order of paths in the list corresponds to the order in which they are used, from first to last, and also corresponds to the order in which they were added to the object. - [call [arg objectName] [method {include add}] [arg path]] This methods adds the specified [arg path] to the list of paths to use to search for include files when processing input. The path is added @@ -242,11 +238,10 @@ [para] The method does nothing if the path is already known. - [call [arg objectName] [method {include remove}] [arg path]] This methods removes the specified [arg path] from the list of paths to use to search for include files when processing input. The result of the command is the empty string. @@ -253,19 +248,17 @@ [para] The method does nothing if the path is not known. - [call [arg objectName] [method {include clear}]] This method clears the list of paths to use to search for include files when processing input. The result of the command is the empty string. [list_end] - [section {Import plugin API v2 reference}] Plugins are what this package uses to manage the support for any input format beyond the [sectref {Keyword index serialization format}]. Here @@ -392,11 +385,10 @@ [enum] A single usage cycle of a plugin consists of the invokations of the command [cmd import]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] - [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2idx/introduction.man ================================================================== --- modules/doctools2idx/introduction.man +++ modules/doctools2idx/introduction.man @@ -1,24 +1,30 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools2idx_introduction n 2.0] +[see_also docidx_intro] +[see_also doctoc_intro] +[see_also doctools] +[see_also doctools2doc_introduction] +[see_also doctools2toc_introduction] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[see_also doctools_plugin_apiref] +[keywords conversion] +[keywords formatting] +[keywords index] +[keywords {keyword index}] +[keywords markup] +[keywords parsing] +[keywords plugin] +[keywords {semantic markup}] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {DocTools - Keyword indices}] [category {Documentation tools}] -[keywords markup {semantic markup} index {keyword index}] -[keywords plugin parsing formatting conversion] -[see_also doctools2toc_introduction] -[see_also doctools2doc_introduction] [comment { - [see_also doctools_lang_intro] - [see_also doctools_lang_syntax] - [see_also doctools_lang_cmdref] - [see_also doctools_lang_faq] - [see_also doctools] - [see_also doctools_plugin_apiref] - [see_also doctoc_intro] - [see_also docidx_intro] }] [description] [term docidx] (short for [emph {documentation indices}]) stands for a set of related, yet different, entities which are working together for @@ -106,11 +112,10 @@ [list_end] See also section [sectref {Package Overview}] for an overview of the dependencies between these and other, supporting packages. - [enum] At last, but not least, [term {plugin writers}] have to understand the interaction between the import and export packages and their plugins. These APIs are described in the documentation for the two relevant packages, i.e. @@ -131,13 +136,11 @@ They are described in their own sets of documents, starting at the [manpage {DocTools - Tables Of Contents}] and the [manpage {DocTools - General}], respectively. - [section {Package Overview}] [include include/dependencies.inc] - [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2idx/parse.man ================================================================== --- modules/doctools2idx/parse.man +++ modules/doctools2idx/parse.man @@ -1,12 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::idx::parse n 1] +[keywords docidx] +[keywords doctools] +[keywords lexer] +[keywords parser] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Parsing text in docidx format}] [category {Documentation tools}] -[keywords doctools docidx parser lexer] [require doctools::idx::parse [opt 0.1]] [require Tcl 8.4] [require doctools::idx::structure] [require doctools::msgcat] [require doctools::tcl::parse] @@ -48,65 +51,56 @@ keyword index which was encoded in the text. See the section [sectref {Keyword index serialization format}] for specification of that format. - [call [cmd ::doctools::idx::parse] [method file] [arg path]] The same as [method text], except that the text to parse is read from the file specified by [arg path]. - [call [cmd ::doctools::idx::parse] [method includes]] This method returns the current list of search paths used when looking for include files. - [call [cmd ::doctools::idx::parse] [method {include add}] [arg path]] This method adds the [arg path] to the list of paths searched when looking for an include file. The call is ignored if the path is already in the list of paths. The method returns the empty string as its result. - [call [cmd ::doctools::idx::parse] [method {include remove}] [arg path]] This method removes the [arg path] from the list of paths searched when looking for an include file. The call is ignored if the path is not contained in the list of paths. The method returns the empty string as its result. - [call [cmd ::doctools::idx::parse] [method {include clear}]] This method clears the list of search paths for include files. - [call [cmd ::doctools::idx::parse] [method vars]] This method returns a dictionary containing the current set of predefined variables known to the [cmd vset] markup command during processing. - [call [cmd ::doctools::idx::parse] [method {var set}] [arg name] [arg value]] This method adds the variable [arg name] to the set of predefined variables known to the [cmd vset] markup command during processing, and gives it the specified [arg value]. The method returns the empty string as its result. - [call [cmd ::doctools::idx::parse] [method {var unset}] [arg name]] This method removes the variable [arg name] from the set of predefined variables known to the [cmd vset] markup command during processing. The method returns the empty string as its result. - [call [cmd ::doctools::idx::parse] [method {var clear}] [opt [arg pattern]]] This method removes all variables matching the [arg pattern] from the set of predefined variables known to the [cmd vset] markup command @@ -116,12 +110,10 @@ The pattern matching is done with [cmd {string match}], and the default pattern used when none is specified, is [const *]. [list_end] - - [section {Parse errors}] The format of the parse error messages thrown when encountering violations of the [term docidx] markup syntax is human readable and @@ -172,13 +164,12 @@ the set of errors found in the included file, using the format described here. [list_end] [list_end] - [include include/format/docidx.inc] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2idx/structure.man ================================================================== --- modules/doctools2idx/structure.man +++ modules/doctools2idx/structure.man @@ -1,12 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::idx::structure n 0.1] +[keywords deserialization] +[keywords docidx] +[keywords doctools] +[keywords serialization] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Docidx serialization utilities}] [category {Documentation tools}] -[keywords docidx doctools serialization deserialization] [require doctools::idx::structure [opt 0.1]] [require Tcl 8.4] [require logger] [require snit] [description] @@ -48,11 +51,10 @@ For the specification of regular and canonical keyword index serializations see the section [sectref {Keyword index serialization format}]. - [call [cmd ::doctools::idx::structure] [method verify-as-canonical] \ [arg serial]] This command verifies that the content of [arg serial] is a valid [term canonical] serialization of a keyword index and will throw an @@ -61,11 +63,10 @@ [para] For the specification of canonical keyword index serializations see the section [sectref {Keyword index serialization format}]. - [call [cmd ::doctools::idx::structure] [method canonicalize] [arg serial]] This command assumes that the content of [arg serial] is a valid [term regular] serialization of a keyword index and will throw an @@ -81,12 +82,10 @@ For the specification of regular and canonical keyword index serializations see the section [sectref {Keyword index serialization format}]. - - [call [cmd ::doctools::idx::structure] [method print] [arg serial]] This command assumes that the argument [arg serial] contains a valid regular serialization of a keyword index and returns a string containing that index in a human readable form. @@ -98,11 +97,10 @@ [para] For the specification of regular keyword index serializations see the section [sectref {Keyword index serialization format}]. - [call [cmd ::doctools::idx::structure] [method merge] \ [arg seriala] [arg serialb]] This command accepts the regular serializations of two keyword indices @@ -121,12 +119,11 @@ For the specification of regular and canonical keyword index serializations see the section [sectref {Keyword index serialization format}]. [list_end] - [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2toc/container.man ================================================================== --- modules/doctools2toc/container.man +++ modules/doctools2toc/container.man @@ -1,20 +1,35 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::toc n 2] +[keywords conversion] +[keywords {doctoc markup}] +[keywords documentation] +[keywords formatting] +[keywords generation] +[keywords HTML] +[keywords json] +[keywords latex] +[keywords markup] +[keywords nroff] +[keywords parsing] +[keywords plugin] +[keywords reference] +[keywords table] +[keywords {table of contents}] +[keywords {tcler's wiki}] +[keywords text] +[keywords TMML] +[keywords wiki] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Holding tables of contents}] [category {Documentation tools}] [require doctools::toc [opt 2]] [require Tcl 8.4] [require doctools::toc::structure] [require struct::tree] [require snit] -[keywords {table of contents} table reference documentation] -[keywords {doctoc markup} markup conversion formatting generation plugin] -[keywords json text nroff wiki {tcler's wiki} latex TMML HTML] -[keywords parsing] [description] This package provides a class to contain and programmatically manipulate tables of contents. @@ -40,13 +55,11 @@ This is the only format directly known to this class. Conversions from and to any other format are handled by export and import manager objects. These may be attached to a container, but do not have to be, it is merely a convenience. - [section Concepts] [include include/concept.inc] - [section API] [subsection {Package commands}] [list_begin definitions] @@ -60,11 +73,10 @@ under the current namespace if the [arg objectName] is not fully qualified, and in the specified namespace otherwise. [list_end] - [subsection {Object command}] All objects created by the [cmd ::doctools::toc] command have the following general form: @@ -77,11 +89,10 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] @@ -111,11 +122,10 @@ [para] The result of the method is the handle (id) of the new element. - [call [arg objectName] [method {+ division}] [arg id] [arg label] [opt [arg docid]]] This method adds a new division element to the table of contents, under the element specified via its handle [arg id]. This parent element has to be a division element, or the root. An error is thrown @@ -132,11 +142,10 @@ [para] The result of the method is the handle (id) of the new element. - [call [arg objectName] [method remove] [arg id]] This method removes the element identified by the handle [arg id] from the table of contents. @@ -146,69 +155,59 @@ [para] The result of the method is the empty string. - [call [arg objectName] [method up] [arg id]] This method returns the handle of the parent for the element identified by its handle [arg id], or the empty string if [arg id] refered to the root element. - [call [arg objectName] [method next] [arg id]] This method returns the handle of the right sibling for the element identified by its handle [arg id], or the handle of the parent if the element has no right sibling, or the empty string if [arg id] refered to the root element. - - [call [arg objectName] [method prev] [arg id]] This method returns the handle of the left sibling for the element identified by its handle [arg id], or the handle of the parent if the element has no left sibling, or the empty string if [arg id] refered to the root element. - [call [arg objectName] [method child] [arg id] [arg label] [opt [arg ...]]] This method returns the handle of a child of the element identified by its handle [arg id]. The child itself is identified by a series of labels. - [call [arg objectName] [method element] [opt [arg ...]]] This method returns the handle of the element identified by a series of labels, starting from the root of the table of contents. The series of labels is allowed to be empty, in which case the handle of the root element is returned. - [call [arg objectName] [method children] [arg id]] This method returns a list containing the handles of all children of the element identified by the handle [arg id], from first to last, in that order. - [call [arg objectName] [method type] [arg id]] This method returns the type of the element, either [const reference], or [const division]. - [call [arg objectName] [method full-label] [arg id]] This method is the complement of the method [method element], converting the handle [arg id] of an element into a list of labels full identifying the element within the whole table of contents. - [call [arg objectName] [method elabel] [arg id] [opt [arg newlabel]]] This method queries and/or changes the label of the element identified by the handle [arg id]. If the argument [arg newlabel] is present then @@ -225,11 +224,10 @@ Further, of the [arg id] refers to the root element of the table of contents, then using this method is equivalent to using the method [arg label], i.e. it is accessing the global label for the whole table. - [call [arg objectName] [method description] [arg id] [opt [arg newdesc]]] This method queries and/or changes the description of the element identified by the handle [arg id]. If the argument [arg newdesc] is present then the description is changed to that value. Regardless of @@ -237,11 +235,10 @@ [para] The element this method operates on has to be a reference element, or an error will be thrown. - [call [arg objectName] [method document] [arg id] [opt [arg newdocid]]] This method queries and/or changes the document reference of the element identified by the handle [arg id]. @@ -255,38 +252,32 @@ Setting the reference to the empty string means unsetting it, and is allowed only for division elements. Conversely, if the result is the empty string then the element has no document reference, and this can happen only for division elements. - [call [arg objectName] [method title]] Returns the currently defined title of the table of contents. - [call [arg objectName] [method title] [arg text]] Sets the title of the table of contents to [arg text], and returns it as the result of the command. - [call [arg objectName] [method label]] Returns the currently defined label of the table of contents. - [call [arg objectName] [method label] [arg text]] Sets the label of the table of contents to [arg text], and returns it as the result of the command. - [call [arg objectName] [method importer]] Returns the import manager object currently attached to the container, if any. - [call [arg objectName] [method importer] [arg object]] Attaches the [arg object] as import manager to the container, and returns it as the result of the command. @@ -300,16 +291,14 @@ It is expected that [arg object] provides a method named [method {import text}] which takes a text and a format name, and returns the canonical serialization of the table of contents contained in the text, assuming the given format. - [call [arg objectName] [method exporter]] Returns the export manager object currently attached to the container, if any. - [call [arg objectName] [method exporter] [arg object]] Attaches the [arg object] as export manager to the container, and returns it as the result of the command. @@ -325,11 +314,10 @@ and returns a text encoding table of contents stored in the container, in the given format. It is further expected that the [arg object] will use the container's method [method serialize] to obtain the serialization of the table of contents from which to generate the text. - [call [arg objectName] [method {deserialize =}] [arg data] [opt [arg format]]] This method replaces the contents of the table object with the table contained in the [arg data]. If no [arg format] was specified it is assumed to be the regular serialization of a table of contents. @@ -344,25 +332,23 @@ [para] The result of the method is the empty string. - [call [arg objectName] [method {deserialize +=}] [arg data] [opt [arg format]]] This method behaves like [method {deserialize =}] in its essentials, except that it merges the table of contents in the [arg data] to its -contents instead of replacing it. +contents instead of replacing it. The method will throw an error if merging is not possible, i.e. would produce an invalid table. The existing content is left unchanged in that case. [para] The result of the method is the empty string. - [call [arg objectName] [method serialize] [opt [arg format]]] This method returns the table of contents contained in the object. If no [arg format] is not specified the returned result is the canonical @@ -374,13 +360,11 @@ the data to the specified format. In that case an error will be thrown if the container has no export manager attached to it. - [list_end] - [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2toc/export.man ================================================================== --- modules/doctools2toc/export.man +++ modules/doctools2toc/export.man @@ -1,7 +1,26 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::toc::export n 0.1] +[keywords conversion] +[keywords doctoc] +[keywords documentation] +[keywords export] +[keywords formatting] +[keywords generation] +[keywords HTML] +[keywords json] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords plugin] +[keywords reference] +[keywords table] +[keywords {table of contents}] +[keywords {tcler's wiki}] +[keywords text] +[keywords url] +[keywords wiki] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Exporting tables of contents}] [category {Documentation tools}] [require doctools::toc::export [opt 0.1]] @@ -8,13 +27,10 @@ [require Tcl 8.4] [require doctools::config] [require doctools::toc::structure] [require snit] [require pluginmgr] -[keywords {table of contents} table reference documentation manpage url] -[keywords markup conversion formatting export generation plugin] -[keywords json doctoc text nroff wiki {tcler's wiki} HTML] [description] This package provides a class to manage the plugins for the export of tables of contents to other formats, i.e. their conversion to, for example [term doctoc], [term HTML], etc. @@ -81,13 +97,11 @@ [term {plugin writer}]s reading and understanding the section containing the [sectref {Export plugin API v2 reference}] is an absolute necessity, as it specifies the interaction between this package and its plugins in detail. - [section Concepts] [include include/concept.inc] - [section API] [subsection {Package commands}] [list_begin definitions] @@ -100,11 +114,10 @@ and [sectref {Object methods}]. The object command will be created under the current namespace if the [arg objectName] is not fully qualified, and in the specified namespace otherwise. [list_end] - [subsection {Object command}] All objects created by the [cmd ::doctools::toc::export] command have the following general form: @@ -119,19 +132,17 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method {export serial}] [arg serial] [opt [arg format]]] This method takes the canonical serialization of a table of contents stored in [arg serial] and converts it to the specified [arg format], @@ -153,11 +164,10 @@ [para] The plugin has to conform to the interface specified in section [sectref {Export plugin API v2 reference}]. - [call [arg objectName] [method {export object}] [arg object] [opt [arg format]]] This method is a convenient wrapper around the [method {export serial}] method described by the previous item. @@ -165,22 +175,19 @@ [method serialize] method returning the canonical serialization of a table of contents. It invokes that method, feeds the result into [method {export serial}] and returns the resulting string as its own result. - [call [arg objectName] [method {config names}]] This method returns a list containing the names of all configuration variables currently known to the object. - [call [arg objectName] [method {config get}]] This method returns a dictionary containing the names and values of all configuration variables currently known to the object. - [call [arg objectName] [method {config set}] [arg name] [opt [arg value]]] This method sets the configuration variable [arg name] to the specified [arg value] and returns the new value of the variable. @@ -195,20 +202,17 @@ Note that while the user can set the predefined configuration variables [const user] and [const format] doing so will have no effect, these values will be internally overriden when invoking an import plugin. - [call [arg objectName] [method {config unset}] [arg pattern]...] This method unsets all configuration variables matching the specified glob [arg pattern]s. If no pattern is specified it will unset all currently defined configuration variables. - [list_end] - [section {Export plugin API v2 reference}] Plugins are what this package uses to manage the support for any output format beyond the [sectref {ToC serialization format}]. Here we @@ -293,11 +297,10 @@ [enum] A single usage cycle of a plugin consists of the invokations of the command [cmd export]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] - [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2toc/import.man ================================================================== --- modules/doctools2toc/import.man +++ modules/doctools2toc/import.man @@ -1,7 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::toc::import n 0.1] +[keywords conversion] +[keywords doctoc] +[keywords documentation] +[keywords import] +[keywords json] +[keywords manpage] +[keywords markup] +[keywords parsing] +[keywords plugin] +[keywords reference] +[keywords table] +[keywords {table of contents}] +[keywords url] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Importing keyword indices}] [category {Documentation tools}] [require doctools::toc::import [opt 0.1]] @@ -8,13 +21,10 @@ [require Tcl 8.4] [require doctools::config] [require doctools::toc::structure] [require snit] [require pluginmgr] -[keywords {table of contents} table reference documentation manpage url] -[keywords markup conversion import parsing plugin] -[keywords json doctoc] [description] This package provides a class to manage the plugins for the import of tables of contents from other formats, i.e. their conversion from, for example [term doctoc], [term json], etc. @@ -77,13 +87,11 @@ [term {plugin writer}]s reading and understanding the section containing the [sectref {Import plugin API v2 reference}] is an absolute necessity, as it specifies the interaction between this package and its plugins in detail. - [section Concepts] [include include/concept.inc] - [section API] [subsection {Package commands}] [list_begin definitions] @@ -96,11 +104,10 @@ and [sectref {Object methods}]. The object command will be created under the current namespace if the [arg objectName] is not fully qualified, and in the specified namespace otherwise. [list_end] - [subsection {Object command}] All objects created by the [cmd ::doctools::toc::import] command have the following general form: @@ -115,19 +122,17 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method {import text}] [arg text] [opt [arg format]]] This method takes the [arg text] and converts it from the specified [arg format] to the canonical serialization of a table of contents using @@ -149,20 +154,18 @@ [para] The plugin has to conform to the interface specified in section [sectref {Import plugin API v2 reference}]. - [call [arg objectName] [method {import file}] [arg path] [opt [arg format]]] This method is a convenient wrapper around the [method {import text}] method described by the previous item. It reads the contents of the specified file into memory, feeds the result into [method {import text}] and returns the resulting serialization as its own result. - [call [arg objectName] [method {import object text}] [arg object] \ [arg text] [opt [arg format]]] This method is a convenient wrapper around the [method {import text}] @@ -175,30 +178,26 @@ It imports the text using [method {import text}] and then feeds the resulting serialization into the [arg object] via [method deserialize]. This method returns the empty string as it result. - [call [arg objectName] [method {import object file}] [arg object] \ [arg path] [opt [arg format]]] This method behaves like [method {import object text}], except that it reads the text to convert from the specified file instead of being given it as argument. - [call [arg objectName] [method {config names}]] This method returns a list containing the names of all configuration variables currently known to the object. - [call [arg objectName] [method {config get}]] This method returns a dictionary containing the names and values of all configuration variables currently known to the object. - [call [arg objectName] [method {config set}] [arg name] [opt [arg value]]] This method sets the configuration variable [arg name] to the specified [arg value] and returns the new value of the variable. @@ -213,27 +212,24 @@ Note that while the user can set the predefined configuration variables [const user] and [const format] doing so will have no effect, these values will be internally overriden when invoking an import plugin. - [call [arg objectName] [method {config unset}] [arg pattern]...] This method unsets all configuration variables matching the specified glob [arg pattern]s. If no pattern is specified it will unset all currently defined configuration variables. - [call [arg objectName] [method includes]] This method returns a list containing the currently specified paths to use to search for include files when processing input. The order of paths in the list corresponds to the order in which they are used, from first to last, and also corresponds to the order in which they were added to the object. - [call [arg objectName] [method {include add}] [arg path]] This methods adds the specified [arg path] to the list of paths to use to search for include files when processing input. The path is added @@ -242,11 +238,10 @@ [para] The method does nothing if the path is already known. - [call [arg objectName] [method {include remove}] [arg path]] This methods removes the specified [arg path] from the list of paths to use to search for include files when processing input. The result of the command is the empty string. @@ -253,19 +248,17 @@ [para] The method does nothing if the path is not known. - [call [arg objectName] [method {include clear}]] This method clears the list of paths to use to search for include files when processing input. The result of the command is the empty string. [list_end] - [section {Import plugin API v2 reference}] Plugins are what this package uses to manage the support for any input format beyond the [sectref {ToC serialization format}]. Here we @@ -392,11 +385,10 @@ [enum] A single usage cycle of a plugin consists of the invokations of the command [cmd import]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end] - [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2toc/introduction.man ================================================================== --- modules/doctools2toc/introduction.man +++ modules/doctools2toc/introduction.man @@ -1,27 +1,31 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools2toc_introduction n 2.0] +[see_also doctoc_intro] +[see_also doctools] +[see_also doctools2doc_introduction] +[see_also doctools2idx_introduction] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[see_also doctools_plugin_apiref] +[keywords contents] +[keywords conversion] +[keywords formatting] +[keywords markup] +[keywords parsing] +[keywords plugin] +[keywords {semantic markup}] +[keywords {table of contents}] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {DocTools - Tables of Contents}] [category {Documentation tools}] -[keywords markup {semantic markup} contents {table of contents}] -[keywords plugin parsing formatting conversion] -[see_also doctools2idx_introduction] -[see_also doctools2doc_introduction] [comment { - [see_also doctools_lang_intro] - [see_also doctools_lang_syntax] - [see_also doctools_lang_cmdref] - [see_also doctools_lang_faq] - [see_also doctools] - [see_also doctools_plugin_apiref] - [see_also doctoc_intro] - [see_also doctoc_intro] }] [description] - [term doctoc] (short for [emph {documentation tables of contents}]) stands for a set of related, yet different, entities which are working together for the easy creation and transformation of tables and contents for documentation. @@ -105,11 +109,10 @@ [list_end] See also section [sectref {Package Overview}] for an overview of the dependencies between these and other, supporting packages. - [enum] At last, but not least, [term {plugin writers}] have to understand the interaction between the import and export packages and their plugins. These APIs are described in the documentation for the two relevant packages, i.e. @@ -130,13 +133,11 @@ They are described in their own sets of documents, starting at the [manpage {DocTools - Keyword Indices}] and the [manpage {DocTools - General}], respectively. - [section {Package Overview}] [include include/dependencies.inc] - [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2toc/parse.man ================================================================== --- modules/doctools2toc/parse.man +++ modules/doctools2toc/parse.man @@ -1,12 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::toc::parse n 1] +[keywords doctoc] +[keywords doctools] +[keywords lexer] +[keywords parser] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Parsing text in doctoc format}] [category {Documentation tools}] -[keywords doctools doctoc parser lexer] [require doctools::toc::parse [opt 0.1]] [require Tcl 8.4] [require doctools::toc::structure] [require doctools::msgcat] [require doctools::tcl::parse] @@ -48,65 +51,56 @@ table of contents which was encoded in the text. See the section [sectref {ToC serialization format}] for specification of that format. - [call [cmd ::doctools::toc::parse] [method file] [arg path]] The same as [method text], except that the text to parse is read from the file specified by [arg path]. - [call [cmd ::doctools::toc::parse] [method includes]] This method returns the current list of search paths used when looking for include files. - [call [cmd ::doctools::toc::parse] [method {include add}] [arg path]] This method adds the [arg path] to the list of paths searched when looking for an include file. The call is ignored if the path is already in the list of paths. The method returns the empty string as its result. - [call [cmd ::doctools::toc::parse] [method {include remove}] [arg path]] This method removes the [arg path] from the list of paths searched when looking for an include file. The call is ignored if the path is not contained in the list of paths. The method returns the empty string as its result. - [call [cmd ::doctools::toc::parse] [method {include clear}]] This method clears the list of search paths for include files. - [call [cmd ::doctools::toc::parse] [method vars]] This method returns a dictionary containing the current set of predefined variables known to the [cmd vset] markup command during processing. - [call [cmd ::doctools::toc::parse] [method {var set}] [arg name] [arg value]] This method adds the variable [arg name] to the set of predefined variables known to the [cmd vset] markup command during processing, and gives it the specified [arg value]. The method returns the empty string as its result. - [call [cmd ::doctools::toc::parse] [method {var unset}] [arg name]] This method removes the variable [arg name] from the set of predefined variables known to the [cmd vset] markup command during processing. The method returns the empty string as its result. - [call [cmd ::doctools::toc::parse] [method {var clear}] [opt [arg pattern]]] This method removes all variables matching the [arg pattern] from the set of predefined variables known to the [cmd vset] markup command @@ -116,12 +110,10 @@ The pattern matching is done with [cmd {string match}], and the default pattern used when none is specified, is [const *]. [list_end] - - [section {Parse errors}] The format of the parse error messages thrown when encountering violations of the [term doctoc] markup syntax is human readable and @@ -172,13 +164,12 @@ the set of errors found in the included file, using the format described here. [list_end] [list_end] - [include include/format/doctoc.inc] [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/doctools2toc/structure.man ================================================================== --- modules/doctools2toc/structure.man +++ modules/doctools2toc/structure.man @@ -1,12 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin doctools::toc::structure n 0.1] +[keywords deserialization] +[keywords doctoc] +[keywords doctools] +[keywords serialization] [copyright {2009 Andreas Kupries }] [moddesc {Documentation tools}] [titledesc {Doctoc serialization utilities}] [category {Documentation tools}] -[keywords doctoc doctools serialization deserialization] [require doctools::toc::structure [opt 0.1]] [require Tcl 8.4] [require logger] [require snit] [description] @@ -47,11 +50,10 @@ [para] For the specification of regular and canonical serializations see the section [sectref {ToC serialization format}]. - [call [cmd ::doctools::toc::structure] [method verify-as-canonical] \ [arg serial]] This command verifies that the content of [arg serial] is a valid [term canonical] serialization of a table of contents and will throw @@ -60,11 +62,10 @@ [para] For the specification of canonical serializations see the section [sectref {ToC serialization format}]. - [call [cmd ::doctools::toc::structure] [method canonicalize] [arg serial]] This command assumes that the content of [arg serial] is a valid [term regular] serialization of a table of contents and will throw an @@ -79,11 +80,10 @@ [para] For the specification of regular and canonical serializations see the section [sectref {ToC serialization format}]. - [call [cmd ::doctools::toc::structure] [method print] [arg serial]] This command assumes that the argument [arg serial] contains a valid regular serialization of a table of contents and returns a string containing that table in a human readable form. @@ -95,11 +95,10 @@ [para] For the specification of regular serializations see the section [sectref {ToC serialization format}]. - [call [cmd ::doctools::toc::structure] [method merge] \ [arg seriala] [arg serialb]] This command accepts the regular serializations of two tables of @@ -142,12 +141,11 @@ For the specification of regular and canonical serializations see the section [sectref {ToC serialization format}]. [list_end] - [include include/serialization.inc] [vset CATEGORY doctools] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/dtplite/dtplite.man ================================================================== --- modules/dtplite/dtplite.man +++ modules/dtplite/dtplite.man @@ -1,7 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin dtplite n 1.1] +[see_also {docidx introduction}] +[see_also {doctoc introduction}] +[see_also {doctools introduction}] +[keywords conversion] +[keywords docidx] +[keywords doctoc] +[keywords doctools] +[keywords HTML] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] [copyright {2004-2013 Andreas Kupries }] [titledesc {Lightweight DocTools Markup Processor}] [moddesc {Documentation toolbox}] [category {Documentation tools}] [description] @@ -15,11 +27,10 @@ [para] [syscmd dtplite] is based upon the package [package doctools], like the other two processors. - [subsection {USE CASES}] [syscmd dtplite] was written with the following three use cases in mind. @@ -89,34 +100,30 @@ The generated document will be written to a file in that directory, and the name of that file will be derived from the [arg inputfile], the [arg format], and the value given to option [option -ext] (if present). - [arg_def (path|handle) format in] This argument specifies the formatting engine to use when processing the input, and thus the format of the generated document. See section [sectref FORMATS] for the possibilities recognized by the application. - [arg_def path inputfile in] This argument specifies the path to the file to process. It has to exist, must be readable, and written in [term doctools] format. [list_end] [para] - [call [cmd dtplite] [const validate] [arg inputfile]] This is a simpler form for use case [lb]1[rb]. The "validate" format generates no output at all, only syntax checks are performed. As such the specification of an output file or other options is not necessary and left out. - [call [cmd dtplite] [option -o] [arg output] [opt options] [arg format] [arg inputdirectory]] This is the form for use case [lb]2[rb]. It differs from the form for use case [lb]1[rb] by having the input documents specified through a @@ -127,11 +134,10 @@ [para] The input documents are all files in [arg inputdirectory] or any of its subdirectories which were recognized by [cmd fileutil::fileType] as containing text in [term doctools] format. - [call [cmd dtplite] [option -merge] [option -o] [arg output] [opt options] [arg format] [arg inputdirectory]] This is the form for use case [lb]3[rb]. The only difference to the form for use case [lb]2[rb] is the additional option [option -merge]. @@ -163,11 +169,10 @@ This option specifies an exclude (glob) pattern. Any files identified as manpages to process which match the exclude pattern are ignored. The option can be provided multiple times, each usage adding an additional pattern to the list of exclusions. - [opt_def -ext string] If the name of an output file has to be derived from the name of an input file it will use the name of the [arg format] as the extension by default. This option here will override this however, forcing it to @@ -175,11 +180,10 @@ name of the output file is fully specified through option [option -o]. [para] When used multiple times only the last definition is relevant. - [opt_def -header file] This option can be used if and only if the selected [arg format] provides an engine parameter named "header". It takes the contents of @@ -193,21 +197,19 @@ [para] When used multiple times only the last definition is relevant. - [opt_def -footer file] Like [option -header], except that: Any navigation buttons are ignored, the corresponding required engine parameter is named "footer", and the data is inserted just before the tag [const ]. [para] When used multiple times only the last definition is relevant. - [opt_def -style file] This option can be used if and only if the selected [arg format] provides an engine parameter named "meta". When specified it will @@ -226,20 +228,18 @@ [para] When used multiple times only the last definition is relevant. - [opt_def -toc path|text] This option specifies a doctoc file (or text) to use for the table of contents instead of generating our own. [para] When used multiple times only the last definition is relevant. - [opt_def -pre+toc "label path|text"] [opt_def -post+toc "label path|text"] This option specifies additional doctoc files (or texts) to use in @@ -266,11 +266,10 @@ [para] The url can be relative. In that case it is assumed to be relative to the main files (TOC and Keyword index), and will be transformed for all others to still link properly. - [opt_def -postnav "label url"] Use this option to specify a navigation button with [arg label] to display and the [arg url] to link to. This option can be used if and only if the selected [arg format] provides an engine parameter named @@ -287,11 +286,10 @@ [para] The url can be relative. In that case it is assumed to be relative to the main files (TOC and Keyword index), and will be transformed for all others to still link properly. [list_end] - [subsection FORMATS] At first the [arg format] argument will be treated as a path to a tcl file containing the code for the requested formatting engine. The @@ -342,10 +340,22 @@ The processor generates Wiki markup as understood by [syscmd wikit]. [def [const list]] The processor extracts the information provided by [cmd manpage_begin]. +[see_also {docidx introduction}] +[see_also {doctoc introduction}] +[see_also {doctools introduction}] +[keywords conversion] +[keywords docidx] +[keywords doctoc] +[keywords doctools] +[keywords HTML] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] This format is used internally to extract the meta data from which both table of contents and keyword index are derived from. [def [const null]] @@ -352,11 +362,10 @@ The processor does not generate any output. This is equivalent to [const validate]. [list_end] - [subsection {DIRECTORY STRUCTURES}] In this section we describe the directory structures generated by the application under [arg output] when processing all documents in an @@ -384,11 +393,10 @@ generated for a file FOO located at [example { inputdirectory/path/to/FOO }] - [def "[lb]3[rb]"] When merging many packages into a unified set of documents the generated directory structure is a bit deeper: @@ -432,23 +440,8 @@ They are left in place, i.e. not deleted, to serve as demonstrations of doctoc and docidx markup. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the application it describes, will undoubtedly -contain bugs and other problems. - -Please report such in the category [emph doctools] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -application and/or documentation. - - -[see_also {doctools introduction}] -[see_also {docidx introduction}] -[see_also {doctoc introduction}] -[keywords manpage TMML HTML nroff conversion markup] -[keywords doctools docidx doctoc] +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/exif/exif.man ================================================================== --- modules/exif/exif.man +++ modules/exif/exif.man @@ -1,13 +1,16 @@ [manpage_begin exif n 1.1.2] +[keywords exif] +[keywords jpeg] +[keywords {maker note}] +[keywords tiff] [moddesc {EXIF parsing}] [titledesc {Tcl EXIF extracts and parses EXIF fields from digital images}] [category {File formats}] [require Tcl 8.2] [require exif [opt 1.1.2]] [description] -[keywords exif jpeg {maker note} tiff] [para] The EXIF package is a recoding of Chris Breeze's Perl package to do the same thing. This version accepts a channel as input and returns a serialized array with all the recognised fields parsed out. @@ -16,11 +19,11 @@ There is also a function to obtain a list of all possible field names that might be present, which is useful in building GUIs that present such information. -[section COMMANDS] +[section COMMANDS] [list_begin definitions] [call [cmd exif::analyze] [arg channel] [opt [arg thumbnail]]] @@ -41,11 +44,10 @@ [call [cmd exif::analyzeFile] [arg filename] [opt [arg thumbnail]]] This is a file-based wrapper around [cmd exif::analyze]. Instead of taking a stream it takes a [arg filename] and analyzes the contents of the specified file. - [call [cmd exif::fieldnames]] This returns a list of all possible field names. That is, the array returned by [cmd exif::analyze] will not contain keys that are not @@ -71,18 +73,8 @@ [section ACKNOWLEDGEMENTS] This code is a direct translation of version 1.3 of exif.pl by Chris Breeze. See the source for full headers, references, etc. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph exif] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY exif] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fileutil/fileutil.man ================================================================== --- modules/fileutil/fileutil.man +++ modules/fileutil/fileutil.man @@ -1,14 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin fileutil n 1.14.5] +[keywords cat] +[keywords {file utilities}] +[keywords grep] +[keywords {temp file}] +[keywords test] +[keywords touch] +[keywords type] [moddesc {file utilities}] [titledesc {Procedures implementing some file utilities}] [category {Programming tools}] [require Tcl 8] [require fileutil [opt 1.14.5]] [description] -[keywords {file utilities} touch grep type {temp file} test cat] [para] This package provides implementations of standard unix utilities. [list_begin definitions] @@ -33,11 +39,10 @@ This command resolves all symbolic links in the [arg path] and returns the changed path as its result. In contrast to the builtin [cmd {file normalize}] this command resolves a symbolic link in the last element of the path as well. - [call [cmd ::fileutil::test] [arg path] [arg codes] [opt [arg msgvar]] [opt [arg label]]] A command for the testing of several properties of a [arg path]. The properties to test for are specified in [arg codes], either as a list @@ -74,11 +79,10 @@ [cmd {file isfile}] [def "[emph d]ir"] [cmd {file isdirectory}] [list_end] - [call [cmd ::fileutil::cat] ([opt [arg options]] [arg file])...] A tcl implementation of the UNIX [syscmd cat] command. Returns the contents of the specified file(s). The arguments are files to read, with interspersed options configuring the process. If there are @@ -99,26 +103,23 @@ Each file can have its own set of options coming before it, and for anything not specified directly the defaults are inherited from the options of the previous file. The first file inherits the system default for unspecified options. - [call [cmd ::fileutil::writeFile] [opt [arg options]] [arg file] [arg data]] The command replaces the current contents of the specified [arg file] with [arg data], with the process configured by the options. The command accepts the same options as [cmd ::fileutil::cat]. The specification of a non-existent file is legal and causes the command to create the file (and all required but missing directories). - [call [cmd ::fileutil::appendToFile] [opt [arg options]] [arg file] [arg data]] This command is like [cmd ::fileutil::writeFile], except that the previous contents of [arg file] are not replaced, but appended to. The command accepts the same options as [cmd ::fileutil::cat] - [call [cmd ::fileutil::insertIntoFile] [opt [arg options]] [arg file] [arg at] [arg data]] This comment is similar to [cmd ::fileutil::appendToFile], except that the new data is not appended at the end, but inserted at a specified @@ -136,11 +137,10 @@ [para] The command accepts the same options as [cmd ::fileutil::cat]. - [call [cmd ::fileutil::removeFromFile] [opt [arg options]] [arg file] [arg at] [arg n]] This command is the complement to [cmd ::fileutil::insertIntoFile], removing [arg n] characters from the [arg file], starting at location [arg at]. The specified location [arg at] has to be an integer number in the @@ -153,11 +153,10 @@ [para] The command accepts the same options as [cmd ::fileutil::cat]. - [call [cmd ::fileutil::replaceInFile] [opt [arg options]] [arg file] [arg at] [arg n] [arg data]] This command is a combination of [cmd ::fileutil::removeFromFile] and [cmd ::fileutil::insertIntoFile]. It first removes the part of the contents specified by the arguments [arg at] and [arg n], and then @@ -169,11 +168,10 @@ are obeyed. [para] The command accepts the same options as [cmd ::fileutil::cat]. - [call [cmd ::fileutil::updateInPlace] [opt [arg options]] [arg file] [arg cmd]] This command can be seen as the generic core functionality of [cmd ::fileutil::replaceInFile]. @@ -189,11 +187,10 @@ [para] The command accepts the same options as [cmd ::fileutil::cat]. - [call [cmd ::fileutil::fileType] [arg filename]] An implementation of the UNIX [syscmd file] command, which uses various heuristics to guess the type of a file. Returns a list specifying as much type information as can be determined about the @@ -206,11 +203,10 @@ if available), message pgp, binary pdf, text ps, text eps, binary gravity_wave_data_frame, compressed bzip, compressed gzip, compressed zip, compressed tar, audio wave, audio mpeg, and link. It further detects doctools, doctoc, and docidx documentation files, and tklib diagrams. - [call [cmd ::fileutil::find] [opt "[arg basedir] [opt [arg filtercmd]]"]] An implementation of the unix command [syscmd find]. Adapted from the Tcler's Wiki. Takes at most two arguments, the path to the directory @@ -243,11 +239,10 @@ package require fileutil proc is_tcl {name} {return [string match *.tcl $name]} set tcl_files [fileutil::find . is_tcl] }] - [call [cmd ::fileutil::findByPattern] [arg basedir] \ [opt [option -regexp]|[option -glob]] [opt [option --]] \ [arg patterns]] This command is based upon the [package TclX] command @@ -262,21 +257,19 @@ patterns. The options before the pattern-list determine the style of matching, either regexp or glob. glob-style matching is the default if no options are given. Usage of the option [option --] stops option processing. This allows the use of a leading '-' in the patterns. - [call [cmd ::fileutil::foreachLine] [arg {var filename cmd}]] The command reads the file [arg filename] and executes the script [arg cmd] for every line in the file. During the execution of the script the variable [arg var] is set to the contents of the current line. The return value of this command is the result of the last invocation of the script [arg cmd] or the empty string if the file was empty. - [call [cmd ::fileutil::grep] [arg pattern] [opt [arg files]]] Implementation of [syscmd grep]. Adapted from the Tcler's Wiki. The first argument defines the [arg pattern] to search for. This is @@ -313,11 +306,10 @@ directory is stripped from the [arg path]. The possibly modified path is returned as the result of the command. If the current working directory itself was specified for [arg path] the result is the string "[const .]". - [call [cmd ::fileutil::stripPath] [arg prefix] [arg path]] If, and only of the [arg path] is inside of the directory [file prefix] (or the prefix directory itself) it is made relative to @@ -325,11 +317,10 @@ the [arg path]. The possibly modified path is returned as the result of the command. If the prefix directory itself was specified for [arg path] the result is the string "[const .]". - [call [cmd ::fileutil::jail] [arg jail] [arg path]] This command ensures that the [arg path] is not escaping the directory [arg jail]. It always returns an absolute path derived from [arg path] @@ -347,11 +338,10 @@ happens if [arg path] is relative, except that nothing is stripped of it. Before adding the [arg jail] prefix the [arg path] is lexically normalized to prevent the caller from using [const ..] segments in [arg path] to escape the jail. - [call [cmd ::fileutil::touch] [opt [option -a]] [opt [option -c]] [opt [option -m]] [opt "[option -r] [arg ref_file]"] [opt "[option -t] [arg time]"] [arg filename] [opt [arg ...]]] Implementation of [syscmd touch]. Alter the atime and mtime of the specified files. If [option -c], do not create files if they do not already exist. If [option -r], use the atime and mtime from @@ -363,11 +353,10 @@ [option -t]. If [option -a], only change the atime. If [option -m], only change the mtime. [para] [emph {This command is not available for Tcl versions less than 8.3.}] - [call [cmd ::fileutil::tempdir]] The command returns the path of a directory where the caller can place temporary files, such as [file /tmp] on Unix systems. The @@ -439,12 +428,10 @@ [para] The code was taken from [uri http://wiki.tcl.tk/772], attributed to Igor Volobouev and anon. - - [call [cmd ::fileutil::relative] [arg base] [arg dst]] This command takes two directory paths, both either absolute or relative and computes the path of [arg dst] relative to [arg base]. This relative path is returned as the result of the command. As implied in the previous @@ -453,11 +440,10 @@ [para] [emph Note:] The processing done by this command is purely lexical. Symbolic links are [emph not] taken into account. - [call [cmd ::fileutil::relativeUrl] [arg base] [arg dst]] This command takes two file paths, both either absolute or relative and computes the path of [arg dst] relative to [arg base], as seen @@ -475,18 +461,9 @@ [emph Note:] The processing done by this command is purely lexical. Symbolic links are [emph not] taken into account. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph fileutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - + +[vset CATEGORY fileutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fileutil/multi.man ================================================================== --- modules/fileutil/multi.man +++ modules/fileutil/multi.man @@ -1,16 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin fileutil::multi n 0.1] +[keywords copy] +[keywords {file utilities}] +[keywords move] +[keywords multi-file] +[keywords remove] [moddesc {file utilities}] [titledesc {Multi-file operation, scatter/gather, standard object}] [category {Programming tools}] [require Tcl 8.4] [require fileutil::multi [opt 0.1]] [require fileutil::multi::op [opt 0.1]] [require wip [opt 1.0]] [description] -[keywords {file utilities} copy move remove multi-file] [para] This package provides a single command to perform actions on multiple files selected by glob patterns. It is a thin layer over the package [package fileutil::multi::op] which provides objects for the @@ -45,17 +49,8 @@ The result of the command is the result generated by the last file command it executed. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph fileutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY fileutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fileutil/multiop.man ================================================================== --- modules/fileutil/multiop.man +++ modules/fileutil/multiop.man @@ -1,15 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin fileutil::multi::op n 0.5.3] +[keywords copy] +[keywords {file utilities}] +[keywords move] +[keywords multi-file] +[keywords remove] [moddesc {file utilities}] [titledesc {Multi-file operation, scatter/gather}] [category {Programming tools}] [require Tcl 8.4] [require fileutil::multi::op [opt 0.5.3]] [require wip [opt 1.0]] [description] -[keywords {file utilities} copy move remove multi-file] [para] This package provides objects which are able to perform actions on multiple files selected by glob patterns. @@ -54,11 +58,10 @@ [list_end] [para] - [section {OBJECT API}] The following methods are possible for multi-file operation objects: [list_begin definitions] @@ -73,11 +76,10 @@ The result of the method is the result generated by the last file command it executed. [list_end] - [section {FILE API}] Both object constructor and method [method do] take a list of words and interpret them as file commands to execute. The names were chosen @@ -236,11 +238,11 @@ values (i.e. empty), but nothing else. [call [cmd the-set] [arg varname]] Like [cmd the], however the set of files to use is not specified -implicitly per a glob pattern, but contained and loaded from the +implicitly per a glob pattern, but contained and loaded from the specified variable. The operation [cmd expand] is not available if this command is used. [call [cmd ->] [arg varname]] @@ -317,11 +319,10 @@ Returns the current strictness. [call [cmd type?]] Returns the current path type limiter. [list_end] - [section EXAMPLES] The following examples assume that the variable [var F] contains a reference to a multi-file operation object. @@ -394,17 +395,8 @@ but not *.html not index \\ the index \\ as pkgIndex.tcl }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph fileutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY fileutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fileutil/traverse.man ================================================================== --- modules/fileutil/traverse.man +++ modules/fileutil/traverse.man @@ -1,16 +1,17 @@ [comment {-*- text -*- doctools manpage}] [manpage_begin fileutil_traverse n 0.4.3] +[keywords {directory traversal}] +[keywords traversal] [moddesc {file utilities}] [titledesc {Iterative directory traversal}] [category {Programming tools}] [require Tcl 8.3] [require fileutil::traverse [opt 0.4.3]] [require fileutil] [require control] [description] -[keywords {directory traversal} traversal] [para] This package provides objects for the programmable traversal of directory hierarchies. @@ -57,11 +58,10 @@ This method is the most highlevel one provided by traversal objects. When invoked it returns a list containing the names of all files and directories matching the current configuration of the traverser. - [call [cmd \$traverser] [method foreach] [arg filevar] [arg script]] The highlevel [method files] method (see above) is based on this mid-level method. When invoked it finds all files and directories matching per the current configuration and executes the [arg script] @@ -68,11 +68,10 @@ for each path. The current path under consideration is stored in the variable named by [arg filevar]. Both variable and script live / are executed in the context of the caller of the method. In the method [method files] the script simply saves the found paths into the list to return. - [call [cmd \$traverser] [method next] [arg filevar]] This is the lowest possible interface to the traverser, the core all higher methods are built on. When invoked it returns a boolean value @@ -85,11 +84,10 @@ it returned [const False]. This method is exposed so that we are also able to incrementally traverse a directory hierarchy in an event-based manner. [list_end] - [section OPTIONS] [list_begin options] [opt_def -prefilter command_prefix] @@ -122,19 +120,8 @@ to the caller, i.e. however invoked the [method next]. Any other results from the callback are ignored. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph fileutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY fileutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ftp/ftp.man ================================================================== --- modules/ftp/ftp.man +++ modules/ftp/ftp.man @@ -1,14 +1,21 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin ftp n 2.4.11] +[see_also ftpd] +[see_also mime] +[see_also pop3] +[see_also smtp] +[keywords ftp] +[keywords internet] +[keywords net] +[keywords {rfc 959}] [moddesc {ftp client}] [titledesc {Client-side tcl implementation of the ftp protocol}] [category Networking] [require Tcl 8.2] [require ftp [opt 2.4.11]] [description] - [para] The ftp package provides the client side of the ftp protocol as specified in RFC 959 ([uri http://www.rfc-editor.org/rfc/rfc959.txt]). @@ -425,20 +432,8 @@ 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]. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ftp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also ftpd smtp pop3 mime] -[keywords ftp {rfc 959} internet net] +[vset CATEGORY ftp] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ftp/ftp_geturl.man ================================================================== --- modules/ftp/ftp_geturl.man +++ modules/ftp/ftp_geturl.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin ftp::geturl n 0.2.1] +[see_also ftpd] +[see_also mime] +[see_also pop3] +[see_also smtp] +[keywords ftp] +[keywords internet] +[keywords net] +[keywords {rfc 959}] [moddesc {ftp client}] [titledesc {Uri handler for ftp urls}] [category Networking] [require Tcl 8.2] [require ftp::geturl [opt 0.2.1]] @@ -41,20 +49,8 @@ The attributes of the link, including the path it refers to. [list_end] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ftp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also ftpd smtp pop3 mime] -[keywords ftp {rfc 959} internet net] +[vset CATEGORY ftp] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ftpd/ftpd.man ================================================================== --- modules/ftpd/ftpd.man +++ modules/ftpd/ftpd.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin ftpd n 1.2.6] +[keywords ftp] +[keywords ftpd] +[keywords ftpserver] +[keywords {rfc 959}] +[keywords services] [moddesc {Tcl FTP Server Package}] [titledesc {Tcl FTP server implementation}] [category Networking] [require Tcl 8.3] [require ftpd [opt 1.2.6]] @@ -72,11 +77,10 @@ called whenever a transfer of data to or from the client has completed. [list_end] [list_end] - [section CALLBACKS] [list_begin definitions] @@ -214,11 +218,10 @@ The store subcommand receives the path of a file to write as its only argument. The store subcommand returns a writable channel. [list_end] - [def "[cmd closeCmd]"] The [cmd closeCmd] receives no arguments when it is invoked, and any return value it may generate is discarded. @@ -232,11 +235,10 @@ which was transfered, and a (possibly empty) error message. Any return value it may generate is discarded. [list_end] - [section VARIABLES] [list_begin definitions] @@ -251,38 +253,26 @@ server. This address is printed out as part of the response to the [cmd {FTP HELP}] command. [def [var ::ftpd::port]] -The port that the ftp server should listen on. -If port is specified as zero, the operating system will allocate an -unused port for use as a server socket; afterwards, the variable will +The port that the ftp server should listen on. +If port is specified as zero, the operating system will allocate an +unused port for use as a server socket; afterwards, the variable will contain the port number that was allocated. [def [var ::ftpd::welcome]] The message that is printed out when the user first connects to the ftp server. - [def [var ::ftpd::CurrentSocket]] Accessible to all callbacks and all filesystem commands (which are a special form of callback) and contains the handle of the socket channel which was active when the callback was invoked. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ftpd] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords ftpd ftp ftpserver services {rfc 959}] +[vset CATEGORY ftpd] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fumagic/cfront.man ================================================================== --- modules/fumagic/cfront.man +++ modules/fumagic/cfront.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin fileutil::magic::cfront n 1.0] +[see_also file(1)] +[see_also fileutil] +[see_also magic(5)] +[keywords {file recognition}] +[keywords {file type}] +[keywords {file utilities}] +[keywords mime] +[keywords type] [moddesc {file utilities}] [titledesc {Generator core for compiler of magic(5) files}] [category {Programming tools}] [require Tcl 8.4] [require fileutil::magic::cfront [opt 1.0]] @@ -34,19 +42,17 @@ [para] The result of the command is a Tcl script containing the generated recognizer. - [call [cmd ::fileutil::magic::cfront::procdef] [arg procname] [arg path]...] This command behaves like [cmd ::fileutil::magic::cfront::compile] with regard to the specified path arguments, then wraps the resulting recognizer script into a procedure named [arg procname], puts code setting up the namespace of [arg procname] in front, and returns the resulting script. - [call [cmd ::fileutil::magic::cfront::install] [arg path]...] This command uses [cmd ::fileutil::magic::cfront::procdef] to compile each of the paths into a recognizer procedure and installs the result @@ -58,21 +64,8 @@ file/directory used in its creation, with file/directory [file FOO] causing the creation of procedure [const ::fileutil::magic::/FOO::run]. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {fileutil :: magic}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also fileutil file(1) magic(5)] -[keywords type mime {file utilities} {file type} {file recognition}] +[vset CATEGORY {fileutil :: magic}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fumagic/cgen.man ================================================================== --- modules/fumagic/cgen.man +++ modules/fumagic/cgen.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin fileutil::magic::cgen n 1.0] +[see_also file(1)] +[see_also fileutil] +[see_also magic(5)] +[keywords {file recognition}] +[keywords {file type}] +[keywords {file utilities}] +[keywords mime] +[keywords type] [moddesc {file utilities}] [titledesc {Generator core for compiler of magic(5) files}] [category {Programming tools}] [require Tcl 8.4] [require fileutil::magic::cgen [opt 1.0]] @@ -29,17 +37,15 @@ [para] The [arg script] is in the format specified by magic(5). - [call [cmd ::fileutil::magic::cgen::treedump] [arg tree]] This command takes a [arg tree] as generated by [cmd ::fileutil::magic::cgen::2tree] and returns a string encoding the tree for human consumption, to aid in debugging. - [call [cmd ::fileutil::magic::cgen::treegen] [arg tree] [arg node]] This command takes a [arg tree] as generated by [cmd ::fileutil::magic::cgen::2tree] and returns a Tcl script, the @@ -50,21 +56,8 @@ the recognizer runtime package [package fileutil::magic::rt] to perform its duties. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {fileutil :: magic}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also fileutil file(1) magic(5)] -[keywords type mime {file utilities} {file type} {file recognition}] +[vset CATEGORY {fileutil :: magic}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fumagic/filetypes.man ================================================================== --- modules/fumagic/filetypes.man +++ modules/fumagic/filetypes.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin fileutil::magic::filetype n 1.0.2] +[see_also file(1)] +[see_also fileutil] +[see_also magic(5)] +[keywords {file recognition}] +[keywords {file type}] +[keywords {file utilities}] +[keywords type] [moddesc {file utilities}] [titledesc {Procedures implementing file-type recognition}] [category {Programming tools}] [require Tcl 8.4] [require fileutil::magic::filetype [opt 1.0.2]] @@ -49,20 +56,8 @@ the magic definitions used by it. The latter were used by us to generate this recognizer. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {fileutil :: magic}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also fileutil file(1) magic(5)] -[keywords type {file utilities} {file type} {file recognition}] +[vset CATEGORY {fileutil :: magic}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fumagic/mimetypes.man ================================================================== --- modules/fumagic/mimetypes.man +++ modules/fumagic/mimetypes.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin fileutil::magic::mimetype n 1.0.2] +[see_also file(1)] +[see_also fileutil] +[see_also magic(5)] +[keywords {file recognition}] +[keywords {file type}] +[keywords {file utilities}] +[keywords mime] +[keywords type] [moddesc {file utilities}] [titledesc {Procedures implementing mime-type recognition}] [category {Programming tools}] [require Tcl 8.4] [require fileutil::magic::mimetype [opt 1.0.2]] @@ -45,20 +53,8 @@ the magic definitions used by it. The latter were used by us to generate this recognizer. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {fileutil :: magic}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also fileutil file(1) magic(5)] -[keywords type mime {file utilities} {file type} {file recognition}] +[vset CATEGORY {fileutil :: magic}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/fumagic/rtcore.man ================================================================== --- modules/fumagic/rtcore.man +++ modules/fumagic/rtcore.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin fileutil::magic::rt n 1.0] +[see_also file(1)] +[see_also fileutil] +[see_also magic(5)] +[keywords {file recognition}] +[keywords {file type}] +[keywords {file utilities}] +[keywords mime] +[keywords type] [moddesc {file utilities}] [titledesc {Runtime core for file type recognition engines written in pure Tcl}] [category {Programming tools}] [require Tcl 8.4] [require fileutil::magic::rt [opt 1.0]] @@ -32,11 +40,10 @@ [para] The command returns the channel handle of the opened file as its result. - [call [cmd ::fileutil::magic::rt::close]] This command closes the last file opened via [cmd ::fileutil::magic::rt::open] and shuts the runtime down. @@ -48,16 +55,14 @@ [para] This command returns the empty string as its result. - [call [cmd ::fileutil::magic::rt::file_start] [arg name]] This command marks the start of a magic file when debugging. It returns the empty string as its result. - [call [cmd ::fileutil::magic::rt::result] [opt [arg msg]]] This command returns the current result and stops processing. @@ -64,11 +69,10 @@ [para] If [arg msg] is specified its text is added to the result before it is returned. See [cmd ::fileutil::magic::rt::emit] for the allowed special character sequences. - [call [cmd ::fileutil::magic::rt::resultv] [opt [arg msg]]] This command returns the current result. @@ -79,11 +83,10 @@ If [arg msg] is specified its text is added to the result before it is returned. See [cmd ::fileutil::magic::rt::emit] for the allowed special character sequences. - [call [cmd ::fileutil::magic::rt::emit] [arg msg]] This command adds the text [arg msg] to the result buffer. The message may contain the following special character sequences. They will be replaced with buffered values before the message is added to @@ -93,11 +96,10 @@ [def [const \\b]] This sequence is removed [def [const %s]] Replaced with the last buffered string value. [def [const %ld]] Replaced with the last buffered numeric value. [def [const %d]] See above. [list_end] - [comment [call [cmd ::fileutil::magic::rt::offset] [arg where]]] [comment { Handling of complex offsets. Currently not implemented. Always returns zero. @@ -125,11 +127,10 @@ Nv lelong 0 &0x8080ffff }] For the possible types see section [sectref {NUMERIC TYPES}]. - [call [cmd ::fileutil::magic::rt::N] [arg type] [arg offset] [arg comp] [arg val] [opt [arg qual]]] This command behaves mostly like [cmd ::fileutil::magic::rt::Nv], except that it compares the fetched and masked value against [arg val] as specified with [arg comp] and returns the result of that @@ -148,48 +149,42 @@ The special comparison operator [const x] signals that no comparison should be done, or, in other words, that the fetched value will always match [arg val]. - [call [cmd ::fileutil::magic::rt::Nvx] [arg atlevel] [arg type] [arg offset] [opt [arg qual]]] This command behaves like [cmd ::fileutil::magic::rt::Nv], except that it additionally remembers the location in the file after the fetch in -the calling context, for the level [arg atlevel], for later use by +the calling context, for the level [arg atlevel], for later use by [cmd ::fileutil::magic::rt::R]. - [call [cmd ::fileutil::magic::rt::Nx] [arg atlevel] [arg type] [arg offset] [arg comp] [arg val] [opt [arg qual]]] This command behaves like [cmd ::fileutil::magic::rt::N], except that it additionally remembers the location in the file after the fetch in -the calling context, for the level [arg atlevel], for later use by +the calling context, for the level [arg atlevel], for later use by [cmd ::fileutil::magic::rt::R]. - [call [cmd ::fileutil::magic::rt::S] [arg offset] [arg comp] [arg val] [opt [arg qual]]] This command behaves like [cmd ::fileutil::magic::rt::N], except that it fetches and compares strings, not numeric data. The fetched value is also stored in the internal string buffer instead of the numeric buffer. - [call [cmd ::fileutil::magic::rt::Sx] [arg atlevel] [arg offset] [arg comp] [arg val] [opt [arg qual]]] This command behaves like [cmd ::fileutil::magic::rt::S], except that it additionally remembers the location in the file after the fetch in -the calling context, for the level [arg atlevel], for later use by +the calling context, for the level [arg atlevel], for later use by [cmd ::fileutil::magic::rt::R]. - [call [cmd ::fileutil::magic::rt::L] [arg newlevel]] This command sets the current level in the calling context to [arg newlevel]. The command returns the empty string as its result. - [call [cmd ::fileutil::magic::rt::I] [arg base] [arg type] [arg delta]] This command handles base locations specified indirectly through the contents of the inspected file. It returns the sum of [arg delta] and @@ -197,11 +192,10 @@ [arg base]. [para] For the possible types see section [sectref {NUMERIC TYPES}]. - [call [cmd ::fileutil::magic::rt::R] [arg offset]] This command handles base locations specified relative to the end of the last field one level above. @@ -212,11 +206,10 @@ based on the relative [arg offset] and returns it as its result. The base the offset is added to is the last location remembered for the level in the calling context. [list_end] - [section {NUMERIC TYPES}] [list_begin definitions] [def [const byte]] 8-bit integer @@ -238,21 +231,8 @@ [def [const ldate]] 32-bit integer timestamp, stored in native endianess [def [const beldate]] see above, stored in big endian [def [const leldate]] see above, stored in small/little endian [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {fileutil :: magic}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also fileutil file(1) magic(5)] -[keywords type mime {file utilities} {file type} {file recognition}] +[vset CATEGORY {fileutil :: magic}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/generator/generator.man ================================================================== --- modules/generator/generator.man +++ modules/generator/generator.man @@ -1,6 +1,17 @@ [manpage_begin generator n 0.1] +[keywords {control structure}] +[keywords coroutine] +[keywords filter] +[keywords foldl] +[keywords foldr] +[keywords foreach] +[keywords generator] +[keywords iterator] +[keywords map] +[keywords reduce] +[keywords scanl] [moddesc {Tcl Generator Commands}] [titledesc {Procedures for creating and using generators.}] [require Tcl 8.6] [require generator [opt 0.1]] [description] @@ -35,11 +46,11 @@ also provides a flexible [method foreach] command that loops through the values of one or more generators. This loop construct mimicks the functionality of the built-in Tcl [cmd foreach] command, including handling multiple return values and looping over multiple generators at once. Writing a generator is also a simple task, much like writing a normal procedure: simply use the [method define] -command to define the generator, and then call [method yield] instead of [cmd return]. +command to define the generator, and then call [method yield] instead of [cmd return]. For example, we can define a generator for looping through the integers in a particular range: [para] [example { @@ -91,11 +102,11 @@ Used in the definition of a generator, this command returns the next set of values to the consumer. Once the [method yield] command has been called the generator will suspend to allow the consumer to process that value. When the next value is requested, the generator will resume as if the yield command had -just returned, and can continue processing to yield the next result. The +just returned, and can continue processing to yield the next result. The [method yield] command must be called with at least one argument, but can be called with multiple arguments, in which case this is equivalent to calling [method yield] once for each argument. [call [cmd generator] [method foreach] [arg varList] [arg generator] [arg varList] \ @@ -283,11 +294,10 @@ proc + {a b} { expr {$a + $b} } proc sum gen { generator reduce + 0 $gen } puts [sum [range 1 10]] }] - [para] The [method reduce] operation is an extremely useful one, and a great variety of different operations can be defined using it. For example, we can define a factorial function as the product of a range using generators. This definition @@ -467,9 +477,6 @@ [section {BUGS, IDEAS, FEEDBACK}] Please report any errors in this document, or in the package it describes, to [uri {mailto:nem@cs.nott.ac.uk} {Neil Madden}]. - -[keywords generator coroutine {control structure} iterator foreach] -[keywords map filter foldl reduce foldr scanl] [manpage_end] Index: modules/gpx/gpx.man ================================================================== --- modules/gpx/gpx.man +++ modules/gpx/gpx.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin gpx n 0.9] +[keywords gps] +[keywords gpx] [copyright {2010, Keith Vetter }] [moddesc {GPS eXchange Format (GPX)}] [titledesc {Extracts waypoints, tracks and routes from GPX files}] [category {File formats}] [require Tcl 8.5] @@ -42,28 +44,28 @@ below, but keys [emph version] and [emph creator] will always be present. [call [cmd ::gpx::GetWaypointCount] [arg token]] -This procedure returns the number of waypoints defined in the GPX +This procedure returns the number of waypoints defined in the GPX data identified by [arg token]. [call [cmd ::gpx::GetAllWaypoints] [arg token]] -This procedure returns the a list of waypoints defined in the GPX +This procedure returns the a list of waypoints defined in the GPX data identified by [arg token]. The format of each waypoint item is described below. [call [cmd ::gpx::GetTrackCount] [arg token]] -This procedure returns the number of tracks defined in the GPX +This procedure returns the number of tracks defined in the GPX data identified by [arg token]. [call [cmd ::gpx::GetTrackMetadata] [arg token] [arg whichTrack]] -This procedure returns a dictionary of the metadata -associated track number [arg whichTrack] (1 based) in +This procedure returns a dictionary of the metadata +associated track number [arg whichTrack] (1 based) in the GPX data identified by [arg token]. The format of the metadata dictionary is described below. [call [cmd ::gpx::GetTrackPoints] [arg token] [arg whichTrack]] @@ -71,17 +73,17 @@ number [arg whichTrack] (1 based) in the GPX data identified by [arg token]. The format of the metadata dictionary is described below. [call [cmd ::gpx::GetRouteCount] [arg token]] -This procedure returns the number of routes defined in the GPX +This procedure returns the number of routes defined in the GPX data identified by [arg token]. [call [cmd ::gpx::GetRouteMetadata] [arg token] [arg whichRoute]] -This procedure returns a dictionary of the metadata -associated route number [arg whichRoute] (1 based) in +This procedure returns a dictionary of the metadata +associated route number [arg whichRoute] (1 based) in the GPX data identified by [arg token]. The format of the metadata dictionary is described below. [call [cmd ::gpx::GetRoutePoints] [arg token] [arg whichRoute]] @@ -110,15 +112,14 @@ [def "point item"] Each item in a track or route list of points consists of a list of three elements: [emph latitude], [emph longitude] and [emph "metadata dictionary"]. [emph Latitude] and [emph longitude] are decimal numbers. The [emph "metadata dictionary"] format is -described above. For points in a track, typically there will +described above. For points in a track, typically there will always be ele (elevation) and time metadata keys. [list_end] - [section "EXAMPLE"] [example { % set token [::gpx::Create myGpxFile.gpx] @@ -125,11 +126,11 @@ % set version [dict get [::gpx::GetGPXMetadata $token] version] % set trackCnt [::gpx::GetTrackCount $token] % set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0] % lassign $firstPoint lat lon ptMetadata % puts "first point in the first track is at $lat, $lon" -% if {[dict exists $ptMetadata ele]} { +% if {[dict exists $ptMetadata ele]} { puts "at elevation [dict get $ptMetadata ele] meters" } % ::gpx::Cleanup $token }] @@ -150,18 +151,8 @@ [list_end] [section AUTHOR] Keith Vetter -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph gpx] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords gpx gps] +[vset CATEGORY gpx] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_aycock/aycock.man ================================================================== --- modules/grammar_aycock/aycock.man +++ modules/grammar_aycock/aycock.man @@ -1,23 +1,29 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::aycock n 1.0] +[keywords ambiguous] +[keywords aycock] +[keywords earley] +[keywords grammar] +[keywords horspool] +[keywords parser] +[keywords parsing] +[keywords transducer] [copyright "2006 by Kevin B. Kenny Redistribution permitted under the terms of the Open\ Publication License "] [moddesc "Aycock-Horspool-Earley parser generator for Tcl"] [titledesc "Aycock-Horspool-Earley parser generator for Tcl"] [category "Grammars and finite automata"] [require Tcl 8.5] [require grammar::aycock [opt 1.0]] [description] -[keywords grammar parser aycock earley horspool] -[keywords ambiguous parsing transducer] [para] The [package grammar::aycock] package implements a parser generator for the class of parsers described -in John Aycock and R. Nigel Horspool. Practical Earley Parsing. -[emph "The Computer Journal,"] [emph 45](6):620-630, 2002. +in John Aycock and R. Nigel Horspool. Practical Earley Parsing. +[emph "The Computer Journal,"] [emph 45](6):620-630, 2002. [uri http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254] [section "PROCEDURES"] The [package grammar::aycock] package exports the single procedure: @@ -46,11 +52,11 @@ Destroys a parser constructed by [cmd ::aycock::parser]. [call [arg parserName] [method terminals]] -Returns a list of terminal symbols that may be presented in the +Returns a list of terminal symbols that may be presented in the [arg symList] argument to the [method parse] object command. [call [arg parserName] [method nonterminals]] Returns a list of nonterminal symbols that were defined in the @@ -128,7 +134,6 @@ The example, when run, prints [const 40]. [section KEYWORDS] Aycock, Earley, Horspool, parser, compiler - [manpage_end] Index: modules/grammar_fa/dacceptor.man ================================================================== --- modules/grammar_fa/dacceptor.man +++ modules/grammar_fa/dacceptor.man @@ -1,19 +1,27 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::fa::dacceptor n 0.1.1] +[keywords acceptance] +[keywords acceptor] +[keywords automaton] +[keywords {finite automaton}] +[keywords grammar] +[keywords parsing] +[keywords {regular expression}] +[keywords {regular grammar}] +[keywords {regular languages}] +[keywords state] +[keywords transducer] [copyright {2004 Andreas Kupries }] [moddesc {Finite automaton operations and usage}] [titledesc {Create and use deterministic acceptors}] [category {Grammars and finite automata}] [require Tcl 8.4] [require snit] [require struct::set] [require grammar::fa::dacceptor [opt 0.1.1]] [description] -[keywords acceptor acceptance grammar automaton {finite automaton}] -[keywords state {regular expression} {regular grammar}] -[keywords {regular languages} parsing transducer] [para] This package provides a class for acceptors constructed from deterministic [term {finite automatons}] (DFA). Acceptors are objects which can be given a string of symbols and tell if the DFA they are @@ -65,16 +73,14 @@ All acceptors provide the following methods for their manipulation: [list_begin definitions] - [call [arg daName] [method destroy]] Destroys the automaton, including its storage space and associated command. - [call [arg daName] [method accept?] [arg symbols]] Takes the list of [arg symbols] and checks if the FA the acceptor is based on would accept it. The result is a boolean value. [const True] @@ -88,20 +94,9 @@ [list_end] [para] [section EXAMPLES] -[para] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_fa] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - + +[vset CATEGORY grammar_fa] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_fa/dexec.man ================================================================== --- modules/grammar_fa/dexec.man +++ modules/grammar_fa/dexec.man @@ -1,19 +1,27 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::fa::dexec n 0.2] +[keywords automaton] +[keywords execution] +[keywords {finite automaton}] +[keywords grammar] +[keywords parsing] +[keywords {regular expression}] +[keywords {regular grammar}] +[keywords {regular languages}] +[keywords running] +[keywords state] +[keywords transducer] [copyright {2004 Andreas Kupries }] [copyright {2007 Bogdan }] [moddesc {Finite automaton operations and usage}] [titledesc {Execute deterministic finite automatons}] [category {Grammars and finite automata}] [require Tcl 8.4] [require snit] [require grammar::fa::dexec [opt 0.2]] [description] -[keywords execution running grammar automaton {finite automaton}] -[keywords state {regular expression} {regular grammar}] -[keywords {regular languages} parsing transducer] [para] This package provides a class for executors constructed from deterministic [term {finite automatons}] (DFA). Executors are objects which are given a string of symbols in a piecemal fashion, perform @@ -30,11 +38,10 @@ or a final state is entered this will be reported via the callback specified via the option [option -command]. Note that conversion of this into a pull model where the environment retrieves messages from the object and the object uses a callback to ask for more symbols is a trivial thing. - [para] [emph {Side note}]: @@ -87,16 +94,14 @@ All executors provide the following methods for their manipulation: [list_begin definitions] - [call [arg daName] [method destroy]] Destroys the automaton, including its storage space and associated command. - [call [arg daName] [method put] [arg symbol]] Takes the current state of the executor and the [arg symbol] and performs the appropriate state transition. Reports any errors @@ -107,24 +112,22 @@ When an error is reported all further invokations of [method put] will do nothing, until the error condition has been cleared via an invokation of method [method reset]. - [call [arg daName] [method reset]] Unconditionally sets the executor into the start state of the underlying FA. This also clears any error condition [method put] may have encountered. [call [arg daName] [method state]] -Returns the current state of the underlying FA. This allow for +Returns the current state of the underlying FA. This allow for introspection without the need to pass data from the callback command. [list_end] - [section {EXECUTOR CALLBACK}] The callback command [arg cmdprefix] given to an executor via the option [option -command] will be executed by the object at the global @@ -169,24 +172,12 @@ The FA changed state due to a transition. [arg stateid] is the new state. [list_end] - [para] [section EXAMPLES] -[para] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_fa] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - + +[vset CATEGORY grammar_fa] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_fa/fa.man ================================================================== --- modules/grammar_fa/fa.man +++ modules/grammar_fa/fa.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::fa n 0.4] +[keywords automaton] +[keywords {finite automaton}] +[keywords grammar] +[keywords parsing] +[keywords {regular expression}] +[keywords {regular grammar}] +[keywords {regular languages}] +[keywords state] +[keywords transducer] [copyright {2004-2009 Andreas Kupries }] [moddesc {Finite automaton operations and usage}] [titledesc {Create and manipulate finite automatons}] [category {Grammars and finite automata}] [require Tcl 8.4] @@ -9,13 +18,10 @@ [require struct::list] [require struct::set] [require grammar::fa::op [opt 0.2]] [require grammar::fa [opt 0.4]] [description] -[keywords grammar automaton {finite automaton}] -[keywords state {regular expression} {regular grammar}] -[keywords {regular languages} parsing transducer] [para] This package provides a container class for [term {finite automatons}] (Short: FA). @@ -37,11 +43,10 @@ [para] For more information about what a finite automaton is see section [sectref {FINITE AUTOMATONS}]. - [section API] The package exports the API described here. @@ -77,22 +82,19 @@ All automatons provide the following methods for their manipulation: [list_begin definitions] - [call [arg faName] [method destroy]] Destroys the automaton, including its storage space and associated command. - [call [arg faName] [method clear]] Clears out the definition of the automaton contained in [arg faName], but does [emph not] destroy the object. - [call [arg faName] [method =] [arg srcFA]] Assigns the contents of the automaton contained in [arg srcFA] to [arg faName], overwriting any @@ -109,11 +111,10 @@ [para] [example_begin] [arg faName] [method deserialize] [lb][arg srcFA] [method serialize][rb] [example_end] - [call [arg faName] [method -->] [arg dstFA]] This is the reverse assignment operator for automatons. It copies the automation contained in the object [arg faName] over the automaton definition in the object [arg dstFA]. @@ -125,11 +126,10 @@ This operation is in effect equivalent to [para] [example_begin] [arg dstFA] [method deserialize] [lb][arg faName] [method serialize][rb] [example_end] - [call [arg faName] [method serialize]] This method serializes the automaton stored in [arg faName]. In other words it returns a tcl [emph value] completely describing that @@ -213,30 +213,26 @@ }] [para] A possible one, because I did not care about creation order here - [call [arg faName] [method deserialize] [arg serialization]] This is the complement to [method serialize]. It replaces the automaton definition in [arg faName] with the automaton described by the [arg serialization] value. The old contents of [arg faName] are deleted by this operation. - [call [arg faName] [method states]] Returns the set of all states known to [arg faName]. - [call [arg faName] [method state] [method add] [arg s1] [opt "[arg s2] ..."]] Adds the states [arg s1], [arg s2], et cetera to the FA definition in [arg faName]. The operation will fail any of the new states is already declared. - [call [arg faName] [method state] [method delete] [arg s1] [opt "[arg s2] ..."]] Deletes the state [arg s1], [arg s2], et cetera, and all associated information from the FA definition in [arg faName]. The latter means @@ -243,54 +239,47 @@ that the information about in- or outbound transitions is deleted as well. If the deleted state was a start or final state then this information is invalidated as well. The operation will fail if the state [arg s] is not known to the FA. - [call [arg faName] [method state] [method exists] [arg s]] A predicate. It tests whether the state [arg s] is known to the FA in [arg faName]. The result is a boolean value. It will be set to [const true] if the state [arg s] is known, and [const false] otherwise. - [call [arg faName] [method state] [method rename] [arg s] [arg snew]] Renames the state [arg s] to [arg snew]. Fails if [arg s] is not a known state. Also fails if [arg snew] is already known as a state. - [call [arg faName] [method startstates]] Returns the set of states which are marked as [term start] states, also known as [term initial] states. See [sectref {FINITE AUTOMATONS}] for explanations what this means. - [call [arg faName] [method start] [method add] [arg s1] [opt "[arg s2] ..."]] Mark the states [arg s1], [arg s2], et cetera in the FA [arg faName] as [term start] (aka [term initial]). - [call [arg faName] [method start] [method remove] [arg s1] [opt "[arg s2] ..."]] Mark the states [arg s1], [arg s2], et cetera in the FA [arg faName] as [term {not start}] (aka [term {not accepting}]). - [call [arg faName] [method start?] [arg s]] A predicate. It tests if the state [arg s] in the FA [arg faName] is [term start] or not. The result is a boolean value. It will be set to [const true] if the state [arg s] is [term start], and [const false] otherwise. - [call [arg faName] [method start?set] [arg stateset]] A predicate. It tests if the set of states [arg stateset] contains at least one start state. They operation will fail if the set contains an @@ -297,39 +286,34 @@ element which is not a known state. The result is a boolean value. It will be set to [const true] if a start state is present in [arg stateset], and [const false] otherwise. - [call [arg faName] [method finalstates]] Returns the set of states which are marked as [term final] states, also known as [term accepting] states. See [sectref {FINITE AUTOMATONS}] for explanations what this means. - [call [arg faName] [method final] [method add] [arg s1] [opt "[arg s2] ..."]] Mark the states [arg s1], [arg s2], et cetera in the FA [arg faName] as [term final] (aka [term accepting]). - [call [arg faName] [method final] [method remove] [arg s1] [opt "[arg s2] ..."]] Mark the states [arg s1], [arg s2], et cetera in the FA [arg faName] as [term {not final}] (aka [term {not accepting}]). - [call [arg faName] [method final?] [arg s]] A predicate. It tests if the state [arg s] in the FA [arg faName] is [term final] or not. The result is a boolean value. It will be set to [const true] if the state [arg s] is [term final], and [const false] otherwise. - [call [arg faName] [method final?set] [arg stateset]] A predicate. It tests if the set of states [arg stateset] contains at least one final state. They operation will fail if the set contains an @@ -336,15 +320,13 @@ element which is not a known state. The result is a boolean value. It will be set to [const true] if a final state is present in [arg stateset], and [const false] otherwise. - [call [arg faName] [method symbols]] Returns the set of all symbols known to the FA [arg faName]. - [call [arg faName] [method symbols@] [arg s] [opt [arg d]]] Returns the set of all symbols for which the state [arg s] has transitions. If the empty symbol is present then [arg s] has epsilon transitions. If two @@ -361,43 +343,37 @@ for all states [var s] in [arg stateset]. If the empty symbol is present then at least one state contained in [arg stateset] has epsilon transitions. - [call [arg faName] [method symbol] [method add] [arg sym1] [opt "[arg sym2] ..."]] Adds the symbols [arg sym1], [arg sym2], et cetera to the FA definition in [arg faName]. The operation will fail any of the symbols is already declared. The empty string is not allowed as a value for the symbols. - [call [arg faName] [method symbol] [method delete] [arg sym1] [opt "[arg sym2] ..."]] Deletes the symbols [arg sym1], [arg sym2] et cetera, and all associated information from the FA definition in [arg faName]. The latter means that all transitions using the symbols are deleted as well. The operation will fail if any of the symbols is not known to the FA. - [call [arg faName] [method symbol] [method rename] [arg sym] [arg newsym]] Renames the symbol [arg sym] to [arg newsym]. Fails if [arg sym] is not a known symbol. Also fails if [arg newsym] is already known as a symbol. - [call [arg faName] [method symbol] [method exists] [arg sym]] A predicate. It tests whether the symbol [arg sym] is known to the FA in [arg faName]. The result is a boolean value. It will be set to [const true] if the symbol [arg sym] is known, and [const false] otherwise. - - [call [arg faName] [method next ] [arg s] [arg sym] [opt "[const -->] [arg next]"]] Define or query transition information. @@ -417,11 +393,10 @@ If [arg next] was not specified, then the method will return the set of states which can be reached from [arg s] through a single transition labeled with symbol [arg sym]. - [call [arg faName] [method !next] [arg s] [arg sym] [opt "[const -->] [arg next]"]] Remove one or more transitions from the Fa in [arg faName]. [para] @@ -435,11 +410,10 @@ The operation will fail if [arg s] and/or [arg next] are not known as states. It will also fail if a non-empty [arg sym] is not known as symbol. The empty string is acceptable, and allows the removal of epsilon transitions. - [call [arg faName] [method nextset] [arg stateset] [arg sym]] Returns the set of states which can be reached by a single transition originating in a state in the set [arg stateset] and labeled with the symbol [arg sym]. @@ -448,19 +422,17 @@ In other words, this is the union of [lb][arg faName] next [var s] [arg symbol][rb] for all states [var s] in [arg stateset]. - [call [arg faName] [method is] [method deterministic]] A predicate. It tests whether the FA in [arg faName] is a deterministic FA or not. The result is a boolean value. It will be set to [const true] if the FA is deterministic, and [const false] otherwise. - [call [arg faName] [method is] [method complete]] A predicate. It tests whether the FA in [arg faName] is a complete FA or not. A FA is complete if it has at least one transition per state @@ -475,20 +447,18 @@ Note: When a FA has epsilon-transitions transitions over a symbol for a state S can be indirect, i.e. not attached directly to S, but to a state in the epsilon-closure of S. The symbols for such indirect transitions count when computing completeness. - [call [arg faName] [method is] [method useful]] A predicate. It tests whether the FA in [arg faName] is an useful FA or not. A FA is useful if all states are [term reachable] and [term useful]. The result is a boolean value. It will be set to [const true] if the FA is deterministic, and [const false] otherwise. - [call [arg faName] [method is] [method epsilon-free]] A predicate. It tests whether the FA in [arg faName] is an epsilon-free FA or not. A FA is epsilon-free if it has no epsilon @@ -497,17 +467,14 @@ pre-condition for deterministic'ness. The result is a boolean value. It will be set to [const true] if the FA is deterministic, and [const false] otherwise. - - [call [arg faName] [method reachable_states]] Returns the set of states which are reachable from a start state by one or more transitions. - [call [arg faName] [method unreachable_states]] Returns the set of states which are not reachable from any start state by any number of transitions. This is @@ -515,25 +482,22 @@ [para] [example { [faName states] - [faName reachable_states] }] - [call [arg faName] [method reachable] [arg s]] A predicate. It tests whether the state [arg s] in the FA [arg faName] can be reached from a start state by one or more transitions. The result is a boolean value. It will be set to [const true] if the state can be reached, and [const false] otherwise. - [call [arg faName] [method useful_states]] Returns the set of states which are able to reach a final state by one or more transitions. - [call [arg faName] [method unuseful_states]] Returns the set of states which are not able to reach a final state by any number of transitions. This is @@ -541,27 +505,24 @@ [para] [example { [faName states] - [faName useful_states] }] - [call [arg faName] [method useful] [arg s]] A predicate. It tests whether the state [arg s] in the FA [arg faName] is able to reach a final state by one or more transitions. The result is a boolean value. It will be set to [const true] if the state is useful, and [const false] otherwise. - [call [arg faName] [method epsilon_closure] [arg s]] Returns the set of states which are reachable from the state [arg s] in the FA [arg faName] by one or more epsilon transitions, i.e transitions over the empty symbol, transitions which do not consume input. This is called the [term {epsilon closure}] of [arg s]. - [call [arg faName] [method reverse]] [call [arg faName] [method complete]] [call [arg faName] [method remove_eps]] [call [arg faName] [method trim] [opt [arg what]]] @@ -580,20 +541,16 @@ These methods provide more complex operations on the FA. Please see the same-named commands in the package [package grammar::fa::op] for descriptions of what they do. - - [list_end] [para] [section EXAMPLES] [para] - - [section {FINITE AUTOMATONS}] [para] For the mathematically inclined, a FA is a 5-tuple (S,Sy,St,Fi,T) where @@ -688,18 +645,8 @@ [para] Transducers are not handled by this package. They will get their own package in the future. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_fa] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_fa] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_fa/faop.man ================================================================== --- modules/grammar_fa/faop.man +++ modules/grammar_fa/faop.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::fa::op n 0.4] +[keywords automaton] +[keywords {finite automaton}] +[keywords grammar] +[keywords parsing] +[keywords {regular expression}] +[keywords {regular grammar}] +[keywords {regular languages}] +[keywords state] +[keywords transducer] [copyright {2004-2008 Andreas Kupries }] [moddesc {Finite automaton operations and usage}] [titledesc {Operations on finite automatons}] [category {Grammars and finite automata}] [require Tcl 8.4] @@ -8,13 +17,10 @@ [require snit] [require struct::list] [require struct::set] [require grammar::fa::op [opt 0.4.1]] [description] -[keywords grammar automaton {finite automaton}] -[keywords state {regular expression} {regular grammar}] -[keywords {regular languages} parsing transducer] [para] This package provides a number of complex operations on finite automatons (Short: FA), @@ -67,17 +73,15 @@ Any container class using this package for complex operations should set its own class command as the constructor. See package [package grammar::fa] for an example. - [call [cmd ::grammar::fa::op::reverse] [arg fa]] Reverses the [arg fa]. This is done by reversing the direction of all transitions and swapping the sets of [term start] and [term final] states. The language of [arg fa] changes unpredictably. - [call [cmd ::grammar::fa::op::complete] [arg fa] [opt [arg sink]]] Completes the [arg fa] [term complete], but nothing is done if the [arg fa] is already [term complete]. This implies that only the first @@ -115,12 +119,10 @@ Note that the sink state is [term {not useful}] by definition. In other words, while the FA becomes complete, it is also [term {not useful}] in the strict sense as it has a state from which no final state can be reached. - - [call [cmd ::grammar::fa::op::remove_eps] [arg fa]] Removes all epsilon-transitions from the [arg fa] in such a manner the the language of [arg fa] is unchanged. However nothing is done if the [arg fa] is already [term epsilon-free]. @@ -133,11 +135,10 @@ [emph Note:] This operation may cause states to become unreachable or not useful. These states are not removed by this operation. Use [cmd ::grammar::fa::op::trim] for that instead. - [call [cmd ::grammar::fa::op::trim] [arg fa] [opt [arg what]]] Removes unwanted baggage from [arg fa]. @@ -161,11 +162,10 @@ Removes all states which are not reachable from a start state or are unable to reach a final state. [list_end] [para] - [call [cmd ::grammar::fa::op::determinize] [arg fa] [opt [arg mapvar]]] Makes the [arg fa] deterministic without changing the language accepted by the [arg fa]. However nothing is done if the [arg fa] is @@ -200,12 +200,10 @@ It should also be noted that in this case the possibilities for trimming states from the FA are also severely reduced as we cannot declare states unreachable. - - [call [cmd ::grammar::fa::op::minimize] [arg fa] [opt [arg mapvar]]] Creates a FA which accepts the same language as [arg fa], but has a minimal number of states. Uses Brzozowski's method to accomplish this. @@ -233,18 +231,16 @@ trimming states from the FA are also severely reduced as we cannot declare states unreachable. [list_end] - [emph {Language operations}] All operations in this section require that all input FAs have at least one start and at least one final state. Otherwise the language of the FAs will not be defined, making the operation senseless (as it operates on the languages of the FAs in a defined manner). - [list_begin definitions] [call [cmd ::grammar::fa::op::complement] [arg fa]] @@ -255,11 +251,10 @@ [para] The result will have all states and transitions of the input, and different final states. - [call [cmd ::grammar::fa::op::kleene] [arg fa]] Applies Kleene's closure to [arg fa]. @@ -274,11 +269,10 @@ [para] The result will have all states and transitions of the input, and new start and final states. - [call [cmd ::grammar::fa::op::optional] [arg fa]] Makes the [arg fa] optional. In other words it computes the FA which accepts the language of [arg fa] and the empty the word (epsilon) as well. @@ -285,11 +279,10 @@ [para] The result will have all states and transitions of the input, and new start and final states. - [call [cmd ::grammar::fa::op::union] [arg fa] [arg fb] [opt [arg mapvar]]] Combines the FAs [arg fa] and [arg fb] such that the resulting FA accepts the union of the languages of the two FAs. @@ -304,11 +297,10 @@ [para] It should be noted that the result will be non-deterministic, even if the inputs are deterministic. - [call [cmd ::grammar::fa::op::intersect] [arg fa] [arg fb] [opt [arg mapvar]]] Combines the FAs [arg fa] and [arg fb] such that the resulting FA accepts the intersection of the languages of the two FAs. In other words, the result will accept a word if and only if the word is @@ -322,11 +314,10 @@ the input FAs in [arg mapvar], if it has been specified. Keys of the dictionary are the handles for the states of the resulting fa, values are pairs of states from the input FAs. Pairs are represented by lists. The first element in each pair will be a state in [arg fa], the second element will be drawn from [arg fb]. - [call [cmd ::grammar::fa::op::difference] [arg fa] [arg fb] [opt [arg mapvar]]] Combines the FAs [arg fa] and [arg fb] such that the resulting FA accepts the difference of the languages of the two FAs. In other @@ -343,13 +334,10 @@ dictionary are the handles for the states of the resulting fa, values are pairs of states from the input FAs. Pairs are represented by lists. The first element in each pair will be a state in [arg fa], the second element will be drawn from [arg fb]. - - - [call [cmd ::grammar::fa::op::concatenate] [arg fa] [arg fb] [opt [arg mapvar]]] Combines the FAs [arg fa] and [arg fb] such that the resulting FA accepts the cross-product of the languages of the two FAs. I.e. a word W will be accepted by the result if there are two words A and B @@ -357,12 +345,10 @@ A and B. [para] The result FA will be non-deterministic. - - [call [cmd ::grammar::fa::op::fromRegex] [arg fa] [arg regex] [opt [arg over]]] Generates a non-deterministic FA which accepts the same language as the regular expression [arg regex]. If the [arg over] is specified it @@ -433,13 +419,11 @@ Complement operator. Accepts any word not accepted by the regular expression [var A]. Note that the complement depends on the set of symbol the result should run over. See the discussion of the argument [arg over] before. - [list_end] - [call [cmd ::grammar::fa::op::toRegexp] [arg fa]] This command generates and returns a regular expression which accepts the same language as the finite automaton [arg fa]. The regular @@ -448,11 +432,10 @@ [call [cmd ::grammar::fa::op::toRegexp2] [arg fa]] This command has the same functionality as [cmd ::grammar::fa::op::toRegexp], but uses a different algorithm to simplify the generated regular expressions. - [call [cmd ::grammar::fa::op::toTclRegexp] [arg regexp] [arg symdict]] This command generates and returns a regular expression in Tcl syntax for the regular expression [arg regexp], if that is possible. [arg regexp] is in the @@ -463,17 +446,16 @@ The command will fail and throw an error if [arg regexp] contains complementation and intersection operations. [para] -The argument [arg symdict] is a dictionary mapping symbol names to -pairs of [term {syntactic type}] and Tcl-regexp. If a symbol -occurring in the [arg regexp] is not listed in this dictionary then -single-character symbols are considered to designate themselves -whereas multiple-character symbols are considered to be a character +The argument [arg symdict] is a dictionary mapping symbol names to +pairs of [term {syntactic type}] and Tcl-regexp. If a symbol +occurring in the [arg regexp] is not listed in this dictionary then +single-character symbols are considered to designate themselves +whereas multiple-character symbols are considered to be a character class name. - [call [cmd ::grammar::fa::op::simplifyRegexp] [arg regexp]] This command simplifies a regular expression by applying the following algorithm first to the main expression and then recursively to all @@ -490,20 +472,9 @@ [list_end] [para] [section EXAMPLES] -[para] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_fa] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - + +[vset CATEGORY grammar_fa] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_me/gasm.man ================================================================== --- modules/grammar_me/gasm.man +++ modules/grammar_me/gasm.man @@ -1,15 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::me::cpu::gasm n 0.1] +[keywords assembler] +[keywords grammar] +[keywords graph] +[keywords parsing] +[keywords tree] +[keywords {virtual machine}] [copyright {2005 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {ME assembler}] [category {Grammars and finite automata}] [require grammar::me::cpu::gasm [opt 0.1]] [description] -[keywords {virtual machine}] -[keywords parsing grammar assembler graph tree] This package provides a simple in-memory assembler. Its origin is that of a support package for use by packages converting PEG and other grammars into a corresponding matcher based on the ME virtual machine, like [package page::compiler::peg::mecpu]. Despite that it is actually @@ -148,11 +152,10 @@ [def [const gas::exit::fail]] Written for mode [const okfail]. [list_end] [list_end] - [section API] [list_begin definitions] [call [cmd ::grammar::me::cpu::gasm::begin] [arg g] [arg n] [opt [arg mode]] [opt [arg note]]] @@ -196,11 +199,10 @@ [para] The command returns the empy string as its result. - [call [cmd ::grammar::me::cpu::gasm::done] [const -->] [arg t]] This command finalizes the creation of an instruction sequence and then clears the state of the assembler. [emph NOTE] that this [emph {does not}] delete any of the created @@ -242,16 +244,14 @@ [para] The command returns the empy string as its result. - [call [cmd ::grammar::me::cpu::gasm::state]] This command returns the current state of the assembler. Its format is not documented and considered to be internal to the package. - [call [cmd ::grammar::me::cpu::gasm::state!] [arg s]] This command takes a serialized assembler state [arg s] as returned by [cmd ::grammar::me::cpu::gasm::state] and makes it the current state @@ -265,19 +265,17 @@ [para] The command returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::lift] [arg t] [arg dst] [const =] [arg src]] This command operates on the tree [arg t]. It copies the contents of the attributes [const gas::entry], [const gas::exit::ok] and [const gas::exit::fail] from the node [arg src] to the node [arg dst]. It returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::Inline] [arg t] [arg node] [arg label]] This command links an instruction sequence created by an earlier begin/done pair into the current instruction sequence. @@ -301,11 +299,10 @@ [list_end] The command returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::Cmd] [arg cmd] [opt [arg arg]...]] This is the basic command to add instructions to the graph. It creates a new instruction of type [arg cmd] with the given @@ -319,17 +316,15 @@ [para] The command returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::Bra]] This is a convenience command to create a .BRA pseudo-instruction. It uses [cmd ::grammar::me::cpu::gasm::Cmd] to actually create the instruction and inherits its behaviour. - [call [cmd ::grammar::me::cpu::gasm::Nop] [arg text]] This is a convenience command to create a .NOP pseudo-instruction. It uses [cmd ::grammar::me::cpu::gasm::Cmd] to actually create the @@ -336,20 +331,18 @@ instruction and inherits its behaviour. The [arg text] will be saved as the first and only argument of the new instruction. - [call [cmd ::grammar::me::cpu::gasm::Note] [arg text]] This is a convenience command to create a .C pseudo-instruction, i.e. a comment. It uses [cmd ::grammar::me::cpu::gasm::Cmd] to actually create the instruction and inherits its behaviour. The [arg text] will be saved as the first and only argument of the new instruction. - [call [cmd ::grammar::me::cpu::gasm::Jmp] [arg label]] This command creates an arc from the [term anchor] to the instruction labeled with [arg label], and tags with the the current condition @@ -378,16 +371,14 @@ [para] The command returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::Who] [arg label]] This command returns a reference to the instruction labeled with [arg label]. - [call [cmd ::grammar::me::cpu::gasm::/Label] [arg name]] This command labels the [term anchor] with [arg name]. @@ -395,38 +386,34 @@ [para] The command returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::/Clear]] This command clears the [term anchor], leaving it undefined, and further resets the current condition code to [const always]. [para] The command returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::/Ok]] This command sets the current condition code to [const ok]. [para] The command returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::/Fail]] This command sets the current condition code to [const fail]. [para] The command returns the empty string as its result. - [call [cmd ::grammar::me::cpu::gasm::/At] [arg name]] This command sets the [term anchor] to the instruction labeled with [arg name], and further resets the current condition code to @@ -443,20 +430,10 @@ [para] The command returns the empty string as its result. - [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_me] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY grammar_me] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_me/me_ast.man ================================================================== --- modules/grammar_me/me_ast.man +++ modules/grammar_me/me_ast.man @@ -1,13 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::me_ast n 0.1] +[keywords {abstract syntax tree}] +[keywords AST] [copyright {2005 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {Various representations of ASTs}] [category {Grammars and finite automata}] [description] -[keywords AST {abstract syntax tree}] This document specifies various representations for the [term {abstract syntax tree}]s (short [term AST]) generated by instances of ME virtual machines, independent of variant. @@ -47,11 +48,10 @@ [para] The root of an AS tree can be either a terminal or nonterminal node. - [section {AST VALUES}] This representation of ASTs is a Tcl list. The main list represents the root node of the tree, with the representations of the children nested within. @@ -64,11 +64,10 @@ third elements are then the locations of the first and last tokens. Any additional elements after the third are then the representations of the children, with the leftmost child first, i.e. as the fourth element of the list representing the node. - [section {AST OBJECTS}] In this representation an AST is represented by a Tcl object command whose API is compatible to the tree objects provided by the package @@ -102,11 +101,10 @@ This attribute is present only for nonterminal nodes. It contains the name of the nonterminal symbol stored in the node. [list_end] - [section {EXTENDED AST OBJECTS}] Extended AST objects are like AST objects, with additional information. @@ -129,18 +127,8 @@ locations from attribute [term range] translated into line number and column index. Lines are counted from 1, columns are counted from 0. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_me] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_me] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_me/me_cpu.man ================================================================== --- modules/grammar_me/me_cpu.man +++ modules/grammar_me/me_cpu.man @@ -1,15 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::me::cpu n 0.2] +[keywords grammar] +[keywords parsing] +[keywords {virtual machine}] [copyright {2005-2006 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {Virtual machine implementation II for parsing token streams}] [category {Grammars and finite automata}] [require Tcl 8.4] [require grammar::me::cpu [opt 0.2]] [description] -[keywords {virtual machine} parsing grammar] [para] This package provides an implementation of the ME virtual machine. Please go and read the document [syscmd grammar::me_intro] first if @@ -25,11 +27,10 @@ Internally the package actually uses the value-based machine manipulation commands as provided by the package [package grammar::me::cpu::core] to perform its duties. - [section API] [subsection {CLASS API}] The package directly provides only a single command for the @@ -82,11 +83,10 @@ until they are consumed. In other words, this allows the machine to be suspended and resumed at will and an arbitrary number of times, the quasi-parallel operation of several machines, and the operation as part of the event loop. - [list_begin definitions] [call [arg meName] [method lc] [arg location]] This method converts the location of a token given as offset in the input stream into the associated line number and column index. The @@ -103,11 +103,10 @@ machine has read 7 tokens the command is able to convert the offsets [const 0] to [const 6], but nothing beyond that. This also shows that it is not possible to convert offsets which refer to locations before the beginning of the stream. - [call [arg meName] [method tok] [opt "[arg from] [opt [arg to]]"]] This method returns a Tcl list containing the part of the input stream between the locations [arg from] and [arg to] (both inclusive). If [arg to] is not specified it will default to the value of [arg from]. @@ -120,118 +119,100 @@ order. This command places the same restrictions on its location arguments as the method [method lc]. - [call [arg meName] [method pc] [arg state]] This method takes the state value of a ME virtual machine and returns the current value of the stored program counter. - [call [arg meName] [method iseof] [arg state]] This method takes the state value of a ME virtual machine and returns the current value of the stored eof flag. - [call [arg meName] [method at] [arg state]] This method takes the state value of a ME virtual machine and returns the current location in the input stream. - [call [arg meName] [method cc] [arg state]] This method takes the state value of a ME virtual machine and returns the current token. - [call [arg meName] [method sv]] This command returns the current semantic value [term SV] stored in the machine. This is an abstract syntax tree as specified in the document [syscmd grammar::me_ast], section [sectref-external {AST VALUES}]. - [call [arg meName] [method ok]] This method returns the current match status [term OK]. - [call [arg meName] [method error]] This method returns the current error status [term ER]. - [call [arg meName] [method lstk] [arg state]] This method takes the state value of a ME virtual machine and returns the location stack. - [call [arg meName] [method astk] [arg state]] This method takes the state value of a ME virtual machine and returns the AST stack. - [call [arg meName] [method mstk] [arg state]] This method takes the state value of a ME virtual machine and returns the AST marker stack. - [call [arg meName] [method estk] [arg state]] This method takes the state value of a ME virtual machine and returns the error stack. - [call [arg meName] [method rstk] [arg state]] This method takes the state value of a ME virtual machine and returns the subroutine return stack. - [call [arg meName] [method nc] [arg state]] This method takes the state value of a ME virtual machine and returns the nonterminal match cache as a dictionary. - [call [arg meName] [method ast]] This method returns the current top entry of the AST stack [term AS]. This is an abstract syntax tree as specified in the document [syscmd grammar::me_ast], section [sectref-external {AST VALUES}]. - [call [arg meName] [method halted]] This method returns a boolean value telling the caller whether the engine has halted execution or not. Halt means that no further matching is possible, and the information retrieved via the other method is final. Attempts to [method run] the engine will be ignored, until a [method reset] is made. - [call [arg meName] [method code]] This method returns the [arg code] information used to construct the object. In other words, the match program executed by the machine. - [call [arg meName] [method eof]] This method adds an end of file marker to the end of the input stream. This signals the machine that the current contents of the input queue are the final parts of the input and nothing will come after. Attempts to put more characters into the queue will fail. - [call [arg meName] [method put] [arg tok] [arg lex] [arg line] [arg col]] This method adds the token [arg tok] to the end of the input stream, with associated lexeme data [arg lex] and [arg line]/[arg col]umn @@ -242,11 +223,10 @@ This method adds each individual character in the [arg string] as a token to the end of the input stream, from first to last. The lexemes will be empty and the line/col information is computed based on the characters encountered and the data in the variables [arg lvar] and [arg cvar]. - [call [arg meName] [method run] [opt [arg n]]] This methods causes the engine to execute match instructions until either @@ -260,11 +240,10 @@ [list_end] [para] If no limit [arg n] was set only the last two conditions are checked for. - [call [arg meName] [method pull] [arg nextcmd]] This method implements pull-style operation of the machine. It causes it to execute match instructions until either a halt instruction is @@ -292,31 +271,19 @@ The end of the input stream for this method does not imply that method [method eof] is called for the machine as a whole. By avoiding this and still asking for an explicit call of the method it is possible to mix push- and pull-style operation during the lifetime of the machine. - [call [arg meName] [method reset]] This method resets the machine to its initial state, discarding any state it may have. - [call [arg meName] [method destroy]] This method deletes the object and releases all resurces it claimed. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_me] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_me] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_me/me_cpucore.man ================================================================== --- modules/grammar_me/me_cpucore.man +++ modules/grammar_me/me_cpucore.man @@ -1,15 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::me::cpu::core n 0.2] +[keywords grammar] +[keywords parsing] +[keywords {virtual machine}] [copyright {2005-2006 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {ME virtual machine state manipulation}] [category {Grammars and finite automata}] [require Tcl 8.4] [require grammar::me::cpu::core [opt 0.2]] [description] -[keywords {virtual machine} parsing grammar] [para] This package provides an implementation of the ME virtual machine. Please go and read the document [syscmd grammar::me_intro] first if @@ -35,11 +37,10 @@ [para] The actual structure used by all state values is described in section [sectref {CPU STATE}]. - [section API] The package directly provides only a single command, and all the functionality is made available through its methods. @@ -58,18 +59,16 @@ the empty string. Jump destinations are shown as labels, strings and tokens unencoded. Token names are prefixed with their numeric id, if, and only if a tokmap is defined. The two components are separated by a colon. - [call [cmd ::grammar::me::cpu::core] [method asm] [arg asm]] This method returns code in the format as specified in section [sectref {MATCH PROGRAM REPRESENTATION}] generated from ME assembly code [arg asm], which is in the format as returned by the method [method disasm]. - [call [cmd ::grammar::me::cpu::core] [method new] [arg asm]] This method creates state value for a ME virtual machine in its initial state and returns it as its result. @@ -84,11 +83,10 @@ [para] The [arg tokmap] argument taken by the implementation provided by the package [package grammar::me::tcl] is here hidden inside of the match instructions and therefore not needed. - [call [cmd ::grammar::me::cpu::core] [method lc] [arg state] [arg location]] This method takes the state value of a ME virtual machine and uses it to convert a location in the input stream (as offset) into a line @@ -108,11 +106,10 @@ [para] This utility allows higher levels to convert the location offsets found in the error status and the AST into more human readable data. - [call [cmd ::grammar::me::cpu::core] [method tok] [arg state] [opt "[arg from] [opt [arg to]]"]] This method takes the state value of a ME virtual machine and returns a Tcl list containing the part of the input stream between the locations [arg from] and [arg to] (both inclusive). If [arg to] is not @@ -122,91 +119,77 @@ [para] This method places the same restrictions on its location arguments as the method [method lc]. - [call [cmd ::grammar::me::cpu::core] [method pc] [arg state]] This method takes the state value of a ME virtual machine and returns the current value of the stored program counter. - [call [cmd ::grammar::me::cpu::core] [method iseof] [arg state]] This method takes the state value of a ME virtual machine and returns the current value of the stored eof flag. - [call [cmd ::grammar::me::cpu::core] [method at] [arg state]] This method takes the state value of a ME virtual machine and returns the current location in the input stream. - [call [cmd ::grammar::me::cpu::core] [method cc] [arg state]] This method takes the state value of a ME virtual machine and returns the current token. - [call [cmd ::grammar::me::cpu::core] [method sv] [arg state]] This method takes the state value of a ME virtual machine and returns the current semantic value stored in it. This is an abstract syntax tree as specified in the document [syscmd grammar::me_ast], section [sectref-external {AST VALUES}]. - [call [cmd ::grammar::me::cpu::core] [method ok] [arg state]] This method takes the state value of a ME virtual machine and returns the match status stored in it. - [call [cmd ::grammar::me::cpu::core] [method error] [arg state]] This method takes the state value of a ME virtual machine and returns the current error status stored in it. - [call [cmd ::grammar::me::cpu::core] [method lstk] [arg state]] This method takes the state value of a ME virtual machine and returns the location stack. - [call [cmd ::grammar::me::cpu::core] [method astk] [arg state]] This method takes the state value of a ME virtual machine and returns the AST stack. - [call [cmd ::grammar::me::cpu::core] [method mstk] [arg state]] This method takes the state value of a ME virtual machine and returns the AST marker stack. - [call [cmd ::grammar::me::cpu::core] [method estk] [arg state]] This method takes the state value of a ME virtual machine and returns the error stack. - [call [cmd ::grammar::me::cpu::core] [method rstk] [arg state]] This method takes the state value of a ME virtual machine and returns the subroutine return stack. - [call [cmd ::grammar::me::cpu::core] [method nc] [arg state]] This method takes the state value of a ME virtual machine and returns the nonterminal match cache as a dictionary. - [call [cmd ::grammar::me::cpu::core] [method ast] [arg state]] This method takes the state value of a ME virtual machine and returns the abstract syntax tree currently at the top of the AST stack stored @@ -213,32 +196,28 @@ in it. This is an abstract syntax tree as specified in the document [syscmd grammar::me_ast], section [sectref-external {AST VALUES}]. - [call [cmd ::grammar::me::cpu::core] [method halted] [arg state]] This method takes the state value of a ME virtual machine and returns the current halt status stored in it, i.e. if the machine has stopped or not. - [call [cmd ::grammar::me::cpu::core] [method code] [arg state]] This method takes the state value of a ME virtual machine and returns the code stored in it, i.e. the instructions executed by the machine. - [call [cmd ::grammar::me::cpu::core] [method eof] [arg statevar]] This method takes the state value of a ME virtual machine as stored in the variable named by [arg statevar] and modifies it so that the eof flag inside is set. This signals to the machine that whatever token are in the input queue are the last to be processed. There will be no more. - [call [cmd ::grammar::me::cpu::core] [method put] [arg statevar] [arg tok] [arg lex] [arg line] [arg col]] This method takes the state value of a ME virtual machine as stored in the variable named by [arg statevar] and modifies it so that the token @@ -247,11 +226,10 @@ [para] The operation will fail with an error if the eof flag of the machine has been set through the method [method eof]. - [call [cmd ::grammar::me::cpu::core] [method run] [arg statevar] [opt [arg n]]] This method takes the state value of a ME virtual machine as stored in the variable named by [arg statevar], executes a number of @@ -273,11 +251,10 @@ If no limit [arg n] was set only the last two conditions are checked for. [list_end] - [subsection {MATCH PROGRAM REPRESENTATION}] A match program is represented by nested Tcl list. The first element, [term asm], is a list of integer numbers, the instructions to execute, @@ -339,11 +316,10 @@ [enum] "[cmd ias_mark]" [enum] "[cmd ias_mrewind]" [enum] "[cmd ias_mpop]" [list_end] - [section {CPU STATE}] A state value is a list containing the following elements, in the order listed below: [list_begin enumerated] @@ -391,18 +367,8 @@ [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. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_me] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_me] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_me/me_intro.man ================================================================== --- modules/grammar_me/me_intro.man +++ modules/grammar_me/me_intro.man @@ -1,18 +1,29 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::me_intro n 0.1] +[keywords CFG] +[keywords CFL] +[keywords {context-free grammar}] +[keywords {context-free languages}] +[keywords expression] +[keywords grammar] +[keywords LL(k)] +[keywords matching] +[keywords parsing] +[keywords {parsing expression grammar}] +[keywords PEG] +[keywords {push down automaton}] +[keywords {recursive descent}] +[keywords {top-down parsing languages}] +[keywords TPDL] +[keywords transducer] +[keywords {virtual machine}] [copyright {2005 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {Introduction to virtual machines for parsing token streams}] [category {Grammars and finite automata}] [description] -[keywords {virtual machine}] -[keywords {push down automaton}] -[keywords matching parsing transducer grammar expression] -[keywords {context-free languages} CFL {context-free grammar} CFG] -[keywords {top-down parsing languages} TPDL {parsing expression grammar} PEG] -[keywords {recursive descent} LL(k)] This document is an introduction to and overview of the basic facilities for the parsing and/or matching of [term token] streams. One possibility often used for the token domain are characters. @@ -76,18 +87,8 @@ bytecode based implementation of ME virtual machines. [list_end] [para] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_me] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_me] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_me/me_tcl.man ================================================================== --- modules/grammar_me/me_tcl.man +++ modules/grammar_me/me_tcl.man @@ -1,15 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::me::tcl n 0.1] +[keywords grammar] +[keywords parsing] +[keywords {virtual machine}] [copyright {2005 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {Virtual machine implementation I for parsing token streams}] [category {Grammars and finite automata}] [require Tcl 8.4] [require grammar::me::tcl [opt 0.1]] [description] -[keywords {virtual machine} parsing grammar] [para] This package provides an implementation of the ME virtual machine. Please go and read the document [syscmd grammar::me_intro] first if you do not know what a ME virtual machine is. @@ -34,11 +36,10 @@ A related package is [package grammar::peg::interp] which provides a generic interpreter / parser for parsing expression grammars (PEGs), implemented on top of this implementation of the ME virtual machine. - [section {API}] The commands documented in this section do not implement any of the instructions of the ME virtual machine. They provide the facilities for the initialization of the machine and the retrieval of important @@ -48,11 +49,10 @@ [call [cmd ::grammar::me::tcl] [method cmd] [arg ...]] This is an ensemble command providing access to the commands listed in this section. See the methods themselves for detailed specifications. - [call [cmd ::grammar::me::tcl] [method init] [arg nextcmd] [opt [arg tokmap]]] This command (re)initializes the machine. It returns the empty string. This command has to be invoked before any other command of @@ -80,12 +80,10 @@ is subsequently used by [term ict_match_tokrange] to determine if a token is in the specified range or not. If no token map is specified the lexicographic order of th token names will be used instead. This choice is especially asensible when using characters as tokens. - - [call [cmd ::grammar::me::tcl] [method lc] [arg location]] This command converts the location of a token given as offset in the input stream into the associated line number and column index. The result of the command is a 2-element list containing the two values, @@ -107,11 +105,10 @@ After a call of [method init] the state used for the conversion is cleared, making further conversions impossible until the machine has read tokens again. - [call [cmd ::grammar::me::tcl] [method tok] [arg from] [opt [arg to]]] This command returns a Tcl list containing the part of the input stream between the locations [arg from] and [arg to] (both inclusive). If [arg to] is not specified it will default to the value @@ -129,31 +126,27 @@ [para] This command places the same restrictions on its location arguments as [cmd ::grammar::me::tcl::lc]. - [call [cmd ::grammar::me::tcl] [method tokens]] This command returns the number of tokens currently known to the ME virtual machine. - [call [cmd ::grammar::me::tcl] [method sv]] This command returns the current semantic value [term SV] stored in the machine. This is an abstract syntax tree as specified in the document [syscmd grammar::me_ast], section [sectref-external {AST VALUES}]. - [call [cmd ::grammar::me::tcl] [method ast]] This method returns the abstract syntax tree currently at the top of the AST stack of the ME virtual machine. This is an abstract syntax tree as specified in the document [syscmd grammar::me_ast], section [sectref-external {AST VALUES}]. - [call [cmd ::grammar::me::tcl] [method astall]] This method returns the whole stack of abstract syntax trees currently known to the ME virtual machine. Each element of the returned list is @@ -160,35 +153,30 @@ an abstract syntax tree as specified in the document [syscmd grammar::me_ast], section [sectref-external {AST VALUES}]. The top of the stack resides at the end of the list. - [call [cmd ::grammar::me::tcl] [method ctok]] This method returns the current token considered by the ME virtual machine. - [call [cmd ::grammar::me::tcl] [method nc]] This method returns the contents of the nonterminal cache as a dictionary mapping from "[var symbol],[var location]" to match information. - [call [cmd ::grammar::me::tcl] [method next]] This method returns the next token callback as specified during initialization of the ME virtual machine. - [call [cmd ::grammar::me::tcl] [method ord]] This method returns a dictionary containing the [arg tokmap] specified during initialization of the ME virtual machine. - [var [cmd ::grammar::me::tcl::ok]] This variable contains the current match status [term OK]. It is provided as variable instead of a command because that makes access to @@ -196,11 +184,10 @@ important here as this information is used constantly to determine the control flow. [list_end] [para] - [section {MACHINE STATE}] Please go and read the document [syscmd grammar::me_vm] first for a specification of the basic ME virtual machine and its state. @@ -210,11 +197,10 @@ This implementation manages the state described in that document, except for the stacks minus the AST stack. In other words, location stack, error stack, return stack, and ast marker stack are implicitly managed through standard Tcl scoping, i.e. Tcl variables in procedures, outside of this implementation. - [section {MACHINE INSTRUCTIONS}] Please go and read the document [syscmd grammar::me_vm] first for a specification of the basic ME virtual machine and its instruction set. @@ -350,18 +336,8 @@ Tcl stack, not the machine state. It replaces [term ias_mpop]. [list_end] [para] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_me] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_me] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_me/me_util.man ================================================================== --- modules/grammar_me/me_util.man +++ modules/grammar_me/me_util.man @@ -1,21 +1,22 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::me::util n 0.1] +[keywords {abstract syntax tree}] +[keywords {syntax tree}] +[keywords tree] [copyright {2005 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {AST utilities}] [category {Grammars and finite automata}] [require Tcl 8.4] [require grammar::me::util [opt 0.1]] [description] -[keywords {abstract syntax tree} {syntax tree} tree] [para] This package provides a number of utility command for the conversion between the various representations of abstract syntax trees as specified in the document [syscmd grammar::me_ast]. - [list_begin definitions] [call [cmd ::grammar::me::util::ast2tree] [arg ast] [arg tree] [opt [arg root]]] @@ -24,11 +25,10 @@ nodes of this [arg tree], with the root of the AST a child of the node [arg root]. If this node is not explicitly specified the root of the tree is used. Existing content of tree is not touched, i.e. neither removed nor changed, with the exception of the specified root node, which will gain a new child. - [call [cmd ::grammar::me::util::ast2etree] [arg ast] [arg mcmd] [arg tree] [opt [arg root]]] This command is like [cmd ::grammar::me::util::ast2tree], except that the result is in the extended object representation of the input AST. @@ -65,30 +65,19 @@ Both the ensemble command [cmd ::grammar::me::tcl] provided by the package [package grammar::me::tcl] and the objects command created by the package [package ::grammar::me::cpu] fit the above specification. - [call [cmd ::grammar::me::util::tree2ast] [arg tree] [opt [arg root]]] This command converts an [arg ast] in (extended) object representation into a value and returns it. If a [arg root] node is specified the AST is generated from that node downward. Otherwise the root of the tree object is used as the -starting point. +starting point. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_me] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_me] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_me/me_vm.man ================================================================== --- modules/grammar_me/me_vm.man +++ modules/grammar_me/me_vm.man @@ -1,14 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::me_vm n 0.1] +[keywords grammar] +[keywords parsing] +[keywords {virtual machine}] [copyright {2005 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {Virtual machine for parsing token streams}] [category {Grammars and finite automata}] [description] -[keywords {virtual machine}] -[keywords parsing grammar] Please go and read the document [syscmd grammar::me_intro] first for an overview of the various documents and their relations. [para] @@ -31,11 +32,10 @@ [para] The following sections will discuss first the abstract state kept by ME virtual machines, and then their instruction set. - [section {MACHINE STATE}] A ME virtual machine manages the following state: [list_begin definitions] @@ -47,11 +47,10 @@ This information is used and modified by the instructions defined in the section [sectref {TERMINAL MATCHING}]. - [def "[term {Current location}] CL"] The location of the [term {current token}] in the input stream, as offset relative to the beginning of the stream. The first token is @@ -68,11 +67,10 @@ and can be directly queried and modified by the instructions defined in section [sectref {INPUT LOCATION HANDLING}]. - [def "[term {Location stack}] LS"] In addition to the above a stack of locations, for backtracking. Locations can put on the stack, removed from it, and removed with setting the current location. @@ -87,11 +85,10 @@ and can be directly queried and modified by the instructions defined in section [sectref {INPUT LOCATION HANDLING}]. - [def "[term {Match status}] OK"] A boolean value, the result of the last attempt at matching input. It is set to [const true] if that attempt was successful, and @@ -108,11 +105,10 @@ It is queried by the instructions defined in the section [sectref {CONTROL FLOW}]. - [def "[term {Semantic value}] SV"] The semantic value associated with (generated by) the last attempt at matching input. Contains either the empty string or a node for the abstract syntax tree constructed from the input. @@ -123,11 +119,10 @@ sections [sectref {SEMANTIC VALUES}], and [sectref {AST STACK HANDLING}]. - [def "[term {AST stack}] AS"] A stack of partial abstract syntax trees constructed by the machine during matching. @@ -136,11 +131,10 @@ This information is influenced by the instructions defined in the sections [sectref {SEMANTIC VALUES}], and [sectref {AST STACK HANDLING}]. - [def "[term {AST Marker stack}] MS"] In addition to the above a stack of stacks, for backtracking. This is actually a stack of markers into the AST stack, thus implicitly @@ -153,11 +147,10 @@ This information is influenced by the instructions defined in the sections [sectref {SEMANTIC VALUES}], and [sectref {AST STACK HANDLING}]. - [def "[term {Error status}] ER"] Error information associated with the last attempt at matching input. Contains either the empty string or a list of 2 elements, a @@ -180,11 +173,10 @@ [sectref {TERMINAL MATCHING}], [sectref {NONTERMINAL MATCHING}], and [sectref {ERROR HANDLING}]. - [def "[term {Error stack}] ES"] In addition to the above a stack of error information, to allow the merging of current and older error information when performing backtracking in choices after an unsucessful match. @@ -196,11 +188,10 @@ [sectref {TERMINAL MATCHING}], [sectref {NONTERMINAL MATCHING}], and [sectref {ERROR HANDLING}]. - [def "[term {Return stack}] RS"] A stack of program counter values, i.e. locations in the code controlling the virtual machine, for the management of subroutine calls, i.e. the matching of nonterminal symbols. @@ -209,11 +200,10 @@ This information is queried and influenced by the instructions defined in the section [sectref {NONTERMINAL MATCHING}]. - [def "[term {Nonterminal cache}] NC"] A cache of machine states (A 4-tuple containing a location in the input, match status [term OK], semantic value [term SV], and error @@ -234,17 +224,15 @@ [sectref {NONTERMINAL MATCHING}]. [list_end] - [section {MACHINE INSTRUCTIONS}] With the machine state specified it is now possible to explain the instruction set of ME virtual machines. They are grouped roughly by the machine state they influence and/or query. - [subsection {TERMINAL MATCHING}] First the instructions to match tokens from the input stream, and by extension all terminal symbols. @@ -282,11 +270,10 @@ [para] The argument [arg message] is a reference to the string to put into the error status [term ER], if such is needed. - [def "[cmd ict_match_token] [arg tok] [arg message]"] This instruction tests the current token [term CT] for equality with the argument [arg tok] and records the result in the match status [term OK]. The instruction fails if the current token is @@ -299,11 +286,10 @@ current location [term CL] is moved one token backwards. Otherwise, i.e. upon success, the error status [term ER] is cleared and the current location [term CL] is not touched. - [def "[cmd ict_match_tokrange] [arg tokbegin] [arg tokend] [arg message]"] This instruction tests the current token [term CT] for being in the range of tokens from [arg tokbegin] to [arg tokend] (inclusive) and records the result in the match status [term OK]. The @@ -315,11 +301,10 @@ location [term CL] and the message [arg message], and the current location [term CL] is moved one token backwards. Otherwise, i.e. upon success, the error status [term ER] is cleared and the current location [term CL] is not touched. - [def "[cmd ict_match_tokclass] [arg code] [arg message]"] This instruction tests the current token [term CT] for being a member of the token class [arg code] and records the result in the match @@ -354,11 +339,10 @@ A token is accepted if it is a unicode space character. [list_end] [list_end] [para] - [subsection {NONTERMINAL MATCHING}] The instructions in this section handle the matching of nonterminal symbols. They query the nonterminal cache [term NC] for saved @@ -394,11 +378,10 @@ Together with [cmd icf_ntcall] it is possible to generate code for memoized and non-memoized matching of nonterminal symbols, either as subroutine calls, or inlined in the caller. - [def "[cmd inc_save] [arg nt]"] This instruction saves the current state of the machine (current location [term CL], match status [term OK], semantic value [term SV], and error status [term ER]), to the nonterminal cache [term NC]. It @@ -411,11 +394,10 @@ symbol, with [arg nt] the name of the nonterminal symbol the code was working on. This allows the instruction [cmd inc_restore] to check for and retrieve the data, should we have to match this nonterminal symbol at the same location again, during backtracking. - [def "[cmd icf_ntcall] [arg branchlabel]"] This instruction invokes the code for matching the nonterminal symbol [arg nt] as a subroutine. To this end it stores the current program counter [term PC] on the return stack [term RS], the current location @@ -425,20 +407,18 @@ [para] The next matching [cmd icf_ntreturn] will cause the execution to continue at the instruction coming after the call. - [def [cmd icf_ntreturn]] This instruction will pop an entry from the return stack [term RS], assign it to the program counter [term PC], and then continue execution at the new address. [list_end] [para] - [subsection {UNCONDITIONAL MATCHING}] The instructions in this section are the remaining match operators. They change the match status [term OK] directly and @@ -449,25 +429,22 @@ [def [cmd iok_ok]] This instruction sets the match status [term OK] to [const true], indicating a successful match. - [def [cmd iok_fail]] This instruction sets the match status [term OK] to [const false], indicating a failed match. - [def [cmd iok_negate]] This instruction negates the match status [term OK], turning a failure into a success and vice versa. [list_end] [para] - [subsection {CONTROL FLOW}] The instructions in this section implement both conditional and unconditional control flow. The conditional jumps query the match @@ -479,33 +456,29 @@ This instruction sets the program counter [term PC] to the address specified by [arg branchlabel] and then continues execution from there. This is an unconditional jump. - [def "[cmd icf_jok] [arg branchlabel]"] This instruction sets the program counter [term PC] to the address specified by [arg branchlabel]. This happens if, and only if the match status [term OK] indicates a success. Otherwise it simply continues execution at the next instruction. This is a conditional jump. - [def "[cmd icf_jfail] [arg branchlabel]"] This instruction sets the program counter [term PC] to the address specified by [arg branchlabel]. This happens if, and only if the match status [term OK] indicates a failure. Otherwise it simply continues execution at the next instruction. This is a conditional jump. - [def [cmd icf_halt]] This instruction halts the machine and blocks any further execution. [list_end] - [subsection {INPUT LOCATION HANDLING}] The instructions in this section are for backtracking, they manipulate the current location [term CL] of the machine state. @@ -520,26 +493,23 @@ [def [cmd icl_push]] This instruction pushes a copy of the current location [term CL] on the location stack [term LS]. - [def [cmd icl_rewind]] This instruction pops an entry from the location stack [term LS] and then moves the current location [term CL] back to this point in the input. - [def [cmd icl_pop]] This instruction pops an entry from the location stack [term LS] and discards it. [list_end] [para] - [subsection {ERROR HANDLING}] The instructions in this section provide read and write access to the error status [term ER] of the machine. @@ -549,15 +519,13 @@ [def [cmd ier_push]] This instruction pushes a copy of the current error status [term ER] on the error stack [term ES]. - [def [cmd ier_clear]] This instruction clears the error status [term ER]. - [def "[cmd ier_nonterminal] [arg message]"] This instruction checks if the error status [term ER] contains an error whose location is just past the location found in the top entry @@ -565,11 +533,10 @@ Nothing happens if no such error is found. Otherwise the found error is replaced by an error at the location found on the stack, having the message [arg message]. - [def [cmd ier_merge]] This instruction pops an entry from the error stack [term ES], merges it with the current error status [term ER] and stores the result of @@ -587,11 +554,10 @@ chosen. If both error states refer to the same location their messages are merged (with removing duplicates). [list_end] - [subsection {SEMANTIC VALUES}] The instructions in this section manipulate the semantic value [term SV]. @@ -599,17 +565,15 @@ [def [cmd isv_clear]] This instruction clears the semantic value [term SV]. - [def [cmd isv_terminal]] This instruction creates a terminal AST node for the current token [term CT], makes it the semantic value [term SV], and also pushes the node on the AST stack [term AS]. - [def "[cmd isv_nonterminal_leaf] [arg nt]"] This instruction creates a nonterminal AST node without any children for the nonterminal [arg nt], and makes it the semantic value @@ -619,11 +583,10 @@ This instruction should be executed if, and only if the match status [term OK] indicates a success. In the case of a failure [cmd isv_clear] should be called. - [def "[cmd isv_nonterminal_range] [arg nt]"] This instruction creates a nonterminal AST node for the nonterminal @@ -636,11 +599,10 @@ This instruction should be executed if, and only if the match status [term OK] indicates a success. In the case of a failure [cmd isv_clear] should be called. - [def "[cmd isv_nonterminal_reduce] [arg nt]"] This instruction creates a nonterminal AST node for the nonterminal [arg nt] and makes it the semantic value [term SV]. @@ -661,11 +623,10 @@ In the case of a failure [cmd isv_clear] should be called. [list_end] [para] - [subsection {AST STACK HANDLING}] The instructions in this section manipulate the AST stack [term AS], and the AST Marker stack [term MS]. @@ -674,16 +635,14 @@ [def [cmd ias_push]] This instruction pushes the semantic value [term SV] on the AST stack [term AS]. - [def [cmd ias_mark]] This instruction pushes a marker for the current state of the AST stack [term AS] on the AST Marker stack [term MS]. - [def [cmd ias_mrewind]] This instruction pops an entry from the AST Marker stack [term MS] and then proceeds to pop entries from the AST stack [term AS] until the @@ -690,26 +649,15 @@ state represented by the popped marker has been reached again. Nothing is done if the AST stack [term AS] is already smaller than indicated by the popped marker. - [def [cmd ias_mpop]] This instruction pops an entry from the AST Marker stack [term MS] and discards it. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_me] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_me] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_peg/peg.man ================================================================== --- modules/grammar_peg/peg.man +++ modules/grammar_peg/peg.man @@ -1,19 +1,28 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::peg n 0.1] +[keywords {context-free languages}] +[keywords expression] +[keywords grammar] +[keywords LL(k)] +[keywords parsing] +[keywords {parsing expression}] +[keywords {parsing expression grammar}] +[keywords {push down automaton}] +[keywords {recursive descent}] +[keywords state] +[keywords TDPL] +[keywords {top-down parsing languages}] +[keywords transducer] [copyright {2005 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {Create and manipulate parsing expression grammars}] [category {Grammars and finite automata}] [require Tcl 8.4] [require snit] [require grammar::peg [opt 0.1]] [description] -[keywords grammar expression {push down automaton}] -[keywords state {parsing expression} {parsing expression grammar}] -[keywords {context-free languages} parsing transducer LL(k)] -[keywords TDPL {top-down parsing languages} {recursive descent}] [para] This package provides a container class for [term {parsing expression grammars}] (Short: PEG). @@ -21,17 +30,15 @@ and querying of the definition. The package neither provides complex operations on the grammar, nor has it the ability to execute a grammar definition for a stream of symbols. - Two packages related to this one are [package grammar::mengine] and [package grammar::peg::interpreter]. The first of them defines a general virtual machine for the matching of a character stream, and the second implements an interpreter for parsing expression grammars on top of that virtual machine. - [subsection {TERMS & CONCEPTS}] PEGs are similar to context-free grammars, but not equivalent; in some cases PEGs are strictly more powerful than context-free grammars (there @@ -170,11 +177,10 @@ taken, see the last item. [list_end] [para] - [subsection {CONTAINER CLASS API}] The package exports the API described here. [list_begin definitions] @@ -206,31 +212,27 @@ is the empty expression, i.e. epsilon. It is [term valid], but not [term useful]. [list_end] - [subsection {CONTAINER OBJECT API}] [para] All grammar container objects provide the following methods for the manipulation of their contents: [list_begin definitions] - [call [arg pegName] [method destroy]] Destroys the grammar, including its storage space and associated command. - [call [arg pegName] [method clear]] Clears out the definition of the grammar contained in [arg pegName], but does [emph not] destroy the object. - [call [arg pegName] [method =] [arg srcPEG]] Assigns the contents of the grammar contained in [arg srcPEG] to [arg pegName], overwriting any existing definition. @@ -246,11 +248,10 @@ [para] [example_begin] [arg pegName] [method deserialize] [lb][arg srcPEG] [method serialize][rb] [example_end] - [call [arg pegName] [method -->] [arg dstPEG]] This is the reverse assignment operator for grammars. It copies the automation contained in the object [arg pegName] over the grammar definition in the object [arg dstPEG]. @@ -262,11 +263,10 @@ This operation is in effect equivalent to [para] [example_begin] [arg dstPEG] [method deserialize] [lb][arg pegName] [method serialize][rb] [example_end] - [call [arg pegName] [method serialize]] This method serializes the grammar stored in [arg pegName]. In other words it returns a tcl [emph value] completely describing that @@ -349,28 +349,25 @@ [para] A possible one, because the order of the nonterminals in the dictionary is not relevant. - [call [arg pegName] [method deserialize] [arg serialization]] This is the complement to [method serialize]. It replaces the grammar definition in [arg pegName] with the grammar described by the [arg serialization] value. The old contents of [arg pegName] are deleted by this operation. - [call [arg pegName] [method {is valid}]] A predicate. It tests whether the PEG in [arg pegName] is [term valid]. See section [sectref {TERMS & CONCEPTS}] for the definition of this grammar property. The result is a boolean value. It will be set to [const true] if the PEG has the tested property, and [const false] otherwise. - [call [arg pegName] [method start] [opt [arg pe]]] This method defines the [term {start expression}] of the grammar. It replaces the previously defined start expression with the parsing @@ -386,15 +383,13 @@ [para] If the method is called without an argument it will return the currently defined start expression. - [call [arg pegName] [method nonterminals]] Returns the set of all nonterminal symbols known to the grammar. - [call [arg pegName] [method {nonterminal add}] [arg nt] [arg pe]] This method adds the nonterminal [arg nt] and its associated parsing expression [arg pe] to the set of nonterminal symbols and rules of the @@ -405,11 +400,10 @@ contain a valid parsing expression as specified in the section [sectref {PARSING EXPRESSIONS}]. In that case the current set of nonterminal symbols and rules is not changed. The method returns the empty string as its result. - [call [arg pegName] [method {nonterminal delete}] [arg nt1] [opt "[arg nt2] ..."]] This method removes the named symbols [arg nt1], [arg nt2] from the set of nonterminal symbols of the PEG contained in the object @@ -424,29 +418,26 @@ [para] The stored grammar becomes invalid if the deleted nonterminals are referenced by the RHS of still-known rules. - [call [arg pegName] [method {nonterminal exists}] [arg nt]] A predicate. It tests whether the nonterminal symbol [arg nt] is known to the PEG in [arg pegName]. The result is a boolean value. It will be set to [const true] if the symbol [arg nt] is known, and [const false] otherwise. - [call [arg pegName] [method {nonterminal rename}] [arg nt] [arg ntnew]] This method renames the nonterminal symbol [arg nt] to [arg ntnew]. The method fails and throws an error if either [arg nt] is not known as a nonterminal, or if [arg ntnew] is a known symbol. The method returns the empty string as its result. - [call [arg pegName] [method {nonterminal mode}] [arg nt] [opt [arg mode]]] This mode returns or sets the semantic mode associated with the nonterminal symbol [arg nt]. If no [arg mode] is specified the @@ -484,28 +475,25 @@ The nonterminal has no semantic value. The ASTs generated by the RHS are discarded (as well). [list_end] - [call [arg pegName] [method {nonterminal rule}] [arg nt]] This method returns the parsing expression associated with the nonterminal [arg nt]. The method fails and throws an error if [arg nt] is not known as a nonterminal. - [call [arg pegName] [method {unknown nonterminals}]] This method returns a list containing the names of all nonterminal symbols which are referenced on the RHS of a grammatical rule, but have no rule definining their structure. In other words, a list of the nonterminal symbols which make the grammar invalid. The grammar is valid if this list is empty. - [list_end] [para] @@ -599,11 +587,10 @@ is a parsing expression as well. This is the [term {not lookahead predicate}]. - [enum] For a parsing expression [var e] the result of [lb]list ? [var e][rb] @@ -614,11 +601,10 @@ [list_end] [para] Examples of parsing expressions where already shown, in the description of the method [method serialize]. - [section {PARSING EXPRESSION GRAMMARS}] [para] For the mathematically inclined, a PEG is a 4-tuple (VN,VT,R,eS) where @@ -706,11 +692,10 @@ They can be easily implemented by recursive descent parsers with backtracking. This makes them relatives of LL(k) Context-Free Grammars. - [section REFERENCES] [list_begin enumerated] [enum] [uri {http://www.pdos.lcs.mit.edu/~baford/packrat/} \ @@ -729,18 +714,8 @@ [uri {http://scifac.ru.ac.za/compilers/} \ {Compilers and Compiler Generators}], an online book using CoCo/R, a generator for recursive descent parsers. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_peg] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY grammar_peg] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/grammar_peg/peg_interp.man ================================================================== --- modules/grammar_peg/peg_interp.man +++ modules/grammar_peg/peg_interp.man @@ -1,20 +1,30 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin grammar::peg::interp n 0.1.1] +[keywords {context-free languages}] +[keywords expression] +[keywords grammar] +[keywords LL(k)] +[keywords matching] +[keywords parsing] +[keywords {parsing expression}] +[keywords {parsing expression grammar}] +[keywords {push down automaton}] +[keywords {recursive descent}] +[keywords state] +[keywords TDPL] +[keywords {top-down parsing languages}] +[keywords transducer] +[keywords {virtual machine}] [copyright {2005-2011 Andreas Kupries }] [moddesc {Grammar operations and usage}] [titledesc {Interpreter for parsing expression grammars}] [category {Grammars and finite automata}] [require Tcl 8.4] [require grammar::mengine [opt 0.1]] [require grammar::peg::interp [opt 0.1.1]] [description] -[keywords grammar expression {push down automaton}] -[keywords state {parsing expression} {parsing expression grammar}] -[keywords {context-free languages} parsing transducer LL(k)] -[keywords TDPL {top-down parsing languages} {recursive descent}] -[keywords {virtual machine} matching] [para] This package provides commands for the controlled matching of a character stream via a parsing expression grammar and the creation of an abstract syntax tree for the stream and partials. @@ -48,11 +58,10 @@ characters from the input stream as it needs them. For usage in a push environment, i.e. where the environment pushes new characters as they come we have to put the engine into its own thread. - [section {THE INTERPRETER API}] The package exports the following API [list_begin definitions] @@ -66,11 +75,10 @@ [para] Its argument [arg peg] is the handle of an object containing the parsing expression grammar to interpret. This grammar has to be valid, or an error will be thrown. - [call [cmd ::grammar::peg::interp::parse] [arg nextcmd] [arg errorvar] [arg astvar]] This command interprets the loaded grammar and tries to match it against the stream of characters represented by the command prefix @@ -107,19 +115,8 @@ document [term grammar::me_ast]. [list_end] [para] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph grammar_peg] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - - +[vset CATEGORY grammar_peg] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/hook/hook.man ================================================================== --- modules/hook/hook.man +++ modules/hook/hook.man @@ -1,19 +1,25 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin hook n 0.1] +[see_also uevent(n)] +[keywords callback] +[keywords event] +[keywords hook] +[keywords observer] +[keywords producer] +[keywords publisher] +[keywords subject] +[keywords subscriber] +[keywords uevent] [copyright {2010, by William H. Duquette}] [moddesc {Hooks}] [titledesc {Hooks}] [category {Programming tools}] [require Tcl 8.5] [require hook [opt 0.1]] -[keywords hook event subject observer producer callback] -[keywords publisher subscriber uevent] -[see_also uevent(n)] [description] [para] - This package provides the [cmd hook] ensemble command, which implements the Subject/Observer pattern. It allows [term subjects], which may be [term modules], [term objects], [term widgets], and so forth, to synchronously call [term hooks] which may be bound to an @@ -47,11 +53,10 @@ At present, Tcl/Tk has no standard mechanism for implementing loose coupling of this kind. This package defines a new command, [cmd hook], which implements just such a mechanism. - [subsection Bindings] The [cmd hook] command manages a collection of hook bindings. A hook binding has four elements: @@ -70,15 +75,14 @@ [enum] The name of the [term observer] that wishes to receive the [term hook] from the [term subject]. [enum] -A command prefix to which the [term hook] arguments will be appended -when the binding is executed. +A command prefix to which the [term hook] arguments will be appended +when the binding is executed. [list_end] - [subsection {Subjects and observers}] For convenience, this document collectively refers to subjects and observers as [term objects], while placing no requirements on how @@ -107,11 +111,10 @@ [para] Because object names are arbitrary strings, application code can use whatever additional conventions are dictated by the needs of the application. - [section Reference] Hook provides the following commands: @@ -167,11 +170,11 @@ hook call $s $h }] [list_begin enumerated] [enum] -No binding is ever called after it is deleted. +No binding is ever called after it is deleted. [enum] When a binding is called, the most recently given command prefix is always used. @@ -180,11 +183,11 @@ when this method begins to execute, and does not change thereafter, except that deleted bindings are not called. [list_end] -In particular: +In particular: [list_begin enumerated] [enum] If [var \$o]s binding to [var \$s] and [var \$h] is deleted, and @@ -217,11 +220,10 @@ hook call $s $h }] [list_end] - [call [cmd hook] [method call] [arg subject] [arg hook] [opt [arg args]...]] This command is called when the named [arg subject] wishes to call the named [arg hook]. All relevant bindings are called with the specified arguments in the global namespace. Note that the bindings are called @@ -241,14 +243,14 @@ the observers, nor any expectation regarding return values. This has a number of implications: [list_begin enumerated] [enum] -[cmd {hook call}] returns the empty string. +[cmd {hook call}] returns the empty string. [enum] -Normal return values from observer bindings are ignored. +Normal return values from observer bindings are ignored. [enum] Errors and other exceptional returns propagate normally by default. This will rarely be what is wanted, because the subjects usually have no knowledge of the observers and will therefore have no @@ -260,11 +262,10 @@ If the [option -errorcommand] configuration option has a non-empty value, its value will be invoked for all errors and other exceptional returns in observer bindings. See [cmd {hook configure}], below, for more information on configuration options. - [call [cmd hook] [method forget] [arg object]] This command deletes any existing bindings in which the named [arg object] appears as either the [term subject] or the @@ -287,11 +288,10 @@ then [cmd {hook call}] will return as soon as the current binding returns. No further bindings will be called. [list_end] - [call [cmd hook] [method cget] [arg option]] This command returns the value of one of the [cmd hook] command's configuration options. @@ -301,27 +301,27 @@ configuration options: [list_begin options] [opt_def -errorcommand [arg cmdPrefix]] -If the value of this option is the empty string, "", then errors -and other exception returns in binding scripts are propagated -normally. Otherwise, it must be a command prefix taking three +If the value of this option is the empty string, "", then errors +and other exception returns in binding scripts are propagated +normally. Otherwise, it must be a command prefix taking three additional arguments: [list_begin enumerated] -[enum] a 4-element list {subject hook arglist observer}, +[enum] a 4-element list {subject hook arglist observer}, [enum] the result string, and [enum] the return options dictionary. [list_end] Given this information, the [option -errorcommand] can choose to log the error, call [cmd {interp bgerror}], delete the errant binding (thus preventing the error from arising a second time) and so forth. [opt_def -tracecommand [arg cmdPrefix]] -The option's value should be a command prefix taking four +The option's value should be a command prefix taking four arguments: [list_begin enumerated] [enum] a [term subject], [enum] a [term hook], @@ -362,15 +362,14 @@ [example { hook forget .view }] -All bindings involving [widget .view] are deleted. - +All bindings involving [widget .view] are deleted. [section Credits] Hook has been designed and implemented by William H. Duquette. [vset CATEGORY hook] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/html/html.man ================================================================== --- modules/html/html.man +++ modules/html/html.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin html n 1.4] +[see_also htmlparse] +[see_also ncgi] +[keywords checkbox] +[keywords checkbutton] +[keywords form] +[keywords html] +[keywords radiobutton] +[keywords table] [moddesc {HTML Generation}] [titledesc {Procedures to generate HTML structures}] [category {CGI programming}] [require Tcl 8.2] [require html [opt 1.4]] @@ -24,54 +32,47 @@ [emph {Side effect only}]. Call this before [cmd ::html::head] to define an author for the page. The author is noted in a comment in the HEAD section. - [call [cmd ::html::bodyTag] [arg args]] Generate a [term body] tag. The tag parameters are taken from [arg args] or from the body.* attributes define with [cmd ::html::init]. - [call [cmd ::html::cell] [arg {param value}] [opt [arg tag]]] Generate a [term td] (or [term th]) tag, a value, and a closing [term td] (or [term th]) tag. The tag parameters come from [arg param] or TD.* attributes defined with [cmd ::html::init]. This uses [cmd ::html::font] to insert a standard [term font] tag into the table cell. The [arg tag] argument defaults to "td". - [call [cmd ::html::checkbox] [arg {name value}]] Generate a [term checkbox] form element with the specified name and value. This uses [cmd ::html::checkValue]. - [call [cmd ::html::checkSet] [arg {key sep list}]] Generate a set of [term checkbox] form elements and associated labels. The [arg list] should contain an alternating list of labels and values. This uses [cmd ::html::checkbox]. All the [term checkbox] buttons share the same [arg key] for their name. The [arg sep] is text used to separate the elements. - [call [cmd ::html::checkValue] [arg name] [opt [arg value]]] Generate the "name=[arg name] value=[arg value] for a [term checkbox] form element. If the CGI variable [arg name] has the value [arg value], then SELECTED is added to the return value. [arg value] defaults to "1". - [call [cmd ::html::closeTag]] Pop a tag off the stack created by [cmd ::html::openTag] and generate the corresponding close tag (e.g., ). - [call [cmd ::html::default] [arg key] [opt [arg param]]] This procedure is used by [cmd ::html::tagParam] to generate the name, value list of parameters for a tag. The [cmd ::html::default] @@ -81,30 +82,26 @@ Otherwise, it returns a "parameter=value" string for a form element identified by [arg key]. The [arg key] has the form "tag.parameter" (e.g., body.bgcolor). Use [cmd ::html::init] to register default values. [arg param] defaults to the empty string. - [call [cmd ::html::description] [arg description]] [emph {Side effect only}]. Call this before [cmd ::html::head] to define a description [term meta] tag for the page. This tag is generated later in the call to [cmd ::html::head]. - [call [cmd ::html::end]] Pop all open tags from the stack and generate the corresponding close HTML tags, (e.g., ). - [call [cmd ::html::eval] [arg arg] [opt [arg args]]] This procedure is similar to the built-in Tcl [cmd eval] command. The only difference is that it returns "" so it can be called from an HTML template file without appending unwanted results. - [call [cmd ::html::extractParam] [arg {param key}] [opt [arg varName]]] This is a parsing procedure that extracts the value of [arg key] from [arg param], which is a HTML-style "name=quotedvalue" list. @@ -113,32 +110,28 @@ have the value found in the parameters. The function returns 1 if the parameter was found in [arg param], otherwise it returns 0. If the [arg varName] is not specified, then [arg key] is used as the variable name. - [call [cmd ::html::font] [arg args]] Generate a standard [term font] tag. The parameters to the tag are taken from [arg args] and the HTML defaults defined with [cmd ::html::init]. - [call [cmd ::html::for] [arg {start test next body}]] This procedure is similar to the built-in Tcl [cmd for] control structure. Rather than evaluating the body, it returns the subst'ed [arg body]. Each iteration of the loop causes another string to be concatenated to the result value. - [call [cmd ::html::foreach] [arg {varlist1 list1}] [opt [arg {varlist2 list2 ...}]] [arg body]] This procedure is similar to the built-in Tcl [cmd foreach] control structure. Rather than evaluating the body, it returns the subst'ed [arg body]. Each iteration of the loop causes another string to be concatenated to the result value. - [call [cmd ::html::formValue] [arg name] [opt [arg defvalue]]] Return a name and value pair, where the value is initialized from existing CGI data, if any. The result has this form: @@ -146,23 +139,20 @@ [para] [example { name="fred" value="freds value" }] - [call [cmd ::html::getFormInfo] [arg args]] Generate hidden fields to capture form values. If [arg args] is empty, then hidden fields are generated for all CGI values. Otherwise args is a list of string match patterns for form element names. - [call [cmd ::html::getTitle]] Return the title string, with out the surrounding [term title] tag, set with a previous call to [cmd ::html::title]. - [call [cmd ::html::h] [arg {level string}] [opt [arg param]]] Generate a heading (e.g., [term h[var level]]) tag. The [arg string] is nested in the heading, and [arg param] is used for the tag parameters. @@ -189,114 +179,100 @@ [call [cmd ::html::h6] [arg string] [opt [arg param]]] Generate an [term h6] tag. See [cmd ::html::h]. - [call [cmd ::html::hdrRow] [arg args]] Generate a table row, including [term tr] and [term th] tags. Each value in [arg args] is place into its own table cell. This uses [cmd ::html::cell]. - [call [cmd ::html::head] [arg title]] Generate the [term head] section that includes the page [term title]. If previous calls have been made to -[cmd ::html::author], -[cmd ::html::keywords], -[cmd ::html::description], +[cmd ::html::author], +[cmd ::html::keywords], +[cmd ::html::description], or [cmd ::html::meta] then additional tags are inserted into the [term head] section. This leaves an open [term html] tag pushed on the stack with [cmd ::html::openTag]. - [call [cmd ::html::headTag] [arg string]] Save a tag for inclusion in the [term head] section generated by [cmd ::html::head]. The [arg string] is everything in the tag except the enclosing angle brackets, < >. - [call [cmd ::html::html_entities] [arg string]] This command replaces all special characters in the [arg string] with their HTML entities and returns the modified text. - [call [cmd ::html::if] [arg {expr1 body1}] [opt "[const elseif] [arg {expr2 body2 ...}]"] [opt "[const else] [arg bodyN]"]] This procedure is similar to the built-in Tcl [cmd if] control structure. Rather than evaluating the body of the branch that is taken, it returns the subst'ed [arg body]. Note that the syntax is slightly more restrictive than that of the built-in Tcl [cmd if] control structure. - [call [cmd ::html::init] [opt [arg list]]] [cmd ::html::init] accepts a Tcl-style name-value list that defines values for items with a name of the form "tag.parameter". For example, a default with key "body.bgcolor" defines the background color for the [term body] tag. - [call [cmd ::html::keywords] [arg args]] [emph {Side effect only}]. Call this before [cmd ::html::head] to define a keyword [term meta] tag for the page. The [term meta] tag is included in the result of [cmd ::html::head]. - [call [cmd ::html::mailto] [arg email] [opt [arg subject]]] Generate a hypertext link to a mailto: URL. - [call [cmd ::html::meta] [arg args]] [emph {Side effect only}]. Call this before [cmd ::html::head] to define a [term meta] tag for the page. The [arg args] is a Tcl-style name, value list that is used for the name= and value= parameters for the [term meta] tag. The [term meta] tag is included in the result of [cmd ::html::head]. - [call [cmd ::html::minorList] [arg list] [opt [arg ordered]]] Generate an ordered or unordered list of links. The [arg list] is a Tcl-style name, value list of labels and urls for the links. [arg ordered] is a boolean used to choose between an ordered or unordered list. It defaults to [const false]. - [call [cmd ::html::minorMenu] [arg list] [opt [arg sep]]] Generate a series of hypertext links. The [arg list] is a Tcl-style name, value list of labels and urls for the links. The [arg sep] is the text to put between each link. It defaults to " | ". - [call [cmd ::html::nl2br] [arg string]] This command replaces all line-endings in the [arg string] with a [term br] tag and returns the modified text. - [call [cmd ::html::openTag] [arg tag] [opt [arg param]]] Push [arg tag] onto a stack and generate the opening tag for [arg tag]. Use [cmd ::html::closeTag] to pop the tag from the stack. The second argument provides any tag arguments, as a list whose elements are formatted to be in the form "[var key]=[const value]". - [call [cmd ::html::paramRow] [arg list] [opt [arg rparam]] [opt [arg cparam]]] Generate a table row, including [term tr] and [term td] tags. Each value in @@ -304,66 +280,57 @@ [cmd ::html::cell]. The value of [arg rparam] is used as parameter for the [term tr] tag. The value of [arg cparam] is passed to [cmd ::html::cell] as parameter for the [term td] tags. - [call [cmd ::html::passwordInput] [opt [arg name]]] Generate an [term input] tag of type [term password]. The [arg name] defaults to "password". - [call [cmd ::html::passwordInputRow] [arg label] [opt [arg name]]] Format a table row containing a label and an [term input] tag of type [term password]. The [arg name] defaults to "password". - [call [cmd ::html::quoteFormValue] [arg value]] Quote special characters in [arg value] by replacing them with HTML entities for quotes, ampersand, and angle brackets. - [call [cmd ::html::radioSet] [arg {key sep list}]] Generate a set of [term input] tags of type [term radio] and an associated text label. All the radio buttons share the same [arg key] for their name. The [arg sep] is text used to separate the elements. The [arg list] is a Tcl-style label, value list. - [call [cmd ::html::radioValue] [arg {name value}]] Generate the "name=[arg name] value=[arg value] for a [term radio] form element. If the CGI variable [arg name] has the value [arg value], then SELECTED is added to the return value. - [call [cmd ::html::refresh] [arg {seconds url}]] Set up a refresh [term meta] tag. Call this before [cmd ::html::head] and the HEAD section will contain a [term meta] tag that causes the document to refresh in [arg seconds] seconds. The [arg url] is optional. If specified, it specifies a new page to load after the refresh interval. - [call [cmd ::html::row] [arg args]] Generate a table row, including [term tr] and [term td] tags. Each value in [arg args] is place into its own table cell. This uses [cmd ::html::cell]. Ignores any default information set up via [cmd ::html::init]. - [call [cmd ::html::select] [arg {name param choices}] [opt [arg current]]] Generate a [term select] form element and nested [term option] tags. The [arg name] and [arg param] are used to generate the [term select] tag. The [arg choices] list is a Tcl-style name, value list. - [call [cmd ::html::selectPlain] [arg {name param choices}] [opt [arg current]]] Like [cmd ::html::select] except that [arg choices] is a Tcl list of values used for the [term option] tags. The label and the value for each @@ -374,15 +341,13 @@ This procedure is similar to the built-in Tcl [cmd set] command. The main difference is that it returns "" so it can be called from an HTML template file without appending unwanted results. The other difference is that it must take two arguments. - [call [cmd ::html::submit] [arg label] [opt [arg name]]] Generate an [term input] tag of type [term submit]. [arg name] defaults to "submit". - [call [cmd ::html::tableFromArray] [arg arrname] [opt [arg param]] [opt [arg pat]]] Generate a two-column [term table] and nested rows to display a Tcl array. The table gets a heading that matches the array name, and each generated row @@ -402,18 +367,16 @@ [call [cmd ::html::textarea] [arg name] [opt [arg param]] [opt [arg current]]] Generate a [term textarea] tag wrapped around its current values. - [call [cmd ::html::textInput] [arg {name value args}]] Generate an [term input] form tag with type [term text]. This uses [cmd ::html::formValue]. The args is any additional tag attributes you want to put into the [term input] tag. - [call [cmd ::html::textInputRow] [arg {label name value args}]] Generate an [term input] form tag with type [term text] formatted into a table row with an associated label. The args is any additional tag attributes @@ -429,30 +392,17 @@ [call [cmd ::html::varEmpty] [arg name]] This returns 1 if the named variable either does not exist or has the empty string for its value. - [call [cmd ::html::while] [arg {test body}]] This procedure is similar to the built-in Tcl [cmd while] control structure. Rather than evaluating the body, it returns the subst'ed [arg body]. Each iteration of the loop causes another string to be concatenated to the result value. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph html] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also ncgi htmlparse] -[keywords html form table checkbox radiobutton checkbutton] +[vset CATEGORY html] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/htmlparse/htmlparse.man ================================================================== --- modules/htmlparse/htmlparse.man +++ modules/htmlparse/htmlparse.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin htmlparse n 1.2.1] +[see_also struct::tree] +[keywords html] +[keywords parsing] +[keywords queue] +[keywords tree] [moddesc {HTML Parser}] [titledesc {Procedures to parse HTML strings}] [category {Text processing}] [require Tcl 8.2] [require struct::stack 1.3] @@ -16,11 +21,10 @@ [para] The following commands are available: [list_begin definitions] - [call [cmd ::htmlparse::parse] [opt "-cmd [arg cmd]"] [opt "-vroot [arg tag]"] [opt "-split [arg n]"] [opt "-incvar [arg var]"] [opt "-queue [arg q]"] [arg html]] This command is the basic parser for HTML. It takes an HTML string, parses it and invokes a command prefix for every tag encountered. It @@ -254,20 +258,8 @@ [cmd ::htmlparse::2tree]. It removes all nodes representing forms and form elements. Its only argument is the name of the tree to cut down. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph htmlparse] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also struct::tree] -[keywords html parsing tree queue] +[vset CATEGORY htmlparse] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/http/autoproxy.man ================================================================== --- modules/http/autoproxy.man +++ modules/http/autoproxy.man @@ -1,6 +1,10 @@ [manpage_begin autoproxy n 1.5.3] +[see_also http(n)] +[keywords authentication] +[keywords http] +[keywords proxy] [moddesc {HTTP protocol helper modules}] [titledesc {Automatic HTTP proxy usage and authentication}] [category Networking] [require Tcl 8.2] [require http [opt 2.0]] @@ -18,11 +22,11 @@ On Unix the standard for identifying the local HTTP proxy server seems to be to use the environment variable http_proxy or ftp_proxy and no_proxy to list those domains to be excluded from proxying. On Windows we can retrieve the Internet Settings values from the registry to obtain pretty much the same information. -With this information we can setup a suitable filter procedure for the +With this information we can setup a suitable filter procedure for the Tcl http package and arrange for automatic use of the proxy. [para] There seem to be a number of ways that the http_proxy environment @@ -49,11 +53,11 @@ Retrieve individual package configuration options. See [sectref OPTIONS]. [call [cmd ::autoproxy::configure] [opt "-option [arg value]"]] Configure the autoproxy package. Calling [cmd configure] with no -options will return a list of all option names and values. +options will return a list of all option names and values. See [sectref OPTIONS]. [call [cmd ::autoproxy::tls_connect] [arg args]] Connect to a secure socket through a proxy. HTTP proxy servers permit @@ -100,11 +104,11 @@ [opt_def -proxy_port number] Set the proxy port number. This is normally set up by [cmd init]. e.g. [cmd configure] [option -port] [arg 3128] [opt_def -no_proxy list] -You may manipulate the [option no_proxy] list that was setup by +You may manipulate the [option no_proxy] list that was setup by [cmd init]. The value of this option is a tcl list of strings that are matched against the http request host using the tcl [cmd "string match"] command. Therefore glob patterns are permitted. For instance, [cmd configure] [option -no_proxy] [arg "*.localdomain"] @@ -183,23 +187,11 @@ [section {BUGS}] At this time only Basic authentication (1) (2) is supported. It is planned to add support for Digest (2) and NTLM in the future. -[see_also http(n)] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {http :: autoproxy}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords http proxy authentication] +[vset CATEGORY {http :: autoproxy}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ident/ident.man ================================================================== --- modules/ident/ident.man +++ modules/ident/ident.man @@ -1,7 +1,10 @@ [comment {-*- Tcl -*- doctools manpage}] [manpage_begin ident n 0.42] +[keywords ident] +[keywords identification] +[keywords {rfc 1413}] [copyright {2004 Reinhard Max }] [titledesc {Ident protocol client}] [moddesc {Identification protocol client}] [category Networking] [require Tcl 8.3] @@ -10,11 +13,10 @@ The [package ident] package provides a client implementation of the ident protocol as defined in RFC 1413 ([uri http://www.rfc-editor.org/rfc/rfc1413.txt]). - [list_begin definitions] [call [cmd ::ident::query] [arg socket] [opt [arg callback]]] This command queries the ident daemon on the remote side of the given @@ -45,19 +47,8 @@ [const error] key. [list_end] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ident] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {rfc 1413} ident identification] +[vset CATEGORY ident] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/imap4/imap4.man ================================================================== --- modules/imap4/imap4.man +++ modules/imap4/imap4.man @@ -1,6 +1,20 @@ [manpage_begin imap4 n 0.5.1] +[see_also ftp] +[see_also http] +[see_also imap] +[see_also mime] +[see_also pop3] +[see_also tls] +[keywords email] +[keywords imap] +[keywords internet] +[keywords mail] +[keywords net] +[keywords rfc3501] +[keywords ssl] +[keywords tls] [moddesc {imap client}] [titledesc {imap client-side tcl implementation of imap protocol}] [require Tcl 8.5] [require imap4 [opt 0.5.1]] @@ -20,21 +34,21 @@ [list_begin definitions] [call [cmd ::imap4::open] [arg hostname] [opt [arg port]]] [para]Open a new IMAP connection and initalize the handler, the imap communication channel (handler) is returned. -[para][arg hostname] - mail server -[para][arg port] - connection port, defaults to 143 +[para][arg hostname] - mail server +[para][arg port] - connection port, defaults to 143 [para]The namespace variable [option ::imap4::use_ssl] can be used to establish to a secure connection via TSL/SSL if set to true. In this case default connection port defaults to 993. [para][emph Note:] For connecting via SSL the Tcl module [emph tls] must be already loaded otherwise an error is raised. [example { - package require tls ; # must be loaded for TLS/SSL + package require tls ; # must be loaded for TLS/SSL set ::imap4::use_ssl 1 ; # request a secure connection set chan [::imap4::open $server] ; # default port is now 993 }] [call [cmd ::imap4::login] [arg chan] [arg user] [arg pass]] [para]Login using the IMAP LOGIN command, 0 is returned on successful login. @@ -136,12 +150,12 @@ false if it is not. [para][arg chan] - imap channel [para][arg opt] - mailbox option to retrieve [para] Currently supported options: -[emph EXISTS] (noof msgs), -[emph RECENT] (noof 'recent' flagged msgs), +[emph EXISTS] (noof msgs), +[emph RECENT] (noof 'recent' flagged msgs), [emph FLAGS] [para]In conjunction with OK: [emph PERMFLAGS], [emph UIDNEXT], [emph UIDVAL], [emph UNSEEN] [para]Div. states: [emph CURRENT], [emph FOUND], [emph PERM]. @@ -181,16 +195,16 @@ [call [cmd ::imap4::subscribe] [arg chan] [arg mailbox]] [para]Subscribe a new mailbox. [para][arg chan] - imap channel [para][arg mailbox] - mailbox name - + [call [cmd ::imap4::unsubscribe] [arg chan] [arg mailbox]] [para]Unsubscribe a new mailbox. [para][arg chan] - imap channel [para][arg mailbox] - mailbox name - + [call [cmd ::imap4::search] [arg chan] [arg expr] [opt [arg "..."]] ] [para]Search for mails matching search criterions, 0 is returned on success. [para][arg chan] - imap channel [para][arg expr] - imap search expression @@ -202,17 +216,17 @@ [para][emph "Imap message search flags:"] ANSWERED, DELETED, DRAFT, FLAGGED, RECENT, SEEN, NEW, OLD, UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, UNSEEN, ALL [para][emph "Imap header search flags:"] -BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC +BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC [para][emph "Imap conditional search flags:"] SMALLER, LARGER, ON, SENTBEFORE, SENTON, SENTSINCE, SINCE, BEFORE (not implemented), UID (not implemented) [para][emph "Logical search conditions:"] -OR, NOT +OR, NOT [example {::imap4::search $chan larger 4000 seen puts "Found messages: [::imap4::mboxinfo $chan found]" Found messages: 1 3 6 7 8 9 13 14 15 19 20}] [call [cmd ::imap4::close] [arg chan]] @@ -281,11 +295,10 @@ [para][arg chan] - imap channel [para][arg msgid] - message number [para][arg mailbox] - mailbox name - [call [cmd ::imap4::logout] [arg chan]] [para] Informs the server that the client is done with the connection and closes the network connection. Permanently removes \Deleted messages. @@ -300,36 +313,36 @@ [section EXAMPLES] [example_begin] set user myusername set pass xtremescrt - set server imap.test.tld + set server imap.test.tld set FOLDER INBOX # Connect to server set imap [lb]::imap4::open $server[rb] ::imap4::login $imap $user $pass ::imap4::select $imap $FOLDER # Output all the information about that mailbox foreach info [lb]::imap4::mboxinfo $imap[rb] { puts "$info -> [lb]::imap4::mboxinfo $imap $info[rb]" } - # fetch 3 records inline + # fetch 3 records inline set fields {from: to: subject: size} foreach rec [lb]::imap4::fetch $imap :3 -inline {*}$fields[rb] { puts -nonewline "#[lb]incr idx[rb])" for {set j 0} {$j<[lb]llength $fields[rb]} {incr j} { puts "\t[lb]lindex $fields $j[rb] [lb]lindex $rec $j[rb]" } } - + # Show all the information available about the message ID 1 puts "Available info about message 1: [lb]::imap4::msginfo $imap 1[rb]" - + # Use the capability stuff puts "Capabilities: [lb]::imap4::isableto $imap[rb]" puts "Is able to imap4rev1? [lb]::imap4::isableto $imap imap4rev1[rb]" - + # Cleanup ::imap4::cleanup $imap [example_end] [section REFERENCES] @@ -337,21 +350,10 @@ RFC 3501, March 2003, [uri http://www.rfc-editor.org/rfc/rfc3501.txt] [para] OpenSSL, [uri http://www.openssl.org/] -[section {BUGS, IDEAS, FEEDBACK}] -This document, and the package it describes, will undoubtedly contain -bugs and other problems. +[vset CATEGORY imap4] +[include ../doctools2base/include/feedback.inc] Only a small part of rfc3501 implemented. - -[para] -Please report such in the category [emph imap4] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also imap ftp http mime pop3 tls] -[keywords imap email internet mail net imap rfc3501 ssl tls] [manpage_end] Index: modules/inifile/ini.man ================================================================== --- modules/inifile/ini.man +++ modules/inifile/ini.man @@ -89,18 +89,8 @@ comments. When comments are written out each line is preceded by this character. The default is [const \;]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph inifile] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY inifile] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/interp/deleg_method.man ================================================================== --- modules/interp/deleg_method.man +++ modules/interp/deleg_method.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin deleg_method n 0.2] +[keywords comm] +[keywords delegation] +[keywords interpreter] +[keywords method] +[keywords snit] [copyright {2006 Andreas Kupries }] [moddesc {Interpreter utilities}] [titledesc {Creation of comm delegates (snit methods)}] [category {Programming tools}] [require Tcl 8.3] @@ -37,19 +42,8 @@ however the option [option -async] was specified then the generated method will not wait for a result and return immediately. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph interp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords interpreter delegation comm method snit] +[vset CATEGORY interp] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/interp/deleg_proc.man ================================================================== --- modules/interp/deleg_proc.man +++ modules/interp/deleg_proc.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin deleg_proc n 0.2] +[keywords comm] +[keywords delegation] +[keywords interpreter] +[keywords procedure] [copyright {2006 Andreas Kupries }] [moddesc {Interpreter utilities}] [titledesc {Creation of comm delegates (procedures)}] [category {Programming tools}] [require Tcl 8.3] @@ -36,19 +40,8 @@ however the option [option -async] was specified then the generated procedure will not wait for a result and return immediately. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph interp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords interpreter delegation comm procedure] +[vset CATEGORY interp] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/interp/tcllib_interp.man ================================================================== --- modules/interp/tcllib_interp.man +++ modules/interp/tcllib_interp.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin interp n 0.1.2] +[keywords alias] +[keywords {empty interpreter}] +[keywords interpreter] +[keywords method] +[keywords snit] [copyright {2006 Andreas Kupries }] [moddesc {Interpreter utilities}] [titledesc {Interp creation and aliasing}] [category {Programming tools}] [require Tcl 8.3] @@ -9,11 +14,10 @@ [description] [para] This package provides a number of commands for the convenient creation of Tcl interpreters for highly restricted execution. - [section API] [list_begin definitions] [call [cmd ::interp::createEmpty] [opt [arg path]]] @@ -24,11 +28,10 @@ [para] If a [arg path] is specified then it is taken as the name of the new interpreter. - [call [cmd ::interp::snitLink] [arg path] [arg methodlist]] This command assumes that it was called from within a method of a snit object, and that the command [cmd mymethod] is available. @@ -46,11 +49,10 @@ [para] The result of the command is the empty string. - [call [cmd ::interp::snitDictLink] [arg path] [arg methoddict]] This command behaves like [cmd ::interp::snitLink], except that it takes a dictionary mapping from commands to methods as its input, and not a list of methods. @@ -65,20 +67,8 @@ The result of the command is the empty string. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph interp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords interpreter {empty interpreter}] -[keywords snit method alias] +[vset CATEGORY interp] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/irc/irc.man ================================================================== --- modules/irc/irc.man +++ modules/irc/irc.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin irc n 0.6.1] +[see_also {rfc 1459}] +[keywords chat] +[keywords irc] [moddesc {Low Level Tcl IRC Interface}] [titledesc {Create IRC connection and interface.}] [category Networking] [require Tcl] [require irc [opt 0.6.1]] @@ -13,30 +16,27 @@ [para] [list_begin definitions] - [call [cmd ::irc::config] [opt key] [opt value]] Sets configuration [opt key] to [opt value]. The configuration keys currently defined are the boolean flags [const logger] and [const debug]. [const logger] makes [package irc] use the logger package for printing error. [const debug] requires [const logger] and prints extra debug output. If no [opt key] or [opt value] is given the current values are returned. - [call [cmd ::irc::connection]] The command creates a new object to deal with an IRC connection. Creating this IRC object does not automatically create the network connection. It returns a new irc namespace command which can be used to interact with the new IRC connection. NOTE: the old form of the connection command, which took a hostname and port as arguments, is deprecated. Use [cmd connect] instead to specify this information. - [call [cmd ::irc::connections]] Returns a list of all the current connections that were created with [const connection] @@ -68,21 +68,18 @@ [arg script] is executed in the connection namespace, which can take advantage of several commands (see [sectref {Callback Commands}] below) to aid in the parsing of data. - [call [arg net] [method getevent] [arg event] [arg script]] Returns the current handler for the event if one exists. Otherwise an empty string is returned. - [call [arg net] [method eventexists] [arg event] [arg script]] Returns a boolean value indicating the existence of the event handler. - [call [arg net] [method connect] [arg hostname] [opt port]] This causes the socket to be established. [cmd ::irc::connection] created the namespace and the commands to be used, but did not @@ -106,22 +103,19 @@ [call [arg net] [method connected]] Returns a boolean value indicating if this connection is connected to a server. - [call [arg net] [method sockname]] Returns a 3 element list consisting of the ip address, the hostname, and the port of the local end of the connection, if currently connected. - [call [arg net] [method peername]] Returns a 3 element list consisting of the ip address, the hostname, and the port of the remote end of the connection, if currently connected. - [call [arg net] [method socket]] Return the Tcl channel for the socket used by the connection. @@ -130,32 +124,27 @@ Sends USER command to server. [arg username] is the username you want to appear. [arg localhostname] is the host portion of your hostname, [arg localdomainname] is your domain name, and [arg userinfo] is a short description of who you are. The 2nd and 3rd arguments are normally ignored by the IRC server. - [call [arg net] [method nick] [arg nick]] NICK command. [arg nick] is the nickname you wish to use for the particular connection. - [call [arg net] [method ping] [arg target]] Send a CTCP PING to [arg target]. - [call [arg net] [method serverping]] PING the server. - [call [arg net] [method join] [arg channel] [opt [arg key]]] [arg channel] is the IRC channel to join. IRC channels typically begin with a hashmark ("#") or ampersand ("&"). - [call [arg net] [method part] [arg channel] [opt [arg message]]] Makes the client leave [arg channel]. Some networks may support the optional argument [arg message] @@ -163,55 +152,46 @@ [call [arg net] [method quit] [opt [arg message]]] Instructs the IRC server to close the current connection. The package will use a generic default if no [arg message] was specified. - [call [arg net] [method privmsg] [arg target] [arg message]] Sends [arg message] to [arg target], which can be either a channel, or another user, in which case their nick is used. - [call [arg net] [method notice] [arg target] [arg message]] Sends a [const notice] with message [arg message] to [arg target], which can be either a channel, or another user, in which case their nick is used. - [call [arg net] [method ctcp] [arg target] [arg message]] Sends a CTCP of type [arg message] to [arg target] - [call [arg net] [method kick] [arg channel] [arg target] [opt [arg message]]] Kicks the user [arg target] from the channel [arg channel] with a [arg message]. The latter can be left out. - [call [arg net] [method mode] [arg target] [arg args]] Sets the mode [arg args] on the target [arg target]. [arg target] may be a channel, a channel user, or yourself. - [call [arg net] [method topic] [arg channel] [arg message]] Sets the topic on [arg channel] to [arg message] specifying an empty string will remove the topic. - [call [arg net] [method invite] [arg channel] [arg target]] Invites [arg target] to join the channel [arg channel] - [call [arg net] [method send] [arg text]] Sends [arg text] to the IRC server. - [call [arg net] [method destroy]] Deletes the connection and its associated namespace and information. @@ -236,11 +216,11 @@ Normally not useful, as callbacks are bound to a particular event. [call [cmd target]] Returns the target of a particular command, such as the channel or -user to whom a PRIVMSG is sent. +user to whom a PRIVMSG is sent. [call [cmd additional]] Returns a list of any additional arguments after the target. @@ -252,20 +232,8 @@ Returns the message portion of the command (the part after the :). [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph irc] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also {rfc 1459}] -[keywords irc chat] +[vset CATEGORY irc] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/irc/picoirc.man ================================================================== --- modules/irc/picoirc.man +++ modules/irc/picoirc.man @@ -1,15 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin picoirc n 0.5] +[see_also {rfc 1459}] +[keywords chat] +[keywords irc] [moddesc {Simple embeddable IRC interface}] [titledesc {Small and simple embeddable IRC client.}] [category Networking] [require Tcl] [require picoirc [opt 0.5]] [description] -This package provides a general purpose minimal IRC client suitable for +This package provides a general purpose minimal IRC client suitable for embedding in other applications. All communication with the parent application is done via an application provided callback procedure. Each connection has its own state so you can hook up multiple servers in a single application instance. @@ -70,11 +73,11 @@ [example { proc Callback {context state args} { } }] -where context is the irc context variable name (in case you need to pass +where context is the irc context variable name (in case you need to pass it back to a picoirc procedure). state is one of a number of states as described below. [list_begin options] @@ -102,11 +105,11 @@ [opt_def chat "[arg target] [arg nick] [arg message] [arg type]"] called when a message arrives. [arg target] is the identity that the message was targetted for. This can be the logged in nick or a channel -name. [arg nick] is the name of the sender of the message. +name. [arg nick] is the name of the sender of the message. [arg message] is the message text. [arg type] is set to "ACTION" if the message was sent as a CTCP ACTION [opt_def system "[arg channel] [arg message]"] @@ -146,16 +149,13 @@ socket. [arg type] is set to [const read] when reading data and [const write] if the data is to be written. [arg raw] is the unprocessed IRC protocol data. [para] In both cases the application can return a break error code to -interrupt further processing of the raw data. If this is a +interrupt further processing of the raw data. If this is a [const read] operation then the package will not handle this line. If the operation is [const write] then the package will not send the data. This callback is intended for debugging protocol issues but could be used to redirect all input and output if desired. [list_end] - -[see_also {rfc 1459}] -[keywords irc chat] [manpage_end] Index: modules/javascript/javascript.man ================================================================== --- modules/javascript/javascript.man +++ modules/javascript/javascript.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin javascript n 1.0.2] +[see_also html] +[see_also ncgi] +[keywords checkbox] +[keywords html] +[keywords javascript] +[keywords selectionbox] +[keywords submitbutton] [moddesc {HTML and Java Script Generation}] [titledesc {Procedures to generate HTML and Java Script structures.}] [category {CGI programming}] [require Tcl 8] [require javascript [opt 1.0.2]] @@ -38,28 +45,25 @@ selection box. The [arg length] argument (optional) determines the number of elts to show before adding a vertical scrollbar; it defaults to 8. The [arg minWidth] argument (optional) is the number of spaces to determine the minimum box width; it defaults to 32. - [call [cmd ::javascript::makeSubmitButton] [arg {name value}]] Create an HTML submit button that resets a hidden field for each registered multi-selection box. The [arg name] argument is the name of the HTML button object to create. The [arg value] argument is the label of the HTML button object to create. - [call [cmd ::javascript::makeProtectedSubmitButton] [arg {name value msg}]] Create an HTML submit button that prompts the user with a continue/cancel shutdown warning before the form is submitted. The [arg name] argument is the name of the HTML button object to create. The [arg value] argument is the label of the HTML button object to create. The [arg msg] argument is the message to display when the button is pressed. - [call [cmd ::javascript::makeMasterButton] [arg {master value slavePattern boolean}]] Create an HTML button that sets its slave checkboxs to the boolean value. The [arg master] argument is the name of the child's parent @@ -67,19 +71,17 @@ master. The [arg slaves] argument is the name of child html checkbox object to create. The [arg boolean] argument is the java script boolean value that will be given to all the slaves; it must be "true" or "false". - [call [cmd ::javascript::makeParentCheckbox] [arg {parentName childName}]] Create an HTML checkbox and tie its value to that of its child checkbox. If the parent is unchecked, the child is automatically unchecked. The [arg parentName] argument is the name of parent html checkbox object to create. The [arg childName] argument is the name of the parent's child html checkbox object. - [call [cmd ::javascript::makeChildCheckbox] [arg {parentName childName}]] Create an HTML checkbox and tie its value to that of its parent checkbox. If the child is checked, the parent is automatically @@ -87,20 +89,8 @@ parent html checkbox object. The [arg childName] argument is the name of child html checkbox object to create. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph javascript] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also html ncgi] -[keywords javascript html checkbox submitbutton selectionbox] +[vset CATEGORY javascript] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/jpeg/jpeg.man ================================================================== --- modules/jpeg/jpeg.man +++ modules/jpeg/jpeg.man @@ -1,6 +1,12 @@ [manpage_begin jpeg n 0.4.0] +[keywords comment] +[keywords exif] +[keywords image] +[keywords jfif] +[keywords jpeg] +[keywords thumbnail] [copyright {2004-2005, Code: Aaron Faupell }] [copyright {2007, Code: Andreas Kupries }] [copyright {2004-2009, Doc: Andreas Kupries }] [copyright {2011, Code: Pat Thoyts }] [moddesc {JPEG image manipulation}] @@ -31,18 +37,16 @@ [const ythumb]. The values are the associated properties of the JPEG image in [arg file]. Throws an error if [arg file] is not a JPEG image. - [call [cmd ::jpeg::dimensions] [arg file]] Returns the dimensions of the JPEG [arg file] as a list of the horizontal and vertical pixel count. Throws an error if [arg file] is not a JPEG image. - [call [cmd ::jpeg::getThumbnail] [arg file]] This procedure will return the binary thumbnail image data, if a JPEG thumbnail is included in [arg file], and the empty string @@ -81,11 +85,11 @@ [call [cmd ::jpeg::getExifFromChannel] [arg channel] [opt [arg section]]] This command is as per [cmd ::jpeg::getExif] except that it uses a previously opened channel. [arg channel] should be a seekable channel -and [arg section] is as described in the documentation of +and [arg section] is as described in the documentation of [cmd ::jpeg::getExif] Note: the jpeg parser expects that the start of the channel is the start of the image data. If working with an image embedded in a container file format it may be necessary to read the jpeg data into @@ -127,33 +131,29 @@ the image. This includes comments, EXIF segments, JFXX segments, and application specific segments. Throws an error if [arg file] is not a JPEG image. - [call [cmd ::jpeg::getComments] [arg file]] Returns a list containing all the JPEG comments found in the [arg file]. Throws an error if [arg file] is not a valid JPEG image. - [call [cmd ::jpeg::addComment] [arg file] [arg text]...] Adds one or more plain [arg text] comments to the JPEG image in [arg file]. Throws an error if [arg file] is not a valid JPEG image. - [call [cmd ::jpeg::removeComments] [arg file]] Removes all comments from the file specified. Throws an error if [arg file] is not a valid JPEG image. - [call [cmd ::jpeg::replaceComment] [arg file] [arg text]] Replaces the first comment in the file with the new [arg text]. This is merely a shortcut for [cmd ::jpeg::removeComments] @@ -184,19 +184,8 @@ can only work with files cant write exif data gps exif data not parsed makernote data not yet implemented -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph jpeg] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords jpeg image comment exif thumbnail jfif] +[vset CATEGORY jpeg] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/json/json.man ================================================================== --- modules/json/json.man +++ modules/json/json.man @@ -1,15 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin json n 1.1.2] +[keywords {data exchange}] +[keywords {exchange format}] +[keywords javascript] +[keywords json] [copyright {2006 ActiveState Software Inc.}] [copyright {2009 Thomas Maeder, Glue Software Engineering AG}] [moddesc {JSON}] [titledesc {JSON parser}] [category {CGI programming}] [require Tcl 8.4] [require json [opt 1.1.2]] -[keywords json javascript {data exchange} {exchange format}] [description] [para] The [package json] package provides a simple Tcl-only library for parsing the JSON [uri http://www.json.org/] data exchange format as specified in RFC 4627 Index: modules/json/json_write.man ================================================================== --- modules/json/json_write.man +++ modules/json/json_write.man @@ -1,14 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin json::write n 1.0.2] +[keywords {data exchange}] +[keywords {exchange format}] +[keywords javascript] +[keywords json] [copyright {2009-2013 Andreas Kupries }] [moddesc {JSON}] [titledesc {JSON generation}] [category {CGI programming}] [require Tcl 8.5] [require json::write [opt 1.0.2]] -[keywords json javascript {data exchange} {exchange format}] [description] [para] The [package json::write] package provides a simple Tcl-only library for generation of text in the JSON [uri http://www.json.org/] data @@ -20,11 +23,10 @@ [list_begin definitions] [call [cmd ::json::write] [method indented]] This method returns the current state of the indentation setting. - [call [cmd ::json::write] [method indented] [arg flag]] This and the method [method aligned] configure the layout of the JSON generated by the package. @@ -38,18 +40,15 @@ [para] If this flag is not set, the whole JSON object will be written on a single line, with minimum spacing between all elements. - [call [cmd ::json::write] [method aligned]] This method returns the current state of the alignment setting. - [call [cmd ::json::write] [method aligned] [arg flag]] - This and the method [method indented] configure the layout of the JSON generated by the package. [para] @@ -62,31 +61,27 @@ [para] If this flag is not set, the output is formatted as per the value of [var indented], without trying to align the values for object keys. - [call [cmd ::json::write] [method string] [arg s]] This method takes the string [arg s] and returns it properly quoted for JSON as its result. - [call [cmd ::json::write] [method array] [arg arg]...] This method takes a series of JSON formatted arguments and returns them as a properly formatted JSON array as its result. - [call [cmd ::json::write] [method object] [arg key] [arg value]...] This method takes a series of key/value arguments, the values already formatted for JSON, and returns them as a properly formatted JSON object as its result, with the keys formatted as JSON strings. - [list_end] [para] [vset CATEGORY json] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/lambda/lambda.man ================================================================== --- modules/lambda/lambda.man +++ modules/lambda/lambda.man @@ -1,16 +1,22 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin lambda n 1] +[see_also apply(n)] +[see_also proc(n)] +[keywords {anonymous procedure}] +[keywords callback] +[keywords {command prefix}] +[keywords currying] +[keywords lambda] +[keywords {partial application}] +[keywords proc] [copyright {2011 Andreas Kupries, BSD licensed}] [moddesc {Utility commands for anonymous procedures}] [titledesc {Utility commands for anonymous procedures}] [category Utility] [require Tcl 8.5] [require lambda [opt 1]] -[keywords lambda {anonymous procedure} callback {command prefix}] -[keywords {partial application} currying proc] -[see_also apply(n) proc(n)] [description] [para] This package provides two convenience commands to make the writing of anonymous procedures, i.e. lambdas more [cmd proc]-like. Instead of, @@ -59,11 +65,10 @@ [para] When invoked the [arg body] is run in a new procedure scope just underneath the global scope, with the arguments set to the values supplied at both construction and invokation time. - [comment {- - -- --- ----- -------- ------------- ---------------------}] [call [cmd ::lambda@] [arg namespace] [arg arguments] [arg body] [opt [arg arg]...]] The command constructs an anonymous procedure from the namespace name, list of arguments, body script and (optional) predefined argument @@ -77,17 +82,8 @@ [list_end] [section AUTHORS] Andreas Kupries -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph lambda] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY lambda] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ldap/ldap.man ================================================================== --- modules/ldap/ldap.man +++ modules/ldap/ldap.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin ldap n 1.6.9] +[keywords {directory access}] +[keywords internet] +[keywords ldap] +[keywords {ldap client}] +[keywords protocol] +[keywords {rfc 2251}] +[keywords {rfc 4511}] +[keywords x.500] [copyright {2004 Andreas Kupries }] [copyright {2004 Jochen Loewer }] [copyright {2006 Michael Schlenker }] [moddesc {LDAP client}] [titledesc {LDAP client}] @@ -71,31 +79,31 @@ string. Both [arg name] and [arg passwd] default to the empty string if they are not specified. -By leaving out [arg name] and [arg passwd] you can make an anonymous bind to +By leaving out [arg name] and [arg passwd] you can make an anonymous bind to the ldap server. -You can issue [cmd ::ldap::bind] again to bind with different credentials. +You can issue [cmd ::ldap::bind] again to bind with different credentials. [call [cmd ::ldap::bindSASL] [arg handle] [opt [arg name]] [opt [arg password]]] This command uses SASL authentication mechanisms to do a multistage bind. Its otherwise identical to the standard [cmd ::ldap::bind]. This feature is currently experimental and subject to change. See the documentation -for the [package SASL] and the [file SASL.txt] in the tcllib CVS repository for +for the [package SASL] and the [file SASL.txt] in the tcllib CVS repository for details how to setup and use SASL with openldap. [call [cmd ::ldap::unbind] [arg handle]] This command asks the ldap server to release the last bind done for the connection refered to by the token in [arg handle]. -The [arg handle] is invalid after the unbind, as the server closes the connection. +The [arg handle] is invalid after the unbind, as the server closes the connection. So this is effectivly just a more polite disconnect operation. [call [cmd ::ldap::search] [arg handle] [arg baseObject] [arg filterString] [arg attributes] [arg options]] This command performs a LDAP search below the [arg baseObject] tree @@ -122,25 +130,24 @@ [example { {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ... }] [para] - [call [cmd ::ldap::searchInit] [arg handle] [arg baseObject] [arg filterString] [arg attributes] [arg options]] This command initiates a LDAP search below the [arg baseObject] tree -using a complex LDAP search expression [arg filterString]. -The search gets the specified [arg attributes] of all matching objects (DNs). +using a complex LDAP search expression [arg filterString]. +The search gets the specified [arg attributes] of all matching objects (DNs). -The command itself just starts the search, to retrieve the actual results, use -[cmd ::ldap::searchNext]. +The command itself just starts the search, to retrieve the actual results, use +[cmd ::ldap::searchNext]. A search can be terminated at any time by [cmd ::ldap::searchEnd]. This informs the server that no further results should be sent by sending and ABANDON message and cleans up the internal state of the search. Only one [cmd ::ldap::search] can be active at a given time, this -includes the introspection commands [cmd {::ldap::info saslmechanisms}], [cmd {ldap::info control}] and +includes the introspection commands [cmd {::ldap::info saslmechanisms}], [cmd {ldap::info control}] and [cmd {ldap::info extensions}], which invoke a search internally. Error responses from the server due to wrong arguments or similar things are returned with the first [cmd ::ldap::searchNext] call and should be checked and dealed with there. @@ -158,17 +165,17 @@ [list_begin options] [opt_def -scope {base one sub} ] Control the scope of the search to be one of [const base], [const one], or [const sub], to specify a base -object, one-level or subtree search. The default is [const sub]. +object, one-level or subtree search. The default is [const sub]. [opt_def {-derefaliases} {never search find always}] Control how aliases dereferencing is done. Should be one of [const never], [const always], [const search], or [const find] to specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or -dereferenced only when locating the base object for the search. +dereferenced only when locating the base object for the search. The default is to never dereference aliases. [opt_def {-sizelimit} num ] Determines the maximum number of entries to return in a search. If specified as @@ -175,11 +182,11 @@ 0 no limit is enforced. The server may enforce a configuration dependent sizelimit, which may be lower than the one given by this option. The default is 0, no limit. [opt_def {-timelimit} seconds] -Asks the server to use a timelimit of [arg seconds] for the search. Zero means no +Asks the server to use a timelimit of [arg seconds] for the search. Zero means no limit. The default is 0, no limit. [opt_def {-attrsonly} boolean] If set to 1 only the attribute names but not the values will be present in the search result. @@ -191,11 +198,10 @@ The caller can than decide to follow those references and query other LDAP servers for further results. [list_end] [para] - [call [cmd ::ldap::searchNext] [arg handle]] This command returns the next entry from a LDAP search initiated by [cmd ::ldap::searchInit]. It returns only after a new result is received @@ -212,11 +218,10 @@ }] [para] The [cmd ::ldap::searchNext] command returns an empty list at the end of the search. - [para] [call [cmd ::ldap::searchEnd] [arg handle]] @@ -267,11 +272,10 @@ [para] The command blocks until all modifications have completed. Its result is the empty string. - [call [cmd ::ldap::modifyMulti] [arg handle] [arg dn] \ [arg attrValToReplace] \ [opt [arg attrValToDelete]] \ [opt [arg attrValToAdd]]] @@ -310,21 +314,19 @@ [para] The command blocks until all modifications have completed. Its result is the empty string. - [call [cmd ::ldap::add] [arg handle] [arg dn] [arg attrValueTuples]] This command creates a new object using the specified [arg dn]. The attributes of the new object are set to the values in the list [arg attrValueTuples]. Multiple valuated attributes may be specified using multiple tuples. The command blocks until the operation has completed. Its result is the empty string. - [call [cmd ::ldap::addMulti] [arg handle] [arg dn] [arg attrValueTuples]] This command is the preferred one to create a new object using the specified [arg dn]. The @@ -333,19 +335,17 @@ Each tuple is a list containing multiple values. The command blocks until the operation has completed. Its result is the empty string. - [call [cmd ::ldap::delete] [arg handle] [arg dn]] This command removes the object specified by [arg dn], and all its attributes from the server. The command blocks until the operation has completed. Its result is the empty string. - [call [cmd ::ldap::modifyDN] [arg handle] [arg dn] [arg newrdn] [opt [arg deleteOld]] [opt [arg newSuperior]]]] This command moves or copies the object specified by [arg dn] to a new location in the tree of object. This location is @@ -368,26 +368,26 @@ This command returns the IP address of the remote LDAP server the handle is connected to. [call [cmd ::ldap::info] [cmd bound] [arg handle]] -This command returns 1 if a handle has successfully completed a [cmd ::ldap::bind]. +This command returns 1 if a handle has successfully completed a [cmd ::ldap::bind]. If no bind was done or it failed, a 0 is returned. [call [cmd ::ldap::info] [cmd bounduser] [arg handle]] -This command returns the username used in the bind operation if a handle has successfully completed a [cmd ::ldap::bind]. +This command returns the username used in the bind operation if a handle has successfully completed a [cmd ::ldap::bind]. If no bound was done or it failed, an empty string is returned. [call [cmd ::ldap::info] [cmd connections] ] This command returns all currently existing ldap connection handles. [call [cmd ::ldap::info] [cmd tls] [arg handle] ] This command returns 1 if the ldap connection [arg handle] used TLS/SSL for -connection via [cmd ldap::secure_connect] or completed [cmd ldap::starttls], 0 otherwise. +connection via [cmd ldap::secure_connect] or completed [cmd ldap::starttls], 0 otherwise. [call [cmd ::ldap::info] [cmd saslmechanisms] [arg handle]] Return the supported SASL mechanisms advertised by the server. Only valid in a bound state (anonymous or other). @@ -405,11 +405,11 @@ This is currently experimental and subject to change. [call [cmd ::ldap::info] [cmd whoami] [arg handle]] Returns authzId for the current connection. This implements the RFC 4532 -protocol extension. +protocol extension. [list_end] [para] [section EXAMPLES] @@ -469,11 +469,11 @@ ldap::modifyDN $handle $dn "cn=Tester" # Kill the test object, and shut the connection down. set dn "cn=Tester,ou=People,o=University of Michigan,c=US" ldap::delete $handle $dn - + ldap::unbind $handle ldap::disconnect $handle }] [para] @@ -496,14 +496,14 @@ set width 0 set sortedAttribs {} foreach {type values} $attributes { if {[string length $type] > $width} { - set width [string length $type] + set width [string length $type] } lappend sortedAttribs [list $type $values] - } + } puts "object='$object'" foreach sortedAttrib $sortedAttribs { foreach {type values} $sortedAttrib break @@ -516,21 +516,8 @@ } ldap::unbind $handle ldap::disconnect $handle }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ldap] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -One know bug is the usage of [cmd vwait] inside the dispatch mechanism, which makes -it currently unsafe to use this code in code that also enters the event loop. - -[keywords ldap {rfc 2251} {rfc 4511} x.500 {ldap client} {directory access} internet protocol] +[vset CATEGORY ldap] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ldap/ldap.tcl ================================================================== --- modules/ldap/ldap.tcl +++ modules/ldap/ldap.tcl @@ -1570,11 +1570,11 @@ # # In order to handle multi-valuated attributes (see bug 1191326 on # sourceforge), we walk through tuples to collect all values for # an attribute. - # http://sourceforge.net/tracker/index.php?func=detail&atid=112883&group_id=12883&aid=1191326 + # http://core.tcl.tk/tcllib/tktview?name=1191326fff # foreach { attrName attrValue } $attrValueTuples { lappend avpairs($attrName) $attrValue } Index: modules/ldap/ldapx.man ================================================================== --- modules/ldap/ldapx.man +++ modules/ldap/ldapx.man @@ -1,8 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [comment {$Id: ldapx.man,v 1.14 2009/01/29 06:16:19 andreas_kupries Exp $}] [manpage_begin ldapx n 0.2.5] +[keywords {directory access}] +[keywords internet] +[keywords ldap] +[keywords {ldap client}] +[keywords ldif] +[keywords protocol] +[keywords {rfc 2251}] +[keywords {rfc 2849}] [copyright {2006 Pierre David }] [moddesc {LDAP extended object interface}] [titledesc {LDAP extended object interface}] [category Networking] [require Tcl 8.4] @@ -18,11 +26,10 @@ LDAP access is compatible with RFC 2251 ([uri http://www.rfc-editor.org/rfc/rfc2251.txt]). LDIF access is compatible with RFC 2849 ([uri http://www.rfc-editor.org/rfc/rfc2849.txt]). - [section OVERVIEW] The [package ldapx] package provides objects to interact with LDAP directories and LDIF files with an easy to use programming interface. @@ -153,15 +160,13 @@ [list_end] [list_end] - [subsection {Entry Options}] No option is defined by this class. - [subsection {Methods for all kinds of entries}] [list_begin definitions] [call [arg e] [method reset]] @@ -229,11 +234,10 @@ [call [arg se] [method add1] [arg attr] [arg value]] This method adds a single value given by the parameter [arg value] to the attribute [arg attr]. - [call [arg se] [method del] [arg attr] [opt [arg values]]] If the optional list [arg values] is specified, this method deletes all specified values from the attribute [arg attr]. If the argument [arg values] is not specified, this method @@ -286,11 +290,10 @@ This method applies changes defined in the [arg centry] argument, which must be a [emph change] entry. [list_end] - [subsection {Methods for change entries only}] [list_begin definitions] [call [arg ce] [method change] [opt [arg new]]] @@ -311,11 +314,10 @@ is computed from the entry and its internal backup (see section [sectref OVERVIEW]). Return value is the computed change list. [list_end] - [subsection {Entry Example}] [example { package require ldapx @@ -378,11 +380,10 @@ e destroy $b destroy c destroy nc destroy }] - [section {LDAP CLASS}] [subsection {Ldap Instance Data}] @@ -458,11 +459,10 @@ [para] The last option is used when getting entries or committing changes in the directory: - [list_begin options] [opt_def -utf8 {pattern-yes pattern-no}] Specify which attribute values are encoded in UTF-8. This @@ -480,11 +480,10 @@ Default is {{.*} {}}, meaning: all attributes are converted, without exception. [list_end] - [subsection {Ldap Methods}] [list_begin definitions] [call [arg la] [method error] [opt [arg newmsg]]] @@ -554,11 +553,10 @@ Note: in the future, this method should use the LDAP transaction extension provided by OpenLDAP 2.3 and later. [list_end] - [subsection {Ldap Example}] [example { package require ldapx @@ -609,11 +607,10 @@ l disconnect l destroy }] - [section {LDIF CLASS}] [subsection {Ldif Instance Data}] An instance of the [class ldif] class keeps the following data: @@ -649,15 +646,13 @@ version 1 files, and method [method write] only creates version 1 files. [list_end] - [subsection {Ldif Options}] This class defines two options: - [list_begin options] [opt_def -ignore {list-of-attributes}] @@ -687,12 +682,10 @@ Default is {{.*} {}}, meaning: all attributes are converted, without exception. [list_end] - - [subsection {Ldif Methods}] [list_begin definitions] [call [arg li] [method channel] [arg chan]] @@ -717,13 +710,11 @@ [call [arg li] [method write] [arg entry]] This method writes the entry given in the argument [arg entry] to the LDIF file. - [list_end] - [subsection {Ldif Example}] [example { package require ldapx @@ -772,23 +763,10 @@ c destroy liout destroy liin destroy }] - [section References] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ldap] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords ldap ldif {rfc 2251} {rfc 2849} {ldap client} {directory access} internet protocol] +[vset CATEGORY ldap] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/log/log.man ================================================================== --- modules/log/log.man +++ modules/log/log.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin log n 1.3] +[keywords log] +[keywords {log level}] +[keywords message] +[keywords {message level}] [copyright {2001-2009 Andreas Kupries }] [moddesc {Logging facility}] [titledesc {Procedures to log messages of libraries and applications.}] [category {Programming tools}] [require Tcl 8] @@ -91,11 +95,10 @@ [para] The following commands are available: [list_begin definitions] - [call [cmd ::log::levels]] Returns the names of all known levels, in alphabetical order. @@ -206,25 +209,22 @@ are allowed. Errors in the actual logging command are [emph not] caught, but propagated to the caller, as they may indicate misconfigurations of the log facility or errors in the callers code itself. - [call [cmd ::log::logarray] [arg level] [arg arrayvar] [opt [arg pattern]]] Like [cmd ::log::log], but logs the contents of the specified array variable [arg arrayvar], possibly restricted to entries matching the [arg pattern]. The pattern defaults to [const *] (i.e. all entries) if none was specified. - [call [cmd ::log::loghex] [arg level] [arg text] [arg data]] Like [cmd ::log::log], but assumes that [arg data] contains binary data. It converts this into a mixed hex/ascii representation before writing them to the log. - [call [cmd ::log::logMsg] [arg text]] Convenience wrapper around [cmd ::log::log]. Equivalent to [cmd "::log::log info text"]. @@ -270,20 +270,8 @@ [emph Note] that by default all messages with levels [const warning] down to [const debug] are suppressed. This is done intentionally, because (we believe that) in most situations debugging output is not wanted. Most people wish to have such output only when actually debugging an application. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph log] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords log {log level} {message level} message] +[vset CATEGORY log] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/log/logger.man ================================================================== --- modules/log/logger.man +++ modules/log/logger.man @@ -1,8 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [comment {$Id: logger.man,v 1.26 2012/07/10 03:34:47 andreas_kupries Exp $}] [manpage_begin logger n 0.9.3] +[keywords log] +[keywords {log level}] +[keywords logger] +[keywords service] [moddesc {Object Oriented logging facility}] [titledesc {System to control logging of events.}] [category {Programming tools}] [require Tcl 8.2] [require logger [opt 0.9.3]] @@ -49,25 +53,25 @@ service underneath [term foo]), [term bar] would copy the current configuration of the [term foo] service, although it would of course, also be possible to then separately configure [term bar]. If a logger service is initialized and the parent does not yet exist, the -parent is also created. +parent is also created. -The new logger service is initialized with the default loglevel set +The new logger service is initialized with the default loglevel set with [cmd logger::setlevel]. [call [cmd logger::import] [opt [option -all] ] [opt [option -force]] [opt "[option -prefix] [arg prefix]" ] [opt "[option -namespace] [arg namespace]" ] [arg service] ] Import the logger service commands into the current namespace. Without the [option -all] option -only the commands corresponding to the log levels are imported. If [option -all] is given, +only the commands corresponding to the log levels are imported. If [option -all] is given, all the [cmd \${log}::cmd] style commands are imported. If the import would overwrite a command an error is returned and no command is imported. Use the [option -force] option to force the import and overwrite existing commands without complaining. If the [option -prefix] option is given, the commands are imported with the given [arg prefix] -prepended to their names. +prepended to their names. If the [option -namespace] option is given, the commands are imported into the given namespace. If the namespace does not exist, it is created. If a namespace without a leading :: is given, it is interpreted as a child namespace to the current namespace. @@ -133,21 +137,21 @@ [cmd setlevel] instead. [call [cmd \${log}::disable] [arg level]] Disable logging, in the service referenced by [var \${log}], and its -children, at and below the level specified. Note that this does [emph not] enable logging above this level, +children, at and below the level specified. Note that this does [emph not] enable logging above this level, so you should probably use [cmd setlevel] instead. Disabling the loglevel [const emergency] switches logging off for the service and its children. [call [cmd \${log}::lvlchangeproc] [arg command]] [call [cmd \${log}::lvlchangeproc]] Set the script to call when the log instance in question changes its log level. If called without a command it returns the currently registered command. The command gets two arguments appended, the old and the new loglevel. The callback is invoked after all changes have been done. -If child loggers are affected, their callbacks are called before their parents callback. +If child loggers are affected, their callbacks are called before their parents callback. [example { proc lvlcallback {old new} { puts "Loglevel changed from $old to $new" } @@ -157,11 +161,11 @@ [call [cmd \${log}::logproc] [arg level]] [call [cmd \${log}::logproc] [arg level] [arg command]] [call [cmd \${log}::logproc] [arg level] [arg argname] [arg body]] This command comes in three forms - the third, older one is deprecated -and may be removed from future versions of the logger package. +and may be removed from future versions of the logger package. The current set version takes one argument, a command to be executed when the level is called. The callback command takes on argument, the text to be logged. If called only with a valid level [cmd logproc] returns the name of the command currently registered as callback command. @@ -258,11 +262,11 @@ proc foo { args } { puts "In foo" bar 1 return "foo_result" } - + proc bar { x } { puts "In bar" return "bar_result" } @@ -378,26 +382,14 @@ puts "Variables in callers scope:" foreach {var value} $val { puts "$var = $value" } } - + # install as logproc ${log}::logproc debug log_local_var } ] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph logger] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - - -[keywords logger log service {log level}] +[vset CATEGORY logger] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/log/loggerAppender.man ================================================================== --- modules/log/loggerAppender.man +++ modules/log/loggerAppender.man @@ -1,16 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [comment {$Id: loggerAppender.man,v 1.6 2009/01/29 06:16:19 andreas_kupries Exp $}] [manpage_begin logger::appender n 1.2] +[keywords appender] +[keywords logger] [copyright {2005 Aamer Akhter }] [moddesc {Object Oriented logging facility}] [titledesc {Collection of predefined appenders for logger}] [category {Programming tools}] [require Tcl 8.2] [require logger::appender [opt 1.2]] [description] -[keywords logger appender] This package provides a predefined set of logger templates. [list_begin definitions] @@ -47,11 +48,10 @@ Name of the variable to set in the calling context. This variable will contain the name of the procedure. [list_end] - [call [cmd ::logger::appender::colorConsole] \ [option -level] [arg level] \ [option -service] [arg service] [opt [arg options]...] \ ] @@ -58,18 +58,8 @@ See [cmd ::logger::appender::colorConsole] for a description of the applicable options. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph logger] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY logger] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/log/loggerUtils.man ================================================================== --- modules/log/loggerUtils.man +++ modules/log/loggerUtils.man @@ -1,16 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [comment {$Id: loggerUtils.man,v 1.7 2009/01/29 06:16:19 andreas_kupries Exp $}] [manpage_begin logger::utils n 1.3] +[keywords appender] +[keywords logger] [copyright {2005 Aamer Akhter }] [moddesc {Object Oriented logging facility}] [titledesc {Utilities for logger}] [category {Programming tools}] [require Tcl 8.4] [require logger::utils [opt 1.3]] [description] -[keywords logger appender] This package adds template based [term appenders]. [list_begin definitions] @@ -30,11 +31,10 @@ [def %m] Message to be logged [def %M] Method where logging event was issued [def %p] Priority of logging event [def %P] Pid of current process [list_end] - [call [cmd ::logger::utils::createLogProc] \ [option -procName] [arg procName] \ [opt [arg options]...]] @@ -62,11 +62,10 @@ [opt_def -outputChannel channel] channel to output on (default stdout) [list_end] - [call [cmd ::logger::utils::applyAppender] \ [option -appender] [arg appenderType] \ [opt [arg options]...]] @@ -117,12 +116,10 @@ % logger::utils::applyAppender -appender console -serviceCmd $log % ${log}::error "this is an error" [2005/08/22 10:14:13] [testLog] [global] [error] this is an error }] - - [call [cmd ::logger::utils::autoApplyAppender] \ [arg command] [arg command-string] [arg log] [arg op] [arg args]... \ ] This command is designed to be added via [cmd {trace leave}] to calls @@ -140,18 +137,8 @@ set log [logger::init applyAppender-3] ${log}::error "this is an error" }] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph logger] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY logger] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/map/map_geocode_nominatim.man ================================================================== --- modules/map/map_geocode_nominatim.man +++ modules/map/map_geocode_nominatim.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin map::geocode::nominatim n 0.1] +[keywords geocoding] +[keywords http] +[keywords location] +[keywords map] +[keywords nominatim] +[keywords server] +[keywords url] [moddesc {Mapping utilities}] [titledesc {Resolving geographical names with a Nominatim service}] [require Tcl 8.5] [require http] [require json] @@ -101,9 +108,6 @@ [list_begin enum] [enum] [uri http://wiki.openstreetmap.org/wiki/Nominatim] [enum] [uri http://open.mapquestapi.com/nominatim/] [list_end] - -[keywords server geocoding map location nominatim http url] [manpage_end] - Index: modules/map/map_slippy.man ================================================================== --- modules/map/map_slippy.man +++ modules/map/map_slippy.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin map::slippy n 0.5] +[keywords geodesy] +[keywords geography] +[keywords latitute] +[keywords location] +[keywords longitude] +[keywords map] +[keywords slippy] +[keywords zoom] [moddesc {Mapping utilities}] [titledesc {Common code for slippy based map packages}] [require Tcl 8.4] [require Tk 8.4] [require map::slippy [opt 0.5]] @@ -22,22 +30,19 @@ [example { expr { [tiles $level] * [tile size] } }] - [call [cmd ::map::slippy] [method tiles] [arg level]] This method returns the width/height of a slippy-based map at the specified zoom [arg level], in [term tiles]. - [call [cmd ::map::slippy] [method {tile size}]] This method returns the width/height of a tile in a slippy-based map, in pixels. - [call [cmd ::map::slippy] [method {tile valid}] [arg tile] \ [arg levels] [opt [arg msgvar]]] This method checks whether [arg tile] described a valid tile in a @@ -53,19 +58,17 @@ essentially checks this, i.e. the syntax, that the zoom level is between 0 and "[arg levels]-1", and that the row/col information is within the boundaries for the zoom level, i.e. 0 ... "[lb]tiles $zoom[rb]-1". - [call [cmd ::map::slippy] [method {geo 2tile}] [arg geo]] Converts a geographical location at a zoom level ([arg geo], a list containing zoom level, latitude, and longitude, in this order) to a tile identifier (list containing zoom level, row, and column) at that level. The tile identifier uses pure integer numbers for the tile coordinates, for all geographic coordinates mapping to that tile. - [call [cmd ::map::slippy] [method {geo 2tile.float}] [arg geo]] Converts a geographical location at a zoom level ([arg geo], a list containing zoom level, latitude, and longitude, in this order) to a @@ -72,40 +75,35 @@ tile identifier (list containing zoom level, row, and column) at that level. The tile identifier uses floating point numbers for the tile coordinates, representing not only the tile the geographic coordinates map to, but also the fractional location inside of that tile. - [call [cmd ::map::slippy] [method {geo 2point}] [arg geo]] Converts a geographical location at a zoom level ([arg geo], a list containing zoom level, latitude, and longitude, in this order) to a pixel position (list containing zoom level, y, and x) at that level. - [call [cmd ::map::slippy] [method {tile 2geo}] [arg tile]] Converts a tile identifier at a zoom level ([arg tile], list containing zoom level, row, and column) to a geographical location (list containing zoom level, latitude, and longitude, in this order) at that level. - [call [cmd ::map::slippy] [method {tile 2point}] [arg tile]] Converts a tile identifier at a zoom level ([arg tile], a list containing zoom level, row, and column, in this order) to a pixel position (list containing zoom level, y, and x) at that level. - [call [cmd ::map::slippy] [method {point 2geo}] [arg point]] Converts a pixel position at a zoom level ([arg point], list containing zoom level, y, and x) to a geographical location (list containing zoom level, latitude, and longitude, in this order) at that level. - [call [cmd ::map::slippy] [method {point 2tile}] [arg point]] Converts a pixel position at a zoom level ([arg point], a list containing zoom level, y, and x, in this order) to a tile identifier @@ -120,11 +118,10 @@ in this order) fits into a viewport given by [arg canvdim], a 2-element list containing the width and height of the viewport, in this order. [list_end] - [section {Coordinate systems}] The commands of this package operate on three distinct coordinate systems, which are explained below. @@ -144,11 +141,10 @@ going [term north] and negative values going [term south]. While the true range is +/- 90 degrees the projection used by the package requires us to cap the range at +/- 85.05112877983284 degrees. This means that north and south pole are not representable and not part of any map. - [subsection Tiles] While [sectref Geographic]al coordinates of the previous section are independent of zoom level the [term {tile coordinates}] are not. @@ -176,23 +172,18 @@ [para] This means that at zoom level N the map is sliced (horizontally and vertically) into 2^N stripes, for a total of 4^N tiles, with tile coordinates ranging from 0 to 2^N+1. - [subsection Pixels/Points] [term {pixel coordinates}], also called [term {point coordinates}] are in essence [sectref Tiles {tile coordinates}] scaled by the size of the image representing a tile. This tile size currently has a fixed value, [const 256]. - [section References] [list_begin enum] [enum] [uri http://wiki.openstreetmap.org/wiki/Main_Page] [list_end] - - -[keywords slippy map location geodesy geography latitute longitude zoom] [manpage_end] Index: modules/map/map_slippy_cache.man ================================================================== --- modules/map/map_slippy_cache.man +++ modules/map/map_slippy_cache.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin map::slippy::cache n 0.2] +[keywords cache] +[keywords filesystem] +[keywords location] +[keywords map] +[keywords slippy] +[keywords tile] +[keywords zoom] [moddesc {Mapping utilities}] [titledesc {Management of a tile cache in the local filesystem}] [require Tcl 8.4] [require Tk 8.4] [require img::png] @@ -27,11 +34,10 @@ The result of the command is [arg cacheName]. [list_end] - [subsection Methods] [list_begin definitions] [call [arg cacheName] [method valid] [arg tile] [opt [arg msgvar]]] @@ -38,21 +44,17 @@ This method checks the validity of a the given [arg tile] identifier. This is a convenience wrapper to [cmd {::map::slippy tile valid}] and has the same interface. - - [call [arg cacheName] [method exists] [arg tile]] This methods tests whether the cache contains the specified [arg tile] or not. The result is a boolean value, [const true] if the tile is known, and [const false] otherwise. The tile is identified by a list containing three elements, zoom level, row, and column number, in this order. - - [call [arg cacheName] [method get] [arg tile] [arg donecmd]] This is the main method of the cache, retrieving the image for the specified [arg tile] from the cache. The tile identifier is a list @@ -92,10 +94,6 @@ [section References] [list_begin enum] [enum] [uri http://wiki.openstreetmap.org/wiki/Main_Page] [list_end] - - -[keywords cache tile slippy map location zoom filesystem] [manpage_end] - Index: modules/map/map_slippy_fetcher.man ================================================================== --- modules/map/map_slippy_fetcher.man +++ modules/map/map_slippy_fetcher.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin map::slippy::fetcher n 0.3] +[keywords http] +[keywords location] +[keywords map] +[keywords server] +[keywords slippy] +[keywords tile] +[keywords url] +[keywords zoom] [moddesc {Mapping utilities}] [titledesc {Accessing a server providing tiles for slippy-based maps}] [require Tcl 8.4] [require Tk 8.4] [require img::png] @@ -26,11 +34,10 @@ The result of the command is [arg fetcherName]. [list_end] - [subsection Methods] [list_begin definitions] [call [arg fetcherName] [method levels]] @@ -40,15 +47,13 @@ [call [arg fetcherName] [method tileheight]] This method returns the height of tiles served, in pixels. - [call [arg fetcherName] [method tilewidth]] This method returns the width of tiles served, in pixels. - [call [arg fetcherName] [method get] [arg tile] [arg donecmd]] This is the main method of the fetcher, retrieving the image for the specified [arg tile]. The tile identifier is a list containing three @@ -74,10 +79,6 @@ [section References] [list_begin enum] [enum] [uri http://wiki.openstreetmap.org/wiki/Main_Page] [list_end] - - -[keywords server tile slippy map location zoom http url] [manpage_end] - Index: modules/mapproj/mapproj.man ================================================================== --- modules/mapproj/mapproj.man +++ modules/mapproj/mapproj.man @@ -1,15 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin mapproj n 0.1] +[keywords geodesy] +[keywords map] +[keywords projection] [copyright {2007 Kevin B. Kenny }] [moddesc {Tcl Library}] [titledesc {Map projection routines}] [require Tcl [opt 8.4]] [require math::interpolate [opt 1.0]] [require math::special [opt 0.2.1]] [require mapproj [opt 1.0]] -[keywords map projection geodesy] [description] The [package mapproj] package provides a set of procedures for converting between world co-ordinates (latitude and longitude) and map co-ordinates on a number of different map projections. @@ -75,11 +77,11 @@ [call [cmd ::mapproj::fromOrthographic] [arg lambda_0] [arg phi_0] [arg x] [arg y]] Converts from the orthographic projection. [call [cmd ::mapproj::toStereographic] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]] Converts to the stereographic (azimuthal conformal) projection. [call [cmd ::mapproj::fromStereographic] [arg lambda_0] [arg phi_0] [arg x] [arg y]] -Converts from the stereographic (azimuthal conformal) projection. +Converts from the stereographic (azimuthal conformal) projection. [call [cmd ::mapproj::toGnomonic] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]] Converts to the gnomonic projection. [call [cmd ::mapproj::fromGnomonic] [arg lambda_0] [arg phi_0] [arg x] [arg y]] Converts from the gnomonic projection. [call [cmd ::mapproj::toAzimuthalEquidistant] [arg lambda_0] [arg phi_0] [arg lambda] [arg phi]] @@ -156,11 +158,11 @@ The following arguments are accepted by the projection commands: [list_begin definitions] -[def [arg lambda]] +[def [arg lambda]] Longitude of the point to be projected, in degrees. [def [arg phi]] @@ -171,21 +173,21 @@ Longitude of the center of the sheet, in degrees. For many projections, this figure is also the reference meridian of the projection. [def [arg phi_0]] -Latitude of the center of the sheet, in degrees. For the azimuthal +Latitude of the center of the sheet, in degrees. For the azimuthal projections, this figure is also the latitude of the center of the projection. [def [arg phi_1]] Latitude of the first reference parallel, for projections that use reference parallels. [def [arg phi_2]] -Latitude of the second reference parallel, for projections that use reference +Latitude of the second reference parallel, for projections that use reference parallels. [def [arg x]] X co-ordinate of a point on the map, in units of Earth radii. @@ -196,11 +198,11 @@ [list_end] [section Results] -For all of the procedures whose names begin with 'to', the return value +For all of the procedures whose names begin with 'to', the return value is a list comprising an [emph x] co-ordinate and a [emph y] co-ordinate. The co-ordinates are relative to the center of the map sheet to be drawn, measured in Earth radii at the reference location on the map. For all of the functions whose names begin with 'from', the return value @@ -211,27 +213,27 @@ This package offers a great many projections, because no single projection is appropriate to all maps. This section attempts to provide guidance on how to choose a projection. [para] First, consider the type of data that you intend to display on the map. -If the data are [emph directional] ([emph e.g.,] winds, ocean currents, or +If the data are [emph directional] ([emph e.g.,] winds, ocean currents, or magnetic fields) then you need to use a projection that preserves angles; these are known as [emph conformal] projections. Conformal projections include the Mercator, the Albers azimuthal equal-area, the stereographic, and the Peirce Quincuncial projection. If the data are [emph thematic], describing properties of land or water, such as temperature, population density, land use, or demographics; then you need a projection that will show these data with the areas on the map proportional to the areas in real life. These so-called [emph {equal area}] projections include the various cylindrical equal area projections, -the sinusoidal projection, the Lambert azimuthal equal-area projection, -the Albers equal-area conic projection, and several of the world-map +the sinusoidal projection, the Lambert azimuthal equal-area projection, +the Albers equal-area conic projection, and several of the world-map projections (Miller Cylindrical, Mollweide, Eckert IV, Eckert VI, Robinson, and Hammer). If the significant factor in your data is distance from a central point or line (such as air routes), then you will do best with an [emph equidistant] projection such as [emph "plate carr\u00e9e"], -Cassini, azimuthal equidistant, or conic equidistant. If direction from +Cassini, azimuthal equidistant, or conic equidistant. If direction from a central point is a critical factor in your data (for instance, air routes, radio antenna pointing), then you will almost surely want to use one of the azimuthal projections. Appropriate choices are azimuthal equidistant, azimuthal equal-area, stereographic, and perhaps orthographic. [para] @@ -240,28 +242,28 @@ the cylindrical equal area, Eckert IV and VI, Mollweide, Robinson, and Hammer projections are good overall choices. The Mercator projection is traditional, but the extreme distortions of area at high latitudes make it a poor choice unless a conformal projection is required. The Peirce projection is a better choice of conformal projection, having less distortion -of landforms. The Miller Cylindrical is a compromise designed to give +of landforms. The Miller Cylindrical is a compromise designed to give shapes similar to the traditional Mercator, but with less polar stretching. The Peirce Quincuncial projection shows all the continents with acceptable distortion if a reference meridian close to +20 degrees is chosen. The Robinson projection yields attractive maps for things like political divisions, but should be avoided in presenting scientific data, since other projections have moe useful geometric properties. [para] -If the map will cover a hemisphere, then choose stereographic, +If the map will cover a hemisphere, then choose stereographic, azimuthal-equidistant, Hammer, or Mollweide projections; these all project the hemisphere into a circle. [para] -If the map will cover a large area (at least a few hundred km on a side), +If the map will cover a large area (at least a few hundred km on a side), but less than a hemisphere, then you have several choices. Azimuthal projections are usually good (choose stereographic, azimuthal equidistant, or -Lambert azimuthal equal-area according to whether shapes, distances from -a central point, or areas are important). Azimuthal projections (and possibly +Lambert azimuthal equal-area according to whether shapes, distances from +a central point, or areas are important). Azimuthal projections (and possibly the Cassini projection) are the only really good choices for mapping the polar regions. [para] If the large area is in one of the temperate zones and is round or has a primarily east-west extent, then the conic projections are good choices. @@ -271,11 +273,11 @@ should be chosen at approximately 1/6 and 5/6 of the range of latitudes to be displayed. For instance, maps of the 48 coterminous United States are attractive with reference parallels of 28.5 and 45.5 degrees. [para] If the large area is equatorial and is round or has a primarily east-west -extent, then the Mercator projection is a good choice for a conformal +extent, then the Mercator projection is a good choice for a conformal projection; Lambert cylindrical equal-area and sinusoidal projections are good equal-area projections; and the [emph "plate carr\u00e9e"] is a good equidistant projection. [para] Large areas having a primarily North-South aspect, particularly those @@ -301,7 +303,6 @@ map on which all great circles (the shortest distance between two points on the Earth's surface) are rendered as straight lines. While this projection is useful for navigational planning, it has extreme distortions of shape and area, and can display only a limited area of the Earth (substantially less than a hemisphere). - [manpage_end] Index: modules/math/bigfloat.man ================================================================== --- modules/math/bigfloat.man +++ modules/math/bigfloat.man @@ -1,6 +1,12 @@ [manpage_begin math::bigfloat n 2.0.1] +[keywords computations] +[keywords floating-point] +[keywords interval] +[keywords math] +[keywords multiprecision] +[keywords tcl] [copyright {2004-2008, by Stephane Arnold }] [moddesc {Tcl Math Library}] [titledesc {Arbitrary precision floating-point numbers}] [category Mathematics] [require Tcl 8.5] @@ -75,11 +81,10 @@ set x [lb]fromstr 1.0000000000[rb] # the next line does the same, but smarter set y [lb]fromstr 1. 10[rb] [example_end] - [call [cmd tostr] [opt [option -nosci]] [arg number]] Returns a string form of a BigFloat, in which all digits are exacts. [emph "All exact digits"] means a rounding may occur, for example to zero, if the uncertainty interval does not clearly show the true digits. [emph number] may be an integer, causing the command to return exactly the input argument. @@ -96,11 +101,11 @@ [call [cmd fromdouble] [arg double] [opt [arg decimals]]] Converts a double (a simple floating-point value) to a BigFloat, with exactly [arg decimals] digits. Without the [arg decimals] argument, -it behaves like [cmd fromstr]. +it behaves like [cmd fromstr]. Here, the only important feature you might care of is the ability to create BigFloats with a fixed number of [arg decimals]. [example_begin] tostr [lb]fromstr 1.111 4[rb] @@ -128,11 +133,10 @@ set x [lb]int2float $n[rb]; # like fromstr 10.0 puts [lb]tostr $x[rb]; # prints "10." set x [lb]int2float $n 3[rb]; # like fromstr 10.000 puts [lb]tostr $x[rb]; # prints "10.00" [example_end] - [list_end] [section "ARITHMETICS"] [list_begin definitions] @@ -161,11 +165,10 @@ [call [cmd pow] [arg x] [arg n]] Returns [emph x] taken to the [emph n]th power. It only works if [emph n] is an integer. [emph x] might be a BigFloat or an integer. - [list_end] [section COMPARISONS] [list_begin definitions] [call [cmd iszero] [arg x]] @@ -189,11 +192,10 @@ set a [lb]fromstr 0.001[rb] ; # uncertainty interval : 0.000, 0.002 tostr $a ; # 0.e-2 iszero $a ; # true [example_end] - [call [cmd equal] [arg x] [arg y]] Returns 1 if [emph x] and [emph y] are equal, 0 elsewhere. @@ -264,11 +266,11 @@ is internally computed the closest to the reality, thus saving the memory used. [item] When converting back to string, the digits that are printed are not subject to uncertainty. However, some rounding is done, as not doing so causes severe problems. [list_end] -Uncertainties are kept in the internal representation of the number ; +Uncertainties are kept in the internal representation of the number ; it is recommended to use [cmd tostr] only for outputting data (on the screen or in a file), and NEVER call [cmd fromstr] with the result of [cmd tostr]. It is better to always keep operands in their internal representation. Due to the internals of this library, the uncertainty interval may be slightly wider than expected, but this should not cause false digits. @@ -283,22 +285,22 @@ # $a belongs to [lb]1.229, 1.231[rb] set a [lb]fromstr 1.000[rb] # $a belongs to [lb]0.999, 1.001[rb] # $a has a relative uncertainty of 0.1% : 0.001(the uncertainty)/1.000(the medium value) [example_end] -The uncertainty of the sum, or the difference, of two numbers, is the sum +The uncertainty of the sum, or the difference, of two numbers, is the sum of their respective uncertainties. [example_begin] set a [lb]fromstr 1.230[rb] set b [lb]fromstr 2.340[rb] set sum [lb]add $a $b[rb][rb] # the result is : [lb]3.568, 3.572[rb] (the last digit is known with an uncertainty of 2) tostr $sum ; # 3.57 [example_end] -But when, for example, we add or substract an integer to a BigFloat, -the relative uncertainty of the result is unchanged. So it is desirable +But when, for example, we add or substract an integer to a BigFloat, +the relative uncertainty of the result is unchanged. So it is desirable not to convert integers to BigFloats: [example_begin] set a [lb]fromstr 0.999999999[rb] # now something dangerous @@ -335,11 +337,11 @@ puts [lb]tostr [lb]cos [lb]fromstr 0. 5[rb][rb][rb]; # -> 1.0000 puts [lb]tostr [lb]cos [lb]fromstr 0e-10[rb][rb][rb]; # -> 1.000000000 puts [lb]tostr [lb]cos [lb]fromstr 1e-10[rb][rb][rb]; # -> 1.000000000 [example_end] -BigFloats with different internal representations may be converted +BigFloats with different internal representations may be converted to the same string. [para] For most analysis functions (cosine, square root, logarithm, etc.), determining the precision @@ -350,11 +352,10 @@ [example_begin] tostr [lb]exp [lb]fromstr 100.0 10[rb][rb] # returns : 2.688117142e+43 which has only 10 digits of precision, although the entry # has 14 digits of precision. [example_end] - [section "WHAT ABOUT TCL 8.4 ?"] If your setup do not provide Tcl 8.5 but supports 8.4, the package can still be loaded, switching back to [emph math::bigfloat] 1.2. Indeed, an important function introduced in Tcl 8.5 is required - the ability to handle bignums, that we can do with [cmd expr]. @@ -391,11 +392,11 @@ [example_end] If you matter much about avoiding names conflicts, I considere it should be resolved by the following : [example_begin] package require math::bigfloat -# beware: namespace ensembles are not available in Tcl 8.4 +# beware: namespace ensembles are not available in Tcl 8.4 namespace eval ::math::bigfloat {namespace ensemble create -command ::bigfloat} # from now, the bigfloat command takes as subcommands all original math::bigfloat::* commands set a [lb]bigfloat sub [lb]bigfloat fromstr 2.000[rb] [lb]bigfloat fromstr 0.530[rb][rb] puts [lb]bigfloat tostr $a[rb] [example_end] @@ -424,19 +425,8 @@ set cosProduct [lb]mul [lb]cos $angle1[rb] [lb]cos $angle2[rb][rb] set angle3 [lb]asin [lb]add [lb]mul $sinProduct [lb]cos $opposite3[rb][rb] $cosProduct[rb][rb] puts "angle3 : [lb]tostr [lb]rad2deg $angle3[rb][rb]" [example_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: bignum :: float}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords tcl multiprecision math floating-point interval computations] +[vset CATEGORY {math :: bignum :: float}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/bignum.man ================================================================== --- modules/math/bignum.man +++ modules/math/bignum.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::bignum n 3.1] +[keywords bignums] +[keywords math] +[keywords multiprecision] +[keywords tcl] [copyright {2004 Salvatore Sanfilippo }] [copyright {2004 Arjen Markus }] [moddesc {Tcl Math Library}] [titledesc {Arbitrary precision integer numbers}] [category Mathematics] @@ -32,11 +36,10 @@ The bignum interface is opaque, so operations on bignums that are not returned by procedures in this package (but created by hand) may lead to unspecified behaviours. It's safe to treat bignums as pure values, so there is no need to free a bignum, or to duplicate it via a special operation. - [section "EXAMPLES"] This section shows some simple example. This library being just a way to perform math operations, examples may be the simplest way to learn how to work with it. Consult the API section of @@ -218,19 +221,8 @@ Return the number of bits needed to represent bignum in radix 2. [list_end] [para] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: bignum}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords tcl multiprecision math bignums] +[vset CATEGORY {math :: bignum}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/calculus.man ================================================================== --- modules/math/calculus.man +++ modules/math/calculus.man @@ -1,6 +1,12 @@ [manpage_begin math::calculus n 0.7.1] +[see_also romberg] +[keywords calculus] +[keywords {differential equations}] +[keywords integration] +[keywords math] +[keywords roots] [copyright {2002,2003,2004 Arjen Markus}] [moddesc {Tcl Math Library}] [titledesc {Integration and ordinary differential equations}] [category Mathematics] [require Tcl 8.4] @@ -76,18 +82,16 @@ polynomials of third degree or less. [para] The function must take two arguments and return the function value. - [call [cmd ::math::calculus::integral3D] [arg xinterval] [arg yinterval] [arg zinterval] [arg func]] [call [cmd ::math::calculus::integral3D_accurate] [arg xinterval] [arg yinterval] [arg zinterval] [arg func]] The commands [cmd integral3D] and [cmd integral3D_accurate] are the three-dimensional equivalent of [cmd integral2D] and [cmd integral3D_accurate]. The function [emph func] takes three arguments and is integrated over the block in 3D space given by three intervals. - [call [cmd ::math::calculus::eulerStep] [arg t] [arg tstep] [arg xvec] [arg func]] Set a single step in the numerical integration of a system of differential equations. The method used is Euler's. @@ -106,11 +110,10 @@ Function of t and the dependent values, returning a list of the derivatives of the dependent values. (The lengths of xvec and the return value of "func" must match). [list_end] [para] - [call [cmd ::math::calculus::heunStep] [arg t] [arg tstep] [arg xvec] [arg func]] Set a single step in the numerical integration of a system of differential equations. The method used is Heun's. @@ -130,11 +133,10 @@ a list of the derivatives of the dependent values. (The lengths of xvec and the return value of "func" must match). [list_end] [para] - [call [cmd ::math::calculus::rungeKuttaStep] [arg t] [arg tstep] [arg xvec] [arg func]] Set a single step in the numerical integration of a system of differential equations. The method used is Runge-Kutta 4th order. @@ -153,11 +155,10 @@ Function of t and the dependent values, returning a list of the derivatives of the dependent values. (The lengths of xvec and the return value of "func" must match). [list_end] [para] - [call [cmd ::math::calculus::boundaryValueSecondOrder] [arg coeff_func] [arg force_func] [arg leftbnd] [arg rightbnd] [arg nostep]] Solve a second order linear differential equation with boundary values at two sides. The equation has to be of the form (the "conservative" form): @@ -207,11 +208,10 @@ The procedure returns a list of x-coordinates and the approximated values of the solution. [list_end] [para] - [call [cmd ::math::calculus::solveTriDiagonal] [arg acoeff] [arg bcoeff] [arg ccoeff] [arg dvalue]] Solve a system of linear equations Ax = b with A a tridiagonal matrix. Returns the solution as a list. [list_begin definitions] @@ -226,11 +226,10 @@ [def [arg dvalue]] List of values on the righthand-side [list_end] [para] - [call [cmd ::math::calculus::newtonRaphson] [arg func] [arg deriv] [arg initval]] Determine the root of an equation given by [example_begin] func(x) = 0 @@ -248,11 +247,10 @@ [def [arg initval]] Initial value for x [list_end] [para] - [call [cmd ::math::calculus::newtonRaphsonParameters] [arg maxiter] [arg tolerance]] Set the numerical parameters for the Newton-Raphson method: [list_begin definitions] [def [arg maxiter]] @@ -259,11 +257,10 @@ Maximum number of iteration steps (defaults to 20) [def [arg tolerance]] Relative precision (defaults to 0.001) [list_end] - [call [cmd ::math::calculus::regula_falsi] [arg f] [arg xb] [arg xe] [arg eps]] Return an estimate of the zero or one of the zeros of the function contained in the interval [lb]xb,xe[rb]. The error in this estimate is of the @@ -407,21 +404,8 @@ set y [lb]::math::calculus::boundaryValueSecondOrder \ coeffs force {0.0 1.0} [lb]list $length 0.0[rb] 100[rb] [example_end] -[see_also romberg] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: calculus}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math calculus integration "differential equations" roots] +[vset CATEGORY {math :: calculus}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/combinatorics.man ================================================================== --- modules/math/combinatorics.man +++ modules/math/combinatorics.man @@ -34,11 +34,11 @@ [emph {ISIAM J. Numerical Analysis, series B,}] volume 1, p. 86. For "[var x] > 1", the absolute error of the result is claimed to be smaller than 5.5*10**-10 -- that is, the resulting value of Gamma when [example { - exp( ln_Gamma( x) ) + exp( ln_Gamma( x) ) }] is computed is expected to be precise to better than nine significant figures. @@ -101,18 +101,8 @@ nine significant digits provided that [arg w] and [arg z] are both at least 1. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph math] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - +[vset CATEGORY math] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/constants.man ================================================================== --- modules/math/constants.man +++ modules/math/constants.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::constants n 1.0.1] +[keywords constants] +[keywords degrees] +[keywords e] +[keywords math] +[keywords pi] +[keywords radians] [copyright {2004 Arjen Markus }] [moddesc {Tcl Math Library}] [titledesc {Mathematical and numerical constants}] [category Mathematics] [require Tcl [opt 8.3]] @@ -100,19 +106,8 @@ (name, value and description) or, if no arguments are given, print all defined constants. This is mainly a convenience procedure. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: constants}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math constants pi e radians degrees] +[vset CATEGORY {math :: constants}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/decimal.man ================================================================== --- modules/math/decimal.man +++ modules/math/decimal.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::decimal n 1.0.2] +[keywords decimal] +[keywords math] +[keywords tcl] [copyright {2011 Mark Alston }] [moddesc {Tcl Decimal Arithmetic Library}] [titledesc {General decimal arithmetic}] [category Mathematics] [require Tcl [opt 8.5]] @@ -64,11 +67,10 @@ # Why bother using this instead of simply expr? puts [expr {8.2 + .2}] ; # => will output 8.399999999999999 puts [expr {8.2 - .2}] ; # => will output 7.999999999999999 # See http://speleotrove.com/decimal to learn more about why this happens. [example_end] - [section "API"] [list_begin definitions] [call [cmd ::math::decimal::fromstr] [arg string]] @@ -189,19 +191,8 @@ the result is the same as for round-down. [list_end] [para] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {Decimal}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords tcl decimal math] +[vset CATEGORY decimal] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/fourier.man ================================================================== --- modules/math/fourier.man +++ modules/math/fourier.man @@ -1,6 +1,10 @@ [manpage_begin math::fourier n 1.0.2] +[keywords {complex numbers}] +[keywords FFT] +[keywords {Fourier transform}] +[keywords mathematics] [moddesc {Tcl Math Library}] [titledesc {Discrete and fast fourier transforms}] [category Mathematics] [require Tcl 8.4] [require math::fourier 1.0.2] @@ -72,11 +76,10 @@ The package includes two simple filters. They have an analogue equivalent in a simple electronic circuit, a resistor and a capacitance in series. Using these filters requires the [package math::complexnumbers] package. - [section "PROCEDURES"] The public Fourier transform procedures are: [list_begin definitions] @@ -124,19 +127,8 @@ [list_end] [para] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: fourier}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords mathematics "FFT" "Fourier transform" "complex numbers"] +[vset CATEGORY {math :: fourier}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/fuzzy.man ================================================================== --- modules/math/fuzzy.man +++ modules/math/fuzzy.man @@ -1,6 +1,9 @@ [manpage_begin math::fuzzy n 0.2] +[keywords floating-point] +[keywords math] +[keywords rounding] [moddesc {Tcl Math Library}] [titledesc {Fuzzy comparison of floating-point numbers}] [category Mathematics] [require Tcl [opt 8.3]] [require math::fuzzy [opt 0.2]] @@ -123,19 +126,8 @@ [para] D. Knuth, Art of Computer Programming, Vol. 1, Problem 1.2.4-5. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: fuzzy}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math floating-point rounding] +[vset CATEGORY {math :: fuzzy}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/interpolate.man ================================================================== --- modules/math/interpolate.man +++ modules/math/interpolate.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::interpolate n 1.0.2] +[keywords interpolation] +[keywords math] +[keywords {spatial interpolation}] [copyright {2004 Arjen Markus }] [copyright {2004 Kevn B. Kenny }] [moddesc {Tcl Math Library}] [titledesc {Interpolation routines}] [category Mathematics] @@ -68,11 +71,10 @@ The values must be sorted with respect to the independent variable(s). [list_end] [para] - [call [cmd ::math::interpolate::interp-1d-table] [arg name] [arg xval]] Interpolate into the one-dimensional table "name" and return a list of values, one for each dependent column. @@ -82,11 +84,10 @@ [arg_def float xval in] Value of the independent [emph row] variable [list_end] [para] - [call [cmd ::math::interpolate::interp-table] [arg name] [arg xval] [arg yval]] Interpolate into the two-dimensional table "name" and return the interpolated value. @@ -99,11 +100,10 @@ [list_end] [para] - [call [cmd ::math::interpolate::interp-linear] [arg xyvalues] [arg xval]] Interpolate linearly into the list of x,y pairs and return the interpolated value. [list_begin arguments] @@ -115,11 +115,10 @@ must be computed. [list_end] [para] - [call [cmd ::math::interpolate::interp-lagrange] [arg xyvalues] [arg xval]] Use the list of x,y pairs to construct the unique polynomial of lowest degree that passes through all points and return the interpolated value. @@ -166,11 +165,10 @@ [list_end] [para] - [call [cmd ::math::interpolate::interp-spatial] [arg xyvalues] [arg coord]] Use a straightforward interpolation method with weights as function of the inverse distance to interpolate in 2D and N-dimensional space @@ -196,11 +194,10 @@ [list_end] [para] - [call [cmd ::math::interpolate::interp-spatial-params] [arg max_search] [arg power]] Set the parameters for spatial interpolation [list_begin arguments] @@ -222,11 +219,10 @@ interpolating polynomial of high degree, which is likely to result in numerical instabilities; one is better off using only a few tabulated values near the desired abscissa. [list_end] - [section EXAMPLES] [emph TODO] Example of using the cubic splines: @@ -262,20 +258,8 @@ 0.9: 3.95675857843 1.0: 4.12 }] As you can see, the values at the abscissae are reproduced perfectly. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: interpolate}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math interpolation "spatial interpolation"] +[vset CATEGORY {math :: interpolate}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/linalg.man ================================================================== --- modules/math/linalg.man +++ modules/math/linalg.man @@ -1,17 +1,22 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::linearalgebra n 1.1] +[keywords {least squares}] +[keywords {linear algebra}] +[keywords {linear equations}] +[keywords math] +[keywords matrices] +[keywords matrix] +[keywords vectors] [copyright {2004-2008 Arjen Markus }] [copyright {2004 Ed Hume }] [copyright {2008 Michael Buadin }] [moddesc {Tcl Math Library}] [titledesc {Linear Algebra}] [category Mathematics] [require Tcl [opt 8.4]] [require math::linearalgebra [opt 1.1]] -[keywords math {linear algebra} vectors matrices {least squares}] -[keywords matrix {linear equations}] [description] [para] This package offers both low-level procedures and high-level algorithms to deal with linear algebra problems: @@ -47,12 +52,10 @@ [section "PROCEDURES"] The package defines the following public procedures (several exist as specialised procedures, see below): - - [para] [emph "Constructing matrices and vectors"] [list_begin definitions] @@ -190,12 +193,10 @@ [arg_def integer imin] Maximum row index (default: nrows-1) [list_end] [list_end] - - [para] [emph "Querying matrices and vectors"] [list_begin definitions] @@ -270,12 +271,10 @@ [arg_def float eps] Tolerance for determining approximate equality (defaults to 1.0e-8) [list_end] [list_end] - - [para] [emph "Basic operations"] [list_begin definitions] @@ -489,12 +488,10 @@ [arg_def list mv2] Second vector/matrix (y) [list_end] [list_end] - - [para] [emph "Common matrices and test matrices"] [list_begin definitions] @@ -625,12 +622,10 @@ [list_begin arguments] [arg_def integer size] Dimension of the matrix [list_end] [list_end] - - [para] [emph "Common algorithms"] [list_begin definitions] @@ -852,11 +847,10 @@ [arg_def integer maxiter] The maximum number of iterations (default:10). [list_end] [list_end] - [para] [emph "Compability with the LA package"] Two procedures are provided for compatibility with Hume's LA package: @@ -878,15 +872,13 @@ [list_begin arguments] [arg_def list mv] Matrix or vector as used by the LA package [list_end] - [list_end] [para] - [section "STORAGE"] While most procedures assume that the matrices are given in full form, the procedures [emph solveGaussBand] and [emph solveTriangularBand] @@ -968,17 +960,8 @@ rename ::scale scaleTk scaleTk .scale ... } }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: linearalgebra}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY {math :: linearalgebra}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/machineparameters.man ================================================================== --- modules/math/machineparameters.man +++ modules/math/machineparameters.man @@ -182,6 +182,8 @@ Print machine parameters on standard output. [list_end] +[vset CATEGORY math] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/math.man ================================================================== --- modules/math/math.man +++ modules/math/math.man @@ -1,6 +1,8 @@ [manpage_begin math n 1.2.5] +[keywords math] +[keywords statistics] [comment {-*- tcl -*- doctools manpage}] [moddesc {Tcl Math Library}] [titledesc {Tcl Math Library}] [category Mathematics] [require Tcl 8.2] @@ -67,41 +69,34 @@ [call [cmd ::math::cov] [arg value] [arg value] [opt [arg {value ...}]]] Return the coefficient of variation expressed as percent of two or more numeric values. - [call [cmd ::math::integrate] [arg {list of xy value pairs}]] Return the area under a "curve" defined by a set of x,y pairs and the error bound as a list. - [call [cmd ::math::fibonacci] [arg n]] Return the [arg n]'th Fibonacci number. - [call [cmd ::math::max] [arg value] [opt [arg {value ...}]]] Return the maximum of one or more numeric values. - [call [cmd ::math::mean] [arg value] [opt [arg {value ...}]]] Return the mean, or "average" of one or more numeric values. - [call [cmd ::math::min] [arg value] [opt [arg {value ...}]]] Return the minimum of one or more numeric values. - [call [cmd ::math::product] [arg value] [opt [arg {value ...}]]] Return the product of one or more numeric values. - [call [cmd ::math::random] [opt [arg value1]] [opt [arg value2]]] Return a random number. If no arguments are given, the number is a floating point value between 0 and 1. If one argument is given, the @@ -108,38 +103,24 @@ number is an integer value between 0 and [arg value1]. If two arguments are given, the number is an integer value between [arg value1] and [arg value2]. - [call [cmd ::math::sigma] [arg value] [arg value] [opt [arg {value ...}]]] Return the population standard deviation of two or more numeric values. - [call [cmd ::math::stats] [arg value] [arg value] [opt [arg {value ...}]]] Return the mean, standard deviation, and coefficient of variation (as percent) as a list. - [call [cmd ::math::sum] [arg value] [opt [arg {value ...}]]] Return the sum of one or more numeric values. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph math] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math statistics] +[vset CATEGORY math] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/math_geometry.man ================================================================== --- modules/math/math_geometry.man +++ modules/math/math_geometry.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::geometry n 1.1.2] +[keywords angle] +[keywords distance] +[keywords line] +[keywords math] +[keywords {plane geometry}] +[keywords point] [copyright {2001 by Ideogramic ApS and other parties}] [copyright {2004 by Arjen Markus}] [copyright {2010 by Andreas Kupries}] [copyright {2010 by Kevin Kenny}] [moddesc {Tcl Math Library}] @@ -57,11 +63,10 @@ [emph "point set"] - again a list of an even number of coordinates, but the points are regarded without any ordering. [list_end] - [section "PROCEDURES"] The package defines the following public procedures: [list_begin definitions] @@ -93,11 +98,10 @@ [call [cmd ::math::geometry::length] [arg point]] Compute the length of the vector and return it as the result of the command. - [call [cmd ::math::geometry::s*] [arg factor] [arg point]] Scale the vector by the factor and return it as the result of the command. This is a vector as well. @@ -110,11 +114,10 @@ [call [cmd ::math::geometry::h] [arg length]] Returns a horizontal vector on the X-axis of the specified length. Positive lengths point to the right (east). - [call [cmd ::math::geometry::v] [arg length]] Returns a vertical vector on the Y-axis of the specified length. Positive lengths point down (south). @@ -122,11 +125,10 @@ Compute the point which is at relative distance [arg s] between the two points and return it as the result of the command. A relative distance of [const 0] returns [arg point1], the distance [const 1] returns [arg point2]. Distances < 0 or > 1 extrapolate along the line between the two point. - [call [cmd ::math::geometry::octant] [arg point]] Compute the octant of the circle the point is in and return it as the result of the command. The possible results are @@ -142,11 +144,10 @@ [enum] southeast [list_end] Each octant is the arc of the circle +/- 22.5 degrees from the cardinal direction the octant is named for. - [call [cmd ::math::geometry::rect] [arg nw] [arg se]] Construct a rectangle from its northwest and southeast corners and return it as the result of the command. @@ -432,19 +433,8 @@ [enum] [uri http:/wiki.tcl.tk/12070 {Polygon Intersection}] [enum] [uri http://en.wikipedia.org/wiki/Line-line_intersection] [enum] [uri http://local.wasp.uwa.edu.au/~pbourke/geometry/lineline2d/] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: geometry}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math "plane geometry" "point" "line" "distance" "angle"] +[vset CATEGORY {math :: geometry}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/numtheory.man ================================================================== --- modules/math/numtheory.man +++ modules/math/numtheory.man @@ -1,6 +1,8 @@ [manpage_begin math::numtheory n 1.0] +[keywords {number theory}] +[keywords prime] [copyright "2010 Lars Hellstr\u00F6m\ "] [moddesc {Tcl Math Library}] [titledesc {Number Theory}] [category Mathematics] @@ -47,7 +49,8 @@ [list_end] Unknown options are silently ignored. [list_end] -[keywords {number theory} prime] +[vset CATEGORY {math :: numtheory}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/optimize.man ================================================================== --- modules/math/optimize.man +++ modules/math/optimize.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::optimize n 1.0] +[keywords {linear program}] +[keywords math] +[keywords maximum] +[keywords minimum] +[keywords optimization] [copyright {2004 Arjen Markus }] [copyright {2004,2005 Kevn B. Kenny }] [moddesc {Tcl Math Library}] [titledesc {Optimisation routines}] [category Mathematics] @@ -165,11 +170,10 @@ [para] [arg objective] - The M coefficients of the objective function [para] [arg result] - The result as returned by solveLinearProgram - [call [cmd ::math::optimize::nelderMead] [arg objective] [arg xVector] [opt "[option -scale] [arg xScaleVector]"] [opt "[option -ftol] [arg epsilon]"] [opt "[option -maxiter] [arg count]"] [opt "[opt -trace] [arg flag]"]] Minimizes, in unconstrained fashion, a function of several variable over all of space. The function to evaluate, [arg objective], must be a single Tcl command. To it will be appended as many elements as appear in the initial guess at @@ -314,19 +318,8 @@ [para] The theory of linear programming is the subject of many a text book and the Simplex algorithm that is implemented here is the best-known method to solve this type of problems, but it is not the only one. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: optimize}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math optimization minimum maximum "linear program"] +[vset CATEGORY {math :: optimize}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/polynomials.man ================================================================== --- modules/math/polynomials.man +++ modules/math/polynomials.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::polynomials n 1.0.1] +[keywords math] +[keywords {polynomial functions}] [copyright {2004 Arjen Markus }] [moddesc {Tcl Math Library}] [titledesc {Polynomial functions}] [category Mathematics] [require Tcl [opt 8.3]] @@ -72,11 +74,10 @@ [list_end] [para] - [call [cmd ::math::polynomials::addPolyn] [arg polyn1] [arg polyn2]] Return a new polynomial which is the sum of the two others. [list_begin arguments] @@ -86,11 +87,10 @@ [list_end] [para] - [call [cmd ::math::polynomials::subPolyn] [arg polyn1] [arg polyn2]] Return a new polynomial which is the difference of the two others. [list_begin arguments] @@ -99,11 +99,10 @@ [arg_def list polyn2] The second polynomial operand [list_end] [para] - [call [cmd ::math::polynomials::multPolyn] [arg polyn1] [arg polyn2]] Return a new polynomial which is the product of the two others. If one of the arguments is a scalar value, the other polynomial is simply @@ -116,11 +115,10 @@ [list_end] [para] - [call [cmd ::math::polynomials::divPolyn] [arg polyn1] [arg polyn2]] Divide the first polynomial by the second polynomial and return the result. The remainder is dropped @@ -130,11 +128,10 @@ [arg_def list polyn2] The second polynomial operand [list_end] [para] - [call [cmd ::math::polynomials::remainderPolyn] [arg polyn1] [arg polyn2]] Divide the first polynomial by the second polynomial and return the remainder. @@ -146,11 +143,10 @@ [list_end] [para] - [call [cmd ::math::polynomials::derivPolyn] [arg polyn]] Differentiate the polynomial and return the result. [list_begin arguments] @@ -157,11 +153,10 @@ [arg_def list polyn] The polynomial to be differentiated [list_end] [para] - [call [cmd ::math::polynomials::primitivePolyn] [arg polyn]] Integrate the polynomial and return the result. The integration constant is set to zero. @@ -171,11 +166,10 @@ [list_end] [para] - [call [cmd ::math::polynomials::degreePolyn] [arg polyn]] Return the degree of the polynomial. [list_begin arguments] @@ -182,11 +176,10 @@ [arg_def list polyn] The polynomial to be examined [list_end] [para] - [call [cmd ::math::polynomials::coeffPolyn] [arg polyn] [arg index]] Return the coefficient of the term of the index'th degree of the polynomial. @@ -197,11 +190,10 @@ [list_end] [para] - [call [cmd ::math::polynomials::allCoeffsPolyn] [arg polyn]] Return the coefficients of the polynomial (in ascending order). [list_begin arguments] @@ -208,11 +200,10 @@ [arg_def list polyn] The polynomial in question [list_end] [list_end] - [section "REMARKS ON THE IMPLEMENTATION"] The implementation for evaluating the polynomials at some point uses Horn's rule, which guarantees numerical stability and a minimum of @@ -221,20 +212,8 @@ To recognise that a polynomial definition is indeed a correct definition, it consists of a list of two elements: the keyword "POLYNOMIAL" and the list of coefficients in descending order. The latter makes it easier to implement Horner's rule. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: polynomials}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math "polynomial functions"] +[vset CATEGORY {math :: polynomials}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/qcomplex.man ================================================================== --- modules/math/qcomplex.man +++ modules/math/qcomplex.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::complexnumbers n 1.0.2] +[keywords {complex numbers}] +[keywords math] [copyright {2004 Arjen Markus }] [moddesc {Tcl Math Library}] [titledesc {Straightforward complex number package}] [category Mathematics] [require Tcl 8.3] @@ -293,20 +295,8 @@ [list_end] [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: complexnumbers}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math {complex numbers}] +[vset CATEGORY {math :: complexnumbers}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/rational_funcs.man ================================================================== --- modules/math/rational_funcs.man +++ modules/math/rational_funcs.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::rationalfunctions n 1.0.1] +[keywords math] +[keywords {rational functions}] [copyright {2005 Arjen Markus }] [moddesc {Math}] [titledesc {Polynomial functions}] [category Mathematics] [require Tcl [opt 8.4]] @@ -81,11 +83,10 @@ [list_end] [para] - [call [cmd ::math::rationalfunctions::addRatio] [arg ratio1] [arg ratio2]] Return a new rational function which is the sum of the two others. [list_begin arguments] @@ -94,11 +95,10 @@ [arg_def list ratio2] The second rational function operand [list_end] [para] - [call [cmd ::math::rationalfunctions::subRatio] [arg ratio1] [arg ratio2]] Return a new rational function which is the difference of the two others. @@ -109,11 +109,10 @@ [arg_def list ratio2] The second rational function operand [list_end] [para] - [call [cmd ::math::rationalfunctions::multRatio] [arg ratio1] [arg ratio2]] Return a new rational function which is the product of the two others. If one of the arguments is a scalar value, the other rational function is @@ -126,11 +125,10 @@ [list_end] [para] - [call [cmd ::math::rationalfunctions::divRatio] [arg ratio1] [arg ratio2]] Divide the first rational function by the second rational function and return the result. The remainder is dropped @@ -141,11 +139,10 @@ [list_end] [para] - [call [cmd ::math::rationalfunctions::derivPolyn] [arg ratio]] Differentiate the rational function and return the result. [list_begin arguments] @@ -153,21 +150,19 @@ [list_end] [para] - [call [cmd ::math::rationalfunctions::coeffsNumerator] [arg ratio]] Return the coefficients of the numerator of the rational function. [list_begin arguments] [arg_def list ratio] The rational function to be examined [list_end] [para] - [call [cmd ::math::rationalfunctions::coeffsDenominator] [arg ratio]] Return the coefficients of the denominator of the rational function. @@ -178,26 +173,14 @@ [para] [list_end] - [section "REMARKS ON THE IMPLEMENTATION"] The implementation of the rational functions relies on the math::polynomials package. For further remarks see the documentation on that package. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: rationalfunctions}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math "rational functions"] +[vset CATEGORY {math :: rationalfunctions}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/roman.man ================================================================== --- modules/math/roman.man +++ modules/math/roman.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::roman "" 1.0] +[keywords conversion] +[keywords integer] +[keywords {roman numeral}] [copyright {2005 Kenneth Green }] [moddesc {Tcl Math Library}] [titledesc {Tools for creating and manipulating roman numerals}] [category Mathematics] [require Tcl 8.3] @@ -41,19 +44,8 @@ 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. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: roman}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords conversion integer "roman numeral"] +[vset CATEGORY {math :: roman}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/romberg.man ================================================================== --- modules/math/romberg.man +++ modules/math/romberg.man @@ -1,6 +1,8 @@ [manpage_begin math::calculus::romberg n 0.6] +[see_also math::calculus] +[see_also math::interpolate] [copyright "2004 Kevin B. Kenny . All rights\ reserved. Redistribution permitted under the terms of the Open\ Publication License "] [moddesc {Tcl Math Library}] [titledesc {Romberg integration}] @@ -331,21 +333,8 @@ puts [format "integral is %.6g +/- %.6g" $value $error] integral is 3.97746 +/- 2.3557e-010 }] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: calculus}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - - -[see_also math::calculus math::interpolate] +[vset CATEGORY {math :: calculus}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/special.man ================================================================== --- modules/math/special.man +++ modules/math/special.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin math::special n 0.2] +[keywords {Bessel functions}] +[keywords {error function}] +[keywords math] +[keywords {special functions}] [copyright {2004 Arjen Markus }] [moddesc {Tcl Math Library}] [titledesc {Special mathematical functions}] [category Mathematics] [require Tcl [opt 8.3]] @@ -51,11 +55,10 @@ [item] legendre, hermite: some of the classical orthogonal polynomials. [list_end] - [section OVERVIEW] In the following table several characteristics of the functions in this package are summarized: the domain for the argument, the values for the @@ -119,11 +122,10 @@ [item] The digamma function (psi) [item] The incomplete gamma and beta functions [list_end] - [section "PROCEDURES"] The package defines the following public procedures: @@ -332,37 +334,33 @@ [list_begin arguments] [arg_def float x] Argument for the function (x > 0) [list_end] - [call [cmd ::math::special::fresnel_C] [arg x]] Compute the Fresnel cosine integral for real argument x [list_begin arguments] [arg_def float x] Argument for the function [list_end] - [call [cmd ::math::special::fresnel_S] [arg x]] Compute the Fresnel sine integral for real argument x [list_begin arguments] [arg_def float x] Argument for the function [list_end] - [call [cmd ::math::special::sinc] [arg x]] Compute the sinc function for real argument x [list_begin arguments] [arg_def float x] Argument for the function [list_end] - [call [cmd ::math::special::legendre] [arg n]] Return the Legendre polynomial of degree n (see [sectref "THE ORTHOGONAL POLYNOMIALS"]) @@ -371,21 +369,19 @@ [arg_def int n] Degree of the polynomial [list_end] [para] - [call [cmd ::math::special::chebyshev] [arg n]] Return the Chebyshev polynomial of degree n (of the first kind) [list_begin arguments] [arg_def int n] Degree of the polynomial [list_end] [para] - [call [cmd ::math::special::laguerre] [arg alpha] [arg n]] Return the Laguerre polynomial of degree n with parameter alpha @@ -394,11 +390,10 @@ [arg_def int n] Degree of the polynomial [list_end] [para] - [call [cmd ::math::special::hermite] [arg n]] Return the Hermite polynomial of degree n [list_begin arguments] @@ -406,11 +401,10 @@ [list_end] [para] [list_end] - [section "THE ORTHOGONAL POLYNOMIALS"] For dealing with the classical families of orthogonal polynomials, the package relies on the [emph math::polynomials] package. To evaluate the @@ -421,11 +415,10 @@ }] [para] The return value from the [emph legendre] and other commands is actually the definition of the corresponding polynomial as used in that package. - [section "REMARKS ON THE IMPLEMENTATION"] It should be noted, that the actual implementation of J0 and J1 depends on straightforward Gaussian quadrature formulas. The (absolute) accuracy @@ -458,20 +451,8 @@ Much information about these functions can be found in: [para] Abramowitz and Stegun: [emph "Handbook of Mathematical Functions"] (Dover, ISBN 486-61272-4) - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: special}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords math "special functions" "Bessel functions" "error function"] +[vset CATEGORY {math :: special}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/statistics.man ================================================================== --- modules/math/statistics.man +++ modules/math/statistics.man @@ -1,6 +1,9 @@ [manpage_begin math::statistics n 0.8] +[keywords {data analysis}] +[keywords mathematics] +[keywords statistics] [moddesc {Tcl Math Library}] [titledesc {Basic statistical functions and procedures}] [category Mathematics] [require Tcl 8.4] [require math::statistics 0.8] @@ -55,28 +58,25 @@ [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::min] [arg data]] Determine the [term minimum] value of the given list of data. [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::max] [arg data]] Determine the [term maximum] value of the given list of data. [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::number] [arg data]] Determine the [term number] of non-missing data in the given list [list_begin arguments] @@ -91,29 +91,26 @@ [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::var] [arg data]] Determine the [term "sample variance"] of the data in the given list [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::pstdev] [arg data]] Determine the [term "population standard deviation"] of the data in the given list [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::pvar] [arg data]] Determine the [term "population variance"] of the data in the given list @@ -120,21 +117,19 @@ [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::median] [arg data]] Determine the [term median] of the data in the given list (Note that this requires sorting the data, which may be a costly operation) [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::basic-stats] [arg data]] Determine a list of all the descriptive parameters: mean, minimum, maximum, number of data, sample standard deviation, sample variance, population standard deviation and population variance. @@ -146,11 +141,10 @@ [list_begin arguments] [arg_def list data] - List of data [list_end] [para] - [call [cmd ::math::statistics::histogram] [arg limits] [arg values]] Determine histogram information for the given list of data. Returns a list consisting of the number of values that fall into each interval. (The first interval consists of all values lower than the first limit, the last interval consists of all values greater than the last limit. @@ -161,20 +155,18 @@ intervals of the histogram. [arg_def list values] - List of data [list_end] [para] - [call [cmd ::math::statistics::corr] [arg data1] [arg data2]] Determine the correlation coefficient between two sets of data. [list_begin arguments] [arg_def list data1] - First list of data [arg_def list data2] - Second list of data [list_end] [para] - [call [cmd ::math::statistics::interval-mean-stdev] [arg data] [arg confidence]] Return the interval containing the mean value and one containing the standard deviation with a certain level of confidence (assuming a normal distribution) @@ -182,11 +174,10 @@ [list_begin arguments] [arg_def list data] - List of raw data values (small sample) [arg_def float confidence] - Confidence level (0.95 or 0.99 for instance) [list_end] [para] - [call [cmd ::math::statistics::t-test-mean] [arg data] [arg est_mean] \ [arg est_stdev] [arg confidence]] Test whether the mean value of a sample is in accordance with the estimated normal distribution with a certain level of confidence. @@ -199,11 +190,10 @@ [arg_def float est_stdev] - Estimated stdev of the distribution [arg_def float confidence] - Confidence level (0.95 or 0.99 for instance) [list_end] [para] - [call [cmd ::math::statistics::test-normal] [arg data] [arg confidence]] Test whether the given data follow a normal distribution with a certain level of confidence. Returns 1 if the data are normally distributed within the level of confidence, returns 0 if not. The underlying test is the Lilliefors @@ -212,11 +202,10 @@ [list_begin arguments] [arg_def list data] - List of raw data values [arg_def float confidence] - Confidence level (one of 0.80, 0.90, 0.95 or 0.99) [list_end] [para] - [call [cmd ::math::statistics::lillieforsFit] [arg data]] Returns the goodness of fit to a normal distribution according to Lilliefors. The higher the number, the more likely the data are indeed normally distributed. The test requires at least [emph five] data @@ -246,11 +235,10 @@ [arg_def list counts] - List of counts for for each interval in histogram [arg_def float confidence] - Confidence level (0.95 or 0.99 for instance) [list_end] [para] - [call [cmd ::math::statistics::autocorr] [arg data]] Return the autocorrelation function as a list of values (assuming equidistance between samples, about 1/2 of the number of raw data) [para] The correlation is determined in such a way that the first value is @@ -259,11 +247,10 @@ returned values) increases [list_begin arguments] [arg_def list data] - Raw data for which the autocorrelation must be determined [list_end] [para] - [call [cmd ::math::statistics::crosscorr] [arg data1] [arg data2]] Return the cross-correlation function as a list of values (assuming equidistance between samples, about 1/2 of the number of raw data) [para] @@ -274,11 +261,10 @@ [arg_def list data1] - First list of data [arg_def list data2] - Second list of data [list_end] [para] - [call [cmd ::math::statistics::mean-histogram-limits] [arg mean] \ [arg stdev] [arg number]] Determine reasonable limits based on mean and standard deviation for a histogram Convenience function - the result is suitable for the histogram function. @@ -288,11 +274,10 @@ [arg_def float stdev] - Standard deviation [arg_def int number] - Number of limits to generate (defaults to 8) [list_end] [para] - [call [cmd ::math::statistics::minmax-histogram-limits] [arg min] \ [arg max] [arg number]] Determine reasonable limits based on a minimum and maximum for a histogram [para] Convenience function - the result is suitable for the histogram function. @@ -300,11 +285,10 @@ [arg_def float min] - Expected minimum [arg_def float max] - Expected maximum [arg_def int number] - Number of limits to generate (defaults to 8) [list_end] [para] - [call [cmd ::math::statistics::linear-model] [arg xdata] \ [arg ydata] [arg intercept]] Determine the coefficients for a linear regression between two series of data (the model: Y = A + B*X). Returns a list of @@ -338,11 +322,10 @@ Significance level of B [list_end] [list_end] [para] - [call [cmd ::math::statistics::linear-residuals] [arg xdata] [arg ydata] \ [arg intercept]] Determine the difference between actual data and predicted from the linear model. [para] @@ -353,11 +336,10 @@ [arg_def list ydata] - List of dependent data to be fitted [arg_def boolean intercept] - (Optional) compute the intercept (1, default) or fit to a line through the origin (0) [list_end] [para] - [call [cmd ::math::statistics::test-2x2] [arg n11] [arg n21] [arg n12] [arg n22]] Determine if two set of samples, each from a binomial distribution, differ significantly or not (implying a different parameter). [para] @@ -369,11 +351,10 @@ [arg_def int n12] - Number of outcomes with the second value from the first sample. [arg_def int n22] - Number of outcomes with the second value from the second sample. [list_end] [para] - [call [cmd ::math::statistics::print-2x2] [arg n11] [arg n21] [arg n12] [arg n22]] Determine if two set of samples, each from a binomial distribution, differ significantly or not (implying a different parameter). [para] Returns a short report, useful in an interactive session. @@ -382,11 +363,10 @@ [arg_def int n21] - Number of outcomes with the first value from the second sample. [arg_def int n12] - Number of outcomes with the second value from the first sample. [arg_def int n22] - Number of outcomes with the second value from the second sample. [list_end] [para] - [call [cmd ::math::statistics::control-xbar] [arg data] [opt nsamples]] Determine the control limits for an xbar chart. The number of data in each subsample defaults to 4. At least 20 subsamples are required. [para] @@ -397,11 +377,10 @@ [arg_def list data] - List of observed data [arg_def int nsamples] - Number of data per subsample [list_end] [para] - [call [cmd ::math::statistics::control-Rchart] [arg data] [opt nsamples]] Determine the control limits for an R chart. The number of data in each subsample (nsamples) defaults to 4. At least 20 subsamples are required. [para] Returns the mean range, the lower limit, the upper limit and the number @@ -411,11 +390,10 @@ [arg_def list data] - List of observed data [arg_def int nsamples] - Number of data per subsample [list_end] [para] - [call [cmd ::math::statistics::test-xbar] [arg control] [arg data]] Determine if the data exceed the control limits for the xbar chart. [para] Returns a list of subsamples (their indices) that indeed violate the limits. @@ -423,11 +401,10 @@ [list_begin arguments] [arg_def list control] - Control limits as returned by the "control-xbar" procedure [arg_def list data] - List of observed data [list_end] [para] - [call [cmd ::math::statistics::test-Rchart] [arg control] [arg data]] Determine if the data exceed the control limits for the R chart. [para] Returns a list of subsamples (their indices) that indeed violate the @@ -532,21 +509,19 @@ variables x1, x2 to xN. [list_end] [para] - [call [cmd ::math::statistics::mv-ols] [arg values]] Carries out an ordinary least squares linear regression for the data points provided. [para] This procedure simply calls ::mvlinreg::wls with the weights set to 1.0, and returns the same information. [list_end] - [emph "Example of the use:"] [example { # Store the value of the unicode value for the "+/-" character set pm "\u00B1" @@ -617,11 +592,10 @@ The following procedures have been implemented: [list_begin definitions] - [call [cmd ::math::statistics::pdf-normal] [arg mean] [arg stdev] [arg value]] Return the probability of a given value for a normal distribution with given mean and standard deviation. [list_begin arguments] @@ -628,11 +602,10 @@ [arg_def float mean] - Mean value of the distribution [arg_def float stdev] - Standard deviation of the distribution [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::pdf-exponential] [arg mean] [arg value]] Return the probability of a given value for an exponential distribution with given mean. @@ -640,11 +613,10 @@ [arg_def float mean] - Mean value of the distribution [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::pdf-uniform] [arg xmin] [arg xmax] [arg value]] Return the probability of a given value for a uniform distribution with given extremes. [list_begin arguments] @@ -651,11 +623,10 @@ [arg_def float xmin] - Minimum value of the distribution [arg_def float xmin] - Maximum value of the distribution [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::pdf-gamma] [arg alpha] [arg beta] [arg value]] Return the probability of a given value for a Gamma distribution with given shape and rate parameters @@ -664,21 +635,19 @@ [arg_def float beta] - Rate parameter [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::pdf-poisson] [arg mu] [arg k]] Return the probability of a given number of occurrences in the same interval (k) for a Poisson distribution with given mean (mu) [list_begin arguments] [arg_def float mu] - Mean number of occurrences [arg_def int k] - Number of occurences [list_end] [para] - [call [cmd ::math::statistics::pdf-chisquare] [arg df] [arg value]] Return the probability of a given value for a chi square distribution with given degrees of freedom @@ -686,21 +655,19 @@ [arg_def float df] - Degrees of freedom [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::pdf-student-t] [arg df] [arg value]] Return the probability of a given value for a Student's t distribution with given degrees of freedom [list_begin arguments] [arg_def float df] - Degrees of freedom [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::pdf-beta] [arg a] [arg b] [arg value]] Return the probability of a given value for a Beta distribution with given shape parameters @@ -708,11 +675,10 @@ [arg_def float a] - First shape parameter [arg_def float b] - First shape parameter [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::cdf-normal] [arg mean] [arg stdev] [arg value]] Return the cumulative probability of a given value for a normal distribution with given mean and standard deviation, that is the probability for values up to the given one. @@ -722,21 +688,19 @@ [arg_def float stdev] - Standard deviation of the distribution [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::cdf-exponential] [arg mean] [arg value]] Return the cumulative probability of a given value for an exponential distribution with given mean. [list_begin arguments] [arg_def float mean] - Mean value of the distribution [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::cdf-uniform] [arg xmin] [arg xmax] [arg value]] Return the cumulative probability of a given value for a uniform distribution with given extremes. @@ -745,20 +709,18 @@ [arg_def float xmin] - Maximum value of the distribution [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::cdf-students-t] [arg degrees] [arg value]] Return the cumulative probability of a given value for a Student's t distribution with given number of degrees. [list_begin arguments] [arg_def int degrees] - Number of degrees of freedom [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::cdf-gamma] [arg alpha] [arg beta] [arg value]] Return the cumulative probability of a given value for a Gamma distribution with given shape and rate parameters @@ -767,21 +729,19 @@ [arg_def float beta] - Rate parameter [arg_def float value] - Value for which the cumulative probability is required [list_end] [para] - [call [cmd ::math::statistics::cdf-poisson] [arg mu] [arg k]] Return the cumulative probability of a given number of occurrences in the same interval (k) for a Poisson distribution with given mean (mu) [list_begin arguments] [arg_def float mu] - Mean number of occurrences [arg_def int k] - Number of occurences [list_end] [para] - [call [cmd ::math::statistics::cdf-beta] [arg a] [arg b] [arg value]] Return the cumulative probability of a given value for a Beta distribution with given shape parameters @@ -790,11 +750,10 @@ [arg_def float b] - First shape parameter [arg_def float value] - Value for which the probability is required [list_end] [para] - [call [cmd ::math::statistics::random-normal] [arg mean] [arg stdev] [arg number]] Return a list of "number" random values satisfying a normal distribution with given mean and standard deviation. [list_begin arguments] [arg_def float mean] - Mean value of the distribution @@ -801,20 +760,18 @@ [arg_def float stdev] - Standard deviation of the distribution [arg_def int number] - Number of values to be returned [list_end] [para] - [call [cmd ::math::statistics::random-exponential] [arg mean] [arg number]] Return a list of "number" random values satisfying an exponential distribution with given mean. [list_begin arguments] [arg_def float mean] - Mean value of the distribution [arg_def int number] - Number of values to be returned [list_end] [para] - [call [cmd ::math::statistics::random-uniform] [arg xmin] [arg xmax] [arg number]] Return a list of "number" random values satisfying a uniform distribution with given extremes. @@ -822,11 +779,10 @@ [arg_def float xmin] - Minimum value of the distribution [arg_def float xmax] - Maximum value of the distribution [arg_def int number] - Number of values to be returned [list_end] [para] - [call [cmd ::math::statistics::random-gamma] [arg alpha] [arg beta] [arg number]] Return a list of "number" random values satisfying a Gamma distribution with given shape and rate parameters @@ -835,11 +791,10 @@ [arg_def float beta] - Rate parameter [arg_def int number] - Number of values to be returned [list_end] [para] - [call [cmd ::math::statistics::random-chisquare] [arg df] [arg number]] Return a list of "number" random values satisfying a chi square distribution with given degrees of freedom [list_begin arguments] @@ -846,21 +801,19 @@ [arg_def float df] - Degrees of freedom [arg_def int number] - Number of values to be returned [list_end] [para] - [call [cmd ::math::statistics::random-student-t] [arg df] [arg number]] Return a list of "number" random values satisfying a Student's t distribution with given degrees of freedom [list_begin arguments] [arg_def float df] - Degrees of freedom [arg_def int number] - Number of values to be returned [list_end] [para] - [call [cmd ::math::statistics::random-beta] [arg a] [arg b] [arg number]] Return a list of "number" random values satisfying a Beta distribution with given shape parameters @@ -869,11 +822,10 @@ [arg_def float b] - Second shape parameter [arg_def int number] - Number of values to be returned [list_end] [para] - [call [cmd ::math::statistics::histogram-uniform] [arg xmin] [arg xmax] [arg limits] [arg number]] Return the expected histogram for a uniform distribution. [list_begin arguments] [arg_def float xmin] - Minimum value of the distribution @@ -880,11 +832,10 @@ [arg_def float xmax] - Maximum value of the distribution [arg_def list limits] - Upper limits for the buckets in the histogram [arg_def int number] - Total number of "observations" in the histogram [list_end] [para] - [call [cmd ::math::statistics::incompleteGamma] [arg x] [arg p] [opt tol]] Evaluate the incomplete Gamma integral [example { @@ -898,11 +849,10 @@ [arg_def float p] - Value of p in the integrand [arg_def float tol] - Required tolerance (default: 1.0e-9) [list_end] [para] - [call [cmd ::math::statistics::incompleteBeta] [arg a] [arg b] [arg x] [opt tol]] Evaluate the incomplete Beta integral [list_begin arguments] [arg_def float a] - First shape parameter @@ -909,11 +859,10 @@ [arg_def float b] - Second shape parameter [arg_def float x] - Value of x (limit of the integral) [arg_def float tol] - Required tolerance (default: 1.0e-9) [list_end] [para] - [list_end] TO DO: more function descriptions to be added [section "DATA MANIPULATION"] @@ -930,11 +879,10 @@ [arg_def list data] - List of data [arg_def string expression] - Logical expression using the variable name [list_end] [para] - [call [cmd ::math::statistics::map] [arg varname] [arg data] [arg expression]] Return a list consisting of the data that are transformed via the expression. [list_begin arguments] @@ -941,11 +889,10 @@ [arg_def string varname] - Name of the variable used in the expression [arg_def list data] - List of data [arg_def string expression] - Expression to be used to transform (map) the data [list_end] [para] - [call [cmd ::math::statistics::samplescount] [arg varname] [arg list] [arg expression]] Return a list consisting of the [term counts] of all data in the sublists of the "list" argument for which the expression is true. @@ -955,15 +902,13 @@ [arg_def string expression] - Logical expression to test the data (defaults to "true"). [list_end] [para] - [call [cmd ::math::statistics::subdivide]] Routine [emph PM] - not implemented yet [para] - [call [cmd ::math::statistics::test-Kruskal-Wallis] [arg confidence] [arg args]] Check if the population medians of two or more groups are equal with a given confidence level, using the Kruskal-Wallis test. @@ -970,11 +915,10 @@ [list_begin arguments] [arg_def float confidence] - Confidence level to be used (0-1) [arg_def list args] - Two or more lists of data [list_end] [para] - [call [cmd ::math::statistics::analyse-Kruskal-Wallis] [arg args]] Compute the statistical parameters for the Kruskal-Wallis test. Returns the Kruskal-Wallis statistic and the probability that that value would occur assuming the medians of the populations are @@ -983,21 +927,19 @@ [list_begin arguments] [arg_def list args] - Two or more lists of data [list_end] [para] - [call [cmd ::math::statistics::group-rank] [arg args]] Rank the groups of data with respect to the complete set. Returns a list consisting of the group ID, the value and the rank (possibly a rational number, in case of ties) for each data item. [list_begin arguments] [arg_def list args] - Two or more lists of data [list_end] [para] - [call [cmd ::math::statistics::test-Wilcoxon] [arg sample_a] [arg sample_b]] Compute the Wilcoxon test statistic to determine if two samples have the same median or not. (The statistic can be regarded as standard normal, if the sample sizes are both larger than 10. Returns the value of this statistic. @@ -1006,21 +948,19 @@ [arg_def list sample_a] - List of data comprising the first sample [arg_def list sample_b] - List of data comprising the second sample [list_end] [para] - [call [cmd ::math::statistics::spearman-rank] [arg sample_a] [arg sample_b]] Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation coefficient. The two samples should have the same number of data. [list_begin arguments] [arg_def list sample_a] - First list of data [arg_def list sample_b] - Second list of data [list_end] [para] - [call [cmd ::math::statistics::spearman-rank-extended] [arg sample_a] [arg sample_b]] Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation coefficient as well as additional data. The two samples should have the same number of data. The procedure returns the correlation coefficient, the number of data pairs used and the @@ -1050,11 +990,10 @@ [arg_def float ymin] - Minimum y value [arg_def float ymax] - Maximum y value [list_end] [para] - [call [cmd ::math::statistics::plot-xydata] [arg canvas] \ [arg xdata] [arg ydata] [arg tag]] Create a simple XY plot in the given canvas - the data are shown as a collection of dots. The tag can be used to manipulate the appearance. @@ -1064,11 +1003,10 @@ [arg_def float xdata] - Series of independent data [arg_def float ydata] - Series of dependent data [arg_def string tag] - Tag to give to the plotted data (defaults to xyplot) [list_end] [para] - [call [cmd ::math::statistics::plot-xyline] [arg canvas] \ [arg xdata] [arg ydata] [arg tag]] Create a simple XY plot in the given canvas - the data are shown as a line through the data points. The tag can be used to @@ -1079,11 +1017,10 @@ [arg_def list ydata] - Series of dependent data [arg_def string tag] - Tag to give to the plotted data (defaults to xyplot) [list_end] [para] - [call [cmd ::math::statistics::plot-tdata] [arg canvas] \ [arg tdata] [arg tag]] Create a simple XY plot in the given canvas - the data are shown as a collection of dots. The horizontal coordinate is equal to the index. The tag can be used to manipulate the appearance. @@ -1093,11 +1030,10 @@ [arg_def widget canvas] - Canvas widget to use [arg_def list tdata] - Series of dependent data [arg_def string tag] - Tag to give to the plotted data (defaults to xyplot) [list_end] [para] - [call [cmd ::math::statistics::plot-tline] [arg canvas] \ [arg tdata] [arg tag]] Create a simple XY plot in the given canvas - the data are shown as a line. See plot-tdata for an explanation. @@ -1279,19 +1215,8 @@ [item] The histograms are not very useful in identifying the nature of the time series - they do not show the periodic nature. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: statistics}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords mathematics "data analysis" statistics] +[vset CATEGORY {math :: statistics}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/math/symdiff.man ================================================================== --- modules/math/symdiff.man +++ modules/math/symdiff.man @@ -1,6 +1,8 @@ [manpage_begin math::calculus::symdiff n 1.0] +[see_also math::calculus] +[see_also math::interpolate] [copyright "2010 by Kevin B. Kenny Redistribution permitted under the terms of the Open\ Publication License "] [moddesc "Symbolic differentiation for Tcl"] [titledesc "Symbolic differentiation for Tcl"] @@ -17,11 +19,11 @@ The [cmd math::calculus::symdiff] package exports the two procedures: [list_begin definitions] [call [cmd math::calculus::symdiff::symdiff] [arg expression] [arg variable]] Differentiates the given [arg expression] with respect to the specified [arg variable]. (See [sectref "Expressions"] below for a discussion of the -subset of Tcl math expressions that are acceptable to +subset of Tcl math expressions that are acceptable to [cmd math::calculus::symdiff].) The result is a Tcl expression that evaluates the derivative. Returns an error if [arg expression] is not a well-formed expression or is not differentiable. [call [cmd math::calculus::jacobian] [arg variableDict]] @@ -28,14 +30,14 @@ Computes the Jacobian of a system of equations. The system is given by the dictionary [arg variableDict], whose keys are the names of variables in the system, and whose values are Tcl expressions giving the values of those variables. (See [sectref "Expressions"] below for a discussion of the subset of Tcl math expressions that are acceptable -to [cmd math::calculus::symdiff]. The result is a list of lists: -the i'th element of the j'th sublist is the partial derivative of +to [cmd math::calculus::symdiff]. The result is a list of lists: +the i'th element of the j'th sublist is the partial derivative of the i'th variable with respect to the j'th variable. Returns an error if -any of the expressions cannot be differentiated, or if [arg variableDict] +any of the expressions cannot be differentiated, or if [arg variableDict] is not a well-formed dictionary. [list_end] [section "Expressions"] The [cmd math::calculus::symdiff] package accepts only a small subset of the expressions that are acceptable to Tcl commands such as [cmd expr] or [cmd if]. @@ -44,11 +46,11 @@ [item]Floating-point constants such as [const 5] or [const 3.14159e+00]. [item]References to Tcl variable using $-substitution. The variable names must consist of alphanumerics and underscores: the [const \$\{...\}] notation is not accepted. [item]Parentheses. -[item]The [const +], [const -], [const *], [const /]. and [const **] +[item]The [const +], [const -], [const *], [const /]. and [const **] operators. [item]Calls to the functions [cmd acos], [cmd asin], [cmd atan], [cmd atan2], [cmd cos], [cmd cosh], [cmd exp], [cmd hypot], [cmd log], [cmd log10], [cmd pow], [cmd sin], [cmd sinh]. [cmd sqrt], [cmd tan], and [cmd tanh]. @@ -61,18 +63,9 @@ ==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d))) math::calculus::symdiff::jacobian {x {$a * $x + $b * $y} y {$c * $x + $d * $y}} ==> {{$a} {$b}} {{$c} {$d}} }] -[section {Bugs, Ideas, Feedback}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {math :: calculus}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also math::calculus math::interpolate] + +[vset CATEGORY {math :: calculus}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/md4/md4.man ================================================================== --- modules/md4/md4.man +++ modules/md4/md4.man @@ -1,6 +1,15 @@ [manpage_begin md4 n 1.0.5] +[see_also md5] +[see_also sha1] +[keywords hashing] +[keywords md4] +[keywords message-digest] +[keywords {rfc 1320}] +[keywords {rfc 1321}] +[keywords {rfc 2104}] +[keywords security] [moddesc {MD4 Message-Digest Algorithm}] [copyright {2003, Pat Thoyts }] [titledesc {MD4 Message-Digest Algorithm}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -37,11 +46,11 @@ return a hexadecimal encoded version of the digest. [para] The data to be hashed can be specified either as a string argument to -the md4 command, or as a filename or a pre-opened channel. If the +the md4 command, or as a filename or a pre-opened channel. If the [arg "-filename"] argument is given then the file is opened, the data read and hashed and the file is closed. If the [arg "-channel"] argument is given then data is read from the channel until the end of file. The channel is not closed. @@ -66,13 +75,13 @@ For the programmer, the MD4 hash can be viewed as a bucket into which one pours data. When you have finished, you extract a value that is derived from the data that was poured into the bucket. The programming interface to the MD4 hash operates on a token (equivalent to the -bucket). You call [cmd MD4Init] to obtain a token and then call +bucket). You call [cmd MD4Init] to obtain a token and then call [cmd MD4Update] as many times as required to add data to the hash. To -release any resources and obtain the hash value, you then call +release any resources and obtain the hash value, you then call [cmd MD4Final]. An equivalent set of functions gives you a keyed digest (HMAC). [list_begin definitions] [call [cmd "::md4::MD4Init"]] @@ -80,15 +89,14 @@ Begins a new MD4 hash. Returns a token ID that must be used for the remaining functions. [call [cmd "::md4::MD4Update"] [arg "token"] [arg "data"]] -Add data to the hash identified by token. Calling +Add data to the hash identified by token. Calling [emph {MD4Update $token "abcd"}] is equivalent to calling -[emph {MD4Update $token "ab"}] followed by +[emph {MD4Update $token "ab"}] followed by [emph {MD4Update $token "cb"}]. See [sectref {EXAMPLES}]. - [call [cmd "::md4::MD4Final"] [arg "token"]] Returns the hash value and releases any resources held by this token. Once this command completes the token will be invalid. The @@ -146,27 +154,14 @@ Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data Security, Inc, April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1321.txt]) [enum] - Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] -[see_also md5 sha1] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph md4] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords md4 hashing message-digest security {rfc 1320} {rfc 1321} {rfc 2104}] +[vset CATEGORY md4] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/md5/md5.man ================================================================== --- modules/md5/md5.man +++ modules/md5/md5.man @@ -1,6 +1,15 @@ [manpage_begin md5 n 2.0.7] +[see_also md4] +[see_also sha1] +[keywords hashing] +[keywords md5] +[keywords message-digest] +[keywords {rfc 1320}] +[keywords {rfc 1321}] +[keywords {rfc 2104}] +[keywords security] [moddesc {MD5 Message-Digest Algorithm}] [copyright {2003, Pat Thoyts }] [titledesc {MD5 Message-Digest Algorithm}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -17,11 +26,11 @@ [para] If you have [package critcl] and have built the [package tcllibc] package then the implementation of the hashing function will be -performed by compiled code. Alternatively if you have either +performed by compiled code. Alternatively if you have either [package cryptkit] or [package Trf] then either of these can be used to accelerate the digest computation. If no suitable compiled package is available then the pure-Tcl implementation wil be used. The programming interface remains the same in all cases. @@ -29,11 +38,11 @@ [emph "Note"] the previous version of this package always returned a hex encoded string. This has been changed to simplify the programming interface and to make this version more compatible with other implementations. To obtain the previous usage, either explicitly -specify package version 1 or use the [arg "-hex"] option to the +specify package version 1 or use the [arg "-hex"] option to the [cmd "md5"] command. [section {COMMANDS}] [list_begin definitions] @@ -48,11 +57,11 @@ return a hexadecimal encoded version of the digest. [para] The data to be hashed can be specified either as a string argument to -the [cmd "md5"] command, or as a filename or a pre-opened channel. If the +the [cmd "md5"] command, or as a filename or a pre-opened channel. If the [arg "-filename"] argument is given then the file is opened, the data read and hashed and the file is closed. If the [arg "-channel"] argument is given then data is read from the channel until the end of file. The channel is not closed. @@ -77,13 +86,13 @@ For the programmer, the MD5 hash can be viewed as a bucket into which one pours data. When you have finished, you extract a value that is derived from the data that was poured into the bucket. The programming interface to the MD5 hash operates on a token (equivalent to the -bucket). You call [cmd "MD5Init"] to obtain a token and then call +bucket). You call [cmd "MD5Init"] to obtain a token and then call [cmd "MD5Update"] as many times as required to add data to the hash. To -release any resources and obtain the hash value, you then call +release any resources and obtain the hash value, you then call [cmd "MD5Final"]. An equivalent set of functions gives you a keyed digest (HMAC). [list_begin definitions] @@ -92,15 +101,14 @@ Begins a new MD5 hash. Returns a token ID that must be used for the remaining functions. [call [cmd "::md5::MD5Update"] [arg "token"] [arg "data"]] -Add data to the hash identified by token. Calling +Add data to the hash identified by token. Calling [emph {MD5Update $token "abcd"}] is equivalent to calling -[emph {MD5Update $token "ab"}] followed by +[emph {MD5Update $token "ab"}] followed by [emph {MD5Update $token "cb"}]. See [sectref {EXAMPLES}]. - [call [cmd "::md5::MD5Final"] [arg "token"]] Returns the hash value and releases any resources held by this token. Once this command completes the token will be invalid. The @@ -153,27 +161,14 @@ [enum] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1320.txt]) [enum] - Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] -[see_also md4 sha1] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph md5] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords md5 hashing message-digest security {rfc 1320} {rfc 1321} {rfc 2104}] +[vset CATEGORY md5] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/md5crypt/md5crypt.man ================================================================== --- modules/md5crypt/md5crypt.man +++ modules/md5crypt/md5crypt.man @@ -1,6 +1,12 @@ [manpage_begin md5crypt n 1.1.0] +[see_also md5] +[keywords hashing] +[keywords md5] +[keywords md5crypt] +[keywords message-digest] +[keywords security] [moddesc {MD5-based password encryption}] [copyright {2003, Pat Thoyts }] [titledesc {MD5-based password encryption}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -72,20 +78,8 @@ [example { % md5crypt::md5crypt password [md5crypt::salt] $1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb. }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph md5crypt] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also md5] -[keywords md5crypt md5 hashing message-digest security] +[vset CATEGORY md5crypt] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/mime/mime.man ================================================================== --- modules/mime/mime.man +++ modules/mime/mime.man @@ -1,7 +1,22 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin mime n 1.5.6] +[see_also ftp] +[see_also http] +[see_also pop3] +[see_also smtp] +[keywords email] +[keywords internet] +[keywords mail] +[keywords mime] +[keywords net] +[keywords {rfc 821}] +[keywords {rfc 822}] +[keywords {rfc 2045}] +[keywords {rfc 2046}] +[keywords {rfc 2049}] +[keywords smtp] [copyright {1999-2000 Marshall T. Rose}] [moddesc {Mime}] [titledesc {Manipulation of MIME body parts}] [category {Text processing}] [require Tcl] @@ -11,11 +26,10 @@ The [package mime] library package provides the commands to create and manipulate MIME body parts. [list_begin definitions] - [call [cmd ::mime::initialize] [opt "[option -canonical] [arg type/subtype] [opt "[option -param] \{[arg {key value}]\}..."] [opt "[option -encoding] [arg value]"] [opt "[option -header] \{[arg {key value}]\}..."]"] "([option -file] [arg name] | [option -string] [arg value] | [option -parts] \{[arg token1] ... [arg tokenN]\})"] This command creates a MIME part and returns a token representing it. @@ -48,11 +62,10 @@ contained in either the [option -file] or the [option -string] option is parsed, dynamically generating subordinates as appropriate. [list_end] - [call [cmd ::mime::finalize] [arg token] [opt "[option -subordinates] [const all] | [const dynamic] | [const none]"]] This command destroys the MIME part represented by [arg token]. It returns an empty string. @@ -61,11 +74,10 @@ If the [option -subordinates] option is present, it specifies which subordinates should also be destroyed. The default value is [const dynamic], destroying all subordinates which were created by [cmd ::mime::initialize] together with the containing body part. - [call [cmd ::mime::getproperty] [arg token] [opt "[arg property] | [option -names]"]] This command returns a string or a list of strings containing the properties of a MIME part. If the command is invoked with the name of @@ -76,11 +88,10 @@ [para] The possible properties are: [list_begin definitions] - [def [const content]] The type/subtype describing the content @@ -101,11 +112,10 @@ The approximate size of the content (unencoded) [list_end] - [call [cmd ::mime::getheader] [arg token] [opt "[arg key] | [option -names]"]] This command returns the header of a MIME part, as a list of strings. [para] @@ -122,11 +132,10 @@ is specified (e.g., "Subject"), the list returned usually contains exactly one string; however, some keys (e.g., "Received") often occur more than once in the header, accordingly the list returned usually contains more than one string. - [call [cmd ::mime::setheader] [arg token] [arg {key value}] [opt "[option -mode] [const write] | [const append] | [const delete]"]] This command writes, appends to, or deletes the [arg value] associated with a [arg key] in the header. It returns a list of strings containing the previous value associated with the key. @@ -134,11 +143,10 @@ [para] The value for [option -mode] is one of: [list_begin definitions] - [def [const write]] The [arg key]/[arg value] is either created or overwritten (the default). @@ -150,11 +158,10 @@ All values associated with the key are removed (the [arg value] parameter is ignored). [list_end] - [call [cmd ::mime::getbody] [arg token] [opt [option -decode]] [opt "[option -command] [arg callback] [opt "[option -blocksize] [arg octets]"]"]] This command returns a string containing the body of the leaf MIME part represented by [arg token] in canonical form. @@ -208,25 +215,22 @@ If the option [option -decode] is present however the command will use the charset information associated with the token to convert the string from its encoding into utf-8 before returning it. - [call [cmd ::mime::copymessage] [arg token] [arg channel]] This command copies the MIME represented by [arg token] part to the specified [arg channel]. The command operates synchronously, and uses fileevent to allow asynchronous operations to proceed independently. It returns an empty string. - [call [cmd ::mime::buildmessage] [arg token]] This command returns the MIME part represented by [arg token] as a string. It is similar to [cmd ::mime::copymessage], only it returns the data as a return string instead of writing to a channel. - [call [cmd ::mime::parseaddress] [arg string]] This command takes a string containing one or more 822-style address specifications and returns a list of serialized arrays, one element @@ -237,11 +241,10 @@ Each serialized array contains the properties below. Note that one or more of these properties may be empty. [list_begin definitions] - [def [const address]] local@domain @@ -285,11 +288,10 @@ 822-style route specification (obsolete) [list_end] - [call [cmd ::mime::parsedatetime] ([arg string] | [option -now]) [arg property]] This command takes a string containing an 822-style date-time specification and returns the specified property as a serialized array. @@ -297,11 +299,10 @@ [para] The list of properties and their ranges are: [list_begin definitions] - [def [const hour]] 0 .. 23 @@ -361,31 +362,27 @@ -720 .. 720 (minutes east of GMT) [list_end] - [call [cmd ::mime::mapencoding] [arg encoding_name]] This commansd maps tcl encodings onto the proper names for their MIME charset type. This is only done for encodings whose charset types were known. The remaining encodings return "" for now. - [call [cmd ::mime::reversemapencoding] [arg charset_type]] This command maps MIME charset types onto tcl encoding names. Those that are unknown return "". - [list_end] - [section {KNOWN BUGS}] [list_begin definitions] -[def {SourceForge Tcllib Bug #447037}] +[def {Tcllib Bug #447037}] This problem affects only people which are using Tcl and Mime on a 64-bit system. The currently recommended fix for this problem is to upgrade to Tcl version 8.4. This version has extended 64 bit support and the bug does not appear anymore. @@ -397,26 +394,12 @@ force a large number of unaffected users to upgrade their Tcl interpreter for no reason. [para] -See [uri http://sourceforge.net/tracker/?func=detail&aid=447037&group_id=12883&atid=112883] -for additional information. +See [uri {/tktview?name=447037} {Ticket 447037}] for additional information. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph mime] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also smtp pop3 ftp http] -[keywords mail email smtp mime internet net] -[keywords {rfc 821} {rfc 822} {rfc 2045} {rfc 2046} {rfc 2049}] +[vset CATEGORY mime] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/mime/smtp.man ================================================================== --- modules/mime/smtp.man +++ modules/mime/smtp.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin smtp n 1.4.5] +[see_also ftp] +[see_also http] +[see_also mime] +[see_also pop3] [copyright {1999-2000 Marshall T. Rose and others}] [moddesc {smtp client}] [titledesc {Client-side tcl implementation of the smtp protocol}] [category Networking] [require Tcl] @@ -60,20 +64,20 @@ commas. [def [option -header]] A list containing two elements, an smtp header and its associated -value (the -header option may occur zero or more times). +value (the -header option may occur zero or more times). [def [option -usetls]] -This package supports the RFC 3207 TLS extension (3) by default provided the +This package supports the RFC 3207 TLS extension (3) by default provided the tls package is available. You can turn this off with this boolean option. [def [option -tlspolicy]] -This option lets you specify a command to be called if an error occurs +This option lets you specify a command to be called if an error occurs during TLS setup. The command is called with the SMTP code and diagnostic message appended. The command should return 'secure' or 'insecure' where insecure will cause the package to continue on the unencrypted channel. Returning 'secure' will cause the socket to be closed and the next server in the [option -servers] list to be tried. @@ -168,27 +172,17 @@ P. Hoffman, "SMTP Service Extension for Secure SMTP over Transport Layer Security", RFC 3207, February 2002. ([uri http://www.rfc-editor.org/rfc/rfc3207.txt]) [enum] - J. Myers, "SMTP Service Extension for Authentication", + J. Myers, "SMTP Service Extension for Authentication", RFC 2554, March 1999. ([uri http://www.rfc-editor.org/rfc/rfc2554.txt]) [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph smtp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also mime pop3 ftp http] +[vset CATEGORY smtp] +[include ../doctools2base/include/feedback.inc] + [keywords mail mail email smtp mime tls \ {rfc 821} {rfc 822} {rfc 2821} {rfc 3207} {rfc 2554} internet net] [manpage_end] Index: modules/multiplexer/multiplexer.man ================================================================== --- modules/multiplexer/multiplexer.man +++ modules/multiplexer/multiplexer.man @@ -1,8 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [comment { $Id: multiplexer.man,v 1.11 2009/01/29 06:16:20 andreas_kupries Exp $ }] [manpage_begin multiplexer n 0.2] +[keywords chat] +[keywords multiplexer] [moddesc {One-to-many communication with sockets.}] [titledesc {One-to-many communication with sockets.}] [category {Programming tools}] [require Tcl 8.2] [require logger] @@ -54,11 +56,11 @@ [list_end] [call [cmd \${multiplexer_instance}::AddFilter] [arg cmdprefix]] Command to add a filter for data that passes through the multiplexer -instance. +instance. The registered [arg cmdprefix] is called when data arrives at a multiplexer instance. If there is more than one filter command registered at the instance they will be called in the order of registristation, and each filter will get the result of the preceding @@ -75,11 +77,10 @@ result. The last three arguments contain information about the client which sent the data to filter: The channel connecting us to the client, its ip-address, and its ip-port. [list_end] - [call [cmd \${multiplexer_instance}::AddAccessFilter] [arg cmdprefix]] Command to add an access filter. @@ -100,11 +101,10 @@ connected to the instance: The channel connecting us to the client, its ip-address, and its ip-port. [list_end] - [call [cmd \${multiplexer_instance}::AddExitFilter] [arg cmdprefix]] Adds filter to be run when client socket generates an EOF condition. The registered [arg cmdprefix] is called when a client socket of the @@ -123,19 +123,8 @@ ip-port. [list_end] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph multiplexer] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords multiplexer chat] +[vset CATEGORY multiplexer] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/namespacex/namespacex.man ================================================================== --- modules/namespacex/namespacex.man +++ modules/namespacex/namespacex.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin namespacex n 0.1] +[keywords {extended namespace}] +[keywords info] +[keywords {namespace unknown}] +[keywords {namespace utilities}] +[keywords {state (de)serialization}] +[keywords {unknown hooking}] +[keywords utilities] [copyright {200? Neil Madden (http://wiki.tcl.tk/12790)}] [copyright {200? Various (http://wiki.tcl.tk/1489)}] [copyright {2010 Documentation, Andreas Kupries}] [moddesc {Namespace utility commands}] [titledesc {Namespace utility commands}] @@ -19,30 +26,26 @@ [call [cmd {::namespacex hook add}] [opt [arg namespace]] [arg cmdprefix]] [call [cmd {::namespacex hook proc}] [opt [arg namespace]] [arg arguments] [arg body]] [call [cmd {::namespacex hook on}] [opt [arg namespace]] [arg guardcmdprefix] [arg actioncmdprefix]] [call [cmd {::namespacex hook next}] [arg arg]...] - [call [cmd {::namespacex info allchildren}] [arg namespace]] This command returns a list containing the names of all child namespaces in the specified [arg namespace] and its children. The names are all fully qualified. - [call [cmd {::namespacex info allvars}] [arg namespace]] This command returns a list containing the names of all variables in the specified [arg namespace] and its children. The names are all relative to [arg namespace], and [emph not] fully qualified. - [call [cmd {::namespacex info vars}] [arg namespace] [opt [arg pattern]]] This command returns a list containing the names of all variables in the specified [arg namespace]. - [call [cmd {::namespacex state get}] [arg namespace]] This command returns a dictionary holding the names and values of all variables in the specified [arg namespace] and its child namespaces. @@ -49,28 +52,22 @@ [para] Note that the names are all relative to [arg namespace], and [emph not] fully qualified. - [call [cmd {::namespacex state set}] [arg namespace] [arg dict]] This command takes a dictionary holding the names and values for a set of variables and replaces the current state of the specified [arg namespace] and its child namespaces with this state. The result of the command is the empty string. - [call [cmd {::namespacex state drop}] [arg namespace]] This command unsets all variables in the specified [arg namespace] and its child namespaces. The result of the command is the empty string. [list_end] - -[keywords {extended namespace} {namespace utilities} utilities {namespace unknown}] -[keywords {unknown hooking} {state (de)serialization} info] [manpage_end] - Index: modules/ncgi/ncgi.man ================================================================== --- modules/ncgi/ncgi.man +++ modules/ncgi/ncgi.man @@ -1,6 +1,11 @@ [manpage_begin ncgi n 1.4.2] +[see_also html] +[keywords CGI] +[keywords cookie] +[keywords form] +[keywords html] [comment {-*- tcl -*- doctools manpage}] [moddesc {CGI Support}] [titledesc {Procedures to manipulate CGI values.}] [category {CGI programming}] [require Tcl 8.4] @@ -39,66 +44,57 @@ [para] The complete set of procedures is described below. - [list_begin definitions] [call [cmd ::ncgi::cookie] [arg cookie]] Return a list of values for [arg cookie], if any. It is possible that more than one cookie with the same name can be present, so this procedure returns a list. - [call [cmd ::ncgi::decode] [arg str]] Decode strings in www-url-encoding, which represents special characters with a %xx sequence, where xx is the character code in hex. - [call [cmd ::ncgi::empty] [arg name]] Returns 1 if the CGI variable [arg name] is not present or has the empty string as its value. - [call [cmd ::ncgi::exists] [arg name]] The return value is a boolean. It returns [const 0] if the CGI variable [arg name] is not present, and [const 1] otherwise. - [call [cmd ::ncgi::encode] [arg string]] Encode [arg string] into www-url-encoded format. - [call [cmd ::ncgi::header] [opt [arg type]] [arg args]] Output the CGI header to standard output. This emits a Content-Type: header and additional headers based on [arg args], which is a list of header names and header values. The [arg type] defaults to "text/html". - [call [cmd ::ncgi::import] [arg cginame] [opt [arg tclname]]] This creates a variable in the current scope with the value of the CGI variable [arg cginame]. The name of the variable is [arg tclname], or [arg cginame] if [arg tclname] is empty (default). - [call [cmd ::ncgi::importAll] [arg args]] This imports several CGI variables as Tcl variables. If [arg args] is empty, then every CGI value is imported. Otherwise each CGI variable listed in [arg args] is imported. - -[call [cmd ::ncgi::importFile] [arg cmd] [arg cginame] [opt [arg filename]]] +[call [cmd ::ncgi::importFile] [arg cmd] [arg cginame] [opt [arg filename]]] This provides information about an uploaded file from a form input field of type [const file] with name [arg cginame]. [arg cmd] can be one of [option -server] [option -client], [option -type] or [option -data]. @@ -123,18 +119,16 @@ if supplied) and returns the name of the file. The caller is responsible for deleting this file after use. [list_end] - [call [cmd ::ncgi::input] [opt [arg fakeinput]] [opt [arg fakecookie]]] This reads and decodes the CGI values from the environment. It restricts repeated form values to have a trailing "List" in their name. The CGI values are obtained later with the [cmd ::ncgi::value] procedure. - [call [cmd ::ncgi::multipart] [arg {type query}]] This procedure parses a multipart/form-data [arg query]. This is used by [cmd ::ncgi::nvlist] and not normally called directly. It returns @@ -152,64 +146,56 @@ describe the multipart data. The values are a nested list structure that has some descriptive information first, and the actual form value second. The descriptive information is list of header names and values that describe the content. - [call [cmd ::ncgi::nvlist]] This returns all the query data as a name, value list. In the case of multipart/form-data, the values are structured as described in [cmd ::ncgi::multipart]. - [call [cmd ::ncgi::names]] This returns all names found in the query data, as a list. [cmd ::ncgi::multipart]. - [call [cmd ::ncgi::parse]] This reads and decodes the CGI values from the environment. The CGI values are obtained later with the [cmd ::ncgi::value] procedure. IF a CGI value is repeated, then you should use [cmd ::ncgi::valueList] to get the complete list of values. - [call [cmd ::ncgi::parseMimeValue] [arg value]] This decodes the Content-Type and other MIME headers that have the form of "primary value; param=val; p2=v2" It returns a list, where the first element is the primary value, and the second element is a list of parameter names and values. - [call [cmd ::ncgi::query]] This returns the raw query data. - [call [cmd ::ncgi::redirect] [arg url]] Generate a response that causes a 302 redirect by the Web server. The [arg url] is the new URL that is the target of the redirect. The URL will be qualified with the current server and current directory, if necessary, to convert it into a full URL. - [call [cmd ::ncgi::reset] [arg {query type}]] Set the query data and Content-Type for the current CGI session. This is used by the test suite and by Web servers to initialize the ncgi module so it does not try to read standard input or use environment variables to get its data. If neither [arg query] or [arg type] are specified, then the [package ncgi] module will look in the standard CGI environment for its data. - [call [cmd ::ncgi::setCookie] [arg args]] Set a cookie value that will be returned as part of the reply. This must be done before [cmd ::ncgi::header] or [cmd ::ncgi::redirect] is @@ -224,25 +210,22 @@ [def "[option -expires] [arg date]"] [def "[option -path] [arg {path restriction}]"] [def "[option -domain] [arg {domain restriction}]"] [list_end] - [call [cmd ::ncgi::setDefaultValue] [arg {key defvalue}]] Set a CGI value if it does not already exists. This affects future calls to [cmd ::ncgi::value] (but not future calls to [cmd ::ncgi::nvlist]). If the CGI value already is present, then this procedure has no side effects. - [call [cmd ::ncgi::setDefaultValueList] [arg {key defvaluelist}]] Like [cmd ::ncgi::setDefaultValue] except that the value already has list structure to represent multiple checkboxes or a multi-selection. - [call [cmd ::ncgi::setValue] [arg {key value}]] Set a CGI value, overriding whatever was present in the CGI environment already. This affects future calls to [cmd ::ncgi::value] @@ -251,24 +234,21 @@ [call [cmd ::ncgi::setValueList] [arg {key valuelist}]] Like [cmd ::ncgi::setValue] except that the value already has list structure to represent multiple checkboxes or a multi-selection. - [call [cmd ::ncgi::type]] Returns the Content-Type of the current CGI values. - [call [cmd ::ncgi::urlStub] [opt [arg url]]] Returns the current URL, but without the protocol, server, and port. If [arg url] is specified, then it defines the URL for the current session. That value will be returned by future calls to [cmd ::ncgi::urlStub] - [call [cmd ::ncgi::value] [arg key] [opt [arg default]]] Return the CGI value identified by [arg key]. If the CGI value is not present, then the [arg default] value is returned instead. This value @@ -283,11 +263,10 @@ [arg key] must end in "List" (e.g., "skuList"). In the case of multipart/form-data, this procedure just returns the value of the form element. If you want the meta-data associated with each form value, then use [cmd ::ncgi::valueList]. - [call [cmd ::ncgi::valueList] [arg key] [opt [arg default]]] Like [cmd ::ncgi::value], but this always returns a list of values (even if there is only one value). In the case of @@ -326,20 +305,8 @@ close $fh }] [para] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ncgi] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also html] -[keywords CGI form html cookie] +[vset CATEGORY ncgi] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/nmea/nmea.man ================================================================== --- modules/nmea/nmea.man +++ modules/nmea/nmea.man @@ -1,6 +1,8 @@ [manpage_begin nmea n 1.0.0] +[keywords gps] +[keywords nmea] [copyright {2006-2009, Aaron Faupell }] [moddesc {NMEA protocol implementation}] [titledesc {Process NMEA data}] [category Networking] [require Tcl 8.4] @@ -55,11 +57,11 @@ [call [cmd ::nmea::log] [opt file]] Starts or stops input logging. If a file name is specified then all NMEA data recieved on the open port will be logged to the [opt file] in append mode. If file is an empty string then any logging will be stopped. If no file is specified then returns a boolean value indicating -if logging is currently enabled. Data written to the port by [cmd write], +if logging is currently enabled. Data written to the port by [cmd write], data read from files, or input made using [cmd input], is not logged. [call [cmd ::nmea::checksum] [arg data]] Returns the checksum of the supplied data. @@ -67,11 +69,11 @@ If there is a currently open port, this command will write the specified sentence and data to the port in proper NMEA checksummed format. [call [cmd ::nmea::event] [arg setence] [opt command]] Registers a handler proc for a given NMEA [arg sentence]. There may be at most one handler per -sentence, any existing handler is replaced. +sentence, any existing handler is replaced. If no command is specified, returns the name of the current handler for the given [arg setence] or an empty string if none exists. In addition to the incoming sentences there are 2 builtin types, EOF and DEFAULT. The handler for the DEFAULT setence is invoked if there is not a specific handler for that sentence. The EOF handler is invoked when End Of File is reached on the open file or port. [para] @@ -93,19 +95,8 @@ } }] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph nmea] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords nmea gps] +[vset CATEGORY nmea] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/nns/nns_auto.man ================================================================== --- modules/nns/nns_auto.man +++ modules/nns/nns_auto.man @@ -1,15 +1,19 @@ [manpage_begin nameserv::auto n 0.3] +[see_also nameserv(n)] +[keywords automatic] +[keywords client] +[keywords {name service}] +[keywords reconnect] +[keywords restore] [copyright {2007-2008 Andreas Kupries }] [moddesc {Name service facility}] [titledesc {Name service facility, Client Extension}] [category Networking] [require Tcl 8.4] [require nameserv::auto [opt 0.3]] [require nameserv] -[keywords {name service} client restore reconnect automatic] -[see_also nameserv(n)] [description] Please read the document [term {Name service facility, introduction}] first. @@ -30,11 +34,10 @@ names there is one important limitation to such restoration: It is possible that a name of this client was bound by a different client while the connection was gone. Such names are fully lost, and the best the package can and will do is to inform the user of this. - [section API] The user-visible API is mainly identical the API of [package nameserv] and is therefore not described here. Please read the documentation of [package nameserv]. @@ -41,11 +44,10 @@ [para] The differences are explained in the sections [sectref OPTIONS] and [sectref EVENTS]. - [section OPTIONS] This package supports all the option of package [package nameserv], and one more. The additional option allows the user to specifies the @@ -57,11 +59,10 @@ The value of this option is an integer value > 0 which specifies the interval to wait between attempts to restore a lost connection, in milliseconds. The default value is [const 1000], i.e. one second. [list_end] - [section EVENTS] This package generates all of the events of package [package nameserv], and two more. Both events are generated for the tag [term nameserv]. @@ -90,11 +91,10 @@ The event has no detail information. [list_end] - [section DESIGN] The package is implemented on top of the regular nameservice client, i.e. package [package nameserv]. It detects the loss of the connection by listening for [term lost-connection] events, on the tag @@ -112,18 +112,8 @@ Another loss of the connection, be it during or after re-entering the remembered information simply restarts the timer and subsequent reconnection attempts. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph nameserv] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY nameserv] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/nns/nns_client.man ================================================================== --- modules/nns/nns_client.man +++ modules/nns/nns_client.man @@ -1,17 +1,18 @@ [manpage_begin nameserv n 0.4.2] +[see_also nameserv::common(n)] +[see_also nameserv::server(n)] +[keywords client] +[keywords {name service}] [copyright {2007-2008 Andreas Kupries }] [moddesc {Name service facility}] [titledesc {Name service facility, Client}] [category Networking] [require Tcl 8.4] [require nameserv [opt 0.4.2]] [require comm] [require logger] -[keywords {name service} client] -[see_also nameserv::common(n)] -[see_also nameserv::server(n)] [description] Please read [term {Name service facility, introduction}] first. [para] @@ -55,18 +56,16 @@ [para] Note that the name service, and thwerefore this command, will throw an error if the chosen name is already registered. - [call [cmd ::nameserv::release]] Invoking this command releases all names (and their data) registered by all previous calls to [cmd ::nameserv::bind] of this client. Note that the name service will run this command implicitly when it loses the connection to this client. - [call [cmd ::nameserv::search] [opt [option -async]|[option -continuous]] [opt [arg pattern]]] This command searches the name service for all registered names matching the specified glob-[arg pattern]. If not specified the @@ -104,29 +103,25 @@ [para] For more information about this object see section [sectref {ASYNCHRONOUS AND CONTINUOUS SEARCHES}]. - [call [cmd ::nameserv::protocol]] This command returns the highest version of the name service protocol supported by the package. - [call [cmd ::nameserv::server_protocol]] This command returns the highest version of the name service protocol supported by the name service the client is currently connected to. - [call [cmd ::nameserv::server_features]] This command returns a list containing the names of the features of the name service protocol which are supported by the name service the client is currently connected to. - [call [cmd ::nameserv::cget] [option -option]] This command returns the currently configured value for the specified [option -option]. The list of supported options and their meaning can @@ -136,19 +131,17 @@ In this form the command returns a dictionary of all supported options, and their current values. The list of supported options and their meaning can be found in section [sectref OPTIONS]. - [call [cmd ::nameserv::configure] [option -option]] In this form the command is an alias for "[cmd ::nameserv::cget] [option -option]]". The list of supported options and their meaning can be found in section [sectref OPTIONS]. - [call [cmd ::nameserv::configure] "[option -option] [arg value]..."] In this form the command is used to configure one or more of the supported options. At least one option has to be specified, and each @@ -172,11 +165,10 @@ [cmd_def search] [cmd_def server_protocol] [cmd_def server_features] [list_end] [list_end] - [section {CONNECTION HANDLING}] The client automatically connects to the service when one of the commands below is run for the first time, or whenever one of the @@ -207,11 +199,10 @@ will be a string describing why the connection was lost. This string is supplied by the underlying communication package, i.e. [package comm]. - [section OPTIONS] The options supported by the client are for the specification of which name service to contact, i.e. of the location of the name service. @@ -223,21 +214,19 @@ This option specifies the host name service to contact is running on, either by [arg name], or by [arg ipaddress]. The initial default is [const localhost], i.e. it is expected to contact a name service running on the same host as the application using this package. - [opt_def -port [arg number]] This option specifies the port the name service to contact is listening on. It has to be a positive integer number (> 0) not greater than 65536 (unsigned short). The initial default is the number returned by the command [cmd ::nameserv::common::port], as provided by the package [package ::nameserv::common]. [list_end] - [section {ASYNCHRONOUS AND CONTINUOUS SEARCHES}] Asynchronous and continuous searches are invoked by using either option [option -async] or [option -continuous] as argument to the @@ -296,11 +285,10 @@ [call [cmd \$result] [method destroy]] Destroys the object and cancels any continuous monitoring of the service the object may have had active. - [call [cmd \$result] [method filled]] The result is a boolean value indicating whether the search result has already arrived ([const True]), or not ([const False]). @@ -326,11 +314,10 @@ them at [term bind]-time. [list_end] [list_end] - [section HISTORY] [list_begin definitions] [def 0.3.1] Fixed SF Bug 1954771. @@ -344,17 +331,8 @@ [def 0.1] Initial implementation of the client. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph nameserv] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY nameserv] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/nns/nns_common.man ================================================================== --- modules/nns/nns_common.man +++ modules/nns/nns_common.man @@ -1,15 +1,17 @@ [manpage_begin nameserv::common n 0.1] +[see_also nameserv::client(n)] +[see_also nameserv::server(n)] +[keywords client] +[keywords {name service}] +[keywords server] [copyright {2007-2008 Andreas Kupries }] [moddesc {Name service facility}] [titledesc {Name service facility, shared definitions}] [category Networking] [require Tcl 8] [require nameserv::common [opt 0.1]] -[keywords {name service} client server] -[see_also nameserv::client(n)] -[see_also nameserv::server(n)] [description] Please read [term {Name service facility, introduction}] first. [para] @@ -38,17 +40,8 @@ port a nameservice server will listen on, and a name service client will try to connect to. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph nameserv] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY nameserv] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/nns/nns_intro.man ================================================================== --- modules/nns/nns_intro.man +++ modules/nns/nns_intro.man @@ -1,7 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin nns_intro n 1.0] +[see_also nameserv(n)] +[see_also nameserv::auto(n)] +[see_also nameserv::common(n)] +[see_also nameserv::protocol(n)] +[see_also nameserv::server(n)] +[see_also nnsd(n)] +[see_also nss(n)] +[keywords client] +[keywords {name service}] +[keywords server] [copyright {2008 Andreas Kupries }] [moddesc {Name service facility}] [titledesc {Name service facility, introduction}] [category Networking] [description] @@ -22,11 +32,10 @@ [para] Tcllib provides 2 applications and 4 packages which are working together and provide access to the facility at different levels. - [section Applications] The application [syscmd nnsd] provides a simple name server which can be run by anybody anywhere on their system, as they see fit. @@ -63,11 +72,10 @@ [para] Both clients use the [package nameserv::auto] package to automatically hande the loss and restoration of the connection to the server. - [section Packages] The two main packages implementing the service are [package nameserv] and [package nameserv::server], i.e. client and server. The latter has @@ -113,28 +121,8 @@ Developers wishing to modify and/or extend or to just understand the internals of the nameservice facility however are strongly advised to read it. - -[section {Bugs, Ideas, Feedback}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph nameserv] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -Please also report any ideas for enhancements you may have. - - -[keywords {name service} client server] -[see_also nnsd(n)] -[see_also nss(n)] -[see_also nameserv(n)] -[see_also nameserv::server(n)] -[see_also nameserv::common(n)] -[see_also nameserv::auto(n)] -[see_also nameserv::protocol(n)] +[vset CATEGORY nameserv] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/nns/nns_protocol.man ================================================================== --- modules/nns/nns_protocol.man +++ modules/nns/nns_protocol.man @@ -1,14 +1,16 @@ [manpage_begin nameserv::protocol n 0.1] +[see_also comm_wire(n)] +[see_also nameserv(n)] +[see_also nameserv::server(n)] +[keywords comm] +[keywords {name service}] +[keywords protocol] [copyright {2007-2008 Andreas Kupries }] [moddesc {Name service facility}] [titledesc {Name service facility, client/server protocol}] [category Networking] -[keywords comm {name service} protocol] -[see_also nameserv::server(n)] -[see_also nameserv(n)] -[see_also comm_wire(n)] [description] The packages [package nameserv::server], [package nameserv], and [package nameserv::common] provide a simple unprotected name service facility for use in small trusted environments. @@ -20,11 +22,10 @@ [para] This document contains the specification of the network protocol which is used by client and server to talk to each other, enabling implementations of the same protocol in other languages. - [section {Nano Name Service Protocol Version 1}] This protocol defines the basic set of messages to be supported by a name service, also called the [term Core] feature. @@ -49,11 +50,10 @@ The protocol is synchronous. I.e. for each message sent a response is expected, and has to be generated. All messages are sent by the client. The server does not sent messages, only responses to messages. - [subsection {Message Layer}] [list_begin definitions] [call [method Bind] [arg name] [arg data]] @@ -70,18 +70,16 @@ [call [method Release]] The client sends this message to unregister all names it is known under at the service. The response has to be an empty string, always. - [call [method Search] [arg pattern]] The client sends this message to search the service for names matching the glob-[arg pattern]. The response has to be a dictionary containing the matching names as keys, and mapping them to the data associated with it at [method Bind]-time. - [call [method ProtocolVersion]] The client sends this message to query the service for the highest version of the name service protocol it supports. The response has to @@ -89,11 +87,10 @@ [para] Servers supporting only [term {Nano Name Service Protocol Version 1}] have to return [const 1]. - [call [method ProtocolFeatures]] The client sends this message to query the service for the features of the name service protocol it supports. The response has to be a @@ -103,12 +100,10 @@ Servers supporting only [term {Nano Name Service Protocol Version 1}] have to return [const {{Core}}]. [list_end] - - [section {Nano Name Service Protocol Extension: Continuous Search}] This protocol defines an extended set of messages to be supported by a name service, also called the [term Search/Continuous] feature. This @@ -158,11 +153,10 @@ [call [method Search/Continuous/Stop] [arg tag]] The client sends this message to stop the continuous search identified by the [arg tag]. - [call [method Search/Continuous/Change] [arg tag] [method add]|[method remove] [arg response]] This message is sent by the service to clients with active continuous searches to transfer found changes. The first such message for a new continuous search has to contains the current set of matching entries. @@ -181,19 +175,8 @@ The argument coming before the response tells the client whether the names in the response were added or removed from the service. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph nameserv] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY nameserv] +[include ../doctools2base/include/feedback.inc] [manpage_end] - Index: modules/nns/nns_server.man ================================================================== --- modules/nns/nns_server.man +++ modules/nns/nns_server.man @@ -1,18 +1,19 @@ [manpage_begin nameserv::server n 0.3.2] +[see_also nameserv::client(n)] +[see_also nameserv::common(n)] +[keywords {name service}] +[keywords server] [copyright {2007-2008 Andreas Kupries }] [moddesc {Name service facility}] [titledesc {Name service facility, Server}] [category Networking] [require Tcl 8.4] [require nameserv::server [opt 0.3.2]] [require comm] [require interp] [require logger] -[keywords {name service} server] -[see_also nameserv::common(n)] -[see_also nameserv::client(n)] [description] Please read [term {Name service facility, introduction}] first. [para] @@ -32,11 +33,10 @@ [para] This server supports the [term Core] protocol feature, and since version 0.3 the [term Search/Continuous] feature as well. - [section API] The package exports five commands, as specified below: [list_begin definitions] @@ -51,24 +51,21 @@ Note that any incoming requests will only be handled if the application the server is part of does enter an event loop after this command has been run. - [call [cmd ::nameserv::server::stop]] Invoking this command stops the server and releases all information it had. Existing connections are shut down, and no new connections will be accepted any longer. The result of the command is the empty string. - [call [cmd ::nameserv::server::active?]] This command returns a boolean value indicating the state of the server. The result will be [const true] if the server is active, i.e. has been started, and [const false] otherwise. - [call [cmd ::nameserv::server::cget] [option -option]] This command returns the currently configured value for the specified [option -option]. The list of supported options and their meaning can @@ -78,19 +75,17 @@ In this form the command returns a dictionary of all supported options, and their current values. The list of supported options and their meaning can be found in section [sectref OPTIONS]. - [call [cmd ::nameserv::server::configure] [option -option]] In this form the command is an alias for "[cmd ::nameserv::server::cget] [option -option]]". The list of supported options and their meaning can be found in section [sectref OPTIONS]. - [call [cmd ::nameserv::server::configure] "[option -option] [arg value]..."] In this form the command is used to configure one or more of the supported options. At least one option has to be specified, and each @@ -104,11 +99,10 @@ This form can be used only if the server is not active, i.e. has not been started yet, or has been stopped. While the server is active it cannot be reconfigured. [list_end] - [section OPTIONS] The options supported by the server are for the specification of the TCP port to listen on, and whether to accept non-local connections or @@ -131,11 +125,10 @@ returned by the command [cmd ::nameserv::server::common::port], as provided by the package [package ::nameserv::server::common]. [list_end] - [section HISTORY] [list_begin definitions] [def 0.3] Extended the server with the ability to perform asynchronous and continuous searches. @@ -145,18 +138,8 @@ [def 0.1] Initial implementation of the server. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph nameserv] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY nameserv] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/nntp/nntp.man ================================================================== --- modules/nntp/nntp.man +++ modules/nntp/nntp.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin nntp n 1.5.1] +[keywords news] +[keywords nntp] +[keywords nntpclient] +[keywords {rfc 977}] +[keywords {rfc 1036}] [moddesc {Tcl NNTP Client Library}] [titledesc {Tcl client for the NNTP protocol}] [category Networking] [require Tcl 8.2] [require nntp [opt 0.2.1]] @@ -80,11 +85,10 @@ mostly binary and retrieving it as text will corrupt the information. [para] See package [package yencode] for both encoder and decoder of such data. - [call [arg nntpName] [method date]] Query the server for the servers current date. The date is returned in the format [emph YYYYMMDDHHMMSS]. @@ -246,11 +250,10 @@ All messages between [arg msgid1] and [arg msgid2] (including [arg msgid1] and [arg msgid2]) are queried. [list_end] - [call [arg nntpName] [method xover] [opt [arg range]]] Returns header information for the current message or for a range of messages from the current group. The information is returned in a tcl list where each element is of the form: @@ -259,11 +262,10 @@ }] If [arg range] is not specified or is "" then the current message is queried. The [arg range] argument can be in any of the following forms: [list_begin definitions] - [def [const {""}]] The current message is queried. @@ -276,11 +278,10 @@ All messages between [arg msgid1] and [arg msgid2] (including [arg msgid1] and [arg msgid2]) are queried. [list_end] - [call [arg nntpName] [method xpat] [arg field] [arg range] [opt [arg pattern_list]]] Returns the specified header field value for a specified message or for a list of messages from the current group where the messages match the @@ -316,33 +317,22 @@ A bigger example for posting a single article. [para] [example { - package require nntp - set n [nntp::nntp NNTP_SERVER] - $n post "From: USER@DOMAIN.EXT (USER_FULL) - Path: COMPUTERNAME!USERNAME - Newsgroups: alt.test - Subject: Tcl test post -ignore - Message-ID: <[pid][clock seconds] - @COMPUTERNAME> - Date: [clock format [clock seconds] -format "%a, %d % - b %y %H:%M:%S GMT" -gmt true] - - Test message body" + package require nntp + set n [nntp::nntp NNTP_SERVER] + $n post "From: USER@DOMAIN.EXT (USER_FULL) + Path: COMPUTERNAME!USERNAME + Newsgroups: alt.test + Subject: Tcl test post -ignore + Message-ID: <[pid][clock seconds] + @COMPUTERNAME> + Date: [clock format [clock seconds] -format "%a, %d % + b %y %H:%M:%S GMT" -gmt true] + + Test message body" }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph nntp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords news nntp nntpclient {rfc 1036} {rfc 977}] +[vset CATEGORY nntp] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ntp/ntp_time.man ================================================================== --- modules/ntp/ntp_time.man +++ modules/ntp/ntp_time.man @@ -1,6 +1,12 @@ [manpage_begin ntp_time n 1.2.1] +[see_also ntp] +[keywords NTP] +[keywords {rfc 868}] +[keywords {rfc 2030}] +[keywords SNTP] +[keywords time] [copyright {2002, Pat Thoyts }] [moddesc {Network Time Facilities}] [titledesc {Tcl Time Service Client}] [category Networking] [require Tcl 8.0] @@ -8,11 +14,11 @@ [description] [para] This package implements a client for the RFC 868 TIME protocol ([uri http://www.rfc-editor.org/rfc/rfc868.txt]) and also a minimal -client for the RFC 2030 Simple Network Time Protocol +client for the RFC 2030 Simple Network Time Protocol ([uri http://www.rfc-editor.org/rfc/rfc2030.txt]). RFC 868 returns the time in seconds since 1 January 1900 to either tcp or udp clients. RFC 2030 also gives this time but also provides a fractional part which is not used in this client. @@ -30,11 +36,11 @@ release all resources. The default port is [const 37]. [call [cmd ::time::getsntp] [opt [arg "options"]] [arg timeserver] [opt [arg "port"]]] Get the time from an SNTP server. This accepts exactly the same -arguments as [cmd ::time::gettime] except that the default port is +arguments as [cmd ::time::gettime] except that the default port is [const 123]. The result is a token as per [cmd ::time::gettime] and should be handled in the same way. [para] Note that it is unlikely that any SNTP server will reply using tcp so you will require the [package tcludp] or the [package ceptcl] @@ -91,11 +97,10 @@ [call [cmd ::time::cleanup] [arg token]] Remove all state variables associated with the request. [list_end] - [example { % set tok [::time::gettime ntp2a.mcc.ac.uk] % set t [::time::unixtime $tok] % ::time::cleanup $tok }] @@ -116,23 +121,11 @@ time::cleanup $token } time::getsntp -command on_time pool.ntp.org }] -[see_also ntp] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ntp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords time NTP {rfc 868} SNTP {rfc 2030}] +[vset CATEGORY ntp] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ooutil/ooutil.man ================================================================== --- modules/ooutil/ooutil.man +++ modules/ooutil/ooutil.man @@ -1,17 +1,24 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin oo::util n 1.1] +[see_also snit(n)] +[keywords callback] +[keywords {class methods}] +[keywords {class variables}] +[keywords {command prefix}] +[keywords currying] +[keywords {method reference}] +[keywords {my method}] +[keywords singleton] +[keywords TclOO] [copyright {2011-2013 Andreas Kupries, BSD licensed}] [moddesc {Utility commands for TclOO}] [titledesc {Utility commands for TclOO}] [category Utility] [require Tcl 8.5] [require TclOO] [require oo::util [opt 1.1]] -[keywords TclOO callback {my method} {command prefix} currying {method reference}] -[keywords {class methods} {class variables} singleton] -[see_also snit(n)] [description] [para] This package provides a convenience command for the easy specification of instance methods as callback commands, like timers, file events, Tk @@ -29,11 +36,10 @@ object we are in, with the provided arguments, and any others supplied at the time of actual invokation. [para] Note: The command is equivalent to and named after the command provided by the OO package [package snit] for the same purpose. - [comment {- - -- --- ----- -------- ------------- ---------------------}] [call [cmd classmethod] [arg name] [arg arguments] [arg body]] This command is available within class definitions. It takes a method @@ -55,11 +61,10 @@ # ====== # which will write # ====== # ::Table called with arguments: foo bar }] - [comment {- - -- --- ----- -------- ------------- ---------------------}] [call [cmd classvariable] [opt [arg arg]...]] This command is available within instance methods. It takes a series @@ -125,11 +130,10 @@ }] The main use of this command is expected to be in instance constructors, for convenience, or to set up some methods for use in a mini DSL. - [comment {- - -- --- ----- -------- ------------- ---------------------}] [call [cmd ooutil::singleton] [opt [arg arg]...]] This command is a meta-class, i.e. a variant of the builtin [cmd oo::class] which ensures that it creates only a single @@ -153,17 +157,8 @@ [list_end] [section AUTHORS] Donal Fellows, Andreas Kupries -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph oo::util] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY oo::util] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/otp/otp.man ================================================================== --- modules/otp/otp.man +++ modules/otp/otp.man @@ -1,6 +1,16 @@ [manpage_begin otp n 1.0.0] +[see_also md4] +[see_also md5] +[see_also ripemd160] +[see_also SASL] +[see_also sha1] +[keywords hashing] +[keywords message-digest] +[keywords password] +[keywords {rfc 2289}] +[keywords security] [moddesc {RFC 2289 A One-Time Password System}] [copyright {2006, Pat Thoyts }] [titledesc {One-Time Passwords}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -17,11 +27,11 @@ mechanism for authenticating users. [para] In this implementation we provide support for four algorithms that are -included in the tcllib distribution: MD5 (2), MD4 (3), RIPE-MD160 (4) +included in the tcllib distribution: MD5 (2), MD4 (3), RIPE-MD160 (4) and SHA-1 (5). [section {COMMANDS}] [list_begin definitions] @@ -49,11 +59,10 @@ SOON ARAB BURG LIMB FILE WAD % otp::otp-md5 -hex -count 99 -seed host67821 "My Secret Pass Phrase" e249b58257c80087 }] - [section {REFERENCES}] [list_begin enumerated] [enum] @@ -68,11 +77,11 @@ [enum] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1320.txt]) [enum] - H. Dobbertin, A. Bosselaers, B. Preneel, + H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened version of RIPEMD" [uri http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf] [enum] "Secure Hash Standard", National Institute of Standards @@ -79,20 +88,8 @@ and Technology, U.S. Department Of Commerce, April 1995. ([uri http://www.itl.nist.gov/fipspubs/fip180-1.htm]) [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph otp] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also md4 md5 sha1 ripemd160 SASL] -[keywords password hashing message-digest security {rfc 2289}] +[vset CATEGORY otp] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/page/page_intro.man ================================================================== --- modules/page/page_intro.man +++ modules/page/page_intro.man @@ -1,12 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin page_intro n 1.0] +[keywords page] +[keywords {parser generator}] +[keywords {text processing}] [copyright {2007 Andreas Kupries }] [moddesc {Parser generator tools}] [titledesc {page introduction}] [category {Page Parser Generator}] -[keywords page {parser generator} {text processing}] [description] [para] [term page] (short for [emph {parser generator}]) stands for a set of related packages which help in the construction of parser generators, @@ -26,15 +28,8 @@ The packages implementing the plugins are not documented as regular packages, as they cannot be loaded into a general interpreter, like tclsh, without extensive preparation of the interpreter. Preparation which is done for them by the plugin manager. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph page] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - +[vset CATEGORY page] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/page/page_pluginmgr.man ================================================================== --- modules/page/page_pluginmgr.man +++ modules/page/page_pluginmgr.man @@ -1,12 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin page_pluginmgr n 1.0] +[keywords page] +[keywords {parser generator}] +[keywords {text processing}] [copyright {2007 Andreas Kupries }] [moddesc {Parser generator tools}] [titledesc {page plugin manager}] [category {Page Parser Generator}] -[keywords page {parser generator} {text processing}] [require page::pluginmgr [opt 0.2]] [require fileutil] [description] [para] @@ -64,11 +66,10 @@ The optional argument [arg from] and [arg to] can be used by the caller to indicate the location (or range) in the input where the reported problem occured. Each is a list containing two elements, the line and the column in the input, in this order. - [call [cmd ::page::pluginmgr::log] [arg cmd]] This command defines a log callback command to be used by loaded plugins for the reporting of internal errors, warnings, and general information. Specifying the empty string as callback disables logging. @@ -79,11 +80,10 @@ or follow the same API as such. [para] The command returns the empty string as its result. - [call [cmd ::page::pluginmgr::configuration] [arg name]] This command loads the named configuration plugin, retrieves the options encoded in it, and then immediately unloads it again. @@ -103,11 +103,10 @@ [para] The result of the command is the list of options retrieved. - [call [cmd ::page::pluginmgr::reader] [arg name]] This command loads the named reader plugin and initializes it. The result of the command is a list of options the plugin understands. @@ -119,11 +118,10 @@ [para] See section [sectref {READER PLUGIN API}] for the API expected of reader plugins. - [call [cmd ::page::pluginmgr::rconfigure] [arg dict]] This commands configures the loaded reader plugin. The options and their values are provided as a Tcl dictionary. The result of the @@ -789,23 +787,14 @@ the environment. Describe the predefined features. }] - [section FEATURES] The plugin manager currently checks the plugins for only one feature, [const timeable]. A plugin supporting this feature is assumed to be able to collect timing statistics on request. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph page] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - +[vset CATEGORY page] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/page/page_util_flow.man ================================================================== --- modules/page/page_util_flow.man +++ modules/page/page_util_flow.man @@ -1,15 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin page_util_flow n 1.0] +[keywords dataflow] +[keywords {graph walking}] +[keywords page] +[keywords {parser generator}] +[keywords {text processing}] +[keywords {tree walking}] [copyright {2007 Andreas Kupries }] [moddesc {Parser generator tools}] [titledesc {page dataflow/treewalker utility}] [category {Page Parser Generator}] [require page::util::flow [opt 0.1]] [require snit] -[keywords page dataflow {tree walking} {graph walking}] -[keywords {parser generator} {text processing}] [description] [para] This package provides a single utility command for easy dataflow based manipulation of arbitrary data structures, especially abstract syntax @@ -85,15 +89,8 @@ This is the variadic arguments form of the method [method visitl], see above. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph page] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - +[vset CATEGORY page] +[include ../doctools2base/include/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 @@ -1,15 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin page_util_norm_lemon n 1.0] +[keywords {graph walking}] +[keywords lemon] +[keywords normalization] +[keywords page] +[keywords {parser generator}] +[keywords {text processing}] +[keywords {tree walking}] [copyright {2007 Andreas Kupries }] [moddesc {Parser generator tools}] [titledesc {page AST normalization, LEMON}] [category {Page Parser Generator}] [require page::util::norm_lemon [opt 0.1]] [require snit] -[keywords page lemon normalization {tree walking} {graph walking}] -[keywords {parser generator} {text processing}] [description] [para] This package provides a single utility command which takes an AST for a lemon grammar and normalizes it in various ways. The result @@ -39,15 +44,8 @@ The exact operations performed are left undocumented for the moment. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph page] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - +[vset CATEGORY page] +[include ../doctools2base/include/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 @@ -1,15 +1,20 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin page_util_norm_peg n 1.0] +[keywords {graph walking}] +[keywords normalization] +[keywords page] +[keywords {parser generator}] +[keywords PEG] +[keywords {text processing}] +[keywords {tree walking}] [copyright {2007 Andreas Kupries }] [moddesc {Parser generator tools}] [titledesc {page AST normalization, PEG}] [category {Page Parser Generator}] [require page::util::norm_peg [opt 0.1]] [require snit] -[keywords page PEG normalization {tree walking} {graph walking}] -[keywords {parser generator} {text processing}] [description] [para] This package provides a single utility command which takes an AST for a parsing expression grammar and normalizes it in various ways. The result @@ -38,11 +43,11 @@ [para] The following operations are performd [list_begin enum] -[enum] +[enum] The data for all terminals is stored in their grandparental nodes. The terminal nodes and their parents are removed. Type information is dropped. [enum] @@ -93,15 +98,8 @@ to avoid unnecessary work later. [list_end] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph page] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - +[vset CATEGORY page] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/page/page_util_peg.man ================================================================== --- modules/page/page_util_peg.man +++ modules/page/page_util_peg.man @@ -1,15 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin page_util_peg n 1.0] +[keywords page] +[keywords {parser generator}] +[keywords {parsing expression grammar}] +[keywords PEG] +[keywords {text processing}] +[keywords transformation] [copyright {2007 Andreas Kupries }] [moddesc {Parser generator tools}] [titledesc {page PEG transformation utilities}] [category {Page Parser Generator}] [require page::util::peg [opt 0.1]] [require snit] -[keywords page {parsing expression grammar} {parser generator} {text processing}] -[keywords PEG transformation] [description] [para] This package provides a few common operations to PEG transformations. They assume a [term {Normalized PE Grammar Tree}] as input, see the @@ -97,15 +101,8 @@ See the package [package grammar::peg] for the exact syntax of [arg pe]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph page] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - +[vset CATEGORY page] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/page/page_util_quote.man ================================================================== --- modules/page/page_util_quote.man +++ modules/page/page_util_quote.man @@ -1,14 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin page_util_quote n 1.0] +[keywords page] +[keywords {parser generator}] +[keywords quoting] +[keywords {text processing}] [copyright {2007 Andreas Kupries }] [moddesc {Parser generator tools}] [titledesc {page character quoting utilities}] [category {Page Parser Generator}] [require page::util::quote [opt 0.1]] [require snit] -[keywords page quoting {parser generator} {text processing}] [description] [para] This package provides a few utility commands to convert characters into various forms. @@ -52,15 +55,8 @@ used within a Tcl comment. The string is returned as the result of this command. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, will undoubtedly contain bugs and other problems. - -Please report such in the category [emph page] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have. - +[vset CATEGORY page] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/pki/pki.man ================================================================== --- modules/pki/pki.man +++ modules/pki/pki.man @@ -1,7 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin pki n 0.6] +[see_also aes(n)] +[see_also blowfish(n)] +[see_also des(n)] +[see_also md5(n)] +[see_also sha1(n)] +[keywords cipher] +[keywords {data integrity}] +[keywords encryption] +[keywords {public key cipher}] +[keywords rsa] +[keywords security] [copyright {2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries}] [moddesc {public key encryption}] [titledesc {Implementation of the public key cipher}] [category {Hashes, checksums, and encryption}] [require Tcl 8.5] @@ -69,11 +80,10 @@ [list_begin enumerated] [enum] "openssl rsautl -encrypt" == "::pki::encrypt -binary -pub" [enum] "openssl rsautl -sign" == "::pki::encrypt -binary -priv" [list_end] - [call [cmd "::pki::decrypt"] \ [opt [arg "-binary"]] \ [opt [arg "-hex"]] \ [opt [arg "-unpad"]] \ [opt [arg "-nounpad"]] \ @@ -87,12 +97,10 @@ [para] Mapping to OpenSSL's [syscmd openssl] application: [list_begin enumerated] [enum] "openssl rsautl -decrypt" == "::pki::decrypt -binary -priv" [enum] "openssl rsautl -verify" == "::pki::decrypt -binary -pub" [list_end] - - [call [cmd ::pki::sign] [arg input] [arg key] [opt [arg algo]]] Digitally sign message [arg input] using the private [arg key]. If [arg algo] is ommited "sha1" is assumed. Possible values for [arg algo] include @@ -143,21 +151,19 @@ [comment { What is the default for password? What choices for password has the user ? }] - [call [cmd ::pki::x509::parse_cert] [arg cert]] Convert an X.509 certificate to a usable (public) key, i.e. one which can be used as argument for [cmd ::pki:encrypt], [cmd ::pki::decrypt], and [cmd ::pki::verify]. The [arg cert] argument can be either PEM or DER encoded. - [call [cmd ::pki::rsa::generate] [arg bitlength] [opt [arg exponent]]] Generate a new RSA key pair, the parts of which can be used as argument for @@ -176,12 +182,10 @@ -- 65537 (0x10001) What choices for exponent has the user ? -- Any value, but it should be chosen wisely. This is the "RSA exponent" and small values may represent a security risk. }] - - [call [cmd ::pki::x509::verify_cert] [arg cert] [arg trustedcerts] [opt [arg intermediatecerts]]] Verify that a trust can be found between the certificate specified in the [arg cert] argument and one of the certificates specified in the list of certificates in the [arg trustedcerts] argument. (Eventually the @@ -188,12 +192,10 @@ chain can be through untrusted certificates listed in the [arg intermediatecerts] argument, but this is currently unimplemented). The certificates specified in the [arg cert] and [arg trustedcerts] option should be parsed (from [cmd ::pki::x509::parse_cert]). - - [call [cmd ::pki::x509::validate_cert] \ [arg cert] \ [opt "[option -sign_message] [arg dn_of_signer]"] \ [opt "[option -encrypt_message] [arg dn_of_signer]"] \ @@ -213,12 +215,10 @@ the [arg cert] argument can sign. The [arg ca_depth] argument is used to indicate at which depth the verification should be done at. Some certificates are limited to how far down the chain they can be used to verify a given certificate. - - [call [cmd ::pki::pkcs::create_csr] [arg keylist] [arg namelist] [opt [arg encodePem]] [opt [arg algo]]] Generate a certificate signing request from a key pair specified in the [arg keylist] argument. @@ -232,18 +232,14 @@ The [arg algo] argument specifies the hashing algorithm we should use to sign this certificate signing request with. The default is "sha1". Other possible values include "md5" and "sha256". - - [call [cmd ::pki::pkcs::parse_csr] [arg csr]] Parse a Certificate Signing Request. The [arg csr] argument can be either PEM or DER encoded. - - [call [cmd ::pki::x509::create_cert] [arg signreqlist] [arg cakeylist] [arg serial_number] [arg notBefore] [arg notAfter] [arg isCA] [arg extensions] [opt [arg encodePem]] [opt [arg algo]]] Sign a signing request (usually from [cmd ::pki::pkcs::create_csr] or [cmd ::pki::pkcs::parse_csr]) with a Certificate Authority (CA) certificate. @@ -251,11 +247,11 @@ The [arg signreqlist] argument should be the parsed signing request. The [arg cakeylist] argument should be the parsed CA certificate. The [arg serial_number] argument should be a serial number unique to -this certificate from this certificate authority. +this certificate from this certificate authority. The [arg notBefore] and [arg notAfter] arguments should contain the time before and after which (respectively) the certificate should be considered invalid. The time should be encoded as something [cmd "clock format"] will accept (i.e., the results of [cmd "clock seconds"] @@ -274,17 +270,15 @@ argument to this extension (and any extension) whether or not the validator should reject the certificate as invalid if it does not understand the extension (if set to "true") or should ignore the extension (if set to "false"). The [arg allowCA] argument is used to specify as a boolean value whether or not we can be used a certificate -authority (CA). The [arg caDepth] argument indicates how many children +authority (CA). The [arg caDepth] argument indicates how many children CAs can be children of this CA in a depth-wise fashion. A value of "0" for the [arg caDepth] argument means that this CA cannot sign a CA certificate and have the result be valid. A value of "-1" indicates infinite depth. - - [list_end] [section "EXAMPLES"] @@ -298,23 +292,11 @@ [list_begin enumerated] [enum] [list_end] -[see_also aes(n) des(n) md5(n) sha1(n) blowfish(n)] - [section AUTHORS] Roy Keene -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph rsa] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords rsa cipher {public key cipher} security encryption {data integrity}] +[vset CATEGORY rsa] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/pluginmgr/pluginmgr.man ================================================================== --- modules/pluginmgr/pluginmgr.man +++ modules/pluginmgr/pluginmgr.man @@ -1,15 +1,16 @@ [comment {-*- tcl -*- paths manpage}] [manpage_begin pluginmgr n 0.3] +[keywords {plugin management}] +[keywords {plugin search}] [copyright {2005 Andreas Kupries }] [moddesc {Plugin management}] [titledesc {Manage a plugin}] [category {Programming tools}] [require Tcl 8.4] [require pluginmgr [opt 0.3]] [description] -[keywords {plugin management} {plugin search}] This package provides commands and objects for the generic management of plugins which can be loaded into an application. [para] @@ -71,11 +72,10 @@ [para] The options and their values coming after the name of the object are used to set the initial configuration of the mamager object, specifying the applicable plugins and their API. - [call [cmd ::pluginmgr::paths] [arg objectName] [arg name]...] This utility command adds a set of paths to the specified object, based on the given [arg name]s. @@ -165,11 +165,10 @@ path ~/.doctools/idx/plugin }] [list_end] - [subsection {OBJECT COMMAND}] All commands created by the command [cmd ::pluginmgr] (See section [sectref {PACKAGE COMMANDS}]) have the following general form and may be used to invoke various operations on their plugin manager object. @@ -181,11 +180,10 @@ The method [method method] and its [arg arg]'uments determine the exact behavior of the command. See section [sectref {OBJECT METHODS}] for the detailed specifications. [list_end] - [subsection {OBJECT METHODS}] [list_begin definitions] @@ -198,23 +196,20 @@ current object has a plugin loaded then this plugin and all associated state is moved to the generated clone and the current object is reset into the base state (no plugin loaded). In this manner a configured plugin manager is also a factory for loaded plugins. - [call [arg objectName] [method configure]] The method returns a list of all known options and their current values when called without any arguments. - [call [arg objectName] [method configure] [arg option]] The method behaves like the method [method cget] when called with a single argument and returns the value of the option specified by said argument. - [call [arg objectName] [method configure] [option -option] [arg value]...] The method reconfigures the specified [option option]s of the object, setting them to the associated [arg value]s, when called with an even @@ -222,11 +217,10 @@ [para] The legal options are described in the section [sectref {OBJECT CONFIGURATION}]. - [call [arg objectName] [method cget] [option -option]] This method expects a legal configuration option as argument and will return the current value of that option for the object the method was @@ -235,15 +229,13 @@ [para] The legal configuration options are described in section [sectref {OBJECT CONFIGURATION}]. - [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method do] [arg arg]...] This method interprets its list of arguments as the words of a command and invokes this command in the execution context of the plugin. @@ -251,24 +243,21 @@ The result of the invoked command is made the result of the method. The call will fail with an error if no valid plugin has been loaded into the manager object. - [call [arg objectName] [method interpreter]] This method returns the handle of the safe interpreter the current plugin is loaded into. An empty string as return value signals that the manager currently has no valid plugin loaded. - [call [arg objectName] [method plugin]] This method returns the name of the plugin currently loaded. An empty string as return value signals that the manager currently has no valid plugin loaded. - [call [arg objectName] [method load] [arg string]] This method loads, validates, and initializes a named plugin into the manager object. @@ -317,41 +306,36 @@ A previously loaded plugin is discarded, but only if the new plugin was found and sucessfully validated and initialized. Note that there will be no intereference between old and new plugin as both will be put into separate safe interpreters. - [call [arg objectName] [method unload]] This method unloads the currently loaded plugin. It returns the empty string. The call will be silently ignored if no plugin is loaded at all. - [call [arg objectName] [method list]] This method uses the contents of the option [option -pattern] to find all packages which can be plugins under the purview of this manager object. It translates their names into plugin names and returns a list containing them. - [call [arg objectName] [method path] [arg path]] This methods adds the specified [arg path] to the list of additional package paths to look at when searching for a plugin. It returns the empty string. Duplicate paths are ignored, i.e. each path is added only once. Paths are made absolute, but are not normalized. - [call [arg objectName] [method paths]] This method returns a list containing all additional paths which have been added to the plugin manager object since its creation. [list_end] - [subsection {OBJECT CONFIGURATION}] All plugin manager objects understand the following configuration options: @@ -369,20 +353,18 @@ This option has no default, except if option [option -name] was set. It has to be set before attempting to load a plugin, either directly, or through option [option -name]. - [opt_def -api [arg list]] The value of this option is a list of command names, and any plugin loaded has to provide these commands. Names which are not fully qualified are considered to be rooted in the global namespace. If empty no expectations are made on the plugin. The default value is the empty list. - [opt_def -check [arg cmdprefix]] The value of this option is interpreted as a command prefix. @@ -401,11 +383,10 @@ [para] The default value is the empty list, which causes the manager object to suppress the call and to assume the candidate plugin passes. - [opt_def -cmds [arg dict]] The value of this option is a dictionary. It specifies the commands which will be made available to the plugin (as keys), and the trusted commands in the environment which implement them (as values). @@ -413,18 +394,16 @@ The trusted commands will be executed in the interpreter specified by the option [option -cmdip]. The default value is the empty dictionary. - [opt_def -cmdip [arg ipspec]] The value of this option is the path of the interpreter where the trusted commands given to the plugin will be executed in. The default is the empty string, referring to the current interpreter. - [opt_def -setup [arg cmdprefix]] The value of this option is interpreted as a command prefix. @@ -441,18 +420,8 @@ define commands, packages, etc. a chosen plugin may need while being loaded. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph pluginmgr] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY pluginmgr] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/png/png.man ================================================================== --- modules/png/png.man +++ modules/png/png.man @@ -1,6 +1,10 @@ [manpage_begin png n 0.1.2] +[keywords comment] +[keywords image] +[keywords png] +[keywords timestamp] [copyright {2004, Code: Aaron Faupell }] [copyright {2004, Doc: Andreas Kupries }] [moddesc {Image manipulation}] [titledesc {PNG querying and manipulation of meta data}] [category {File formats}] @@ -66,29 +70,26 @@ header is invalid. For information on interpreting the values for the returned properties see [uri http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html]. - [call [cmd ::png::getTimestamp] [arg file]] Returns the epoch time if a timestamp chunk is found in the PNG image contained in the [arg file], otherwise returns the empty string. Does not attempt to verify the checksum of the timestamp chunk. Throws an error if the [arg file] is not a valid PNG image. - [call [cmd ::png::setTimestamp] [arg file] [arg time]] Writes a new timestamp to the [arg file], either replacing the old timestamp, or adding one just before the data chunks if there was no previous timestamp. [arg time] is the new time in the gmt epoch format. Throws an error if [arg file] is not a valid PNG image. - [call [cmd ::png::getComments] [arg file]] Currently supports only uncompressed comments. Does not attempt to verify the checksums of the comment chunks. Returns a list where each @@ -98,27 +99,24 @@ elements: the human readable keyword, the language identifier, the translated keyword, and the unicode text data. Throws an error if [arg file] is not a valid PNG image. - [call [cmd ::png::removeComments] [arg file]] Removes all comments from the PNG image in [arg file]. Beware - This uses memory equal to the file size minus comments, to hold the intermediate result. Throws an error if [arg file] is not a valid PNG image. - [call [cmd ::png::addComment] [arg file] [arg keyword] [arg text]] Adds a plain [arg text] comment to the PNG image in [arg file], just before the first data chunk. Will throw an error if no data chunk is found. [arg keyword] has to be less than 80 characters long to conform to the PNG specification. - [call [cmd ::png::addComment] [arg file] [arg keyword] [arg lang] [arg keyword2] [arg text]] Adds a unicode (international) comment to the PNG image in [arg file], just before the first data chunk. Will throw an error if no data chunk @@ -136,19 +134,8 @@ Takes a list of scanlines in the Tk_GetColor format and writes the represented image to [arg file]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph png] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords png image comment timestamp] +[vset CATEGORY png] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/pop3/pop3.man ================================================================== --- modules/pop3/pop3.man +++ modules/pop3/pop3.man @@ -1,10 +1,17 @@ [manpage_begin pop3 n 1.9] +[keywords email] +[keywords mail] +[keywords pop] +[keywords pop3] +[keywords {rfc 1939}] +[keywords secure] +[keywords ssl] +[keywords tls] [comment {-*- tcl -*- doctools manpage}] [moddesc {Tcl POP3 Client Library}] [titledesc {Tcl client for POP3 email protocol}] -[keywords mail email pop pop3 {rfc 1939} ssl tls secure] [category Networking] [require Tcl 8.4] [require pop3 [opt 1.9]] [description] @@ -76,20 +83,18 @@ [opt_def -tls-callback stls-callback-command] This option allows the user to overide the [cmd tls::callback] used during the [const -stls] SSL/TLS handshake. See the TLS manual for details on how -to implement this callback. +to implement this callback. [list_end] - [call [cmd ::pop3::config] [arg chan]] Returns the configuration of the pop3 connection identified by the channel handle [arg chan] as a serialized array. - [call [cmd ::pop3::status] [arg chan]] Query the server for the status of the mail spool. The status is returned as a list containing two elements, the first is the number of @@ -126,11 +131,10 @@ It should also be noted that the system checks upon the configured mode and falls back to the slower modes if the above assumptions are not true. - [call [cmd ::pop3::delete] [arg {chan startIndex}] [opt [arg endIndex]]] Delete a range of messages from the server. If the [arg endIndex] is not specified, only one message will be deleted. Note, the indices are not reordered on the server, so if you delete message 1, then the @@ -153,11 +157,11 @@ to the value 1. [def [const next]] The message immediately following the last message read, see -[cmd ::pop3::last]. +[cmd ::pop3::last]. [def [const end]] The most recent message in the spool (the end of the spool). This is useful to retrieve only the most recent message. @@ -190,31 +194,29 @@ [call [cmd ::pop3::list] [arg chan] [opt [arg msg]]] Returns the scan listing of the mailbox. If parameter [arg msg] is given, then the listing only for that message is returned. - [call [cmd ::pop3::top] [arg chan] [arg msg] [arg n] ] - Optional POP3 command, not all servers may support this. [cmd ::pop3::top] retrieves headers of a message, specified by parameter [arg msg], and number of [arg n] lines from the message body. [call [cmd ::pop3::uidl] [arg chan] [opt [arg msg]]] -Optional POP3 command, not all servers may support this. +Optional POP3 command, not all servers may support this. [cmd ::pop3::uidl] returns the uid listing of the mailbox. If the parameter [arg msg] is specified, then the listing only for that message is returned. [call [cmd ::pop3::capa] [arg chan]] -Optional POP3 command, not all servers may support this. +Optional POP3 command, not all servers may support this. [cmd ::pop3::capa] returns a list of the capabilities of the server. TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities. See IETF RFC 2449. @@ -223,11 +225,10 @@ Gracefully close the connect after sending a POP3 QUIT command down the socket. [list_end] - [section {Secure mail transfer}] A pop3 connection can be secured with SSL/TLS by requiring the package [package TLS] and then using either the option [option -socketcmd] or @@ -263,10 +264,9 @@ pop3::open -stls 1 \\ $thehost $theuser $thepassword ... }] - [vset CATEGORY pop3] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/pop3d/pop3d.man ================================================================== --- modules/pop3d/pop3d.man +++ modules/pop3d/pop3d.man @@ -1,13 +1,20 @@ [comment {-*- tcl -*-}] [manpage_begin pop3d n 1.1.0] +[keywords internet] +[keywords network] +[keywords pop3] +[keywords protocol] +[keywords {rfc 1939}] +[keywords secure] +[keywords ssl] +[keywords tls] [copyright {2002-2009 Andreas Kupries }] [copyright {2005 Reinhard Max }] [moddesc {Tcl POP3 Server Package}] [titledesc {Tcl POP3 server implementation}] [category Networking] -[keywords pop3 internet network protocol {rfc 1939} ssl tls secure] [require Tcl 8.3] [require pop3d [opt 1.1.0]] [description] [para] @@ -251,11 +258,10 @@ ... pop3d::new S -socket tls::socket ... }] - [section References] [list_begin enumerated] [enum] [uri http://www.rfc-editor.org/rfc/rfc1939.txt {RFC 1939}] Index: modules/pop3d/pop3d_dbox.man ================================================================== --- modules/pop3d/pop3d_dbox.man +++ modules/pop3d/pop3d_dbox.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*-}] [manpage_begin pop3d::dbox n 1.0.2] +[keywords internet] +[keywords network] +[keywords pop3] +[keywords protocol] +[keywords {rfc 822}] [copyright {2002 Andreas Kupries }] [moddesc {Tcl POP3 Server Package}] [titledesc {Simple mailbox database for pop3d}] [category Networking] [require Tcl 8.3] @@ -123,11 +128,10 @@ or this call will fail. If [method stat] was not called before this call, [method size] will assume that there are zero messages in the mailbox. - [call [arg dbName] [method dele] [arg {mbox msgList}]] Deletes the messages whose numeric ids are contained in the [arg msgList] from the mailbox specified via [arg mbox]. @@ -136,11 +140,10 @@ The numeric ids in [arg msgList] have to be in the range "1 ... [lb][arg dbName] [method stat][rb]" or this call will fail. If [method stat] was not called before this call, [method dele] will assume that there are zero messages in the mailbox. - [call [arg storageCmd] [method get] [arg mbox] [arg msgId]] Returns a handle for the specified message. This handle is a mime token following the interface described in the documentation of @@ -152,22 +155,10 @@ [lb][arg dbName] [method stat][rb]" or this call will fail. If [method stat] was not called before this call, [method get] will assume that there are zero messages in the mailbox. - [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph pop3d] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords pop3 internet network protocol {rfc 822}] +[vset CATEGORY pop3d] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/pop3d/pop3d_udb.man ================================================================== --- modules/pop3d/pop3d_udb.man +++ modules/pop3d/pop3d_udb.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*-}] [manpage_begin pop3d::udb n 1.0.1] +[keywords internet] +[keywords network] +[keywords pop3] +[keywords protocol] [copyright {2002 Andreas Kupries }] [moddesc {Tcl POP3 Server Package}] [titledesc {Simple user database for pop3d}] [category Networking] [require Tcl 8.2] @@ -19,11 +23,10 @@ Objects created by this package can be directly used in the authentication callback of pop3 servers following the same interface as servers created by the package [package pop3d]. [para] - [list_begin definitions] [call [cmd ::pop3d::udb::new] [opt [arg dbName]]] @@ -100,22 +103,10 @@ signature as the method [method add]. The path of the [arg file] is remembered internally so that it can be used in the next call of [arg dbName] [method save] without an argument. - [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph pop3d] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords pop3 internet network protocol] +[vset CATEGORY pop3d] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/profiler/profiler.man ================================================================== --- modules/profiler/profiler.man +++ modules/profiler/profiler.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin profiler n 0.3] +[keywords performance] +[keywords profile] +[keywords speed] [moddesc {Tcl Profiler}] [titledesc {Tcl source code profiler}] [category {Programming tools}] [require Tcl 8.3] [require profiler [opt 0.3]] @@ -15,11 +18,10 @@ Profiling is initiated via the [cmd ::profiler::init] command. [section COMMANDS] [list_begin definitions] - [call [cmd ::profiler::init]] Initiate profiling. All procedures created after this command is called will be profiled. To profile an entire application, this @@ -65,14 +67,13 @@ Sum of the time spent in descendants of [arg functionName]. [def [const averageDescendantTime]] -Average time spent in descendants of [arg functionName]. +Average time spent in descendants of [arg functionName]. [list_end] - [call [cmd ::profiler::print] [opt [arg pattern]]] Print profiling information for all functions matching [arg pattern]. If no pattern is specified, information about all functions will be @@ -113,19 +114,8 @@ sublist consists of a function name and the value of [arg key] for that function. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph profiler] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords profile performance speed] +[vset CATEGORY profiler] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/pt/pt_astree.man ================================================================== --- modules/pt/pt_astree.man +++ modules/pt/pt_astree.man @@ -39,11 +39,10 @@ [para] For the specification of serializations see the section [sectref {AST serialization format}]. - [call [cmd ::pt::ast] [method verify-as-canonical] \ [arg serial]] This command verifies that the content of [arg serial] is a valid [term canonical] serialization of an abstract syntax tree and will @@ -52,11 +51,10 @@ [para] For the specification of canonical serializations see the section [sectref {AST serialization format}]. - [call [cmd ::pt::ast] [method canonicalize] [arg serial]] This command assumes that the content of [arg serial] is a valid [term regular] serialization of an abstract syntax and will throw an @@ -71,11 +69,10 @@ [para] For the specification of regular and canonical serializations see the section [sectref {AST serialization format}]. - [call [cmd ::pt::ast] [method print] [arg serial]] This command assumes that the argument [arg serial] contains a valid serialization of an abstract syntax tree and returns a string containing that tree in a human readable form. @@ -87,11 +84,10 @@ [para] For the specification of serializations see the section [sectref {AST serialization format}]. - [call [cmd ::pt::ast] [method bottomup] [arg cmdprefix] [arg ast]] This command walks the abstract syntax tree [arg ast] from the bottom up to the root, invoking the command prefix [arg cmdprefix] for each @@ -117,11 +113,10 @@ elements are the results of the command prefix invoked for the children of this node. [list_end] - [call [cmd ::pt::ast] [method topdown] [arg cmdprefix] [arg pe]] This command walks the abstract syntax tree [arg ast] from the root down to the leaves, invoking the command prefix [arg cmdprefix] for each node. This implies that the children of a node N are handled @@ -134,11 +129,10 @@ [para] The result returned by the command prefix is [emph ignored]. - [call [cmd ::pt::ast] [method equal] \ [arg seriala] [arg serialb]] This command tests the two sbstract syntax trees [arg seriala] and [arg serialb] for structural equality. The result of the command is a @@ -148,28 +142,25 @@ [para] String equality is usable only if we can assume that the two trees are pure Tcl lists. - [call [cmd ::pt::ast] [method terminal] [arg loc]] This command command constructs the ast for a terminal node refering to the position [arg loc] in the input, and returns it as the result of the command. - [call [cmd ::pt::ast] [method nonterminal] [arg s] \ [arg start] [arg end] [opt [arg child]...]] This command command constructs the ast for a nonterminal node refering to the symbol [arg s] covering the range of positions [arg start] to [arg end] in the input, and the set of child nodes [arg child] ..., from left right. The latter may be empty. The constructed node is returned as the result of the command. - [list_end] [include include/serial/ast.inc] [include include/feedback.inc] [manpage_end] Index: modules/pt/pt_from_api.man ================================================================== --- modules/pt/pt_from_api.man +++ modules/pt/pt_from_api.man @@ -55,11 +55,10 @@ converting the input text. [list_end][comment {-- api command signatures --}] [list_end][comment {-- converter rules --}] - [section {Plugin API}] Any (grammar) import plugin has to follow the rules set out below: [list_begin enumerated][comment {-- plugin rules --}] @@ -134,11 +133,10 @@ for a [const notread] error in more detail. [list_end][comment {-- result list elements --}] [list_end][comment {-- include-file signature --}] - [enum] A plugin has to provide a single command, in the global namespace, with the signature shown below. Plugins are allowed to provide more commands of their own, but not less, and they may not provide different semantics for the standardized command. @@ -169,11 +167,10 @@ [enum] A single usage cycle of a plugin consists of an invokation of the command [cmd import]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end][comment {-- plugin rules --}] - [section Usage] To use a converter do Index: modules/pt/pt_introduction.man ================================================================== --- modules/pt/pt_introduction.man +++ modules/pt/pt_introduction.man @@ -85,11 +85,10 @@ [subsection {User Packages}] [list_begin definitions] [def [package pt::pgen]] [list_end] - [subsection {Core Packages}] This layer is further split into six sections handling the storage, import, export, transformation, and execution of grammars, plus grammar specific support packages. @@ -140,11 +139,10 @@ [def [package pt::ast]] [def [package pt::pe]] [def [package pt::peg]] [list_end][comment {------------------- core support ---}] [list_end] - [subsection {Support Packages}] [list_begin definitions] [def [package pt::peg::container::peg]] [def [package text::write]] Index: modules/pt/pt_param.man ================================================================== --- modules/pt/pt_param.man +++ modules/pt/pt_param.man @@ -1,9 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin pt::param n 1] -[include include/module.inc] [keywords {virtual machine}] +[include include/module.inc] [titledesc {PackRat Machine Specification}] [description] [include include/ref_intro.inc] Welcome to the PackRat Machine (short: [term PARAM]), a virtual @@ -146,11 +146,10 @@ [vset INS0 {Input Handling}][include include/param_1is.inc] [list_end] - [section {Instruction Set}] With the machine's architectural state specified it is now possible to specify the instruction set operating on that state and to be implemented by any realization of the PARAM. The 37 instructions are @@ -183,11 +182,10 @@ If, on the other hand, the end of IN was reached, the operation is recorded as failed in ST, CL is left unchanged, and the pair of CL and [arg msg] becomes the new ES. [list_end] - [subsection {Character Processing}] The instructions in this section mainly access CC, testing it against character classes, ranges, and individual characters. @@ -246,11 +244,10 @@ [def [cmd test_xdigit]] [vset OP xdigit][include include/param_special.inc] [list_end] - [subsection {Error Handling}] The instructions in this section mainly access ER and ES. [list_begin definitions] @@ -300,11 +297,10 @@ [emph Note]: In the above "just past" means "that location plus one", or also "the location of the next character after that location". [list_end] - [subsection {Status Control}] The instructions in this section directly manipulate ST. [list_begin definitions] @@ -321,11 +317,10 @@ This instruction negates ST, turning a failure into a success and vice versa. [list_end] - [subsection {Location Handling}] The instructions in this section access CL and LS. @@ -344,15 +339,13 @@ This instruction pops the last saved location from LS and restores it as CL. [list_end] - [subsection {Nonterminal Execution}] The instructions in this section access and manipulate NC. - [list_begin definitions] [def "[cmd symbol_restore] [arg symbol]"] @@ -375,11 +368,10 @@ NC, using the pair of nonterminal [arg symbol] and the last location saved in LS as key. [list_end] - [subsection {Value Construction}] The instructions in this section manipulate SV. [list_begin definitions] @@ -401,15 +393,13 @@ right-most / last child. Note that ARS is not modfied by this operation. [list_end] - [subsection {AST Construction}] The instructions in this section manipulate ARS and AS. - [list_begin definitions] [def [cmd ast_value_push]] @@ -429,11 +419,10 @@ This instruction pops the last entry saved on AS. [list_end] - [subsection {Control Flow}] Normally this section would contain the specifications of the control flow instructions of the PARAM, i.e. (un)conditional jumps and the like. However, this part of the PARAM is intentionally left @@ -443,11 +432,10 @@ [para] The implementation of this machine in Parser Tools, i.e the package [package pt::rde], is not only coded in Tcl, but also relies on Tcl commands to provide it with control flow (instructions). - [section {Interaction of the Instructions with the Architectural State}] [comment {-- in lieu of a true table markup --}] [example { Index: modules/pt/pt_parser_api.man ================================================================== --- modules/pt/pt_parser_api.man +++ modules/pt/pt_parser_api.man @@ -44,11 +44,10 @@ All parser instances provide at least the methods shown below: [list_begin definitions] [include include/std_parser_object_api.inc] [list_end] - [section Usage] A generated parser is used like this Index: modules/pt/pt_peg_container.man ================================================================== --- modules/pt/pt_peg_container.man +++ modules/pt/pt_peg_container.man @@ -42,11 +42,10 @@ This package implements an interpreter for PEGs on top of the virtual machine provided by [package pt::peg::rde] [list_end] - [subsection {Class API}] The package exports the API described here. [list_begin definitions] @@ -76,11 +75,10 @@ is the empty expression, i.e. epsilon. It is [term valid], but not [term useful]. [list_end] - [subsection {Object API}] [para] All objects created by this package provide the following methods for the manipulation and querying of their contents: @@ -90,22 +88,19 @@ [call [arg objectName] [method destroy]] This method destroys the object, releasing all claimed memory, and deleting the associated object command. - [call [arg objectName] [method clear]] This method resets the object to contain the empty grammar. It does [emph not] destroy the object itself. - [call [arg objectName] [method importer]] This method returns the import manager object currently attached to the container, if any. - [call [arg objectName] [method importer] [arg object]] This method attaches the [arg object] as import manager to the container, and returns it as the result of the command. @@ -119,16 +114,14 @@ It is expected that [arg object] provides a method named [method {import text}] which takes a text and a format name, and returns the canonical serialization of the table of contents contained in the text, assuming the given format. - [call [arg objectName] [method exporter]] This method returns the export manager object currently attached to the container, if any. - [call [arg objectName] [method exporter] [arg object]] This method attaches the [arg object] as export manager to the container, and returns it as the result of the command. @@ -144,11 +137,10 @@ and returns a text encoding table of contents stored in the container, in the given format. It is further expected that the [arg object] will use the container's method [method serialize] to obtain the serialization of the table of contents from which to generate the text. - [call [arg objectName] [method =] [arg source]] This method assigns the contents of the PEG object [arg source] to ourselves, overwriting the existing definition. This is the assignment operator for grammars. @@ -158,11 +150,10 @@ This operation is in effect equivalent to [para] [example_begin] [arg objectName] [method {deserialize =}] [lb][arg source] [method serialize][rb] [example_end] - [call [arg objectName] [method -->] [arg destination]] This method assigns our contents to the PEG object [arg destination], overwriting the existing definition. This is the reverse assignment @@ -174,11 +165,10 @@ [para] [example_begin] [arg destination] [method {deserialize =}] [lb][arg objectName] [method serialize][rb] [example_end] - [call [arg objectName] [method serialize] [opt [arg format]]] This method returns our grammar in some textual form usable for transfer, persistent storage, etc. If no [arg format] is not specified the returned result is the canonical serialization of the grammar, as @@ -187,11 +177,10 @@ [para] Otherwise the object will use the attached export manager to convert the data to the specified format. In that case the method will fail with an error if the container has no export manager attached to it. - [call [arg objectName] [method {deserialize =}] [arg data] [opt [arg format]]] This is the complementary method to [method serialize]. @@ -209,29 +198,26 @@ [para] The result of the method is the empty string. - [call [arg objectName] [method {deserialize +=}] [arg data] [opt [arg format]]] This method behaves like [method {deserialize =}] in its essentials, except that it merges the grammar in the [arg data] to its -contents instead of replacing it. +contents instead of replacing it. The method will fail with an error and leave the grammar unchanged if merging is not possible, i.e. would produce an invalid grammar. [para] The result of the method is the empty string. - [call [arg objectName] [method start]] This method returns the current start expression of the grammar. - [call [arg objectName] [method start] [arg pe]] This method defines the [term {start expression}] of the grammar. It replaces the current start expression with the parsing expression @@ -241,22 +227,19 @@ The method will fail with an error and leave the grammar unchanged if [arg pe] does not contain a valid parsing expression as specified in the section [sectref {PE serialization format}]. - [call [arg objectName] [method nonterminals]] This method returns the set of all nonterminal symbols known to the grammar. - [call [arg objectName] [method modes]] This method returns a dictionary mapping the set of all nonterminal symbols known to the grammar to their semantic modes. - [call [arg objectName] [method modes] [arg dict]] This method takes a dictionary mapping a set of nonterminal symbols known to the grammar to their semantic modes, and returns the new full @@ -267,17 +250,15 @@ The method will fail with an error if any of the nonterminal symbols in the dictionary is not known to the grammar, or the empty string, i.e. an invalid nonterminal symbol, or if any the chosen [arg mode]s is not one of the legal values. - [call [arg objectName] [method rules]] This method returns a dictionary mapping the set of all nonterminal symbols known to the grammar to their parsing expressions (right-hand sides). - [call [arg objectName] [method rules] [arg dict]] This method takes a dictionary mapping a set of nonterminal symbols known to the grammar to their parsing expressions (right-hand sides), @@ -289,11 +270,10 @@ The method will fail with an error any of the nonterminal symbols in the dictionary is not known to the grammar, or the empty string, i.e. an invalid nonterminal symbol, or any of the chosen parsing expressions is not a valid parsing expression as specified in the section [sectref {PE serialization format}]. - [call [arg objectName] [method add] [opt [arg nt]...]] This method adds the nonterminal symbols [arg nt], etc. to the grammar, and defines default semantic mode and expression for it @@ -309,11 +289,10 @@ [para] The method does nothing if no symbol was specified as argument. - [call [arg objectName] [method remove] [opt [arg nt]...]] This method removes the named nonterminal symbols [arg nt], etc. from the set of nonterminal symbols known to our grammar. @@ -322,11 +301,10 @@ [para] The method will fail with an error and leave the grammar unchanged if any of the nonterminal symbols is not known to the grammar, or is the empty string, i.e. an invalid nonterminal symbol. - [call [arg objectName] [method exists] [arg nt]] This method tests whether the nonterminal symbol [arg nt] is known to our grammar or not. @@ -337,11 +315,10 @@ [para] The method will fail with an error if [arg nt] is the empty string, i.e. an invalid nonterminal symbol. - [call [arg objectName] [method rename] [arg ntold] [arg ntnew]] This method renames the nonterminal symbol [arg ntold] to [arg ntnew]. The method returns the empty string as its result. @@ -350,21 +327,19 @@ The method will fail with an error and leave the grammar unchanged if either [arg ntold] is not known to the grammar, or [arg ntnew] is already known, or any of them is the empty string, i.e. an invalid nonterminal symbol. - [call [arg objectName] [method mode] [arg nt]] This method returns the current semantic mode for the nonterminal symbol [arg nt]. [para] The method will fail with an error if [arg nt] is not known to the grammar, or the empty string, i.e. an invalid nonterminal symbol. - [call [arg objectName] [method mode] [arg nt] [arg mode]] This mode sets the semantic mode for the nonterminal symbol [arg nt], and returns the new mode. @@ -376,21 +351,19 @@ [para] The following modes are legal: [include include/modes.inc] - [call [arg objectName] [method rule] [arg nt]] This method returns the current parsing expression (right-hand side) for the nonterminal symbol [arg nt]. [para] The method will fail with an error if [arg nt] is not known to the grammar, or the empty string, i.e. an invalid nonterminal symbol. - [call [arg objectName] [method rule] [arg nt] [arg pe]] This method set the parsing expression (right-hand side) of the nonterminal [arg nt] to [arg pe], and returns the new parsing Index: modules/pt/pt_peg_export.man ================================================================== --- modules/pt/pt_peg_export.man +++ modules/pt/pt_peg_export.man @@ -76,11 +76,10 @@ i.e. [term {plugin writer}]s, reading and understanding the [manpage {Parser Tools Export API}] specification is an absolute necessity, as it documents the interaction between this package and its plugins in detail. - [section API] [subsection {Package commands}] [list_begin definitions] @@ -92,11 +91,10 @@ and [sectref {Object methods}]. The object command will be created under the current namespace if the [arg objectName] is not fully qualified, and in the specified namespace otherwise. [list_end] - [subsection {Object command}] All objects created by the [cmd ::pt::peg::export] command have the following general form: @@ -111,19 +109,17 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method {export serial}] [arg serial] [opt [arg format]]] This method takes the canonical serialization of a parsing expression grammar stored in [arg serial] and converts it to the specified @@ -145,11 +141,10 @@ [para] The plugin has to conform to the interface documented in the [manpage {Parser Tools Export API}] specification. - [call [arg objectName] [method {export object}] [arg object] [opt [arg format]]] This method is a convenient wrapper around the [method {export serial}] method described by the previous item. @@ -157,22 +152,19 @@ [method serialize] method returning the canonical serialization of a parsing expression grammar. It invokes that method, feeds the result into [method {export serial}] and returns the resulting string as its own result. - [call [arg objectName] [method {configuration names}]] This method returns a list containing the names of all configuration options currently known to the object. - [call [arg objectName] [method {configuration get}]] This method returns a dictionary containing the names and values of all configuration options currently known to the object. - [call [arg objectName] [method {configuration set}] [arg name] \ [opt [arg value]]] This method sets the configuration option [arg name] to the @@ -187,20 +179,17 @@ Note that these configuration options and their values are simply passed to a plugin when the actual export is performed. It is the plugin which checks the validity, not the manager. - [call [arg objectName] [method {configuration unset}] [arg pattern]...] This method unsets all configuration options matching the specified glob [arg pattern]s. If no pattern is specified it will unset all currently defined configuration options. - [list_end] - [include include/serial/pegrammar.inc] [include include/serial/pexpression.inc] [include include/feedback.inc] [manpage_end] Index: modules/pt/pt_peg_from_container.man ================================================================== --- modules/pt/pt_peg_from_container.man +++ modules/pt/pt_peg_from_container.man @@ -17,6 +17,5 @@ Another way of looking at this is, the CONTAINER output is its own import package. [include include/feedback.inc] [manpage_end] - Index: modules/pt/pt_peg_import.man ================================================================== --- modules/pt/pt_peg_import.man +++ modules/pt/pt_peg_import.man @@ -76,11 +76,10 @@ i.e. [term {plugin writer}]s, reading and understanding the [manpage {Parser Tools Impport API}] specification is an absolute necessity, as it documents the interaction between this package and its plugins in detail. - [section API] [subsection {Package commands}] [list_begin definitions] @@ -92,11 +91,10 @@ and [sectref {Object methods}]. The object command will be created under the current namespace if the [arg objectName] is not fully qualified, and in the specified namespace otherwise. [list_end] - [subsection {Object command}] All objects created by the [cmd ::pt::peg::import] command have the following general form: @@ -111,19 +109,17 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] This method destroys the object it is invoked for. - [call [arg objectName] [method {import text}] [arg text] [opt [arg format]]] This method takes the [arg text] and converts it from the specified [arg format] to the canonical serialization of a parsing expression @@ -145,20 +141,18 @@ [para] The plugin has to conform to the interface documented in the [manpage {Parser Tools Import API}] specification. - [call [arg objectName] [method {import file}] [arg path] [opt [arg format]]] This method is a convenient wrapper around the [method {import text}] method described by the previous item. It reads the contents of the specified file into memory, feeds the result into [method {import text}] and returns the resulting serialization as its own result. - [call [arg objectName] [method {import object text}] [arg object] \ [arg text] [opt [arg format]]] This method is a convenient wrapper around the [method {import text}] @@ -171,28 +165,25 @@ It imports the text using [method {import text}] and then feeds the resulting serialization into the [arg object] via [method deserialize]. This method returns the empty string as it result. - [call [arg objectName] [method {import object file}] [arg object] \ [arg path] [opt [arg format]]] This method behaves like [method {import object text}], except that it reads the text to convert from the specified file instead of being given it as argument. - [call [arg objectName] [method includes]] This method returns a list containing the currently specified paths to use to search for include files when processing input. The order of paths in the list corresponds to the order in which they are used, from first to last, and also corresponds to the order in which they were added to the object. - [call [arg objectName] [method {include add}] [arg path]] This methods adds the specified [arg path] to the list of paths to use to search for include files when processing input. The path is added @@ -201,11 +192,10 @@ [para] The method does nothing if the path is already known. - [call [arg objectName] [method {include remove}] [arg path]] This methods removes the specified [arg path] from the list of paths to use to search for include files when processing input. The result of the command is the empty string. @@ -212,19 +202,17 @@ [para] The method does nothing if the path is not known. - [call [arg objectName] [method {include clear}]] This method clears the list of paths to use to search for include files when processing input. The result of the command is the empty string. [list_end] - [include include/serial/pegrammar.inc] [include include/serial/pexpression.inc] [include include/feedback.inc] [manpage_end] Index: modules/pt/pt_peg_import_container.man ================================================================== --- modules/pt/pt_peg_import_container.man +++ modules/pt/pt_peg_import_container.man @@ -17,6 +17,5 @@ Another way of looking at this is, the CONTAINER output is its own import package. [include include/feedback.inc] [manpage_end] - Index: modules/pt/pt_peg_interp.man ================================================================== --- modules/pt/pt_peg_interp.man +++ modules/pt/pt_peg_interp.man @@ -25,11 +25,10 @@ The interpreted grammar is copied from an instance of [package \ pt::peg::container], or anything providing the same API, like the container classes created by [package pt::peg::to::container] or the associated export plugin [package pt::peg::export::container]. - [subsection {Class API}] The package exports the API described here. [list_begin definitions] @@ -46,11 +45,10 @@ This new parser is configured for the execution of an empty PEG. To configure the object for any other PEG use the method [method use] of the [sectref {Object API}]. [list_end] - [subsection {Object API}] All objects created by this package provide the following methods. @@ -72,11 +70,10 @@ The result of the method the empty string. [include include/std_parser_object_api.inc] [list_end] - [include include/serial/ast.inc] [include include/serial/pexpression.inc] [include include/feedback.inc] [manpage_end] Index: modules/pt/pt_peg_introduction.man ================================================================== --- modules/pt/pt_peg_introduction.man +++ modules/pt/pt_peg_introduction.man @@ -85,11 +85,10 @@ The remainder of this document consists of the formal definition of PEGs for the mathematically inclined, and an appendix listing references to places with more information on PEGs specifically, and parsing in general. - [section {Formal definition}] [para] For the mathematically inclined, a Parsing Expression Grammar is a 4-tuple (VN,VT,R,eS) where @@ -177,11 +176,10 @@ They can be easily implemented by recursive descent parsers with backtracking. This makes them relatives of LL(k) Context-Free Grammars. - [section References] [list_begin enumerated] [enum] [uri {http://www.pdos.lcs.mit.edu/~baford/packrat/} \ @@ -203,9 +201,8 @@ [enum] [uri {http://scifac.ru.ac.za/compilers/} \ {Compilers and Compiler Generators}], an online book using CoCo/R, a generator for recursive descent parsers. [list_end] - [include include/feedback.inc] [manpage_end] Index: modules/pt/pt_peg_language.man ================================================================== --- modules/pt/pt_peg_language.man +++ modules/pt/pt_peg_language.man @@ -118,11 +118,11 @@ # Binary operators. <> <> # sequence. parse 1, then 2. <> / <> # alternative. try to parse 1, and parse 2 if 1 failed to parse. - # Prefix operators. Lookahead constraints. Same priority. + # Prefix operators. Lookahead constraints. Same priority. & <> # Parse expression, ok on successful parse. ! <> # Ditto, except ok on failure to parse. # Suffix operators. Repetition. Same priority. @@ -253,16 +253,15 @@ unicode codepoint 0x5C). This is then followed by a series of octal digits, or 'u' and hexedecimal digits, or a regular character from a fixed set for various control characters. Some examples: [example { - \n \r \t \' \" \[ \] \\ # + \n \r \t \' \" \[ \] \\ # \000 up to \277 # octal escape, all ascii character, leading 0's can be removed. \u2CA7 # hexadecimal escape, all unicode characters. # # Here 2ca7 <=> Koptic Small Letter Tau }] - [subsection {Whitespace and comments}] One issue not touched upon so far is whitespace and comments. @@ -309,10 +308,9 @@ [para] Now, with all the above under our belt it should be possible to not only read, but understand the formal specification of the text representation shown in the next section, written in itself. - [include include/format/peg.inc] [include include/feedback.inc] [manpage_end] Index: modules/pt/pt_pegrammar.man ================================================================== --- modules/pt/pt_pegrammar.man +++ modules/pt/pt_pegrammar.man @@ -40,11 +40,10 @@ [para] For the specification of serializations see the section [sectref {PE serialization format}]. - [call [cmd ::pt::peg] [method verify-as-canonical] \ [arg serial]] This command verifies that the content of [arg serial] is a valid [term canonical] serialization of a PEG and will throw an error if @@ -52,11 +51,10 @@ [para] For the specification of canonical serializations see the section [sectref {PEG serialization format}]. - [call [cmd ::pt::peg] [method canonicalize] [arg serial]] This command assumes that the content of [arg serial] is a valid [term regular] serialization of a PEG and will throw an error if that @@ -71,11 +69,10 @@ [para] For the specification of regular and canonical serializations see the section [sectref {PEG serialization format}]. - [call [cmd ::pt::peg] [method print] [arg serial]] This command assumes that the argument [arg serial] contains a valid serialization of a parsing expression and returns a string containing that PE in a human readable form. @@ -87,11 +84,10 @@ [para] For the specification of serializations see the section [sectref {PEG serialization format}]. - [call [cmd ::pt::peg] [method merge] \ [arg seriala] [arg serialb]] This command accepts the regular serializations of two grammars and @@ -124,11 +120,10 @@ [para] The start expression of the unified grammar is the choice between the start expressions of the input grammars, with the start expression of [arg seriala] coming first, except if both expressions are identical. In that case the first expression is taken - [call [cmd ::pt::peg] [method equal] \ [arg seriala] [arg serialb]] This command tests the two grammars [arg seriala] and [arg serialb] Index: modules/pt/pt_pexpr_op.man ================================================================== --- modules/pt/pt_pexpr_op.man +++ modules/pt/pt_pexpr_op.man @@ -29,23 +29,20 @@ This command removes all occurences of any of the nonterminals symbols in the set [arg dropset] from the parsing expression [arg pe], and simplifies it. This may result in the expression becoming "epsilon", i.e. matching nothing. - [call [cmd ::pt::pe::op] [method rename] \ [arg nt] [arg ntnew] [arg pe]] This command renames all occurences of the nonterminal [arg nt] in the parsing expression [arg pe] into [arg ntnew]. - [call [cmd ::pt::pe::op] [method called] [arg pe]] This command extracts the set of all nonterminal symbols used, i.e. 'called', in the parsing expression [arg pe]. - [call [cmd ::pt::pe::op] [method flatten] [arg pe]] This command transforms the parsing expression by eliminating sequences nested in sequences, and choices in choices, lifting the @@ -55,11 +52,10 @@ [para] The resulting parsing expression is returned as the result of the command. - [call [cmd ::pt::pe::op] [method fusechars] [arg pe]] This command transforms the parsing expression by fusing adjacent terminals in sequences and adjacent terminals and ranges in choices, @@ -84,10 +80,9 @@ Notably, the commands [cmd {::pt::peg bottomup}] and [cmd {::pt::peg topdown}] will process them without trouble. [list_end] - [include include/serial/pexpression.inc] [include include/feedback.inc] [manpage_end] Index: modules/pt/pt_pexpression.man ================================================================== --- modules/pt/pt_pexpression.man +++ modules/pt/pt_pexpression.man @@ -40,11 +40,10 @@ [para] For the specification of serializations see the section [sectref {PE serialization format}]. - [call [cmd ::pt::pe] [method verify-as-canonical] \ [arg serial]] This command verifies that the content of [arg serial] is a valid [term canonical] serialization of a parsing expression and will throw @@ -53,11 +52,10 @@ [para] For the specification of canonical serializations see the section [sectref {PE serialization format}]. - [call [cmd ::pt::pe] [method canonicalize] [arg serial]] This command assumes that the content of [arg serial] is a valid [term regular] serialization of a parsing expression and will throw an @@ -72,11 +70,10 @@ [para] For the specification of regular and canonical serializations see the section [sectref {PE serialization format}]. - [call [cmd ::pt::pe] [method print] [arg serial]] This command assumes that the argument [arg serial] contains a valid serialization of a parsing expression and returns a string containing that PE in a human readable form. @@ -88,11 +85,10 @@ [para] For the specification of serializations see the section [sectref {PE serialization format}]. - [call [cmd ::pt::pe] [method bottomup] [arg cmdprefix] [arg pe]] This command walks the parsing expression [arg pe] from the bottom up to the root, invoking the command prefix [arg cmdprefix] for each @@ -122,11 +118,10 @@ [arg arguments] are the results of the command prefix invoked for the children of this inner parsing expression. [list_end] - [call [cmd ::pt::pe] [method topdown] [arg cmdprefix] [arg pe]] This command walks the parsing expression [arg pe] from the root down to the leaves, invoking the command prefix [arg cmdprefix] for each partial expression. This implies that the children of a parsing @@ -139,11 +134,10 @@ [para] The result returned by the command prefix is [emph ignored]. - [call [cmd ::pt::pe] [method equal] \ [arg seriala] [arg serialb]] This command tests the two parsing expressions [arg seriala] and [arg serialb] for structural equality. The result of the command is a @@ -153,155 +147,128 @@ [para] String equality is usable only if we can assume that the two parsing expressions are pure Tcl lists. - [call [cmd ::pt::pe] [method epsilon]] This command constructs the atomic parsing expression for epsilon. - [call [cmd ::pt::pe] [method dot]] This command constructs the atomic parsing expression for dot. - [call [cmd ::pt::pe] [method alnum]] This command constructs the atomic parsing expression for alnum. - [call [cmd ::pt::pe] [method alpha]] This command constructs the atomic parsing expression for alpha. - [call [cmd ::pt::pe] [method ascii]] This command constructs the atomic parsing expression for ascii. - [call [cmd ::pt::pe] [method control]] This command constructs the atomic parsing expression for control. - [call [cmd ::pt::pe] [method digit]] This command constructs the atomic parsing expression for digit. - [call [cmd ::pt::pe] [method graph]] This command constructs the atomic parsing expression for graph. - [call [cmd ::pt::pe] [method lower]] This command constructs the atomic parsing expression for lower. - [call [cmd ::pt::pe] [method print]] This command constructs the atomic parsing expression for print. - [call [cmd ::pt::pe] [method punct]] This command constructs the atomic parsing expression for punct. - [call [cmd ::pt::pe] [method space]] This command constructs the atomic parsing expression for space. - [call [cmd ::pt::pe] [method upper]] This command constructs the atomic parsing expression for upper. - [call [cmd ::pt::pe] [method wordchar]] This command constructs the atomic parsing expression for wordchar. - [call [cmd ::pt::pe] [method xdigit]] This command constructs the atomic parsing expression for xdigit. - [call [cmd ::pt::pe] [method ddigit]] This command constructs the atomic parsing expression for ddigit. - [call [cmd ::pt::pe] [method terminal] [arg t]] This command constructs the atomic parsing expression for the terminal symbol [arg t]. - [call [cmd ::pt::pe] [method range] [arg ta] [arg tb]] This command constructs the atomic parsing expression for the range of terminal symbols [arg ta] ... [arg tb]. - [call [cmd ::pt::pe] [method nonterminal] [arg nt]] This command constructs the atomic parsing expression for the nonterminal symbol [arg nt]. - [call [cmd ::pt::pe] [method choice] [arg pe]...] This command constructs the parsing expression representing the ordered or prioritized choice between the argument parsing expressions. The first argument has the highest priority. - [call [cmd ::pt::pe] [method sequence] [arg pe]...] This command constructs the parsing expression representing the sequence of the argument parsing expression. The first argument is the first element of the sequence. - [call [cmd ::pt::pe] [method repeat0] [arg pe]] This command constructs the parsing expression representing the zero or more repetition of the argument parsing expression [arg pe], also known as the kleene closure. - [call [cmd ::pt::pe] [method repeat1] [arg pe]] This command constructs the parsing expression representing the one or more repetition of the argument parsing expression [arg pe], also known as the positive kleene closure. - [call [cmd ::pt::pe] [method optional] [arg pe]] This command constructs the parsing expression representing the optionality of the argument parsing expression [arg pe]. - [call [cmd ::pt::pe] [method ahead] [arg pe]] This command constructs the parsing expression representing the positive lookahead of the argument parsing expression [arg pe]. - [call [cmd ::pt::pe] [method notahead] [arg pe]] This command constructs the parsing expression representing the negative lookahead of the argument parsing expression [arg pe]. [list_end] - [include include/serial/pexpression.inc] [include include/feedback.inc] [manpage_end] Index: modules/pt/pt_rdengine.man ================================================================== --- modules/pt/pt_rdengine.man +++ modules/pt/pt_rdengine.man @@ -45,11 +45,10 @@ described in the section [sectref {Object API}]. It may be used to invoke various operations on the object. [list_end] - [subsection {Object API}] All objects created by this package provide the following 63 methods for the manipulation and querying of their state, which is, in essence the architectural state of a PARAM. @@ -346,11 +345,10 @@ i_error_push }] Parsers use it at the beginning of sequences generating an AST and choices with an initial branch generating an AST. - [call [arg objectName] [method si:void_state_merge]] This method combines [example { i_error_pop_merge Index: modules/pt/pt_to_api.man ================================================================== --- modules/pt/pt_to_api.man +++ modules/pt/pt_to_api.man @@ -48,16 +48,14 @@ This method has to reset the configuration of the converter to its default settings. The result of the method has to be the empty string. - [call [cmd CONVERTER] [method configure]] This method, in this form, has to return a dictionary containing the current configuration of the converter. - [call [cmd CONVERTER] [method configure] [arg option]] This method, in this form, has to return the current value of the specified configuration [arg option] of the converter. @@ -67,11 +65,10 @@ Please read the section [sectref Options] for the set of standard options any converter has to accept. Any other options accepted by a specific converter will be described in its manpage. - [call [cmd CONVERTER] [method configure] [arg option] [arg value]...] This command, in this form, sets the specified [arg option]s of the converter to the given [arg value]s. @@ -82,11 +79,10 @@ options a converter has to accept. Any other options accepted by a specific converter will be described in its manpage. - [call [cmd CONVERTER] [method convert] [arg serial]] This method has to accept the canonical serialization of a parsing expression grammar, as specified in section [sectref {PEG serialization format}], and contained in [arg serial]. @@ -94,11 +90,10 @@ The result of the method has to be the result of converting the input grammar into whatever the converter is for, per its configuration. [list_end][comment {-- api command signatures --}] [list_end][comment {-- converter rules --}] - [section {Plugin API}] Any (grammar) export plugin has to follow the rules set out below: @@ -169,11 +164,10 @@ the command [cmd export]. This call has to leave the plugin in a state where another usage cycle can be run without problems. [list_end][comment {-- plugin rules --}] - [section Options] Each export converter and plugin for an export converter has to accept the options below in their [method configure] method. Converters are allowed to ignore the contents of these options when performing a @@ -181,11 +175,10 @@ pass the options given to them to the converter they are invoking. [list_begin options] [include include/format/options_std.inc] [list_end] - [section Usage] To use a converter do Index: modules/rc4/rc4.man ================================================================== --- modules/rc4/rc4.man +++ modules/rc4/rc4.man @@ -1,17 +1,26 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin rc4 n 1.1.0] +[see_also aes(n)] +[see_also blowfish(n)] +[see_also des(n)] +[keywords arcfour] +[keywords {data integrity}] +[keywords encryption] +[keywords rc4] +[keywords security] +[keywords {stream cipher}] [copyright {2003, Pat Thoyts }] [moddesc {RC4 Stream Cipher}] [titledesc {Implementation of the RC4 stream cipher}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] [require rc4 [opt 1.1.0]] [description] [para] -This package is an implementation in Tcl of the RC4 stream cipher +This package is an implementation in Tcl of the RC4 stream cipher developed by Ron Rivest of RSA Data Security Inc. The cipher was a trade secret of RSA but was reverse-engineered and published to the internet in 1994. It is used in a number of network protocols for securing communications. To evade trademark restrictions this cipher is sometimes known as ARCFOUR. @@ -35,11 +44,11 @@ version of the result if not using an [arg -out] channel. [para] The data to be processes can be specified either as a string argument to -the rc4 command, or as a filename or a pre-opened channel. If the +the rc4 command, or as a filename or a pre-opened channel. If the [arg "-infile"] argument is given then the file is opened, the data read and processed and the file is closed. If the [arg "-in"] argument is given then data is read from the channel until the end of file. The channel is not closed. If the [arg "-out"] argument is given then the processing result is written to this channel. @@ -63,20 +72,20 @@ [list_begin definitions] [call [cmd "::rc4::RC4Init"] [arg "keydata"]] Initialize a new RC4 key. The [arg keydata] is any amount of binary -data and is used to initialize the cipher internal state. +data and is used to initialize the cipher internal state. [call [cmd "::rc4::RC4"] [arg "Key"] [arg "data"]] Encrypt or decrypt the input data using the key obtained by calling [cmd RC4Init]. [call [cmd "::rc4::RC4Final"] [arg "Key"]] -This should be called to clean up resources associated with +This should be called to clean up resources associated with [arg Key]. Once this function has been called the key is destroyed. [list_end] [section "EXAMPLES"] @@ -101,24 +110,11 @@ DoStuffWith $myState $data } rc4::rc4 -in $socket -command [list ::Finish $ApplicationState] }] -[see_also des(n) aes(n) blowfish(n)] - [section "AUTHORS"] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph rc4] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords rc4 arcfour {stream cipher} security encryption {data integrity}] +[vset CATEGORY rc4] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/rcs/rcs.man ================================================================== --- modules/rcs/rcs.man +++ modules/rcs/rcs.man @@ -1,6 +1,16 @@ [manpage_begin rcs n 2.0.2] +[see_also struct] +[see_also textutil] +[keywords CVS] +[keywords {diff -n format}] +[keywords patching] +[keywords RCS] +[keywords {RCS patch}] +[keywords SCCS] +[keywords {text conversion}] +[keywords {text differences}] [moddesc {RCS low level utilities}] [copyright {2005, Andreas Kupries }] [copyright {2005, Colin McCormack }] [titledesc {RCS low level utilities}] [category {Text processing}] @@ -41,11 +51,10 @@ In the future we might add the generation and decoding of other patch formats as well. Like regular 'patch' patches, or also context and unified patches. }] - [section {COMMANDS}] [list_begin definitions] [call [cmd ::rcs::text2dict] [arg text]] @@ -56,35 +65,31 @@ More information about the format of the result can be found in section [sectref {TEXT DICT DATA STRUCTURE}]. This command returns the [term canonical] representation of the input. - [call [cmd ::rcs::dict2text] [arg dict]] This command provides the complementary operation to [cmd ::rcs::text2dict]. It converts a dictionary in the form described in section [sectref {TEXT DICT DATA STRUCTURE}] back into a text and returns that text as its result. The command does accept non-canonical representations of the text as its input. - [call [cmd ::rcs::file2dict] [arg filename]] This command is identical to [cmd ::rcs::text2dict], except that it reads the text to convert from the file with path [arg filename]. The file has to exist and must be readable as well. - [call [cmd ::rcs::dict2file] [arg filename] [arg dict]] This command is identical to [cmd ::rcs::2dict2text], except that it stores the resulting text in the file with path [arg filename]. The file is created if it did not exist, and must be writable. The result of the command is the empty string. - [call [cmd ::rcs::decodeRcsPatch] [arg text]] Converts the [arg text] argument into a patch command list (PCL) as specified in the section [sectref {RCS PATCH COMMAND LIST}] and @@ -94,11 +99,10 @@ known as [term {RCS patch}] format, as specified in the section [sectref rpf]. Please note that the command ignores no-ops in the input, in other words the resulting PCL contains only instructions doing something. - [call [cmd ::rcs::encodeRcsPatch] [arg pcmds]] This command provides the complementary operation to @@ -113,11 +117,10 @@ encoder cannot put back anymore into the generated RCS patch. In other words, the result of a decode/encode step may not match the original input at the character level, but it will match it at the functional level. - [call [cmd ::rcs::applyRcsPatch] [arg text] [arg pcmds]] This operation applies a patch in the form of a PCL to a text given in the form of a dictionary and returns the modified text, again as dictionary, as its result. @@ -129,11 +132,10 @@ into data structures acceptable to this command. Analogously use the command [cmd ::rcs::dict2text] (or equivalent) to transform the result of this command into actuall text as required. [list_end] - [section {TEXT DICT DATA STRUCTURE}] A text dictionary is a dictionary whose keys are integer numbers and text strings as the associated values. The keys represent the line @@ -186,11 +188,10 @@ [para] The result of applying a patch to a text dictionary will in general cause the dictionary to become non-canonical. - [section {RCS PATCH FORMAT} rpf] A [term patch] is in general a series of instructions how to transform an input text T into a different text T', and also encoded in text @@ -257,11 +258,10 @@ This is the format of results returned by the command [cmd ::rcs::decodeRcsPatch] and accepted by the commands [cmd ::rcs::encodeRcsPatch] and [cmd ::rcs::appplyRcsPatch] resp. - Note however that the decoder will strip no-op commands, and the encoder will not generate no-ops, making them not fully complementary at the textual level, only at the functional level. [para] @@ -276,11 +276,10 @@ a11 3 They both may be called deep and profound. Deeper and more profound, The door of all subtleties!}] - [section {RCS PATCH COMMAND LIST}] Patch command lists (sort: PCL's) are the data structures generated by patch decoder command and accepted by the patch encoder and applicator @@ -324,23 +323,8 @@ }} {a 11 {They both may be called deep and profound. Deeper and more profound, The door of all subtleties!}}}}] -[see_also textutil struct] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph rcs] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords RCS CVS SCCS] -[keywords {RCS patch} {diff -n format} patching] -[keywords {text conversion} {text differences}] +[vset CATEGORY rcs] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/report/report.man ================================================================== --- modules/report/report.man +++ modules/report/report.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin report n 0.3.1] +[keywords matrix] +[keywords report] +[keywords table] [copyright {2002 Andreas Kupries }] [moddesc {Matrix reports}] [titledesc {Create and manipulate report objects}] [category {Data structures}] [require Tcl 8.2] @@ -104,11 +107,10 @@ The different kinds of lines and the codes used by the report methods to address them are: [list_begin definitions] - [def [const top]] The topmost line of a report. Separates the report from anything which came before it. The user can enable the usage of this line at will. @@ -233,11 +235,10 @@ [para] The following commands are possible for report objects: [list_begin definitions] - [call [arg reportName] [method destroy]] Destroys the report, including its storage space and associated command. @@ -467,19 +468,8 @@ % % # alternate way of doing the above % m format 2string r }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph report] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords matrix report table] +[vset CATEGORY report] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/rest/rest.man ================================================================== --- modules/rest/rest.man +++ modules/rest/rest.man @@ -17,11 +17,11 @@ [call [cmd ::rest::post] [arg url] [arg query] [opt config] [opt body]] [call [cmd ::rest::head] [arg url] [arg query] [opt config] [opt body]] [call [cmd ::rest::put] [arg url] [arg query] [opt config] [opt body]] [call [cmd ::rest::delete] [arg url] [arg query] [opt config] [opt body]] [list_end] -The above commands are all equivalent except for the http method used. If you use [cmd simple] then the method should be specified as an option in the [opt config] dict, otherwise it defaults to [const get]. If a body is needed then the config dict must be present, however it may be empty. +The above commands are all equivalent except for the http method used. If you use [cmd simple] then the method should be specified as an option in the [opt config] dict, otherwise it defaults to [const get]. If a body is needed then the config dict must be present, however it may be empty. [example { set appid APPID set search tcl set res [rest::get http://boss.yahooapis.com/ysearch/web/v1/$search [list appid $appid]] @@ -44,11 +44,10 @@ auth format method content-type - Interface usage An interface to a REST API consists of a series of definitions of REST calls contained in an array. The array name becomes a namespace containing the defined commands. Each array element defines the name of the call and takes the form of a dict, aka key/value pairs. These keys are the defined configuration options below. After creating the definitions simply call rest::create_interface on the array to create the commands. [example { @@ -62,11 +61,10 @@ rest::create_interface yweather puts [yweather::forecast -p 94089] }] - ::${name}::basic_auth [arg u] [arg p] ::${name}::set_static_args [opt args]] @@ -83,11 +81,10 @@ [call [cmd ::rest::parse_opts] [arg static] [arg required] [arg optional] [arg string]] [call [cmd ::rest::substitute] [arg string] [opt var]] take a string and substitute real values for any option identifiers - [call [cmd ::rest::create_interface] [arg name]] 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. @@ -199,7 +196,6 @@ google calendar facebook del.icio.us read the file or source it and use [cmd describe] for more information. also see the developers documentation on the respective sites. - [manpage_end] Index: modules/ripemd/ripemd128.man ================================================================== --- modules/ripemd/ripemd128.man +++ modules/ripemd/ripemd128.man @@ -1,6 +1,18 @@ [manpage_begin ripemd128 n 1.0.3] +[see_also md4] +[see_also md5] +[see_also ripemd160] +[see_also sha1] +[keywords hashing] +[keywords md4] +[keywords message-digest] +[keywords {rfc 1320}] +[keywords {rfc 1321}] +[keywords {rfc 2104}] +[keywords RIPEMD] +[keywords security] [moddesc {RIPEMD Message-Digest Algorithm}] [copyright {2004, Pat Thoyts }] [titledesc {RIPEMD-128 Message-Digest Algorithm}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -8,11 +20,11 @@ [description] [para] This package is an implementation in Tcl of the RIPEMD-128 message-digest algorithm (1). This algorithm takes an arbitrary quantity of data and -generates a 128-bit message digest from the input. The RIPEMD-128 +generates a 128-bit message digest from the input. The RIPEMD-128 algorithm is based upon the MD4 algorithm (2, 4) but has been cryptographically strengthened against weaknesses that have been found in MD4 (4). RIPEMD-128 has been designed to be a drop-in replacement for MD4 and MD5 (5). If security is the major consideration, then RIPEMD-160 or SHA1 should be considered. @@ -38,11 +50,11 @@ will return a hexadecimal encoded version of the digest. [para] The data to be hashed can be specified either as a string argument to -the ripemd128 command, or as a filename or a pre-opened channel. If the +the ripemd128 command, or as a filename or a pre-opened channel. If the [arg "-filename"] argument is given then the file is opened, the data read and hashed and the file is closed. If the [arg "-channel"] argument is given then data is read from the channel until the end of file. The channel is not closed. @@ -65,15 +77,15 @@ [section {PROGRAMMING INTERFACE}] For the programmer, hash functions can be viewed as a bucket into which one pours data. When you have finished, you extract a value that is -uniquely derived from the data that was poured into the bucket. The +uniquely derived from the data that was poured into the bucket. The programming interface to the hash operates on a token (equivalent to the -bucket). You call [cmd RIPEMD128Init] to obtain a token and then call +bucket). You call [cmd RIPEMD128Init] to obtain a token and then call [cmd RIPEMD128Update] as many times as required to add data to the hash. To -release any resources and obtain the hash value, you then call +release any resources and obtain the hash value, you then call [cmd RIPEMD128Final]. An equivalent set of functions gives you a keyed digest (HMAC). [para] @@ -91,15 +103,14 @@ Begins a new RIPEMD-128 hash. Returns a token ID that must be used for the remaining functions. [call [cmd "::ripemd::RIPEMD128Update"] [arg "token"] [arg "data"]] -Add data to the hash identified by token. Calling +Add data to the hash identified by token. Calling [emph {RIPEMD128Update $token "abcd"}] is equivalent to calling -[emph {RIPEMD128Update $token "ab"}] followed by +[emph {RIPEMD128Update $token "ab"}] followed by [emph {RIPEMD128Update $token "cb"}]. See [sectref {EXAMPLES}]. - [call [cmd "::ripemd::RIPEMD128Final"] [arg "token"]] Returns the hash value and releases any resources held by this token. Once this command completes the token will be invalid. The @@ -143,11 +154,11 @@ [section {REFERENCES}] [list_begin enumerated] [enum] - H. Dobbertin, A. Bosselaers, B. Preneel, + H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened version of RIPEMD" [uri http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf] [enum] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, @@ -166,26 +177,14 @@ Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and RSA Data Security, Inc, April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1321.txt]) [enum] - Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ripemd] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also md4 md5 sha1 ripemd160] -[keywords RIPEMD md4 hashing message-digest security {rfc 1320} {rfc 1321} {rfc 2104}] +[vset CATEGORY ripemd] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/ripemd/ripemd160.man ================================================================== --- modules/ripemd/ripemd160.man +++ modules/ripemd/ripemd160.man @@ -1,6 +1,18 @@ [manpage_begin ripemd160 n 1.0.3] +[see_also md4] +[see_also md5] +[see_also ripemd128] +[see_also sha1] +[keywords hashing] +[keywords md4] +[keywords message-digest] +[keywords {rfc 1320}] +[keywords {rfc 1321}] +[keywords {rfc 2104}] +[keywords RIPEMD] +[keywords security] [moddesc {RIPEMD Message-Digest Algorithm}] [copyright {2004, Pat Thoyts }] [titledesc {RIPEMD-160 Message-Digest Algorithm}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -8,11 +20,11 @@ [description] [para] This package is an implementation in Tcl of the RIPEMD-160 message-digest algorithm (1). This algorithm takes an arbitrary quantity of data and -generates a 160-bit message digest from the input. The RIPEMD-160 +generates a 160-bit message digest from the input. The RIPEMD-160 algorithm is based upon the MD4 algorithm (2, 4) but has been cryptographically strengthened against weaknesses that have been found in MD4 (4). [para] @@ -36,11 +48,11 @@ will return a hexadecimal encoded version of the digest. [para] The data to be hashed can be specified either as a string argument to -the ripemd160 command, or as a filename or a pre-opened channel. If the +the ripemd160 command, or as a filename or a pre-opened channel. If the [arg "-filename"] argument is given then the file is opened, the data read and hashed and the file is closed. If the [arg "-channel"] argument is given then data is read from the channel until the end of file. The channel is not closed. @@ -63,15 +75,15 @@ [section {PROGRAMMING INTERFACE}] For the programmer, hash functions can be viewed as a bucket into which one pours data. When you have finished, you extract a value that is -uniquely derived from the data that was poured into the bucket. The +uniquely derived from the data that was poured into the bucket. The programming interface to the hash operates on a token (equivalent to the -bucket). You call [cmd RIPEMD160Init] to obtain a token and then call +bucket). You call [cmd RIPEMD160Init] to obtain a token and then call [cmd RIPEMD160Update] as many times as required to add data to the hash. To -release any resources and obtain the hash value, you then call +release any resources and obtain the hash value, you then call [cmd RIPEMD160Final]. An equivalent set of functions gives you a keyed digest (HMAC). [list_begin definitions] @@ -80,15 +92,14 @@ Begins a new RIPEMD-160 hash. Returns a token ID that must be used for the remaining functions. [call [cmd "::ripemd::RIPEMD160Update"] [arg "token"] [arg "data"]] -Add data to the hash identified by token. Calling +Add data to the hash identified by token. Calling [emph {RIPEMD160Update $token "abcd"}] is equivalent to calling -[emph {RIPEMD160Update $token "ab"}] followed by +[emph {RIPEMD160Update $token "ab"}] followed by [emph {RIPEMD160Update $token "cb"}]. See [sectref {EXAMPLES}]. - [call [cmd "::ripemd::RIPEMD160Final"] [arg "token"]] Returns the hash value and releases any resources held by this token. Once this command completes the token will be invalid. The @@ -132,11 +143,11 @@ [section {REFERENCES}] [list_begin enumerated] [enum] - H. Dobbertin, A. Bosselaers, B. Preneel, + H. Dobbertin, A. Bosselaers, B. Preneel, "RIPEMD-160, a strengthened version of RIPEMD" [uri http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf] [enum] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, @@ -150,26 +161,14 @@ [enum] Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology vol 11 (4), pp. 253-271 (1998) [enum] - Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph ripemd] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also md4 md5 sha1 ripemd128] -[keywords RIPEMD md4 hashing message-digest security {rfc 1320} {rfc 1321} {rfc 2104}] +[vset CATEGORY ripemd] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/sasl/sasl.man ================================================================== --- modules/sasl/sasl.man +++ modules/sasl/sasl.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin SASL n 1.3.0] +[keywords authentication] +[keywords SASL] [copyright {2005-2006, Pat Thoyts }] [moddesc {Simple Authentication and Security Layer (SASL)}] [titledesc {Implementation of SASL mechanisms for Tcl}] [category Networking] [require Tcl 8.2] @@ -41,11 +43,11 @@ Modify and inspect the SASL context option. See [sectref OPTIONS] for further details. [call [cmd "::SASL::step"] [arg "context"] [arg "challenge"] [opt [arg "..."]]] -This is the core procedure for using the SASL framework. The +This is the core procedure for using the SASL framework. The [cmd step] procedure should be called until it returns 0. Each step takes a server challenge string and the response is calculated and stored in the context. Each mechanism may require one or more steps. For some steps there may be no server challenge required in which case an empty string should be provided for this parameter. All mechanisms should accept @@ -67,21 +69,21 @@ [call [cmd "::SASL::mechanisms"] [opt [arg "type"]] [opt [arg "minimum"]]] Returns a list of all the available SASL mechanisms. The list is sorted by the mechanism preference value (see [cmd register]) with the -preferred mechanisms and the head of the list. Any mechanism with a +preferred mechanisms and the head of the list. Any mechanism with a preference value less than the[arg minimum] (which defaults to 0) is removed from the returned list. This permits a security threshold to be set. Mechanisms with a preference less that 25 transmit authentication are particularly susceptible to eavesdropping and should not be provided unless a secure channel is in use (eg: tls). [para] The [arg type] parameter may be one of [arg client] or [arg server] and defaults to [arg client]. -Only mechanisms that have an implementation matching the [arg type] are -returned (this permits servers to correctly declare support only for +Only mechanisms that have an implementation matching the [arg type] are +returned (this permits servers to correctly declare support only for mechanisms that actually provide a server implementation). [call [cmd "::SASL::register"] [arg "mechanism"] [arg "preference"] \ [arg "clientproc"] [opt [arg "serverproc"]]] @@ -91,12 +93,10 @@ the list returned by the [cmd mechanisms] command. Higher values indicate a preferred mechanism. If the mechanism is already registered then the recorded values are updated. [list_end] - - [section "OPTIONS"] [list_begin definitions] @@ -134,12 +134,10 @@ challenge. A new context must be created for each incoming client connection when in server mode. [list_end] - - [section "CALLBACK PROCEDURE"] When the SASL framework requires any user details it will call the procedure provided when the context was created with an argument that specfies the item of information required. @@ -164,11 +162,11 @@ [def "password"] The callback procedure should return the password that matches the authentication identity as used within the current realm. [para] -For server mechanisms the password callback should always be called with +For server mechanisms the password callback should always be called with the authentication identity and the realm as the first two parameters. [def "realm"] Some SASL mechanisms use realms to partition authentication identities. @@ -178,12 +176,10 @@ [def "hostname"] Returns the client host name - typically [lb]info host[rb]. [list_end] - - [section "MECHANISMS"] [list_begin definitions] @@ -225,12 +221,12 @@ [def "OTP"] OTP is the One-Time Password system described in RFC 2289 [lb]6[rb]. This mechanism is secure against replay attacks and also avoids storing password or password equivalents on the server. Only a digest of a seed -and a passphrase is ever transmitted across the network. Requires the -[package otp] package from tcllib and one or more of the cryptographic +and a passphrase is ever transmitted across the network. Requires the +[package otp] package from tcllib and one or more of the cryptographic digest packages (md5 or sha-1 are the most commonly used). [def "NTLM"] This is a proprietary protocol developed by Microsoft [lb]5[rb] and is @@ -237,26 +233,24 @@ in common use for authenticating users in a Windows network environment. NTLM uses DES encryption and MD4 digests of the users password to authenticate a connection. Certain weaknesses have been found in NTLM and thus there are a number of versions of the protocol. As this mechanism has additional dependencies it is made available as -a separate sub-package. To enable this mechanism your application must +a separate sub-package. To enable this mechanism your application must load the SASL::NTLM package. [def "X-GOOGLE-TOKEN"] -This is a proprietary protocol developed by Google and used for +This is a proprietary protocol developed by Google and used for authenticating users for the Google Talk service. This mechanism makes -a pair of HTTP requests over an SSL channel and so this mechanism +a pair of HTTP requests over an SSL channel and so this mechanism depends upon the availability of the tls and http packages. To enable this mechanism your application must load the SASL::XGoogleToken package. -In addition you are recommended to make use of the autoproxy package to +In addition you are recommended to make use of the autoproxy package to handle HTTP proxies reasonably transparently. [list_end] - - [section "EXAMPLES"] See the examples subdirectory for more complete samples using SASL with network protocols. The following should give an idea how the SASL @@ -328,19 +322,8 @@ [list_end] [section AUTHORS] Pat Thoyts -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph sasl] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords SASL authentication] +[vset CATEGORY sasl] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/sha1/sha1.man ================================================================== --- modules/sha1/sha1.man +++ modules/sha1/sha1.man @@ -1,6 +1,16 @@ [manpage_begin sha1 n 2.0.3] +[see_also md4] +[see_also md5] +[see_also ripemd128] +[see_also ripemd160] +[keywords {FIPS 180-1}] +[keywords hashing] +[keywords message-digest] +[keywords {rfc 2104}] +[keywords security] +[keywords sha1] [moddesc {SHA-x Message-Digest Algorithm}] [copyright {2005, Pat Thoyts }] [titledesc {SHA1 Message-Digest Algorithm}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -35,11 +45,11 @@ giving [arg "-bin"]. [para] The data to be hashed can be specified either as a string argument to -the [cmd "sha1"] command, or as a filename or a pre-opened channel. If the +the [cmd "sha1"] command, or as a filename or a pre-opened channel. If the [arg "-filename"] argument is given then the file is opened, the data read and hashed and the file is closed. If the [arg "-channel"] argument is given then data is read from the channel until the end of file. The channel is not closed. [emph NOTE] use of the channel or filename options results in the internal use of [cmd vwait]. To avoid nested @@ -68,13 +78,13 @@ For the programmer, the SHA1 hash can be viewed as a bucket into which one pours data. When you have finished, you extract a value that is derived from the data that was poured into the bucket. The programming interface to the SHA1 hash operates on a token (equivalent to the -bucket). You call [cmd "SHA1Init"] to obtain a token and then call +bucket). You call [cmd "SHA1Init"] to obtain a token and then call [cmd "SHA1Update"] as many times as required to add data to the hash. To -release any resources and obtain the hash value, you then call +release any resources and obtain the hash value, you then call [cmd "SHA1Final"]. An equivalent set of functions gives you a keyed digest (HMAC). [para] @@ -91,15 +101,14 @@ Begins a new SHA1 hash. Returns a token ID that must be used for the remaining functions. [call [cmd "::sha1::SHA1Update"] [arg "token"] [arg "data"]] -Add data to the hash identified by token. Calling +Add data to the hash identified by token. Calling [emph {SHA1Update $token "abcd"}] is equivalent to calling -[emph {SHA1Update $token "ab"}] followed by +[emph {SHA1Update $token "ab"}] followed by [emph {SHA1Update $token "cb"}]. See [sectref {EXAMPLES}]. - [call [cmd "::sha1::SHA1Final"] [arg "token"]] Returns the hash value and releases any resources held by this token. Once this command completes the token will be invalid. The @@ -152,27 +161,14 @@ [enum] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1320.txt]) [enum] - Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] -[see_also md4 md5 ripemd128 ripemd160] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph sha1] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords sha1 hashing security message-digest {FIPS 180-1} {rfc 2104}] +[vset CATEGORY sha1] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/sha1/sha256.man ================================================================== --- modules/sha1/sha256.man +++ modules/sha1/sha256.man @@ -1,6 +1,17 @@ [manpage_begin sha256 n 1.0.3] +[see_also md4] +[see_also md5] +[see_also ripemd128] +[see_also ripemd160] +[see_also sha1] +[keywords {FIPS 180-1}] +[keywords hashing] +[keywords message-digest] +[keywords {rfc 2104}] +[keywords security] +[keywords sha256] [moddesc {SHA-x Message-Digest Algorithm}] [copyright {2008, Andreas Kupries }] [titledesc {SHA256 Message-Digest Algorithm}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -34,11 +45,11 @@ data by giving [arg "-bin"]. [para] The data to be hashed can be specified either as a string argument to -the [cmd "sha256"] command, or as a filename or a pre-opened channel. If the +the [cmd "sha256"] command, or as a filename or a pre-opened channel. If the [arg "-filename"] argument is given then the file is opened, the data read and hashed and the file is closed. If the [arg "-channel"] argument is given then data is read from the channel until the end of file. The channel is not closed. [emph NOTE] use of the channel or filename options results in the internal use of [cmd vwait]. To avoid nested @@ -53,11 +64,10 @@ [opt "[arg -hex|-bin]"] \ [lb] [arg "-channel channel"] | \ [arg "-file filename"] | [arg "string"] [rb]] Like [cmd ::sha2::sha256], except that the SHA224 digest is returned. - [call [cmd "::sha2::hmac"] [arg "key"] [arg "string"]] [call [cmd "::sha2::hmac"] \ [opt "[arg -hex|-bin]"] \ [arg "-key key"] \ @@ -98,13 +108,13 @@ Begins a new SHA256/SHA224 hash. Returns a token ID that must be used for the remaining functions. [call [cmd "::sha2::SHA256Update"] [arg "token"] [arg "data"]] -Add data to the hash identified by token. Calling +Add data to the hash identified by token. Calling [emph {SHA256Update $token "abcd"}] is equivalent to calling -[emph {SHA256Update $token "ab"}] followed by +[emph {SHA256Update $token "ab"}] followed by [emph {SHA256Update $token "cb"}]. See [sectref {EXAMPLES}]. Note that this command is used for both SHA256 and SHA224. Only the initialization and finalization commands of both hashes differ. @@ -162,27 +172,14 @@ [enum] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992. ([uri http://www.rfc-editor.org/rfc/rfc1320.txt]) [enum] - Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997. ([uri http://www.rfc-editor.org/rfc/rfc2104.txt]) [list_end] -[see_also sha1 md4 md5 ripemd128 ripemd160] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph sha1] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords sha256 hashing security message-digest {FIPS 180-1} {rfc 2104}] +[vset CATEGORY sha1] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/simulation/annealing.man ================================================================== --- modules/simulation/annealing.man +++ modules/simulation/annealing.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin simulation::annealing n 0.2] +[keywords math] +[keywords optimization] +[keywords {simulated annealing}] [copyright {2008 Arjen Markus }] [moddesc {Tcl Simulation Tools}] [titledesc {Simulated annealing}] [category Mathematics] [require Tcl [opt 8.4]] @@ -249,8 +252,6 @@ solution you may want to try different values of the trials parameter for instance. Also ensure that the function to be minimized depends on all or most parameters - see the source code for a counter example and run that. [list_end] - -[keywords math optimization "simulated annealing"] [manpage_end] Index: modules/simulation/montecarlo.man ================================================================== --- modules/simulation/montecarlo.man +++ modules/simulation/montecarlo.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin simulation::montecarlo n 0.1] +[keywords math] +[keywords {montecarlo simulation}] +[keywords {stochastic modelling}] [copyright {2008 Arjen Markus }] [moddesc {Tcl Simulation Tools}] [titledesc {Monte Carlo simulations}] [category Mathematics] [require Tcl [opt 8.4]] @@ -211,8 +214,6 @@ temporary procedure that does the actual work. It loops for the given number of trials. [para] As it constructs a temporary procedure, local variables defined at the start continue to exist in the loop. - -[keywords math "montecarlo simulation" "stochastic modelling"] [manpage_end] Index: modules/simulation/simulation_random.man ================================================================== --- modules/simulation/simulation_random.man +++ modules/simulation/simulation_random.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin simulation::random n 0.1] +[keywords math] +[keywords {random numbers}] +[keywords simulation] +[keywords {statistical distribution}] [copyright {2004 Arjen Markus }] [moddesc {Tcl Simulation Tools}] [titledesc {Pseudo-random number generators}] [category Mathematics] [require Tcl [opt 8.4]] @@ -65,11 +69,10 @@ [list_begin arguments] [arg_def float lambda] Mean number per time interval [list_end] [list_end] - The package defines the following public procedures for [emph continuous] distributions: [list_begin definitions] @@ -147,11 +150,10 @@ [arg_def float df] Degrees of freedom [list_end] [list_end] - The package defines the following public procedures for random point sets: [list_begin definitions] [call [cmd ::simulation::random::prng_Disk] [arg rad]] @@ -209,9 +211,6 @@ [arg_def float width] Width of the block (y-direction) [arg_def float depth] Depth of the block (z-direction) [list_end] [list_end] - - -[keywords math "statistical distribution" simulation "random numbers"] [manpage_end] Index: modules/smtpd/smtpd.man ================================================================== --- modules/smtpd/smtpd.man +++ modules/smtpd/smtpd.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin smtpd n 1.5] +[keywords {rfc 821}] +[keywords {rfc 2821}] +[keywords services] +[keywords smtp] +[keywords smtpd] +[keywords socket] +[keywords vwait] [copyright {Pat Thoyts }] [moddesc {Tcl SMTP Server Package}] [titledesc {Tcl SMTP server implementation}] [category Networking] [require Tcl 8.3] @@ -196,11 +203,11 @@ proc validate_sender {address} { eval array set addr [mime::parseaddress $address] if {[string match "denied" $addr(local)]} { error "mailbox $addr(local) denied" } - return + return } }] [para] @@ -278,19 +285,8 @@ This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file [file license.terms] for more details. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph smtpd] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords smtpd smtp services {rfc 821} {rfc 2821} vwait socket] +[vset CATEGORY smtpd] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/snit/snit.man ================================================================== --- modules/snit/snit.man +++ modules/snit/snit.man @@ -1,7 +1,19 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin snit n 2.3.2] +[keywords adaptors] +[keywords BWidget] +[keywords C++] +[keywords class] +[keywords {Incr Tcl}] +[keywords {mega widget}] +[keywords object] +[keywords {object oriented}] +[keywords Snit] +[keywords type] +[keywords widget] +[keywords {widget adaptors}] [copyright {2003-2009, by William H. Duquette}] [moddesc {Snit's Not Incr Tcl, OO system}] [titledesc {Snit's Not Incr Tcl}] [category {Programming tools}] [require Tcl 8.5] @@ -11,11 +23,11 @@ Snit is a pure Tcl object and megawidget system. It's unique among Tcl object systems in that it's based not on inheritance but on delegation. Object systems based on inheritance only allow you to inherit from classes defined using the same system, which is -limiting. In Tcl, an object is +limiting. In Tcl, an object is anything that acts like an object; it shouldn't matter how the object was implemented. Snit is intended to help you build applications out of the materials at hand; thus, Snit is designed to be able to incorporate and build on any object, whether it's a hand-coded object, a [package Tk] widget, an [package {Incr Tcl}] object, @@ -66,11 +78,11 @@ [list_begin definitions] [call [cmd typevariable] [arg name] [opt [const -array]] [opt [arg value]]] Defines a type variable with the specified [arg name], and optionally the specified [arg value]. Type variables are shared by all instances -of the type. If the [const -array] option is included, then +of the type. If the [const -array] option is included, then [arg value] should be a dictionary; it will be assigned to the variable using [cmd "array set"]. [call [cmd typemethod] [arg name] [arg arglist] [arg body]] @@ -83,11 +95,11 @@ [para] The variable [var type] is automatically defined in the [arg body] to the type's fully-qualified name. In addition, -type variables are automatically visible in the [arg body] +type variables are automatically visible in the [arg body] of every type method. [para] If the [arg name] consists of two or more tokens, Snit handles it specially: @@ -100,19 +112,19 @@ [example { $type a b "Hello, world!" }] [const a] may have any number of subcommands. This makes it possible -to define a hierarchical command structure; see [cmd method], below, +to define a hierarchical command structure; see [cmd method], below, for more examples. [para] Type methods can call commands from the namespace in which the type is -defined without importing them, e.g., if the type name is +defined without importing them, e.g., if the type name is [cmd ::parentns::typename], then the type's type methods can call -[cmd ::parentns::someproc] just as [cmd someproc]. +[cmd ::parentns::someproc] just as [cmd someproc]. [emph {Snit 1.x Incompatibility:}] This does not work in Snit 1.x, as it depends on [cmd "namespace path"], a new command in Tcl 8.5. [para] @@ -132,42 +144,42 @@ initialize array-valued type variables and to add entries to [sectref {The Tk Option Database}]. [para] -The variable [var type] is automatically defined in the [arg body], +The variable [var type] is automatically defined in the [arg body], and contains the type's fully-qualified name. In addition, -type variables are automatically visible in the [arg body] of the type +type variables are automatically visible in the [arg body] of the type constructor. [para] A type may define at most one type constructor. [para] The type constructor can call commands from the namespace in which the type is -defined without importing them, e.g., if the type name is +defined without importing them, e.g., if the type name is [cmd ::parentns::typename], then the type constructor can call -[cmd ::parentns::someproc] just as [cmd someproc]. +[cmd ::parentns::someproc] just as [cmd someproc]. [emph {Snit 1.x Incompatibility:}] This does not work in Snit 1.x, as it depends on [cmd "namespace path"], a new command in Tcl 8.5. [call [cmd variable] [arg name] [opt [const -array]] [opt [arg value]]] Defines an instance variable, a private variable associated with each -instance of this type, and optionally its initial value. -If the [const -array] option is included, then +instance of this type, and optionally its initial value. +If the [const -array] option is included, then [arg value] should be a dictionary; it will be assigned to the variable using [cmd "array set"]. [call [cmd method] [arg name] [arg arglist] [arg body]] Defines an instance method, a subcommand of each instance of this type, with the specified name, argument list and body. The [arg arglist] is a normal Tcl argument list and may contain -default arguments and the [var args] argument. +default arguments and the [var args] argument. [para] The method is implicitly passed the following arguments as well: @@ -225,13 +237,13 @@ explicitly. [para] Methods can call commands from the namespace in which the type is -defined without importing them, e.g., if the type name is +defined without importing them, e.g., if the type name is [cmd ::parentns::typename], then the type's methods can call -[cmd ::parentns::someproc] just as [cmd someproc]. +[cmd ::parentns::someproc] just as [cmd someproc]. [emph {Snit 1.x Incompatibility:}] This does not work in Snit 1.x, as it depends on [cmd "namespace path"], a new command in Tcl 8.5. [para] @@ -278,35 +290,35 @@ [para] Options are normally set and retrieved using the standard instance methods [method configure] and [method cget]; within instance code -(method bodies, etc.), option values are available through the +(method bodies, etc.), option values are available through the [var options] array: [example { set myfont $options(-font) }] -If the type defines any option handlers (e.g., [const -configuremethod]), -then it should probably use [method configure] and [method cget] to +If the type defines any option handlers (e.g., [const -configuremethod]), +then it should probably use [method configure] and [method cget] to access its options to avoid subtle errors. [para] The [cmd option] statement may include the following options: [list_begin definitions] [def "[const -default] [arg defvalue]"] -Defines the option's default value; the option's default value +Defines the option's default value; the option's default value will be "" otherwise. [def "[const -readonly] [arg flag]"] -The [arg flag] can be any Boolean value recognized by Tcl. +The [arg flag] can be any Boolean value recognized by Tcl. If [arg flag] is true, then the option is read-only--it can only -be set using [method configure] or [method configurelist] +be set using [method configure] or [method configurelist] at creation time, i.e., in the type's constructor. [def "[const -type] [arg type]"] Every locally-defined option may define its validation type, which may @@ -327,11 +339,11 @@ [example { option -number -type {snit::integer -min 1 -max 10} }] If a validation type or subtype is defined for an option, then it will be used to validate the option's value whenever it is -changed by the object's [method configure] or +changed by the object's [method configure] or [method configurelist] methods. In addition, all such options will have their values validated automatically immediately after the constructor executes. [para] @@ -345,11 +357,11 @@ [def "[const -cgetmethod] [arg methodName]"] Every locally-defined option may define a [const -cgetmethod]; it is called when the option's value is retrieved using the [method cget] method. Whatever the method's [arg body] returns will -be the return value of the call to [method cget]. +be the return value of the call to [method cget]. [para] The named method must take one argument, the option name. For example, this code is equivalent to (though slower than) @@ -359,11 +371,11 @@ method GetOption {option} { return $options($option) } }] -Note that it's possible for any number of options to share a +Note that it's possible for any number of options to share a [const -cgetmethod]. [def "[const -configuremethod] [arg methodName]"] Every locally-defined option may define a [const -configuremethod]; @@ -374,20 +386,20 @@ the method saves it there. [para] The named method must take two arguments, the option name and -its new value. For example, this code is equivalent to +its new value. For example, this code is equivalent to (though slower than) Snit's default handling of [cmd configure]: [example { option -font -configuremethod SetOption method SetOption {option value} { set options($option) $value } }] -Note that it's possible for any number of options to share a +Note that it's possible for any number of options to share a single [const -configuremethod]. [def "[const -validatemethod] [arg methodName]"] Every locally-defined option may define a [const -validatemethod]; @@ -398,11 +410,11 @@ and to throw an error if the value is invalid. [para] The named method must take two arguments, the option name and -its new value. For example, this code verifies that +its new value. For example, this code verifies that [const -flag]'s value is a valid Boolean value: [example { option -font -validatemethod CheckBoolean method CheckBoolean {option value} { if {![string is boolean -strict $value]} { @@ -409,41 +421,41 @@ error "option $option must have a boolean value." } } }] -Note that it's possible for any number of options to share a +Note that it's possible for any number of options to share a single [const -validatemethod]. [list_end] [call [cmd constructor] [arg arglist] [arg body]] The constructor definition specifies a [arg body] of code to be -executed when a new instance is created. The [arg arglist] is a -normal Tcl argument list and may contain default arguments and +executed when a new instance is created. The [arg arglist] is a +normal Tcl argument list and may contain default arguments and the [var args] argument. [para] -As with methods, the arguments [var type], [var self], [var selfns], -and [var win] are defined implicitly, and all type and instance +As with methods, the arguments [var type], [var self], [var selfns], +and [var win] are defined implicitly, and all type and instance variables are automatically visible in its [arg body]. [para] If the [arg definition] doesn't explicitly define the constructor, Snit defines one implicitly. If the type declares at least one option -(whether locally or by delegation), the default constructor will +(whether locally or by delegation), the default constructor will be defined as follows: [example { constructor {args} { $self configurelist $args } }] -For standard Tk widget behavior, the argument list should be +For standard Tk widget behavior, the argument list should be the single name [const args], as shown. [para] If the [arg definition] defines neither a constructor nor @@ -452,13 +464,13 @@ [example { constructor {} {} }] As with methods, the constructor can call commands from the namespace in which the type is -defined without importing them, e.g., if the type name is +defined without importing them, e.g., if the type name is [cmd ::parentns::typename], then the constructor can call -[cmd ::parentns::someproc] just as [cmd someproc]. +[cmd ::parentns::someproc] just as [cmd someproc]. [emph {Snit 1.x Incompatibility:}] This does not work in Snit 1.x, as it depends on [cmd "namespace path"], a new command in Tcl 8.5. [call [cmd destructor] [arg body]] @@ -466,20 +478,20 @@ an instance of the type is destroyed: typically, the destruction of anything created in the constructor. [para] -The destructor takes no explicit arguments; as with methods, the -arguments [var type], [var self], [var selfns], and [var win], are -defined implicitly, and all type and instance +The destructor takes no explicit arguments; as with methods, the +arguments [var type], [var self], [var selfns], and [var win], are +defined implicitly, and all type and instance variables are automatically visible in its [arg body]. As with methods, the destructor can call commands from the namespace in which the type is -defined without importing them, e.g., if the type name is +defined without importing them, e.g., if the type name is [cmd ::parentns::typename], then the destructor can call -[cmd ::parentns::someproc] just as [cmd someproc]. +[cmd ::parentns::someproc] just as [cmd someproc]. [emph {Snit 1.x Incompatibility:}] This does not work in Snit 1.x, as it depends on [cmd "namespace path"], a new command in Tcl 8.5. [call [cmd proc] [arg name] [arg args] [arg body]] @@ -486,11 +498,11 @@ Defines a new Tcl procedure in the type's namespace. [para] The defined proc differs from a normal Tcl proc in that all type -variables are automatically visible. The proc can access +variables are automatically visible. The proc can access instance variables as well, provided that it is passed [var selfns] (with precisely that name) as one of its arguments. [para] @@ -499,13 +511,13 @@ [para] As with methods and typemethods, procs can call commands from the namespace in which the type is -defined without importing them, e.g., if the type name is +defined without importing them, e.g., if the type name is [cmd ::parentns::typename], then the proc can call -[cmd ::parentns::someproc] just as [cmd someproc]. +[cmd ::parentns::someproc] just as [cmd someproc]. [emph {Snit 1.x Incompatibility:}] This does not work in Snit 1.x, as it depends on [cmd "namespace path"], a new command in Tcl 8.5. [call [cmd delegate] [const method] [arg name] [const to] [arg comp] [opt "[const as] [arg target]"]] @@ -546,18 +558,18 @@ both instance components and type components. [call [cmd delegate] [const method] [arg name] [opt "[const to] [arg comp]"] [const using] [arg pattern]] In this form of the [cmd delegate] statement, the [const using] clause -is used to specify the precise form of the command to which method +is used to specify the precise form of the command to which method [arg name] name is delegated. In this form, the [const "to"] clause is optional, since the chosen command might not involve any particular component. [para] -The value of the [const using] clause is a list that may contain +The value of the [const using] clause is a list that may contain any or all of the following substitution codes; these codes are substituted with the described value to build the delegated command prefix. Note that the following two statements are equivalent: [example { delegate method wag to tail @@ -687,11 +699,11 @@ [call [cmd component] [arg comp] \ [opt "[const -public] [arg method]"] \ [opt "[const -inherit] [arg flag]"]] Explicitly declares a component called [arg comp], and automatically -defines the component's instance variable. +defines the component's instance variable. [para] If the [const -public] option is specified, then the option is made public by defining a [arg method] whose subcommands are delegated @@ -748,18 +760,18 @@ A type method cannot be both locally defined and delegated. [call [cmd delegate] [const typemethod] [arg name] [opt "[const to] [arg comp]"] [const using] [arg pattern]] In this form of the [cmd delegate] statement, the [const using] clause -is used to specify the precise form of the command to which type method +is used to specify the precise form of the command to which type method [arg name] name is delegated. In this form, the [const "to"] clause is optional, since the chosen command might not involve any particular type component. [para] -The value of the [const using] clause is a list that may contain +The value of the [const using] clause is a list that may contain any or all of the following substitution codes; these codes are substituted with the described value to build the delegated command prefix. Note that the following two statements are equivalent: [example { delegate typemethod lostdogs to pound @@ -817,11 +829,11 @@ [para] [const Note:] By default, Snit interprets [cmd "\$type foo"], where [const "foo"] is not a defined type method, as equivalent to [cmd "\$type create foo"], where -[const "foo"] is the name of a new instance of the type. If you +[const "foo"] is the name of a new instance of the type. If you use [const "delegate typemethod *"], then the [method "create"] type method must always be used explicitly. [para] @@ -845,11 +857,11 @@ [para] If the [const -public] option is specified, then the type component is made public by defining a [arg typemethod] whose subcommands are delegated to -the type component, e.g., specifying [const "-public mytypemethod"] +the type component, e.g., specifying [const "-public mytypemethod"] is equivalent to the following: [example { typecomponent mycomp delegate typemethod {mytypemethod *} to mycomp }] @@ -867,11 +879,11 @@ [call [cmd pragma] [opt [arg options...]]] The [cmd pragma] statement provides control over how Snit generates a type. It takes the following options; in each case, [arg flag] must -be a Boolean value recognized by Tcl, e.g., [const 0], [const 1], +be a Boolean value recognized by Tcl, e.g., [const 0], [const 1], [const "yes"], [const "no"], and so on. [para] @@ -901,11 +913,11 @@ instances. The [cmd destroy] type method is documented below. If false, it will not. [def "[const -hastypemethods] [arg flag]"] -If true (the default), the generated type's type command will have +If true (the default), the generated type's type command will have subcommands (type methods) as usual. If false, the type command will serve only to create instances of the type; the first argument is the instance name. [para] @@ -912,23 +924,23 @@ This pragma and [const -hasinstances] cannot both be set false. [def "[const -hasinstances] [arg flag]"] -If true (the default), the generated type will have a type method +If true (the default), the generated type will have a type method called [cmd create] that is used to create instances of the type, along with a variety of instance-related features. If false, it will -not. +not. [para] This pragma and [const -hastypemethods] cannot both be set false. [def "[const -hasinfo] [arg flag]"] -If true (the default), instances of the generated type will have -an instance method called [method info] that is used for +If true (the default), instances of the generated type will have +an instance method called [method info] that is used for instance introspection; the [method info] method is documented below. If false, it will not. [def "[const -simpledispatch] [arg flag]"] @@ -937,19 +949,19 @@ [para] If false (the default), instance methods are dispatched normally. If true, a faster dispatching scheme is used instead. -The speed comes at a price; with [const "-simpledispatch yes"] you +The speed comes at a price; with [const "-simpledispatch yes"] you get the following limitations: [list_begin itemized] [item] Methods cannot be delegated. [item] [cmd uplevel] and [cmd upvar] do not work as expected: the caller's scope is two levels up rather than one. -[item] The option-handling methods +[item] The option-handling methods ([cmd cget], [cmd configure], and [cmd configurelist]) are very slightly slower. [list_end] [list_end] @@ -965,11 +977,11 @@ [const Deprecated.] To expose component [arg comp] publicly, use [cmd component]'s [const -public] option. [call [cmd onconfigure] [arg name] [arg arglist] [arg body]] -[const Deprecated.] Define [cmd option]'s [const -configuremethod] +[const Deprecated.] Define [cmd option]'s [const -configuremethod] option instead. [para] As of version 0.95, the following definitions, @@ -988,11 +1000,11 @@ } }] [call [cmd oncget] [arg name] [arg body]] -[const Deprecated.] Define [cmd option]'s [const -cgetmethod] +[const Deprecated.] Define [cmd option]'s [const -cgetmethod] option instead. [para] As of version 0.95, the following definitions, @@ -1010,11 +1022,10 @@ # Code to return the option's value } }] [list_end] - [call [cmd snit::widget] [arg name] [arg definition]] This command defines a Snit megawidget type with the specified [arg name]. The [arg definition] is defined as for [cmd snit::type]. @@ -1058,20 +1069,20 @@ [call [cmd hulltype] [arg type]] Determines the kind of widget used as the [cmd snit::widget]'s hull. The [arg type] may be [const frame] (the default), [const toplevel], -[const labelframe]; the qualified equivalents of these, +[const labelframe]; the qualified equivalents of these, [const tk::frame], [const tk::toplevel], and [const tk::labelframe]; or, if available, the equivalent Tile widgets: -[const ttk::frame], [const ttk::toplevel], and +[const ttk::frame], [const ttk::toplevel], and [const ttk::labelframe]. In practice, any widget that supports the -[const -class] option can be used as a hull widget by +[const -class] option can be used as a hull widget by [cmd lappend]'ing its name to the variable [var snit::hulltypes]. [list_end] - + [call [cmd snit::widgetadaptor] [arg name] [arg definition]] This command defines a Snit megawidget type with the specified name. It differs from [cmd snit::widget] in that the instance's [var hull] component is not created automatically, but is created in the @@ -1109,19 +1120,19 @@ page. [para] A macro is simply a Tcl proc that is defined in the slave interpreter -used to compile type and widget definitions. Thus, macros have -access to all of the type and widget definition statements. See +used to compile type and widget definitions. Thus, macros have +access to all of the type and widget definition statements. See [sectref "Macros and Meta-programming"] for more details. [para] -The macro [arg name] cannot be the same as any standard Tcl command, +The macro [arg name] cannot be the same as any standard Tcl command, or any Snit type or widget definition statement, e.g., you can't -redefine the [cmd method] or [cmd delegate] statements, or the +redefine the [cmd method] or [cmd delegate] statements, or the standard [cmd set], [cmd list], or [cmd string] commands. [call [cmd snit::compile] [arg which] [arg type] [arg body]] Snit defines a type, widget, or widgetadaptor by "compiling" the @@ -1129,11 +1140,11 @@ Tcl interpreter, which actually defines the new type. [para] This command exposes the "compiler". Given a definition [arg body] -for the named [arg type], where [arg which] is [const type], +for the named [arg type], where [arg which] is [const type], [const widget], or [const widgetadaptor], [cmd snit::compile] returns a list of two elements. The first element is the fully qualified type name; the second element is the definition script. [para] @@ -1155,32 +1166,32 @@ [para] [list_begin definitions] [call [cmd {$type}] [arg typemethod] [arg args]...] -The [arg typemethod] can be any of the -[sectref "Standard Type Methods"] (e.g., [method create]), +The [arg typemethod] can be any of the +[sectref "Standard Type Methods"] (e.g., [method create]), or any type method defined in the type definition. The subsequent [arg args] depend on the specific [arg typemethod] chosen. [para] -The type command is most often used to create new instances of the +The type command is most often used to create new instances of the type; hence, the [method create] method is assumed if the first argument to the type command doesn't name a valid type method, unless -the type definition includes [cmd "delegate typemethod *"] or the +the type definition includes [cmd "delegate typemethod *"] or the [const -hasinstances] pragma is set to false. [para] Furthermore, if the [const -hastypemethods] pragma is false, then Snit type commands can be called with no arguments at all; in this case, the type command creates an instance with an -automatically generated name. In other words, provided that the +automatically generated name. In other words, provided that the [const -hastypemethods] pragma is false and the type has instances, the following commands are equivalent: [example {snit::type dog { ... } @@ -1226,11 +1237,11 @@ [para] So long as [arg name] does not conflict with any defined type method name the [method create] keyword may be omitted, unless -the type definition includes [cmd "delegate typemethod *"] or the +the type definition includes [cmd "delegate typemethod *"] or the [const -hasinstances] pragma is set to false. [para] If the [arg name] includes the string [const %AUTO%], it will be @@ -1249,11 +1260,10 @@ As of Snit V0.95, [method create] will throw an error if the [arg name] is the same as any existing command--note that this was always true for [cmd snit::widget]s and [cmd snit::widgetadaptor]s. You can restore the previous behavior using the [const -canreplace] pragma. - [call [cmd {$type}] [method {info typevars}] [opt [arg pattern]]] Returns a list of the type's type variables (excluding Snit internal variables); all variable names are fully-qualified. @@ -1260,51 +1270,46 @@ [para] If [arg pattern] is given, it's used as a [cmd {string match}] pattern; only names that match the pattern are returned. - [call [cmd {$type}] [method {info typemethods}] [opt [arg pattern]]] -Returns a list of the names of the type's type methods. -If the type has hierarchical +Returns a list of the names of the type's type methods. +If the type has hierarchical type methods, whether locally-defined or delegated, only the first word of each will be included in the list. [para] If the type definition includes [cmd "delegate typemethod *"], the list will -include only the names of those implicitly delegated type methods +include only the names of those implicitly delegated type methods that have been called at least once and are still in the type method cache. [para] If [arg pattern] is given, it's used as a [cmd {string match}] pattern; only names that match the pattern are returned. - [call [cmd {$type}] [method {info args}] [arg method]] Returns a list containing the names of the arguments to the type's [arg method], in order. This method cannot be applied to delegated type methods. - [call [cmd {$type}] [method {info body}] [arg method]] Returns the body of typemethod [arg method]. This method cannot be applied to delegated type methods. - [call [cmd {$type}] [method {info default}] [arg method] [arg aname] [arg varname]] Returns a boolean value indicating whether the argument [arg aname] of the type's [arg method] has a default value ([const true]) or not ([const false]). If the argument has a default its value is placed into the variable [arg varname]. - [call [cmd {$type}] [method {info instances}] [opt [arg pattern]]] Returns a list of the type's instances. For [cmd snit::type]s, it will be a list of fully-qualified instance names; @@ -1337,12 +1342,12 @@ [para] [list_begin definitions] [call [cmd {$object}] [arg method] [arg args...]] -The [arg method] can be any of the -[sectref "Standard Instance Methods"], or any instance method +The [arg method] can be any of the +[sectref "Standard Instance Methods"], or any instance method defined in the type definition. The subsequent [arg args] depend on the specific [arg method] chosen. [list_end] @@ -1406,15 +1411,13 @@ The [method destroy] method isn't defined for [cmd snit::widget] or [cmd snit::widgetadaptor] objects; instances of these are destroyed by calling [package Tk]'s [cmd destroy] command, just as normal widgets are. - [call [cmd {$object}] [method {info type}]] Returns the instance's type. - [call [cmd {$object}] [method {info vars}] [opt [arg pattern]]] Returns a list of the object's instance variables (excluding Snit internal variables). The names are fully qualified. @@ -1421,11 +1424,10 @@ [para] If [arg pattern] is given, it's used as a [cmd {string match}] pattern; only names that match the pattern are returned. - [call [cmd {$object}] [method {info typevars}] [opt [arg pattern]]] Returns a list of the object's type's type variables (excluding Snit internal variables). The names are fully qualified. @@ -1433,23 +1435,22 @@ [para] If [arg pattern] is given, it's used as a [cmd {string match}] pattern; only names that match the pattern are returned. - [call [cmd {$object}] [method {info typemethods}] [opt [arg pattern]]] -Returns a list of the names of the type's type methods. -If the type has hierarchical +Returns a list of the names of the type's type methods. +If the type has hierarchical type methods, whether locally-defined or delegated, only the first word of each will be included in the list. [para] If the type definition includes [cmd "delegate typemethod *"], the list will -include only the names of those implicitly delegated type methods +include only the names of those implicitly delegated type methods that have been called at least once and are still in the type method cache. [para] If [arg pattern] is given, it's used as a [cmd {string match}] @@ -1481,11 +1482,11 @@ to another. [call [cmd {$object}] [method {info methods}] [opt [arg pattern]]] Returns a list of the names of the instance's methods. -If the type has hierarchical methods, whether locally-defined or +If the type has hierarchical methods, whether locally-defined or delegated, only the first word of each will be included in the list. [para] If the type @@ -1501,30 +1502,26 @@ [para] [emph "Snit 1.x Incompatibility:"] In Snit 1.x, the full multi-word names of hierarchical type methods are included in the return value. - [call [cmd {$object}] [method {info args}] [arg method]] Returns a list containing the names of the arguments to the instance's [arg method], in order. This method cannot be applied to delegated methods. - [call [cmd {$object}] [method {info body}] [arg method]] Returns the body of the instance's method [arg method]. This method cannot be applied to delegated methods. - [call [cmd {$object}] [method {info default}] [arg method] [arg aname] [arg varname]] Returns a boolean value indicating whether the argument [arg aname] of the instance's [arg method] has a default value ([const true]) or not ([const false]). If the argument has a default its value is placed into the variable [arg varname]. - [list_end] [subsection {Commands for use in Object Code}] @@ -1532,24 +1529,23 @@ that is, for use in type methods, instance methods, constructors, destructors, onconfigure handlers, oncget handlers, and procs. They do not reside in the ::snit:: namespace; instead, they are created with the type, and can be used without qualification. - [list_begin definitions] [call [cmd mymethod] [arg name] [opt [arg args...]]] The [cmd mymethod] command is used for formatting callback commands to be passed to other objects. It returns a command that when called will invoke method [arg name] with the specified arguments, plus of course any arguments added by the caller. In other words, both of the -following commands will cause the object's +following commands will cause the object's [method dosomething] method to be called when the [cmd {$button}] is pressed: [example { $button configure -command [list $self dosomething myargument] - + $button configure -command [mymethod dosomething myargument] }] The chief distinction between the two is that the latter form will not break if the object's command is renamed. @@ -1562,11 +1558,11 @@ course any arguments added by the caller. In other words, both of the following commands will cause the object's [method dosomething] type method to be called when [cmd {$button}] is pressed: [example { $button configure -command [list $type dosomething myargument] - + $button configure -command [mytypemethod dosomething myargument] }] Type commands cannot be renamed, so in practice there's little difference between the two forms. [cmd mytypemethod] is provided for @@ -1580,11 +1576,11 @@ course any arguments added by the caller. In other words, both of the following commands will cause the object's [method dosomething] proc to be called when [cmd {$button}] is pressed: [example { $button configure -command [list ${type}::dosomething myargument] - + $button configure -command [myproc dosomething myargument] }] [call [cmd myvar] [arg name]] @@ -1617,11 +1613,11 @@ type definition will be returned instead. [call [cmd install] [arg compName] [const using] [arg objType] [arg objName] [arg args...]] Creates a new object of type [arg objType] called [arg objName] -and installs it as component [arg compName], +and installs it as component [arg compName], as described in [sectref {Components and Delegation}]. Any additional [arg args...] are passed along with the name to the [arg objType] command. If this is a [cmd snit::type], then the following two commands are @@ -1699,19 +1695,19 @@ It's generally clearest to define all instance variables in the type definition, and omit declaring them in methods and so forth. [para] -Note that this is an instance-specific version of the standard Tcl +Note that this is an instance-specific version of the standard Tcl [cmd ::variable] command. [call [cmd typevariable] [arg name]] Normally, type variables are defined in the type definition, along with the instance variables; such type variables are automatically visible in all of the type's code. However, type methods, instance -methods and so forth can use [cmd typevariable] to declare type +methods and so forth can use [cmd typevariable] to declare type variables that don't appear in the type definition. [para] It's generally clearest to declare all type variables in the type @@ -1724,11 +1720,10 @@ [para] Given an instance variable name, returns the fully qualified name. Use this if you're passing the variable to some other object, e.g., as a [option -textvariable] to a Tk label widget. - [call [cmd typevarname] [arg name]] [const Deprecated.] Use [cmd mytypevar] instead. @@ -1752,28 +1747,28 @@ When an object includes other objects, as when a toolbar contains buttons or a GUI object contains an object that references a database, the included object is called a component. The standard way to handle component objects owned by a Snit object is to declare them using -[cmd component], which creates a component instance variable. +[cmd component], which creates a component instance variable. In the following example, a [cmd dog] object has a [cmd tail] object: [para] [example { snit::type dog { component mytail - + constructor {args} { set mytail [tail %AUTO% -partof $self] $self configurelist $args } - + method wag {} { $mytail wag } } - + snit::type tail { option -length 5 option -partof method wag {} { return "Wag, wag, wag."} } @@ -1817,11 +1812,11 @@ this: [para] [example { snit::type dog { delegate method wag to mytail - + constructor {args} { install mytail using tail %AUTO% -partof $self $self configurelist $args } } @@ -1860,11 +1855,11 @@ will simply raise an error. [para] Option delegation is similar to method delegation, except for the -interactions with the Tk option database; this is described in +interactions with the Tk option database; this is described in [sectref "The Tk Option Database"]. [subsection {Type Components and Delegation}] The relationship between type components and instance components is @@ -1876,11 +1871,11 @@ instance of the type. [para] Just as [cmd "delegate method"] can be used to delegate methods to -instance components, as described in +instance components, as described in [sectref "Components and Delegation"], so [cmd "delegate typemethod"] can be used to delegate type methods to type components. [para] @@ -1985,14 +1980,14 @@ the resource name with an initial capital, but not always. For example, here are the option, resource, and class names for several [cmd text] widget options: [para] -[example { -background background Background - -borderwidth borderWidth BorderWidth - -insertborderwidth insertBorderWidth BorderWidth - -padx padX Pad +[example { -background background Background + -borderwidth borderWidth BorderWidth + -insertborderwidth insertBorderWidth BorderWidth + -padx padX Pad }] [para] As is easily seen, sometimes the resource and class names can be inferred from the option name, but not always. @@ -2052,11 +2047,11 @@ The class name will default to "BorderWidth", as expected. [para] -Suppose, however, that [cmd mywidget] also delegated +Suppose, however, that [cmd mywidget] also delegated [option -padx] and [option -pady] to the hull. In this case, both the resource name and the class name must be specified explicitly: [para] @@ -2145,14 +2140,14 @@ [para] The value of B is "red". The hull will automatically pick up the value "green" for its [option -background] option, just as it picked up the -[option -relief] value. However, Snit knows that +[option -relief] value. However, Snit knows that [option -hullbackground] is mapped to the hull's [option -background] option; hence, it queries the option database -for [option -hullbackground] and gets "red" and updates the hull +for [option -hullbackground] and gets "red" and updates the hull accordingly. [para] The value of C is also "red", because [option -background] is implicitly @@ -2163,14 +2158,14 @@ [para] The value of D is "5", but not for the reason you think. Note that as it is defined above, the resource name for [option -borderwidth] -defaults to "borderwidth", whereas the option database entry is -"borderWidth". As with [option -relief], the hull picks up its +defaults to "borderwidth", whereas the option database entry is +"borderWidth". As with [option -relief], the hull picks up its own [option -borderwidth] option before Snit does anything. Because the -option is delegated under its own name, Snit assumes that the correct +option is delegated under its own name, Snit assumes that the correct thing has happened, and doesn't worry about it any further. [para] For [cmd snit::widgetadaptor]s, the case is somewhat altered. Widget @@ -2311,11 +2306,11 @@ method setmood {newmood} { set mood $newmood } } }] - + That's nine lines of text per property. Or, you could define the following [cmd snit::macro]: [example { snit::macro property {name initValue} { variable $name $initValue @@ -2364,11 +2359,11 @@ [para] [subsection "Validation Types"] A validation type is an object that can be used to validate -Tcl values of a particular kind. For example, +Tcl values of a particular kind. For example, [cmd snit::integer] is used to validate that a Tcl value is an integer. [para] @@ -2416,18 +2411,18 @@ option -breed -type { snit::enum -values {mutt retriever sheepdog} } # Or use predefined subtypes... - option -breed -type ::dog::breed + option -breed -type ::dog::breed } }] [para] Any object that has a [method validate] method with the semantics -described above can be used as a validation type; see +described above can be used as a validation type; see [sectref "Defining Validation Types"] for information on how to define new ones. [para] @@ -2491,17 +2486,17 @@ [list_begin definitions] [def "[const -min] [arg min]"] Specifies a minimum bound; a value is invalid if it is strictly -less than [arg min]. The bound may be expressed in any of the +less than [arg min]. The bound may be expressed in any of the forms accepted by [cmd "winfo fpixels"]. [def "[const -max] [arg max]"] Specifies a maximum bound; a value is invalid if it is strictly -greater than [arg max]. The bound may be expressed in any of the +greater than [arg max]. The bound may be expressed in any of the forms accepted by [cmd "winfo fpixels"]. [list_end] [call [cmd snit::integer] [const validate] [opt [arg value]]] @@ -2537,11 +2532,11 @@ Specifies a minimum list length; the value is invalid if it has fewer than [arg min] elements. Defaults to 0. [def "[const -maxlen] [arg max]"] -Specifies a maximum list length; the value is invalid if it +Specifies a maximum list length; the value is invalid if it more than [arg max] elements. [def "[const -type] [arg type]"] Specifies the type of the list elements; [arg type] must be @@ -2567,11 +2562,10 @@ snit::type mytype { option -numbers -type {snit::listtype -type gt4} } }] - [list_end] [call [cmd snit::pixels] [const validate] [opt [arg value]]] [call [cmd snit::pixels] [arg name] [opt "[arg option] [arg value]..."]] @@ -2582,21 +2576,20 @@ [list_begin definitions] [def "[const -min] [arg min]"] Specifies a minimum bound; a value is invalid if it is strictly -less than [arg min]. The bound may be expressed in any of the +less than [arg min]. The bound may be expressed in any of the forms accepted by [cmd "winfo pixels"]. [def "[const -max] [arg max]"] Specifies a maximum bound; a value is invalid if it is strictly -greater than [arg max]. The bound may be expressed in any of the +greater than [arg max]. The bound may be expressed in any of the forms accepted by [cmd "winfo pixels"]. [list_end] - [call [cmd snit::stringtype] [const validate] [opt [arg value]]] [call [cmd snit::stringtype] [arg name] [opt "[arg option] [arg value]..."]] Validates Tcl strings. The base type is of little use by itself, @@ -2637,11 +2630,11 @@ [call [cmd snit::window] [arg name]] [emph "Tk programs only."] Validates Tk window names. The value must cause [cmd "winfo exists"] to return true; otherwise, the value is invalid. It's possible to define subtypes--that is, instances--of -[cmd snit::window], but as it has no options at present there's no +[cmd snit::window], but as it has no options at present there's no reason to do so. [list_end] [para] @@ -2654,11 +2647,11 @@ Defining subtypes of Snit's validation types is described above, under [sectref "Validation Types"]. [para] -The next simplest way to create a new validation type is as a +The next simplest way to create a new validation type is as a validation type command. A validation type is simply an object that has a [method validate] method; the [method validate] method must take one argument, a value, return the value if it is valid, and throw an error with [cmd -errorcode] INVALID if the value is invalid. This can be done with a simple [cmd proc]. For @@ -2665,11 +2658,11 @@ example, the [cmd snit::boolean] validate type could have been implemented like this: [example { proc ::snit::boolean {"validate" value} { if {![string is boolean -strict $value]} { - return -code error -errorcode INVALID \ + return -code error -errorcode INVALID \ "invalid boolean \"$value\", should be one of: 1, 0, ..." } return $value } @@ -2695,15 +2688,15 @@ option -min -default "" -readonly 1 option -max -default "" -readonly 1 # Next, define a "validate" type method which should do the # validation in the basic case. This will allow the - # type command to be used as a validation type. + # type command to be used as a validation type. typemethod validate {value} { if {![string is integer -strict $value]} { - return -code error -errorcode INVALID \ + return -code error -errorcode INVALID \ "invalid value \"$value\", expected integer" } return $value } @@ -2734,11 +2727,11 @@ ("" != $options(-max) && $value > $options(-max))} { # It's out of range; format a detailed message about # the error, and throw it. set msg "...." - + return -code error -errorcode INVALID $msg } # Otherwise, if it's valid just return it. return $valid @@ -2749,25 +2742,21 @@ And now you have a type that can be subtyped. [para] The file "validate.tcl" in the Snit distribution defines all of Snit's -validation types; you can find the complete implementation for +validation types; you can find the complete implementation for [cmd snit::integer] and the other types there, to use as examples for your own types. [para] [section CAVEATS] If you have problems, find bugs, or new ideas you are hereby cordially -invited to submit a report of your problem, bug, or idea at the -SourceForge trackers for tcllib, which can be found at - -[uri http://sourceforge.net/projects/tcllib/]. - -The relevant category is [emph snit]. +invited to submit a report of your problem, bug, or idea as explained +in the section [sectref {Bugs, Ideas, Feedback}] below. [para] Additionally, you might wish to join the Snit mailing list; see [uri http://www.wjduquette.com/snit] for details. @@ -2788,15 +2777,14 @@ contain far too much information about Snit internals. The error messages are much improved in Snit 2.2. [item] -Also see the SourceForge Trackers at -[uri http://sourceforge.net/projects/tcllib/], category [emph snit]. +Also see the Project Trackers as explained in the section +[sectref {Bugs, Ideas, Feedback}] below. [list_end] - [section HISTORY] During the course of developing Notebook (See [uri http://www.wjduquette.com/notebook]), my Tcl-based personal @@ -2831,35 +2819,21 @@ there's a Snit mailing list; you can find out more about it at the Snit home page (see [uri http://www.wjduquette.com/snit]). [para] - [section CREDITS] Snit has been designed and implemented from the very beginning by William H. Duquette. However, much credit belongs to the following people for using Snit and providing me with valuable feedback: Rolf Ade, Colin McCormack, Jose Nazario, Jeff Godfrey, Maurice Diamanti, -Egon Pasztor, David S. Cargo, Tom Krehbiel, Michael Cleverly, +Egon Pasztor, David S. Cargo, Tom Krehbiel, Michael Cleverly, Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, Brian -Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, -and Anton Kovalenko. -If I've forgotten anyone, my apologies; let me know and I'll add +Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, +and Anton Kovalenko. +If I've forgotten anyone, my apologies; let me know and I'll add your name to the list. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph snit] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords class {object oriented} object C++] -[keywords Snit type {Incr Tcl} BWidget] -[keywords widget adaptors {widget adaptors} {mega widget}] +[vset CATEGORY snit] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/snit/snitfaq.man ================================================================== --- modules/snit/snitfaq.man +++ modules/snit/snitfaq.man @@ -1,7 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin snitfaq n 2.2] +[keywords adaptors] +[keywords BWidget] +[keywords C++] +[keywords class] +[keywords {Incr Tcl}] +[keywords {mega widget}] +[keywords object] +[keywords {object oriented}] +[keywords widget] +[keywords {widget adaptors}] [copyright {2003-2006, by William H. Duquette}] [moddesc {Snit's Not Incr Tcl, OO system}] [titledesc {Snit Frequently Asked Questions}] [category {Programming tools}] [description] @@ -17,12 +27,12 @@ Snit, however; that information is in the [cmd snit] man page. [subsection {What is Snit?}] Snit is a framework for defining abstract data types and megawidgets -in pure Tcl. The name "Snit" stands for "Snit's Not Incr Tcl", -signifying that Snit takes a different approach to defining objects +in pure Tcl. The name "Snit" stands for "Snit's Not Incr Tcl", +signifying that Snit takes a different approach to defining objects than does Incr Tcl, the best known object framework for Tcl. Had I realized that Snit would become at all popular, I'd probably have chosen something else. [para] @@ -35,11 +45,11 @@ [para] Snit isn't about theoretical purity or minimalist design; it's about being able to do powerful things easily and consistently without having to think about them--so that you can concentrate on building -your application. +your application. [para] Snit isn't about implementing thousands of nearly identical carefully-specified lightweight thingamajigs--not as individual Snit @@ -48,18 +58,18 @@ to manage a collection of thousands of nearly identical carefully-specified lightweight thingamajigs (e.g., think of the text widget and text tags, or the canvas widget and canvas objects). Snit lets you hide the details of just how those thingamajigs are stored--so that you can ignore it, and concentrate on building your -application. +application. [para] Snit isn't a way of life, a silver bullet, or the Fountain of Youth. It's just a way of managing complexity--and of managing some of the complexity of managing complexity--so that you can concentrate on -building your application. +building your application. [subsection {What version of Tcl does Snit require?}] Snit 1.3 requires Tcl 8.3 or later; Snit 2.2 requires Tcl 8.5 or later. See [sectref {SNIT VERSIONS}] for the differences between Snit @@ -119,11 +129,11 @@ incorporate and build on any object, whether it's a hand-coded object, a Tk widget, an Incr Tcl object, a BWidget or almost anything else. [para] -Note that you can achieve the effect of inheritance using +Note that you can achieve the effect of inheritance using [sectref COMPONENTS] and [sectref "DELEGATION"]--and you can inherit from anything that looks like a Tcl object. [subsection {What can I do with Snit?}] @@ -205,11 +215,11 @@ [subsection {How are Snit 1.3 and Snit 2.2 incompatible?}] To the extent possible, Snit 2.2 is intended to be a drop-in replacement for Snit 1.3. Unfortunately, some incompatibilities were -inevitable because Snit 2.2 uses Tcl 8.5's new +inevitable because Snit 2.2 uses Tcl 8.5's new [cmd "namespace ensemble"] mechanism to implement subcommand dispatch. This approach is much faster than the mechanism used in Snit 1.3, and also results in much better error messages; however, it also places new constraints on the implementation. @@ -231,37 +241,37 @@ set obj2 [dog] ;# Implicit naming }] In Snit 2.2, type commands are defined using the [cmd "namespace ensemble"] mechanism; and [cmd "namespace ensemble"] doesn't allow an ensemble command -to be called without a subcommand. In short, using +to be called without a subcommand. In short, using [cmd "namespace ensemble"] there's no way to support implicit naming. [para] All is not lost, however. If the type has no type methods, then the -type command is a simple command rather than an ensemble, and +type command is a simple command rather than an ensemble, and [cmd "namespace ensemble"] is not used. In this case, implicit naming is still possible. [para] In short, you can have implicit naming if you're willing to do without -type methods (including the standard type methods, like +type methods (including the standard type methods, like [cmd "\$type info"]). To do so, use the [const -hastypemethods] pragma: [example {pragma -hastypemethods 0}] [item] Hierarchical methods and type methods are implemented differently in -Snit 2.2. +Snit 2.2. [para] A hierarchical method is an instance method which has subcommands; these subcommands are themselves methods. The Tk text -widget's [cmd tag] command and its subcommands are examples of +widget's [cmd tag] command and its subcommands are examples of hierarchical methods. You can implement such subcommands in Snit simply by including multiple words in the method names: [example {method {tag configure} {tag args} { ... } @@ -289,11 +299,11 @@ [item] The third incompatibility derives from the second. In Snit 1.3, hierarchical methods were also simply methods whose name contains multiple words. As a result, [cmd "\$obj info methods"] returned the -full names of all hierarchical methods. In the example above, +full names of all hierarchical methods. In the example above, the list returned by [cmd "\$obj info methods"] would include [cmd "tag configure"] and [cmd "tag cget"] but not [cmd "tag"], since [cmd "tag"] is defined only implicitly. [para] @@ -302,18 +312,17 @@ simply ones whose name contains multiple words; in the above example, the list returned by [cmd "\$obj info methods"] would include [cmd "tag"] but not [cmd "tag configure"] or [cmd "tag cget"]. - [item] The fourth incompatibility is due to a new feature. Snit 2.2 uses -the new [cmd "namespace path"] command so that a type's code can +the new [cmd "namespace path"] command so that a type's code can call any command defined in the type's parent namespace without -qualification or importation. For example, suppose you have a +qualification or importation. For example, suppose you have a package called [cmd "mypackage"] which defines a number of commands -including a type, [cmd "::mypackage::mytype"]. Thanks to +including a type, [cmd "::mypackage::mytype"]. Thanks to [cmd "namespace path"], the type's code can call any of the other commands defined in [cmd "::mypackage::"]. [para] @@ -322,11 +331,11 @@ type's access to identically named commands in the global namespace. This can lead to bugs. For example, Tcllib includes a type called [cmd "::tie::std::file"]. This type's code calls the standard [cmd "file"] command. When run with Snit 2.2, the code broke-- the type's command, [cmd "::tie::std::file"], is itself a command -in the type's parent namespace, and so instead of calling +in the type's parent namespace, and so instead of calling the standard [cmd "file"] command, the type found itself calling itself. [list_end] @@ -343,11 +352,11 @@ [item] The [const -simpledispatch] pragma is obsolete, and ignored if present. In Snit 1.x, [const -simpledispatch] substitutes a faster mechanism for method dispatch, at the cost of losing certain features. -Snit 2.2 method dispatch is faster still in all cases, so +Snit 2.2 method dispatch is faster still in all cases, so [const -simpledispatch] is no longer needed. [item] In Snit 2.2, a type's code (methods, type methods, etc.) can call commands @@ -374,11 +383,10 @@ only those commands which have already been exported by the parent namespace at the time the type is defined. [list_end] - [section OBJECTS] [subsection {What is an object?}] A full description of object-oriented programming is beyond @@ -387,13 +395,13 @@ There are many ways to represent objects in Tcl/Tk; the best known examples are the Tk widgets. [para] -A Tk widget is an object; it is represented by a Tcl command. +A Tk widget is an object; it is represented by a Tcl command. The object's methods are subcommands of the Tcl command. The object's -properties are options accessed using the [method configure] and +properties are options accessed using the [method configure] and [method cget] methods. Snit uses the same conventions as Tk widgets do. [subsection {What is an abstract data type?}] In computer science terms, an abstract data type is a complex data @@ -400,13 +408,13 @@ structure along with a set of operations--a stack, a queue, a binary tree, etc--that is to say, in modern terms, an object. In systems that include some form of inheritance the word [term class] is usually used instead of [term {abstract data type}], but as Snit doesn't implement inheritance as it's ordinarily understood -the older term seems more appropriate. Sometimes this is called +the older term seems more appropriate. Sometimes this is called [term {object-based}] programming as opposed to object-oriented -programming. Note that you can easily create the effect of +programming. Note that you can easily create the effect of inheritance using [sectref COMPONENTS] and [sectref "DELEGATION"]. [para] In Snit, as in Tk, a [term type] is a command that creates instances @@ -433,11 +441,11 @@ In this example, [cmd text] is the [term type] command and [cmd .mytext] is the [term instance] command. [para] -In Snit, object subcommands are generally called +In Snit, object subcommands are generally called [sectref "INSTANCE METHODS"]. [subsection {What kinds of abstract data types does Snit provide?}] Snit allows you to define three kinds of abstract data type: @@ -453,11 +461,10 @@ [cmd snit::widget] [item] [cmd snit::widgetadaptor] [list_end] - [subsection {What is a snit::type?}] A [cmd snit::type] is a non-GUI abstract data type, e.g., a stack or a queue. [cmd snit::type]s are defined using the [cmd snit::type] @@ -479,27 +486,24 @@ [para] An instance of a [cmd snit::type] can have [sectref {INSTANCE METHODS}], [sectref {INSTANCE VARIABLES}], [sectref OPTIONS], and [sectref COMPONENTS]. The type itself can have [sectref {TYPE METHODS}], -[sectref {TYPE VARIABLES}], [sectref {TYPE COMPONENTS}], and -[sectref PROCS]. - +[sectref {TYPE VARIABLES}], [sectref {TYPE COMPONENTS}], and +[sectref PROCS]. [subsection {What is a snit::widget?, the short story}] A [cmd snit::widget] is a Tk megawidget built using Snit; it is very similar to a [cmd snit::type]. See [sectref WIDGETS]. - [subsection {What is a snit::widgetadaptor?, the short story}] A [cmd snit::widgetadaptor] uses Snit to wrap an existing widget type (e.g., a Tk label), modifying its interface to a lesser or greater extent. It is very similar to a [cmd snit::widget]. See [sectref {WIDGET ADAPTORS}]. - [subsection {How do I create an instance of a snit::type?}] You create an instance of a [cmd snit::type] by passing the new instance's name to the type's create method. In the following @@ -515,11 +519,11 @@ % }] [para] In general, the [method create] method name can be omitted so long as -the instance name doesn't conflict with any defined +the instance name doesn't conflict with any defined [sectref {TYPE METHODS}]. (See [sectref {TYPE COMPONENTS}] for the special case in which this doesn't work.) So the following example is identical to the previous example: @@ -536,11 +540,11 @@ This document generally uses the shorter form. [para] -If the [cmd dog] type defines [sectref OPTIONS], these can usually be +If the [cmd dog] type defines [sectref OPTIONS], these can usually be given defaults at creation time: [para] [example {% snit::type dog { option -breed mongrel @@ -616,11 +620,10 @@ ::obj_dog4 barks. % }] [para] - [subsection {Can types be renamed?}] Tcl's [cmd rename] command renames other commands. It's a common technique in Tcl to modify an existing command by renaming it and defining a new command with the original name; the new command usually @@ -653,11 +656,11 @@ other instance methods using [var \$self]. [item] If the object is renamed, however, then [var \$self]'s value will change. -Therefore, don't use [var \$self] for anything that will break if +Therefore, don't use [var \$self] for anything that will break if [var \$self] changes. For example, don't pass a callback command to another object like this: [example { .btn configure -command [list $self ButtonPress] @@ -681,19 +684,19 @@ [item] Every object has a private namespace; the name of this namespace is available in method bodies, etc., as the value of the implicit argument [var selfns]. This value is constant for the life of the -object. Use [var \$selfns] instead of [var \$self] if you need a +object. Use [var \$selfns] instead of [var \$self] if you need a unique token to identify the object. [item] When a [cmd snit::widget]'s instance command is renamed, its Tk window name remains the same -- and is still extremely -important. Consequently, the Tk window name is available in -method bodies as the value of the implicit argument [var win]. +important. Consequently, the Tk window name is available in +method bodies as the value of the implicit argument [var win]. This value is constant for the life of the object. When creating child windows, it's best to use [var {$win.child}] rather than [var {$self.child}] as the name of the child window. @@ -836,27 +839,27 @@ [subsection {Are there any limitations on instance method names?}] Not really, so long as you avoid the standard instance method names: [method configure], [method configurelist], [method cget], -[method destroy], and [method info]. Also, method names consisting of +[method destroy], and [method info]. Also, method names consisting of multiple words define hierarchical methods. [subsection {What is a hierarchical method?}] An object's methods are subcommands of the object's instance command. Hierarchical methods allow an object's methods to have subcommands of their own; and these can in turn have subcommands, and so on. This allows the programmer to define a tree-shaped command structure, such -as is used by many of the Tk widgets--the subcommands of the +as is used by many of the Tk widgets--the subcommands of the Tk [cmd text] widget's [cmd tag] method are hierarchical methods. [subsection {How do I define a hierarchical method?}] Define methods whose names consist of multiple words. These words define the hierarchy implicitly. For example, the following code -defines a [cmd tag] method with subcommands [cmd cget] and +defines a [cmd tag] method with subcommands [cmd cget] and [cmd configure]: [example {snit::widget mytext { method {tag configure} {tag args} { ... } @@ -1017,11 +1020,11 @@ specific naming convention, as it might change in future releases. [subsection {What is $win?}] The implicit argument [var win] is defined for all Snit methods, -though it really makes sense only for those of +though it really makes sense only for those of [sectref WIDGETS] and [sectref {WIDGET ADAPTORS}]. [var \$win] is simply the original name of the object, whether it's been renamed or not. For widgets and widgetadaptors, it is also therefore the name of a Tk window. @@ -1043,11 +1046,11 @@ It depends on the context. [para] Suppose in my application I have a [cmd dog] object named [cmd fido], -and I want [cmd fido] to bark when a Tk button called [cmd .bark] is +and I want [cmd fido] to bark when a Tk button called [cmd .bark] is pressed. In this case, I create the callback command in the usual way, using [cmd list]: [para] [example { button .bark -text "Bark!" -command [list fido bark] @@ -1107,19 +1110,19 @@ }] [para] The command [cmd mymethod] takes any number of arguments, and can be used like [cmd list] to build up a callback command; the only -difference is that [cmd mymethod] returns a +difference is that [cmd mymethod] returns a form of the command that won't change even if the instance's name changes. [para] -On the other hand, you might prefer to allow a widgetadaptor to +On the other hand, you might prefer to allow a widgetadaptor to override a method such that your renamed widget will call the -widgetadaptor's method instead of its own. In this case, +widgetadaptor's method instead of its own. In this case, using [cmd "\[list \$self bark\]"] will do what you want...but this is a technique which should be used only in carefully controlled circumstances. [subsection {How do I delegate instance methods to a component?}] @@ -1126,16 +1129,14 @@ See [sectref DELEGATION]. [section {INSTANCE VARIABLES}] - [subsection {What is an instance variable?}] An instance variable is a private variable associated with some particular Snit object. Instance variables can be scalars or arrays. - [subsection {How is a scalar instance variable defined?}] Scalar instance variables are defined in the type definition using the [cmd variable] statement. You can simply name it, or you can @@ -1166,11 +1167,11 @@ }] [para] [subsection {What happens if I don't initialize an instance variable?}] -Variables do not really exist until they are given values. If you +Variables do not really exist until they are given values. If you do not initialize a variable when you define it, then you must be sure to assign a value to it (in the constructor, say, or in some method) before you reference it. [subsection {Are there any limitations on instance variable names?}] @@ -1190,11 +1191,10 @@ [para] Third, instance variable names containing the namespace delimiter ([const ::]) are likely to cause great confusion. - [subsection {Do I need to declare my instance variables in my methods?}] No. Once you've defined an instance variable in the type definition, it can be used in any instance code (instance methods, the constructor, and the destructor) without declaration. This differs @@ -1202,14 +1202,14 @@ need to be declared. [para] There is a speed penalty to having all instance variables implicitly -available in all instance code. Even though your code need not +available in all instance code. Even though your code need not declare the variables explicitly, Snit must still declare them, and that takes time. If you have ten instance variables, a method -that uses none of them must still pay the declaration penalty for +that uses none of them must still pay the declaration penalty for all ten. In most cases, the additional runtime cost is negligible. If extreme cases, you might wish to avoid it; there are two methods for doing so. [para] @@ -1266,11 +1266,11 @@ you'll be confused by the result; Tk will assume that the name names a global variable. Instead, you need to provide a fully-qualified variable name. From within an instance method or a constructor, you can fully qualify the variable's name using the [cmd myvar] command: -[para] +[para] [example {snit::widget mywidget { variable labeltext "" constructor {args} { # ... @@ -1301,12 +1301,12 @@ an object. [para] Snit's implementation of options follows the Tk model fairly exactly, -except that [cmd snit::type] objects usually don't interact with -[sectref "THE TK OPTION DATABASE"]; [cmd snit::widget] and +except that [cmd snit::type] objects usually don't interact with +[sectref "THE TK OPTION DATABASE"]; [cmd snit::widget] and [cmd snit::widgetadaptor] objects, on the other hand, always do. [subsection {How do I define an option?}] Options are defined in the type definition using the [cmd option] @@ -1321,20 +1321,19 @@ option -shots -default 0 } }] [para] - According to this, a dog has four notable properties: a breed, a color, a flag that says whether it's pedigreed with the American Kennel Club, and another flag that says whether it has had its shots. The default dog, evidently, is a brown mutt. [para] There are a number of options you can specify when defining an option; -if [const -default] is the only one, you can omit the word +if [const -default] is the only one, you can omit the word [const -default] as follows: [para] [example {snit::type dog { option -breed mongrel @@ -1394,11 +1393,11 @@ [subsection {How can a client set options after object creation?}] Any number of options may be set at one time using the [method configure] instance method. Suppose that closer inspection -shows that ::fido is not a brown mongrel, but rather a rare Arctic Boar +shows that ::fido is not a brown mongrel, but rather a rare Arctic Boar Hound of a lovely dun color: [para] [example {% fido configure -color dun -breed "Arctic Boar Hound" % fido cget -color @@ -1421,11 +1420,11 @@ Arctic Boar Hound % }] [para] -In Tcl 8.5, the [cmd {*}] keyword can be used with +In Tcl 8.5, the [cmd {*}] keyword can be used with [method configure] in this case: [para] [example {% set features [list -color dun -breed "Arctic Boar Hound"] -color dun -breed {Arctic Boar Hound} @@ -1480,17 +1479,17 @@ } }] [para] As you can see, using the [var options] variable involves considerably -less typing and is the usual way to do it. But if you use +less typing and is the usual way to do it. But if you use [const -configuremethod] or [const -cgetmethod] (described in the following -answers), you might wish to use the [method configure] and +answers), you might wish to use the [method configure] and [method cget] methods anyway, just so that any special processing you've implemented is sure to get done. Also, if the option is delegated to a component then [method configure] and [method cget] are the only way -to access it without accessing the component directly. See +to access it without accessing the component directly. See [sectref "DELEGATION"] for more information. [subsection {How can I make an option read-only?}] Define the option with [const "-readonly yes"]. @@ -1524,11 +1523,11 @@ Define a [const -cgetmethod] for the option. [subsection {What is a -cgetmethod?}] A [const -cgetmethod] is a method that's called whenever the related -option's value is queried via the +option's value is queried via the [method cget] instance method. The handler can compute the option's value, retrieve it from a database, or do anything else you'd like it to do. [para] @@ -1555,11 +1554,11 @@ [subsection {What is a -configuremethod?}] A [const -configuremethod] is a method that's called whenever the related option is given a new value via the [method configure] or -[method configurelist] instance methods. The method can +[method configurelist] instance methods. The method can pass the value on to some other object, store it in a database, or do anything else you'd like it to do. [para] @@ -1627,20 +1626,18 @@ [para] Any method can be a [const -validatemethod] provided that it takes two arguments, the option name and the new option value. - [section {TYPE VARIABLES}] [subsection {What is a type variable?}] A type variable is a private variable associated with a Snit type rather than with a particular instance of the type. In C++ and Java, the term [term "static member variable"] is used for the same notion. Type variables can be scalars or arrays. - [subsection {How is a scalar type variable defined?}] Scalar type variables are defined in the type definition using the [cmd typevariable] statement. You can simply name it, or you can @@ -1659,11 +1656,11 @@ called [var greeting]. [subsection {How is an array-valued type variable defined?}] Array-valued type variables are also defined using the -[cmd typevariable] command; to initialize them, include the +[cmd typevariable] command; to initialize them, include the [const -array] option: [para] [example {snit::type mytype { # Define typearray variable "greetings" @@ -1675,18 +1672,18 @@ }] [para] [subsection {What happens if I don't initialize a type variable?}] -Variables do not really exist until they are given values. If you +Variables do not really exist until they are given values. If you do not initialize a variable when you define it, then you must be sure to assign a value to it (in the type constructor, say) before you reference it. [subsection {Are there any limitations on type variable names?}] -Type variable names have the same restrictions as +Type variable names have the same restrictions as the names of [sectref {INSTANCE VARIABLES}] do. [subsection {Do I need to declare my type variables in my methods?}] No. Once you've defined a type variable in the type definition, it can @@ -1696,11 +1693,11 @@ [para] Type variables are subject to the same speed/readability tradeoffs as instance variables; see -[sectref {Do I need to declare my instance variables in my methods?}] +[sectref {Do I need to declare my instance variables in my methods?}] [subsection {How do I pass a type variable's name to another object?}] In Tk, it's common to pass a widget a variable name; for example, Tk label widgets have a [option -textvariable] option which names the @@ -1714,11 +1711,11 @@ be confused by the result; Tk will assume that the name names a global variable. Instead, you need to provide a fully-qualified variable name. From within an instance method or a constructor, you can fully qualify the type variable's name using the [cmd mytypevar] command: -[para] +[para] [example {snit::widget mywidget { typevariable labeltext "" constructor {args} { # ... @@ -1819,11 +1816,10 @@ [subsection {Are there any limitations on type method names?}] Not really, so long as you avoid the standard type method names: [method create], [method destroy], and [method info]. - [subsection {How do I make a type method private?}] It's sometimes useful to define private type methods, that is, type methods intended to be called only by other type or instance methods of the same object. @@ -1837,11 +1833,10 @@ [para] Alternatively, a Snit [cmd proc] can be used as a private type method; see [sectref PROCS]. - [subsection {Are there any limitations on type method arguments?}] Method argument lists are defined just like normal Tcl proc argument lists; in particular, they can include arguments with default values @@ -1883,11 +1878,11 @@ [example { button .btn -text "Pedigrees" -command [list dog printPedigrees] pack .btn }] -Alternatively, from a method or type method you can use the +Alternatively, from a method or type method you can use the [cmd mytypemethod] command, just as you would use [cmd mymethod] to define a callback command for [sectref {INSTANCE METHODS}]. [subsection {Can type methods be hierarchical?}] @@ -1899,11 +1894,11 @@ [subsection {What is a proc?}] A Snit [cmd proc] is really just a Tcl proc defined within the type's namespace. You can use procs for private code that isn't related to -any particular instance. +any particular instance. [subsection {How do I define a proc?}] Procs are defined by including a [cmd proc] statement in the type definition: @@ -1954,11 +1949,11 @@ }] [para] [subsection {How can I pass a proc to another object as a callback?}] -The [cmd myproc] command returns a callback command for the +The [cmd myproc] command returns a callback command for the [cmd proc], just as [cmd mymethod] does for a method. [section {TYPE CONSTRUCTORS}] [subsection {What is a type constructor?}] @@ -1969,11 +1964,10 @@ again. [para] A type can have at most one type constructor. - [subsection {How do I define a type constructor?}] A type constructor is defined by using the [cmd typeconstructor] statement in the type definition. For example, suppose the type uses @@ -1989,12 +1983,10 @@ } } }] [para] - - [section CONSTRUCTORS] [subsection {What is a constructor?}] In object-oriented programming, an object's constructor is responsible @@ -2007,21 +1999,20 @@ [para] The constructor's return value is ignored (unless it's an error, of course). - [subsection {How do I define a constructor?}] A constructor is defined by using the [cmd constructor] statement in the type definition. Suppose that it's desired to keep a list of all -pedigreed dogs. The list can be maintained in a +pedigreed dogs. The list can be maintained in a type variable and retrieved by a type method. Whenever a dog is created, it can add itself to the list--provided that it's registered with the American Kennel Club. -[para] +[para] [example {% snit::type dog { option -akc 0 typevariable akcList {} @@ -2098,26 +2089,26 @@ }] [para] The drawback is that this syntax is non-standard, and may limit the compatibility of your new type with other people's code. -For example, Snit assumes that it can create +For example, Snit assumes that it can create [sectref COMPONENTS] using the standard creation syntax. [subsection {Are there any limitations on constructor arguments?}] Constructor argument lists are subject to the same limitations as those on instance method argument lists. It has the -same implicit arguments, and can contain default values and the +same implicit arguments, and can contain default values and the [var args] argument. [subsection "Is there anything special about writing the constructor?"] Yes. Writing the constructor can be tricky if you're delegating options to components, and there are specific issues relating to -[cmd snit::widget]s and [cmd snit::widgetadaptor]s. See -[sectref {DELEGATION}], [sectref {WIDGETS}], +[cmd snit::widget]s and [cmd snit::widgetadaptor]s. See +[sectref {DELEGATION}], [sectref {WIDGETS}], [sectref {WIDGET ADAPTORS}], and [sectref {THE TK OPTION DATABASE}]. [section DESTRUCTORS] [subsection {What is a destructor?}] @@ -2181,28 +2172,28 @@ [para] Any Tk widgets created by a [cmd snit::widget] or [cmd snit::widgetadaptor] will be destroyed automatically by Tk -when the megawidget is destroyed, in keeping with normal Tk behavior +when the megawidget is destroyed, in keeping with normal Tk behavior (destroying a parent widget destroys the whole tree). [para] -Components of normal [cmd snit::types], on the other hand, -are never destroyed automatically, nor are non-widget components -of Snit megawidgets. If your object creates them in its +Components of normal [cmd snit::types], on the other hand, +are never destroyed automatically, nor are non-widget components +of Snit megawidgets. If your object creates them in its constructor, then it should generally destroy them in its destructor. [subsection {Is there any special about writing a destructor?}] Yes. If an object's constructor throws an error, the object's destructor will be called to clean up; this means that the object might not be completely constructed when the destructor is called. This can cause the destructor to throw its own error; the result is usually misleading, confusing, and unhelpful. Consequently, it's -important to write your destructor so that it's fail-safe. +important to write your destructor so that it's fail-safe. [para] For example, a [cmd dog] might create a [cmd tail] component; the component will need to be destroyed. But suppose there's an error @@ -2223,11 +2214,10 @@ catch {$tail destroy} } } }] - [section COMPONENTS] [subsection {What is a component?}] Often an object will create and manage a number of other objects. A @@ -2235,11 +2225,11 @@ widgets. These objects are part of the main object; it is composed of them, so they are called components of the object. [para] -But Snit also has a more precise meaning for +But Snit also has a more precise meaning for [sectref COMPONENTS COMPONENT]. The components of a Snit object are those objects to which methods or options can be delegated. (See [sectref DELEGATION] for more information about delegation.) [subsection {How do I declare a component?}] @@ -2290,11 +2280,11 @@ constructor. This second name is always a Tcl command name, and is referred to as the component's object name. [para] -In the example in the previous question, the component name is +In the example in the previous question, the component name is [const mytail]; the [const mytail] component's object name is chosen automatically by Snit since [const %AUTO%] was used when the component object was created. [subsection {Are there any limitations on component names?}] @@ -2382,11 +2372,11 @@ } }] In a [cmd snit::type]'s code, the [cmd install] command shown above is equivalent to the [const {set mytail}] command -that's commented out. In a [cmd snit::widget]'s or +that's commented out. In a [cmd snit::widget]'s or [cmd snit::widgetadaptor]'s, code, however, the [cmd install] command also queries [sectref {THE TK OPTION DATABASE}] and initializes the new component's options accordingly. For consistency, it's a good idea to get in the habit of using [cmd install] for all owned components. @@ -2413,11 +2403,11 @@ namespace of the command. Note that Snit always creates objects with fully qualified names. [para] -Next, the object names of components and owned by your object +Next, the object names of components and owned by your object must be unique. This is no problem for widget components, since widget names are always unique; but consider the following code: [para] [example {snit::type tail { ... } @@ -2496,22 +2486,21 @@ However, there are times when it's appropriate, not to mention simpler, just to make the entire component part of your type's public interface. - [subsection {How do I expose a component's object command?}] When you declare the component, specify the [cmd component] statement's [const -public] option. The value of this option is the -name of a method which will be delegated to your component's object +name of a method which will be delegated to your component's object command. [para] For example, supposed you've written a combobox megawidget which owns -a listbox widget, and you want to make the listbox's entire interface +a listbox widget, and you want to make the listbox's entire interface public. You can do it like this: [para] [example {snit::widget combobox { component listbox -public listbox @@ -2540,11 +2529,11 @@ [subsection {What is a type component?}] A type component is a component that belongs to the type itself instead of to a particular instance of the type. The relationship between components and type components is the same as the -relationship between [sectref {INSTANCE VARIABLES}] and +relationship between [sectref {INSTANCE VARIABLES}] and [sectref {TYPE VARIABLES}]. Both [sectref {INSTANCE METHODS}] and [sectref {TYPE METHODS}] can be delegated to type components. [para] @@ -2573,11 +2562,11 @@ }] [subsection {How do I install a type component?}] Just use the [cmd set] command to assign the component's object -command to the type component. Because types +command to the type component. Because types (even [cmd snit::widget] types) are not widgets, and do not have options anyway, the extra features of the [cmd install] command are not needed. [para] @@ -2596,13 +2585,12 @@ } }] [subsection {Are there any limitations on type component names?}] -Yes, the same as on [sectref {INSTANCE VARIABLES}], +Yes, the same as on [sectref {INSTANCE VARIABLES}], [sectref {TYPE VARIABLES}], and normal [sectref COMPONENTS]. - [section DELEGATION] [subsection {What is delegation?}] @@ -2610,16 +2598,15 @@ one of your assistants. (You do have assistants, don't you?) Snit objects can do the same thing. The following example shows one way in which the [cmd dog] object can delegate its [cmd wag] method and its [option -taillength] option to its [cmd tail] component. -[para] +[para] [example {snit::type dog { variable mytail option -taillength -configuremethod SetTailOption -cgetmethod GetTailOption - method SetTailOption {option value} { $mytail configure $option $value } @@ -2651,11 +2638,11 @@ error. [subsection {How can I delegate a method to a component object?}] Delegation occurs frequently enough that Snit makes it easy. Any -method can be delegated to any component or type component +method can be delegated to any component or type component by placing a single [cmd delegate] statement in the type definition. (See [sectref COMPONENTS] and [sectref {TYPE COMPONENTS}] for more information about component names.) @@ -2717,11 +2704,10 @@ } } }] [para] - [subsection {Can I delegate to a method with additional arguments?}] Suppose the [cmd tail]'s [method wag] method takes as an argument the number of times the tail should be wagged. You want to delegate the [cmd dog]'s [method wagtail] method to the [cmd tail]'s [method wag] @@ -2744,11 +2730,11 @@ [para] [subsection {Can I delegate a method to something other than an object?}] Normal method delegation assumes that you're delegating a method (a -subcommand of an object command) to a method of another object (a +subcommand of an object command) to a method of another object (a subcommand of a different object command). But not all Tcl objects follow Tk conventions, and not everything you'd to which you'd like to delegate a method is necessary an object. Consequently, Snit makes it easy to delegate a method to pretty much anything you like using the [cmd delegate] statement's [const using] clause. @@ -2758,44 +2744,44 @@ Suppose your dog simulation stores dogs in a database, each dog as a single record. The database API you're using provides a number of commands to manage records; each takes the record ID (a string you choose) as its first argument. For example, [cmd saverec] saves a record. If you let the record ID be the name of the dog -object, you can delegate the dog's [method save] method to the +object, you can delegate the dog's [method save] method to the [cmd saverec] command as follows: [example {snit::type dog { delegate method save using {saverec %s} } }] -The [const %s] is replaced with the instance name when the +The [const %s] is replaced with the instance name when the [method save] method is called; any additional arguments are the appended to the resulting command. [para] The [const using] clause understands a number of other %-conversions; -in addition to the instance name, you can substitute in the method -name ([const %m]), the type name ([const %t]), the instance +in addition to the instance name, you can substitute in the method +name ([const %m]), the type name ([const %t]), the instance namespace ([const %n]), the Tk window name ([const %w]), and, -if a component or typecomponent name was given in the -[cmd delegate] statement, the component's object command +if a component or typecomponent name was given in the +[cmd delegate] statement, the component's object command ([const %c]). [subsection {How can I delegate a method to a type component object?}] -Just exactly as you would to a component object. The +Just exactly as you would to a component object. The [cmd {delegate method}] statement accepts both component and type component names in its [const to] clause. [subsection {How can I delegate a type method to a type component object?}] Use the [cmd {delegate typemethod}] statement. It works like [cmd {delegate method}], with these differences: first, it defines -a type method instead of an instance method; second, the -[const using] clause ignores the [const {%s}], [const {%n}], +a type method instead of an instance method; second, the +[const using] clause ignores the [const {%s}], [const {%n}], and [const {%w}] %-conversions. [para] Naturally, you can't delegate a type method to an instance @@ -2944,11 +2930,11 @@ }] [para] Dogs have four legs, so we specify that explicitly when we create the [var animal] component, and explicitly exclude [option -numlegs] from the -set of delegated options. Similarly, dogs can neither +set of delegated options. Similarly, dogs can neither [method fly] nor [method climb], so we exclude those [cmd animal] methods as shown. [subsection {Can a hierarchical method be delegated?}] @@ -2957,11 +2943,10 @@ [para] [example {snit::type tail { method wag {} {return "Wag, wag"} method droop {} {return "Droop, droop"} } - snit::type dog { delegate method {tail wag} to mytail delegate method {tail droop} to mytail @@ -2988,13 +2973,10 @@ # ... } }] [para] - - - [section WIDGETS] [subsection {What is a snit::widget?}] A [cmd snit::widget] is the Snit version of what Tcl programmers @@ -3005,21 +2987,19 @@ A [cmd snit::widget] is also a special kind of [cmd snit::type]. Just about everything in this FAQ list that relates to [cmd snit::types] also applies to [cmd snit::widgets]. - [subsection {How do I define a snit::widget?}] [cmd snit::widgets] are defined using the [cmd snit::widget] command, just as [cmd snit::types] are defined by the [cmd snit::type] command. [para] The body of the definition can contain all of the same kinds of statements, plus a couple of others which will be mentioned below. - [subsection {How do snit::widgets differ from snit::types?}] [list_begin itemized] [item] @@ -3028,18 +3008,16 @@ command name, in any namespace. The name of an instance of a [cmd snit::widget] must be a valid Tk widget name, and its parent widget must already exist. - [item] An instance of a [cmd snit::type] can be destroyed by calling its [cmd destroy] method. Instances of a [cmd snit::widget] have no destroy method; use the Tk [cmd destroy] command instead. - [item] Every instance of a [cmd snit::widget] has one predefined component called its [var hull] component. @@ -3078,11 +3056,11 @@ [sectref {WIDGET ADAPTORS}]. [subsection {How can I set the hull type for a snit::widget?}] A [cmd snit::widget]'s hull component will usually be a Tk [cmd frame] -widget; however, it may be any Tk widget that defines the +widget; however, it may be any Tk widget that defines the [const -class] option. You can explicitly choose the hull type you prefer by including the [cmd hulltype] command in the widget definition: [para] @@ -3114,12 +3092,10 @@ # ... } }] [para] - - [subsection {How should I name widgets which are components of a snit::widget?}] Every widget, whether a genuine Tk widget or a Snit megawidget, has to have a valid Tk window name. When a [cmd snit::widget] is first @@ -3171,11 +3147,10 @@ [para] It's called a [term {widget adaptor}] because it allows you to take an existing widget and customize its behavior. - [subsection {How do I define a snit::widgetadaptor?}] Use the [cmd snit::widgetadaptor] command. The definition for a [cmd snit::widgetadaptor] looks just like that for a [cmd snit::type] or [cmd snit::widget], except that the constructor must create and @@ -3210,11 +3185,11 @@ # Enable ins and del as synonyms, so the program can insert and # delete. delegate method ins to hull as insert delegate method del to hull as delete - + # Pass all other methods and options to the real text widget, so # that the remaining behavior is as expected. delegate method * to hull delegate option * to hull } @@ -3269,11 +3244,11 @@ [subsection {Can I adapt another megawidget?}] Maybe. If the other megawidget is a [cmd snit::widget] or [cmd snit::widgetadaptor], then yes. If it isn't then, again, maybe. You'll have to try it and see. You're most likely to have trouble -with widget destruction--you have to make sure that your +with widget destruction--you have to make sure that your megawidget code receives the [const ] event before the megawidget you're adapting does. [section {THE TK OPTION DATABASE}] @@ -3326,21 +3301,20 @@ Use the [cmd install] command to create and install all components which are widgets. [item] -Use the [cmd install] command to create and install -components which aren't widgets if you'd like them to +Use the [cmd install] command to create and install +components which aren't widgets if you'd like them to receive option values from the option database. [list_end] [para] The interaction of Tk widgets with the option database is a complex thing; the interaction of Snit with the option database is even more so, and repays attention to detail. - [subsection {Do snit::types use the Tk option database?}] No, they don't; querying the option database requires a Tk window name, and [cmd snit::type]s don't have one. @@ -3358,11 +3332,11 @@ [subsection {What is my snit::widget's widget class?}] Every Tk widget has a "widget class": a name that is used when adding option settings to the database. For Tk widgets, the widget class is the same as the widget command name with an initial capital. For -example, the widget class of the Tk [cmd button] widget is +example, the widget class of the Tk [cmd button] widget is [const Button]. [para] Similarly, the widget class of a [cmd snit::widget] defaults to the @@ -3410,11 +3384,10 @@ Try to use [cmd snit::widgetadaptor]s only to make small modifications to another widget's behavior. Then, it will usually not make sense to change the widget's widget class anyway. - [subsection {What are option resource and class names?}] Every Tk widget option has three names: the option name, the resource name, and the class name. @@ -3432,20 +3405,19 @@ name with an initial capital, but not always. For example, here are the option, resource, and class names for several Tk [cmd text] widget options: [para] -[example { -background background Background - -borderwidth borderWidth BorderWidth - -insertborderwidth insertBorderWidth BorderWidth - -padx padX Pad +[example { -background background Background + -borderwidth borderWidth BorderWidth + -insertborderwidth insertBorderWidth BorderWidth + -padx padX Pad }] [para] As is easily seen, sometimes the resource and class names can be inferred from the option name, but not always. - [subsection {What are the resource and class names for my megawidget's options?}] For options implicitly delegated to a component using [cmd {delegate option *}], the resource and class names will be @@ -3525,11 +3497,10 @@ % .text configure -padx -padx padX Pad 1 1 % }] - [subsection {How does Snit initialize my megawidget's locally-defined options?}] The option database is queried for each of the megawidget's locally-defined options, using the option's resource and class name. If the result isn't "", then it replaces the default value given in @@ -3555,11 +3526,10 @@ [subsection {How does Snit initialize delegated options?}] That depends on whether the options are delegated to the hull, or to some other component. - [subsection {How does Snit initialize options delegated to the hull?}] A [cmd snit::widget]'s hull is a widget, and given that its class has been set it is expected to query the option database for itself. The @@ -3600,35 +3570,35 @@ [para] The value of B is "red". The hull will automatically pick up the value "green" for its [const -background] option, just as it picked up the [const -relief] value. However, Snit knows that [const -hullbackground] -is mapped to the hull's [const -background] option; hence, it queries -the option database for [const -hullbackground] and gets "red" and +is mapped to the hull's [const -background] option; hence, it queries +the option database for [const -hullbackground] and gets "red" and updates the hull accordingly. [para] The value of C is also "red", because [const -background] is implicitly delegated to the hull; thus, retrieving it is the same as retrieving -[const -hullbackground]. Note that this case is unusual; the +[const -hullbackground]. Note that this case is unusual; the [const -background] option should probably have been excluded using the delegate statement's [const except] clause, or (more likely) delegated to some other component. [para] The value of D is "5", but not for the reason you think. Note that as it is defined above, the resource name for [const -borderwidth] defaults to -[const borderwidth], whereas the option database entry is +[const borderwidth], whereas the option database entry is [const borderWidth], in accordance with the standard Tk naming for this option. As with [const -relief], the hull picks up its own [const -borderwidth] option before Snit does anything. Because the option is delegated under its own name, Snit assumes that the correct thing has happened, and doesn't worry -about it any further. To avoid confusion, the +about it any further. To avoid confusion, the [const -borderwidth] option should have been delegated like this: [para] [example { delegate option {-borderwidth borderWidth BorderWidth} to hull @@ -3749,11 +3719,11 @@ [item] Creates the component using the specified command, after inserting into it a list of options and values read from the option database. -Thus, the explicitly included options (like [const -foreground]) will +Thus, the explicitly included options (like [const -foreground]) will override anything read from the option database. [item] If the widget definition implicitly delegated options to the component @@ -3787,11 +3757,11 @@ [subsection {What is an ensemble command?}] An ensemble command is a command with subcommands. Snit objects are all ensemble commands; however, the term more usually refers to -commands like the standard Tcl commands [cmd string], [cmd file], +commands like the standard Tcl commands [cmd string], [cmd file], and [cmd clock]. In a sense, these are singleton objects--there's only one instance of them. [subsection {How can I create an ensemble command using Snit?}] @@ -3850,11 +3820,11 @@ Now the type command itself is your ensemble command. [para] -This method has only one drawback, and though it's major, it's +This method has only one drawback, and though it's major, it's also surmountable. Your new ensemble command will have [method create], [method info] and [method destroy] subcommands you don't want. And worse yet, since the [method create] method can be implicit, users of your command will accidentally be creating instances of your [cmd mystring] type if they should mispell one @@ -3864,12 +3834,12 @@ [para] The work around is to set some [sectref {PRAGMAS}], as shown here: [example {snit::type mystring { - pragma -hastypeinfo no - pragma -hastypedestroy no + pragma -hastypeinfo no + pragma -hastypedestroy no pragma -hasinstances no delegate typemethod * to stringhandler typeconstructor { @@ -3878,11 +3848,11 @@ } }] Here we've used the [cmd pragma] statement to tell Snit that we don't want the [method info] typemethod or the [method destroy] typemethod, -and that our type has no instances; this eliminates the +and that our type has no instances; this eliminates the [method create] typemethod and all related code. As a result, our ensemble command will be well-behaved, with no unexpected subcommands. [section {PRAGMAS}] @@ -3946,13 +3916,13 @@ Pragmas [const -hastypemethods] and [const -hasinstances] cannot both be false (or there'd be nothing left). [subsection {How can I get rid of type methods altogether?}] -Normal Tk widget type commands don't have subcommands; all they do is -create widgets--in Snit terms, the type command calls the -[method create] type method directly. To get the same behavior from +Normal Tk widget type commands don't have subcommands; all they do is +create widgets--in Snit terms, the type command calls the +[method create] type method directly. To get the same behavior from Snit, set the [const -hastypemethods] pragma to [const no]: [example {snit::type dog { pragma -hastypemethods no #... @@ -3968,11 +3938,11 @@ Pragmas [const -hastypemethods] and [const -hasinstances] cannot both be false (or there'd be nothing left). [subsection {Why can't I create an object that replaces an old object with the same name?}] -Up until Snit 0.95, you could use any name for an instance of a +Up until Snit 0.95, you could use any name for an instance of a [cmd snit::type], even if the name was already in use by some other object or command. You could do the following, for example: [example {snit::type dog { ... } @@ -3995,34 +3965,34 @@ In Snit 1.x, you can set the [const -simpledispatch] pragma to [const yes]. [para] Snit 1.x method dispatch is both flexible and fast, but the flexibility -comes with a price. If your type doesn't require the flexibility, the +comes with a price. If your type doesn't require the flexibility, the [const -simpledispatch] pragma allows you to substitute a simpler dispatch mechanism that runs quite a bit faster. The limitations are these: [list_begin itemized] [item] Methods cannot be delegated. [item] [cmd uplevel] and [cmd upvar] do not work as expected: the caller's scope is two levels up rather than one. -[item] The option-handling methods +[item] The option-handling methods ([cmd cget], [cmd configure], and [cmd configurelist]) are very slightly slower. [list_end] In Snit 2.2, the [const -simpledispatch] macro is obsolete, and -ignored; all Snit 2.2 method dispatch is faster than Snit 1.x's +ignored; all Snit 2.2 method dispatch is faster than Snit 1.x's [const -simpledispatch]. [section {MACROS}] [subsection {What is a macro?}] -A Snit macro is nothing more than a Tcl proc that's defined in the +A Snit macro is nothing more than a Tcl proc that's defined in the Tcl interpreter used to compile Snit type definitions. [subsection {What are macros good for?}] You can use Snit macros to define new type definition syntax, and to @@ -4064,11 +4034,11 @@ } }] [subsection {How do I define new type definition syntax?}] -Use a macro. For example, your [cmd snit::widget]'s +Use a macro. For example, your [cmd snit::widget]'s [const -background] option should be propagated to a number of component widgets. You could implement that like this: [example {snit::widget mywidget { option -background -default white -configuremethod PropagateBackground @@ -4122,14 +4092,13 @@ your macros in the same namespace as your types or widgets. That way, they won't conflict with other people's macros. [para] -If my fancy [cmd snit::widget] is called [cmd ::mylib::mywidget], +If my fancy [cmd snit::widget] is called [cmd ::mylib::mywidget], for example, then I should define my [cmd propagate] macro as [cmd ::mylib::propagate]: - [example {snit::macro mylib::propagate {option "to" components} { ... } snit::widget ::mylib::mywidget { option -background default -white @@ -4138,22 +4107,8 @@ mylib::propagate -background to {comp1 comp2 comp3} mylib::propagate -foreground to {comp1 comp2 comp3} } }] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph snit] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords class {object oriented} object C++] -[keywords {Incr Tcl} BWidget] -[keywords widget adaptors {widget adaptors} {mega widget}] +[vset CATEGORY snit] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/soundex/soundex.man ================================================================== --- modules/soundex/soundex.man +++ modules/soundex/soundex.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin soundex n 1.0] +[keywords knuth] +[keywords soundex] +[keywords {text comparison}] +[keywords {text likeness}] [copyright {????, Algorithm: Donald E. Knuth}] [copyright {2003, Documentation: Andreas Kupries }] [copyright {1998, Tcl port: Evan Rempel }] [moddesc {Soundex}] [titledesc {Soundex}] @@ -27,27 +31,15 @@ Knuth's algorithm and returns it as the result of the command. [list_end] - [section EXAMPLES] [example { % ::soundex::knuth Knuth K530 }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph soundex] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords soundex knuth {text comparison} {text likeness}] +[vset CATEGORY soundex] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/stooop/stooop.man ================================================================== --- modules/stooop/stooop.man +++ modules/stooop/stooop.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin stooop n 4.4.1] +[keywords C++] +[keywords class] +[keywords object] +[keywords {object oriented}] [moddesc {Simple Tcl Only Object Oriented Programming}] [titledesc {Object oriented extension.}] [category {Programming tools}] [require Tcl 8.3] [require stooop [opt 4.4.1]] @@ -20,11 +24,10 @@ This manual is very succinct and is to be used as a quick reminder for the programmer, who should have read the thorough [uri stooop_man.html] HTML documentation at this point. [list_begin definitions] - [call [cmd ::stooop::class] [arg {name body}]] This command creates a class. The body, similar in contents to a Tcl namespace (which a class actually also is), contains member procedure @@ -77,11 +80,10 @@ [const copy]. It is invoked following a [cmd new] invocation on an existing object of the class. [list_end] - [call [cmd ::stooop::new] [arg class] [opt [arg {arg arg ...}]]] This command is used to create an object. The first argument is the class name and is followed by the arguments needed by the corresponding class constructor. A unique identifier for the object @@ -119,11 +121,10 @@ [section DEBUGGING] [list_begin definitions] [def {Environment variables}] - [list_begin definitions] [def [var STOOOPCHECKDATA]] @@ -169,11 +170,11 @@ library will then output to the specified channel 1 line of informational text for each member data access. [def [var STOOOPTRACEDATAFORMAT]] -Defines the trace data output format. Defaults to +Defines the trace data output format. Defaults to [const {"class: %C, procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: %v"}]. [def [var STOOOPTRACEDATAOPERATIONS]] When tracing data output, by default, all read, write and unsetting @@ -188,11 +189,10 @@ [const stderr] or a file name, enables both procedure and data tracing. [list_end] - [call [cmd ::stooop::printObjects] [opt [arg pattern]]] Prints an ordered list of existing objects, in creation order, oldest first. Each output line contains the class name, object identifier and @@ -216,19 +216,8 @@ [section EXAMPLES] Please see the full HTML documentation in [uri stooop_man.html]. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph stooop] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords class {object oriented} object C++] +[vset CATEGORY stooop] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/string/token.man ================================================================== --- modules/string/token.man +++ modules/string/token.man @@ -1,10 +1,13 @@ [manpage_begin string::token n 1] +[keywords lexing] +[keywords regex] +[keywords string] +[keywords tokenization] [moddesc {Text and string utilities}] [titledesc {Regex based iterative lexing}] [category {Text processing}] -[keywords string tokenization lexing regex] [require Tcl 8.5] [require string::token [opt 1]] [require fileutil] [description] @@ -87,17 +90,8 @@ with the constraint escape [const \A] to ensure that a match starts exactly at the character index found in [arg startvar]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/string/token_shell.man ================================================================== --- modules/string/token_shell.man +++ modules/string/token_shell.man @@ -1,10 +1,15 @@ [manpage_begin string::token::shell n 1.1] +[keywords bash] +[keywords lexing] +[keywords parsing] +[keywords shell] +[keywords string] +[keywords tokenization] [moddesc {Text and string utilities}] [titledesc {Parsing of shell command line}] [category {Text processing}] -[keywords string shell bash tokenization parsing lexing] [require Tcl 8.5] [require string::token::shell [opt 1.1]] [require string::token [opt 1]] [require fileutil] [description] @@ -122,17 +127,8 @@ [para] Whitespace may occur before the first word, or after the last word. Whitespace must occur between adjacent words. [list_end] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/stringprep/stringprep.man ================================================================== --- modules/stringprep/stringprep.man +++ modules/stringprep/stringprep.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin stringprep n 1.0.1] +[see_also unicode(n)] +[keywords stringprep] +[keywords unicode] [copyright {2007-2009, Sergei Golovan }] [moddesc {Preparation of Internationalized Strings}] [titledesc {Implementation of stringprep}] [require Tcl 8.3] [require stringprep 1.0.1] @@ -138,25 +141,11 @@ "Extensible Messaging and Presence Protocol (XMPP): Core", ([uri http://www.ietf.org/rfc/rfc3920.txt]) [list_end] -[see_also unicode(n) ] - [section "AUTHORS"] Sergei Golovan - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph stringprep] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords stringprep unicode] +[vset CATEGORY stringprep] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/stringprep/stringprep_data.man ================================================================== --- modules/stringprep/stringprep_data.man +++ modules/stringprep/stringprep_data.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin stringprep::data n 1.0.1] +[keywords stringprep] +[keywords unicode] [copyright {2007-2009, Sergei Golovan }] [moddesc {Preparation of Internationalized Strings}] [titledesc {stringprep data tables, generated, internal}] [require Tcl 8.3] [require stringprep::data 1.0.1] @@ -12,19 +14,8 @@ [package stringprep], providing it with the data tables needed to perform its functions. It is an [emph internal] package which should not be accessed on its own. Because of that it has no publicly documented API either. Its implementation is generated by a script. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph stringprep] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords stringprep unicode] +[vset CATEGORY stringprep] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/stringprep/unicode.man ================================================================== --- modules/stringprep/unicode.man +++ modules/stringprep/unicode.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin unicode n 1.0.0] +[see_also stringprep(n)] +[keywords normalization] +[keywords unicode] [copyright {2007, Sergei Golovan }] [moddesc {Unicode normalization}] [titledesc {Implementation of Unicode normalization}] [require Tcl 8.3] [require unicode 1.0] @@ -70,25 +73,11 @@ "Unicode Standard Annex #15: Unicode Normalization Forms", ([uri http://unicode.org/reports/tr15/]) [list_end] -[see_also stringprep(n) ] - [section "AUTHORS"] Sergei Golovan - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph stringprep] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords unicode normalization] +[vset CATEGORY stringprep] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/stringprep/unicode_data.man ================================================================== --- modules/stringprep/unicode_data.man +++ modules/stringprep/unicode_data.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin unicode::data n 1.0.0] +[keywords stringprep] +[keywords unicode] [copyright {2007, Sergei Golovan }] [moddesc {Preparation of Internationalized Strings}] [titledesc {unicode data tables, generated, internal}] [require Tcl 8.3] [require unicode::data 1.0.0] @@ -12,20 +14,8 @@ [package unicode], providing it with the data tables needed to perform its functions. It is an [emph internal] package which should not be accessed on its own. Because of that it has no publicly documented API either. Its implementation is generated by a script. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph stringprep] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords stringprep unicode] +[vset CATEGORY stringprep] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/disjointset.man ================================================================== --- modules/struct/disjointset.man +++ modules/struct/disjointset.man @@ -1,6 +1,13 @@ [manpage_begin struct::disjointset n 1.0] +[keywords {disjoint set}] +[keywords {equivalence class}] +[keywords find] +[keywords {merge find}] +[keywords partition] +[keywords {partitioned set}] +[keywords union] [moddesc {Tcl Data Structures}] [titledesc {Disjoint set data structure}] [category {Data structures}] [require Tcl 8.4] [require struct::disjointset [opt 1.0]] @@ -90,11 +97,10 @@ the command. The following commands are possible for disjointset objects: [list_end] - [call [arg disjointsetName] [method add-partition] [arg elements]] Creates a new partition in specified disjoint set, and fills it with the values found in the set of [arg elements]. The command maintains the integrity of the disjoint set, i.e. it verifies that none of the @@ -103,22 +109,19 @@ [para] The result of the command is the empty string. - [call [arg disjointsetName] [method partitions]] Returns the set of partitions the named disjoint set currently consists of. - [call [arg disjointsetName] [method num-partitions]] Returns the number of partitions the named disjoint set currently consists of. - [call [arg disjointsetName] [method equal] [arg a] [arg b]] Determines if the two elements [arg a] and [arg b] of the disjoint set belong to the same partition. The result of the method is a boolean @@ -128,11 +131,10 @@ [para] An error will be thrown if either [arg a] or [arg b] are not elements of the disjoint set. - [call [arg disjointsetName] [method merge] [arg a] [arg b]] Determines the partitions the elements [arg a] and [arg b] are contained in and merges them into a single partition. If the two elements were already contained in the same partition nothing will @@ -140,33 +142,19 @@ [para] The result of the method is the empty string. - [call [arg disjointsetName] [method find] [arg e]] Returns the partition of the disjoint set which contains the element [arg e]. - [call [arg disjointsetName] [method destroy]] Destroys the disjoint set object and all associated memory. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: disjointset}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords {disjoint set}] -[keywords {merge find} union find partition {partitioned set} {equivalence class}] +[vset CATEGORY {struct :: disjointset}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/graph.man ================================================================== --- modules/struct/graph.man +++ modules/struct/graph.man @@ -1,7 +1,19 @@ [comment {-*- tcl -*-}] [manpage_begin struct::graph n 2.4] +[keywords adjacent] +[keywords arc] +[keywords cgraph] +[keywords degree] +[keywords edge] +[keywords graph] +[keywords loop] +[keywords neighbour] +[keywords node] +[keywords serialization] +[keywords subgraph] +[keywords vertex] [copyright {2002-2009 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate directed graph objects}] [category {Data structures}] [require Tcl 8.4] @@ -8,11 +20,10 @@ [require struct::graph [opt 2.4]] [require struct::list [opt 1.5]] [require struct::set [opt 2.2.3]] [description] [para] - A directed graph is a structure containing two collections of elements, called [term nodes] and [term arcs] respectively, together with a relation ("connectivity") that places a general structure upon the nodes and arcs. @@ -112,11 +123,11 @@ [example { ::struct::graph mygraph mygraph = b }] [para] -and +and [para] [example { ::struct::graph mygraph deserialize $b }] [para] @@ -154,11 +165,10 @@ The operation assumes that the [arg sourcegraph] provides the method [method serialize] and that this method returns a valid graph serialization. - [call [arg graphName] [method -->] [arg destgraph]] This is the [term {reverse assignment}] operator for graph objects. It copies the graph contained in the graph object [arg graphName] over the graph data in the object [arg destgraph]. @@ -176,35 +186,30 @@ [para] The operation assumes that the [arg destgraph] provides the method [method deserialize] and that this method takes a graph serialization. - [call [arg graphName] [method append] [arg key] [arg value]] Appends a [arg value] to one of the keyed values associated with the graph. Returns the new value given to the attribute [arg key]. - [call [arg graphName] [method deserialize] [arg serialization]] This is the complement to [method serialize]. It replaces the graph data in [arg graphName] with the graph described by the [arg serialization] value. The old contents of [arg graphName] are deleted by this operation. - [call [arg graphName] [method destroy]] Destroys the graph, including its storage space and associated command. - [call [arg graphName] [method {arc append}] [arg arc] [arg key] [arg value]] Appends a [arg value] to one of the keyed values associated with an [arg arc]. Returns the new value given to the attribute [arg key]. - [call [arg graphName] [method {arc attr}] [arg key]] [call [arg graphName] [method {arc attr}] [arg key] [option -arcs] [arg list]] [call [arg graphName] [method {arc attr}] [arg key] [option -glob] [arg globpattern]] [call [arg graphName] [method {arc attr}] [arg key] [option -regexp] [arg repattern]] @@ -242,31 +247,26 @@ names match this pattern are searched for the attribute. [list_end] [para] - [call [arg graphName] [method {arc delete}] [arg arc] [opt "[arg arc] ..."]] Remove the specified arcs from the graph. - [call [arg graphName] [method {arc exists}] [arg arc]] Return true if the specified [arg arc] exists in the graph. - [call [arg graphName] [method {arc flip}] [arg arc]] Reverses the direction of the named [arg arc], i.e. the source and target nodes of the arc are exchanged with each other. - [call [arg graphName] [method {arc get}] [arg arc] [arg key]] Returns the value associated with the key [arg key] for the [arg arc]. - [call [arg graphName] [method {arc getall}] [arg arc] [opt [arg pattern]]] Returns a dictionary (suitable for use with [lb][cmd {array set}][rb]) for the [arg arc]. @@ -273,139 +273,118 @@ If the [arg pattern] is specified only the attributes whose names match the pattern will be part of the returned dictionary. The pattern is a [cmd glob] pattern. - [call [arg graphName] [method {arc getunweighted}]] Returns a list containing the names of all arcs in the graph which have no weight associated with them. - [call [arg graphName] [method {arc getweight}] [arg arc]] Returns the weight associated with the [arg arc]. Throws an error if the arc has no weight associated with it. - [call [arg graphName] [method {arc keys}] [arg arc] [opt [arg pattern]]] Returns a list of keys for the [arg arc]. If the [arg pattern] is specified only the attributes whose names match the pattern will be part of the returned list. The pattern is a [cmd glob] pattern. - [call [arg graphName] [method {arc keyexists}] [arg arc] [arg key]] Return true if the specified [arg key] exists for the [arg arc]. - [call [arg graphName] [method {arc insert}] [arg start] [arg end] [opt [arg child]]] Insert an arc named [arg child] into the graph beginning at the node [arg start] and ending at the node [arg end]. If the name of the new arc is not specified the system will generate a unique name of the form [emph arc][arg x]. - [call [arg graphName] [method {arc lappend}] [arg arc] [arg key] [arg value]] Appends a [arg value] (as a list) to one of the keyed values associated with an [arg arc]. Returns the new value given to the attribute [arg key]. - [call [arg graphName] [method {arc rename}] [arg arc] [arg newname]] Renames the arc [arg arc] to [arg newname]. An error is thrown if either the arc does not exist, or a arc with name [arg newname] does exist. The result of the command is the new name of the arc. - [call [arg graphName] [method {arc set}] [arg arc] [arg key] [opt [arg value]]] -Set or get one of the keyed values associated with an arc. +Set or get one of the keyed values associated with an arc. -An arc may have any number of keyed values associated with it. -If [arg value] is not specified, this command returns the current value assigned to the key; +An arc may have any number of keyed values associated with it. +If [arg value] is not specified, this command returns the current value assigned to the key; if [arg value] is specified, this command assigns that value to the key, and returns that value. - [call [arg graphName] [method {arc setunweighted}] [opt [arg weight]]] Sets the weight of all arcs without a weight to [arg weight]. Returns the empty string as its result. If not present [arg weight] defaults to [const 0]. - [call [arg graphName] [method {arc setweight}] [arg arc] [arg weight]] Sets the weight of the [arg arc] to [arg weight]. Returns [arg weight]. - [call [arg graphName] [method {arc unsetweight}] [arg arc]] Removes the weight of the [arg arc], if present. Does nothing otherwise. Returns the empty string. - [call [arg graphName] [method {arc hasweight}] [arg arc]] Determines if the [arg arc] has a weight associated with it. The result is a boolean value, [const True] if a weight is defined, and [const False] otherwise. - [call [arg graphName] [method {arc source}] [arg arc]] Return the node the given [arg arc] begins at. - [call [arg graphName] [method {arc target}] [arg arc]] Return the node the given [arg arc] ends at. - [call [arg graphName] [method {arc nodes}] [arg arc]] Return the nodes the given [arg arc] begins and ends at, as a two-element list. - [call [arg graphName] [method {arc move-source}] [arg arc] [arg newsource]] Changes the source node of the arc to [arg newsource]. It can be said that the arc rotates around its target node. - [call [arg graphName] [method {arc move-target}] [arg arc] [arg newtarget]] Changes the target node of the arc to [arg newtarget]. It can be said that the arc rotates around its source node. - [call [arg graphName] [method {arc move}] [arg arc] [arg newsource] [arg newtarget]] Changes both source and target nodes of the arc to [arg newsource], and [arg newtarget] resp. - [call [arg graphName] [method {arc unset}] [arg arc] [arg key]] Remove a keyed value from the arc [arg arc]. The method will do nothing if the [arg key] does not exist. - [call [arg graphName] [method {arc weights}]] Returns a dictionary whose keys are the names of all arcs which have a weight associated with them, and the values are these weights. - [call [arg graphName] [method arcs] [opt "-key [arg key]"] [opt "-value [arg value]"] [opt "-filter [arg cmdprefix]"] [opt "-in|-out|-adj|-inner|-embedding [arg {node node...}]"]] Returns a list of arcs in the graph. If no restriction is specified a list containing all arcs is returned. Restrictions can limit the list @@ -479,11 +458,10 @@ This restriction can only be used in combination with [option -key]. It limits the list of arcs that are returned to those arcs whose associated key [arg key] has the value [arg value]. - [def "[option -filter] [arg cmdrefix]"] Limit the list of arcs that are returned to those arcs that pass the test. The command in [arg cmdprefix] is called with two arguments, the name of the graph object, and the name of the arc in question. It is @@ -491,23 +469,20 @@ value. Arcs for which the command returns [const false] are removed from the result list before it is returned to the caller. [list_end] - [call [arg graphName] [method lappend] [arg key] [arg value]] Appends a [arg value] (as a list) to one of the keyed values associated with the graph. Returns the new value given to the attribute [arg key]. - [call [arg graphName] [method {node append}] [arg node] [arg key] [arg value]] Appends a [arg value] to one of the keyed values associated with an [arg node]. Returns the new value given to the attribute [arg key]. - [call [arg graphName] [method {node attr}] [arg key]] [call [arg graphName] [method {node attr}] [arg key] [option -nodes] [arg list]] [call [arg graphName] [method {node attr}] [arg key] [option -glob] [arg globpattern]] [call [arg graphName] [method {node attr}] [arg key] [option -regexp] [arg repattern]] @@ -545,33 +520,28 @@ names match this pattern are searched for the attribute. [list_end] [para] - [call [arg graphName] [method {node degree}] [opt -in|-out] [arg node]] Return the number of arcs adjacent to the specified [arg node]. If one of the restrictions [option -in] or [option -out] is given only the incoming resp. outgoing arcs are counted. - [call [arg graphName] [method {node delete}] [arg node] [opt "[arg node]..."]] Remove the specified nodes from the graph. All of the nodes' arcs will be removed as well to prevent unconnected arcs. - [call [arg graphName] [method {node exists}] [arg node]] Return true if the specified [arg node] exists in the graph. - [call [arg graphName] [method {node get}] [arg node] [arg key]] Return the value associated with the key [arg key] for the [arg node]. - [call [arg graphName] [method {node getall}] [arg node] [opt [arg pattern]]] Returns a dictionary (suitable for use with [lb][cmd {array set}][rb]) for the [arg node]. @@ -578,67 +548,58 @@ If the [arg pattern] is specified only the attributes whose names match the pattern will be part of the returned dictionary. The pattern is a [cmd glob] pattern. - [call [arg graphName] [method {node keys}] [arg node] [opt [arg pattern]]] Returns a list of keys for the [arg node]. If the [arg pattern] is specified only the attributes whose names match the pattern will be part of the returned list. The pattern is a [cmd glob] pattern. - [call [arg graphName] [method {node keyexists}] [arg node] [arg key]] Return true if the specified [arg key] exists for the [arg node]. - [call [arg graphName] [method {node insert}] [opt [arg node]...]] Insert one or more nodes into the graph. The new nodes have no arcs connected to them. If no node is specified one node will be inserted, and the system will generate a unique name of the form [emph node][arg x] for it. - [call [arg graphName] [method {node lappend}] [arg node] [arg key] [arg value]] Appends a [arg value] (as a list) to one of the keyed values associated with an [arg node]. Returns the new value given to the attribute [arg key]. - [call [arg graphName] [method {node opposite}] [arg node] [arg arc]] Return the node at the other end of the specified [arg arc], which has to be adjacent to the given [arg node]. - [call [arg graphName] [method {node rename}] [arg node] [arg newname]] Renames the node [arg node] to [arg newname]. An error is thrown if either the node does not exist, or a node with name [arg newname] does exist. The result of the command is the new name of the node. - [call [arg graphName] [method {node set}] [arg node] [arg key] [opt [arg value]]] Set or get one of the keyed values associated with a node. A node may have any number of keyed values associated with it. If [arg value] is not specified, this command returns the current value assigned to the key; if [arg value] is specified, this command assigns that value to the key. - [call [arg graphName] [method {node unset}] [arg node] [arg key]] Remove a keyed value from the node [arg node]. The method will do nothing if the [arg key] does not exist. - [call [arg graphName] [method nodes] [opt "-key [arg key]"] [opt "-value [arg value]"] [opt "-filter [arg cmdprefix]"] [opt "-in|-out|-adj|-inner|-embedding [arg node] [arg node]..."]] Return a list of nodes in the graph. Restrictions can limit the list of returned nodes based on neighboring nodes, or based on the keyed @@ -704,15 +665,13 @@ value. Nodes for which the command returns [const false] are removed from the result list before it is returned to the caller. [list_end] - [call [arg graphName] [method get] [arg key]] Return the value associated with the key [arg key] for the graph. - [call [arg graphName] [method getall] [opt [arg pattern]]] Returns a dictionary (suitable for use with [lb][cmd {array set}][rb]) for the whole graph. @@ -719,24 +678,21 @@ If the [arg pattern] is specified only the attributes whose names match the pattern will be part of the returned dictionary. The pattern is a [cmd glob] pattern. - [call [arg graphName] [method keys] [opt [arg pattern]]] Returns a list of keys for the whole graph. If the [arg pattern] is specified only the attributes whose names match the pattern will be part of the returned list. The pattern is a [cmd glob] pattern. - [call [arg graphName] [method keyexists] [arg key]] Return true if the specified [arg key] exists for the whole graph. - [call [arg graphName] [method serialize] [opt [arg node]...]] This method serializes the sub-graph spanned up by the [arg node]s. In other words it returns a tcl value completely describing that @@ -846,30 +802,26 @@ # # This assumes that the graph has neither attribute data nor weighted arcs. }] [para] - [call [arg graphName] [method set] [arg key] [opt [arg value]]] Set or get one of the keyed values associated with a graph. A graph may have any number of keyed values associated with it. If [arg value] is not specified, this command returns the current value assigned to the key; if [arg value] is specified, this command assigns that value to the key. - [call [arg graphName] [method swap] [arg node1] [arg node2]] Swap the position of [arg node1] and [arg node2] in the graph. - [call [arg graphName] [method unset] [arg key]] Remove a keyed value from the graph. The method will do nothing if the [arg key] does not exist. - [call [arg graphName] [method walk] [arg node] \ [opt "-order [arg order]"] \ [opt "-type [arg type]"] \ [opt "-dir [arg direction]"] \ @@ -913,11 +865,10 @@ node appended. For a pre-order walk, all nodes are [const enter]ed, for a post-order all nodes are left. In a both-order walk the first visit of a node [const enter]s it, the second visit [const leave]s it. [list_end] - [section {Changes for 2.0}] The following noteworthy changes have occurred: [list_begin enumerated] @@ -970,11 +921,10 @@ Beyond the copying of whole graph objects these new API's also enable the transfer of graph objects over arbitrary channels and for easy persistence. - [enum] A new method, [method attr], was added to both [method arc] and [method node] allowing the query and retrieval of attribute data without regard to arc and node relationships. @@ -983,25 +933,10 @@ Both methods [method arcs] and [method nodes] have been extended with the ability to select arcs and nodes based on an arbitrary filtering criterium. - [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: graph}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords graph cgraph serialization] -[keywords edge arc node vertex subgraph neighbour] -[keywords adjacent loop degree] +[vset CATEGORY {struct :: graph}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/graph1.man ================================================================== --- modules/struct/graph1.man +++ modules/struct/graph1.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*-}] [manpage_begin {struct::graph_v1} n 1.2.1] +[keywords cgraph] +[keywords graph] [copyright {2002 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate directed graph objects}] [category {Data structures}] [require Tcl 8.2] @@ -68,20 +70,17 @@ Appends a [arg value] to one of the keyed values associated with an [arg arc]. If no [arg key] is specified, the key [const data] is assumed. - [call [arg graphName] [method {arc delete}] [arg arc] [opt "[arg arc] ..."]] Remove the specified arcs from the graph. - [call [arg graphName] [method {arc exists}] [arg arc]] Return true if the specified [arg arc] exists in the graph. - [call [arg graphName] [method {arc get}] [arg arc] [opt "-key [arg key]"]] Return the value associated with the key [arg key] for the [arg arc]. If no key is specified, the key [const data] is assumed. @@ -89,36 +88,31 @@ [call [arg graphName] [method {arc getall}] [arg arc]] Returns a serialized list of key/value pairs (suitable for use with [lb][cmd {array set}][rb]) for the [arg arc]. - [call [arg graphName] [method {arc keys}] [arg arc]] Returns a list of keys for the [arg arc]. - [call [arg graphName] [method {arc keyexists}] [arg arc] [opt "-key [arg key]"]] Return true if the specified [arg key] exists for the [arg arc]. If no [arg key] is specified, the key [const data] is assumed. - [call [arg graphName] [method {arc insert}] [arg start] [arg end] [opt [arg child]]] Insert an arc named [arg child] into the graph beginning at the node [arg start] and ending at the node [arg end]. If the name of the new arc is not specified the system will generate a unique name of the form [emph arc][arg x]. - [call [arg graphName] [method {arc lappend}] [arg arc] [opt "-key [arg key]"] [arg value]] Appends a [arg value] (as a list) to one of the keyed values associated with an [arg arc]. If no [arg key] is specified, the key [const data] is assumed. - [call [arg graphName] [method {arc set}] [arg arc] [opt "-key [arg key]"] [opt [arg value]]] Set or get one of the keyed values associated with an arc. If no key is specified, the key [const data] is assumed. Each arc that is @@ -127,26 +121,22 @@ [const data] automatically. An arc may have any number of keyed values associated with it. If [arg value] is not specified, this command returns the current value assigned to the key; if [arg value] is specified, this command assigns that value to the key. - [call [arg graphName] [method {arc source}] [arg arc]] Return the node the given [arg arc] begins at. - [call [arg graphName] [method {arc target}] [arg arc]] Return the node the given [arg arc] ends at. - [call [arg graphName] [method {arc unset}] [arg arc] [opt "-key [arg key]"]] Remove a keyed value from the arc [arg arc]. If no key is specified, the key [const data] is assumed. - [call [arg graphName] [method arcs] [opt "-key [arg key]"] [opt "-value [arg value]"] [opt "-in|-out|-adj|-inner|-embedding [arg nodelist]"]] Return a list of arcs in the graph. If no restriction is specified a list containing all arcs is returned. Restrictions can limit the list @@ -208,35 +198,30 @@ At last the restrictions set via [option -key] (and [option -value]) are applied. Specifying more than one [option -key] (and [option -value]) is illegal. - [call [arg graphName] [method {node append}] [arg node] [opt "-key [arg key]"] [arg value]] Appends a [arg value] to one of the keyed values associated with an [arg node]. If no [arg key] is specified, the key [const data] is assumed. - [call [arg graphName] [method {node degree}] [opt -in|-out] [arg node]] Return the number of arcs adjacent to the specified [arg node]. If one of the restrictions [option -in] or [option -out] is given only the incoming resp. outgoing arcs are counted. - [call [arg graphName] [method {node delete}] [arg node] [opt "[arg node] ..."]] Remove the specified nodes from the graph. All of the nodes' arcs will be removed as well to prevent unconnected arcs. - [call [arg graphName] [method {node exists}] [arg node]] Return true if the specified [arg node] exists in the graph. - [call [arg graphName] [method {node get}] [arg node] [opt "-key [arg key]"]] Return the value associated with the key [arg key] for the [arg node]. If no key is specified, the key [const data] is assumed. @@ -244,21 +229,18 @@ [call [arg graphName] [method {node getall}] [arg node]] Returns a serialized list of key/value pairs (suitable for use with [lb][cmd {array set}][rb]) for the [arg node]. - [call [arg graphName] [method {node keys}] [arg node]] Returns a list of keys for the [arg node]. - [call [arg graphName] [method {node keyexists}] [arg node] [opt "-key [arg key]"]] Return true if the specified [arg key] exists for the [arg node]. If no [arg key] is specified, the key [const data] is assumed. - [call [arg graphName] [method {node insert}] [opt [arg child]]] Insert a node named [arg child] into the graph. The nodes has no arcs connected to it. If the name of the new child is not specified the @@ -268,16 +250,14 @@ Appends a [arg value] (as a list) to one of the keyed values associated with an [arg node]. If no [arg key] is specified, the key [const data] is assumed. - [call [arg graphName] [method {node opposite}] [arg node] [arg arc]] Return the node at the other end of the specified [arg arc], which has to be adjacent to the given [arg node]. - [call [arg graphName] [method {node set}] [arg node] [opt "-key [arg key]"] [opt [arg value]]] Set or get one of the keyed values associated with a node. If no key is specified, the key [const data] is assumed. Each node that is @@ -285,11 +265,10 @@ [const data] automatically. A node may have any number of keyed values associated with it. If [arg value] is not specified, this command returns the current value assigned to the key; if [arg value] is specified, this command assigns that value to the key. - [call [arg graphName] [method {node unset}] [arg node] [opt "-key [arg key]"]] Remove a keyed value from the node [arg node]. If no key is specified, the key [method data] is assumed. @@ -308,33 +287,28 @@ [method arcs]. The set of nodes to return is computed as the union of all source and target nodes for all the arcs satisfying the restriction as defined for [method arcs]. - [call [arg graphName] [method get] [opt "-key [arg key]"]] Return the value associated with the key [arg key] for the graph. If no key is specified, the key [const data] is assumed. - [call [arg graphName] [method getall]] Returns a serialized list of key/value pairs (suitable for use with [lb][cmd {array set}][rb]) for the whole graph. - [call [arg graphName] [method keys]] Returns a list of keys for the whole graph. - [call [arg graphName] [method keyexists] [opt "-key [arg key]"]] Return true if the specified [arg key] exists for the whole graph. If no [arg key] is specified, the key [const data] is assumed. - [call [arg graphName] [method set] [opt "-key [arg key]"] [opt [arg value]]] Set or get one of the keyed values associated with a graph. If no key is specified, the key [const data] is assumed. Each graph has the @@ -342,15 +316,13 @@ may have any number of keyed values associated with it. If [arg value] is not specified, this command returns the current value assigned to the key; if [arg value] is specified, this command assigns that value to the key. - [call [arg graphName] [method swap] [arg node1] [arg node2]] Swap the position of [arg node1] and [arg node2] in the graph. - [call [arg graphName] [method unset] [opt "-key [arg key]"]] Remove a keyed value from the graph. If no key is specified, the key [const data] is assumed. @@ -396,19 +368,8 @@ post-order all nodes are left. In a both-order walk the first visit of a node [const enter]s it, the second visit [const leave]s it. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: graph}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords graph cgraph] +[vset CATEGORY {struct :: graph}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/graphops.man ================================================================== --- modules/struct/graphops.man +++ modules/struct/graphops.man @@ -1,7 +1,56 @@ [comment {-*- tcl -*-}] [manpage_begin struct::graph::op n 0.11.3] +[keywords {adjacency list}] +[keywords {adjacency matrix}] +[keywords adjacent] +[keywords {approximation algorithm}] +[keywords arc] +[keywords {articulation point}] +[keywords {augmenting network}] +[keywords {augmenting path}] +[keywords bfs] +[keywords bipartite] +[keywords {blocking flow}] +[keywords bridge] +[keywords {complete graph}] +[keywords {connected component}] +[keywords {cut edge}] +[keywords {cut vertex}] +[keywords degree] +[keywords {degree constrained spanning tree}] +[keywords diameter] +[keywords dijkstra] +[keywords distance] +[keywords eccentricity] +[keywords edge] +[keywords {flow network}] +[keywords graph] +[keywords heuristic] +[keywords {independent set}] +[keywords isthmus] +[keywords {level graph}] +[keywords {local searching}] +[keywords loop] +[keywords matching] +[keywords {max cut}] +[keywords {maximum flow}] +[keywords {minimal spanning tree}] +[keywords {minimum cost flow}] +[keywords {minimum degree spanning tree}] +[keywords {minimum diameter spanning tree}] +[keywords neighbour] +[keywords node] +[keywords radius] +[keywords {residual graph}] +[keywords {shortest path}] +[keywords {squared graph}] +[keywords {strongly connected component}] +[keywords subgraph] +[keywords {travelling salesman}] +[keywords vertex] +[keywords {vertex cover}] [copyright {2008 Alejandro Paz }] [copyright {2008 (docs) Andreas Kupries }] [copyright {2009 Michal Antoniewski }] [moddesc {Tcl Data Structures}] [titledesc {Operation for (un)directed graph objects}] @@ -49,19 +98,17 @@ Note that the matrix is symmetric. It does not represent the directionality of arcs, only their presence between nodes. It is also unable to represent parallel arcs in [arg g]. - - [call [cmd struct::graph::op::toAdjacencyList] [arg G] [opt [arg options]...]] Procedure creates for input graph [arg G], it's representation as [term "Adjacency List"]. It handles both directed and undirected graphs (default is undirected). It returns dictionary that for each node (key) returns list of nodes adjacent to it. When considering weighted version, for each adjacent node there is also -weight of the edge included. +weight of the edge included. [para] [list_begin definitions] [def Arguments:] @@ -86,12 +133,10 @@ is thrown if that is not the case. [list_end][comment {-- options --}] [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::kruskal] [arg g]] This command takes the graph [arg g] and returns a list containing the names of the arcs in [arg g] which span up a minimum weight spanning tree (MST), or, in the case of an un-connected graph, a minimum weight spanning @@ -110,12 +155,10 @@ [para] A note regarding the result, the command refrains from explicitly listing the nodes of the MST as this information is implicitly provided in the arcs already. - - [call [cmd struct::graph::op::prim] [arg g]] This command takes the graph [arg g] and returns a list containing the names of the arcs in [arg g] which span up a minimum weight spanning tree @@ -137,21 +180,17 @@ A note regarding the result, the command refrains from explicitly listing the nodes of the MST as this information is implicitly provided in the arcs already. - - [call [cmd struct::graph::op::isBipartite?] [arg g] [opt [arg bipartvar]]] This command takes the graph [arg g] and returns a boolean value indicating whether it is bipartite ([const true]) or not ([const false]). If the variable [arg bipartvar] is specified the two partitions of the graph are there as a list, if, and only if the graph is bipartit. If it is not the variable, if specified, is not touched. - - [call [cmd struct::graph::op::tarjan] [arg g]] This command computes the set of [emph {strongly connected}] components (SCCs) of the graph [arg g]. The result of the command is a @@ -164,12 +203,10 @@ The graph [arg g] is [term acyclic] if all SCCs in the result contain only a single node. The graph [arg g] is [term {strongly connected}] if the result contains only a single SCC containing all nodes of [arg g]. - - [call [cmd struct::graph::op::connectedComponents] [arg g]] This command computes the set of [emph connected] components (CCs) of the graph [arg g]. The result of the command is a list of sets, each of which contains the nodes for one of the CCs of [arg g]. The union @@ -179,11 +216,10 @@ [para] The graph [arg g] is [term connected] if the result contains only a single SCC containing all nodes of [arg g]. - [call [cmd struct::graph::op::connectedComponentOf] [arg g] [arg n]] This command computes the [emph connected] component (CC) of the graph [arg g] containing the node [arg n]. The result of the command is a sets which contains the nodes for the CC of [arg n] in [arg g]. @@ -191,19 +227,15 @@ [para] The command will throw an error if [arg n] is not a node of the graph [arg g]. - - [call [cmd struct::graph::op::isConnected?] [arg g]] This is a convenience command determining whether the graph [arg g] is [term connected] or not. The result is a boolean value, [const true] if the graph is connected, and [const false] otherwise. - - [call [cmd struct::graph::op::isCutVertex?] [arg g] [arg n]] This command determines whether the node [arg n] in the graph [arg g] is a [term {cut vertex}] (aka [term {articulation point}]). The result @@ -213,11 +245,10 @@ [para] The command will throw an error if [arg n] is not a node of the graph [arg g]. - [call [cmd struct::graph::op::isBridge?] [arg g] [arg a]] This command determines whether the arc [arg a] in the graph [arg g] is a [term bridge] (aka [term {cut edge}], or [term isthmus]). The result is a boolean value, [const true] if the arc is a bridge, and @@ -225,11 +256,10 @@ [para] The command will throw an error if [arg a] is not an arc of the graph [arg g]. - [call [cmd struct::graph::op::isEulerian?] [arg g] [opt [arg tourvar]]] This command determines whether the graph [arg g] is [term eulerian] or not. The result is a boolean value, [const true] if the graph is @@ -239,11 +269,10 @@ If the graph is eulerian and [arg tourvar] is specified then an euler tour is computed as well and stored in the named variable. The tour is represented by the list of arcs traversed, in the order of traversal. - [call [cmd struct::graph::op::isSemiEulerian?] [arg g] [opt [arg pathvar]]] This command determines whether the graph [arg g] is [term semi-eulerian] or not. The result is a boolean value, [const true] if the graph is semi-eulerian, and [const false] otherwise. @@ -252,11 +281,10 @@ If the graph is semi-eulerian and [arg pathvar] is specified then an euler path is computed as well and stored in the named variable. The path is represented by the list of arcs traversed, in the order of traversal. - [call [cmd struct::graph::op::dijkstra] [arg g] [arg start] [opt [arg options]...]] This command determines distances in the weighted [arg g] from the node [arg start] to all other nodes in the graph. The options specify @@ -283,17 +311,15 @@ from the node to [arg start], excluding the node itself, but including [arg start]. Tree format is the default. [list_end] - [call [cmd struct::graph::op::distance] [arg g] [arg origin] [arg destination] [opt [arg options]...]] This command determines the (un)directed distance between the two nodes [arg origin] and [arg destination] in the graph [arg g]. It accepts the option [option -arcmode] of [cmd struct::graph::op::dijkstra]. - [call [cmd struct::graph::op::eccentricity] [arg g] [arg n] [opt [arg options]...]] This command determines the (un)directed [term eccentricity] of the node [arg n] in the graph [arg g]. It accepts the option @@ -303,11 +329,10 @@ The (un)directed [term eccentricity] of a node is the maximal (un)directed distance between the node and any other node in the graph. - [call [cmd struct::graph::op::radius] [arg g] [opt [arg options]...]] This command determines the (un)directed [term radius] of the graph [arg g]. It accepts the option [option -arcmode] of [cmd struct::graph::op::dijkstra]. @@ -314,22 +339,19 @@ [para] The (un)directed [term radius] of a graph is the minimal (un)directed [term eccentricity] of all nodes in the graph. - [call [cmd struct::graph::op::diameter] [arg g] [opt [arg options]...]] This command determines the (un)directed [term diameter] of the graph [arg g]. It accepts the option [option -arcmode] of [cmd struct::graph::op::dijkstra]. [para] The (un)directed [term diameter] of a graph is the maximal (un)directed [term eccentricity] of all nodes in the graph. - - [call [cmd struct::graph::op::BellmanFord] [arg G] [arg startnode]] Searching for [sectref {Shortest Path Problem} "shortests paths"] between chosen node and all other nodes in graph [arg G]. Based on relaxation method. In comparison to [cmd struct::graph::op::dijkstra] it doesn't need assumption that all weights @@ -360,12 +382,10 @@ [para] [emph Note:] If algorithm finds a negative cycle, it will return error message. - - [call [cmd struct::graph::op::Johnsons] [arg G] [opt [arg options]...]] Searching for [sectref {Shortest Path Problem} "shortest paths"] between all pairs of vertices in graph. For sparse graphs asymptotically quicker than [cmd struct::graph::op::FloydWarshall] algorithm. Johnson's algorithm uses [cmd struct::graph::op::BellmanFord] and [cmd struct::graph::op::dijkstra] as subprocedures. @@ -392,11 +412,11 @@ [def Options:] [list_begin options] [opt_def -filter] -Returns only existing distances, cuts all [term Inf] values for +Returns only existing distances, cuts all [term Inf] values for non-existing connections between pairs of nodes. [list_end][comment {-- options --}] [def Result:] @@ -403,12 +423,10 @@ Dictionary containing distances between all pairs of vertices. [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::FloydWarshall] [arg G]] Searching for [sectref {Shortest Path Problem} "shortest paths"] between all pairs of edges in weighted graphs.[para] Time complexity: [term O(V^3)] - where [term V] is number of vertices.[para] Memory complexity: [term O(V^2)]. @@ -429,18 +447,16 @@ Dictionary containing shortest distances to each node from each node. [list_end][comment {-- definitions --}] [emph Note:] Algorithm finds solutions dynamically. It compares all possible paths through the graph between each pair of vertices. Graph shouldn't possess any cycle with negative -sum of weights (the presence of such cycles means there is no shortest path, +sum of weights (the presence of such cycles means there is no shortest path, since the total weight becomes lower each time the cycle is traversed). [para] -On the other hand algorithm can be used to find those cycles - if any shortest distance +On the other hand algorithm can be used to find those cycles - if any shortest distance found by algorithm for any nodes [term v] and [term u] (when [term v] is the same node as [term u]) is negative, that node surely belong to at least one negative cycle. - - [call [cmd struct::graph::op::MetricTravellingSalesman] [arg G]] Algorithm for solving a metric variation of [sectref {Travelling Salesman Problem} "Travelling salesman problem"]. [term "TSP problem"] is [term NP-Complete], so there is no efficient algorithm to solve it. Greedy methods @@ -461,12 +477,10 @@ each exactly one time. [list_end][comment {-- definitions --}] [emph Note:] [sectref {Approximation algorithm} "It's 2-approximation algorithm."] - - [call [cmd struct::graph::op::Christofides] [arg G]] Another algorithm for solving [sectref {Travelling Salesman Problem} "metric [term "TSP problem"]"]. Christofides implementation uses [term "Max Matching"] for reaching better approximation factor. @@ -491,12 +505,10 @@ [para] [emph Note:] [sectref {Approximation algorithm} "It's is a 3/2 approximation algorithm. "] - - [call [cmd struct::graph::op::GreedyMaxMatching] [arg G]] [term "Greedy Max Matching"] procedure, which finds [sectref {Matching Problem} "maximal matching"] (not maximum) for given graph [arg G]. It adds edges to solution, beginning from edges with the lowest cost. @@ -514,12 +526,10 @@ [def Result:] Set of edges - the max matching for graph [arg G]. [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::MaxCut] [arg G] [arg U] [arg V]] Algorithm solving a [sectref {Cut Problems} "Maximum Cut Problem"]. @@ -547,16 +557,13 @@ [list_end][comment {-- definitions --}] [emph Note:] [term MaxCut] is a [sectref {Approximation algorithm} "2-approximation algorithm."] - - [call [cmd struct::graph::op::UnweightedKCenter] [arg G] [arg k]] Approximation algorithm that solves a [sectref {K-Center Problem} "k-center problem"]. - [para] [list_begin definitions] [def Arguments:] @@ -572,12 +579,10 @@ Set of nodes - [arg k] center for graph [arg G]. [list_end][comment {-- definitions --}] [emph Note:] [term UnweightedKCenter] is a [sectref {Approximation algorithm} "2-approximation algorithm."] - - [call [cmd struct::graph::op::WeightedKCenter] [arg G] [arg nodeWeights] [arg W]] Approximation algorithm that solves a weighted version of [sectref {K-Center Problem} "k-center problem"]. @@ -599,23 +604,19 @@ Set of nodes, which is solution found by algorithm. [list_end][comment {-- definitions --}] [emph Note:][term WeightedKCenter] is a [sectref {Approximation algorithm} "3-approximation algorithm."] - - [call [cmd struct::graph::op::GreedyMaxIndependentSet] [arg G]] A [term "maximal independent set"] is an [term "independent set"] such that adding any other node to the set forces the set to contain an edge. [para] Algorithm for input graph [arg G] returns set of nodes (list), which are contained in Max Independent Set found by algorithm. - - [call [cmd struct::graph::op::GreedyWeightedMaxIndependentSet] [arg G] [arg nodeWeights]] Weighted variation of [term "Maximal Independent Set"]. It takes as an input argument not only graph [arg G] but also set of weights for all vertices in graph [arg G]. @@ -622,23 +623,19 @@ [para] [emph Note:] Read also [term "Maximal Independent Set"] description for more info. - - [call [cmd struct::graph::op::VerticesCover] [arg G]] [term "Vertices cover"] is a set of vertices such that each edge of the graph is incident to at least one vertex of the set. This 2-approximation algorithm searches for minimum -[term "vertices cover"], which is a classical optimization problem in computer science and +[term "vertices cover"], which is a classical optimization problem in computer science and is a typical example of an [term "NP-hard"] optimization problem that has an approximation algorithm. For input graph [arg G] algorithm returns the set of edges (list), which is Vertex Cover found by algorithm. - - [call [cmd struct::graph::op::EdmondsKarp] [arg G] [arg s] [arg t]] Improved Ford-Fulkerson's algorithm, computing the [sectref {Flow Problems} "maximum flow"] in given flow network [arg G]. @@ -665,26 +662,24 @@ [list_end][comment {-- definitions --}] [para] -The general idea of algorithm is finding the shortest augumenting paths in graph [arg G], as long +The general idea of algorithm is finding the shortest augumenting paths in graph [arg G], as long as they exist, and for each path updating the edge's weights along that path, with maximum possible throughput. The final (maximum) flow is found when there is no other augumenting path from source to sink. [para] [emph Note:] Algorithm complexity : [term O(V*E)], where [term V] is the number of nodes and [term E] is the number of edges in graph [term G]. - - [call [cmd struct::graph::op::BusackerGowen] [arg G] [arg desiredFlow] [arg s] [arg t]] Algorithm finds solution for a [sectref {Flow Problems} "minimum cost flow problem"]. So, the goal is to find a flow, -whose max value can be [arg desiredFlow], from source node [arg s] to sink node [arg t] in given flow network [arg G]. +whose max value can be [arg desiredFlow], from source node [arg s] to sink node [arg t] in given flow network [arg G]. That network except throughputs at edges has also defined a non-negative cost on each edge - cost of using that edge when directing flow with that edge ( it can illustrate e.g. fuel usage, time or any other measure dependent on usages ). [para] [list_begin definitions] @@ -708,17 +703,15 @@ [list_end][comment {-- definitions --}] [emph Note:] Algorithm complexity : [term O(V**2*desiredFlow)], where [term V] is the number of nodes in graph [arg G]. - - [call [cmd struct::graph::op::ShortestsPathsByBFS] [arg G] [arg s] [arg outputFormat]] Shortest pathfinding algorithm using BFS method. In comparison to [cmd struct::graph::op::dijkstra] it can work with negative weights on edges. Of course negative cycles are not allowed. Algorithm is better than dijkstra -for sparse graphs, but also there exist some pathological cases (those cases generally don't appear in practise) that +for sparse graphs, but also there exist some pathological cases (those cases generally don't appear in practise) that make time complexity increase exponentially with the growth of the number of nodes. [para] [list_begin definitions] @@ -742,15 +735,11 @@ When selected [arg outputFormat] is [const paths] - procedure returns dictionary containing for each node [term v], a list of nodes, which is a path between source node [arg s] and node [term v]. [list_end][comment {-- options --}] - - [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::BFS] [arg G] [arg s] [opt [arg outputFormat]...]] Breadth-First Search - algorithm creates the BFS Tree. Memory and time complexity: [term "O(V + E)"], where [term V] is the number of nodes and [term E] @@ -782,12 +771,10 @@ [list_end][comment {-- options --}] [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::MinimumDiameterSpanningTree] [arg G]] The goal is to find for input graph [arg G], the [term "spanning tree"] that has the minimum [term "diameter"] value. @@ -811,21 +798,19 @@ [para] For input graph [arg G] algorithm returns the graph structure ([cmd struct::graph]) that is a spanning tree with minimum diameter found by algorithm. - - [call [cmd struct::graph::op::MinimumDegreeSpanningTree] [arg G]] Algorithm finds for input graph [arg G], a spanning tree [term T] with the minimum possible degree. That problem is [term NP-hard], so algorithm is an approximation algorithm. [para] Let [term V] be the set of nodes for graph [arg G] and let [term W] be any subset of [term V]. Lets -assume also that [term OPT] is optimal solution and [term ALG] is solution found by algorithm for input +assume also that [term OPT] is optimal solution and [term ALG] is solution found by algorithm for input graph [arg G]. [para] It can be proven that solution found with the algorithm must fulfil inequality: [para] [term "((|W| + k - 1) / |W|) <= ALG <= 2*OPT + log2(n) + 1"]. [para] [list_begin definitions] @@ -840,12 +825,10 @@ [def Result:] Algorithm returns graph structure, which is equivalent to spanning tree [term T] found by algorithm. [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::MaximumFlowByDinic] [arg G] [arg s] [arg t] [arg blockingFlowAlg]] Algorithm finds [sectref {Flow Problems} "maximum flow"] for the flow network represented by graph [arg G]. It is based on the blocking-flow finding methods, which give us different complexities what makes a better fit for different graphs. @@ -854,11 +837,11 @@ [list_begin definitions] [def Arguments:] [list_begin arguments] [arg_def {Graph Object} G input] -Directed graph [arg G] representing the flow network. Each edge should have attribute +Directed graph [arg G] representing the flow network. Each edge should have attribute [term throughput] set with integer value. [arg_def {Node} s input] The source node for the flow network [arg G]. @@ -886,12 +869,10 @@ [emph Note:] [cmd struct::graph::op::BlockingFlowByDinic] gives [term O(m*n^2)] complexity and [cmd struct::graph::op::BlockingFlowByMKM] gives [term O(n^3)] complexity, where [term n] is the number of nodes and [term m] is the number of edges in flow network [arg G]. - - [call [cmd struct::graph::op::BlockingFlowByDinic] [arg G] [arg s] [arg t]] Algorithm for given network [arg G] with source [arg s] and sink [arg t], finds a [sectref {Flow Problems} "blocking flow"], which can be used to obtain a [term "maximum flow"] for that network [arg G]. @@ -899,11 +880,11 @@ [list_begin definitions] [def Arguments:] [list_begin arguments] [arg_def {Graph Object} G input] -Directed graph [arg G] representing the flow network. Each edge should have attribute +Directed graph [arg G] representing the flow network. Each edge should have attribute [term throughput] set with integer value. [arg_def {Node} s input] The source node for the flow network [arg G]. [arg_def {Node} t input] The sink node for the flow network [arg G]. @@ -915,12 +896,10 @@ [list_end][comment {-- definitions --}] [emph Note:] Algorithm's complexity is [term O(n*m)], where [term n] is the number of nodes and [term m] is the number of edges in flow network [arg G]. - - [call [cmd struct::graph::op::BlockingFlowByMKM] [arg G] [arg s] [arg t]] Algorithm for given network [arg G] with source [arg s] and sink [arg t], finds a [sectref {Flow Problems} "blocking flow"], which can be used to obtain a [term "maximum flow"] for that [term network] [arg G]. @@ -928,11 +907,11 @@ [list_begin definitions] [def Arguments:] [list_begin arguments] [arg_def {Graph Object} G input] -Directed graph [arg G] representing the flow network. Each edge should have attribute +Directed graph [arg G] representing the flow network. Each edge should have attribute [term throughput] set with integer value. [arg_def {Node} s input] The source node for the flow network [arg G]. [arg_def {Node} t input] The sink node for the flow network [arg G]. @@ -944,14 +923,11 @@ [list_end][comment {-- definitions --}] [emph Note:] Algorithm's complexity is [term O(n^2)], where [term n] is the number of nodes in flow network [arg G]. - - [call [cmd struct::graph::op::createResidualGraph] [arg G] [arg f]] - Procedure creates a [term "residual graph"] (or [sectref {Flow Problems} "residual network"] ) for network [arg G] and given flow [arg f]. [para] @@ -970,15 +946,13 @@ [def Result:] Procedure returns graph structure that is a [term "residual graph"] created from input flow network [arg G]. [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::createAugmentingNetwork] [arg G] [arg f] [arg path]] -Procedure creates an [sectref {Flow Problems} "augmenting network"] for a given residual network [arg G] +Procedure creates an [sectref {Flow Problems} "augmenting network"] for a given residual network [arg G] , flow [arg f] and augmenting path [arg path]. [para] [list_begin definitions] @@ -996,12 +970,10 @@ [def Result:] Algorithm returns graph structure containing the modified augmenting network. [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::createLevelGraph] [arg Gf] [arg s]] For given residual graph [arg Gf] procedure finds the [sectref {Flow Problems} "level graph"]. [para] @@ -1017,12 +989,10 @@ [def Result:] Procedure returns a [term "level graph"] created from input [term "residual network"]. [list_end][comment {-- definitions --}] - - [call [cmd struct::graph::op::TSPLocalSearching] [arg G] [arg C]] Algorithm is a [term "heuristic of local searching"] for [term "Travelling Salesman Problem"]. For some solution of [term "TSP problem"], it checks if it's possible to find a better solution. As [term "TSP"] is well known NP-Complete problem, so algorithm is a approximation algorithm (with 2 approximation factor). @@ -1033,22 +1003,20 @@ [def Arguments:] [list_begin arguments] [arg_def {Graph Object} G input] Undirected and complete graph with attributes "weight" set on each single edge. [arg_def {List} C input] -A list of edges being [term "Hamiltonian cycle"], which is solution of [term "TSP Problem"] for graph [arg G]. +A list of edges being [term "Hamiltonian cycle"], which is solution of [term "TSP Problem"] for graph [arg G]. [list_end][comment {-- arguments --}] [def Result:] Algorithm returns the best solution for [term "TSP problem"], it was able to find. [list_end][comment {-- definitions --}] [emph Note:] The solution depends on the choosing of the beginning cycle [arg C]. It's not true that better cycle assures that better solution will be found, but practise shows that we should give starting cycle with as small sum of weights as possible. - - [call [cmd struct::graph::op::TSPLocalSearching3Approx] [arg G] [arg C]] Algorithm is a [term "heuristic of local searching"] for [term "Travelling Salesman Problem"]. For some solution of [term "TSP problem"], it checks if it's possible to find a better solution. As [term "TSP"] @@ -1061,23 +1029,21 @@ [def Arguments:] [list_begin arguments] [arg_def {Graph Object} G input] Undirected and complete graph with attributes "weight" set on each single edge. [arg_def {List} C input] -A list of edges being [term "Hamiltonian cycle"], which is solution of [term "TSP Problem"] for graph [arg G]. +A list of edges being [term "Hamiltonian cycle"], which is solution of [term "TSP Problem"] for graph [arg G]. [list_end][comment {-- arguments --}] [def Result:] Algorithm returns the best solution for [term "TSP problem"], it was able to find. [list_end][comment {-- definitions --}] [emph Note:] In practise 3-approximation algorithm turns out to be far more effective than 2-approximation, but it gives -worser approximation factor. Further heuristics of local searching (e.g. 4-approximation) doesn't give enough boost to +worser approximation factor. Further heuristics of local searching (e.g. 4-approximation) doesn't give enough boost to square the increase of approximation factor, so 2 and 3 approximations are mainly used. - - [call [cmd struct::graph::op::createSquaredGraph] [arg G]] X-Squared graph is a graph with the same set of nodes as input graph [arg G], but a different set of edges. X-Squared graph has edge [term (u,v)], if and only if, the distance between [term u] and [term v] nodes is not greater than X and [term "u != v"]. @@ -1086,24 +1052,18 @@ [para] [emph Note:] Distances used in choosing new set of edges are considering the number of edges, not the sum of weights at edges. - - [call [cmd struct::graph::op::createCompleteGraph] [arg G] [arg originalEdges]] For input graph [arg G] procedure adds missing arcs to make it a [term "complete graph"]. It also holds in variable [arg originalEdges] the set of arcs that graph [arg G] possessed before that operation. [list_end] - - [section "Background theory and terms"] - - [subsection "Shortest Path Problem"] [list_begin definitions] @@ -1113,12 +1073,12 @@ the sum of weights on edges along the path is minimal among all paths connecting v to v'. [def "Generalizations:"] [list_begin itemized] -[item][term "The single-source shortest path problem"], in which we have to find shortest paths from a source vertex v to all other vertices in the graph. -[item][term "The single-destination shortest path problem"], in which we have to find shortest paths from all vertices in the graph to a single destination vertex v. This can be reduced to the single-source shortest path problem by reversing the edges in the graph. +[item][term "The single-source shortest path problem"], in which we have to find shortest paths from a source vertex v to all other vertices in the graph. +[item][term "The single-destination shortest path problem"], in which we have to find shortest paths from all vertices in the graph to a single destination vertex v. This can be reduced to the single-source shortest path problem by reversing the edges in the graph. [item][term "The all-pairs shortest path problem"], in which we have to find shortest paths between every pair of vertices v, v' in the graph. [list_end][comment {-- itemized --}] [emph "Note:"] The result of [term "Shortest Path problem"] can be [term "Shortest Path tree"], which is a subgraph of a given (possibly weighted) graph constructed so that the @@ -1125,37 +1085,36 @@ distance between a selected root node and all other nodes is minimal. It is a tree because if there are two paths between the root node and some vertex v (i.e. a cycle), we can delete the last edge of the longer path without increasing the distance from the root node to any node in the subgraph. [list_end][comment {-- definitions --}] - [subsection "Travelling Salesman Problem"] [list_begin definitions] [def "Definition:"] -For given edge-weighted (weights on edges should be positive) graph the goal is to find the cycle that visits each node in graph +For given edge-weighted (weights on edges should be positive) graph the goal is to find the cycle that visits each node in graph exactly once ([term "Hamiltonian cycle"]). [def "Generalizations:"] [list_begin itemized] [item][term "Metric TSP"] - A very natural restriction of the [term TSP] is to require that the distances between cities form a [term metric], i.e., they satisfy [term "the triangle inequality"]. That is, for any 3 cities [term A], [term B] and [term C], the distance between [term A] and [term C] -must be at most the distance from [term A] to [term B] plus the distance from [term B] to [term C]. Most natural instances of [term TSP] +must be at most the distance from [term A] to [term B] plus the distance from [term B] to [term C]. Most natural instances of [term TSP] satisfy this constraint. -[item][term "Euclidean TSP"] - Euclidean TSP, or [term "planar TSP"], is the [term TSP] with the distance being the ordinary [term "Euclidean distance"]. +[item][term "Euclidean TSP"] - Euclidean TSP, or [term "planar TSP"], is the [term TSP] with the distance being the ordinary [term "Euclidean distance"]. [term "Euclidean TSP"] is a particular case of [term TSP] with [term "triangle inequality"], since distances in plane obey triangle inequality. However, -it seems to be easier than general [term TSP] with [term "triangle inequality"]. For example, [term "the minimum spanning tree"] of the graph associated -with an instance of [term "Euclidean TSP"] is a [term "Euclidean minimum spanning tree"], and so can be computed in expected [term "O(n log n)"] time for -[term n] points (considerably less than the number of edges). This enables the simple [term "2-approximation algorithm"] for TSP with triangle +it seems to be easier than general [term TSP] with [term "triangle inequality"]. For example, [term "the minimum spanning tree"] of the graph associated +with an instance of [term "Euclidean TSP"] is a [term "Euclidean minimum spanning tree"], and so can be computed in expected [term "O(n log n)"] time for +[term n] points (considerably less than the number of edges). This enables the simple [term "2-approximation algorithm"] for TSP with triangle inequality above to operate more quickly. [item][term "Asymmetric TSP"] - In most cases, the distance between two nodes in the [term TSP] network is the same in both directions. The case where the distance from [term A] to [term B] is not equal to the distance from [term B] to [term A] is called [term "asymmetric TSP"]. -A practical application of an [term "asymmetric TSP"] is route optimisation using street-level routing (asymmetric due to one-way streets, +A practical application of an [term "asymmetric TSP"] is route optimisation using street-level routing (asymmetric due to one-way streets, slip-roads and motorways). [list_end][comment {-- itemized --}] [list_end][comment {-- definitions --}] @@ -1166,25 +1125,24 @@ [def "Definition:"] Given a graph [term "G = (V,E)"], a matching or [term "edge-independent set"] [term M] in [term G] is a set of pairwise non-adjacent edges, that is, no two edges share a common vertex. A vertex is [term matched] if it is incident to an edge in the [term "matching M"]. Otherwise the vertex is [term unmatched]. - [def "Generalizations:"] [list_begin itemized] [item][term "Maximal matching"] - a matching [term M] of a graph G with the property that if any edge not in [term M] is added to [term M], -it is no longer a [term matching], that is, [term M] is maximal if it is not a proper subset of any other [term matching] in graph G. +it is no longer a [term matching], that is, [term M] is maximal if it is not a proper subset of any other [term matching] in graph G. In other words, a [term "matching M"] of a graph G is maximal if every edge in G has a non-empty intersection with at least one edge in [term M]. [item][term "Maximum matching"] - a matching that contains the largest possible number of edges. There may be many [term "maximum matchings"]. The [term "matching number"] of a graph G is the size of a [term "maximum matching"]. Note that every [term "maximum matching"] is [term maximal], but not every [term "maximal matching"] is a [term "maximum matching"]. [item][term "Perfect matching"] - a matching which matches all vertices of the graph. That is, every vertex of the graph is incident to exactly one edge of the matching. Every [term "perfect matching"] is [term maximum] and hence [term maximal]. In some literature, the term [term "complete matching"] -is used. A [term "perfect matching"] is also a [term "minimum-size edge cover"]. Moreover, the size of a [term "maximum matching"] is no larger than the +is used. A [term "perfect matching"] is also a [term "minimum-size edge cover"]. Moreover, the size of a [term "maximum matching"] is no larger than the size of a [term "minimum edge cover"]. [item][term "Near-perfect matching"] - a matching in which exactly one vertex is unmatched. This can only occur when the graph has an odd number of vertices, and such a [term matching] must be [term maximum]. If, for every vertex in a graph, there is a near-perfect matching that omits only that vertex, the graph is also called [term factor-critical]. @@ -1195,48 +1153,45 @@ [list_begin itemized] [item][term "Alternating path"] - given a matching [term M], an [term "alternating path"] is a path in which the edges belong alternatively to the matching and not to the matching. -[item][term "Augmenting path"] - given a matching [term M], an [term "augmenting path"] is an [term "alternating path"] that starts from +[item][term "Augmenting path"] - given a matching [term M], an [term "augmenting path"] is an [term "alternating path"] that starts from and ends on free (unmatched) vertices. [list_end][comment {-- itemized --}] [list_end][comment {-- definitons --}] - - [subsection "Cut Problems"] [list_begin definitions] [def "Definition:"] -A [term cut] is a partition of the vertices of a graph into two [term "disjoint subsets"]. The [term cut-set] of the [term cut] is the +A [term cut] is a partition of the vertices of a graph into two [term "disjoint subsets"]. The [term cut-set] of the [term cut] is the set of edges whose end points are in different subsets of the partition. Edges are said to be crossing the cut if they are in its [term cut-set]. [para] Formally: [list_begin itemized] [item] a [term cut] [term "C = (S,T)"] is a partition of [term V] of a graph [term "G = (V, E)"]. [item] an [term "s-t cut"] [term "C = (S,T)"] of a [term "flow network"] [term "N = (V, E)"] is a cut of [term N] such that [term s] is included in [term S] -and [term t] is included in [term T], where [term s] and [term t] are the [term source] and the [term sink] of [term N] respectively. +and [term t] is included in [term T], where [term s] and [term t] are the [term source] and the [term sink] of [term N] respectively. [item] The [term cut-set] of a [term "cut C = (S,T)"] is such set of edges from graph [term "G = (V, E)"] that each edge [term "(u, v)"] satisfies condition that [term u] is included in [term S] and [term v] is included in [term T]. [list_end][comment {-- itemized --}] -[para] +[para] In an [term "unweighted undirected"] graph, the size or weight of a cut is the number of edges crossing the cut. In a [term "weighted graph"], the same term is defined by the sum of the weights of the edges crossing the cut. [para] In a [term "flow network"], an [term "s-t cut"] is a cut that requires the [term source] and the [term sink] to be in different subsets, and its [term cut-set] only consists of edges going from the [term source's] side to the [term sink's] side. The capacity of an [term "s-t cut"] is defined by the sum of capacity of each edge in the [term cut-set]. [para] The [term cut] of a graph can sometimes refer to its [term cut-set] instead of the partition. - [def "Generalizations:"] [list_begin itemized] [item][term "Minimum cut"] - A cut is minimum if the size of the cut is not larger than the size of any other cut. [item][term "Maximum cut"] - A cut is maximum if the size of the cut is not smaller than the size of any other cut. @@ -1243,11 +1198,10 @@ [item][term "Sparsest cut"] - The [term "Sparsest cut problem"] is to bipartition the vertices so as to minimize the ratio of the number of edges across the cut divided by the number of vertices in the smaller half of the partition. [list_end][comment {-- itemized --}] [list_end][comment {-- definitons --}] - [subsection "K-Center Problem"] [list_begin definitions] @@ -1270,29 +1224,27 @@ has the smallest possible worth ( [term v] is a node in [term V] and [term u] is a node in [term S] ). [list_end][comment {-- definitions --}] [list_end][comment {-- definitions --}] - - [subsection "Flow Problems"] [list_begin definitions] [def "Definitions:"] [list_begin itemized] [item][term "the maximum flow problem"] - the goal is to find a feasible flow through a single-source, single-sink flow network that is maximum. The [term "maximum flow problem"] can be seen as a special case of more complex network flow problems, such as the [term "circulation problem"]. The maximum value of an [term "s-t flow"] is equal to the minimum capacity of an [term "s-t cut"] in the network, as stated in the -[term "max-flow min-cut theorem"]. +[term "max-flow min-cut theorem"]. [para] More formally for flow network [term "G = (V,E)"], where for each edge [term "(u, v)"] we have its throuhgput [term "c(u,v)"] defined. As [term flow] [term F] we define set of non-negative integer attributes [term f(u,v)] assigned to edges, satisfying such conditions: [list_begin enumerated] [enum]for each edge [term "(u, v)"] in [term G] such condition should be satisfied: 0 <= f(u,v) <= c(u,v) [enum]Network [term G] has source node [term s] such that the flow [term F] is equal to the sum of outcoming flow decreased by the sum of incoming flow from that source node [term s]. -[enum]Network [term G] has sink node [term t] such that the the [term -F] value is equal to the sum of the incoming flow decreased by the sum of outcoming flow from that sink node [term t]. +[enum]Network [term G] has sink node [term t] such that the the [term -F] value is equal to the sum of the incoming flow decreased by the sum of outcoming flow from that sink node [term t]. [enum]For each node that is not a [term source] or [term sink] the sum of incoming flow and sum of outcoming flow should be equal. [list_end][comment {-- enumerated --}] [item][term "the minimum cost flow problem"] - the goal is finding the cheapest possible way of sending a certain amount of flow through a [term "flow network"]. @@ -1313,29 +1265,24 @@ are different. [list_end][comment {-- itemized --}] [list_end][comment {-- definitions --}] - - - [subsection "Approximation algorithm"] [list_begin definitions] [def "k-approximation algorithm:"] Algorithm is a k-approximation, when for [term ALG] (solution returned by algorithm) and -[term OPT] (optimal solution), such inequality is true: +[term OPT] (optimal solution), such inequality is true: [list_begin itemized] [item] for minimalization problems: [term "ALG/OPT <= k" ] [item] for maximalization problems: [term "OPT/ALG <= k" ] [list_end][comment {-- itemized --}] - [list_end][comment {-- definitions --}] - [section References] [list_begin enum] [enum] [uri http://en.wikipedia.org/wiki/Adjacency_matrix {Adjacency matrix}] @@ -1364,30 +1311,8 @@ [enum] [uri http://en.wikipedia.org/wiki/Breadth-first_search {BFS}] [enum] [uri http://en.wikipedia.org/wiki/Degree-constrained_spanning_tree {Minimum Degree Spanning Tree}] [enum] [uri http://en.wikipedia.org/wiki/Approximation_algorithm {Approximation algorithm}] [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: graph}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords graph dijkstra distance radius diameter eccentricity] -[keywords edge arc node vertex subgraph neighbour] -[keywords adjacent loop degree] -[keywords {cut vertex} {articulation point} {connected component}] -[keywords {strongly connected component} {adjacency matrix} {adjacency list}] -[keywords {minimal spanning tree} bipartite bridge {cut edge} isthmus] -[keywords {shortest path} {travelling salesman} {max cut} matching {independent set}] -[keywords {vertex cover} {maximum flow} {minimum cost flow} {blocking flow}] -[keywords {augmenting path} {residual graph} {level graph} {flow network} {augmenting network}] -[keywords {complete graph} {squared graph} {local searching} {heuristic} {bfs} {approximation algorithm}] -[keywords {minimum diameter spanning tree} {minimum degree spanning tree} {degree constrained spanning tree}] +[vset CATEGORY {struct :: graph}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/matrix.man ================================================================== --- modules/struct/matrix.man +++ modules/struct/matrix.man @@ -1,7 +1,8 @@ [comment {-*- tcl -*-}] [manpage_begin struct::matrix n 2.0.1] +[keywords matrix] [copyright {2002 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate matrix objects}] [category {Data structures}] [require Tcl 8.2] @@ -29,11 +30,10 @@ application. A specialty of this structure is the ability to export an array-view onto its contents. Such can be used by tkTable, for example, to link the matrix into the display. [para] - The main command of the package is: [list_begin definitions] @@ -74,11 +74,11 @@ [example { ::struct::matrix mymatrix mymatrix = b }] [para] -and +and [para] [example { ::struct::matrix mymatrix deserialize $b }] [para] @@ -86,11 +86,10 @@ [para] [example { ::struct::matrix mymatrix mymatrix deserialize $b }] - [list_end] [para] @@ -111,11 +110,10 @@ [para] [example_begin] [arg matrixName] [method deserialize] [lb][arg sourcematrix] [method serialize][rb] [example_end] - [call [arg matrixName] [method -->] [arg destmatrix]] This is the reverse assignment operator for matrix objects. It copies the matrix contained in the matrix object [arg matrixName] over the matrix data in the object [arg destmatrix]. @@ -127,11 +125,10 @@ This operation is in effect equivalent to [para] [example_begin] [arg destmatrix] [method deserialize] [lb][arg matrixName] [method serialize][rb] [example_end] - [call [arg matrixName] [method {add column}] [opt [arg values]]] Extends the matrix by one column and then acts like [method {set column}] (see below) on this new column if there were [arg values] @@ -185,40 +182,35 @@ [call [arg matrixName] [method {delete column}] [arg column]] Deletes the specified column from the matrix and shifts all columns with higher indices one index down. - [call [arg matrixName] [method {delete columns}] [arg n]] Deletes [arg n] columns from the right of the matrix. The value of [arg n] has to satisfy the constraint "0 < [arg n] < [lb][cmd matrixName] [method columns][rb]" - [call [arg matrixName] [method {delete row}] [arg row]] Deletes the specified row from the matrix and shifts all row with higher indices one index down. - [call [arg matrixName] [method {delete rows}] [arg n]] Deletes [arg n] rows from the bottom of the matrix. The value of [arg n] has to satisfy the constraint "0 < [arg n] < [lb][cmd matrixName] [method rows][rb]" - [call [arg matrixName] [method deserialize] [arg serialization]] This is the complement to [method serialize]. It replaces matrix data in [arg matrixName] with the matrix described by the [arg serialization] value. The old contents of [arg matrixName] are deleted by this operation. - [call [arg matrixName] [method destroy]] Destroys the matrix, including its storage space and associated command. @@ -310,16 +302,14 @@ [arg column,row]. If the option [option -transpose] is specified the key [arg row,column] will be used instead. It is possible to link the matrix to more than one array. Note that the link is bidirectional, i.e. changes to the array are mirrored in the matrix too. - [call [arg matrixName] [method links]] Returns a list containing the names of all array variables the matrix was linked to through a call to method [method link]. - [call [arg matrixName] [method rowheight] [arg row]] Returns the height of the specified row in lines. This is the highest number of lines spanned by a cell over all cells in the row. @@ -361,11 +351,10 @@ [call [arg matrixName] [method search] [opt -nocase] [opt -exact|-glob|-regexp] [method rect] [arg {column_tl row_tl column_br row_br pattern}]] Like [method {search all}], but the search is restricted to the specified rectangular area of the matrix. - [call [arg matrixName] [method serialize] [opt [arg {column_tl row_tl column_br row_br}]]] This method serializes the sub-matrix spanned up by the rectangle specification. In other words it returns a tcl [emph value] completely @@ -414,11 +403,10 @@ # is # # 3 4 {{a b d g} {c e} {f}} }] [para] - [call [arg matrixName] [method {set cell}] [arg {column row value}]] Sets the value in the cell identified by row and column index to the data in the third argument. @@ -477,16 +465,14 @@ [call [arg matrixName] [method {swap rows}] [arg {row_a row_b}]] Swaps the contents of the two specified rows. - [call [arg matrixName] [method transpose]] Transposes the contents of the matrix, i.e. swaps rows for columns and vice versa. - [call [arg matrixName] [method unlink] [arg arrayvar]] Removes the link between the matrix and the specified arrayvariable, if there is one. @@ -542,19 +528,8 @@ % % # alternate way of doing the above % r printmatrix m }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: matrix}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords matrix] +[vset CATEGORY {struct :: matrix}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/matrix1.man ================================================================== --- modules/struct/matrix1.man +++ modules/struct/matrix1.man @@ -1,7 +1,8 @@ [comment {-*- tcl -*-}] [manpage_begin {struct::matrix_v1} n 1.2.1] +[keywords matrix] [copyright {2002 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate matrix objects}] [category {Data structures}] [require Tcl 8.2] @@ -204,16 +205,14 @@ [arg column,row]. If the option [option -transpose] is specified the key [arg row,column] will be used instead. It is possible to link the matrix to more than one array. Note that the link is bidirectional, i.e. changes to the array are mirrored in the matrix too. - [call [arg matrixName] [method links]] Returns a list containing the names of all array variables the matrix was linked to through a call to method [method link]. - [call [arg matrixName] [method rowheight] [arg row]] Returns the height of the specified row in lines. This is the highest number of lines spanned by a cell over all cells in the row. @@ -375,19 +374,8 @@ % % # alternate way of doing the above % r printmatrix m }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: matrix}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords matrix] +[vset CATEGORY {struct :: matrix}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/pool.man ================================================================== --- modules/struct/pool.man +++ modules/struct/pool.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*-}] [manpage_begin struct::pool n 1.2.1] +[keywords {discrete items}] +[keywords finite] +[keywords pool] +[keywords struct] [copyright {2002, Erik Leunissen }] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate pool objects (of discrete items)}] [category {Data structures}] [require Tcl 8.2] @@ -20,11 +24,11 @@ new pool will be named pool[var X], where X is a positive integer. The optional second argument [arg maxsize] has to be a positive integer indicating the maximum size of the pool; this is the maximum number of items the pool may hold. The default for this value is [const 10]. - + [para] The pool object has an associated global Tcl command whose name is [arg poolName]. This command may be used to invoke various configuration operations on the report. It has the following general @@ -39,16 +43,16 @@ [list_end] [list_end] [para] - + [section {POOLS AND ALLOCATION}] - + The purpose of the pool command and the pool object command that it generates, is to manage pools of discrete items. - + Examples of a pool of discrete items are: [list_begin itemized] [item] @@ -76,28 +80,27 @@ released before it can be re-allocated. While several items in a pool are being allocated and released continuously, the total number of items in the pool remains constant. [para] - + Keeping track of which items are allocated, and by whom, is the purpose of the pool command and its subordinates. -[para] +[para] [emph {Pool parlance}]: If we say that an item is [term allocated], it means that the item is [term busy], [term owned] or [term occupied]; it is not available anymore. If an item is [term free], it is [term available]. Deallocating an item is equivalent to setting free or releasing an item. The person or entity to which the item has been allotted is said to own the item. - - + [section ITEMS] - + [emph {Discrete items}] [para] The [cmd pool] command is designed for @@ -124,11 +127,11 @@ equivalent. The manager of a pool is indifferent about which entity/person occupies a given item. However, clients may have preferences for a particular item, based on some item property they know. -[para] +[para] [emph Preferences] [para] A future owner may have a preference for a particular item. Preference based allocation is supported (see the [option -prefer] option to the @@ -135,83 +138,80 @@ request subcommand). A preference for a particular item is most likely to result from variability among features associated with the items. Note that the pool commands themselves are not designed to manage such item properties. If item properties play a role in an application, they should be managed separately. - - + [section {POOL OBJECT COMMAND}] - + The following subcommands and corresponding arguments are available to any pool object command. [list_begin definitions] - + [call [arg poolName] [method add] [arg itemName1] [opt [arg {itemName2 itemName3 ...}]]] This command adds the items on the command line to the pool. If duplicate item names occur on the command line, an error is raised. If one or more of the items already exist in the pool, this also is considered an error. - [call [arg poolName] [method clear] [opt [option -force]]] Removes all items from the pool. If there are any allocated items at the time when the command is invoked, an error is raised. This behaviour may be modified through the [option -force] argument. If it is supplied on the command line, the pool will be cleared regardless the allocation state of its items. - + [call [arg poolName] [method destroy] [opt [option -force]]] Destroys the pool data structure, all associated variables and the associated pool object command. By default, the command checks whether any items are still allocated and raises an error if such is the case. This behaviour may be modified through the argument [option -force]. If it is supplied on the command line, the pool data structure will be destroyed regardless allocation state of its items. - [call [arg poolName] [method info] [arg type] [opt [arg arg]]] Returns various information about the pool for further programmatic use. The [arg type] argument indicates the type of information requested. Only the type [const allocID] uses an additional argument. [list_begin definitions] - + [def "[const allocID] [arg itemName]"] returns the allocID of the item whose name is [arg itemName]. Free items have an allocation id of [const -1]. [def [const allitems]] returns a list of all items in the pool. - + [def [const allocstate]] Returns a list of key-value pairs, where the keys are the items and the values are the corresponding allocation id's. Free items have an allocation id of [const -1]. - + [def [const cursize]] returns the current pool size, i.e. the number of items in the pool. - + [def [const freeitems]] returns a list of items that currently are not allocated. - + [def [const maxsize]] returns the maximum size of the pool. [list_end] -[para] +[para] [call [arg poolName] [method maxsize] [opt [arg maxsize]]] Sets or queries the maximum size of the pool, depending on whether the [arg maxsize] argument is supplied or not. If [arg maxsize] is @@ -222,27 +222,24 @@ [para] [cmd {poolName info maxsize}]. [para] The [arg maxsize] argument has to be a positive integer. - - + [call [arg poolName] [method release] [arg itemName]] Releases the item whose name is [arg itemName] that was allocated previously. An error is raised if the item was not allocated at the time when the command was issued. - [call [arg poolName] [method remove] [arg itemName] [opt [option -force]]] Removes the item whose name is [arg itemName] from the pool. If the item was allocated at the time when the command was invoked, an error is raised. This behaviour may be modified through the optional argument [option -force]. If it is supplied on the command line, the item will be removed regardless its allocation state. - [call [arg poolName] [method request] itemVar [opt options]] Handles a request for an item, taking into account a possible preference for a particular item. There are two possible outcomes @@ -274,11 +271,11 @@ [para] The following options are supported: [list_begin definitions] - + [def "[option -allocID] [arg allocID]"] If the request is honoured, an item will be allocated to the entity identified by allocID. If the allocation state of an item is queried, it is this allocation ID that will be returned. If the option @@ -285,30 +282,29 @@ [option -allocID] is not supplied, the item will be given to and owned by [const dummyID]. Allocation id's may be anything except the value -1, which is reserved for free items. - [def "[option -prefer] [arg preferredItem]"] This option modifies the allocation strategy as follows: If the item whose name is [arg preferredItem] is not allocated at the time when the command is invoked, the request is honoured (return value is 1). If the item was allocated at the time when the command was invoked, the request is denied (return value is 0). -[list_end] -[list_end] - +[list_end] +[list_end] + [section EXAMPLES] - + Two examples are provided. The first one mimics a step by step interactive tclsh session, where each step is explained. The second example shows the usage in a server application that talks to a back-end application. -[para] +[para] [emph {Example 1}] [para] This example presents an interactive tclsh session which considers the case of a Car rental's collection of cars. Ten steps explain its usage @@ -325,29 +321,29 @@ items, they need to be managed separately. In the latter case the items should be labeled with more neutral names such as: car1, car2, car3 , etc ... and a separate database or array should hold the brand names associated with the car labels. -[para] -[example { +[para] +[example { 1. Load the package into an interpreter % package require pool 0.1 - + 2. Create a pool object called `CarPool' with a maximum size of 55 items (cars): % pool CarPool 55 CarPool - + 4. Add items to the pool: % CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen - + 5. Somebody crashed the Toyota. Remove it from the pool as follows: % CarPool remove Toyota - + 6. Acquired a new car for the pool. Add it as follows: % CarPool add Nissan - + 7. Check whether the pool was adjusted correctly: % CarPool info allitems Trabant Chrysler1 Chrysler2 Volkswagen Nissan }] @@ -354,12 +350,12 @@ [para] Suspend the interactive session temporarily, and show the programmatic use of the request subcommand: -[para] -[example { +[para] +[example { # Mrs. Swift needs a car. She doesn't have a preference for a # particular car. We'll issue a request on her behalf as follows: if { [CarPool request car -allocID "Mrs. Swift"] } { # request was honoured, process the variable `car' puts "$car has been allocated to [CarPool info allocID $car]." @@ -372,11 +368,11 @@ Note how the [cmd if] command uses the value returned by the [method request] subcommand. [para] -[example { +[example { # Suppose Mr. Wiggly has a preference for the Trabant: if { [CarPool request car -allocID "Mr. Wiggly" -prefer Trabant] } { # request was honoured, process the variable `car' puts "$car has been allocated to [CarPool info allocID $car]." } else { @@ -390,18 +386,18 @@ [para] [example { 8. When the car is returned then you can render it available by: % CarPool release Trabant - + 9. When done, you delete the pool. % CarPool destroy Couldn't destroy `CarPool' because some items are still allocated. - + Oops, forgot that Mrs. Swift still occupies a car. - - 10. We force the destruction of the pool as follows: + + 10. We force the destruction of the pool as follows: % CarPool destroy -force }] [para] [emph {Example 2}] @@ -416,19 +412,19 @@ along. The file descriptors that identify the channels to these back-end instances make up a pool of connections. A particular connection may be allocated to just one client request at a time. [para] -[example { +[example { # Create the pool of connections (pipes) set maxpipes 10 pool Pipes $maxpipes for {set i 0} {$i < $maxpipes} {incr i} { set fd [open "|backendApplication" w+] Pipes add $fd } - + # A client request comes in. The request is identified as `clientX'. # Dispatch it onto an instance of a back-end application if { [Pipes request fd -allocID clientX] } { # a connection was allocated # communicate to the back-end application via the variable `fd' @@ -439,19 +435,8 @@ # store the client request in a queue for later processing, # or return a 'Server busy' message to the client. } }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: pool}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords struct pool finite {discrete items}] +[vset CATEGORY {struct :: pool}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/prioqueue.man ================================================================== --- modules/struct/prioqueue.man +++ modules/struct/prioqueue.man @@ -1,6 +1,9 @@ [manpage_begin struct::prioqueue n 1.4] +[keywords {ordered list}] +[keywords prioqueue] +[keywords {priority queue}] [moddesc {Tcl Data Structures}] [copyright {2003 Michael Schlenker }] [titledesc {Create and manipulate prioqueue objects}] [category {Data structures}] [require Tcl 8.2] @@ -26,11 +29,10 @@ [para] Prioqueue names are unrestricted, but may be recognized as options if no priority type is given. - [list_begin definitions] [call [cmd ::struct::prioqueue] [opt [option {-ascii|-dictionary|-integer|-real}]] [opt [arg prioqueueName]] ] The [cmd ::struct::prioqueue] command creates a new prioqueue object @@ -37,44 +39,38 @@ with an associated global Tcl command whose name is [emph prioqueueName]. This command may be used to invoke various operations on the prioqueue. It has the following general form: - [call [arg prioqueueName] [cmd option] [opt [arg {arg arg ...}]]] [cmd option] and the [arg arg]s determine the exact behavior of the command. The following commands are possible for prioqueue objects: - [call [arg prioqueueName] [cmd clear]] Remove all items from the prioqueue. - [call [arg prioqueueName] [cmd remove] [arg item]] Remove the selected item from this priority queue. - [call [arg prioqueueName] [cmd destroy]] Destroy the prioqueue, including its storage space and associated command. - [call [arg prioqueueName] [cmd get] [opt [arg count]]] Return the front [arg count] items of the prioqueue (but not their -priorities) and remove them from the prioqueue. +priorities) and remove them from the prioqueue. If [arg count] is not specified, it defaults to 1. If [arg count] is 1, the result is a simple string; otherwise, it is a list. If specified, [arg count] must be greater than or equal to 1. If there are no or too few items in the prioqueue, this command will throw an error. - [call [arg prioqueueName] [cmd peek] [opt [arg count]]] Return the front [arg count] items of the prioqueue (but not their priorities), without removing them from the prioqueue. @@ -102,28 +98,14 @@ must be a valid priority key for this type of prioqueue, otherwise an error is thrown and no item is added. Items are inserted at their priority ranking. Items with equal priority are added in the order they were added. - [call [arg prioqueueName] [cmd size]] Return the number of items in the prioqueue. - [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: prioqueue}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {ordered list} prioqueue {priority queue}] +[vset CATEGORY {struct :: prioqueue}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/queue.man ================================================================== --- modules/struct/queue.man +++ modules/struct/queue.man @@ -1,7 +1,17 @@ [comment {-*- tcl -*-}] [manpage_begin struct::queue n 1.4.5] +[keywords graph] +[keywords list] +[keywords matrix] +[keywords pool] +[keywords prioqueue] +[keywords record] +[keywords set] +[keywords skiplist] +[keywords stack] +[keywords tree] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate queue objects}] [category {Data structures}] [require Tcl 8.4] [require struct::queue [opt 1.4.5]] @@ -33,20 +43,17 @@ [call [arg queueName] [cmd option] [opt [arg "arg arg ..."]]] [arg Option] and the [arg arg]s determine the exact behavior of the command. The following commands are possible for queue objects: - [call [arg queueName] [cmd clear]] Remove all items from the queue. - [call [arg queueName] [cmd destroy]] Destroy the queue, including its storage space and associated command. - [call [arg queueName] [cmd get] [opt "[arg count]"]] Return the front [arg count] items of the queue and remove them from the queue. If [arg count] is not specified, it defaults to 1. If @@ -53,11 +60,10 @@ [arg count] is 1, the result is a simple string; otherwise, it is a list. If specified, [arg count] must be greater than or equal to 1. If there are not enough items in the queue to fulfull the request, this command will throw an error. - [call [arg queueName] [cmd peek] [opt "[arg count]"]] Return the front [arg count] items of the queue, without removing them from the queue. If [arg count] is not specified, it defaults to 1. @@ -65,42 +71,26 @@ list. If specified, [arg count] must be greater than or equal to 1. If there are not enough items in the queue to fulfull the request, this command will throw an error. - [call [arg queueName] [cmd put] [arg item] [opt "[arg "item ..."]"]] Put the [arg item] or items specified into the queue. If more than one [arg item] is given, they will be added in the order they are listed. - [call [arg queueName] [cmd unget] [arg item]] Put the [arg item] into the queue, at the front, i.e. before any other items already in the queue. This makes this operation the complement to the method [method get]. - [call [arg queueName] [cmd size]] Return the number of items in the queue. - [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: queue}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords stack matrix tree graph set list prioqueue record skiplist] -[keywords pool] +[vset CATEGORY {struct :: queue}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/record.man ================================================================== --- modules/struct/record.man +++ modules/struct/record.man @@ -1,17 +1,20 @@ [comment {-*- tcl -*-}] [manpage_begin struct::record n 1.2.1] +[keywords {data structures}] +[keywords record] +[keywords struct] [copyright {2002, Brett Schwarz }] [moddesc {Tcl Data Structures}] [titledesc {Define and create records (similar to 'C' structures)}] [category {Data structures}] [require Tcl 8.2] [require struct::record [opt 1.2.1]] [description] The [cmd ::struct::record] package provides a mechanism to group variables together -as one data structure, similar to a 'C' structure. The members of a +as one data structure, similar to a 'C' structure. The members of a record can be variables or other records. However, a record can not contain circular record, i.e. records that contain the same record as a member. [para] @@ -51,11 +54,11 @@ [call [cmd {record show}] [arg values] [arg instanceName]] Returns a list of values that are set for the instance [arg instanceName]. The output is a list of key/value pairs. If there -are nested records, then the values of the nested records will +are nested records, then the values of the nested records will itself be a list. [call [cmd {record exists}] [arg record] [arg recordName]] Tests for the existence of a [arg record] with the @@ -76,11 +79,11 @@ Deletes [arg instance] with the name of [arg instanceName]. It will return an error if the instance does not exist. [list_end] [para] - + [section {RECORD MEMBERS}] Record members can either be variables, or other records, However, the same record can not be nested witin itself (circular). To define a nested record, you need to specify the [const record] keyword, along @@ -122,11 +125,11 @@ [para] [emph {Getting Values}] [para] -To get a value of a member, there are several ways to do this. +To get a value of a member, there are several ways to do this. [list_begin enumerated] [enum] To get a member value, then use the instance built-in [method cget] method: @@ -156,11 +159,11 @@ [para] [emph {Setting Values}] [para] -To set a value of a member, there are several ways to do this. +To set a value of a member, there are several ways to do this. [list_begin enumerated] [enum] To set a member value, then use the instance built-in [method configure] method: @@ -181,11 +184,11 @@ [para] [emph {Alias access}] [para] -In the original implementation, access was done by using dot notation similar to how 'C' structures are accessed. However, +In the original implementation, access was done by using dot notation similar to how 'C' structures are accessed. However, there was a concensus to make the interface more Tcl like, which made sense. However, the original alias access still exists. It might prove to be helpful to some. [para] Basically, for every member of every instance, an alias is created. This alias is used to get and set values for that @@ -194,27 +197,27 @@ [para] [example_begin] # Create an instance first % myrecord inst1 ::inst1 -% # To get a member of an instance, just use the +% # To get a member of an instance, just use the % # alias (it behaves like a Tcl command): % inst1.mem1 % -% # To set a member via the alias, just include +% # To set a member via the alias, just include % # a value (optionally the equal sign - syntactic sugar) % inst1.mem1 = 5 5 % inst1.mem1 5 -% # For nested records, just continue with the +% # For nested records, just continue with the % # dot notation (note no equal sign) % inst1.mem3.nest1 10 10 % inst1.mem3.nest1 10 -% # just the instance by itself gives all +% # just the instance by itself gives all % # member/values pairs for that instance % inst1 -mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}} % # and to get all members within the nested record % inst1.mem3 @@ -230,11 +233,11 @@ [list_begin definitions] [call [arg recordName] [method [arg instanceName|#auto]] [opt [arg "-member1 value1 -member2 value2 ..."]]] -Using the [arg recordName] object command that was created from the record definition, +Using the [arg recordName] object command that was created from the record definition, instances of the record definition can be created. Once a instance is created, then it inherits the members of the record definition, very similar to how objects work. During instance generation, an object command for the instance is created as well, using [arg instanceName]. This object command is used to access the data members of the instance. During the instantiation, values for @@ -248,16 +251,16 @@ [list_end] [para] [section {INSTANCE COMMAND}] - + The following subcommands and corresponding arguments are available to any record instance command: [list_begin definitions] - + [call [arg instanceName] [method cget] [opt [arg "-member1 -member2 ..."]]] Each instance has the sub command [method cget] associated with it. This is very similar to how Tk widget's cget command works. It queries the values of the member for that particular instance. If @@ -271,15 +274,15 @@ no arguments are given, then a key/value list is returned. [list_end] [section EXAMPLES] - + Two examples are provided to give an good illustration on how to use this package. -[para] +[para] [emph {Example 1}] [para] Probably the most obvious example would be to hold contact information, such as addresses, phone numbers, comments, etc. Since a person can have @@ -289,11 +292,11 @@ [para] [example { ## -## This is an interactive example, to see what is +## This is an interactive example, to see what is ## returned by each command as well. ## % namespace import ::struct::record::* @@ -308,13 +311,13 @@ phone } ::locations % # Define the main record. Notice that it uses the location record twice. % record define contacts { - first - middle - last + first + middle + last {record locations home} {record locations work} } ::contacts % # Create an instance for the contacts record. @@ -343,11 +346,11 @@ % record show members contacts first middle last {record locations home} {record locations work} % }] -[para] +[para] [emph {Example 1}] [para] This next example just illustrates a simple linked list [para] @@ -383,19 +386,8 @@ }] [para] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: record}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords struct record {data structures}] +[vset CATEGORY {struct :: record}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/skiplist.man ================================================================== --- modules/struct/skiplist.man +++ modules/struct/skiplist.man @@ -1,7 +1,8 @@ [comment {-*- tcl -*-}] [manpage_begin struct::skiplist n 1.3] +[keywords skiplist] [copyright {2000 Keith Vetter}] [comment { This software is licensed under a BSD license as described in tcl/tk license.txt file but with the copyright held by Keith Vetter. }] @@ -50,29 +51,25 @@ [list_begin definitions] [call [arg skiplistName] [method delete] [arg node] [opt [arg node]...]] Remove the specified nodes from the skiplist. - [call [arg skiplistName] [method destroy]] Destroy the skiplist, including its storage space and associated command. - [call [arg skiplistName] [method insert] [arg {key value}]] Insert a node with the given [arg key] and [arg value] into the skiplist. If a node with that key already exists, then the that node's value is updated and its node level is returned. Otherwise a new node is created and 0 is returned. - [call [arg skiplistName] [method search] [arg node] [opt "[const -key] [arg key]"]] Search for a given key in a skiplist. If not found then 0 is returned. If found, then a two element list of 1 followed by the node's value is retuned. - [call [arg skiplistName] [method size]] Return a count of the number of nodes in the skiplist. @@ -82,19 +79,8 @@ command [arg cmd] will be evaluated with the key and value of the current node appended. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: skiplist}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords skiplist] +[vset CATEGORY {struct :: skiplist}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/stack.man ================================================================== --- modules/struct/stack.man +++ modules/struct/stack.man @@ -1,6 +1,10 @@ [manpage_begin struct::stack n 1.5.3] +[keywords graph] +[keywords matrix] +[keywords queue] +[keywords tree] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate stack objects}] [category {Data structures}] [require Tcl 8.4] [require struct::stack [opt 1.5.3]] @@ -32,20 +36,17 @@ [call [arg stackName] [cmd option] [opt [arg "arg arg ..."]]] [arg Option] and the [arg arg]s determine the exact behavior of the command. The following commands are possible for stack objects: - [call [arg stackName] [method clear]] Remove all items from the stack. - [call [arg stackName] [method destroy]] Destroy the stack, including its storage space and associated command. - [call [arg stackName] [method get]] Returns the whole contents of the stack as a list, without removing them from the stack. @@ -88,33 +89,20 @@ list. If specified, [arg count] must be greater than or equal to 1. If there are not enoughs items on the stack to fulfull the request, this command will throw an error. - [call [arg stackName] [method push] [arg item] [opt [arg item...]]] Push the [arg item] or items specified onto the stack. If more than one [arg item] is given, they will be pushed in the order they are listed. - [call [arg stackName] [method size]] Return the number of items on the stack. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: stack}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords queue matrix tree graph] +[vset CATEGORY {struct :: stack}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/struct_list.man ================================================================== --- modules/struct/struct_list.man +++ modules/struct/struct_list.man @@ -1,8 +1,40 @@ [comment {-*- tcl -*- doctools manpage}] [comment {$Id: struct_list.man,v 1.24 2010/10/05 21:47:25 andreas_kupries Exp $}] [manpage_begin struct::list n 1.8.2] +[keywords assign] +[keywords common] +[keywords comparison] +[keywords diff] +[keywords differential] +[keywords equal] +[keywords equality] +[keywords filter] +[keywords {first permutation}] +[keywords Fisher-Yates] +[keywords flatten] +[keywords folding] +[keywords {full outer join}] +[keywords {generate permutations}] +[keywords {inner join}] +[keywords join] +[keywords {left outer join}] +[keywords list] +[keywords {longest common subsequence}] +[keywords map] +[keywords {next permutation}] +[keywords {outer join}] +[keywords permutation] +[keywords reduce] +[keywords repeating] +[keywords repetition] +[keywords reshuffle] +[keywords reverse] +[keywords {right outer join}] +[keywords shuffle] +[keywords subsequence] +[keywords swapping] [copyright {2003-2005 by Kevin B. Kenny. All rights reserved}] [copyright {2003-2012 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Procedures for manipulating lists}] [category {Data structures}] @@ -64,11 +96,10 @@ [arg sequence1], and the second sublist is of indices into [arg sequence2]. Each corresponding pair of indices corresponds to equal elements in the sequences. The sequence approximates the longest common subsequence. - [call [cmd ::struct::list] [method lcsInvert] [arg lcsData] [arg len1] [arg len2]] This command takes a description of a longest common subsequence @@ -161,17 +192,15 @@ Also an index equal to the length of the first sequence in an [term added] chunk refers to just behind the end of the sequence. [list_end] - [call [cmd ::struct::list] [method lcsInvert2] [arg lcs1] [arg lcs2] [arg len1] [arg len2]] Similar to [method lcsInvert]. Instead of directly taking the result of a call to [method longestCommonSubsequence] this subcommand expects the indices for the two sequences in two separate lists. - [call [cmd ::struct::list] [method lcsInvertMerge] [arg lcsData] [arg len1] [arg len2]] Similar to [method lcsInvert]. It returns essentially the same structure as that command, except that it may contain chunks of type @@ -198,34 +227,28 @@ {deleted {6 7} {4 5}} {unchanged {8 10} {5 7}} {added {10 11} {8 8}}} }] - [call [cmd ::struct::list] [method lcsInvertMerge2] [arg lcs1] [arg lcs2] [arg len1] [arg len2]] Similar to [method lcsInvertMerge]. Instead of directly taking the result of a call to [method longestCommonSubsequence] this subcommand expects the indices for the two sequences in two separate lists. - - [call [cmd ::struct::list] [method reverse] [arg sequence]] The subcommand takes a single [arg sequence] as argument and returns a new sequence containing the elements of the input sequence in reverse order. - [call [cmd ::struct::list] [method shuffle] [arg list]] -[keywords shuffle reshuffle Fisher-Yates] The subcommand takes a [arg list] and returns a copy of that list with the elements it contains in random order. Every possible ordering of elements is equally likely to be generated. The -Fisher-Yates shuffling algorithm is used internally. - +Fisher-Yates shuffling algorithm is used internally. [call [cmd ::struct::list] [method assign] [arg sequence] [arg varname] [opt [arg varname]]...] The subcommand assigns the first [var n] elements of the input @@ -252,11 +275,10 @@ a tclsh> set bar b }] - [call [cmd ::struct::list] [method flatten] [opt [option -full]] [opt [option --]] [arg sequence]] The subcommand takes a single [arg sequence] and returns a new sequence where one level of nesting was removed from the input sequence. In other words, the sublists in the input sequence are @@ -271,11 +293,10 @@ tclsh> ::struct::list flatten {1 2 3 {4 5} {6 7} {{8 9}} 10} 1 2 3 4 5 6 7 {8 9} 10 tclsh> ::struct::list flatten -full {1 2 3 {4 5} {6 7} {{8 9}} 10} 1 2 3 4 5 6 7 8 9 10 }] - [call [cmd ::struct::list] [method map] [arg sequence] [arg cmdprefix]] The subcommand takes a [arg sequence] to operate on and a command prefix ([arg cmdprefix]) specifying an operation, applies the command @@ -303,11 +324,10 @@ tclsh> proc projection {n list} {::lindex $list $n} tclsh> ::struct::list map {{a b c} {1 2 3} {d f g}} {projection 1} b 2 f }] - [call [cmd ::struct::list] [method mapfor] [arg var] [arg sequence] [arg script]] The subcommand takes a [arg sequence] to operate on and a tcl [arg script], applies the script to each element of the sequence and returns a sequence consisting of the results of that application. @@ -334,11 +354,10 @@ tclsh> ::struct::list mapfor x {{a b c} {1 2 3} {d f g}} { lindex $x 1 } b 2 f }] - [call [cmd ::struct::list] [method filter] [arg sequence] [arg cmdprefix]] The subcommand takes a [arg sequence] to operate on and a command prefix ([arg cmdprefix]) specifying an operation, applies the command @@ -370,11 +389,10 @@ [emph Note:] The [method filter] is a specialized application of [method fold] where the result is extended with the current item or not, depending o nthe result of the test. - [call [cmd ::struct::list] [method filterfor] [arg var] [arg sequence] [arg expr]] The subcommand takes a [arg sequence] to operate on and a tcl expression ([arg expr]) specifying a condition, applies the conditionto each element of the sequence and returns a sequence consisting of all elements of the @@ -397,11 +415,10 @@ tclsh> ::struct::list filterfor x {1 2 3 4 5} {($x % 2) == 0} 2 4 }] - [call [cmd ::struct::list] [method split] [arg sequence] [arg cmdprefix] [opt "[arg passVar] [arg failVar]"]] This is a variant of method [method filter], see above. Instead of returning just the elements passing the test we get lists of both passing and failing elements. @@ -416,11 +433,10 @@ passing the test, and the number of elements failing, in this order. [para] The interface to the test is the same as used by [method filter]. - [call [cmd ::struct::list] [method fold] [arg sequence] [arg initialvalue] [arg cmdprefix]] The subcommand takes a [arg sequence] to operate on, an arbitrary string [arg {initial value}] and a command prefix ([arg cmdprefix]) @@ -470,11 +486,10 @@ tclsh> proc + {a b} {expr {$a + $b}} tclsh> ::struct::list fold {1 2 3 4 5} 0 + 15 }] - [call [cmd ::struct::list] [method shift] [arg listvar]] The subcommand takes the list contained in the variable named by [arg listvar] and shifts it down one element. @@ -482,21 +497,19 @@ After the call [arg listvar] will contain a list containing the second to last elements of the input list. The first element of the ist is returned as the result of the command. Shifting the empty list does nothing. - [call [cmd ::struct::list] [method iota] [arg n]] The subcommand returns a list containing the integer numbers in the range [const {[0,n)}]. The element at index [var i] of the list contain the number [const i]. [para] For "[arg n] == [const 0]" an empty list will be returned. - [call [cmd ::struct::list] [method equal] [arg a] [arg b]] The subcommand compares the two lists [arg a] and [arg b] for equality. In other words, they have to be of the same length and have @@ -506,11 +519,10 @@ [para] A boolean value will be returned as the result of the command. This value will be [const true] if the two lists are equal, and [const false] else. - [call [cmd ::struct::list] [method repeat] [arg size] [arg element1] [opt "[arg element2] [arg element3]..."]] The subcommand creates a list of length @@ -575,11 +587,10 @@ {0 0 0} {0 0 0} {0 0 0} {0 0 0} tclsh> ::struct::list repeatn 0 {3 4 5} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} }] - [call [cmd ::struct::list] [method dbJoin] [opt [option -inner]|[option -left]|[option -right]|[option -full]] [opt "[option -keys] [arg varname]"] \{[arg keycol] [arg table]\}...] The method performs a table join according to relational algebra. The execution of any of the possible outer join operation is triggered by the presence of either option [option -left], [option -right], or @@ -626,12 +637,10 @@ The table resulting from the join operation is returned as the result of the command. We use the same representation as described above for the input [arg table]s. - - [call [cmd ::struct::list] [method dbJoinKeyed] [opt [option -inner]|[option -left]|[option -right]|[option -full]] [opt "[option -keys] [arg varname]"] [arg table]...] The operations performed by this method are the same as described above for [method dbJoin]. The only difference is in the specification of the keys to use. Instead of using column indices separate from the @@ -645,16 +654,14 @@ The subcommand exchanges the elements at the indices [arg i] and [arg j] in the list stored in the variable named by [arg listvar]. The list is modified in place, and also returned as the result of the subcommand. - [call [cmd ::struct::list] [method firstperm] [arg list]] This subcommand returns the lexicographically first permutation of the input [arg list]. - [call [cmd ::struct::list] [method nextperm] [arg perm]] This subcommand accepts a permutation of a set of elements (provided by [arg perm]) and returns the next permutatation in lexicographic @@ -662,16 +669,14 @@ [para] The algorithm used here is by Donal E. Knuth, see section [sectref REFERENCES] for details. - [call [cmd ::struct::list] [method permutations] [arg list]] This subcommand returns a list containing all permutations of the input [arg list] in lexicographic order. - [call [cmd ::struct::list] [method foreachperm] [arg var] [arg list] [arg body]] This subcommand executes the script [arg body] once for each permutation of the specified [arg list]. The permutations are visited @@ -697,11 +702,11 @@ [para] One approach to dealing with the performance problem that is sometimes effective in practice is arbitrarily to exclude elements that appear -more than a certain number of times. +more than a certain number of times. This number is provided as the [arg maxOccurs] parameter. If frequent lines are excluded in this manner, they will not appear in the common subsequence that is computed; the result will be the longest common subsequence of infrequent elements. @@ -711,11 +716,10 @@ It functions as a wrapper around [method longestCommonSubsequence]; it computes the longest common subsequence of infrequent elements, and then subdivides the subsequences that lie between the matches to approximate the true longest common subsequence. - [section {TABLE JOIN}] This is an operation from relational algebra for relational databases. @@ -752,11 +756,10 @@ [enum] For the right outer join the additional rows are all rows from the right table for which there is no key in the left table. They are joined to an empty row of the left table to fit them into the result. - [enum] The full outer join combines both left and right outer join. In other words, the additional rows are as defined for left outer join, and @@ -802,20 +805,17 @@ {1 snarf} full outer join {1 snatz} = {1 snarf 1 snatz} {2 blue} {3 driver} {2 blue {} {}} {{} {} 3 driver} }] - - - [section REFERENCES] [list_begin enumerated] [enum] -J. W. Hunt and M. D. McIlroy, "An algorithm for differential -file comparison," Comp. Sci. Tech. Rep. #41, Bell Telephone +J. W. Hunt and M. D. McIlroy, "An algorithm for differential +file comparison," Comp. Sci. Tech. Rep. #41, Bell Telephone Laboratories (1976). Available on the Web at the second author's personal site: [uri http://www.cs.dartmouth.edu/~doug/] [enum] Donald E. Knuth, "Fascicle 2b of 'The Art of Computer Programming' @@ -822,28 +822,8 @@ volume 4". Available on the Web at the author's personal site: [uri http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: list}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords list diff differential comparison common subsequence] -[keywords {longest common subsequence}] -[keywords reverse] -[keywords assign] -[keywords flatten] -[keywords map filter] -[keywords folding reduce] -[keywords equality equal repetition repeating] -[keywords {inner join} {left outer join} {right outer join} {full outer join} {outer join} join] -[keywords swapping permutation {first permutation} {next permutation} {generate permutations}] +[vset CATEGORY {struct :: list}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/struct_set.man ================================================================== --- modules/struct/struct_set.man +++ modules/struct/struct_set.man @@ -1,8 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [comment {$Id: struct_set.man,v 1.12 2009/01/29 06:16:20 andreas_kupries Exp $}] [manpage_begin struct::set n 2.2.3] +[keywords cardinality] +[keywords difference] +[keywords emptiness] +[keywords exclusion] +[keywords inclusion] +[keywords intersection] +[keywords membership] +[keywords set] +[keywords {symmetric difference}] +[keywords union] [copyright {2004-2008 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Procedures for manipulating sets}] [category {Data structures}] [require Tcl 8.0] @@ -32,50 +42,43 @@ [call [cmd ::struct::set] [method empty] [arg set]] Returns a boolean value indicating if the [arg set] is empty ([const true]), or not ([const false]). - [call [cmd ::struct::set] [method size] [arg set]] Returns an integer number greater than or equal to zero. This is the number of elements in the [arg set]. In other words, its cardinality. - [call [cmd ::struct::set] [method contains] [arg set] [arg item]] Returns a boolean value indicating if the [arg set] contains the element [arg item] ([const true]), or not ([const false]). - [call [cmd ::struct::set] [method union] [opt [arg set1]...]] Computes the set containing the union of [arg set1], [arg set2], etc., i.e. "[arg set1] + [arg set2] + ...", and returns this set as the result of the command. - [call [cmd ::struct::set] [method intersect] [opt [arg set1]...]] Computes the set containing the intersection of [arg set1], [arg set2], etc., i.e. "[arg set1] * [arg set2] * ...", and returns this set as the result of the command. - [call [cmd ::struct::set] [method difference] [arg set1] [arg set2]] Computes the set containing the difference of [arg set1] and [arg set2], i.e. ("[arg set1] - [arg set2]") and returns this set as the result of the command. - [call [cmd ::struct::set] [method symdiff] [arg set1] [arg set2]] Computes the set containing the symmetric difference of [arg set1] and [arg set2], i.e. ("([arg set1] - [arg set2]) + ([arg set2] - [arg set1])") and returns this set as the result of the command. - [call [cmd ::struct::set] [method intersect3] [arg set1] [arg set2]] This command is a combination of the methods [method intersect] and [method difference]. @@ -83,71 +86,51 @@ It returns a three-element list containing "[arg set1]*[arg set2]", "[arg set1]-[arg set2]", and "[arg set2]-[arg set1]", in this order. In other words, the intersection of the two parameter sets, and their differences. - [call [cmd ::struct::set] [method equal] [arg set1] [arg set2]] Returns a boolean value indicating if the two sets are equal ([const true]) or not ([const false]). - [call [cmd ::struct::set] [method include] [arg svar] [arg item]] The element [arg item] is added to the set specified by the variable name in [arg svar]. The return value of the command is empty. This is the equivalent of [cmd lappend] for sets. If the variable named by [arg svar] does not exist it will be created. - [call [cmd ::struct::set] [method exclude] [arg svar] [arg item]] The element [arg item] is removed from the set specified by the variable name in [arg svar]. The return value of the command is empty. This is a near-equivalent of [cmd lreplace] for sets. - [call [cmd ::struct::set] [method add] [arg svar] [arg set]] All the element of [arg set] are added to the set specified by the variable name in [arg svar]. The return value of the command is empty. This is like the method [method include], but for the addition of a whole set. If the variable named by [arg svar] does not exist it will be created. - [call [cmd ::struct::set] [method subtract] [arg svar] [arg set]] All the element of [arg set] are removed from the set specified by the variable name in [arg svar]. The return value of the command is empty. This is like the method [method exclude], but for the removal of a whole set. - [call [cmd ::struct::set] [method subsetof] [arg A] [arg B]] Returns a boolean value indicating if the set [arg A] is a true subset of or equal to the set [arg B] ([const true]), or not ([const false]). [list_end] - [section REFERENCES] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: set}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords set union intersection difference {symmetric difference}] -[keywords emptiness membership cardinality] -[keywords inclusion exclusion] +[vset CATEGORY {struct :: set}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/struct_tree.man ================================================================== --- modules/struct/struct_tree.man +++ modules/struct/struct_tree.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*-}] [manpage_begin struct::tree n 2.1.1] +[keywords breadth-first] +[keywords depth-first] +[keywords in-order] +[keywords node] +[keywords post-order] +[keywords pre-order] +[keywords serialization] +[keywords tree] [copyright {2002-2004,2012 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate tree objects}] [category {Data structures}] [require Tcl 8.2] @@ -96,11 +104,11 @@ [example { ::struct::tree mytree mytree = b }] [para] -and +and [para] [example { ::struct::tree mytree deserialize $b }] [para] @@ -108,11 +116,10 @@ [para] [example { ::struct::tree mytree mytree deserialize $b }] - [call [cmd ::struct::tree::prune]] This command is provided outside of the tree methods, as it is not a tree method per se. It however interacts tightly with the method @@ -167,11 +174,10 @@ [para] [example_begin] [arg treeName] [method deserialize] [lb][arg sourcetree] [method serialize][rb] [example_end] - [call [arg treeName] [method -->] [arg desttree]] This is the reverse assignment operator for tree objects. It copies the tree contained in the tree object [arg treeName] over the tree data in the object [arg desttree]. The old contents of [arg desttree] are deleted by this @@ -183,25 +189,22 @@ [para] [example_begin] [arg desttree] [method deserialize] [lb][arg treeName] [method serialize][rb] [example_end] - [call [arg treeName] [method ancestors] [arg node]] This method extends the method [method parent] and returns a list containing all ancestor nodes to the specified [arg node]. The immediate ancestor, in other words, parent node, is the first element in that list, its parent the second element, and so on until the root node is reached, making it the last element of the returned list. - [call [arg treeName] [method append] [arg node] [arg key] [arg value]] Appends a [arg value] to one of the keyed values associated with an node. Returns the new value given to the attribute [arg key]. - [call [arg treeName] [method attr] [arg key]] [call [arg treeName] [method attr] [arg key] [option -nodes] [arg list]] [call [arg treeName] [method attr] [arg key] [option -glob] [arg globpattern]] [call [arg treeName] [method attr] [arg key] [option -regexp] [arg repattern]] @@ -287,28 +290,24 @@ tclsh> puts ([lsort [mytree children root filter vgt40]]) () }] - [call [arg treeName] [method cut] [arg node]] Removes the node specified by [arg node] from the tree, but not its children. The children of [arg node] are made children of the parent of the [arg node], at the index at which [arg node] was located. - [call [arg treeName] [method delete] [arg node] [opt "[arg node] ..."]] Removes the specified nodes from the tree. All of the nodes' children will be removed as well to prevent orphaned nodes. - [call [arg treeName] [method depth] [arg node]] Return the number of steps from node [arg node] to the root node. - [call [arg treeName] [method descendants] [arg node] [opt "[const filter] [arg cmdprefix]"]] This method extends the method [method children] and returns a list containing all nodes descending from [arg node], and passing the @@ -319,67 +318,58 @@ This is actually the same as "[arg treeName] [method children] [option -all]". [method descendants] should be prefered, and "children -all" will be deprecated sometime in the future. - [call [arg treeName] [method deserialize] [arg serialization]] This is the complement to [method serialize]. It replaces tree data in [arg treeName] with the tree described by the [arg serialization] value. The old contents of [arg treeName] are deleted by this operation. - [call [arg treeName] [method destroy]] Destroy the tree, including its storage space and associated command. - [call [arg treeName] [method exists] [arg node]] Returns true if the specified node exists in the tree. - [call [arg treeName] [method get] [arg node] [arg key]] Returns the value associated with the key [arg key] for the node [arg node]. - [call [arg treeName] [method getall] [arg node] [opt [arg pattern]]] Returns a dictionary (suitable for use with [lb][cmd {array set}][rb]) containing the attribute data for the [arg node]. If the glob [arg pattern] is specified only the attributes whose names match the pattern will be part of the dictionary. - [call [arg treeName] [method keys] [arg node] [opt [arg pattern]]] Returns a list of keys for the [arg node]. If the [arg pattern] is specified only the attributes whose names match the pattern will be part of the returned list. The pattern is a [cmd glob] pattern. - [call [arg treeName] [method keyexists] [arg node] [arg key]] Return true if the specified [arg key] exists for the [arg node]. - [call [arg treeName] [method index] [arg node]] Returns the index of [arg node] in its parent's list of children. For example, if a node has [term nodeFoo], [term nodeBar], and [term nodeBaz] as children, in that order, the index of [term nodeBar] is 1. - [call [arg treeName] [method insert] [arg parent] [arg index] [opt "[arg child] [opt "[arg child] ..."]"]] Insert one or more nodes into the tree as children of the node @@ -405,28 +395,24 @@ [para] The return result from this command is a list of nodes added. - [call [arg treeName] [method isleaf] [arg node]] Returns true if [arg node] is a leaf of the tree (if [arg node] has no children), false otherwise. - [call [arg treeName] [method lappend] [arg node] [arg key] [arg value]] Appends a [arg value] (as a list) to one of the keyed values associated with an [arg node]. Returns the new value given to the attribute [arg key]. - [call [arg treeName] [method leaves]] Return a list containing all leaf nodes known to the tree. - [call [arg treeName] [method move] [arg parent] [arg index] [arg node] [opt "[arg node] ..."]] Make the specified nodes children of [arg parent], inserting them into the parent's child list at the index given by [arg index]. Note that @@ -434,51 +420,43 @@ under the new parent, and that it determines the position to place them into after the removal, before the re-insertion. This behaviour is important when it comes to moving one or more nodes to a different index without changing their parent node. - [call [arg treeName] [method next] [arg node] ] Return the right sibling of [arg node], or the empty string if [arg node] was the last child of its parent. - [call [arg treeName] [method numchildren] [arg node]] Return the number of immediate children of [arg node]. - [call [arg treeName] [method nodes]] Return a list containing all nodes known to the tree. - [call [arg treeName] [method parent] [arg node]] Return the parent of [arg node]. - [call [arg treeName] [method previous] [arg node] ] Return the left sibling of [arg node], or the empty string if [arg node] was the first child of its parent. - [call [arg treeName] [method rename] [arg node] [arg newname]] Renames the node [arg node] to [arg newname]. An error is thrown if either the node does not exist, or a node with name [arg newname] does exist. The result of the command is the new name of the node. - [call [arg treeName] [method rootname]] Returns the name of the root node of the tree. - [call [arg treeName] [method serialize] [opt [arg node]]] This method serializes the sub-tree starting at [arg node]. In other words it returns a tcl [emph value] completely describing the tree @@ -549,27 +527,22 @@ {root {} {} a 0 {} d 3 {} e 3 {} b 0 {} c 0 {}} The above assumes that none of the nodes have attributes. }] - - [call [arg treeName] [method set] [arg node] [arg key] [opt [arg value]]] Set or get one of the keyed values associated with a node. A node may have any number of keyed values associated with it. If [arg value] is not specified, this command returns the current value assigned to the key; if [arg value] is specified, this command assigns that value to the key, and returns it. - [call [arg treeName] [method size] [opt [arg node]]] - Return a count of the number of descendants of the node [arg node]; if no node is specified, [const root] is assumed. - [call [arg treeName] [method splice] [arg parent] [arg from] [opt [arg to]] [opt [arg child]]] Insert a node named [arg child] into the tree as a child of the node [arg parent]. If [arg parent] is [const root], it refers to the root @@ -585,21 +558,18 @@ [para] The arguments [arg from] and [arg to] are regular list indices, i.e. the form "end-[var n]" is accepted as well. - [call [arg treeName] [method swap] [arg node1] [arg node2]] Swap the position of [arg node1] and [arg node2] in the tree. - [call [arg treeName] [method unset] [arg node] [arg key]] Removes a keyed value from the node [arg node]. The method will do nothing if the [arg key] does not exist. - [call [arg treeName] [method walk] [arg node] [opt "[option -order] [arg order]"] [opt "[option -type] [arg type]"] [arg loopvar] [arg script]] Perform a breadth-first or depth-first walk of the tree starting at the node [arg node]. The type of walk, breadth-first or depth-first, @@ -691,18 +661,16 @@ in the walk script to force the command to ignore the children of the node we are currently at. It will throw an error if the order of traversal is either [const post] or [const in] as these modes visit the children before their parent, making pruning non-sensical. - [call [arg treeName] [method walkproc] [arg node] [opt "[option -order] [arg order]"] [opt "[option -type] [arg type]"] [arg cmdprefix]] This method is like method [method walk] in all essentials, except the interface to the user code. This method invokes a command prefix with three additional arguments (tree, node, and action), instead of evaluating a script and passing the node via a loop variable. - [list_end] [subsection {Changes for 2.0}] @@ -757,11 +725,10 @@ [para] Beyond the copying of whole tree objects these new API's also enable the transfer of tree objects over arbitrary channels and for easy persistence. - [enum] The walker API has been streamlined and made more similar to the command [cmd foreach]. In detail: @@ -818,19 +785,8 @@ mytree insert 0 end ; # Create another child of 0, with a # generated name. The name is returned # as the result of the command. }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: tree}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords tree serialization node pre-order post-order in-order depth-first breadth-first] +[vset CATEGORY {struct :: tree}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/struct/struct_tree1.man ================================================================== --- modules/struct/struct_tree1.man +++ modules/struct/struct_tree1.man @@ -1,7 +1,8 @@ [comment {-*- tcl -*-}] [manpage_begin {struct::tree_v1} n 1.2.2] +[keywords tree] [copyright {2002 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Create and manipulate tree objects}] [category {Data structures}] [require Tcl 8.2] @@ -53,53 +54,45 @@ [list_end] [para] - The following commands are possible for tree objects: [list_begin definitions] [call [arg treeName] [method append] [arg node] [opt "-key [arg key]"] [arg value]] Appends a [arg value] to one of the keyed values associated with an node. If no [arg key] is specified, the key [const data] is assumed. - [call [arg treeName] [method children] [arg node]] Return a list of the children of [arg node]. - [call [arg treeName] [method cut] [arg node]] Removes the node specified by [arg node] from the tree, but not its children. The children of [arg node] are made children of the parent of the [arg node], at the index at which [arg node] was located. - [call [arg treeName] [method delete] [arg node] [opt "[arg node] ..."]] Removes the specified nodes from the tree. All of the nodes' children will be removed as well to prevent orphaned nodes. - [call [arg treeName] [method depth] [arg node]] Return the number of steps from node [arg node] to the root node. - [call [arg treeName] [method destroy]] Destroy the tree, including its storage space and associated command. - [call [arg treeName] [method exists] [arg node]] Returns true if the specified node exists in the tree. - [call [arg treeName] [method get] [arg node] [opt "[option -key] [arg key]"]] Return the value associated with the key [arg key] for the node @@ -108,31 +101,27 @@ [call [arg treeName] [method getall] [arg node]] Returns a serialized list of key/value pairs (suitable for use with [lb][cmd {array set}][rb]) for the [arg node]. - [call [arg treeName] [method keys] [arg node]] Returns a list of keys for the [arg node]. - [call [arg treeName] [method keyexists] [arg node] [opt "-key [arg key]"]] Return true if the specified [arg key] exists for the [arg node]. If no [arg key] is specified, the key [const data] is assumed. - [call [arg treeName] [method index] [arg node]] Returns the index of [arg node] in its parent's list of children. For example, if a node has [term nodeFoo], [term nodeBar], and [term nodeBaz] as children, in that order, the index of [term nodeBar] is 1. - [call [arg treeName] [method insert] [arg parent] [arg index] [opt "[arg child] [opt "[arg child] ..."]"]] Insert one or more nodes into the tree as children of the node @@ -157,23 +146,20 @@ [para] The return result from this command is a list of nodes added. - [call [arg treeName] [method isleaf] [arg node]] Returns true if [arg node] is a leaf of the tree (if [arg node] has no children), false otherwise. - [call [arg treeName] [method lappend] [arg node] [opt "-key [arg key]"] [arg value]] Appends a [arg value] (as a list) to one of the keyed values associated with an [arg node]. If no [arg key] is specified, the key [const data] is assumed. - [call [arg treeName] [method move] [arg parent] [arg index] [arg node] [opt "[arg node] ..."]] Make the specified nodes children of [arg parent], inserting them into the parent's child list at the index given by [arg index]. Note that @@ -187,27 +173,23 @@ Return the right sibling of [arg node], or the empty string if [arg node] was the last child of its parent. - [call [arg treeName] [method numchildren] [arg node]] Return the number of immediate children of [arg node]. - [call [arg treeName] [method parent] [arg node]] Return the parent of [arg node]. - [call [arg treeName] [method previous] [arg node] ] Return the left sibling of [arg node], or the empty string if [arg node] was the first child of its parent. - [call [arg treeName] [method set] [arg node] [opt "[option -key] [arg key]"] [opt [arg value]]] Set or get one of the keyed values associated with a node. If no key is specified, the key [const data] is assumed. Each node that is @@ -215,17 +197,14 @@ automatically. A node may have any number of keyed values associated with it. If [arg value] is not specified, this command returns the current value assigned to the key; if [arg value] is specified, this command assigns that value to the key. - [call [arg treeName] [method size] [opt [arg node]]] - Return a count of the number of descendants of the node [arg node]; if no node is specified, [const root] is assumed. - [call [arg treeName] [method splice] [arg parent] [arg from] [opt [arg to]] [opt [arg child]]] Insert a node named [arg child] into the tree as a child of the node [arg parent]. If [arg parent] is [const root], it refers to the root @@ -236,21 +215,18 @@ defaults to [const end]. If no name is given for [arg child], a name will be generated for the new node. The generated name is of the form [emph node][var x], where [var x] is a number. The return result from this command is the name of the new node. - [call [arg treeName] [method swap] [arg node1] [arg node2]] Swap the position of [arg node1] and [arg node2] in the tree. - [call [arg treeName] [method unset] [arg node] [opt "[option -key] [arg key]"]] Removes a keyed value from the node [arg node]. If no key is specified, the key [const data] is assumed. - [call [arg treeName] [method walk] [arg node] [opt "[option -order] [arg order]"] [opt "[option -type] [arg type]"] [option -command] [arg cmd]] Perform a breadth-first or depth-first walk of the tree starting at the node [arg node]. The type of walk, breadth-first or depth-first, @@ -309,19 +285,8 @@ second. [list_end] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {struct :: tree}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords tree] +[vset CATEGORY {struct :: tree}] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/tar/tar.man ================================================================== --- modules/tar/tar.man +++ modules/tar/tar.man @@ -1,14 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tar n 0.7] +[keywords archive] +[keywords {tape archive}] +[keywords tar] [moddesc {Tar file handling}] [titledesc {Tar file creation, extraction & manipulation}] [category {File formats}] [require Tcl 8.4] [require tar [opt 0.7]] [description] - [para] [list_begin definitions] @@ -36,11 +38,10 @@ [para] If the option [option -chan] is present [arg tarball] is interpreted as an open channel. It is assumed that the channel was opened for reading, and configured for binary input. The command will [emph not] close the channel. - [call [cmd ::tar::untar] [arg tarball] [arg args]] Extracts [arg tarball]. [arg -file] and [arg -glob] limit the extraction to files which exactly match or pattern match the given argument. No error is @@ -92,11 +93,10 @@ [para] If the option [option -chan] is present [arg tarball] is interpreted as an open channel. It is assumed that the channel was opened for reading, and configured for binary input. The command will [emph not] close the channel. - [call [cmd ::tar::create] [arg tarball] [arg files] [arg args]] Creates a new tar file containing the [arg files]. [arg files] must be specified as a single argument which is a proper list of filenames. @@ -129,18 +129,18 @@ [opt_def -dereference] Normally [cmd add] will store links as an actual link pointing at a file that may or may not exist in the archive. Specifying this option will cause the actual file point to by the link to be stored instead. [opt_def -prefix string] -Normally [cmd add] will store files under exactly the name specified as -argument. Specifying a [opt -prefix] causes the [arg string] to be +Normally [cmd add] will store files under exactly the name specified as +argument. Specifying a [opt -prefix] causes the [arg string] to be prepended to every name. [opt_def -quick] -The only sure way to find the position in the [arg tarball] where new -files can be added is to read it from start, but if [arg tarball] was -written with a "blocksize" of 1 (as this package does) then one can -alternatively find this position by seeking from the end. The +The only sure way to find the position in the [arg tarball] where new +files can be added is to read it from start, but if [arg tarball] was +written with a "blocksize" of 1 (as this package does) then one can +alternatively find this position by seeking from the end. The [opt -quick] option tells [cmd add] to do the latter. [list_end] [para] [call [cmd ::tar::remove] [arg tarball] [arg files]] @@ -155,20 +155,8 @@ file3 }] [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph tar] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords tar {tape archive} archive] +[vset CATEGORY tar] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/tepam/tepam_argument_dialogbox.man ================================================================== --- modules/tepam/tepam_argument_dialogbox.man +++ modules/tepam/tepam_argument_dialogbox.man @@ -1,16 +1,19 @@ [manpage_begin tepam::argument_dialogbox n 0.4.1] +[see_also tepam(n)] +[see_also tepam::procedure(n)] +[keywords {data entry form}] +[keywords {parameter entry form}] [copyright {2009/2010, Andreas Drollinger}] [moddesc {Tcl's Enhanced Procedure and Argument Manager}] [titledesc {TEPAM argument_dialogbox, reference manual}] [category {Argument entry form, mega widget}] [require Tcl 8.3] [require Tk 8.3] [require tepam [opt 0.4]] [description] - [section "ARGUMENT DIALOGBOX CALL"] TEPAM's [cmd argument_dialogbox] is a flexible and easily usable data entry form generator. Each data entry element of a form is defined via a [emph {data entry item}] that can be provided to [cmd argument_dialogbox] in two formats: @@ -53,11 +56,11 @@ [list_end] The commands [cmd argument_dialogbox] as well as [cmd procedure] are exported from the namespace [namespace tepam]. To use these commands without the [namespace tepam::] namespace prefix, it is sufficient to import them into the main namespace: [example_begin][cmd {namespace import tepam::*}] - + set DialogResult [lb][cmd argument_dialogbox] \ -title "Itinerary selection" ...[example_end] The following subsections explain the different argument item types that are accepted by the [cmd argument_dialogbox], classified into three groups. The first data entry item definition format will be used in the remaining document, knowing that this format can always be transformed into the second format by putting all arguments into a single list that is then provided to [cmd argument_dialogbox]. @@ -244,11 +247,11 @@ In contrast to the combo box, the list box is always displayed by the [arg listbox] entry widget. Only one element is selectable unless the [arg -multiple_selection] attribute is set. The list box height can be selected with the [arg -height] attribute. If the height is not explicitly defined, the list box height is automatically adapted to the argument dialog box' size. The first example uses a variable to define the available choices: [example_begin]set set AvailableSizes for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [lb]expr 1<<$k[rb]} - + tepam::argument_dialogbox \ [cmd -listbox] {-label "Distance" -variable Distance \ -choicevariable AvailableSizes -default 6 -height 5}[example_end] Here is a multi-element selection example. Please note that also the default selection can contain multiple elements: @@ -364,11 +367,11 @@ [def "-type [arg string]"] If the data type is defined with the [arg -type] attribute the argument dialog box will automatically perform a data type check after acknowledging the entered values and before the dialog box is closed. If a type incompatible value is found an error message box appears and the user can correct the value. [para] The argument dialog box accepts all types that have been specified by the TEPAM package and that are also used by [cmd tepam::procedure] (see the [emph {tepam::procedure reference manual}]). [para] -Some entry widgets like the file and directory widgets, as well as the color and font widgets are specifying automatically the default data type if no type has been specified explicitly with the [arg -type] attribute. +Some entry widgets like the file and directory widgets, as well as the color and font widgets are specifying automatically the default data type if no type has been specified explicitly with the [arg -type] attribute. [example_begin]tepam::argument_dialogbox \ [cmd -entry] {-label "Street number" -variable start_street_nbr [cmd {-type integer}]} \[example_end] [def "-range [arg string]"] Values can be constrained with the [arg -range] attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value. @@ -450,11 +453,10 @@ -listbox {-label "Text size" -variable Size \ -choices {8 9 10 12 15 18} -default 12 [cmd {-height 3}]}[example_end] If the no height has been explicitly specified the height of the widget will be dynamically adapted to the argument dialog box' size. [list_end] - [section "APPLICATION SPECIFIC ENTRY WIDGETS"] An application specific entry widget can be made available to the argument dialog box by adding a dedicated procedure to the [namespace tepam] namespace. This procedure has three arguments; the first one is the widget path, the second one a subcommand and the third argument has various purposes: [example_begin][arg proc] tepam::ad_form() {W Command {Par ""}} { @@ -473,11 +475,11 @@ The entry widget procedure has to support 3 mandatory and an optional command that are selected via the argument [arg Command]: [list_begin definitions] [def [arg create]] -The entry widget is called a first time with the command [arg create] to build the data entry widget. +The entry widget is called a first time with the command [arg create] to build the data entry widget. [para] The frames that are made available by [cmd argument_dialogbox] for the entry widgets are by default only extendable in the X direction. To make them also extendable in the Y direction, for example for extendable list boxes, the command [cmd {ad_form(make_expandable) $W}] has to be executed when an entry widget is built. [def [arg set_choice]] The entry widget procedure is only called with the [arg set_choice] command if the [arg -choices] or [arg -choicevariable] has been specified. The command is therefore only relevant for list and combo boxes. [para] @@ -530,9 +532,6 @@ This array variable is only used by an argument dialog box if its context has been specified via the [arg -context] attribute. The argument dialog box' position and size as well as its entered data are stored inside this variable if the data are acknowledged and the form is closed. This allows the form to restore its previous state once it is called another time. [para] To reuse the saved parameters not just in the actual application session but also in another one, it is sufficient to store the [var last_parameter] array variable contents in a configuration file which is loaded the next time an application is launched. [list_end] - -[see_also tepam(n) tepam::procedure(n)] -[keywords {data entry form} {parameter entry form}] [manpage_end] Index: modules/tepam/tepam_introduction.man ================================================================== --- modules/tepam/tepam_introduction.man +++ modules/tepam/tepam_introduction.man @@ -1,6 +1,15 @@ [manpage_begin tepam n 0.4.1] +[see_also tepam::argument_dialogbox(n)] +[see_also tepam::procedure(n)] +[keywords {argument integrity}] +[keywords {argument validation}] +[keywords arguments] +[keywords {entry mask}] +[keywords {parameter entry form}] +[keywords procedure] +[keywords subcommand] [copyright {2009/2010, Andreas Drollinger}] [moddesc {Tcl's Enhanced Procedure and Argument Manager}] [titledesc {An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager}] [category {Procedures, arguments, parameters, options}] @@ -88,11 +97,11 @@ puts " $var=[set $var]" } } }]}[example_end] -A call of procedure that has been declared in this way will first invoke the TEPAM argument manager, before the procedure body is executed. The argument manager parses the provided arguments, validates them, completes them eventually with some default values, and makes them finally available to the procedure body as local variables. In case an argument is missing or has a wrong type, the argument manager generates an error message that explains the reason for the error. +A call of procedure that has been declared in this way will first invoke the TEPAM argument manager, before the procedure body is executed. The argument manager parses the provided arguments, validates them, completes them eventually with some default values, and makes them finally available to the procedure body as local variables. In case an argument is missing or has a wrong type, the argument manager generates an error message that explains the reason for the error. [para] As the example above shows, the TEPAM command [cmd procedure] accepts subcommand definitions as procedure name and allows defining much more information than just the argument list inside the procedure header. The procedure body on the other hand is identical between a command declared with [cmd proc] and a command declared with [cmd procedure]. [para] The procedure header allows defining in addition to the arguments some procedure attributes, like a description, information concerning the return value, etc. This information is basically used for the automatic generation of comprehensive help and usage texts. [para] @@ -142,38 +151,38 @@ mtype=Warning font=Arial 10 italic fg=black no_border=0 text={The document hasn't yet been saved!}}] - + [cmd {display message}] -fg red -bg black "Please save first the document" [emph {-> display message: mtype=Warning font=Arial 10 italic fg=red bg=black no_border=0 text={Please save first the document}}] - + [cmd {display message}] -mtype Error -no_border "Why is here no border?" [emph {-> display message: mtype=Error font=Arial 10 italic fg=black no_border=1 text={Why is here no border?}}] - + [cmd {display message}] -font {Courier 12} -level 10 \ "Is there enough space?" "Reduce otherwise the font size!" [emph {-> display message: mtype=Warning font=Courier 12 level=10 fg=black no_border=0 text={Is there enough space?} {Reduce otherwise the font size!}}][example_end] - + The next lines show how wrong arguments are recognized. The [arg text] argument that is mandatory is missing in the first procedure call: [example_begin][cmd {display message}] -font {Courier 12} [emph { -> display message: Required argument is missing: text}][example_end] @@ -183,17 +192,17 @@ [emph { -> display message: Argument '-category' not known}][example_end] Argument types are automatically checked and an error message is generated in case the argument value has not the expected type: [example_begin][cmd {display message}] -fg MyColor "Hello" -[emph { -> display message: Argument 'fg' requires type 'color'. \ +[emph { -> display message: Argument 'fg' requires type 'color'. \ Provided value: 'MyColor'}][example_end] Selection choices have to be respected ... [example_begin][cmd {display message}] -mtype Fatal Hello -[emph { -> display message: Argument (mtype) has to be one of the \ +[emph { -> display message: Argument (mtype) has to be one of the \ following elements: Info, Warning, Error}][example_end] ... as well as valid value ranges: [example_begin][cmd {display message}] -level 12 Hello @@ -203,11 +212,11 @@ The most intuitive way to call the procedure is using an form that allows specifying all arguments interactively. This form will automatically be generated if the declared procedure is called with the [arg -interactive] flag. [example_begin][cmd {display message}] -interactive[example_end] -The generated form contains for each argument a data entry widget that is adapted to the argument type. Check buttons are used to specify flags, radio boxes for tiny choice lists, disjoint list boxes for larger choice lists and files, directories, fonts and colors can be selected with dedicated browsers. +The generated form contains for each argument a data entry widget that is adapted to the argument type. Check buttons are used to specify flags, radio boxes for tiny choice lists, disjoint list boxes for larger choice lists and files, directories, fonts and colors can be selected with dedicated browsers. [para] After acknowledging the specified argument data via an OK button, the entered data are first validated, before the provided arguments are transformed into local variables and the procedure body is executed. In case the entered data are invalid, a message appears and the user can correct them until they are valid. [para] The procedure calls can optionally be logged in a variable. This is for example useful to get the command call lines of interactively called procedures. @@ -230,33 +239,33 @@ [para] The attribute list contains pairs of attribute names and attribute data. The primary attribute is [arg -variable] used to specify the variable in the calling context into which the entered data has to be stored. Another often used attribute is [arg -label] that allows adding a label to the data entry widget. Other attributes are available that allow specifying default values, the expected data types, valid data ranges, etc. [para] The next example of a more complex argument dialog box provides a good overview about the different available entry widget types and parameter attributes. The example contains also some formatting instructions like [arg -frame] and [arg -sep] which allows organizing the different entry widgets in frames and sections: [example_begin]set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"} - + set Result [lb][cmd tepam::argument_dialogbox] \ [cmd -title] "System configuration" \ [cmd -context] test_1 \ [cmd -frame] {-label "Entries"} \ [cmd -entry] {-label Entry1 -variable Entry1} \ [cmd -entry] {-label Entry2 -variable Entry2 -default "my default"} \ [cmd -frame] {-label "Listbox & combobox"} \ [cmd -listbox] {-label "Listbox, single selection" -variable Listbox1 \ -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \ - [cmd -listbox] {-label "Listbox, multiple selection" -variable Listbox2 - -choicevariable ChoiceList -default {"Choice 2" "Choice 3"} + [cmd -listbox] {-label "Listbox, multiple selection" -variable Listbox2 + -choicevariable ChoiceList -default {"Choice 2" "Choice 3"} -multiple_selection 1 -height 3} \ - [cmd -disjointlistbox] {-label "Disjoined listbox" -variable DisJntListbox + [cmd -disjointlistbox] {-label "Disjoined listbox" -variable DisJntListbox -choicevariable ChoiceList \ -default {"Choice 3" "Choice 5"} -height 3} \ [cmd -combobox] {-label "Combobox" -variable Combobox \ -choices {1 2 3 4 5 6 7 8} -default 3} \ [cmd -frame] {-label "Checkbox, radiobox and checkbutton"} \ - [cmd -checkbox] {-label Checkbox -variable Checkbox + [cmd -checkbox] {-label Checkbox -variable Checkbox -choices {bold italic underline} -choicelabels {Bold Italic Underline} \ -default italic} \ - [cmd -radiobox] {-label Radiobox -variable Radiobox + [cmd -radiobox] {-label Radiobox -variable Radiobox -choices {bold italic underline} -choicelabels {Bold Italic Underline} \ -default underline} \ [cmd -checkbutton] {-label CheckButton -variable Checkbutton -default 1} \ [cmd -frame] {-label "Files & directories"} \ [cmd -existingfile] {-label "Input file" -variable InputFile} \ @@ -275,11 +284,11 @@ puts "Canceled" } else { # $Result=="ok" puts "Arguments: " foreach Var { Entry1 Entry2 - Listbox1 Listbox2 DisJntListbox + Listbox1 Listbox2 DisJntListbox Combobox Checkbox Radiobox Checkbutton InputFile OutputFile InputDirectory OutputDirectory Color Font } { puts " $Var: '[lb]set $Var[rb]'" @@ -299,10 +308,6 @@ OutputFile: 'c:\tepam\out.txt' InputDirectory: 'c:\tepam\input' OutputDirectory: 'c:\tepam\output' Color: 'red' Font: 'Courier 12 italic'}][example_end] - -[see_also tepam::argument_dialogbox(n) tepam::procedure(n)] - -[keywords procedure arguments {argument validation} {argument integrity} subcommand {entry mask} {parameter entry form}] [manpage_end] Index: modules/tepam/tepam_procedure.man ================================================================== --- modules/tepam/tepam_procedure.man +++ modules/tepam/tepam_procedure.man @@ -1,6 +1,13 @@ [manpage_begin tepam::procedure n 0.4.1] +[see_also tepam(n)] +[see_also tepam::argument_dialogbox(n)] +[keywords {argument integrity}] +[keywords {argument validation}] +[keywords arguments] +[keywords procedure] +[keywords subcommand] [copyright {2009/2010, Andreas Drollinger}] [moddesc {Tcl's Enhanced Procedure and Argument Manager}] [titledesc {TEPAM procedure, reference manual}] [category {Procedures, arguments, parameters, options}] [require Tcl 8.3] @@ -97,11 +104,11 @@ [arg name] \ [arg attributes] \ [arg body]] [list_end] -The TEPAM procedure declaration syntax is demonstrated by the following example: +The TEPAM procedure declaration syntax is demonstrated by the following example: [example_begin][fun tepam::procedure] {display message} { -short_description "Displays a simple message box" -description @@ -170,11 +177,11 @@ [list_end] The commands [cmd procedure] as well as [cmd argument_dialogbox] are exported from the namespace [namespace tepam]. To use these commands without the [namespace tepam::] namespace prefix, it is sufficient to import them into the main namespace: [example_begin][cmd {namespace import tepam::*}] - + [cmd procedure] {display_message} { -args { ...[example_end] [subsection "Procedure Attributes"] @@ -198,11 +205,11 @@ [def "-example [arg string]"] A help text or manual page of a procedure can be enriched with eventual examples, using the [emph -example] attribute. [list_end] The following attributes are not relevant for the documentation and help text generation, but they affect the behavior of the declared procedure: - + [list_begin definitions] [def "-named_arguments_first [const 0]|[const 1]"] This attribute defines the calling style of a procedure. TEPAM uses by default the [emph "named arguments first, unnamed arguments later"] style (Tcl). This default behavior can globally be changed by setting the variable [var tepam::named_arguments_first] to [const 0]. This global calling style can be changed individually for a procedure with the procedure's [arg -named_arguments_first] attribute. [def "-auto_argument_name_completion [const 0]|[const 1]"] @@ -219,11 +226,11 @@ The argument definition syntax will be described more in detail in the following sub section. [list_end] The following attribute allows controlling the logging settings for an individual procedure: - + [list_begin definitions] [def "-command_log [const 0]|[const 1]|[const \"interactive\"]"] This argument configures the logging of the procedure calls into the list variable [var tepam::ProcedureCallLogList]. The default configuration defined by the variable [var tepam::command_log] will be used if this argument is not defined in a procedure declaration. [para] @@ -248,13 +255,13 @@ Each of the procedure arguments is declared with a list that has as first element the argument name, followed by eventual attributes. The argument definition syntax can be formalized in the following way: [example_begin]tepam::procedure { -args [cmd {{ - { \ + { \ ...} - { \ + { \ ...} ... }}] } [example_end] @@ -304,11 +311,11 @@ [example_begin]tepam::procedure {print_time} { -interactive_display_format short -args { {hours -type integer -description "Hour"} {minutes -type integer -description "Minute"} - + [cmd {{- The following arguments are optional:}}] {seconds -type integer -default 0 -description "Seconds"} {milliseconds -type integer -default 0 -description "Milliseconds"} } } { @@ -325,11 +332,11 @@ -description "This function perform a complex multiplication" -args { [cmd {{#### First complex number ####}}] {-r0 -type double -description "First number's real part"} {-i0 -type double -description "First number's imaginary part"} - + [cmd {{#### Second complex number ####}}] {-r1 -type double -description "Second number's real part"} {-i1 -type double -description "Second number's imaginary part"} } } { @@ -342,11 +349,11 @@ The following argument attributes are supported: [list_begin definitions] [def "-description [arg string]"] -The description argument attribute is used for documentation purpose. Interactive argument definition forms use this attribute to provide explanations for an argument. +The description argument attribute is used for documentation purpose. Interactive argument definition forms use this attribute to provide explanations for an argument. [def "-type [arg type]"] The type argument attribute allows assigning the argument either to a predefined data type, or to an application specific data type. The argument values that are provided during a procedure call are automatically checked with respect to the defined argument type. [para] The section [sectref {ARGUMENT TYPES}] provides a list of predefined data types and explains how application specific types can be specified. @@ -382,11 +389,11 @@ [def "-validatecommand [arg script]"] Eventual more complex argument value validations can be performed via specific validation commands that are assigned to the [arg -validatecommand] attribute. The provided validation command can be a complete script in which the pattern [emph %P] is replaced by the argument value that has to be validated. An example of a validation command declaration is: [example_begin]tepam::procedure {display_message} { -args { - {text -type string -description "Message text" \ + {text -type string -description "Message text" \ [cmd {-validatecommand "IllegalWordDetector %P"}]} } { }[example_end] [def "-widget [arg string]"] @@ -393,26 +400,26 @@ The widgets that allow defining the different arguments in case of an interactive procedure call are normally selected automatically in function of the argument type. The [arg -widget] attribute allows specifying explicitly a certain widget type for an argument. [para] [def "-auxargs [arg list]"] In case a procedure is called interactively, additional argument attributes can be provided to the interactive argument definition form via the [emph -auxargs] attribute that is itself a list of attribute name/attribute value pairs: -[example_begin]-auxargs {- \ +[example_begin]-auxargs {- \ - ... }[example_end] For example, if a procedure takes as argument a file name it may be beneficial to specify the required file type for the interactive argument definition form. This information can be provided via the [emph -auxargs] attribute to the argument definition form: [example_begin]tepam::procedure LoadPicture { -args { - {FileName -type existingfile -description "Picture file" \ + {FileName -type existingfile -description "Picture file" \ [cmd {-auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}}]} } } { }[example_end] [def "-auxargs_commands [arg script]"] If the auxiliary argument attributes are not static but have to be dynamically adaptable, the [emph -auxargs_commands] allows defining them via commands that are executed during a procedure call. A list of pairs of auxiliary attribute names and commands has to be provided to the [emph -auxargs_commands] attribute. The provided commands are executed in the context of the calling procedure. -[example_begin]-auxargs_commands {- \ +[example_begin]-auxargs_commands {- \ - ... }[example_end] [list_end] @@ -494,14 +501,14 @@ [cmd {{-flag -type none -description "This is a flag"}}] } } { puts [cmd {$flag}] } - + flag_test [emph {-> 0}] - + flag_test -flag [emph {-> 1}][example_end] [para] Since no argument value has to be provided to a flag, also no data check is performed for this argument type. @@ -648,28 +655,27 @@ ... can for example be called in the following ways: [example_begin][cmd {display_message Info "It is PM 7:00."}] [emph {-> Info: It is PM 7:00.}] - + [cmd {display_message Info "It is PM 7:00." "You should go home."}] [emph {-> Info: It is PM 7:00. You should go home.}][example_end] The nice thing is that unnamed arguments can also be called as named arguments, which can be handy, for example if the exact specified argument order is not known to a user: [example_begin][cmd {display_message -mtype Info -text "It is PM 7:00."}] [emph {-> Info: It is PM 7:00.}] - + [cmd {display_message -text "It is PM 7:00." -mtype Info}] [emph {-> Info: It is PM 7:00.}] - + [cmd {display_message -mtype Info -text "It is PM 7:00." -text "You should go home."}] [emph {-> Info: It is PM 7:00. You should go home.}] - + [cmd {display_message -text "It is PM 7:00." -text "You should go home." -mtype Info}] [emph {-> Info: It is PM 7:00. You should go home.}][example_end] - [subsection "Named Arguments"] Named arguments have to be provided to a procedure in form of a parameter pairs composed by the argument names and the argument values. The order how they are provided during a procedure call is irrelevant and has not to match with the argument specification order. [para] @@ -686,17 +692,17 @@ ... can be called in the following ways: [example_begin][cmd {display_message -mtype Info -text "It is PM 7:00."}] [emph {-> Info: It is PM 7:00.}] - + [cmd {display_message -text "It is PM 7:00." -mtype Info}] [emph {-> Info: It is PM 7:00.}] - + [cmd {display_message -mtype Info -text "It is PM 7:00." -text "You should go home."}] [emph {-> Info: It is PM 7:00. You should go home.}] - + [cmd {display_message -text "It is PM 7:00." -text "You should go home." -mtype Info}] [emph {-> Info: It is PM 7:00. You should go home.}][example_end] Also named arguments that have not the [emph -multiple] attribute can be provided multiple times. Only the last provided argument will be retained in such a case: @@ -736,20 +742,20 @@ The name of the first unnamed argument has therefore not to start with the '-' character. The unnamed argument is otherwise considered as name of another named argument. This is especially important if the first unnamed argument is given by a variable that can contain any character strings: [example_begin]my_proc [cmd {-n1 N1 -n2 N2 "->" "<-"}] [emph {-> my_proc: Argument '->' not known}] - + set U1 "->" my_proc -n1 N1 -n2 N2 $U1 U2}] my_proc: Argument '->' not known[example_end] The '--' flag allows separating unambiguously the unnamed arguments from the named arguments. All data after the '--' flag will be considered as unnamed argument: [example_begin]my_proc [cmd {-n1 N1 -n2 N2 -- "->" "<-"}] [emph {-> n1:'N1', n2:'N2', u1:'->', u2:'<-'}] - + set U1 "->" my_proc [cmd {-n1 N1 -n2 N2 -- $U1 U2}] [emph {-> n1:'N1', n2:'N2', u1:'->', u2:'<-'}][example_end] [subsection "Named Arguments First, Unnamed Arguments Later (Tcl Style)"] @@ -775,11 +781,11 @@ The argument parser will assign to each defined unnamed argument a value before it switches to read the named arguments. This default behavior changes a bit if there are unnamed arguments that are optional or that can take multiple values. [para] An argument value will only be assigned to an unnamed argument that is optional (that has either the [arg -optional] attribute or that has a default value), if the value is not beginning with the '-' character or if no named arguments are defined. The value that starts with '-' is otherwise considered as the name of a named argument. [para] -Argument values are assigned to an argument that has the [arg -multiple] attribute as long as the parameter value doesn't starts with the '-' character. +Argument values are assigned to an argument that has the [arg -multiple] attribute as long as the parameter value doesn't starts with the '-' character. [para] Values that start with the '-' character can therefore not be assigned to optional unnamed arguments, which restricts the usage of the Tcl procedure calling style. The Tk style may be preferable in some cases, since it allows separating unambiguously the named arguments from the unnamed ones with the '--' flag. [para] Let's explore in a bit less theoretically the ways how the previously defined procedure can be called: The first example calls the procedure without any parameters, which leads to an error since [arg u1] is a mandatory argument: @@ -823,11 +829,11 @@ But the '--' flag is simply ignored if the argument parser has started to handle the named arguments: [example_begin]my_proc [cmd {U1 -- -n1 N1}] [emph {-> n1:'N1', n2:'', u1:'U1', u2:''}] - + my_proc [cmd {U1 -n1 N1 -- -n2 N2}] [emph {-> n1:'N1', n2:'N2', u1:'U1', u2:''}][example_end] [subsection "Raw Argument List"] @@ -842,9 +848,6 @@ } { puts "args: [cmd {$args}]" } display_message -mtype Warning "It is 7:00" [emph {-> args: -mtype Warning {It is 7:00}}][example_end] - -[see_also tepam(n) tepam::argument_dialogbox(n)] -[keywords procedure arguments {argument validation} {argument integrity} subcommand] [manpage_end] Index: modules/term/ansi_cattr.man ================================================================== --- modules/term/ansi_cattr.man +++ modules/term/ansi_cattr.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::ansi::code::attr n 0.1] +[keywords ansi] +[keywords {attribute control}] +[keywords {color control}] +[keywords control] +[keywords terminal] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {ANSI attribute sequences}] [category {Terminal control}] [require Tcl 8.4] @@ -70,19 +75,9 @@ [call [cmd ::term::ansi::code::attr::norevers]] Reverse off. [call [cmd ::term::ansi::code::attr::nohidden]] Hidden off. [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] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords ansi terminal control {attribute control} {color control}] + +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/ansi_cctrl.man ================================================================== --- modules/term/ansi_cctrl.man +++ modules/term/ansi_cctrl.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::ansi::code::ctrl n 0.1] +[keywords ansi] +[keywords {attribute control}] +[keywords {color control}] +[keywords control] +[keywords terminal] [copyright {2006-2008 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {ANSI control sequences}] [category {Terminal control}] [require Tcl 8.4] @@ -80,11 +85,10 @@ [def B] ASCII Set [def 0] Special Graphics [def 1] Alternate Character ROM Standard Character Set [def 2] Alternate Character ROM Special Graphics [list_end] - [call [cmd ::term::ansi::code::ctrl::sda] [arg arg]...] Set Display Attributes. The arguments are the code sequences for the possible attributes, as provided by the package [package term::ansi::code::attr]. For @@ -187,19 +191,9 @@ [call [cmd ::term::ansi::code::ctrl::showat] [arg row] [arg col] [arg text]] Format the block of text for display at the specified location. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords ansi terminal control {attribute control} {color control}] + +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/ansi_cmacros.man ================================================================== --- modules/term/ansi_cmacros.man +++ modules/term/ansi_cmacros.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::ansi::code::macros n 0.1] +[keywords ansi] +[keywords control] +[keywords frame] +[keywords menu] +[keywords terminal] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {Macro sequences}] [category {Terminal control}] [require Tcl 8.4] @@ -45,28 +50,17 @@ [para] The description, [arg menu], is a dictionary mapping from menu label to command character. - [call [cmd ::term::ansi::code::macros::frame] [arg string]] The paragraph of text contained in the string is padded with spaces at the right margin, after normalizing internal tabs, and then put into a frame made of box-graphics. The result is returned as the result of the command. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords ansi terminal control menu frame] + +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/ansi_code.man ================================================================== --- modules/term/ansi_code.man +++ modules/term/ansi_code.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::ansi::code n 0.1] +[keywords control] +[keywords declare] +[keywords define] +[keywords terminal] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {Helper for control sequences}] [category {Terminal control}] [require Tcl 8.4] @@ -35,19 +39,8 @@ This command defines a procedure [arg name] which returns the control sequence [arg code]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords terminal control declare define] +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/ansi_ctrlu.man ================================================================== --- modules/term/ansi_ctrlu.man +++ modules/term/ansi_ctrlu.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::ansi::ctrl::unix n 0.1.1] +[keywords ansi] +[keywords columns] +[keywords control] +[keywords cooked] +[keywords {input mode}] +[keywords lines] +[keywords raw] +[keywords rows] +[keywords terminal] [copyright {2006-2011 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {Control operations and queries}] [category {Terminal control}] [require Tcl 8.4] @@ -62,20 +71,9 @@ This command queries the terminal connected to the standard input for the number of rows (aka lines) available for display. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords ansi terminal control raw cooked] -[keywords {input mode} lines rows columns] + +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/ansi_send.man ================================================================== --- modules/term/ansi_send.man +++ modules/term/ansi_send.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::ansi::send n 0.1] +[keywords {character output}] +[keywords control] +[keywords terminal] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {Output of ANSI control sequences to terminals}] [category {Terminal control}] [require Tcl 8.4] @@ -17,11 +20,10 @@ The commands are defined using the control sequences provided by the package [package term::ansi::code::ctrl]. They have the same arguments as the commands they are based on, with the exception of the variant for sending to any channel. Their first argument is always a channel handle, then followed by the original arguments. Below we will list only the variant sending to [emph stdout]. - [list_begin definitions] [call [cmd ::term::ansi::send::import] [opt [arg ns]] [arg ...]] Imports the commands of this package into the namespace [arg ns]. If not specified @@ -129,11 +131,10 @@ [call [cmd ::term::ansi::send::lg]] Exit Graphics Mode. - [call [cmd ::term::ansi::send::scs0] [arg tag]] [call [cmd ::term::ansi::send::scs1] [arg tag]] Select Character Set. [para] @@ -151,11 +152,10 @@ [def B] ASCII Set [def 0] Special Graphics [def 1] Alternate Character ROM Standard Character Set [def 2] Alternate Character ROM Special Graphics [list_end] - [call [cmd ::term::ansi::send::sda] [arg arg]...] Set Display Attributes. The arguments are the code sequences for the possible attributes, as provided by the package [package term::ansi::code::attr]. For @@ -259,19 +259,8 @@ Show the block of text at the specified location. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords terminal control {character output}] +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/imenu.man ================================================================== --- modules/term/imenu.man +++ modules/term/imenu.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::interact::menu n 0.1] +[keywords control] +[keywords menu] +[keywords terminal] +[keywords {text display}] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {Terminal widget, menu}] [category {Terminal control}] [require Tcl 8.4] @@ -49,11 +53,10 @@ [para] The method returns the symbolic action of the menu item selected by the user at the end of the interaction. - [call [arg object] [method done]] This method can be used by user supplied actions to terminate the interaction with the object. @@ -145,20 +148,8 @@ The interaction with the object is terminated. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords terminal control menu {text display}] +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/ipager.man ================================================================== --- modules/term/ipager.man +++ modules/term/ipager.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::interact::pager n 0.1] +[keywords control] +[keywords pager] +[keywords terminal] +[keywords {text display}] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {Terminal widget, paging}] [category {Terminal control}] [require Tcl 8.4] @@ -59,11 +63,10 @@ [call [arg object] [method text] [arg text]] This method can be used to change the text shown by the pager. The pager will reset the dispay to show the first line of the text at the top. - [call [arg object] [method configure]] [call [arg object] [method configure] [arg option]] [call [arg object] [method configure] [arg option] [arg value]...] [call [arg object] [method cget] [arg option]] @@ -144,20 +147,8 @@ The interaction with the object is terminated. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords terminal control pager {text display}] +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/receive.man ================================================================== --- modules/term/receive.man +++ modules/term/receive.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::receive n 0.1] +[keywords {character input}] +[keywords control] +[keywords {get character}] +[keywords listener] +[keywords receiver] +[keywords terminal] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {General input from terminals}] [category {Terminal control}] [require Tcl 8.4] @@ -25,11 +31,10 @@ [para] It is the responsibility of the caller to make sure that the channel can provide single characters. On unix this can be done, for example, by using the command of package [package term::ansi::ctrl::unix]. - [call [cmd ::term::receive::listen] [arg cmd] [opt [arg chan]]] This command sets up a filevent listener for the channel with handle [arg chan] and invokes the command prefix [arg cmd] whenever @@ -65,20 +70,8 @@ If not specified [arg chan] defaults to [const stdin]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords terminal control {character input}] -[keywords listener receiver {get character}] +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/term.man ================================================================== --- modules/term/term.man +++ modules/term/term.man @@ -1,7 +1,9 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term n 0.1] +[keywords control] +[keywords terminal] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {General terminal control}] [category {Terminal control}] [require Tcl 8.4] @@ -11,19 +13,8 @@ It is planned to have this package provide highlevel general terminal control 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. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords terminal control] +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/term_bind.man ================================================================== --- modules/term/term_bind.man +++ modules/term/term_bind.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::receive::bind n 0.1] +[keywords {character input}] +[keywords control] +[keywords dispatcher] +[keywords listener] +[keywords receiver] +[keywords terminal] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {Keyboard dispatch from terminals}] [category {Terminal control}] [require Tcl 8.4] @@ -48,18 +54,16 @@ should the processor be in a prefix of [arg str], or at the next reset operation. The action is a command prefix and will be invoked with one argument appended to it, the character sequence causing the invokation. It is executed in the global namespace. - [call [arg object] [method default] [arg cmd]] This method defines a default action [arg cmd] which will be invoked whenever an unknown character sequence is encountered. The command prefix is handled in the same as the regular action defined via method [method map]. - [call [arg object] [method listen] [opt [arg chan]]] This methods sets up a filevent listener for the channel with handle [arg chan] and invokes the dispatcher object whenever characters have @@ -67,40 +71,35 @@ [para] If not specified [arg chan] defaults to [const stdin]. - [call [arg object] [method unlisten] [opt [arg chan]]] This methods removes the filevent listener for the channel with handle [arg chan]. [para] If not specified [arg chan] defaults to [const stdin]. - [call [arg object] [method reset]] This method resets the character processor to the beginning of the tree. - [call [arg object] [method next] [arg char]] This method causes the character processor to process the character [arg c]. This may simply advance the internal state, or invoke an associated action for a recognized sequence. - [call [arg object] [method process] [arg str]] This method causes the character processor to process the character sequence [arg str], advancing the internal state and invoking action as necessary. This is a callback for [method listen]. - [call [arg object] [method eof]] This method causes the character processor to handle EOF on the input. This is currently no-op. @@ -118,20 +117,8 @@ [para] In other words, the set of recognized strings has to form a [term {prefix code}]. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords terminal control {character input}] -[keywords listener receiver dispatcher] +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/term/term_send.man ================================================================== --- modules/term/term_send.man +++ modules/term/term_send.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin term::send n 0.1] +[keywords {character output}] +[keywords control] +[keywords terminal] [copyright {2006 Andreas Kupries }] [moddesc {Terminal control}] [titledesc {General output to terminals}] [category {Terminal control}] [require Tcl 8.4] @@ -26,19 +29,8 @@ This convenience command is like [cmd ::term::send::wrch], except that the destination channel is fixed to [emph stdout]. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph term] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords terminal control {character output}] +[vset CATEGORY term] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/textutil/adjust.man ================================================================== --- modules/textutil/adjust.man +++ modules/textutil/adjust.man @@ -1,6 +1,18 @@ [manpage_begin textutil::adjust n 0.7.1] +[see_also regexp(n)] +[see_also split(n)] +[see_also string(n)] +[keywords adjusting] +[keywords formatting] +[keywords hyphenation] +[keywords indenting] +[keywords justification] +[keywords paragraph] +[keywords string] +[keywords TeX] +[keywords undenting] [moddesc {Text and string utilities, macro processing}] [titledesc {Procedures to adjust, indent, and undent paragraphs}] [category {Text processing}] [require Tcl 8.2] [require textutil::adjust [opt 0.7.1]] @@ -50,11 +62,10 @@ The following options may be used after the [arg string] parameter, and change the way the command places a [emph real] line in a [emph logical] line. - [list_begin options] [opt_def -full [arg boolean]] If set to [const false] (default), trailing space characters are @@ -65,11 +76,10 @@ If set to [const false] (default), no hyphenation will be done. If set to [const true], the command will try to hyphenate the last word of a line. [emph Note]: Hyphenation patterns must be loaded prior, using the command [cmd ::textutil::adjust::readPatterns]. - [opt_def -justify [const center|left|plain|right]] Sets the justification of the returned string to either [const left] (default), [const center], [const plain] or [const right]. The @@ -116,20 +126,18 @@ Set the length of the [emph logical] line in the string to [arg integer]. [arg integer] must be a positive integer value. Defaults to [const 72]. - [opt_def -strictlength] [arg boolean]] If set to [const false] (default), a line can exceed the specified [option -length] if a single word is longer than [option -length]. If set to [const true], words that are longer than [option -length] are split so that no line exceeds the specified [option -length]. [list_end] - [call [cmd ::textutil::adjust::readPatterns] [arg filename]] Loads the internal storage for hyphenation patterns with the contents of the file [arg filename]. This has to be done prior to calling @@ -154,11 +162,10 @@ filenames found in the list returned by [cmd ::textutil::adjust::listPredefined] are legal arguments for this command. - [call [cmd ::textutil::adjust::indent] [arg string] [arg prefix] [opt [arg skip]]] Each line in the [arg string] is indented by adding the string [arg prefix] at its beginning. The modified string is returned as the result of the command. @@ -173,11 +180,10 @@ [para] Together with [cmd ::textutil::adjust::adjust] it is possible to create properly wrapped paragraphs with arbitrary indentations. - [call [cmd ::textutil::adjust::undent] [arg string]] The command computes the common prefix for all lines in [arg string] consisting solely out of whitespace, removes this from each line and @@ -194,22 +200,8 @@ Together with [cmd ::textutil::adjust::adjust] it is possible to create properly wrapped paragraphs with arbitrary indentations. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also regexp(n) split(n) string(n)] -[keywords string justification formatting TeX hyphenation] -[keywords indenting undenting paragraph adjusting] +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/textutil/expander.man ================================================================== --- modules/textutil/expander.man +++ modules/textutil/expander.man @@ -1,15 +1,22 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin textutil::expander n 1.3.1] +[see_also {[uri}] +[see_also http://www.wjduquette.com/expand] +[see_also regexp] +[see_also split] +[see_also string] +[keywords string] +[keywords {template processing}] +[keywords {text expansion}] [copyright {William H. Duquette, http://www.wjduquette.com/expand}] [moddesc {Text and string utilities, macro processing}] [titledesc {Procedures to process templates and expand text.}] [category {Documentation tools}] [require Tcl 8.2] [require textutil::expander [opt 1.3.1]] [description] - [para] The Tcl [cmd subst] command is often used to support a kind of template processing. Given a string with embedded variables or @@ -100,41 +107,35 @@ The following commands are possible for expander objects: [list_begin definitions] - [call [arg expanderName] [method cappend] [arg text]] Appends a string to the output in the current context. This command should rarely be used by macros or application code. - [call [arg expanderName] [method cget] [arg varname]] Retrieves the value of variable [arg varname], defined in the current context. - [call [arg expanderName] [method cis] [arg cname]] Determines whether or not the name of the current context is [arg cname]. - [call [arg expanderName] [method cname]] Returns the name of the current context. - [call [arg expanderName] [method cpop] [arg cname]] Pops a context from the context stack, returning all accumulated output in that context. The context must be named [arg cname], or an error results. - [call [arg expanderName] [method ctopandclear]] Returns the output currently captured in the topmost context and clears that buffer. This is similar to a combination of [method cpop] @@ -145,23 +146,20 @@ Pushes a context named [arg cname] onto the context stack. The context must be popped by [method cpop] before expansion ends or an error results. - [call [arg expanderName] [method cset] [arg varname] [arg value]] Sets variable [arg varname] to [arg value] in the current context. - [call [arg expanderName] [method cvar] [arg varname]] Retrieves the internal variable name of context variable [arg varname]; this allows the variable to be passed to commands like [cmd lappend]. - [call [arg expanderName] [method errmode] [arg newErrmode]] Sets the macro expansion error mode to one of [const nothing], [const macro], [const error], or [const fail]; the default value is @@ -197,11 +195,10 @@ [cmd {uplevel #0}]. If specified, [arg newEvalCmd] will be saved for future use and then returned; it must be a Tcl command expecting one additional argument: the macro to evaluate. - [call [arg expanderName] [method expand] [arg string] [opt [arg brackets]]] Expands the input string, replacing embedded macros with their expanded values, and returns the expanded string. @@ -209,34 +206,30 @@ If [arg brackets] is given, it must be a list of two strings; the items will be used as the left and right macro expansion bracket sequences for this expansion only. - [call [arg expanderName] [method lb] [opt [arg newbracket]]] Returns the current value of the left macro expansion bracket; this is for use as or within a macro, when the bracket needs to be included in the output text. If [arg newbracket] is specified, it becomes the new bracket, and is returned. - [call [arg expanderName] [method rb] [opt [arg newbracket]]] Returns the current value of the right macro expansion bracket; this is for use as or within a macro, when the bracket needs to be included in the output text. If [arg newbracket] is specified, it becomes the new bracket, and is returned. - [call [arg expanderName] [method reset]] Resets all expander settings to their initial values. Unusual results are likely if this command is called from within a call to [method expand]. - [call [arg expanderName] [method setbrackets] [arg {lbrack rbrack}]] Sets the left and right macro expansion brackets. This command is for use as or within a macro, or to permanently change the bracket @@ -243,11 +236,10 @@ definitions. By default, the brackets are [const [lb]] and [const [rb]], but any non-empty string can be used; for example, [const <] and [const >] or [const (*] and [const *)] or even [const Hello,] and [const World!]. - [call [arg expanderName] [method textcmd] [opt [arg newTextCmd]]] Returns the current command for processing plain text, which defaults to the empty string, meaning [emph identity]. If specified, @@ -263,11 +255,10 @@ [emph Note] that the combination of "[cmd textcmd] [arg plaintext]" is run through the [arg evalcmd] for the actual evaluation. In other words, the [arg textcmd] is treated as a special macro implicitly surrounding all plain text in the template. - [call [arg expanderName] [method where]] Returns a three-element list containing the current character position, line, and column the expander is at in the processing of the @@ -304,11 +295,10 @@ % ::myexp expand {[set greeting], [place]!} Howdy, World! % }] - [subsection {Embedding Macros}] An expander macro is simply a Tcl script embedded within a text string. Expander evaluates the script in the global context, and replaces it with its result string. For example, @@ -331,11 +321,10 @@ And that's just a small sample! % }] - [subsection {Writing Macro Commands}] More typically, [emph {macro commands}] are used to create a markup language. A macro command is just a Tcl command that returns an output string. For example, expand can be used to implement a generic @@ -353,11 +342,10 @@ [para] The above definitions of [cmd bold] and [cmd /bold] returns HTML, but such commands can be as complicated as needed; they could, for example, decide what to return based on the desired output format. - [subsection {Changing the Expansion Brackets}] By default, embedded macros are enclosed in square brackets, @@ -391,11 +379,10 @@ % ::myexp expand {This is boldface} {< >} This is boldface % }] - [subsection {Customized Macro Expansion}] By default, macros are evaluated using the Tcl [cmd {uplevel #0}] command, so that the embedded code executes in the global context. The application can provide a different evaluation command using @@ -412,11 +399,10 @@ [para] [example { proc identity {macro} {return $macro} ::myexp evalcmd identity }] - [subsection {Using the Context Stack}] Often it's desirable to define a pair of macros which operate in some way on the plain text between them. Consider a set of macros for @@ -515,20 +501,8 @@ [section HISTORY] [cmd expander] was written by William H. Duquette; it is a repackaging of the central algorithm of the expand macro processing tool. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph {textutil :: expander}] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also regexp split string [uri http://www.wjduquette.com/expand]] -[keywords string {template processing} {text expansion}] +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/textutil/repeat.man ================================================================== --- modules/textutil/repeat.man +++ modules/textutil/repeat.man @@ -1,6 +1,12 @@ [manpage_begin textutil::repeat n 0.7.1] +[see_also regexp(n)] +[see_also split(n)] +[see_also string(n)] +[keywords blanks] +[keywords repetition] +[keywords string] [moddesc {Text and string utilities, macro processing}] [titledesc {Procedures to repeat strings.}] [category {Text processing}] [require Tcl 8.2] [require textutil::repeat [opt 0.7]] @@ -33,21 +39,8 @@ A convenience command. Returns a string of [arg num] spaces. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also regexp(n) split(n) string(n)] -[keywords string repetition blanks] +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/textutil/tabify.man ================================================================== --- modules/textutil/tabify.man +++ modules/textutil/tabify.man @@ -1,6 +1,12 @@ [manpage_begin textutil::tabify n 0.7] +[see_also regexp(n)] +[see_also split(n)] +[see_also string(n)] +[keywords formatting] +[keywords string] +[keywords tabstops] [moddesc {Text and string utilities, macro processing}] [titledesc {Procedures to (un)tabify strings}] [category {Text processing}] [require Tcl 8.2] [require textutil::tabify [opt 0.7]] @@ -19,11 +25,10 @@ Tabify the [arg string] by replacing any substring of [arg num] space chars by a tabulation and return the result as a new string. [arg num] defaults to 8. - [call [cmd ::textutil::tabify::tabify2] [arg string] [opt [arg num]]] Similar to [cmd ::textutil::tabify] this command tabifies the [arg string] and returns the result as a new string. A different @@ -36,17 +41,15 @@ Each line of the text in [arg string] is treated as if there are tabstops every [arg num] columns. Only sequences of space characters containing more than one space character and found immediately before a tabstop are replaced with tabs. - [call [cmd ::textutil::tabify::untabify] [arg string] [opt [arg num]]] Untabify the [arg string] by replacing any tabulation char by a substring of [arg num] space chars and return the result as a new string. [arg num] defaults to 8. - [call [cmd ::textutil::tabify::untabify2] [arg string] [opt [arg num]]] Untabify the [arg string] by replacing any tabulation char by a substring of at most [arg num] space chars and return the result as a @@ -62,21 +65,8 @@ There is one asymmetry though: A tab can be replaced with a single space, but not the other way around. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also regexp(n) split(n) string(n)] -[keywords string formatting tabstops] +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/textutil/textutil.man ================================================================== --- modules/textutil/textutil.man +++ modules/textutil/textutil.man @@ -1,6 +1,17 @@ [manpage_begin textutil n 0.7.1] +[see_also regexp(n)] +[see_also split(n)] +[see_also string(n)] +[keywords formatting] +[keywords hyphenation] +[keywords indenting] +[keywords paragraph] +[keywords {regular expression}] +[keywords string] +[keywords TeX] +[keywords trimming] [moddesc {Text and string utilities, macro processing}] [titledesc {Procedures to manipulate texts and strings.}] [category {Text processing}] [require Tcl 8.2] [require textutil [opt 0.7.1]] @@ -65,11 +76,10 @@ [option -full] option below). The following options may be used after the [arg string] parameter, and change the way the command place a [emph real] line in a [emph logical] line. - [list_begin definitions] [def "-full [arg boolean]"] If set to [const false], any trailing space chars are deleted before @@ -80,11 +90,10 @@ if set to [const false], no hyphenation will be done. If set to [const true], the last word of a line is tried to be hyphenated. Defaults to [const false]. Note: hyphenation patterns must be loaded prior, using the command [cmd ::textutil::adjust::readPatterns]. - [def "[option -justify] [const center|left|plain|right]"] Set the justification of the returned string to [const center], @@ -131,11 +140,10 @@ Set the length of the [emph logical] line in the string to [arg integer]. [arg integer] must be a positive integer value. Defaults to [const 72]. - [def "[option -strictlength] [arg boolean]"] If set to [const false], a line can exceed the specified [option -length] if a single word is longer than [option -length]. If @@ -142,11 +150,10 @@ set to [const true], words that are longer than [option -length] are split so that no line exceeds the specified [option -length]. Defaults to [const false]. [list_end] - [call [cmd ::textutil::adjust::readPatterns] [arg filename]] Loads the internal storage for hyphenation patterns with the contents of the file [arg filename]. This has to be done prior to calling @@ -173,11 +180,10 @@ filenames found in the list returned by [cmd ::textutil::adjust::listPredefined] are legal arguments for this command. - [call [cmd ::textutil::indent] [arg string] [arg prefix] [opt [arg skip]]] Each line in the [arg string] indented by adding the string [arg prefix] at its beginning. The modified string is returned as the result of the command. @@ -193,11 +199,10 @@ [para] Together with [cmd ::textutil::adjust] it is possible to create properly wrapped paragraphs with arbitrary indentations. - [call [cmd ::textutil::undent] [arg string]] The command computes the common prefix for all lines in [arg string] consisting solely out of whitespace, removes this from each line and returns the modified string. @@ -210,11 +215,10 @@ [para] Together with [cmd ::textutil::adjust] it is possible to create properly wrapped paragraphs with arbitrary indentations. - [call [cmd ::textutil::splitn] [arg string] [opt [arg len]]] This command splits the given [arg string] into chunks of [arg len] characters and returns a list containing these chunks. The argument @@ -236,17 +240,15 @@ [arg string] is split at every character, like [cmd split] does. The regular expression [arg regexp] defaults to "[lb]\\t \\r\\n[rb]+". - [call [cmd ::textutil::tabify] [arg string] [opt [arg num]]] Tabify the [arg string] by replacing any substring of [arg num] space chars by a tabulation and return the result as a new string. [arg num] defaults to 8. - [call [cmd ::textutil::tabify2] [arg string] [opt [arg num]]] Similar to [cmd ::textutil::tabify] this command tabifies the @@ -261,11 +263,10 @@ Each line of the text in [arg string] is treated as if there are tabstops every [arg num] columns. Only sequences of space characters containing more than one space character and found immediately before a tabstop are replaced with tabs. - [call [cmd ::textutil::trim] [arg string] [opt [arg regexp]]] Remove in [arg string] any leading and trailing substring according to the regular expression [arg regexp] and return the result as a new string. This apply on any [emph line] in the string, that is any @@ -273,11 +274,10 @@ string and a newline, or between a newline and the end of the string, or, if the string contain no newline, between the beginning and the end of the string. The regular expression [arg regexp] defaults to "[lb] \\t[rb]+". - [call [cmd ::textutil::trimleft] [arg string] [opt [arg regexp]]] Remove in [arg string] any leading substring according to the regular expression [arg regexp] and return the result as a new string. This @@ -297,31 +297,27 @@ or between a newline and the end of the string, or, if the string contain no newline, between the beginning and the end of the string. The regular expression [arg regexp] defaults to "[lb] \\t[rb]+". - [call [cmd ::textutil::trimPrefix] [arg string] [arg prefix]] Removes the [arg prefix] from the beginning of [arg string] and returns the result. The [arg string] is left unchanged if it doesn't have [arg prefix] at its beginning. - [call [cmd ::textutil::trimEmptyHeading] [arg string]] Looks for empty lines (including lines consisting of only whitespace) at the beginning of the [arg string] and removes it. The modified string is returned as the result of the command. - [call [cmd ::textutil::untabify] [arg string] [opt [arg num]]] Untabify the [arg string] by replacing any tabulation char by a substring of [arg num] space chars and return the result as a new string. [arg num] defaults to 8. - [call [cmd ::textutil::untabify2] [arg string] [opt [arg num]]] Untabify the [arg string] by replacing any tabulation char by a substring of at most [arg num] space chars and return the result as a @@ -336,21 +332,19 @@ [para] There is one asymmetry though: A tab can be replaced with a single space, but not the other way around. - [call [cmd ::textutil::strRepeat] [arg "text num"]] The implementation depends on the core executing the package. Used [cmd "string repeat"] if it is present, or a fast tcl implementation if it is not. Returns a string containing the [arg text] repeated [arg num] times. The repetitions are joined without characters between them. A value of [arg num] <= 0 causes the command to return an empty string. - [call [cmd ::textutil::blank] [arg num]] A convenience command. Returns a string of [arg num] spaces. @@ -372,11 +366,10 @@ The complementary operation to [cmd ::textutil::cap]. Forces the first character of [arg string] to lower case and returns the modified string. - [call [cmd ::textutil::longestCommonPrefixList] [arg list]] [call [cmd ::textutil::longestCommonPrefix] [opt [arg string]...]] Computes the longest common prefix for either the [arg string]s given to the command, or the strings specified in the single [arg list], and @@ -388,22 +381,8 @@ one string was specified, the string itself is returned, as it is its own longest common prefix. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also regexp(n) split(n) string(n)] -[keywords string {regular expression} formatting TeX hyphenation] -[keywords indenting trimming paragraph] +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/textutil/textutil_split.man ================================================================== --- modules/textutil/textutil_split.man +++ modules/textutil/textutil_split.man @@ -1,6 +1,12 @@ [manpage_begin textutil::split n 0.7] +[see_also regexp(n)] +[see_also split(n)] +[see_also string(n)] +[keywords {regular expression}] +[keywords split] +[keywords string] [moddesc {Text and string utilities, macro processing}] [titledesc {Procedures to split texts}] [category {Text processing}] [require Tcl 8.2] [require textutil::split [opt 0.7]] @@ -40,21 +46,8 @@ The regular expression [arg regexp] defaults to "[lb]\\t \\r\\n[rb]+". [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also regexp(n) split(n) string(n)] -[keywords string {regular expression} split] +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/textutil/textutil_string.man ================================================================== --- modules/textutil/textutil_string.man +++ modules/textutil/textutil_string.man @@ -1,6 +1,16 @@ [manpage_begin textutil::string n 0.7] +[see_also regexp(n)] +[see_also split(n)] +[see_also string(n)] +[keywords capitalize] +[keywords chop] +[keywords {common prefix}] +[keywords formatting] +[keywords prefix] +[keywords string] +[keywords uncapitalize] [moddesc {Text and string utilities, macro processing}] [titledesc {Procedures to manipulate texts and strings.}] [category {Text processing}] [require Tcl 8.2] [require textutil::string [opt 0.7]] @@ -34,11 +44,10 @@ The complementary operation to [cmd ::textutil::string::cap]. Forces the first character of [arg string] to lower case and returns the modified string. - [call [cmd ::textutil::string::longestCommonPrefixList] [arg list]] [call [cmd ::textutil::string::longestCommonPrefix] [opt [arg string]...]] Computes the longest common prefix for either the [arg string]s given to the command, or the strings specified in the single [arg list], and @@ -50,22 +59,8 @@ one string was specified, the string itself is returned, as it is its own longest common prefix. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also regexp(n) split(n) string(n)] -[keywords string capitalize formatting prefix uncapitalize] -[keywords chop {common prefix}] +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/textutil/trim.man ================================================================== --- modules/textutil/trim.man +++ modules/textutil/trim.man @@ -1,6 +1,13 @@ [manpage_begin textutil::trim n 0.7] +[see_also regexp(n)] +[see_also split(n)] +[see_also string(n)] +[keywords prefix] +[keywords {regular expression}] +[keywords string] +[keywords trimming] [moddesc {Text and string utilities, macro processing}] [titledesc {Procedures to trim strings}] [category {Text processing}] [require Tcl 8.2] [require textutil::trim [opt 0.7]] @@ -25,11 +32,10 @@ or, if the string contain no newline, between the beginning and the end of the string. The regular expression [arg regexp] defaults to "[lb] \\t[rb]+". - [call [cmd ::textutil::trim::trimleft] [arg string] [opt [arg regexp]]] Remove in [arg string] any leading substring according to the regular expression [arg regexp] and return the result as a new string. This apply on any [emph line] in the string, that is any substring between @@ -48,37 +54,22 @@ or between a newline and the end of the string, or, if the string contain no newline, between the beginning and the end of the string. The regular expression [arg regexp] defaults to "[lb] \\t[rb]+". - [call [cmd ::textutil::trim::trimPrefix] [arg string] [arg prefix]] Removes the [arg prefix] from the beginning of [arg string] and returns the result. The [arg string] is left unchanged if it doesn't have [arg prefix] at its beginning. - [call [cmd ::textutil::trim::trimEmptyHeading] [arg string]] Looks for empty lines (including lines consisting of only whitespace) at the beginning of the [arg string] and removes it. The modified string is returned as the result of the command. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph textutil] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[see_also regexp(n) split(n) string(n)] -[keywords string {regular expression} trimming prefix] +[vset CATEGORY textutil] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/tie/tie.man ================================================================== --- modules/tie/tie.man +++ modules/tie/tie.man @@ -1,6 +1,13 @@ [manpage_begin tie n 1.1] +[keywords array] +[keywords database] +[keywords file] +[keywords metakit] +[keywords persistence] +[keywords tie] +[keywords untie] [copyright {2004-2008 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Array persistence}] [category {Programming tools}] [require Tcl 8.4] @@ -34,11 +41,10 @@ This section describes the basic API used to establish and remove ties between Tcl array variables and data sources. This interface is the only one a casual user has to be concerned about. The following sections about the various internal interfaces can be safely skipped. - [list_begin definitions] [call [cmd ::tie::tie] [arg arrayvarname] [arg options]... [arg dstype] [arg dsname]...] This command establishes a tie between the Tcl array whose name is @@ -101,11 +107,10 @@ This option and the option [option -save] exclude each other. If neither this nor option [option -save] are specified then this option is assumed as default. - [opt_def -save] The Tcl array for the new tie is [term saved] to the [term {data source}], and the previously existing contents of the [term {data source}] are erased. @@ -113,11 +118,10 @@ [para] This option and the option [option -open] exclude each other. If neither this nor option [option -open] are specified then option [option -open] is assumed as default. - [opt_def -merge] Using this option prevents the erasure of any previously existing content and merges the data instead. It can be specified in @@ -140,11 +144,10 @@ the [term {data source}]. [list_end] [para] - [call [cmd ::tie::untie] [arg arrayvarname] [opt [arg token]]] This command dissolves one or more ties associated with the Tcl array named by [arg arrayvarname]. If no [arg token] is specified then all ties to that Tcl array are dissolved. Otherwise only the tie the token @@ -165,11 +168,10 @@ [para] The result of the command is an empty string. - [list_begin arguments] [arg_def varname arrayname in] The name of a Tcl array variable which may have ties. @@ -177,11 +179,10 @@ A handle representing a specific tie. This argument is optional. [list_end] [para] - [call [cmd ::tie::info] [method ties] [arg arrayvarname]] This command returns a list of ties associated with the Tcl array variable named by [arg arrayvarname]. The result list will be empty if @@ -198,32 +199,28 @@ name. This means that the command will follow a chain of type definitions ot its end. [list_end] - [subsection {STANDARD DATA SOURCE TYPES}] This package provides the six following types as examples and standard data sources. - [list_begin definitions] [def [const log]] This [term {data source}] does not maintain any actual data, nor persistence. It does not accept any identifying arguments. All changes are simply logged to [const stdout]. - [def [const array]] This [term {data source}] uses a regular Tcl array as the origin of the persistent data. It accepts a single identifying argument, the name of this Tcl array. All changes are mirrored to that array. - [def [const remotearray]] This [term {data source}] is similar to [const array]. The difference is that the Tcl array to which we are mirroring is not directly @@ -277,11 +274,10 @@ process. [list_end] [para] - [def [const file]] This [term {data source}] uses a single file as origin of the persistent data. It accepts a single identifying argument, the path to this file. The file has to be both readable and writable. It may not @@ -301,11 +297,10 @@ compacted, i.e. superfluous operations are removed, if the operations log stored in it contains either at least one operation clearing the whole array, or at least 1.5 times more operations than entries in the loaded array. - [def [const growfile]] This [term {data source}] is like [const file] in terms of the storage medium for the array data, and how it is configured. In constrast to the former it however assumes and ensures that the tied array will @@ -319,11 +314,10 @@ the file radically. For one, the file is read only once and the internal cache cannot be invalidated. Second, writing data is reduced to a simple append, and no compaction step is necessary. The format of the contents is the string representation of a dictionary which can be incrementally extended forever at the end. - [def [const dsource]] This [term {data source}] uses an explicitly specified [term {data source object}] as the source for the persistent @@ -339,17 +333,15 @@ All changes are delegated to the specified object. [list_end] - [section {CREATING NEW DATA SOURCES}] This section is of no interest to the casual user of ties. Only developers wishing to create new data sources have to know the information provided herein. - [subsection {DATA SOURCE OBJECTS} dso] All ties are represented internally by an in-memory object which mediates between the tie framework and the specific @@ -381,11 +373,10 @@ In other words, this type allows the creation of ties which talk to pre-existing [term {data source object}]s, and these objects will survive the removal of the ties using them as well. - [subsection {REGISTERING A NEW DATA SOURCE CLASS}] After a [sectref dsc {data source class}] has been written it is necessary to register it as a new type with the framework. @@ -402,11 +393,10 @@ [cmd ::tie::tie] will accept [arg dstype] as a type name and translate it internally to the appropriate class command for the creation of [sectref dso {data source objects}] for the new [term {data source}]. [list_end] - [subsection {DATA SOURCE CLASS} dsc] Each data source class is represented by a single command, also called the [term {class command}], or [term {object creation command}]. Its @@ -466,38 +456,33 @@ This command has to return a list containing the names of all keys found in the [term {data source}] the object talks to. This is equivalent to [cmd {array names}]. - [call [cmd ds] [method size]] This command has to return an integer number specifying the number of keys found in the [term {data source}] the object talks to. This is equivalent to [cmd {array size}]. - [call [cmd ds] [method get]] This command has to return a dictionary containing the data found in the [term {data source}] the object talks to. This is equivalent to [cmd {array get}]. - [call [cmd ds] [method set] [arg dict]] This command takes a dictionary and adds its contents to the data source the object talks to. This is equivalent to [cmd {array set}]. - [call [cmd ds] [method unset] [opt [arg pattern]]] This command takes a pattern and removes all elements whose keys matching it from the [term {data source}]. If no pattern is specified it defaults to [const *], causing the removal of all elements. This is nearly equivalent to [cmd {array unset}]. - [call [cmd ds] [method setv] [arg index] [arg value]] This command has to save the [arg value] in the [term {data source}] the object talks to, under the key [arg index]. @@ -506,11 +491,10 @@ The result of the command is ignored. If an error is thrown then this error will show up as error of the set operation which caused the method call. - [call [cmd ds] [method unsetv] [arg index]] This command has to remove the value under the key [arg index] from the [term {data source}] the object talks to. @@ -517,11 +501,10 @@ [para] The result of the command is ignored. If an error is thrown then this error will show up as error of the unset operation which caused the method call. - [call [cmd ds] [method getv] [arg index]] This command has to return the value for the key [arg index] in the [term {data source}] the object talks to. @@ -545,19 +528,8 @@ unset a($idx) ds unsetv idx $a($idx) ds getv idx ----------- ----------- }] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph tie] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords array tie untie persistence file database metakit] +[vset CATEGORY tie] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/tie/tie_std.man ================================================================== --- modules/tie/tie_std.man +++ modules/tie/tie_std.man @@ -1,6 +1,13 @@ [manpage_begin tie n 1.1] +[keywords array] +[keywords database] +[keywords file] +[keywords metakit] +[keywords persistence] +[keywords tie] +[keywords untie] [copyright {2008 Andreas Kupries }] [moddesc {Tcl Data Structures}] [titledesc {Array persistence, standard data sources}] [category {Programming tools}] [require Tcl 8.4] @@ -21,19 +28,8 @@ 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. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the packages it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph tie] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords array tie untie persistence file database metakit] +[vset CATEGORY tie] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/tiff/tiff.man ================================================================== --- modules/tiff/tiff.man +++ modules/tiff/tiff.man @@ -1,6 +1,9 @@ [manpage_begin tiff n 0.2.1] +[keywords image] +[keywords tif] +[keywords tiff] [copyright {2005-2006, Aaron Faupell }] [moddesc {TIFF image manipulation}] [titledesc {TIFF reading, writing, and querying and manipulation of meta data}] [category {File formats}] [require Tcl 8.2] @@ -164,19 +167,8 @@ [enum] Cannot write exif ifd [enum] Reading limited to uncompressed 8 bit rgb and 8 bit palletized images [enum] Writing limited to uncompressed 8 bit rgb [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph tiff] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords tiff tif image] +[vset CATEGORY tiff] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/transfer/connect.man ================================================================== --- modules/transfer/connect.man +++ modules/transfer/connect.man @@ -1,16 +1,23 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin transfer::connect n 0.2] +[keywords active] +[keywords channel] +[keywords connection] +[keywords passive] +[keywords secure] +[keywords ssl] +[keywords tls] +[keywords transfer] [copyright {2006-2009 Andreas Kupries }] [moddesc {Data transfer facilities}] [titledesc {Connection setup}] [category {Transfer module}] [require Tcl 8.4] [require snit [opt 1.0]] [require transfer::connect [opt 0.2]] [description] -[keywords transfer channel connection passive active ssl tls secure] [para] This package provides objects holding enough information to enable them to either actively connect to a counterpart, or to passively wait for a connection from said counterpart. @@ -59,11 +66,10 @@ The fully qualified name of the object command is returned as the result of the command. [list_end] - [subsection {Object command}] All objects created by the [cmd ::transfer::connect] command have the following general form: @@ -77,27 +83,25 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions][comment ----methods] [call [arg objectName] [method destroy]] -This method destroys the object. +This method destroys the object. This is safe to do for an [term active] object when a connection has been started, as the completion callback is synchronous. For a [term passive] object currently waiting for its partner to establish the connection however this is not safe and will cause errors later on, when the connection setup completes and tries to access the now missing data structures of the destroyed object. - [call [arg objectName] [method connect] [arg command]] This method starts the connection setup per the configuration of the object. When the connection is established the callback [arg command] @@ -146,21 +150,19 @@ [sectref {Secure connections}] for information on how to do this. [list_end][comment ----mode-behaviour] [list_end][comment ----methods] - [subsection Options] Connection objects support the set of options listed below. [list_begin options] [include include/connect_options.inc] [list_end] - [vset OBJCREATE {transfer::connect C}] [include include/secure.inc] [vset CATEGORY transfer] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/transfer/copyops.man ================================================================== --- modules/transfer/copyops.man +++ modules/transfer/copyops.man @@ -1,15 +1,17 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin transfer::copy n 0.2] +[keywords channel] +[keywords copy] +[keywords transfer] [copyright {2006-2009 Andreas Kupries }] [moddesc {Data transfer facilities}] [titledesc {Data transfer foundation}] [category {Transfer module}] [require Tcl 8.4] [require transfer::copy [opt 0.2]] [description] -[keywords transfer copy channel] [para] This package provides a number of commands for the asynchronous of information contained in either a string or channel. The main point of this package is that the commands here provide a nicer callback API @@ -43,40 +45,35 @@ The argument [arg data] contains a string and this is the information to be transfered. [list_end] - [call [cmd transfer::copy::chan] [arg channel] [arg outchannel] \ [opt [arg options]...]] This command is a shorter and more direct form for the command [cmd {transfer::copy::do chan}]. - [call [cmd transfer::copy::string] [arg string] [arg outchannel] \ [opt [arg options]...]] This command is a shorter and more direct form for the command [cmd {transfer::copy::do string}]. - [call [cmd transfer::copy::doChan] [arg channel] [arg outchannel] \ [arg optvar]] This command is an alternate form of [cmd transfer::copy::chan] which reads its options out of the array variable named by [arg optvar] instead of from a variable length argument list. - [call [cmd transfer::copy::doString] [arg string] [arg outchannel] \ [arg optvar]] This command is an alternate form of [cmd transfer::copy::string] which reads its options out of the array variable named by [arg optvar] instead of from a variable length argument list. - [call [cmd transfer::copy::options] [arg outchannel] [arg optionlist] \ [arg optvar]] This command is the option processor used by all the commands above @@ -99,11 +96,10 @@ operation. It is optional and defaults to the value of [option -buffersize] as configured for the output channel. [para] If specified its value has to be an integer number greater than zero. - [opt_def -command [arg commandprefix]] This option specifies the completion callback of the operation. This option has to be specified. An error will be thrown if it is not, or @@ -128,11 +124,10 @@ Its value has to be a command prefix, see above, [option -command] for a more detailed explanation. When the callback is invoked a single additional arguments is appended to the prefix. This argument is the number of bytes which were transfered so far. - [opt_def -size [arg int]] This option specifies the number of bytes to read from the input data and transfer. It is optional and defaults to "Transfer everything". @@ -160,10 +155,9 @@ these options are required, and they default to the settings of the output channel if not specified. [list_end][comment options] [list_end][comment definitions/api] - [vset CATEGORY transfer] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/transfer/ddest.man ================================================================== --- modules/transfer/ddest.man +++ modules/transfer/ddest.man @@ -1,22 +1,24 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin transfer::data::destination n 0.2] +[keywords channel] +[keywords copy] +[keywords {data destination}] +[keywords transfer] [copyright {2006-2009 Andreas Kupries }] [moddesc {Data transfer facilities}] [titledesc {Data destination}] [category {Transfer module}] [require Tcl 8.4] [require snit [opt 1.0]] [require transfer::data::destination [opt 0.2]] [description] -[keywords transfer copy channel {data destination}] [para] This package provides objects mainly describing the destination of a data transfer. They are also able to initiate the reception of information from a channel into the described destination. - [section API] [list_begin definitions] @@ -40,11 +42,10 @@ The fully qualified name of the object command is returned as the result of the command. [list_end] - [subsection {Object command}] All objects created by the [cmd ::transfer::data::destination] command have the following general form: @@ -58,11 +59,10 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] @@ -70,24 +70,21 @@ This method destroys the object. Doing so while the object is busy with the reception of information from a channel will cause errors later on, when the reception completes and tries to access the now missing data structures of the destroyed object. - [call [arg objectName] [method put] [arg chunk]] The main receptor method. Saves the received [arg chunk] of data into the configured destination. It has to be called for each piece of data received. - [call [arg objectName] [method done]] The secondary receptor method. Finalizes the receiver. It has to be called when the receiving channel signals EOF. Afterward neither itself nor method [method put] can be called anymore. - [call [arg objectName] [method valid] [arg msgvar]] This method checks the configuration of the object for validity. It returns a boolean flag as result, whose value is [const True] if the @@ -106,11 +103,10 @@ with the number of received characters appended to it as the sole additional argument. [list_end] - [subsection Options] All data destinations support the options listed below. It should be noted that all are semi-exclusive, each specifying a different type of destination and associated information. If these options are specified @@ -118,10 +114,9 @@ configure the object. [list_begin options] [include include/ddest_options.inc] [list_end] - [vset CATEGORY transfer] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/transfer/dsource.man ================================================================== --- modules/transfer/dsource.man +++ modules/transfer/dsource.man @@ -1,24 +1,26 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin transfer::data::source n 0.2] +[keywords channel] +[keywords copy] +[keywords {data source}] +[keywords transfer] [copyright {2006-2009 Andreas Kupries }] [moddesc {Data transfer facilities}] [titledesc {Data source}] [category {Transfer module}] [require Tcl 8.4] [require snit [opt 1.0]] [require transfer::copy [opt 0.2]] [require transfer::data::source [opt 0.2]] [description] -[keywords transfer copy channel {data source}] [para] This package provides objects mainly describing the origin of some data to transfer. They are also able to initiate transfers of the described information to a channel using the foundation package [package transfer::copy]. - [section API] [subsection {Package commands}] [list_begin definitions] @@ -43,11 +45,10 @@ The fully qualified name of the object command is returned as the result of the command. [list_end] - [subsection {Object command}] All objects created by the [cmd ::transfer::data::source] command have the following general form: @@ -61,11 +62,10 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] @@ -73,11 +73,10 @@ This method destroys the object. Doing so while a transfer initiated by the object is active is safe as all data required for the transfer itself was copied, and the completion of the transfer will not try to access the initiating object anymore. i.e. the transfer is completely separate from the source object itself. - [call [arg objectName] [method type]] This method returns a string describing the type of the data the object is refering to. The possible values and their meanings are: @@ -103,20 +102,18 @@ The method throws an error if the type is [const undefined]. For type [const string] the returned result is the data itself, whereas for type [const channel] the returned result is the handle of the channel containing the data. - [call [arg objectName] [method size]] This method returns a value depending on the type of the data the object refers to, the size of the data. The method throws an error if the type is [const undefined]. Return of a negative value signals that the object is unable to determine an absolute size upfront (like for data in a channel). - [call [arg objectName] [method valid] [arg msgvar]] This method checks the configuration of the object for validity. It returns a boolean flag as result, whose value is [const True] if the @@ -138,12 +135,10 @@ one go. See the option [option -blocksize] of command [cmd transfer::copy::do] in the package [package transfer::copy]. [list_end] - - [subsection Options] All data sources support the options listed below. It should be noted that the first four options are semi-exclusive, each specifying a different type of data source and associated content. If these options @@ -151,10 +146,9 @@ actually configure the object. [list_begin options] [include include/dsource_options.inc] [list_end] - [vset CATEGORY transfer] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/transfer/receiver.man ================================================================== --- modules/transfer/receiver.man +++ modules/transfer/receiver.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin transfer::receiver n 0.2] +[keywords channel] +[keywords copy] +[keywords {data destination}] +[keywords receiver] +[keywords secure] +[keywords ssl] +[keywords tls] +[keywords transfer] [copyright {2006 Andreas Kupries }] [moddesc {Data transfer facilities}] [titledesc {Data source}] [category {Transfer module}] [require Tcl 8.4] @@ -8,21 +16,19 @@ [require snit [opt 1.0]] [require transfer::data::destination [opt 0.2]] [require transfer::connect [opt 0.2]] [require transfer::receiver [opt 0.2]] [description] -[keywords transfer copy channel {data destination} receiver ssl tls secure] [para] This package pulls data destinations and connection setup together into a combined object for the reception of information coming in over a socket. These objects understand all the options from objects created by the packages [package transfer::data::destination] and [package transfer::connect]. - [section API] [subsection {Package commands}] [list_begin definitions] @@ -86,23 +92,18 @@ [vset RETURNER command] [vset OBJECT {if it was set}] [vset QUALIFIER {internal receiver}] [include include/connect_result_ref.inc] - [call [cmd transfer::receiver] [method {stream file}] \ [arg path] [arg host] [arg port] [opt [arg arg]...]] This method is like [method {stream channel}], except that the received data is written to the file [arg path], replacing any prior content. - - - [list_end] - [subsection {Object command}] All objects created by the [cmd ::transfer::receiver] command have the following general form: @@ -116,11 +117,10 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] @@ -149,11 +149,10 @@ [para] [vset RETURNER method] [vset OBJECT {for an object configured}] [vset QUALIFIER {}] [include include/connect_result_ref.inc] - [call [arg objectName] [method busy]] This method returns a boolean value telling us whether a reception is in progress ([const True]), or not ([const False]). Index: modules/transfer/tqueue.man ================================================================== --- modules/transfer/tqueue.man +++ modules/transfer/tqueue.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin transfer::copy::queue n 0.1] +[keywords channel] +[keywords copy] +[keywords queue] +[keywords transfer] [copyright {2006 Andreas Kupries }] [moddesc {Data transfer facilities}] [titledesc {Queued transfers}] [category {Transfer module}] [require Tcl 8.4] @@ -8,11 +12,10 @@ [require snit [opt 1.0]] [require struct::queue [opt 1.4]] [require transfer::copy [opt 0.2]] [require transfer::copy::queue [opt 0.1]] [description] -[keywords transfer copy channel queue] [para] This package provides objects which serialize transfer requests for a single channel by means of a fifo queue. Accumulated requests are executed in order of entrance, with the first request reaching an idle @@ -61,11 +64,10 @@ Note how just prepending the request with [cmd transfer::copy::do] and inserting a channel handle in between [arg data] and [arg options] easily transforms it from a pure data structure into a command whose evaluation will perform the request. - [section API] [subsection {Package commands}] [list_begin definitions] @@ -89,13 +91,11 @@ namespace otherwise. The fully qualified name of the object command is returned as the result of the command. - [list_end] - [subsection {Object command}] All objects created by the [cmd ::transfer::copy::queue] command have the following general form: @@ -110,11 +110,10 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] @@ -122,24 +121,21 @@ This method destroys the object. Doing so while the object is busy will cause errors later on, when the currently executed request completes and tries to access the now missing data structures of the destroyed object. - [call [arg objectName] [method busy]] This method returns a boolean value telling us if the object is currently serving a request (i.e. [term busy], value [const True]), or not (i.e. [term idle], value [const False]). - [call [arg objectName] [method pending]] This method returns the number of requests currently waiting in the queue for their execution. A request currently served is not counted as waiting. - [call [arg objectName] [method put] [arg request]] This method enters the transfer [arg request] into the object's queue of waiting requests. @@ -148,11 +144,10 @@ servicing the request. Otherwise servicing the new request will be defered until all preceding requests have been served. [list_end] - [section Options] The only option known is [option -on-status-change]. It is optional and defaults to the empty list, disabling the reporting of status changes. Otherwise its argument is a command prefix which is invoked @@ -159,11 +154,10 @@ whenever the internal status of the object changed. The callback is invoked with two additional arguments, the result of the methods [method pending] and [method busy], in this order. This allows any user to easily know, for example, when the object has processed all outstanding requests. - [section Use] A possible application of this package and class is within a HTTP 1.1 server, managing the results waiting for transfer to the client. @@ -172,10 +166,9 @@ It should be noted that in this application the system also needs an 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] [manpage_end] Index: modules/transfer/transmitter.man ================================================================== --- modules/transfer/transmitter.man +++ modules/transfer/transmitter.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin transfer::transmitter n 0.2] +[keywords channel] +[keywords copy] +[keywords {data source}] +[keywords secure] +[keywords ssl] +[keywords tls] +[keywords transfer] +[keywords transmitter] [copyright {2006-2009 Andreas Kupries }] [moddesc {Data transfer facilities}] [titledesc {Data source}] [category {Transfer module}] [require Tcl 8.4] @@ -9,20 +17,18 @@ [require transfer::copy [opt 0.2]] [require transfer::data::source [opt 0.2]] [require transfer::connect [opt 0.2]] [require transfer::transmitter [opt 0.2]] [description] -[keywords transfer copy channel {data source} transmitter ssl tls secure] [para] This package pulls data sources and connection setup together into a combined object for the transmission of information over a socket. These objects understand all the options from objects created by the packages [package transfer::data::source] and [package transfer::connect]. - [section API] [subsection {Package commands}] [list_begin definitions] @@ -44,11 +50,10 @@ [arg objectName] is not fully qualified, and in the specified namespace otherwise. The fully qualified name of the object command is returned as the result of the command. - [call [cmd transfer::transmitter] [method {stream channel}] \ [arg chan] [arg host] [arg port] [opt [arg arg]...]] This method creates a fire-and-forget transfer for the data contained @@ -85,19 +90,17 @@ [vset RETURNER command] [vset OBJECT {if it was set}] [vset QUALIFIER {internal transmitter}] [include include/connect_result_ref.inc] - [call [cmd transfer::transmitter] [method {stream file}] \ [arg path] [arg host] [arg port] [opt [arg arg]...]] This method is like [method {stream channel}], except that the data contained in the file [arg path] is transfered. [list_end] - [subsection {Object command}] All objects created by the [cmd ::transfer::transmitter] command have the following general form: @@ -112,11 +115,10 @@ See section [sectref {Object methods}] for the detailed specifications. [list_end] - [subsection {Object methods}] [list_begin definitions] [call [arg objectName] [method destroy]] @@ -123,11 +125,10 @@ This method destroys the object. Doing so while a transmission is in progress will cause errors later on, when the transmission completes and tries to access the now missing data structures of the destroyed object. - [call [arg objectName] [method start]] This method initiates the data transmission, setting up the connection first and then copying the information. @@ -146,18 +147,16 @@ [vset RETURNER method] [vset OBJECT {for an object configured}] [vset QUALIFIER {}] [include include/connect_result_ref.inc] - [call [arg objectName] [method busy]] This method returns a boolean value telling us whether a transmission is in progress ([const True]), or not ([const False]). [list_end] - [subsection Options] All transmitter objects support the union of the options supported by their connect and data source components, plus two of their own. Index: modules/treeql/treeql.man ================================================================== --- modules/treeql/treeql.man +++ modules/treeql/treeql.man @@ -1,8 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [comment ===========================================] [manpage_begin treeql n 1.3.1] +[keywords Cost] +[keywords DOM] +[keywords {structured queries}] +[keywords tree] +[keywords {tree query language}] +[keywords TreeQL] +[keywords XPath] +[keywords XSLT] [copyright {2004 Colin McCormack }] [copyright {2004 Andreas Kupries }] [moddesc {Tree Query Language}] [titledesc {Query tree objects}] [category {Data structures}] @@ -28,11 +36,10 @@ [package treeql], the package, is a fairly thin query facility over tree-structured data types. It implements an ordered set of nodes (really a list) which are generated and filtered through the application of TreeQL operators to each node in turn. - [comment ===========================================] [section API] [subsection {TreeQL CLASS API}] @@ -85,11 +92,10 @@ The operations of the TreeQL available for this are explained in the section about [sectref {The Tree Query Language}]. This section also explains the term [term {node set}] used above. [list_end] - [subsection {TreeQL OBJECT API}] As [package treeql] has been implemented in [package snit] all the standard methods of [package snit]-based classes are available to the @@ -186,15 +192,13 @@ The operators of the TreeQL language available for this are explained in the section about [sectref {The Tree Query Language}]. This section also explains the term [term {node set}] used above. - [call [arg qo] [method result]] This method returns a list containing the current node set. - [call [arg qo] [method discard]] This method returns the current node set (like method [method result]), but also destroys the query object ([arg qo]). @@ -201,11 +205,10 @@ This is useful when constructing and using sub-queries (%AUTO% objects immediately destroyed after use). [list_end] - [comment ===========================================] [section {The Tree Query Language}] This and the following sections specify the Tree Query Language used @@ -242,11 +245,10 @@ [enum] [sectref {Typed node support}] [list_end] [para] - [comment ===========================================] [subsection {TreeQL Concepts}] The main concept which has to be understood is that of the [term {node set}]. @@ -276,11 +278,10 @@ Regarding the possible multiple occurrence of a node, consider a node set containing two nodes A and B, both having node P as their immediate parent. Application of the TreeQL operator "parent" will then add P to the new node set twice, once per node it was parent of. I.e. the new node set will then be {P P}. - [comment ===========================================] [subsection {Structural generators}] All tree-structural operators locate nodes in the tree based on a @@ -313,60 +314,53 @@ without a parent do not contribute to the new node set. In other words, uses all nodes on the path from node [var N] to root, in this order (root last), for all nodes [var N] in the node set. This includes the root, but not the node itself. - [def [method rootpath]] Replaces the current node set with the ancestors for all nodes [var N] in the node set, should [var N] have a parent. In other words, nodes without a parent do not contribute to the new node set. In contrast to the operator [method ancestors] the nodes are added in reverse order however, i.e. the root node first. - [def [method parent]] Replaces the current node set with the parent of node [var N], for all nodes [var N] in the node set, should [var N] have a parent. In other words, nodes without a parent do not contribute to the new node set. - [def [method children]] Replaces the current node set with the immediate children of node [var N], for all nodes [var N] in the node set, should [var N] have children. In other words, nodes without children do not contribute to the new node set. - [def [method left]] Replaces the current node set with the previous/left sibling for all nodes [var N] in the node set, should [var N] have siblings to the left. In other words, nodes without left siblings do not contribute to the new node set. - [def [method right]] Replaces the current node set with the next/right sibling for all nodes [var N] in the node set, should [var N] have siblings to the right. In other words, nodes without right siblings do not contribute to the new node set. - [def [method prev]] Replaces the current node set with all previous/left siblings of node [var N], for all nodes [var N] in the node set, should [var N] have siblings to the left. In other words, nodes without left siblings are ignored. The left sibling adjacent to the node is added first, and the leftmost sibling last (reverse tree order). - [def [method esib]] Replaces the current node set with all previous/left siblings of node [var N], for all nodes [var N] in the node set, should [var N] have @@ -376,32 +370,28 @@ [para] The method name is a shorthand for [term {Earlier SIBling}]. - [def [method next]] Replaces the current node set with all next/right siblings of node [var N], for all nodes [var N] in the node set, should [var N] have siblings to the right. In other words, nodes without right siblings do not contribute to the new node set. The right sibling adjacent to the node is added first, and the rightmost sibling last (tree order). - [def [method root]] Replaces the current node set with a node set containing a single node, the root of the tree. - [def [method tree]] Replaces the current node set with a node set containing all nodes found in the tree. The nodes are added in pre-order (parent first, then children, the latter from left to right, first to last). - [def [method descendants]] Replaces the current node set with the nodes in all subtrees rooted at node [var N], for all nodes [var N] in the node set, should [var N] @@ -412,11 +402,10 @@ This is like the operator [method children], but covers the children of children as well, i.e. all the [term {proper descendants}]. "Rooted at [var N]" means that [var N] itself is not added to the new set, which is also implied by [term {proper descendants}]. - [def [method subtree]] Like operator [method descendants], but includes the node [var N]. In other words: @@ -428,11 +417,10 @@ children. In other words, nodes without children do not contribute to the new node set. I.e this is like the operator [method children], but covers the children of children, etc. as well. "Of [var N]" means that [var N] itself is added to the new set. - [def [method forward]] Replaces the current node set with the nodes in the subtrees rooted at the right siblings of node [var N], for all nodes [var N] in the node set, should [var N] have right siblings, and they children. In other @@ -442,15 +430,13 @@ [para] This is equivalent to the operator sequence [example {next descendants}] - [def [method later]] This is an alias for the operator [method forward]. - [def [method backward]] Replaces the current node set with the nodes in the flattened previous subtrees, in reverse tree order. @@ -459,11 +445,10 @@ This is nearly equivalent to the operator sequence [example {prev descendants}] The only difference is that this uses the nodes in reverse order. - [def [method earlier]] Replaces the current node set with the nodes in the flattened previous subtrees, in tree order. @@ -473,53 +458,47 @@ [example {prev subtree}] [list_end] - [comment ===========================================] [subsection {Attribute Filters}] These operators filter the node set by reference to attributes of nodes and their properties. Filter means that all nodes not fulfilling the criteria are removed from the node set. In other words, the node set is replaced by the set of nodes fulfilling the filter criteria. - [list_begin definitions] [def "[method hasatt] [arg attr]"] Reduces the node set to nodes which have an attribute named [arg attr]. - [def "[method withatt] [arg attr] [arg value]"] Reduces the node set to nodes which have an attribute named [arg attr], and where the value of that attribute is equal to [arg value] (The "==" operator is [cmd {string equal -nocase}]). - [def "[method withatt!] [arg attr] [arg val]"] This is the same as [method withatt], but all nodes in the node set have to have the attribute, and the "==" operator is [cmd {string equal}], i.e. no [option -nocase]. The operator will fail with an error if they don't have the attribute. - [def "[method attof] [arg attr] [arg vals]"] Reduces the node set to nodes which which have an attribute named [arg attr] and where the value of that attribute is contained in the list [arg vals] of legal values. The contained-in operator used here does glob matching (using the attribute value as pattern) and ignores the case of the attribute value, [emph {but not}] for the elements of [arg vals]. - [def "[method attmatch] [arg attr] [arg match]"] Same as [method withatt], but [cmd {string match}] is used as the "==" operator, and [arg match] is the pattern checked for. @@ -535,17 +514,15 @@ This is especially important should the pattern contain spaces. It has to be wrapped into a list for correct interpretation by this operator [list_end] - [comment ===========================================] [subsection {Attribute Mutators}] These operators change node attributes within the underlying tree. In other words, all these operators have [term {side effects}]. - [list_begin definitions] [def "[method set] [arg attr] [arg val]"] @@ -553,22 +530,19 @@ [var N] in the node set. The operator will fail if a node does not have an attribute named [arg attr]. The tree will be left in a partially modified state. - [def "[method unset] [arg attr]"] Unsets the attribute [arg attr], for all nodes [var N] in the node set. The operator will fail if a node does not have an attribute named [arg attr]. The tree will be left in a partially modified state. [list_end] - - [comment ===========================================] [subsection {Attribute String Accessors}] These operators retrieve the values of node attributes from the @@ -586,11 +560,10 @@ one of these operators, silently discarding any later query elements. It also means that our talk about maintenance of a node set is not quite true. It is a node set while the interpreter is processing commands, but can be left as an attribute value set at the end of query processing. - [list_begin definitions] [def "[method string] [arg op] [arg attr]"] @@ -609,41 +582,36 @@ builtin command [cmd string]. Its first word has to be any of the sub-commands understood by [cmd string]. This has to be followed by all arguments required for the subcommand, except the last. that last argument is supplied by the attribute value. - [def "[method get] [arg pattern]"] For all nodes [var N] in the node set it determines all their attributes with names matching the glob [arg pattern], then the values of these attributes, at last it replaces the node set with the list of these attribute values. - [def [method attlist]] This is a convenience definition for the operator [method {getvals *}]. In other words, it replaces the node set with a list of the attribute values for all attributes for all nodes [var N] in the node set. - [def "[method attrs] [arg glob]"] Replaces the current node set with a list of attribute lists, one attribute list per for all nodes [var N] in the node set. - [def "[method attval] [arg attname]"] Reduces the current node set with the operator [method hasatt], and then replaces it with a list containing the values of the attribute named [arg attname] for all nodes [var N] in the node set. [list_end] - [comment ===========================================] [subsection Sub-queries] Sub-queries yield node sets which are then used to augment, reduce or @@ -659,21 +627,19 @@ [para] The execution of the sub-query uses the current node set as its own initial node set. - [def "[method orq] [arg query]"] Replaces the node set with the set-union of the node set generated by the sub-query [arg query] and itself. Duplicate nodes are removed. [para] The execution of the sub-query uses the current node set as its own initial node set. - [def "[method notq] [arg query]"] Replaces the node set with the set of nodes generated by the sub-query [arg query] which are also not in the current node set. In other word @@ -684,11 +650,10 @@ The execution of the sub-query uses the current node set as its own initial node set. [list_end] - [comment ===========================================] [subsection {Node Set Operators}] These operators change the node set directly, without referring to the @@ -704,16 +669,14 @@ Removes duplicate nodes from the node set, preserving order. In other words, the earliest occurrence of a node handle is preserved, every other occurrence is removed. - [def [method select]] Replaces the current node set with a node set containing only the first node from the current node set - [def "[method transform] [arg query] [arg var] [arg body]"] First it interprets the sub-query [arg query], using the current node set as its initial node set. @@ -727,11 +690,10 @@ [para] The script [arg body] is executed in the context of the caller. - [def "[method map] [arg var] [arg body]"] Iterates over the current node set, binding the handle of each node to the variable named in [arg var], and executing the script [arg body]. @@ -740,22 +702,19 @@ [para] The script [arg body] is executed in the context of the caller. - [def "[method quote] [arg val]"] Appends the literal value [arg val] to the current node set. - [def "[method replace] [arg val]"] Replaces the current node set with the literal list value [arg val]. [list_end] - [comment ===========================================] [subsection {Node Set Iterators}] [list_begin definitions] @@ -769,21 +728,19 @@ [para] The script [arg body] is executed in the context of the caller. - [def "[method with] [arg query] [arg body]"] Interprets the [arg query], then runs the script [arg body] on the node set generated by the query. At last it restores the current node set as it was before the execution of the query. [para] The script [arg body] is executed in the context of the caller. - [def "[method over] [arg var] [arg body]"] Executes the script [arg body] for each node in the node set, with the variable named by [arg var] bound to the name of the current node. @@ -797,25 +754,22 @@ [para] The results of executing the [arg body] are ignored. - [def [method delete]] Deletes all the nodes contained in the current node set from the tree. [list_end] - [comment ===========================================] [subsection {Typed node support}] These filters and accessors assume the existence of an attribute called [const @type], and are short-hand forms useful for cost-like tree query, html tree editing, and so on. - [list_begin definitions] [def [method nodetype]] @@ -823,31 +777,27 @@ Attribute string accessor. This is equivalent to [example {get @type}] - [def "[method oftype] [arg t]"] Reduces the node set to nodes whose type is equal to [arg t], with letter case ignored. - [def "[method nottype] [arg t]"] Reduces the node set to nodes whose type is not equal to [arg t], with letter case ignored. - [def "[method oftypes] [arg attrs]"] Reduces set to nodes whose @type is an element in the list [arg attrs] of types. The value of @type is used as a glob pattern, and letter case is relevant. [list_end] - [section Examples] ... TODO ... @@ -862,20 +812,8 @@ [uri http://wiki.tcl.tk/treeql TreeQL] on the Tcler's Wiki. Discuss this package there. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph treeql] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {tree query language} {structured queries}] -[keywords tree TreeQL Cost XPath DOM XSLT] +[vset CATEGORY treeql] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/try/tcllib_try.man ================================================================== --- modules/try/tcllib_try.man +++ modules/try/tcllib_try.man @@ -1,23 +1,29 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin try n 1] +[see_also catch(n)] +[see_also error(n)] +[see_also return(n)] +[see_also throw(n)] +[keywords cleanup] +[keywords error] +[keywords exception] +[keywords final] +[keywords {resource management}] [copyright {2008 Donal K. Fellows, BSD licensed}] [moddesc {Forward compatibility implementation of [try]}] [titledesc {try - Trap and process errors and exceptions}] [category Utility] [require Tcl 8.5] [require try [opt 1]] -[keywords cleanup error exception final {resource management}] -[see_also catch(n) error(n) return(n) throw(n)] [description] [para] This package provides a forward-compatibility implementation of Tcl 8.6's try/finally command (TIP 329), for Tcl 8.5. The code was directly pulled from Tcl 8.6 revision ?, when try/finally was implemented as Tcl procedure instead of in C. - [list_begin definitions] [comment {- - -- --- ----- -------- ------------- ---------------------}] [call [cmd ::try] [arg body] [opt [arg handler...]] [opt "[method finally] [arg script]"]] @@ -98,11 +104,10 @@ } [cmd finally] { close \$f } [example_end] - [para] Handle different reasons for a file to not be openable for reading: [para][example_begin] [cmd try] { set f [lb]open /some/file/name[rb] } [method trap] {POSIX EISDIR} {} { @@ -110,17 +115,8 @@ } [method trap] {POSIX ENOENT} {} { puts "failed to open /some/file/name: it doesn't exist" } [example_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph try] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY try] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/uev/uevent.man ================================================================== --- modules/uev/uevent.man +++ modules/uev/uevent.man @@ -1,15 +1,19 @@ [manpage_begin uevent n 0.3.1] +[see_also hook(n)] +[keywords bind] +[keywords event] +[keywords {generate event}] +[keywords hook] +[keywords unbind] [copyright {2007-2012 Andreas Kupries }] [moddesc {User events}] [titledesc {User events}] [category {Programming tools}] [require Tcl 8.4] [require uevent [opt 0.3.1]] [require logger] -[keywords event bind unbind {generate event} hook] -[see_also hook(n)] [description] This package provides a general facility for the handling of user events. Allows the binding of arbitrary commands to arbitrary events on arbitrary tags, removal of bindings, and event generation. @@ -185,17 +189,8 @@ [para] The result of the command is the empty string. [comment ============================================================] [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph uevent] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY uevent] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/uev/uevent_onidle.man ================================================================== --- modules/uev/uevent_onidle.man +++ modules/uev/uevent_onidle.man @@ -1,13 +1,18 @@ [manpage_begin uevent::onidle n 0.1] +[keywords callback] +[keywords deferal] +[keywords event] +[keywords idle] +[keywords merge] +[keywords on-idle] [copyright {2008 Andreas Kupries }] [moddesc {User events}] [titledesc {Request merging and deferal to idle time}] [require Tcl 8.4] [require uevent::onidle [opt 0.1]] [require logger] -[keywords event idle deferal merge on-idle callback] [description] This package provides objects which can merge multiple requestes for an action and execute the action the moment the system (event loop) becomes idle. The action to be run is configured during object @@ -52,18 +57,8 @@ 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. - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph uevent] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - +[vset CATEGORY uevent] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/units/units.man ================================================================== --- modules/units/units.man +++ modules/units/units.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin units n 1.2] +[keywords angle] +[keywords constants] +[keywords conversion] +[keywords distance] +[keywords radians] +[keywords unit] [copyright {2000-2005 Mayo Foundation}] [moddesc {Convert and manipulate quantities with units}] [titledesc {unit conversion}] [require Tcl 8.1] [require units [opt 2.1]] @@ -59,11 +65,10 @@ 1.0 % ::units::convert 1.0 millimeter 1000.0 [example_end] - [call [cmd ::units::reduce] [arg unitString]] Returns a unit string consisting of a scale factor followed by a space separated list of sorted and reduced primitive units. The reduced unit string may include a forward-slash (separated from the @@ -73,12 +78,10 @@ [example_begin] % ::units::reduce pascal 1000.0 gram / meter second second [example_end] - - [call [cmd ::units::new] [arg name] [arg baseUnits]] Creates a new unit conversion with the specified name. The new unit [arg name] must be only alphabetic (upper or lower case) letters. @@ -98,18 +101,15 @@ 601288.475303 [example_end] [list_end] - - [section "UNIT STRING FORMAT"] Value and unit string format is quite flexible. It is possible to define virtually any combination of units, prefixes, and powers. Valid unit strings must conform to these rules. - [list_begin itemized] [item] A unit string consists of an optional scale factor followed by zero or @@ -163,24 +163,19 @@ 30 second 30.0 second 30 seconds 30.0 second 200*meter/20.5*second 9.75609756098 meter / second [example_end] - - - - [section "SI UNITS"] [para] The standard SI units are predefined according to [emph "NIST Special Publication 330"]. Standard units for both SI Base Units (Table 1) and SI Derived Units with Special Names (Tables 3a and 3b) are included here for reference. Each standard unit name and abbreviation are included in this package. - [subsection "SI Base Units"] [example_begin] Quantity Unit Name Abbr. @@ -191,11 +186,10 @@ Current ampere A Temperature kelvin K Amount mole mol Luminous Intensity candela cd [example_end] - [subsection "SI Derived Units with Special Names"] [example_begin] Quantity Unit Name Abbr. Units Base Units @@ -226,11 +220,11 @@ [para] Note that the SI unit kilograms is actually implemented as grams because 1e-6 kilogram = 1 milligram, not 1 microkilogram. The abbreviation for Electric Resistance (ohms), which is the omega -character, is not supported. +character, is not supported. [para] Also note that there is no support for Celsius or Farenheit temperature. The units conversion routines can only scale values @@ -245,11 +239,10 @@ SI Units can have a multiple or sub-multiple prefix. The prefix or its abbreviation should appear before the unit, without spaces. Compound prefixes are not allowed, and a prefix should never be used alone. These prefixes are defined in Table 5 of [emph "Special Publication 330"]. - [subsection "SI Prefixes"] [example_begin] Prefix Name Abbr. Factor @@ -295,11 +288,10 @@ over 40 conversions for British thermal units!) Application specific conversions can always be added using the [cmd new] command, but some well known and often used conversions are included in this package. - [subsection "Non-SI Units"] [example_begin] Unit Name Abbr. Base Units -------------------------------------------------- @@ -336,11 +328,10 @@ revolutionPerMinute rpm 1.047198E-1 rad/s yard yd 9.144E-1 m year 3.1536E7 s [example_end] - [subsection "Quantities and Derived Units with Special Names"] This units conversion package is limited specifically to unit reduction, comparison, and scaling. This package does not consider any of the quantity names for either base or derived units. A similar @@ -371,11 +362,10 @@ 330"]. The quantity [emph "area"], for example, could be defined as units properly reducing to [emph "meter^2"], although the utility of defining a unit named [emph "square meter"] is arguable. - [section "REFERENCES"] The unit names, abbreviations, and conversion values are derived from those published by the United States Department of Commerce Technology Administration, National Institute of Standards and Technology (NIST) @@ -391,25 +381,12 @@ code written in 1993 by Adrian Mariano which performed dimensional analysis of unit strings using fixed size tables of C structs. After going missing in the late 1990's, Adrian's code has reappeared in the GNU Units program at [uri http://www.gnu.org/software/units/] - [section "AUTHORS"] Robert W. Techentin - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph units] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords unit conversion constants distance radians angle] +[vset CATEGORY units] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/uri/uri.man ================================================================== --- modules/uri/uri.man +++ modules/uri/uri.man @@ -1,6 +1,21 @@ [manpage_begin uri n 1.2.2] +[keywords {fetching information}] +[keywords file] +[keywords ftp] +[keywords gopher] +[keywords http] +[keywords ldap] +[keywords mailto] +[keywords news] +[keywords prospero] +[keywords {rfc 2255}] +[keywords {rfc 2396}] +[keywords uri] +[keywords url] +[keywords wais] +[keywords www] [moddesc {Tcl Uniform Resource Identifier Management}] [titledesc {URI utilities}] [category Networking] [require Tcl 8.2] [require uri [opt 1.2.2]] @@ -16,12 +31,10 @@ [para] The package currently does not conform to RFC 2396 ([uri http://www.rfc-editor.org/rfc/rfc2396.txt]), but quite likely should be. Patches and other help are welcome. - - [section COMMANDS] [list_begin definitions] @@ -65,21 +78,19 @@ Either [const message-id] or [const newsgroup-name]. [list_end] [para] - [call [cmd uri::join] [opt "[arg key] [arg value]"]...] [cmd uri::join] takes a list of key/value pairs (generated by [cmd uri::split], for example) and returns the canonical url they represent. Currently only the schemes [term http], [term ftp], [term mailto], [term urn], [term news], [term ldap] and [term file] are supported. See section [sectref EXTENDING] on how to expand that range. - [call [cmd uri::resolve] [arg base] [arg url]] [cmd uri::resolve] resolves the specified [arg url] relative to @@ -88,16 +99,14 @@ taken from [arg base] and prepended to it. The result of this operation is returned. For an empty [arg url] the result is [arg base]. - [call [cmd uri::isrelative] [arg url]] [cmd uri::isrelative] determines whether the specified [arg url] is absolute or relative. - [call [cmd uri::geturl] [arg url] [opt "[arg options]..."]] [cmd uri::geturl] decodes the specified [arg url] and then dispatches the request to the package appropriate for the scheme found in the @@ -119,17 +128,15 @@ [para] It is not possible to specify results of the command. They depend on the [cmd geturl]-command for the scheme the request was dispatched to. - [call [cmd uri::canonicalize] [arg uri]] [cmd uri::canonicalize] returns the canonical form of a URI. The canonical form of a URI is one where relative path specifications, ie. . and .., have been resolved. - [call [cmd uri::register] [arg schemeList] [arg script]] [cmd uri::register] registers the first element of [arg schemeList] as a new scheme and the remaining elements as aliases for this scheme. It @@ -182,21 +189,8 @@ Original code (regular expressions) by Andreas Kupries. Modularisation by Steve Ball, also the split/join/resolve functionality. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph uri] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords uri url {fetching information} www http ftp mailto] -[keywords news gopher wais ldap prospero file] -[keywords {rfc 2396} {rfc 2255}] +[vset CATEGORY uri] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/uri/urn-scheme.man ================================================================== --- modules/uri/urn-scheme.man +++ modules/uri/urn-scheme.man @@ -1,6 +1,10 @@ [manpage_begin uri_urn n 1.1.2] +[keywords {rfc 2141}] +[keywords uri] +[keywords url] +[keywords urn] [moddesc {Tcl Uniform Resource Identifier Management}] [titledesc {URI utilities, URN scheme}] [category Networking] [require Tcl 8.2] [require uri::urn [opt 1.1.2]] @@ -29,19 +33,8 @@ takes an [term urn] url, removes the quoting from all disallowed characters, and returns the modified urls as its result. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph uri] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords uri url urn] -[keywords {rfc 2141}] +[vset CATEGORY uri] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/uuid/uuid.man ================================================================== --- modules/uuid/uuid.man +++ modules/uuid/uuid.man @@ -1,6 +1,8 @@ [manpage_begin uuid n 1.0.2] +[keywords GUID] +[keywords UUID] [moddesc {uuid}] [copyright {2004, Pat Thoyts }] [titledesc {UUID generation and comparison}] [category {Hashes, checksums, and encryption}] [require Tcl 8.2] @@ -44,19 +46,8 @@ Paul J. Leach, "UUIDs and GUIDs", February 1998. ([uri http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt]) [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph uuid] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords UUID GUID] +[vset CATEGORY uuid] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/valtype/valtype_common.man ================================================================== --- modules/valtype/valtype_common.man +++ modules/valtype/valtype_common.man @@ -1,13 +1,17 @@ [comment {-*- tcl -*- --- doctools ---}] [manpage_begin valtype::common n 1] +[keywords Checking] +[keywords isA] +[keywords Testing] +[keywords {Type checking}] +[keywords Validation] +[keywords {Value checking}] [copyright {2011 Andreas Kupries }] [titledesc "Validation, common code"] [moddesc {Validation types}] [category {Validation, Type checking}] -[keywords Validation Checking Testing {Type checking}] -[keywords {Value checking} isA] [require Tcl 8.5] [require valtype::common [opt 1]] [description] This package implements a number of common commands used by the @@ -96,13 +100,11 @@ The check digit of the input value is wrong. This usually signals a data-entry error, with digits transposed, forgotten, etc. Of course, th input may be an outright fake too. - [include include/c_lenpfx.inc] [list_end] - [vset CATEGORY valtype] [include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/cat.man ================================================================== --- modules/virtchannel_base/cat.man +++ modules/virtchannel_base/cat.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::cat n 1] +[keywords {concatenation channel}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2011 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Concatenation channel}] [require Tcl 8.5] @@ -36,20 +40,8 @@ This command creates the concatenation channel using all the provided channels, and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} {concatenation channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/facade.man ================================================================== --- modules/virtchannel_base/facade.man +++ modules/virtchannel_base/facade.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::facade n 1] +[keywords {concatenation channel}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2011 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Facade channel}] [require Tcl 8.5] @@ -62,19 +66,8 @@ This command creates the facade channel around the provided channel [arg chan], and returns its handle. [list_end] -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} {concatenation channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/halfpipe.man ================================================================== --- modules/virtchannel_base/halfpipe.man +++ modules/virtchannel_base/halfpipe.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::halfpipe n 1] +[keywords callbacks] +[keywords fifo] +[keywords {in-memory channel}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {In-memory channel, half of a fifo2}] [require Tcl 8.5] @@ -36,11 +42,10 @@ handler, in this order. The latter is supplied to the caller to provide her with access to the [method put] method for adding data to the channel. - [para] Two halfpipes with a bit of glue logic in the callbacks make for one [package tcl::chan::fifo2]. [call [arg objectCmd] [method put] [arg bytes]] @@ -69,20 +74,8 @@ This callback is invoked when the channel has run out of data to read. A single argument is supplied, the handle of the channel. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords fifo callbacks] -[keywords {virtual channel} {reflected channel} {in-memory channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/nullzero.man ================================================================== --- modules/virtchannel_base/nullzero.man +++ modules/virtchannel_base/nullzero.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::nullzero n 1] +[keywords /dev/null] +[keywords /dev/zero] +[keywords null] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] +[keywords zero] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Null/Zero channel combination}] [require Tcl 8.5] @@ -30,20 +37,8 @@ This command creates a new nullzero channel and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} null /dev/null zero /dev/zero {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/randseed.man ================================================================== --- modules/virtchannel_base/randseed.man +++ modules/virtchannel_base/randseed.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::randseed n 1] +[keywords /dev/random] +[keywords merge] +[keywords random] +[keywords {reflected channel}] +[keywords seed] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Utilities for random channels}] [require Tcl 8.5] @@ -28,20 +35,8 @@ by XORing them elementwise, modulo 256. If the lists are not of equial length the shorter of the two is padded with 0s before merging. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords seed merge] -[keywords {virtual channel} {reflected channel} random /dev/random {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/std.man ================================================================== --- modules/virtchannel_base/std.man +++ modules/virtchannel_base/std.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::std n 1] +[keywords {reflected channel}] +[keywords {standard io}] +[keywords stdin] +[keywords stdout] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2011 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Standard I/O, unification of stdin and stdout}] [require Tcl 8.5] @@ -30,20 +36,8 @@ [para] The channel is created only once, on the first call, and all future calls simply return this handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} stdin stdout {standard io} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_fifo.man ================================================================== --- modules/virtchannel_base/tcllib_fifo.man +++ modules/virtchannel_base/tcllib_fifo.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::fifo n 1] +[keywords fifo] +[keywords {in-memory channel}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {In-memory fifo channel}] [require Tcl 8.5] @@ -31,20 +36,8 @@ This command creates a new fifo channel and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords fifo] -[keywords {virtual channel} {reflected channel} {in-memory channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_fifo2.man ================================================================== --- modules/virtchannel_base/tcllib_fifo2.man +++ modules/virtchannel_base/tcllib_fifo2.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::fifo2 n 1] +[keywords {connected fifos}] +[keywords fifo] +[keywords {in-memory channel}] +[keywords {inter-thread communication}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {In-memory interconnected fifo channels}] [require Tcl 8.5] @@ -36,20 +43,8 @@ This command creates a new connected pair of fifo channels and returns their handles, as a list containing two elements. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[keywords {inter-thread communication} {connected fifos} fifo] -[keywords {virtual channel} {reflected channel} {in-memory channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_memchan.man ================================================================== --- modules/virtchannel_base/tcllib_memchan.man +++ modules/virtchannel_base/tcllib_memchan.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::memchan n 1] +[keywords {in-memory channel}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {In-memory channel}] [require Tcl 8.5] @@ -33,20 +37,8 @@ This command creates a new memchan channel and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} {in-memory channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_null.man ================================================================== --- modules/virtchannel_base/tcllib_null.man +++ modules/virtchannel_base/tcllib_null.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::null n 1] +[keywords /dev/null] +[keywords null] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Null channel}] [require Tcl 8.5] @@ -33,20 +38,8 @@ This command creates a new null channel and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} null /dev/null {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_random.man ================================================================== --- modules/virtchannel_base/tcllib_random.man +++ modules/virtchannel_base/tcllib_random.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::random n 1] +[keywords /dev/random] +[keywords random] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Random channel}] [require Tcl 8.5] @@ -34,20 +39,8 @@ The seed is a list of integer numbers used to initialize the internal feedback shift register of the generator. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} random /dev/random {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_string.man ================================================================== --- modules/virtchannel_base/tcllib_string.man +++ modules/virtchannel_base/tcllib_string.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::string n 1] +[keywords {in-memory channel}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Read-only in-memory channel}] [require Tcl 8.5] @@ -34,20 +38,8 @@ This command creates a new string channel and returns its handle. The channel provides random read-only access to the [arg content] string. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} {in-memory channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_variable.man ================================================================== --- modules/virtchannel_base/tcllib_variable.man +++ modules/virtchannel_base/tcllib_variable.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::variable n 1] +[keywords {in-memory channel}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {In-memory channel using variable for storage}] [require Tcl 8.5] @@ -35,20 +39,8 @@ The content of the channel is stored in the associated namespace variable [arg varname]. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} {in-memory channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/tcllib_zero.man ================================================================== --- modules/virtchannel_base/tcllib_zero.man +++ modules/virtchannel_base/tcllib_zero.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::zero n 1] +[keywords /dev/zero] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] +[keywords zero] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Zero channel}] [require Tcl 8.5] @@ -33,20 +38,8 @@ This command creates a new zero channel and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} zero /dev/zero {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_base/textwindow.man ================================================================== --- modules/virtchannel_base/textwindow.man +++ modules/virtchannel_base/textwindow.man @@ -1,7 +1,12 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::textwindow n 1] +[keywords {reflected channel}] +[keywords {text widget}] +[keywords {tip 219}] +[keywords Tk] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Textwindow channel}] [require Tcl 8.5] @@ -27,20 +32,8 @@ This command creates a new textwindow channel and returns its handle. Data written to this channel will appear in the associated [arg widget]. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} Tk {text widget} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_core/core.man ================================================================== --- modules/virtchannel_core/core.man +++ modules/virtchannel_core/core.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::core n 1] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Basic reflected/virtual channel support}] [require Tcl 8.5] @@ -15,11 +18,10 @@ reflected or virtual channel (initialization, finalization). [para] This class expects to be used as either superclass of a concrete channel class, or to be mixed into such a class. - [section {Class API}] [list_begin definitions] [call [cmd ::tcl::chan::core] [arg objectName]] @@ -29,18 +31,16 @@ be used to invoke various operations on the object, as described in the section for the [sectref {Instance API}]. [list_end] - [section {Instance API}] The API of channel core instances provides only two methods, both corresponding to channel handler commands (For reference see [uri http:/tip.tcl.tk/219 {TIP 219}]). They expect to be called from whichever object instance the channel core was made a part of. - [list_begin definitions] [call [arg objectName] [method initialize] [arg thechannel] [arg mode]] @@ -51,16 +51,14 @@ core. [para] It further remembers the channel handle in an instance variable for access by sub-classes. - [call [arg objectName] [method finalize] [arg thechannel]] This method implements standard behaviour for the [method finalize] method of channel handlers. It simply destroys itself. - [call [arg objectName] [method destroy]] Destroying the channel core instance closes the channel it was initialized for, see the method [method initialize]. When destroyed @@ -67,20 +65,8 @@ from within a call of [method finalize] this does not happen, under the assumption that the channel is being destroyed by Tcl. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_core/events.man ================================================================== --- modules/virtchannel_core/events.man +++ modules/virtchannel_core/events.man @@ -1,7 +1,11 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::chan::events n 1] +[keywords {event management}] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Event support for reflected/virtual channels}] [require Tcl 8.5] @@ -17,11 +21,10 @@ sub-class of [package tcl::chan::core], inheriting all of its behaviour. [para] This class expects to be used as either superclass of a concrete channel class, or to be mixed into such a class. - [section {Class API}] [list_begin definitions] [call [cmd ::tcl::chan::events] [arg objectName]] @@ -31,19 +34,17 @@ be used to invoke various operations on the object, as described in the section for the [sectref {Instance API}]. [list_end] - [section {Instance API}] The API of channel event core instances provides only four methods, two corresponding to channel handler commands (For reference see [uri http:/tip.tcl.tk/219 {TIP 219}]), and the other two for use by sub-classes to control event generation. They former expect to be called from whichever object instance the channel event core was made a part of. - [list_begin definitions] [call [arg objectName] [method finalize] [arg thechannel]] @@ -50,18 +51,16 @@ This method implements standard behaviour for the [method finalize] method of channel handlers. It overrides the behaviour inherited from [package tcl::chan::core] and additionally disables any and all event generation before destroying itself. - [call [arg objectName] [method watch] [arg thechannel] [arg eventmask]] This method implements standard behaviour for the [method watch] method of channel handlers. Called by the IO system whenever the interest in event changes it updates the instance state to activate and/or suppress the generation of the events of (non-)interest. - [call [arg objectName] [method allow] [arg eventname]...] [call [arg objectName] [method disallow] [arg eventname]...] These two methods are exported to sub-classes, so that their instances @@ -73,20 +72,8 @@ able to determine which events it should (not) generate and act accordingly. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} {event management} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_core/transformcore.man ================================================================== --- modules/virtchannel_core/transformcore.man +++ modules/virtchannel_core/transformcore.man @@ -1,7 +1,10 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::core n 1] +[keywords {reflected channel}] +[keywords {tip 219}] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Basic reflected/virtual channel transform support}] [require Tcl 8.5] @@ -15,11 +18,10 @@ reflected or virtual channel transformation (initialization, finalization). [para] This class expects to be used as either superclass of a concrete channel class, or to be mixed into such a class. - [section {Class API}] [list_begin definitions] [call [cmd ::tcl::transform::core] [arg objectName]] @@ -29,18 +31,16 @@ be used to invoke various operations on the object, as described in the section for the [sectref {Instance API}]. [list_end] - [section {Instance API}] The API of transform core instances provides only two methods, both corresponding to transform handler commands (For reference see [uri http:/tip.tcl.tk/230 {TIP 230}]). They expect to be called from whichever object instance the transform core was made a part of. - [list_begin definitions] [call [arg objectName] [method initialize] [arg thechannel] [arg mode]] @@ -51,16 +51,14 @@ Tcl core. [para] It further remembers the channel handle in an instance variable for access by sub-classes. - [call [arg objectName] [method finalize] [arg thechannel]] This method implements standard behaviour for the [method finalize] method of channel handlers. It simply destroys itself. - [call [arg objectName] [method destroy]] Destroying the transform core instance closes the channel and transform it was initialized for, see the method [method initialize]. When destroyed @@ -67,20 +65,8 @@ from within a call of [method finalize] this does not happen, under the assumption that the channel and transform are being destroyed by Tcl. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {virtual channel} {reflected channel} {tip 219}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/adler32.man ================================================================== --- modules/virtchannel_transform/adler32.man +++ modules/virtchannel_transform/adler32.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::adler32 n 1] +[keywords adler32] +[keywords {channel transformation}] +[keywords checksum] +[keywords {reflected channel}] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Adler32 transformation}] [require Tcl 8.6] @@ -56,21 +63,8 @@ write direction is not saved. [list_end] [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords adler32 checksum transformation {channel transformation}] -[keywords {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/base64.man ================================================================== --- modules/virtchannel_transform/base64.man +++ modules/virtchannel_transform/base64.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::base64 n 1] +[keywords base64] +[keywords {channel transformation}] +[keywords {reflected channel}] +[keywords {tip 230}] +[keywords {tip 317}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Base64 encoding transformation}] [require Tcl 8.6] @@ -30,21 +37,8 @@ This command creates a base64 transformation on top of the channel [arg chan] and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords base64 {tip 317} transformation {channel transformation}] -[keywords {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/counter.man ================================================================== --- modules/virtchannel_transform/counter.man +++ modules/virtchannel_transform/counter.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::counter n 1] +[keywords {channel transformation}] +[keywords counter] +[keywords {reflected channel}] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Counter transformation}] [require Tcl 8.6] @@ -55,21 +61,8 @@ write direction is not saved. [list_end] [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords counter transformation {channel transformation}] -[keywords {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/crc32.man ================================================================== --- modules/virtchannel_transform/crc32.man +++ modules/virtchannel_transform/crc32.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::crc32 n 1] +[keywords {channel transformation}] +[keywords checksum] +[keywords crc32] +[keywords {reflected channel}] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Crc32 transformation}] [require Tcl 8.6] @@ -56,21 +63,8 @@ write direction is not saved. [list_end] [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords crc32 checksum transformation {channel transformation}] -[keywords {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/hex.man ================================================================== --- modules/virtchannel_transform/hex.man +++ modules/virtchannel_transform/hex.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::hex n 1] +[keywords {channel transformation}] +[keywords hexadecimal] +[keywords {reflected channel}] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Hexadecimal encoding transformation}] [require Tcl 8.6] @@ -30,21 +36,8 @@ This command creates a hex transformation on top of the channel [arg chan] and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords hexadecimal transformation {channel transformation}] -[keywords {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/identity.man ================================================================== --- modules/virtchannel_transform/identity.man +++ modules/virtchannel_transform/identity.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::identity n 1] +[keywords {channel transformation}] +[keywords identity] +[keywords {reflected channel}] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Identity transformation}] [require Tcl 8.6] @@ -37,21 +43,8 @@ This command creates an identity transformation on top of the channel [arg chan] and returns its handle. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords identity transformation {channel transformation}] -[keywords {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/limitsize.man ================================================================== --- modules/virtchannel_transform/limitsize.man +++ modules/virtchannel_transform/limitsize.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::limitsize n 1] +[keywords {channel transformation}] +[keywords limitsize] +[keywords {reflected channel}] +[keywords {size limit}] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {limiting input}] [require Tcl 8.6] @@ -32,21 +39,8 @@ channel before EOF is signaled by the transformation. Note that popping the transformation clears the EOF it generated as well. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords {size limit} transformation {channel transformation}] -[keywords limitsize {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/observe.man ================================================================== --- modules/virtchannel_transform/observe.man +++ modules/virtchannel_transform/observe.man @@ -1,7 +1,14 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::observe n 1] +[keywords {channel transformation}] +[keywords observer] +[keywords {reflected channel}] +[keywords {stream copy}] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Observer transformation, stream copy}] [require Tcl 8.6] @@ -36,21 +43,8 @@ [arg chan] and returns its handle. The channel handles [arg logr] and [arg logw] are there the data is copied to. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords observer {stream copy} transformation {channel transformation}] -[keywords {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/otp.man ================================================================== --- modules/virtchannel_transform/otp.man +++ modules/virtchannel_transform/otp.man @@ -1,7 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::otp n 1] +[keywords {channel transformation}] +[keywords cipher] +[keywords decryption] +[keywords encryption] +[keywords {one time pad}] +[keywords otp] +[keywords {reflected channel}] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] +[keywords xor] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Encryption via one-time pad}] [require Tcl 8.6] @@ -35,21 +46,8 @@ contents are reads and xored with the bytes written to and read from the channel. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords xor otp encryption decryption transformation {channel transformation}] -[keywords {one time pad} cipher {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/rot.man ================================================================== --- modules/virtchannel_transform/rot.man +++ modules/virtchannel_transform/rot.man @@ -1,7 +1,18 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::rot n 1] +[keywords {caesar cipher}] +[keywords {channel transformation}] +[keywords cipher] +[keywords decryption] +[keywords encryption] +[keywords {reflected channel}] +[keywords rot] +[keywords rot13] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {rot-encryption}] [require Tcl 8.6] @@ -12,11 +23,10 @@ The [package tcl::transform::rot] package provides a command creating a channel transformation which performs primitive encryption (on writing) and decryption (on reading) on the alphabetic characters. The algorithm is the Caesar-cipher, a specific variant of which is rot13. - [para] A related transformations in this module is [package tcl::transform::otp]. [para] The internal [package TclOO] class implementing the transform @@ -40,21 +50,8 @@ characters, i.e. "A...Z" and "a...z". All other bytes are passed through unchanged. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords rot encryption decryption rot13 transformation {channel transformation}] -[keywords {caesar cipher} cipher {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/spacer.man ================================================================== --- modules/virtchannel_transform/spacer.man +++ modules/virtchannel_transform/spacer.man @@ -1,7 +1,13 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::spacer n 1] +[keywords {channel transformation}] +[keywords {reflected channel}] +[keywords spacing] +[keywords {tip 230}] +[keywords transformation] +[keywords {virtual channel}] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {Space insertation and removal}] [require Tcl 8.6] @@ -32,21 +38,8 @@ reverse, removing the spacing. If [arg space] is not specified it defaults to a single space character (ASCII 32). [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords spacing transformation {channel transformation}] -[keywords {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/virtchannel_transform/tcllib_zlib.man ================================================================== --- modules/virtchannel_transform/tcllib_zlib.man +++ modules/virtchannel_transform/tcllib_zlib.man @@ -1,7 +1,16 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin tcl::transform::zlib n 1] +[keywords {channel transformation}] +[keywords compression] +[keywords decompression] +[keywords {reflected channel}] +[keywords {tip 230}] +[keywords {tip 234}] +[keywords transformation] +[keywords {virtual channel}] +[keywords zlib] [copyright {2009 Andreas Kupries }] [moddesc {Reflected/virtual channel support}] [category Channels] [titledesc {zlib (de)compression}] [require Tcl 8.6] @@ -30,21 +39,8 @@ [para] The [arg level] specifies how much effort is put into the compression, from [const 0] to [const 9], and defaults to [const 4]. [list_end] - -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph virtchannel] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords compression decompression transformation {channel transformation}] -[keywords zlib {tip 234} {virtual channel} {reflected channel} {tip 230}] +[vset CATEGORY virtchannel] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/wip/wip.man ================================================================== --- modules/wip/wip.man +++ modules/wip/wip.man @@ -1,7 +1,10 @@ [comment {-*- text -*-}] [manpage_begin wip n 2.2] +[keywords interpreter] +[keywords list] +[keywords word] [copyright {2007-2010 Andreas Kupries }] [moddesc {Word Interpreter}] [titledesc {Word Interpreter}] [category {Programming tools}] [require Tcl 8.4] @@ -92,11 +95,10 @@ list of words when used, enabling recursive use from within command implementations. [list_end] - [section {CLASS API}] The main command of the package is: [list_begin definitions] @@ -162,11 +164,11 @@ [method wip_setup] for initializing it. This method has to be called from within the constructor of the type using the word interpreter. If further installs a series of procedures which make the object API of the word interpreter directly available to the type's methods, -without having to specify the component. +without having to specify the component. [para] [emph Note] that this does and cannot install the language to interpret, i.e. the mapping from words to engine methods. @@ -229,11 +231,10 @@ Sets the handler for unknown words to [arg cmdprefix]. This command prefix takes one argument, the current word, and either throws some error, or returns the result of executing the word, as defined by the handler. The default handler simply throws an error. - [call [arg wipName] [method runl] [arg wordlist]] Treats the list of words in [arg wordlist] as a program and executes the contained command one by one. The result of the command executed @@ -376,19 +377,8 @@ [section EXAMPLES] No examples yet. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph wip] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - - -[keywords word list interpreter] +[vset CATEGORY wip] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/yaml/CHANGES ================================================================== --- modules/yaml/CHANGES +++ modules/yaml/CHANGES @@ -16,17 +16,17 @@ 0.3.6: - 2011-08-23 - fixed for empty block/floating sub node. to see - https://sourceforge.net/tracker/?func=detail&atid=112883&aid=3396656&group_id=12883 - - https://sourceforge.net/tracker/?func=detail&atid=112883&aid=3396661&group_id=12883 + - https://core.tcl.tk/tcllib/tktview?name=3396661fff 0.3.5: - 2009-05-24 - To read uninitialized yaml::data(current), when there is not empty line or "---" at the beginning of yaml. - Thanks al_chou! - - https://sourceforge.net/tracker/?func=detail&atid=112883&aid=2795699&group_id=12883 + - https://core.tcl.tk/tcllib/tktview?name=2795699fff - supported for YAML termination(...) 0.3.4: - 2008-09-27 - fixed for some incorrect use of "string first/last" 0.3.3: Index: modules/yaml/huddle.man ================================================================== --- modules/yaml/huddle.man +++ modules/yaml/huddle.man @@ -1,7 +1,15 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin huddle n 0.1.5] +[see_also yaml] +[keywords {data exchange}] +[keywords {exchange format}] +[keywords huddle] +[keywords json] +[keywords parsing] +[keywords {text processing}] +[keywords yaml] [copyright {2008 KATO Kanryu }] [moddesc {HUDDLE}] [titledesc {Create and manipulate huddle object}] [require Tcl 8.4] [require huddle [opt 0.1.5]] @@ -48,26 +56,22 @@ Create a huddle object as a dict. It can contain other huddle objects. [call [cmd "huddle list"] [opt [arg "value value ..."]]] Create a huddle object as a list. It can contain other huddle objects. - [call [cmd "huddle get"] [arg object] [arg key] [opt [arg "key ..."]]] Almost the same as [cmd "dict get"]. Get a sub-object from the huddle object. [arg key] can be used to huddle-list's index. - [call [cmd "huddle gets"] [arg object] [arg key] [opt [arg "key ..."]]] Get a sub-object from the huddle object, stripped. - [call [cmd "huddle set"] [arg objectVar] [arg key] [opt [arg "key ..."]] [arg value]] Almost the same as [cmd "dict set"]. Set a sub-object from the huddle object. [arg key] can be used to huddle-list's index. - [call [cmd "huddle remove"] [arg object] [arg key] [opt [arg "key ..."]]] Almost the same as [cmd "dict remove"]. Remove a sub-object from the huddle object. [arg key] can be used to huddle-list's index. @@ -110,18 +114,15 @@ HUDDLE {L {{s i} {s j} {s k} {s l}}} % huddle append bb g h i HUDDLE {L {{s i} {s j} {s k} {s l} {s g} {s h} {s i}}} }] - [call [cmd "huddle keys"] [arg object]] The same as [cmd "dict keys"]. - [call [cmd "huddle llength"] [arg object]] The same as [cmd llength]. - [call [cmd "huddle type"] [arg object] [opt [arg "key key..."]]] Return the element type of specified by keys. if [opt key] is not given, returns the type of root node. [para] @@ -147,11 +148,10 @@ % huddle type {HUDDLE {L {{s a} {s b} {s c}}}} list % huddle type {HUDDLE {D {aa {s b} cc {s d}}}} cc string }] - [call [cmd "huddle strip"] [arg object]] Stripped all tags. Converted to normal Tcl's list/dict. [call [cmd "huddle jsondump"] [arg object] [opt [arg offset]] [opt [arg newline]] [opt [arg begin_offset]]] @@ -191,11 +191,10 @@ [call [cmd "huddle compile"] [arg spec] [arg data]] construct a huddle object from plain old tcl values. - [arg spec] is defined as follows: [list_begin definitions] [def [const string]] data is simply a string @@ -223,11 +222,10 @@ [example {% huddle compile {dict * list} {a {1 2 3} b {4 5}} HUDDLE {D {a {L {{s 1} {s 2} {s 3}}} b {L {{s 4} {s 5}}}}} % huddle compile {dict * {list {dict d list}}} {a {{c 1} {d {2 2 2} e 3}} b {{f 4 g 5}}} HUDDLE {D {a {L {{D {c {s 1}}} {D {d {L {{s 2} {s 2} {s 2}}} e {s 3}}}}} b {L {{D {f {s 4} g {s 5}}}}}}} }] - [call [cmd "huddle isHuddle"] [arg object]] if [arg object] is a huddle, returns 1. the other, returns 0. [call [cmd "huddle checkHuddle"] [arg object]] @@ -444,11 +442,10 @@ } } } }] - [section "How to add type"] [para] You can add huddle-node types e.g. ::struct::tree. @@ -517,25 +514,13 @@ ], "s" ] }] - [section LIMITATIONS] [para] now printing. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph huddle] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also yaml] -[keywords huddle yaml json {text processing} parsing {data exchange} {exchange format}] +[vset CATEGORY huddle] +[include ../doctools2base/include/feedback.inc] [manpage_end] Index: modules/yaml/yaml.man ================================================================== --- modules/yaml/yaml.man +++ modules/yaml/yaml.man @@ -1,17 +1,25 @@ [comment {-*- tcl -*- doctools manpage}] [manpage_begin yaml n 0.3.6] +[see_also base64] +[see_also huddle] +[see_also json] +[keywords {data exchange}] +[keywords huddle] +[keywords parsing] +[keywords {text processing}] +[keywords yaml] [copyright {2008 KATO Kanryu }] [moddesc {YAML processing}] [titledesc {YAML Format Encoder/Decoder}] [require Tcl 8.4] [require yaml [opt 0.3.6]] [description] [para] The [package yaml] package provides a simple Tcl-only library for parsing the -YAML [uri http://www.yaml.org/] data exchange format as specified in +YAML [uri http://www.yaml.org/] data exchange format as specified in [uri http://www.yaml.org/spec/1.1/]. [para] The [package yaml] package returns data as a Tcl [cmd dict]. Either the [package dict] package or Tcl 8.5 is @@ -32,11 +40,10 @@ [arg txt] is a filename of YAML-stream. [opt_def [const -stream]] [arg txt] is just a YAML-stream. - [opt_def "[const -types] [arg list]"] The [arg list] is a type list for the yaml-scalar types.(e.g. !!str !!timestamp !!integer !!true ...) @@ -79,11 +86,10 @@ [call [cmd ::yaml::setOption] [opt [arg options]]] Change implicit options for the library. Now, the params are the same as [cmd ::yaml::yaml2dict]. Arguments of[cmd ::yaml::yaml2dict] is more priority than this setting. - [call [cmd ::yaml::dict2yaml] [arg dict] [opt [arg indent]] [opt [arg wordwrap]]] [call [cmd ::yaml::list2yaml] [arg list] [opt [arg indent]] [opt [arg wordwrap]]] [call [cmd ::yaml::huddle2yaml] [arg huddle] [opt [arg indent]] [opt [arg wordwrap]]] Convert a dict/list/huddle object into YAML stream. @@ -94,11 +100,10 @@ [def wordwrap] word wrap for YAML stream. currently default is 40. [list_end] - [list_end] [para] [section EXAMPLES] @@ -154,18 +159,17 @@ [example {{ --- - [name , hr, avg ] - [Mark McGwire, 65, 0.278] - [Sammy Sosa , 63, 0.288] -- +- Mark McGwire: {hr: 65, avg: 0.278} Sammy Sosa: { hr: 63, avg: 0.288} } => {name hr avg} {{Mark McGwire} 65 0.278} {{Sammy Sosa} 63 0.288} {{Mark McGwire} {hr 65 avg 0.278} {Sammy Sosa} {hr 63 avg 0.288}} }] - [section LIMITATIONS] [para] tag parser not implemented. currentry, tags are merely ignored. @@ -177,19 +181,8 @@ Too many braces, or too few braces. [para] Not enough character set of line feeds. Please use only "\n" as line breaks. -[section {BUGS, IDEAS, FEEDBACK}] - -This document, and the package it describes, will undoubtedly contain -bugs and other problems. - -Please report such in the category [emph yaml] of the -[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. - -Please also report any ideas for enhancements you may have for either -package and/or documentation. - -[see_also json huddle base64] -[keywords yaml {text processing} parsing {data exchange} huddle] +[vset CATEGORY yaml] +[include ../doctools2base/include/feedback.inc] [manpage_end]

aes(n) 1.1 tcllib "Advanced Encryption Standard (AES)"

aes(n) 1.1.1 tcllib "Advanced Encryption Standard (AES)"