On Thu, Aug 12, 2004 at 11:17:43PM -0400, Aaron Gaudio wrote:
> 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.
You will be disappointed, but should you?
In my opinion you should not.
> > 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"...
Hmmmm...
>
> 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.
There is a long list of man pages that you will never read unless know
how to use "man -a something" or "man N something". This is a real
problem but less of a problem than no page at all.
Apropos, man -k and such are a logical expression of the old
permuted index from hard copy days. As for info documents
I see no problem as long as there is a terse man page that
tells me that the real document is in info format. Same for html.
The whole trick to thinking about this is how do we bootstrap the
knowledge that a user must gather to be a productive user of the
system. Today that includes system administration and new users need
to be able to help themselves.....
One thing that I am finding tedious is the tangle that the explosion
of languages adds to things. Example...
$ apropos open | wc -l
315
$ apropos open | grep ^open
open (1) - start a program on a new virtual terminal (VT)
open (2) - open and possibly create a file or device
open (3) - Open a file-based or command pipeline channel
open (3pm) - perl pragma to set default PerlIO layers for input and output
.... snip ...
openvt (1) - start a program on a new virtual terminal (VT)
The current problem is that the point of view for documentation is
often inside knowing the answer looking out when the dominant need is
outside (ignorant not stupid) looking in.
But first things first... We need to have developers write the initial
simple man page.
Eventually confusion introduced by stuff like this needs to be sorted out:
SLALSA [slalsa] (l) - i an itermediate step in solving the least squares problem by computing the SVD of the coefficient matrix in compact form (The singular vectors are computed as products of simple orthorgonal matrices.) [[[ Woof.... all in one breath]]]
AND
alsactl (1) - advanced controls for ALSA soundcard driver
Yet, many users need this class of information first.
"The Advanced Linux Sound Architecture (ALSA) provides audio and
MIDI functionality to the Linux operating system. ALSA has the
following significant features:
1. Efficient support for all types of audio interfaces, from
consumer soundcards to professional multichannel audio interfaces.
2. Fully modularized sound drivers.
3. SMP and thread-safe design.
4. User space library (alsa-lib) to simplify application
programming and provide higher level functionality.
5. Support for the older OSS API, providing binary compatibility
for most OSS programs."
The fun part is that today with CGI, php, perl, HTML and XML we have
tools to address this stuff in ways that will help. I suspect that if
the emacs folks had html and lynx we would not be using info...
--
T o m M i t c h e l l
Just say no to 74LS73 in 2004
