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@xxxxxxxxxxxxxxxxxxxx>
