Tcl Library Source Code

View Ticket
Login
Ticket UUID: 564071
Title: doctools - multi-release SYNOPSIS convention
Type: RFE Version: None
Submitter: dgp Created on: 2002-06-03 21:14:34
Subsystem: doctools Assigned To: andreas_kupries
Priority: 5 Medium Severity:
Status: Open Last Modified: 2007-04-05 23:43:33
Resolution: Closed By:
    Closed on:
Description:
When looking for documentation on Unix, one types

man package

and that turns into a search for a file named
"package.n" on the MANPATH, and a formatting and
display of its contents.

When a new release of package is installed, say
version 1.1, where a prior version, say 1.0, is
already installed, the two versions get installed
side by side, but the man page for 1.1 overwrites
the one for 1.0.

For this reason it would be a good convention for
man pages to include documentation for earlier
compatible versions, as well as the latest changes.
I recommended a SYNOPSIS convention like this:

package require foo 1.0
foo::bar x
foo::baz
package require foo 1.1
foo::grok a b c
package require foo 1.2
foo::snafu
foo::bar x ?y z?

Here it is clear what minor release introduced
each (variation of) each command.

If the doctools cannot format such a SYNOPSIS 
convention, I request the new feature that they
be enhanced so they can.