Tcl Source Code

Here are some undocumented features of zipfs (implementing TIP 430):

1. zipfs mount_data

There is a command zipfs mount_data but it is undocumented. Should it be documented in the manual page?

2. ::tcl::zipfs::tcl_library_init

The C source code defines a ::tcl::zipfs::tcl_library_init procedure that is also undocumented. Should it be documented and what does it do? I guess it is only for internal use.

On the other hand, TIP 430 defines a public subcommand zipfs tcl_library. This command is not implemented but seems to do the same.

3. zip archives attached to tclsh/wish or to libraries

TIP 430 describes what happens when a zip archive is attached/appended to tclsh/wish or to a library file. In this context, it also mentions the specific mount points ZIPFS_ROOT/app and ZIPFS_ROOT/lib/PGKNAME plus some files and directories inside to look for during startup.

This is documented in the tclsh(1) manual page. However, the documentation does not mention the specific mount points. The example at the end of TIP 430 should then also be included in the manual as it clarifies nicely how to exactly use that feature as it is difficult to put in words alone. This could be done in zipfs(n) to not overload the tclsh(1) manual page.

Also, the TIP defines something like tclsh install .... This is not documented in tclsh(1) and I am not sure if this is even implemented.

4. General consistency with TIP 430

In general, the manual page is not consistent with the proposal in the TIP, meaning that zipfs was implemented differently from what the TIP says. Maybe that is OK, I am not sure whether the TIP should always be in line with the implementation, but here are some of the differences:

• zipfs canonical has some options not mentioned in the TIP
• zipfs mount can use a password option not documented in the TIP
• zipfs lmkimg has one optional pair of options (... ?password infile?) while the TIP has them as two separate options (... ?password? ?infile?). This is somewhat related to this ticket

When we refer to the TIP as "further reading" from the manual page, this could at least increase confusion.

As the TIP is now also edited and contains an additional "Amendment" section, this ticket is consequently closed.

The changes are now implemented with commit d97273f74c2dfecc (apart from the TIP amendment)

After discussion with TCT members, the following was agreed:

1. Rename the subcommand to zipfs mountdata and document it in the manual page. The renaming has already been done as of commit 731b44b4c730e74d. (This can be done without a TIP as zipfs mount_data was not part of TIP 430 anyway).

2. Nothing to do, the command is internal and stays undocumented in the manual page

3. The respective manual pages will be clarified. tclsh install ... will not be documented as it is not implemented.

4. An amendment to TIP430 is to be written to clarify which parts of the TIP are actually implemented and which not. A future TIP might then be issued for remaining subcommands etc. that are still missing.

1. When invoking zipfs xxx to provoke an error message about the possible subcommands, zipfs mount_data is also listed. I am not sure whether this already qualifies for the subcommand as candidate for being documented. At least it feels awkward to have a subcommand being listed but not being documented. As for the name, I would propose zipfs mountdata then. We still have the chance to rename it now.

2. OK, I get the point. If zipfs mount_data should stay undocumented, I nearly believe this is for internal use also. Then that one should probably also be moved into the ::tcl::zipfs namespace.

As for the TIP, I guess the process should be to first look at the zipfs source code now in core and make sure the documentation (manual pages zipfs(n) and interp(n)) is in line with the implementation. Then, the TIP should be brought in line with those as well ...