Open tcllib tickets: Docs

Triage of all 509 open and Pending tickets of tcllib (bugs, patches and feature requests) on 2026-11-15. Each ticket was checked against tcllib trunk on Linux with Tcl 9.1, 9.0, 8.6 and 8.5, using local servers for the network modules and a Windows 11 VM for Windows-only tickets. Outdated, superseded, duplicate and misfiled tickets are listed separately. Rows marked patch link to a prototype fix with a regression test (147 in all, in tcllib-triage/prototypes). Updated 2026-11-16.

Docs 22

⬜0fc5d241092024Gaps in format documentationDOCS (all points still valid). The PE serialization docs do not list .., cl or str. pt::pe verify still rejects [pt::pe class abc] and `[…

Open ticket 0fc5d24109 · Bug · pt (parsetools) · filed 2024-01-21

Full verdict

DOCS (all points still valid). The PE serialization docs do not list .., cl or str. pt::pe verify still rejects [pt::pe class abc] and [pt::pe str abc] ("invalid operator"), while .. verifies. t x with multi-character x is not documented as invalid. ddigit is still described as regexp-based.

  • Module pt docs (include/serial/pexpression.inc, pt_astree.man, pt_peg_language.man)
  • Tested pt::pe verify on range/class/str results on 9.1. Grep of the docs; pexpression.inc has been unchanged since 2010.
  • Cause docs gaps, plus an inconsistency between pt::pe class/str and pt::pe verify
  • Prototype none (needs the maintainer to decide whether cl/str are official serialization operators)
  • Suggested action keep open
  • Suggested ticket comment Still valid on trunk: .., cl and str are undocumented, and verify rejects cl/str although pt::pe class/str produce them.
⬜9c75b39aa22023reference to unknown library "streams" in documentation of generatorpatchDOCS (the sentence is still in generator.man on trunk)

Open ticket 9c75b39aa2 · Bug · generator · filed 2023-10-26

Full verdict

DOCS (the sentence is still in generator.man on trunk)

  • Module generator 0.3 (generator.man)
  • Tested grep generator.man; the sentence is at line 236.
  • Cause aku (2024-04-05): even the author does not remember what "streams" meant. aku said he would remove the sentence, but has not done so yet.
  • Prototype prototypes/9c75b39aa2.patch (16 lines; removes the sentence). Docs only, so no test is possible.
  • Suggested action apply prototype, close as Fixed
  • Suggested ticket comment Removed the reference to the nonexistent "streams" library, as agreed with the author.
⬜743f95e16d2023matrices cannot be a single columnDOCS (inherent: {{1} {2} {3}} and {1 2 3} are the same Tcl value; mkMatrix 3 1 returns 1.0 1.0 1.0, and shape gives 3)

Open ticket 743f95e16d · Bug · math :: linearalgebra · filed 2023-06-28

Full verdict

DOCS (inherent: {{1} {2} {3}} and {1 2 3} are the same Tcl value; mkMatrix 3 1 returns 1.0 1.0 1.0, and shape gives 3)

  • Module math, math::linearalgebra 1.1.7
  • Tested 9.1, 8.6: shape {{1} {2} {3}} gives 3, and shape [mkMatrix 3 1 1.0] gives 3.
  • Prototype none (a doc note in linalg.man near shape/mkMatrix, saying n×1 matrices cannot be told apart from vectors; doc only, so no test)
  • Suggested action add a doc note, then close
  • Suggested ticket comment A single-column matrix and a vector have the same string representation in Tcl, so this cannot be fixed without a different data representation. We will document it.
⬜422bc67f032020Tcllib cmdline example is inadequateDOCS (the reported getfiles problem is misuse, not a bug)

Open ticket 422bc67f03 · Bug · cmdline · filed 2020-09-17

Full verdict

DOCS (the reported getfiles problem is misuse, not a bug)

  • Module cmdline 1.5.3
  • Tested getfiles [list /path/a.zip] 0 returns the file. getfiles {/path/*.zip} 0 on Unix warns "no files match", as documented (no globbing on Unix). The reporter passed the pattern instead of the remaining argv. There is no optind in cmdline: argv is modified in place, and the example now says so (2dce7b748a, Fixed).
  • Cause n/a
  • Prototype none (docs only. Could extend the example with set files [cmdline::getfiles $argv 0] after getoptions.)
  • Suggested action add a short example of processing the remaining argv, then close
  • Suggested ticket comment After getoptions, argv holds the remaining words. Pass that list to getfiles (on Unix the shell does the globbing). There is no optind variable.
⬜c426ceafad2019pki package - add pki::public_keyDOCS (RFE-OPEN; ::pki::public_key keylist ?password? ?encodePem? (pki.tcl:861) and ::pki::pkcs::parse_public_key key ?password? (pki.tcl:1135) …

Open ticket c426ceafad · RFE · pki · filed 2019-10-26

Full verdict

DOCS (RFE-OPEN; ::pki::public_key keylist ?password? ?encodePem? (pki.tcl:861) and ::pki::pkcs::parse_public_key key ?password? (pki.tcl:1135) exist but pki.man still documents neither)

  • Module pki 0.22
  • Tested grep of pki.man on trunk.
  • Prototype none (docs only: two [call] entries modelled on ::pki::key and ::pki::pkcs::parse_key)
  • Suggested action document both commands in pki.man, then close
  • Suggested ticket comment Still valid on trunk: both pki::public_key and pki::pkcs::parse_public_key exist but are missing from pki.man.
⬜14e2c2cbba2017Update aycock parser example to include lexerpatchDOCS (still valid). The example is also wrong: it and the [call] use aycock::parser, which does not exist (`invalid command name "aycock::parser"…

Open ticket 14e2c2cbba · Bug · Documentation · filed 2017-05-24

Full verdict

DOCS (still valid). The example is also wrong: it and the [call] use aycock::parser, which does not exist (invalid command name "aycock::parser"). The real command is grammar::aycock::parser.

  • Module grammar::aycock 1.1 (docs, aycock.man)
  • Tested ran the documented example (fails) and the submitter's lexer example on 9.1 and 8.6 (prints 40)
  • Prototype prototypes/14e2c2cbba.patch (+25/-4, docs only, no test). It fixes the [call] name to ::grammar::aycock::parser and replaces the example with a slightly condensed version of the submitted lexer plus the parser. I extracted the example from the .man and ran it: it prints 40 on 9.1 and 8.6, and dtplite renders it.
  • Suggested action apply the prototype, regenerate the docs, close
  • Suggested ticket comment Agreed. The current example also calls the non-existent aycock::parser. Proposed doc update with a lexer and the correct grammar::aycock::parser name.
⬜9fdff6c6032016Write manpages for oo::dialectDOCS (still only oodialect.md, no .man; not in the generated docs. The oo::meta twin a20b080092 was fixed in 2019.)

Open ticket 9fdff6c603 · Bug · A Category Is Missing · filed 2016-11-14

Full verdict

DOCS (still only oodialect.md, no .man; not in the generated docs. The oo::meta twin a20b080092 was fixed in 2019.)

  • Module oo::dialect 0.3.4
  • Tested ls modules/oodialect; grep embedded/md/toc.md (no entry)
  • Cause n/a
  • Prototype none (docs-only; could convert oodialect.md to doctools)
  • Suggested action keep open, or close if oo::dialect counts as superseded by clay
  • Suggested ticket comment oo::dialect still has only a Markdown README and no doctools manpage, so it's missing from the docs.
⬜83567329c92016suggest clarification of pki docs about proc input typesDOCS (partly addressed: since tcllib 1.21 (900fb4ff6d, 2021-10-31) parse_cert/parse_csr say "can be either PEM or DER encoded". parse_key, verify_c…

Open ticket 83567329c9 · RFE · pki · filed 2016-03-19

Full verdict

DOCS (partly addressed: since tcllib 1.21 (900fb4ff6d, 2021-10-31) parse_cert/parse_csr say "can be either PEM or DER encoded". parse_key, verify_cert etc. still just say "key"/"cert", and nothing states that the arguments are data, not file names)

  • Module pki 0.22
  • Tested read pki.man on trunk.
  • Prototype none (docs only)
  • Suggested action add a sentence near the top of pki.man that all key/cert/csr arguments are the PEM or DER data, not file names, then close
  • Suggested ticket comment Partly done in 1.21 (parse_cert/parse_csr now say "PEM or DER encoded"). A general note that the arguments are the encoded data, not file names, is still missing.
⬜70d8274f902015json2dict return valueDOCS (fixed on trunk 2b2bcd7ecf, 2026-01-27). json.man documents dict-or-list results and the type ambiguity. DUPLICATE of 2df194042b in substance.

Open ticket 70d8274f90 · Bug · json · filed 2015-09-02

Full verdict

DOCS (fixed on trunk 2b2bcd7ecf, 2026-01-27). json.man documents dict-or-list results and the type ambiguity. DUPLICATE of 2df194042b in substance.

  • Module json 1.3.6
  • Tested doc read
  • Cause n/a
  • Prototype none
  • Suggested action close as Fixed (docs) / Duplicate of 2df194042b
  • Suggested ticket comment The docs now explain that arrays become lists, objects become dicts, and that the type cannot be recovered 2b2bcd7ecf.
⬜2df194042b2015json2dict does not always produce a dictionaryDOCS (fixed on trunk, 3ec5b08cd9 / b96bdd24d5, merged 2b2bcd7ecf, 2026-01-23/27, not yet released)

Open ticket 2df194042b · Bug · json · filed 2015-01-16

Full verdict

DOCS (fixed on trunk, 3ec5b08cd9 / b96bdd24d5, merged 2b2bcd7ecf, 2026-01-23/27, not yet released)

  • Module json 1.3.6
  • Tested json.man on trunk: "Returns a dict or list …" and explains that type information is not kept.
  • Cause n/a
  • Prototype none
  • Suggested action close as Fixed (docs)
  • Suggested ticket comment The documentation now states that json2dict returns a dict or a list (or a scalar) and that type information is lost 2b2bcd7ecf.
⬜dec864a3b52014Example ::tcl::transform::otpDOCS (RFE-OPEN; vt_otp.man still has no example)

Open ticket dec864a3b5 · RFE · otp · filed 2014-10-15

Full verdict

DOCS (RFE-OPEN; vt_otp.man still has no example)

  • Module virtchannel_transform, tcl::transform::otp 1.1 (vt_otp.man)
  • Tested a file encrypt/decrypt round trip on 9.1 and 8.6 works: open the output channel, open the key file twice (rb) for keychanw/keychanr, call tcl::transform::otp $out $kw $kr, then fcopy. Reading back through the transform with fresh key channels gives the plaintext.
  • Cause missing documentation only.
  • Prototype none (docs only; a short [example] block in vt_otp.man would do it)
  • Suggested action add an example to vt_otp.man, then close
  • Suggested ticket comment Still valid: vt_otp.man has no example. Usage: open the key file twice (one channel for writing, one for reading), tcl::transform::otp $chan $keyw $keyr, then write or fcopy through $chan.
⬜759713c5c42014Tcllib mime package doesn't (document) support for header encodingDOCS / RFE-OPEN (still true: mime::word_encode, word_decode, field_decode are not in mime.man; non-ASCII header values are written raw, not RFC 204…

Open ticket 759713c5c4 · Bug · mime · filed 2014-01-07

Full verdict

DOCS / RFE-OPEN (still true: mime::word_encode, word_decode, field_decode are not in mime.man; non-ASCII header values are written raw, not RFC 2047 encoded)

  • Module mime 1.7.2
  • Tested 9.1/8.6: -header {Subject "Привіт öö"} → raw UTF-8 bytes in the header
  • Cause n/a
  • Prototype none (docs + optional auto-encoding is a design decision)
  • Suggested action document word_encode/word_decode/field_decode in mime.man (they are tested in mime.test, so they are effectively public); auto-encoding could be a separate RFE
  • Suggested ticket comment Still valid: word_encode, word_decode and field_decode are tested but not documented, and headers are not encoded automatically.
⬜3600285fff2013smtpd STARTTLS not documentedpatchDOCS

Open ticket 3600285fff · Bug · smtpd · filed 2013-01-10

Full verdict

DOCS

  • Module smtpd 1.6
  • Tested smtpd.man has no -usetls and none of the tls::import pass-through options (-certfile, -keyfile, ...). The code supports them (configure, STARTTLS).
  • Cause smtpd.man: configure option list
  • Prototype prototypes/3600285fff.patch (41 lines, docs only). Documents -usetls and the tls options. Formats cleanly with doctools. No regression test (documentation change).
  • Suggested action apply prototype
  • Suggested ticket comment Still undocumented. Proposed doc text for -usetls and the tls options in prototypes/3600285fff.patch.
⬜2459470fff2008Debug and Verbose do not generate outputDOCS (works as designed; the manual is misleading)

Open ticket 2459470fff · Bug · ftp · filed 2008-12-22

Full verdict

DOCS (works as designed; the manual is misleading)

  • Module ftp 2.4.14, log 1.5
  • Tested set ftp::VERBOSE 1; set ftp::DEBUG 1 prints nothing by default. After log::lvSuppress debug 0 everything shows, on 9.1 and 8.6.
  • Cause ftp.tcl ::ftp::DisplayMsg logs through log::log debug, and the log package suppresses debug/info/notice/warning by default. The suggested log::lvSuppressLE emergency 0 inside the ftp package would change the logging of the whole application, so it should not be done.
  • Prototype none (doc-only change; no test possible). Suggested ftp.man text after the paragraph about DisplayMsg: "The messages are logged at level debug (errors at level error). The log package suppresses level debug by default, so an application setting VERBOSE or DEBUG also has to call log::lvSuppress debug 0, or use the -output option of ::ftp::Open."
  • Suggested action fix the docs, then close
  • Suggested ticket comment The messages go to the log package at level debug, which is suppressed by default. Enable them with log::lvSuppress debug 0 (or use -output). Changing log's global settings from inside ftp would affect the whole application, so we will document this instead.
⬜2220159fff2008Missing in snitfaq: limitiation on names for optionspatchDOCS (snit.man's option statement already states the rule; snitfaq.man does not)

Open ticket 2220159fff · Bug · snit · filed 2008-11-04

Full verdict

DOCS (snit.man's option statement already states the rule; snitfaq.man does not)

  • Module snit 2.3.4 (snitfaq.man)
  • Tested option transformBefore and option -transformBefore both give badly named option on 9.1 and 8.6. The rule (Comp.OptionNameIsValid: leading hyphen, no upper case, no space) is already covered by tests option-*.
  • Cause snitfaq "How do I define an option?" does not mention the naming rules.
  • Prototype prototypes/2220159fff.patch (27 lines, docs only; it adds a paragraph to the snitfaq "How do I define an option?" section, and the doctools render has no warnings). No new test: the naming rule is already tested (snit.test lines ~2790-2837, "badly named option").
  • Suggested action apply prototype, close as Fixed
  • Suggested ticket comment The rule (leading hyphen, no upper case or spaces; resource/class names may use upper case) is in snit(n) but missing in the FAQ. Proposed FAQ paragraph is ready.
⬜1927092fff2008ncgi documentation - confusing use of term 'session'patchDOCS (still present: two uses of "session" in the reset and urlStub descriptions)

Open ticket 1927092fff · Bug · ncgi · filed 2008-03-27

Full verdict

DOCS (still present: two uses of "session" in the reset and urlStub descriptions)

  • Module ncgi 1.4.6 (ncgi.man)
  • Tested grep of ncgi.man
  • Cause wording
  • Prototype prototypes/1927092fff.patch (2 changed lines, replaces "session" with "request". No test possible for wording.)
  • Suggested action apply prototype, close
  • Suggested ticket comment Replaced "session" with "request" in the reset and urlStub descriptions.
⬜1917018fff2008dns - Package resolv is not documentedDOCS: still no man page and no test suite. Duplicate 1954483fff was closed in favour of this ticket.

Open ticket 1917018fff · Bug · dns · filed 2008-03-17

Full verdict

DOCS: still no man page and no test suite. Duplicate 1954483fff was closed in favour of this ticket.

  • Module resolv 1.0.4 (dns module)
  • Tested grep of all .man files
  • Prototype none (needs a new man page)
  • Suggested action keep open (or decide to deprecate resolv)
  • Suggested ticket comment Still true on trunk: resolv has no man page and no tests.
⬜1917019fff2008dns - Package spf not documentedDOCS: still no man page. spf.test exists now; tcllib_dns.man only links to an SPF website.

Open ticket 1917019fff · Bug · dns · filed 2008-03-17

Full verdict

DOCS: still no man page. spf.test exists now; tcllib_dns.man only links to an SPF website.

  • Module spf 1.1.2 (dns module)
  • Tested grep of all .man files
  • Prototype none (needs a new man page)
  • Suggested action keep open
  • Suggested ticket comment Still undocumented on trunk. A test suite exists now, but no man page.
⬜1646625fff2007doctools - html backend - backslashes wrong in doc examplepatchDOCS (REPRODUCED on 9.1 and 8.6. The doubled backslashes are in the des.man source, not added by doctools. Inside [example {...}] doctools copies…

Open ticket 1646625fff · Bug · doctools · filed 2007-01-28

Full verdict

DOCS (REPRODUCED on 9.1 and 8.6. The doubled backslashes are in the des.man source, not added by doctools. Inside [example {...}] doctools copies backslashes verbatim, so \\0 in the source shows up as \\0 in HTML/markdown/text. That is also wrong Tcl: string repeat \\0 8 is 16 literal characters, not 8 NUL bytes. aes.man has the same error, string repeat \\0 16, and its printed hex result only matches the single-backslash form. I checked: with \\0 the result is fdb1..., with \0 it is 66e94bd4... as documented.)

  • Module des 1.2 (des.man), aes (aes.man). doctools itself is fine.
  • Tested formatted AK's four test cases plus des.man/aes.man to html/nroff on 9.1 and 8.6. Ran the aes example both ways.
  • Cause modules/des/des.man:175-176 and modules/aes/aes.man:140 use \\ inside a braced example. The only doctools special case is a backslash at the end of a line, where \\ gives one \ (AK's continuation-line note). That does not apply here.
  • Prototype prototypes/1646625fff.patch (4 changed lines, docs only. No regression test possible, because the change is only in .man example text. I checked by regenerating the HTML.)
  • Suggested action apply prototype, regenerate embedded docs, close as Fixed
  • Suggested ticket comment The doubled backslashes come from des.man itself: doctools copies the text of [example {...}] verbatim. The example was also wrong as Tcl code. Fixed des.man, and aes.man which had the same mistake.
⬜1608820fff2006Doc update for ncgi - examples neededpatchDOCS (partly done: an "Uploading a file" EXAMPLES section was added in 2007, c33818a4c4, but there is still no basic read-a-form example)

Open ticket 1608820fff · Patch · ncgi · filed 2006-12-04

Full verdict

DOCS (partly done: an "Uploading a file" EXAMPLES section was added in 2007, c33818a4c4, but there is still no basic read-a-form example)

  • Module ncgi 1.4.6 (ncgi.man)
  • Tested ran the new example as a CGI script (QUERY_STRING) on 9.1 and 8.6. sak.tcl doc validate ncgi passes.
  • Cause n/a
  • Prototype prototypes/1608820fff.patch (31 lines, docs only. No regression test possible for a man page example; the example was run by hand instead.)
  • Suggested action apply prototype, then close
  • Suggested ticket comment The man page has an upload example since 2007. A basic parse/value/header example is proposed in addition.
⬜1307714fff2005ftp - NList Documentation problempatchDOCS

Open ticket 1307714fff · Bug · ftp · filed 2005-09-29

Full verdict

DOCS

  • Module ftp 2.4.14 (ftp.man)
  • Tested the ftpd NList examples work. Globbing is done by the server, as with List.
  • Cause ftp.man documents NList handle ?directory?, while List documents ?pattern?
  • Prototype prototypes/1307714fff.patch (6 lines, docs only, so no test possible). It renames the argument to pattern and notes that directory prefixes in the result depend on the server (see 1584235).
  • Suggested action apply prototype, close
  • Suggested ticket comment The argument is passed to the server like List's pattern; the docs now say so.
⬜861622ffff2003Documentation error(s)DOCS (the -part/-parts naming was fixed via 3354014/3552226; there is still no example of building a multipart message, or of naming an attachment …

Open ticket 861622ffff · Bug · mime · filed 2003-12-17

Full verdict

DOCS (the -part/-parts naming was fixed via 3354014/3552226; there is still no example of building a multipart message, or of naming an attachment with Content-Disposition/filename)

  • Module mime 1.7.2 (mime.man)
  • Tested read mime.man
  • Cause n/a
  • Prototype none (docs only; Pat's 2006 comment has a ready example for the EXAMPLES section)
  • Suggested action add Pat's multipart/mixed + attachment example to mime.man, then close
  • Suggested ticket comment -parts is documented now. An example of a multipart message with a named attachment, like the one in the 2006 comment, is still missing from the manual.