|
Home > Archive > Unix questions > January 2007 > [Proposal]Add a 'typical usage' section to man pages
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
[Proposal]Add a 'typical usage' section to man pages
|
|
| A. Z. Rick 2006-02-26, 10:17 am |
| Hi, all
The Manpages is the de facto standard way to get info about
commands and other things. It often helps, but it also has some weak
point. A typical man page can be long, more than 300 lines, and cover
many aspects of the commands(or other things). But the user often
need only the info to write a command line for typical usage. It is a
pain in the XXX to scan nnn line man page to write only one command
line. And such pain happens again and again...
Let us add a 'typical usage' section to man pages. In this 'typical usage'
section, we will put the command lines for most typical usage and their
short explanations in it. A search engine may help us judge which usage
is the 'most typical usage'.
Any comments?
| |
| Howard S Shubs 2006-02-26, 10:17 am |
| In article <dtlvfl$jj9$1@news.cn99.com>,
"A. Z. Rick" <azrick2@gmail.com> wrote:
> Any comments?
So, you want to make MAN pages even longer?
--
We are the music makers, And we are the dreamers of dreams,
Wandering by lone sea-breakers, And sitting by desolate streams.
from "Ode", Arthur O'Shaughnessy
| |
| Jordan Abel 2006-02-26, 10:17 am |
| On 2006-02-24, Howard S Shubs <howard@shubs.net> wrote:
> In article <dtlvfl$jj9$1@news.cn99.com>,
> "A. Z. Rick" <azrick2@gmail.com> wrote:
>
>
> So, you want to make MAN pages even longer?
Eh - for someone completely new, something along the lines of
TYPICAL USAGE
ls
list files in the current directory
ls -l
long-format listing
ls *.[ch]
list files ending .c and .h -- see also 'Pathname Expansion' in sh(1)
ls -d */
list only directories
ls -ad .*
list hidden files.
echo ejvyz
list the five lowercase letters that are not valid options to
the BSD version of ls.
would be nice.
| |
| Moe Trin 2006-02-26, 10:17 am |
| On Fri, 24 Feb 2006, in the Usenet newsgroup comp.unix.questions, in article
<dtlvfl$jj9$1@news.cn99.com>, A. Z. Rick wrote:
>The Manpages is the de facto standard way to get info about
>commands and other things. It often helps, but it also has some weak
>point. A typical man page can be long, more than 300 lines, and cover
>many aspects of the commands(or other things). But the user often
>need only the info to write a command line for typical usage.
Your $PAGER doesn't have a search function?
http://www.ora.com/
I suspect you might be looking for 'Unix in a Nutshell" Fourth Edition,
October 2005, ISBN: 0-596-10029-9, 906 pages, US$34.95.
>Let us add a 'typical usage' section to man pages. In this 'typical usage'
>section, we will put the command lines for most typical usage and their
>short explanations in it.
At the web site above, you can view sections of the book. It's basically
what you'd want. They also have similar books for SCO UNIX, Linux, and BSD.
Old guy
| |
|
| Begin <slrndvum95.1ig6.random832@random.yi.org>
On 2006-02-24, Jordan Abel <random832@gmail.com> wrote:
> On 2006-02-24, Howard S Shubs <howard@shubs.net> wrote:
>
> Eh - for someone completely new, something along the lines of
[snip]
Won't help. You're confusing the reference manual with a cheatsheet,
and you're assuming a cheatsheet is a good substitute for a working
knowledge, usually instilled through introductory book and/or course.
For one, the completely new person won't know that man(1) gives in fact
access to _The Online Reference Manual_, creating a nice catch 22. You
might say this particular is easily overcome, but that still won't
fix the larger problem. Cheatsheets are no substitute for a working
knowledge.
A smart person with a little knowledge is regarded as ``dangerous'', and
rightly so. Unix does not have safeguards to prevent such a person from
doing serious damage. Trying that is a losing battle and on top of that,
likely^Wproven to get in the way of getting real work done.
Let's face it: unix isn't droolproof. It doesn't claim to be, and isn't
intended to be, either. If it is, it isn't unix anymore. It's not sold
as windowdressing, but it is a *tool*. If you want to use the tool
effectively, you have no option but to learn how to use it.
If you don't believe me, consider the following:
http://steve-parker.org/articles/ot.../holehawg.shtml
You can't hope to control that kind of power with mere handwaving. Like
how in Hollywood any visiting space alien or time transported medieval
peasant not only knows how to drive a car but also knows the rules of
the road, and all that without any previous experience at all, expecting
that simply isn't realistic. And lo and behold, this is exemplified by
the trouble people have to use the systems that are supposed to work
that way, in the real world. In short, your suggestion might look smart,
but it really isn't.
If it actually had merit, it's likely someone would have thought of
it, and implemented it, somewhere along the 30-odd years that unix has
been around. If that had proven satisfactory, then it'd've spread. Even
on a commercial system, the act of adding a couple of manpages is not
particularly hard. Doing it, however, will likely not contribute to the
number of people that know their stuff, and as such degrade the overall
quality of the userbase, causing more grief for the people that have
to support it. This is much the same mechanism as to why knowledgeable
people don't do others' homework for them.
Despite popular belief instilled by proponents of systems that *are*
sold as window dressing, --and in fact don't come with any usable manual
at all, causing a large 3rd party market for ``for dummies'' books--
to make effective use of unix, you need to know your stuff. You simply
can't get by on cheatsheets and handwaving. This, as they say, isn't a
bug, but a feature.
--
j p d (at) d s b (dot) t u d e l f t (dot) n l .
This message was originally posted on Usenet in plain text.
Any other representation, additions, or changes do not have my
consent and may be a violation of international copyright law.
| |
| Warren Block 2006-02-26, 10:17 am |
| Jordan Abel <random832@gmail.com> wrote:
> On 2006-02-24, Howard S Shubs <howard@shubs.net> wrote:
>
> Eh - for someone completely new, something along the lines of
>
> TYPICAL USAGE
> ls
> list files in the current directory
> ls -l
> long-format listing
> ls *.[ch]
> list files ending .c and .h -- see also 'Pathname Expansion' in sh(1)
Many FreeBSD manpages already have EXAMPLES sections (not ls, though).
From dd(1):
EXAMPLES
Check that a disk drive contains no bad blocks:
dd if=/dev/ad0 of=/dev/null bs=1m
--
Warren Block * Rapid City, South Dakota * USA
| |
| Ángel 2006-02-26, 10:17 am |
| A. Z. Rick <azrick2@gmail.com> wrote:
> Let us add a 'typical usage' section to man pages. In this 'typical usage'
> section, we will put the command lines for most typical usage and their
> short explanations in it. A search engine may help us judge which usage
> is the 'most typical usage'.
>
> Any comments?
That's exactly what the EXAMPLES section is.
--
Saludos,
Ángel
| |
| Alan Connor 2006-02-26, 8:48 pm |
| On comp.unix.questions, in <dtlvfl$jj9$1@news.cn99.com>, "A. Z. Rick" wrote:
> Path: newsspool2.news.pas.earthlink.net!stamper.news.pas.earthlink.net!elnk-nf2-pas!newsfeed.earthlink.net!newshub.sdsu.edu!newsfeed.media.kyoto-u.ac.jp!news.cn99.com!not-for-mail
> From: "A. Z. Rick" <azrick2@gmail.com>
> Newsgroups: comp.unix.questions,comp.unix.user-friendly
> Subject: [Proposal]Add a 'typical usage' section to man pages
> Followup-To: comp.unix.questions
> Date: Fri, 24 Feb 2006 11:22:16 +0800
> Organization: Bentium Ltd. (CN99)
> Lines: 17
> Message-ID: <dtlvfl$jj9$1@news.cn99.com>
> NNTP-Posting-Host: 221.232.28.183
> Mime-Version: 1.0
> Content-Type: text/plain; charset=us-ascii
> Content-Transfer-Encoding: 7Bit
> X-Trace: news.cn99.com 1140752693 20073 221.232.28.183 (24 Feb 2006 03:44:53 GMT)
> X-Complaints-To: usenet@news.cn99.com
> NNTP-Posting-Date: Fri, 24 Feb 2006 03:44:53 +0000 (UTC)
> User-Agent: KNode/0.8.1
> Xref: news.earthlink.net comp.unix.questions:126789 comp.unix.user-friendly:4712
> X-Received-Date: Thu, 23 Feb 2006 19:20:26 PST (newsspool2.news.pas.earthlink.net)
<article not downloaded>
http://groups.google.com/advanced_group_search
A. Z. Rick
Results 1 - 2 of 2 posts in the last year
1 comp.unix.questions
1 misc.test
So you know enough to use a test group and a real newsreader and
have experience with nix and have an anonymous gmail address but
you've only posted once before on the Usenet?
Troll.
Thou Shalt Not Assist Trolls.
Killscored.
Alan
--
http://home.earthlink.net/~alanconnor/contact.html
Other URLs of possible interest in my headers.
| |
| Stephane Chazelas 2006-02-27, 7:50 am |
| On 24 Feb 2006 19:03:26 GMT, Jordan Abel wrote:
[...]
> TYPICAL USAGE
> ls
> list files in the current directory
> ls -l
> long-format listing
> ls *.[ch]
> list files ending .c and .h -- see also 'Pathname Expansion' in sh(1)
Several problems in that. It would make people think that it's
ls that produces the list. It's not, it's the shell, ls does
nothing but to print them in a nice columned way (and resort a
list the the shell already sorted). You could have used printf
'%s\n' instead.
Also,
you need
ls -d -- *.[ch]
> ls -d */
> list only directories
That will be very confusing again. The "/" is for the shell
again, and not every shell will recognise that. That is not
POSIX conformant.
> ls -ad .*
> list hidden files.
Again, -a doesn't make any difference here.
You should definitely not use shell globbing in the examples, or
only in one of them to clarify the fact that the shell expands
the wildcards, not ls nor any other command.
> echo ejvyz
> list the five lowercase letters that are not valid options to
> the BSD version of ls.
>
> would be nice.
--
Stephane
| |
| Chuck Dillon 2006-02-27, 8:48 pm |
| A. Z. Rick wrote:
> Hi, all
>
> Let us add a 'typical usage' section to man pages. In this 'typical usage'
> section, we will put the command lines for most typical usage and their
> short explanations in it. A search engine may help us judge which usage
> is the 'most typical usage'.
>
I'm guessing you are using Linux and not UNIX. On a UNIX system the
man pages include examples for the most part. However, as is always
the case with such things when your climbing a learning curve the
examples often seem inadequate.
In the Linux world the man pages (at least for every flavor I've used)
are a lot more cryptic. They're arguably inadequate. On a Linux box
try the *info* pages... info grep rather than man grep. Many of the
Linux commands (e.g. stuff from GNU) are documented much better in info
pages. Why that info isn't in the man pages is one of my pet peaves
wrt Linux.
-- ced
--
Chuck Dillon
Senior Software Engineer
NimbleGen Systems Inc.
| |
| Jordan Abel 2006-02-27, 8:48 pm |
| On 2006-02-27, Stephane Chazelas <stephane_chazelas@yahoo.fr> wrote:
> On 24 Feb 2006 19:03:26 GMT, Jordan Abel wrote:
> [...]
>
> Several problems in that. It would make people think that it's
> ls that produces the list. It's not, it's the shell, ls does
> nothing but to print them in a nice columned way (and resort a
> list the the shell already sorted). You could have used printf
> '%s\n' instead.
It refers to the shell manpage. And it _is_ typical usage.
>
> Also,
>
> you need
>
> ls -d -- *.[ch]
that's not typically done, because it's not typical to expect there to
be directories with such names.
>
> That will be very confusing again. The "/" is for the shell
> again, and not every shell will recognise that. That is not
> POSIX conformant.
I'm surprised by that. Are you sure? Anyway, manpages on a system aren't
required to refrain from documenting non-POSIX extensions.
>
> Again, -a doesn't make any difference here.
>
> You should definitely not use shell globbing in the examples, or
> only in one of them to clarify the fact that the shell expands
> the wildcards, not ls nor any other command.
Wildcards are often used with ls.
| |
| Bill Marcum 2006-02-27, 8:48 pm |
| On Mon, 27 Feb 2006 08:39:39 -0600, Chuck Dillon
<spam@nimblegen.com> wrote:
>
> In the Linux world the man pages (at least for every flavor I've used)
> are a lot more cryptic. They're arguably inadequate. On a Linux box
> try the *info* pages... info grep rather than man grep. Many of the
> Linux commands (e.g. stuff from GNU) are documented much better in info
> pages. Why that info isn't in the man pages is one of my pet peaves
> wrt Linux.
>
Like most other things in Linux, the man pages are written by
volunteers, and contributions are welcome.
--
BOFH excuse #115:
your keyboard's space bar is generating spurious keycodes.
| |
| Chris F.A. Johnson 2006-02-27, 8:48 pm |
| On 2006-02-27, Stephane Chazelas wrote:
> On 24 Feb 2006 19:03:26 GMT, Jordan Abel wrote:
> [...]
>
> That will be very confusing again. The "/" is for the shell
> again, and not every shell will recognise that. That is not
> POSIX conformant.
Actually, it is. POSIX requires that a path ending in an slash be
interpreted as if it is followed by a dot. So '*/' is the same as
'*/.', which is also works in a Bourne shell.
--
Chris F.A. Johnson, author | <http://cfaj.freeshell.org>
Shell Scripting Recipes: | My code in this post, if any,
A Problem-Solution Approach | is released under the
2005, Apress | GNU General Public Licence
| |
| Stephane Chazelas 2006-02-27, 8:48 pm |
| On 27 Feb 2006 17:05:57 GMT, Jordan Abel wrote:
[...]
>
> It refers to the shell manpage. And it _is_ typical usage.
But will be confusing. I see too many people that think the
wildcard expansion is done the way microsoft tools do it.
>
> that's not typically done, because it's not typical to expect there to
> be directories with such names.
>
>
> I'm surprised by that. Are you sure? Anyway, manpages on a system aren't
> required to refrain from documenting non-POSIX extensions.
In ls man page I would expect ls features to be documented, not
some hypothetical feature of some hypothetical shell a
hypothetical user might be using.
Typically, I would write it:
ls -ld ./*(/)
(/) is zsh's globbing qualifiers.
Otherwise I would use
cd <Tab>
to see the list of directories I may want to cd to.
>
> Wildcards are often used with ls.
I can see your point, but I can see the danger of putting it
that way in an example section. If one is going to read only
that section of the man page, he will most certainly have
misconceptions about the whole thing.
--
Stephane
| |
| Jordan Abel 2006-02-27, 8:48 pm |
| On 2006-02-27, Stephane Chazelas <stephane_chazelas@yahoo.fr> wrote:
> On 27 Feb 2006 17:05:57 GMT, Jordan Abel wrote:
> [...]
>
> But will be confusing. I see too many people that think the
> wildcard expansion is done the way microsoft tools do it.
>
>
> In ls man page I would expect ls features to be documented, not
> some hypothetical feature of some hypothetical shell a
> hypothetical user might be using.
It's not a hypothetical shell, it's /bin/sh. Any user using a different
shell probably knows their shell's features anyway. (Or are you assuming
the unusual case where the shell is not from the same source as the ls
command?)
>
> I can see your point, but I can see the danger of putting it
> that way in an example section. If one is going to read only
> that section of the man page, he will most certainly have
> misconceptions about the whole thing.
My example _does_ refer to the sh manpage.
| |
| Sven Mascheck 2006-02-27, 8:48 pm |
| Jordan Abel wrote:
> [ ls -d */ list only directories ]
> It's not a hypothetical shell, it's /bin/sh.
$ /bin/sh -c 'cd /; ls */; uname -sr'
*/: No such file or directory
SunOS 5.9
> Any user using a different shell probably knows
> their shell's features anyway.
You want examples in ls(1) but require the above knowledge about sh(1)?
(I'm not arguing against examples, but they have to be thought over.)
| |
| Jordan Abel 2006-02-27, 8:48 pm |
| On 2006-02-28, Sven Mascheck <cus.e.mascheck@spamgourmet.com> wrote:
> Jordan Abel wrote:
>
I'll add to that it's _my_ /bin/sh. The /bin/sh on the hypothetical
system on which the hypothetical ls.1 also exists. On most systems, sh
and ls come from the same "vendor". Your manpage can have different
examples.
[vbcol=seagreen]
> $ /bin/sh -c 'cd /; ls */; uname -sr'
> */: No such file or directory
> SunOS 5.9
>
>
> You want examples in ls(1) but require the above knowledge about sh(1)?
I meant if they're using a shell other than sh(1). Use of /bin/sh can
reasonably be safely assumed throughout system manpages, since users
using other shells should know how their shells differ.
> (I'm not arguing against examples, but they have to be thought over.)
| |
| Stephane CHAZELAS 2006-02-28, 7:51 am |
| 2006-02-27, 13:21(-05), Chris F.A. Johnson:
> On 2006-02-27, Stephane Chazelas wrote:
>
> Actually, it is. POSIX requires that a path ending in an slash be
> interpreted as if it is followed by a dot. So '*/' is the same as
> '*/.', which is also works in a Bourne shell.
[...]
Thanks for pointing that out.
SUSv3> In the case of symbolic links, IEEE Std 1003.1-2001 states
SUSv3> that a trailing slash is considered to be the final
SUSv3> component of a pathname rather than the pathname component
SUSv3> that preceded it. This is the behavior of historical
SUSv3> implementations. For example, for /a/b and /a/b/, if /a/b
SUSv3> is a symbolic link to a directory, then /a/b refers to the
SUSv3> symbolic link, and /a/b/ is the same as /a/b/., which is
SUSv3> the directory to which the symbolic link points.
Note that I understand it as that lstat() on such a file should
return information on the target if the file is a symlink.
That does not necessarily apply to globbing even if it would
make sense.
In */foo
The shell looks for a file called "foo" in all the
subdirectories. So in */, the shell would have to look for a
file called "" in all the subdirectories unless it treats */
specially. I don't think that's covered by that SUSv3 exceirpt
above. Anyway, I think most existing POSIX shells recognize it.
What should noted, as well is that
zsh's *(/) does return the directories (the non-dot ones)
while */ returns the directories and the symlinks to
directories.
In zsh, you'd need *(-/) to also get the symlinks to directories
(or */, though */ appends a "/" to the file names).
--
Stéphane
| |
| Sven Mascheck 2006-02-28, 7:51 am |
| Chris F.A. Johnson wrote:
> POSIX requires that a path ending in an slash be interpreted as if
> it is followed by a dot. So '*/' is the same as '*/.', which is also
> works in a Bourne shell.
(BTW: The last sentence is a bit ambiguous:
Bourne shells accept '*/.' but i don't know any variant,
except OSF1 sh, which handles '*/')
| |
| Geoff Clare 2006-03-03, 6:42 pm |
| "Chris F.A. Johnson" <cfajohnson@gmail.com> wrote, on Mon, 27 Feb 2006:
> On 2006-02-27, Stephane Chazelas wrote:
>
> Actually, it is. POSIX requires that a path ending in an slash be
> interpreted as if it is followed by a dot. So '*/' is the same as
> '*/.', which is also works in a Bourne shell.
No. You are taking a part of POSIX that has a very specific narrow
context and trying to apply it to a much wider context. The "as if
it is followed by a dot" thing is part of the pathname resolution
algorithm, which is POSIX's formal description of the pathname-to-inum
lookup process.
The classic example of mis-applying the "followed by a dot" rule is
to think that if "dir" is an empty directory then rmdir("dir/") has to
behave the same as rmdir("dir/."). In fact rmdir("dir/") is required
to remove the directory "dir" whereas rmdir("dir/.") is required to
fail with EINVAL.
--
Geoff Clare <netnews@gclare.org.uk>
| |
| Stephane Chazelas 2006-03-03, 6:42 pm |
| On Tue, 28 Feb 2006 14:05:45 +0000, Geoff Clare wrote:
[...]
>
> No. You are taking a part of POSIX that has a very specific narrow
> context and trying to apply it to a much wider context. The "as if
> it is followed by a dot" thing is part of the pathname resolution
> algorithm, which is POSIX's formal description of the pathname-to-inum
> lookup process.
>
> The classic example of mis-applying the "followed by a dot" rule is
> to think that if "dir" is an empty directory then rmdir("dir/") has to
> behave the same as rmdir("dir/."). In fact rmdir("dir/") is required
> to remove the directory "dir" whereas rmdir("dir/.") is required to
> fail with EINVAL.
Does that mean that
/some/link -> /some/dir
rmdir("/some/link/") will remove "/some/dir" (and not
/some/link).
On Linux, I get:
rmdir("link/") = -1 ENOTDIR (Not a directory)
Though,
lstat64("link/", {st_mode=S_IFDIR|0755, st_size=4096, ...}) = 0
("link/" is a directory).
--
Stephane
| |
| Geoff Clare 2006-03-03, 6:42 pm |
| Stephane Chazelas <stephane_chazelas@yahoo.fr> wrote, on Tue, 28 Feb 2006:
> On Tue, 28 Feb 2006 14:05:45 +0000, Geoff Clare wrote:
> [...]
>
> Does that mean that
>
> /some/link -> /some/dir
> rmdir("/some/link/") will remove "/some/dir" (and not
> /some/link).
Yes, POSIX requires "/some/dir" to be removed, leaving "/some/link"
as a dangling symlink.
> On Linux, I get:
>
> rmdir("link/") = -1 ENOTDIR (Not a directory)
>
> Though,
>
> lstat64("link/", {st_mode=S_IFDIR|0755, st_size=4096, ...}) = 0
>
> ("link/" is a directory).
I just checked Solaris 10 and HP-UX 11 and they both behave as
per POSIX.
--
Geoff Clare <netnews@gclare.org.uk>
| |
| B1GfOot 2007-01-06, 8:00 pm |
| I think thats a great idea, I for one know that I very quickly skim
through the man pages looking for what I need only to become more
confused as I pick up random bits and pieces from across the document.
Good thinkin mate!
On Fri, 2006-02-24 at 11:22 +0800, A. Z. Rick wrote:
> Hi, all
>
> The Manpages is the de facto standard way to get info about
> commands and other things. It often helps, but it also has some weak
> point. A typical man page can be long, more than 300 lines, and cover
> many aspects of the commands(or other things). But the user often
> need only the info to write a command line for typical usage. It is a
> pain in the XXX to scan nnn line man page to write only one command
> line. And such pain happens again and again...
>
> Let us add a 'typical usage' section to man pages. In this 'typical usage'
> section, we will put the command lines for most typical usage and their
> short explanations in it. A search engine may help us judge which usage
> is the 'most typical usage'.
>
> Any comments?
>
| |
| Moe Trin 2007-01-06, 8:00 pm |
| On Tue, 02 Jan 2007, in the Usenet newsgroup comp.unix.questions, in article
<1167709257.7850.5.camel@bigfoot.home.net>, B1GfOot wrote:
>On Fri, 2006-02-24 at 11:22 +0800, A. Z. Rick wrote:
Geez, only 41 weeks old. Did you read the rest of the thread?
Look at the configuration file for your man tool, and find out what
you are using for a pager. Often, it has a 'search' function.
[vbcol=seagreen]
[vbcol=seagreen]
>I think thats a great idea, I for one know that I very quickly skim
>through the man pages looking for what I need only to become more
>confused as I pick up random bits and pieces from across the document.
You may find that the O'Reilly "in a Nutshell" book for your O/S is
useful. See the on-line examples for 'Unix in a Nutshell' at
www.ora.com. Personally, I also keep a personal crib-sheet of
command sequences I've found useful.
>Good thinkin mate!
Do you really think the O/P is still reading this group?
Old guy
|
|
|
|
|