on Sat, Jul 14, 2001 at 04:41:21AM -0000, john smith (inquirer23@hotmail.com) wrote:
> Hi,
>
> I was just wondering...I don't know if this topic is for this list
> but...is there a book or link somewhere that gives easier examples of
> how to do the correct syntax for "man" something.
I find that the O'Reilly "Nutshell" series, _Linux in a Nutshell_ in
particular, fills this niche nicely. The treatment isn't a raw dump of
man pages, but rather digests much of the information, while *expanding*
the treatment given to examples, particularly to _useful_ examples.
> This probably won't be any problems to you unix gurus out there but if
> I wanted to do something and I do a "man" something, I get arcane (at
> least for me) explanations of how to use different options/parameters
> of that something but not giving me a simple example on how to do the
> command with the options I want correctly and I'd spend a lot of time
> figuring out the correct syntax instead of spending time with
> something else.
There is an art to reading man pages. Usually:
- Name: one line description of command.
- Synopsis: summary of arguments for command.
- Description: more detailed description of command.
- Options: more detailed description of options and arguments.
- Files: files related to command (support, reference, configuration,
etc.).
- See Also: related commands or manual pages.
- Bugs: unusual behavior.
- Author: See also: blame ;-)
There isn't, unfortunately, a standard "Examples" section. There should
be.
> It would certainly be nice for the "man" pages to include a simple
> example of a correct command's syntax and how to add options etc..
> along with the lengthy explanation of all of the available commands
> options. might not be useful to you gurus out there but it certainly
> will help newbies to make the learning curve a little easier?
It certainly would be helpful to see examples with *typical* or *useful*
(but infrequently used) incantations of a command specified. I find I
frequently need to refer to documentation for proper use of tar, cpio,
afio, time (particularly when setting system time), bash, wget, rsync,
nmap, and other commands, many of which I do use frequently. And I'm
not a newcomer to either GNU/Linux or Unix. I don't think it's
necessary (or useful) to give examples for *all* possible combinations
of options, in part as the list would almost certainly get too long and
be of limited utility. But a good 2-6 examples would almost certainly
be helpful.
There's also the issue that there are now several sources for
documentation under GNU/Linux. Some, such as Info, are IMO misguided
attempts to replace the fundamental utility of the man pages (which
actually *are* meant to be a system manual, and in fact replaced the
printed manual of early Unix systems). Others fill different niches and
are themselves useful:
- man pages: basic command reference. Synopsis, arguments,
basic examples, related topics.
- info pages: advanced command and/or feature reference.
Better for describing complex systems such as
emacs, gcc, etc., many of which, for some odd
reason, appear to originate from FSF.
- HOWTOS: task-oriented references. Formally organized by
the LDP (GNU/Linux Documentation Project), these
typically describe how to accomplish some
particular task (configuring your bash prompt,
installing a bootloader, printing, software
RAID, etc.).
- Guides: The classics are the NAG and SAG: _Network
Administrator's Guide_ and _System
Administrator's Guide_, which address the
comprehensive issues of network and system
administration, respectively.
- Debian docs: Of uneven quality, some are golden. The Debian
Policy manual should be required reading. I
should re-read it myself. Poke around the docs
section of debian.org sometime.
- Others: Books are quite useful. I'd recommend a good
system admin book (Nemeth, Frisch), _Running
Linux_ if you're just getting started, and the
aforementioned "Nutshell" book. _UNIX Power
Tools_ is a good cookbook of basic tasks.
Specific references for areas of interest -- DNS,
programming, mailers, etc. -- are also useful.
Don't discount the value of websites, project
pages, other online documentation, and support
lists and newsgroups.
My suggestion would be to notice when you run across a man page that's
noticeably lacking in examples, possible gin up a few yourself, and
submit same as a bug against the appropriate package. Debian *has* been
making a concerted effort to improve the quality of manpages and is
ahead of most other GNU/Linux distros in this regard. Or you could poke
around a *BSD system -- they tend to have well crafted manpages.
Cheers.
--
Karsten M. Self <kmself@ix.netcom.com> http://kmself.home.netcom.com/
What part of "Gestalt" don't you understand? There is no K5 cabal
http://gestalt-system.sourceforge.net/ http://www.kuro5hin.org
Are these opinions my employer's? Hah! I don't believe them myself!
Attachment:
pgp3bLemegAOK.pgp
Description: PGP signature