Documentation of services

[Aaron Gaudio]

On Thu, 2004-08-12 at 11:53 -0700, Kevin Wang wrote:
> 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.

I don't know if I would call info "new-fangled" as it has been used for
emacs documentation for a long time, as well as most other GNU
utilities, especially gcc. While I don't find the curses interface to
info very user-friendly, I did like the gnome-help front-end's
capability to read info (which has since been removed, apparently). Info
pages for commands like gcc tend to be much more comprehensive than you
would find (or want) in a man page. Try browsing the bash man page to
find out using the test builtin and you'll see what I mean.

I agree that a program which has an initscript associated with it should
list that under the files section of a man page. Then, a whatis
(apropos, man -k, whatever) search would locate references to that
initscript. However, what the initscript does versus what the command
associated with it does may not have a 1:1 correlation with each other.