Re: Documentation suggestion (was Re: Slink upgrade and xwindows)
> > I have to admit, there is a bit of truth to this, alot of people just don't
> > have the time to read 18 different documents in 18 different locations. Man
> > pages, info pages, FAQs, HOWTOs, mini-HOWTOs, READMEs, INSTALL docs, package
> > descriptions... it is a bit daunting. I do feel that anyone installing
> > anything shoud be up for some reading, but just how much reading is the
> > question. I'm not even going to think about complaining about the amount of
> > documentation, coming from systems that have zip, I know from experience how
> > helpful good documentation can be. But I wonder if maybe there is a better
> > way to organize the volumunous information given to us in a standard, easy to
> > use, heirarchial fashion.
> >
>
> What about this: for a start make sure that every package has a file
> in /usr/doc/<package name> that points to the available documentation,
> like
>
> * manual page blurp.1: short overview of command line options
> * info blurp.info.gz: extensive discussion of all options, and some
> examples
> * http://www.blurp.org: web site dedicated to blurp
> * see also the blurp-doc package
>
> In a similar vain it would be very helpful to have a file that lists
> configuration files that have an impact on the package, like this.
>
> /etc/conf.blurp
> /var/lib/blurp/blurp.history
>
> HTH,
> Eric Meijer
This would be wonderful!!! Only one single point from where to search for
documentation. If you ever executed a command like
find /usr -type f|xargs egrep -li 'proxy|squid'
then you know, that a central point for documentation would be a great time saver.
But when talking about documentation, I must talk about man pages. Every (I really
mean every) executable should have an up to date and complete man page. Unfortunately
the gnu folks stick to info files. Info files tend to be lengthy and tedious, but most
time I only need a comprehensive description of the command and its options. That's
what a man page should be. Therefore I am a strong advocate of man pages, which ideally
should have the following structure (sections in brackets [] are optional):
Name:
The name of the command.
Synopsis:
Syntax of the command.
Description:
Short, but complete description of what the command does.
Options:
List of all options and description of how they alter the
behaviour of the command.
[Exit Status]:
Sic
[X-Resources]:
For X programs the list of X resources with description which are meant
for user customization.
[Environment]:
List and description of environment variables, which are affected or which
affect the command execution.
Examples:
List of a few examples showing the typical use of the command.
Files:
List of files which are in tight relation to the command, i.e. full
path of the command and full path of configuration-, log-, etc files.
See Also:
List of related man pages.
[Bugs]:
List of known bugs.
Version:
Version number of the command with date of release.
Authors:
List of authors together with email addresses and/or web pages
Of course this is not the last word spoken on what a man page should look like,
but it might be a good starting point.
Olaf Rogalsky
\\|//
(. .)
+-----------------------------oOOo-(_)-oOOo----------------------------+
I Dipl. Phys. Olaf Rogalsky Institut f. Theo. Physik I I
I Tel.: 09131 8528440 Univ. Erlangen-Nuernberg I
I Fax.: 09131 8528444 Staudtstrasse 7 B3 I
I rogalsky@theorie1.physik.uni-erlangen.de D-91058 Erlangen I
+----------------------------------------------------------------------+
Reply to: