[2000] in Athena Bugs
Re: finding manual pages
daemon@ATHENA.MIT.EDU (Lang Zerner)
Wed Mar 29 14:02:04 1989
To: doc-bugs@ATHENA.MIT.EDU
In-Reply-To: Your message of Wed, 29 Mar 89 12:49:00 -0500.
Reply-To: Lang Zerner <langz@ATHENA.MIT.EDU>
Date: Wed, 29 Mar 89 14:00:56 EST
From: Lang Zerner <langz@ATHENA.MIT.EDU>
> ------- Forwarded Message
> Date: Tue, 22 Nov 88 09:59:41 EST
> this seems correct to me.
> - --dan
> - ------- Forwarded Message
> From: <treese@ATHENA.MIT.EDU>
> Subject: finding manual pages
> Now that xman is available, it seems that we should reorganize the layout of
> the manual directories. The basic problem is that the manual directories are
> currently organized for ease of administration, not for ease of browsing.
> For example, is a command in the New section or Section 1? Why should system
> calls and library functions be distinct?
...
> - ------- End of Forwarded Message
> ------- End of Forwarded Message
Here is an excerpt from the xman(1) man page:
By using the mandesc file a user or system manager is able
to more closely control which manual pages will appear in
each of the sections represented by menu items in the Manual
Sections menu. This functionality is only avaliable on a
section by section basis, and individual manual pages may
not be handled in this manner (Although generous use of sym-
bolic links - ln(1) - will allow almost any configuration
you can imagine). The format of the mandesc file is a char-
acter followed by a label. The character determines which
of the sections will be added under this label. For
instance suppose that you would like to create an extra menu
item that contains all programmer subroutines. This label
should contain all manual pages in both sections two and
three. The mandesc file would look like this.
2Programmer Subroutines
3Programmer Subroutines
This will add a menu item to the Manual Sections menu that
would bring up a listing of all manual pages in sections two
and three of Unix Programmers Manual. Since the label names
are exactly the same they will be added to the same section.
Note, however, that the original sections still exist.
If you want to completely ignore the default sections in a
manual directory the add the line:
no default sections
Anywhere in your mandesc file. This keeps xman from search-
ing the default manual sections In that directory only. As
an example, suppose you want to do the same thing as above,
but you don't think that it is useful to have the System
Calls or Subroutines sections any longer. You would need to
duplicate the default entries, as well as adding your new
one.
no default sections
1User Commands (1)
2Programmer Subroutines
3Programmer Subroutines
4Devices (4)
5File Formats (5)
6Games (6)
7Miscellaneous (7)
8Sys. Administration (8)
lLocal (l)
nNew (n)
oOld (o)
At minimum, all that is neccessary is a two-line mandesc file in /usr/man
combining sections 2 and 3 into one label, and possibly n, l, and 1. At worst
we would have to use a longer, 'no default sections' mandesc file. Since the
URVD is read-only, I can't test this in our /usr/man directory, but in any case
it appears that we can enhance the behavior of xman without undertaking the more
complex (and otherwise unnecessary) project of restructuring the /usr/man tree.
Two cents' worth of related commentary: I agree that some of the topics in (n)
(new) need to be moved into (1) for logical reasons. In particular, the X client
man pages originally did describe "new" programs, but the programs have been moved
from /usr/new into the more "official" /usr/athena directory. Items in /usr/new
are normally pseudo-supported, "enjoy at your own risk" programs; when they
eventually migrate into the stable release, as the X clients have, their man pages
should migrate into the stable sections of the manual (1-8).
Be seeing you...
--Lang Zerner
Internet: langz@athena.mit.edu UUCP: {decvax,mit-eddie}!athena.mit.edu!langz
Witnessed: "...that is the question. Whether 'tis knobblier in the knees..."
