Tcl Source Code

View Ticket
Login
Ticket UUID: a127bf6415cbfa420ed96dcb9144ab4263f1e6b
Title: auto_path is documented in two manpages
Type: Bug Created on: 2026-06-04 08:28:54
Submitter: apnadkarni Assigned to: nobody
Subsystem: 38. Init - Library - Autoload Severity: Minor
Priority: 5 Medium Last modified: 2026-06-16 16:38:36
Status: Pending Closed by: nobody
Resolution: Fixed Closed on:
Version:
Description:

The auto_path variable is documented in both library.n and tclvars.n with slightly different (not conflicting) information in each. Should be merged.

Leaving it to Torsten to decide on the best location :-)

User Comments:
tberg added on 2026-06-16 13:33:32:

This cannot be resolved unambiguously as both manual pages mix things. It is not only auto_path but also env(TCLLIBPATH) and env(TCL_LIBRARY) as well as tcl_nonwordchars and tcl_wordchars which are documented in both places.

Judging from the NAME of the manual pages, these are the topics:

  • library.n = standard library of Tcl procedures
  • tclvars.n = variables used by Tcl

So, in an ideal situation, the library page should only document what comes from the Tcl library whereas the tclvars page should take the rest, i.e. what comes from Tcl directly (disregarding the Tcl library).

However, these two cannot be separated. tclInterp.c (core) is setting auto_path under some circumstances as does auto.tcl (library).

So, what is the most natural place? Let's keep it in tclvars.n as it is not solely the Tcl library but also the core that has a role here. Also, tclvars.n is the manual page where auto_path is linked to from the main page "html/TclCmd/index.html".

I have now kept the documentation in tclvars_n and removed the slightly shorter one from library.n. Where auto_path is mentioned in library.n, I have inserted a reference to the tclvars page.

What should we do about the others (env(TCLLIBPATH), env(TCL_LIBRARY), tcl_nonwordchars, tcl_wordchars)? Same procedure as with auto_path?


apnadkarni added on 2026-06-16 16:38:36:

Good catch, did not realize auto_path was not the only duplication.

In the case of env(TCLLIBPATH), I think it can stay in library.n as it is more pertinent there. env itself belongs to tclvars but specific elements may be described where they are relevant. For example env(PATH) may be better described in exec than in tclvars. Ditto for env(TCL_LIBRARY).

For similar reasons, tcl_wordchars and tcl_nonwordchars can stay in the same manpage as the commands to which they apply.

For me, the location of the description is not as important as avoiding duplication so I'm ok with whichever page you think is appropriate.