On Thu, 12 Aug 2004 00:34:46 +0100, James Wilkinson <james@xxxxxxxxxxxxxxxxxxx> wrote: > Kevin Wang wrote: > > You really want to leave service names the same. don't change them > > gratuitously. It confuses users. > > Now that's an old argument (and I realise that means both sides have > an honourable history). I didn't say it should be changed to something better. I just argue that 'alsa' to 'alsactl' is not an improvement over what we have today. > > Secondly, 'alsa' is the correct name. it names the general service. > > Just because it happens to call ONE program called alsactl doesn't > > mean the whole script should be called that. > > If the alsa script in /etc/init.d was responsible for the whole ALSA > sound system, then yes, you would be correct. But it isn't. It only > looks after one part of ALSA: setting the sound levels. It would be > annoying to have to reset them each time, but it's not essential. > Since the /etc/init.d/alsa script *isn't* responsible for the whole of > ALSA, it should be given a name that better reflects what it does, and > that can be found in the manual pages. Just because it only does alsactl today doesn't mean that it won't do more in the future. > > Compare to more > > complicated services like 'ntpd' - it can call ntpdate before it calls > > ntpd. what would you call the script then? > > Another bad example, I'm afraid ;-) realistically, though, I see ntpdate the binary going away, replaced with a script for compatability purposes. ntpdate is just *easy* and better than making people learn "ntp -q -x -oiburst ntp1.mainecoon.com" or whatever the equivalent cmd line is. 'ntpdate' as a command is extremely useful. as a separate binary, probably not. > But I think this is where we started. These services *need* > documentation: what they are, what they run, how they work, who should > run them, and why. And it's the complex services that need it most. > > But where proper naming of the services can point people to the right > documentation quickly, that is the easiest and probably the best way to > do it. (GNU/Linux has *enough* formats for documentation, and *enough* > places where the Right Answer might be lurking. It's not normally a > good thing to spread chunks of wisdom as far as possible...) > > So what's the best way to document these services? We've had suggestions > of man pages: what else, besides third party web sites, is reasonable? architecturally, the init scripts with chkconfig make good sense. They're modular, and you have the ability to restart an individual service on demand. the problem is that they were originally designed to provide individual daemons, not generalized services. To fix this problem is an architectural problem, not a documentation problem. realistically, the scripts can be reworked to be more service oriented (/etc/init.d/smb starts smbd and nmbd). This will lead to new problems. For example, today, if you restart portmap, you need to restart everything else that depends on it: nfs for example. But restarting nfs doesn't imply restarting portmap. But the way that fedora/redhat is setup today, restarting portmap by itself will cause all other functions that depend on it to "cease to exist". It's undocumented, and terribly confusing. First thing I'd do is fix the init scripts so that they have appropriate comments in the top. the redhat 'chkconfig' requires that there be a 'description' field at the top. Most of them are pretty useless. Self documenting scripts would be the best. maybe add a 'help' command in addition to the 'start|stop|status|restart' commands. at least add "see also...man pages: nfsd, portmap, etc" to the description. But to answer the bigger question of how do we link the general idea of a service to the high level documentation? that's much more difficult. Linking a "service startup script" to man pages is easy, to help the user find out what config files to edit and what command line flags mean. However, to link them to the "What is Samba" web page is a much different problem. For obviously self-contained projects like samba it's easy. point to http://www.samba.org/ or the equivalent top level html documentation that's presumably somewhere in /usr/share (unfortunately, documentation on disk varies widely with distribution!). For this I really have no good answer. Having a better description of the service would help greatly. Unfortunately, most init scripts are distribution specific, due to paths and other issues. This train of thought highlights a more general problem - that distributions are different from each other - which would seem to be an intractable problem. Summary: imho separate is never equal. self documenting is the way to go. - Kevin
