On Thu, 2004-08-12 at 23:59 -0700, Nifty Hat Mitch wrote: > 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. But there are now two topics for 'alsactl'- the command and the proposed initscript. Should they be combined? IMO they should not in this case. > 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..... I doubt that 'man' is the place for this, because what non-Unix user knows how to use man (and try explaining man N topic). Ditto for info. IMO if someone is that green to Unix/Linux, then they should get a book and/or a mentor (if they bought a box set, hopefully they get some kind of book). Beyond that, I expect they would use the help system provided by whichever desktop environment they are using, if any. > > 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. > I don't think the multiple languages would be so bad if the default was for man not to return any pages for language functions unless you specifically ask for that section. Users of the language would have to be taught to always look in that section. > > 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... > > I think this sort of information is best handled via the likes of scrollkeeper OMF files. I think man pages should be concise descriptions of individual commands and functions, not thorough documentation for applications. I again refer to the mess that is the bash man page; almost impossible to find what you're looking for in it. -- Aaron Gaudio <prothonotar@xxxxxxxxxxxxxxxxxxxx>
