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.
