Documentation of services

James Wilkinson james at westexe.demon.co.uk
Wed Aug 11 23:34:46 UTC 2004


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). "We shouldn't change this to something better,
it will adversely affect the existing users." On the one hand, it led
to sendmail being inflicted with the sendmail.cf format, the bogosities
of the Intel x86 range, and much else that is wrong in computing. On
the other hand, yes, significant changes for questionable and/or
theoretical advantages led to "Let's put all the configuration
information in a database" and the Windows Registry.

In this case, I submit that there are enough changes between Fedora
Core releases, and the improvement in documentation is good enough,
that it would be worthwhile.

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

> 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 ;-)

>From man ntpdate:
       Disclaimer:  The  functionality of this program is now available in the
       ntpd  program. See the -q  command line option in the ntpd   -  Network
       Time  Protocol  (NTP) daemon page. After a suitable period of mourning,
       the ntpdate  program is to be retired from this distribution.

So it should all be ntpd anyway...

I see your point. There will be services that start a number of daemons,
and none of them can be considered "primary".

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?

> It's not nearly as simple as you might think.  For example, nfs
> depends on 'portmap'.  imho dependencies like this need to be
> expressed somehow, but the existing infrastructure doesn't do that.

I'm glad we agree!

James.

-- 
E-mail address: james | Never meddle in the affairs of Windows NT. It is
@westexe.demon.co.uk  | slow to boot and quick to crash.





More information about the fedora-list mailing list