Wanted: philosophy behind online manuals.

Wanted: philosophy behind online manuals.

Post by Piet Tutelae » Sun, 01 Apr 1990 21:21:53



On our campus we have a mixture of UNIX equipment: SUNs, VAXes, etc.
All software suppliers have there own ideas (or none because there seems
no uniform view?) about how the manual pages should be organized.
Because these suppliers don't supply the sources of these manual related
commands -- man(1), catman(8), makewhatis (?) -- system administrators
find it difficult, if not impossible, to provide users with a
consistent, fast and reliable online manual service.

In an attempt to get the situation improved, I started with the version
of the sources of man.c and apropos.c as ftp-able from some 4.3 BSD tahoe
servers. This version of man looks for manpages in the default MANPATH
/usr/man:/usr/new/man:/usr/local/man. In each of this directory a search
is started for subdirectories cat<number-or-letter> or
MACHINE/cat<number-or-letter>. The <number-or-letter> is the section
1..8, o (old), n (new) and l (local). Manual pages are expected to have
extension ".0" (don't ask me why).

I have addapted this version to a more SUN-man look alike. So my version
has the following added, and deleted, features:
 - I have ommited the MACHINE-feature (I see no use for it),
 - automatic update feature, the cat<section>/<manual>.<section> file
   will be created if there was none or if the corresponding man-version was
   newer than the cat-file,
 - typeset feature (-t) for our local typesetter.

Although the situation is improved now, it turns out that our manual
pages (and also the manual pages on SUN's!) cann't be located if the
extension (ex.: AllPlanes.3X11) of the manual page is not equal to
the directories (man3 and cat3) in which the manpages are expected.
Thanks to the source of man I can easily make man look for manuals of the
form man3/<manual>.3X11. But I would expect a more elegant way for the
system administrator to add manual subsections (ex: 3X11) to their
system without recompiling the sources.

So if somebody knows the filosophy behind online manuals on UNIX
systems, I would like to hear about it.  Does there exist a document:
``Guidelines for UNIX programmers Writing their own Manual page'' or
something equivalent?

Piet Tutelaers

 
 
 

Wanted: philosophy behind online manuals.

Post by Johan Vroma » Mon, 02 Apr 1990 07:56:25


: On our campus we have a mixture of UNIX equipment: SUNs, VAXes, etc.
: All software suppliers have there own ideas (or none because there seems
: no uniform view?) about how the manual pages should be organized.
: Because these suppliers don't supply the sources of these manual related
: commands -- man(1), catman(8), makewhatis (?) -- system administrators
: find it difficult, if not impossible, to provide users with a
: consistent, fast and reliable online manual service.


implementation of 'man', which has most of the features you're looking
for (and more).

        Johan
--

Multihouse Automatisering bv                   uucp: ..!{uunet,hp4nl}!mh.nl!jv
Doesburgweg 7, 2803 PL Gouda, The Netherlands  phone/fax: +31 1820 62944/62500
------------------------ "Arms are made for hugging" -------------------------

 
 
 

Wanted: philosophy behind online manuals.

Post by Tom Christians » Tue, 03 Apr 1990 00:40:22


It was for all these reasons that I rewrote man and makewhatis.
Here's an excerpt from my makewhatis(8) man page, stripped of
point and font changes and underlining:

    NAME
         makewhatis - rebuild the whatis database

    SYNOPSIS
         /usr/lib/makewhatis [ -v ] [ -n ] [ -y ] [[ -M ] manpath ]

    DESCRIPTION
         Makewhatis rebuilds the text and dbm(3X) forms of the whatis
         database from the on-line manual pages for a given manpath,
         or from /usr/man if none is supplied.  These files are used
         by the man(1), whatis(1), and apropos(1) programs.
         Makewhatis should be run whenever new man pages are added so
         these programs can find them.

         Each component of the colon-delimited manpath is interpreted
         to be the root of a new tree containing directories of the
         form man*, within which are unformatted man pages of the
         form *.*.  A separate whatis file and corresponding dbm
         files, whatis.pag and whatis.dir, will be placed at the root
         of that man tree.  Files or directories ending in tilda (~)
         or in .bak or .old (in either case) will be skipped, as will
         a section named man0, should such exist.

         In general, files in section manX should end in .X*, where X
         is a section of the manual like 1 or 3x11.  This means it's
         ok to put things ending in 1c in man1, but not things ending
         in 3s.  Any man page whose name doesn't match these criteria
         will generate an warning, but will be processed anyway.  The
         exception to this is the mano subdirectory, which has tradi-
         tionally been the receptacle of all obsoleted man pages
         irrespective of their file extension.  A better way to do
         that would be to have an entire man tree dedicated to this,
         as in /usr/old/man/.

         Multiple entries occurring in the NAME section or as links
         (hard, soft, or via .so inclusion) will all be stored under
         the same man page name.  This method can save significant
         amounts of disk space because it guarantees that only one
         cat page need be generated, regardless of how many ways you
         can get at the corresponding man page. Maintaining aliases
         as links or via a one-line file that .so's the real man
         page, once the only way to do this, is still supported
         although no longer required; mere inclusion in the NAME sec-
         tion is sufficient.

         Embedded point and font changes will be removed from the
         output, and troff string macros for hyphens and underscores
         will be translated into their corresponding ASCII represen-
         tations.  In general, all that can be done will be done to
         produce nicely readable output for whatis(1).

The man program includes per-user customization of the $MANPATH and
also of $MANSECTS for section and subsection search order: I prefer
"23816457"; Fortran programmers like "1:3f:2:3".  

My version of man also supports Sun-style significant comments
indicating eqn or tbl filters, typesetter and previewer support, local
man page, per-tree man macro sets, alternative MACHINE support
(ucbman's /usr/man/${MACHINE}/ stuff), $PAGER support, support for
compressed man pages either of the form manX.Z/cmd.X or manX/cmd.X.Z,
the -w flag for finding whence your man pages are coming and in what
order (e.g. man -w stty), and a -l flag for man-style processing of
a local file.

You'll be able to do 'man XTimeCoord' and get the XSendEvent(3x11) man
page without generating a whole new cat page due to NAME cross-referencing.

My version is also usually a lot faster than ucbman because of the
(n)dbm files.  It's written in perl.  If you don't have ndbm support,
then you probably don't want it.

Available upon request, if and only if you send me an address to
which I can easily reply.

--tom
--

    Tom Christiansen                       {uunet,uiucdcs,sun}!convex!tchrist

                 "EMACS belongs in <sys/errno.h>: Editor too big!"

 
 
 

1. emacs + online manual + Init File

The FAQ advised me to read Init File found in the online manual. I am
now an expert with info :) but I still can't find Init File. Can anyone
provide me with a tree or path through the various menus as I have used
up my inspiration quota for tonight. Thanks.

2. OOPS with 2.4.2-ac2

3. Online Admin Guide/Manual ???

4. Pb:Des liens interactifs

5. Online manuals for UNIX progamming

6. Zdnet on Linux / Be - todays story

7. Online linux manual??

8. Thinking Alpha ....any INfo?

9. Online manual pages

10. Need help navigating SCO OSE 5 online manuals

11. On-line manuals

12. Motif Programming Manual reprinted and online as HTML