Hi Stuart,
Stuart Cassoff wrote on Sat, Jun 23, 2018 at 08:30:36AM -0400:
> I sometimes wonder if /usr/local/share/doc/tcl8.6/man/
> would be a better place.
That question is part of a bigger picture: logical organization of
manual pages and representating that organization in the file system,
on the command line, and in URIs.
The corpus of all manual pages can be organized on the following
levels:
* Operating system, e.g. OpenBSD, FreeBSD, NetBSD, ...
File system representation: Not needed because on a local
machine, you have only one system installed.
(Uh oh, but we do have the books/man-pages-posix port
using /usr/local/share/doc/posix/man/
but lacking the @mandir annotation.)
Command line representation: Not needed for the same reason.
But note that Eaton man (ca. 1991-1993) and hence the ancient
man-1.6 still used by some Linux systems and the more modern
man-db used by some other Linux systems do have a command
line option to display pages for a foreign operating system
and abuse the -m option for it, even though -m was already
used earlier in 4.3BSD-Reno (1990) in the modern sense now
known in OpenBSD and NetBSD.
I think we should *not* introduce a command line option
for displaying foreign manual pages.
URI representation: /*system*-version/arch/name.section -
that is, using a dedicated family of manpaths.
* Operating system version, e.g. 5.2, 5.3, 5.4, ...
File system representation: Not needed for the same reason.
Command line representation: Not needed for the same reason.
URI representation: /system-*version*/arch/name.section -
that is, using a dedicated manpath.
* Subsystem, e.g. tcl, tk, lowfat, openssl, ...
File system representation:
- in a top-level portdir (seems rather flat):
/usr/local/heirloom-doctools/man/
/usr/local/jdk-1.8.0/man/
/usr/local/jre-1.8.0/man/
/usr/local/mingw32/man/
- below share/portdir (also a bit flat):
/usr/local/share/lowfat/man/
- below lib/portdir (seems somewhat wrong, manuals aren't libs):
/usr/local/lib/eopenssl/man/
/usr/local/lib/erlang16/man/
/usr/local/lib/qt3/man/
/usr/local/lib/tcl/{tcl,tk}8.{5,6}/man/
/usr/local/lib/stk/4.0.11/man/
- totally broken:
/usr/local/man/man3am/ # lang/gawk
- The most logical /usr/local/share/doc/portdir/man/
does not seem to occur except for man-pages-posix;
then again, it is awkwardly long.
This is all seriously inconsistent, part of which can be explained
by the usual upstream inconsistentcy of some ports using a
top-level portdir and some distributing their files logically
across common dirs like lib and share.
Note that man-db represents subsystem names as suffixes to
numerical section numbers, for example 3tcl, 3posix, ...
That is slightly confusing because logically, subsystems form
a higher level of organization than numerical sections; for
example, OpenSSL has pages in sections 1, 3, 5, and 7.
Solaris and illumos also use a wide variety of such suffixes
for similar purposes, basically for both functional and genetic
subsystems.
Then again, it's merely a matter of the order of the two syntax
elements "subsystem name" and "section number", which probably
doesn't matter all that much. So, in order to not invent our
own bikeshed that differs only in colour, maybe we *should* use
paths like
/usr/local/man/man3tcl8.6
/usr/local/man/man3posix
in the future. That does need adjustments in mandoc though to
not search such directories by default - or maybe there even
isn't even anything wrong with searching them by default as
long as the non-suffixed directories are preferred?
Command line representation: Traditionally, subsystems were
supposed to be accessed with man(1) -s just like numerical
sections, but that functionality was never fully implemented
as far as i'm aware, in the sense that the old man.conf(5) only
supported "-s X11", "-s X11R6", and "-s local" by default, which
was almost useless, so support was removed with the new man.conf(5)
format.
If we go for the above subsystem suffix scheme, we get the side
benefit of restoring part of that traditional functionality with
a more useful practical application, namely that "man -s 3tcl8.6"
will just work, and if we want, we can let "man -s tcl8.6" search
all the sections [1-9]tcl8.6, it's quite easy to implement.
URI representation: None so far, and not needed unless we want to
publish ports manual pages on man.openbsd.org.
* Language, e.g. es, ja, pt_BR, zh_CN, ...
File system representation: /usr/local/man/*language*/
Command line representation: Use -m or -M.
Note that man-db inspects $LC_MESSAGES for this purpose, but
that is logically wrong, because even if users want to see
translated messages, that doesn't imply they also want translated
manual pages, which are almost always outdated, buggy, and
incomplete. We should not follow that bad practice - and
besides, we do not support $LC_MESSAGES in the first place.
URI representation: Not needed.
* (Numerical) section.
File system representation: /usr/local/man/man*section*/
Command line representation: -s
URI representation: /system-version/arch/name.*section*
So, what do you think about consistently moving stuff to
/usr/local/man/man*section**suffix*/
and supporting
man -s *section**suffix*
and
man -s *suffix*
in addition to
man -s *section* ?
If so, should the following work out of the box when tcl is installed,
or should they require explicitly specifying -s tcl - i tend to think
they should just work?
man [-k] tclsh
man Tcl_WaitForEvent
man -k WaitForEvent
Yours,
Ingo
