Documentation of services

[Kevin Wang]

On Thu, 12 Aug 2004 15:24:31 -0400, Aaron Gaudio
<prothonotar at tarnation.dyndns.org> wrote:
> [ info ]

Not going to argue, it's more religious than anything else.  kinda
like vi/emacs.  just venting, really.

You're right that documentation on how to use emacs doesn't belong in
a man page.  I suppose my real gripe is apps that put everything in
info, including command line usage. makes it harder to find things.  a
little more on this below...

> 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.

But there's the crux of the problem.  

because there's an init script does not mean that you should link to
the commands.  that may be completely irrelevant.  What you need to
link to are "how to configure service $THING".  Take for example ntp. 
There are two different things that need configuring: 1- at boot time,
what server should I set my time to (regardless what my local clock
says) and 2- what ntp time servers should I point to for fine grained
time control plus continuous time tuning.

The man page isn't going to tell you anything about #1, because it's
distribution specific.  The man page will tell you WHAT to do in #2,
but not always where, because file locations are distribution
specific.

FYI, the answer for #1 are to "add names of ntp servers into
/etc/ntp/step-tickers" and #2 is to edit ntp.conf - add server lines
and restrict lines as per the man page, but it's typically not that
easy because the man page doesn't really include any real good
diagnostic isntructions.  I remember the first time I did this I did
the first part (add server lines) but not the restrict lines, so that
my machine was asking for time, and was getting that info, but was
refusing to let that server adjust my time locally.  so ntp might as
well have not been running due to the default security settings being
so restrictive.  One could argue that the config file needs help, but
that's a separate issue.

Same goes for "overall larger apps" like kde, gnome, or emacs for that
matter.  man page should tell you about command line and config files,
not necessarily how to reformat a paragraph.

   - Kevin