Re: Documentation of services

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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



[Index of Archives]     [Current Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Yosemite News]     [Yosemite Photos]     [KDE Users]     [Fedora Tools]     [Fedora Docs]

  Powered by Linux