Documentation of services

[Kevin Wang]

On Thu, 12 Aug 2004 13:11:50 +1000, Peter Smith <pasmith at wbmpl.com.au> wrote:
> There must be a man page associated with each package name.
> There should to be a man page associated with each command name.
> Each man page associated with a package should identify all the commands
> in the package ("See Also"), and (my pet gripe for this week) it should
> identify all the files affected by the command ("Files").
> I get annoyed at the way that the "hard bits" are being hidden from the
> tender eyes of the non-coder, a la Windows, especially with respect to
> the GUI interfaces.  And what's with this new-fangled "info" stuff, anyway?
> </rant>  I feel better now..

I agree about info. I don't like it. man pages were the original
standard; why create a separate thing?  Usually I goto the web before
I goto info.  At the very least, have a man page that says "see info".
Not all things do.

But back to the original topic - what do you mean 'package'?  you mean
rpm?  or service?  This is an extremely grey area.

On one end of the spectrum, man pages should indeed have a 1:1
correlation with executables and config files like man syslog.conf.

rpm's have a built-in description mechanism. 'rpm -qi mutt' spits out:
    URL         : http://www.mutt.org/
    Summary     : A text mode mail user agent.
    Description :
    Mutt is a text-mode mail user agent. Mutt supports color, threading,
    arbitrary key remapping, and a lot of customization.

    You should install mutt if you have used it in the past and you prefer
    it, or if you are new to mail programs and have not decided which one
    you are going to use.

Unfortunately, not all are so good:
    URL         : http://sourceforge.net/projects/libusb/
    Summary     : A library which allows userspace access to USB devices.
    Description :
    This package provides a way for applications to access USB devices.

So the descriptions are a general FAQ #1: "What is $THING?"  Including
a url to a more general "project" page.

Here's where things start falling apart.  You have the general idea of
what an app is, but without the url, you have no link into the general
introduction "how do I use $THING?" "what commands start up $THING?"
which might lead one to need man pages for cmd-line flags, but that's
near the end of your trip, not the middle, meaty part.

As I've said before, I'm not good at coming up with the ideas, but I
can certainly point them out clearly 8>  And I'm happy to work with
someone to flesh out ideas.  I can evolve thoughts, but not come up
with them.

   - Kevin