On Fri, 2004-08-13 at 01:38 +0100, James Wilkinson wrote:
Aaron Gaudio wrote:
> Unfortunately, if you call the init script 'alsactl' and expect to be
> able to find a man page on the init script by typing 'man alsactl' you
> will be sorely disappointed.
I'd better clarify this.
man alsactl shows what the alsactl command can do, and (by extension)
what the service might expect it to do. "Description: alsactl is used to
control advanced settings for the ALSA soundcard drivers" isn't so bad:
it's a good deal better than just calling the service "alsa"...
It is bad IMO because it is misleading. If I see an initscript called
"alsactl" and run 'man alsactl' and get a valid manpage describing the
usage of the alsactl command, I might get confused and think that is the
usage of alsactl initscript. To think otherwise is to assume I have
knowledge of how initscripts integrate into a Unix system, and once you
assume that, I should have enough knowledge to figure out what the
initscript does (or at least, to figure out how to figure it out)
without having documentation handed to me.
> Now, aside from the aforementioned system-config-services type
of
> contextual documentation, there could be a 'help' argument in addition
> to the standard 'start|stop|restart|reload' commands. Now someone needs
> to only know how to use /sbin/service, which they should already know if
> they plan on starting or stopping the service from a terminal anyway.
The big problem is "how do they find the documentation"?
We really do need a man page for service, which points to other
documentation. But many people (including me) have got used to
/etc/init.d/whatever commands.
Agreed. If /sbin/service (and its derivatives) is what folks are
supposed to use to control services from the command line, then there
ought to be a man page for it. In fact, I'll go so far as saying that I
think the initscripts should all fail if you try to run them directly,
because /sbin/service sets up a more secure environment.
Apart from using Google or reading the shell code, how would *you* go
about finding information about a service?
It depends on the usage scenario in question. In the context of me
trying to figure out how to set up a particular service, I would expect
documentation to be included in the documentation for the package which
provides the service. In a RH system, that usually means grokking the
stuff in /usr/share/doc/[package] (especially the INSTALL file, if any).
This is because I'm coming from the context of "I've just installed this
package and now I want to find out how to get it up and running". I
believe this is probably the most common usage scenario, btw.
On the other hand, if I happen to be doing some generic administrative
browsing of my services, usually I look to see what the script is doing,
since I can understand bash. If that were not the case, however, I would
expect some basic documentation from whatever tool I'm using to
administer the services. If I'm using system-config-services, I expect
to be able to get some documentation there; probably just a short
description giving me enough info to find out the rest (or even better-
pointing me to the resource necessary to find out the rest; or best- a
help link that sends me right to the resource, whatever its format, in
my help browser).
If I'm using /sbin/service, then I think being able to do '/sbin/service
[servicename] help' to get the same info as above would be best. I
wouldn't think offhand to try the man or info pages, as I don't tend to
find initscript information in them (on my workstation, autofs was the
only initscript which has a man page; incidentally it's the only
initscript other than clearcase's that I've had to repeatedly edit to
get to work right [though in FC2 it finally appears to work
correctly]).
--
Aaron Gaudio <prothonotar(a)tarnation.dyndns.org>