Re: man command made easy?
on Sat, Jul 14, 2001 at 04:41:21AM -, john smith ([EMAIL PROTECTED]) 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
Re: man command made easy?
Rebecca Dridan uttered: And for those who, like me, don't like the key bindings in info, check out pinfo, apt-get install pinfo. Thanks, Bec. I don't much like the Info bindings. (Don't like Lynx too much either, but I'd rather learn as few sets of keybindings as possible...) Paul
Re: man command made easy?
On Mon, Jul 16, 2001 at 11:02:31PM -0400, D-Man wrote: [snip] Thanks. Actually, I'm not 100% sure that vim supports backreferences like that (the \1 in the replacement text). I know that Python's and Perl's regex engines do. I think I've heard/read that vim does do backreferences. Yes. [EMAIL PROTECTED]/\(.*\)$@a href=\1\1/a@ Given lines like ./foo/bar/index.html... Or some such... Remeber u to undo... -- Eric G. Miller egm2@jps.net
Re: man command made easy?
[EMAIL PROTECTED] (Joost Kooij) writes: On Mon, Jul 16, 2001 at 10:35:30PM +0200, Leonard Stiles wrote: Even vi is an overkill here, let alone an advanced editor:-) #!/bin/sh Even easier: g install package dwww, point browser to: http://localhost/dwww Pshaw¹! Thats cheating:-) (and you need to install a web server) [1] Is this the correct spelling? -- Leonard Stiles [EMAIL PROTECTED]
Re: man command made easy? -vim
Actually, I'm not 100% sure that vim supports backreferences like that (the \1 in the replacement text). I know that Python's and Perl's regex engines do. I think I've heard/read that vim does do backreferences. Vim does support backreferences, h: regex will give more details.There was a recent talk on e-mail-list(http://groups.yahoo.com/group/vim/message/19141) about the small diferences between perl regex and vim regex. From: D-Man To: debian-user@lists.debian.org CC: Dave Sherohman Subject: Re: man command made easy? Date: Mon, 16 Jul 2001 23:02:31 -0400 On Mon, Jul 16, 2001 at 03:41:01PM -0700, Paul Mackinney wrote: | D-Man uttered: | | [I haven't been following most of this thread, but] | | On Mon, Jul 16, 2001 at 10:59:23AM -0700, Paul Mackinney wrote: | | Night before last I ran 'find /usr/doc -name index.html foo.txt' and | | then spent 2 hours adding links from foo.txt to my local home/start | | 2 hours!? Wow. Learn vi(m) or some other advanced editor. If you | have that foo.txt with each filename on its own line the following | will take very little time to create a web page of links out of it. | | Vim is indeed my editor of choice. The 2 hours was mostly because I got | distracted reading checking out the stuff I found. But my edits Oh, ok. That's better. Two hours reading docs, not two hours creating HTML links. (BTW, thanks guys for those other generation techniques) | weren't nearly as slick as what you suggest. | | Thanks to a conversation at a BAD (Bay Area Debian) meeting last week, I | was clued in to visual mode. Here's what I did: | 1. At the first line, type 'v' to enter visual mode. | 2. Scroll to the last line, type ':' | 3. Vim starts the command text for you. Append | s/^/ DESCR \/a/g | | This turned a line like | /usr/share/doc/apache/manual/mod/index.html | | into | DESCR Yes, visual mode is great when you want to operate on a subset of the buffer. The '%' at the beginning of my command means use the whole buffer. | But your technique for capturing the original line using it for the | link description is very cool will save me much effort for my updates. Thanks. Actually, I'm not 100% sure that vim supports backreferences like that (the \1 in the replacement text). I know that Python's and Perl's regex engines do. I think I've heard/read that vim does do backreferences. BTW, I probably spent more time making my sample commands a little shorter than you spent with your slightly simpler version. Also, the simpler the command is the more likely it is correct ;-). -D -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED] _ Get your FREE download of MSN Explorer at http://explorer.msn.com
Re: man command made easy?
On Sat, Jul 14, 2001 at 10:25:10PM -0500, will trillich wrote: caveat -- if your VCR is still blinking 12:00 then you're not ready for linux... Good thing mine blinks --:-- instead... and sometimes there's no documentation at all... but that's rare. (even the most self-satisfied programmer wants her program to be USED, so she'll likely write up an intro, at the very least.) Then there are those of us who realize that, if we add a neat new feature today, we'll forget about it sometime next week and write docs primarly to remind ourselves of what we've done.
Re: man command made easy?
All that Will said about the man pages is true, and I completely agree about the need for examples; I to have wasted hours fighting syntax errors, all the while with an ugly feeling that I might not even be trying the right command or option. General advice based on things I've done: 1. Use less as you man pager, learn the search tools. 2. Start by searching manpages for 'example'. 3. Use info -- it will run man-pages for programs that don't have info pages, and programs that do have info pages usually have good documentation. 4. Remember to check the HowTos and the contents of /usr/doc/exasperating_command... some of the programs with the worst man pages have excellent manuals. Use zless to read .gz files. 5. Check out the Newbiedoc manual. 6. Invest in some good Linux reference books, I like the Oreilly series a lot. Night before last I ran 'find /usr/doc -name index.html foo.txt' and then spent 2 hours adding links from foo.txt to my local home/start page. I found answers to 3 random trivial questions that have been bugging me; I'll never regret spending the time on this. HTH, Paul
Re: man command made easy?
[I haven't been following most of this thread, but] On Mon, Jul 16, 2001 at 10:59:23AM -0700, Paul Mackinney wrote: | Night before last I ran 'find /usr/doc -name index.html foo.txt' and | then spent 2 hours adding links from foo.txt to my local home/start 2 hours!? Wow. Learn vi(m) or some other advanced editor. If you have that foo.txt with each filename on its own line the following will take very little time to create a web page of links out of it. :%s,^(.*)$,\1\1/abr, :%s,^,a href=file:///usr/doc/, Then insert HTMLBody at the top and /body/html at the bottom. Those vi commands say (1) replace each line with itself followed by '' followed by itself followed by '/abr' It will turn texmf/latex/index.html into texmf/latex/index.htmltexmf/latex/index.html/abr (2) insert the link at the beginning of the line texmf/latex/index.htmltexmf/latex/index.html/abr becomes a href=file:///usr/doc/texmf/latex/index.htmltexmf/latex/index.html/abr Becoming familiar with commands like that (and regexes in general) can really be a time saver. | page. I found answers to 3 random trivial questions that have been | bugging me; I'll never regret spending the time on this. Yeah, it is always good to find info you are interested in in the documentation. It really helps (like learning commands like the above). HTH, -D
Re: man command made easy?
D-Man [EMAIL PROTECTED] writes: [I haven't been following most of this thread, but] On Mon, Jul 16, 2001 at 10:59:23AM -0700, Paul Mackinney wrote: | Night before last I ran 'find /usr/doc -name index.html foo.txt' and | then spent 2 hours adding links from foo.txt to my local home/start 2 hours!? Wow. Learn vi(m) or some other advanced editor. Even vi is an overkill here, let alone an advanced editor:-) #!/bin/sh # as /usr/doc contains lots of symlinks to /usr/share/doc, adding # -follow to find args may be useful. { echo '!DOCTYPE HTML PUBLIC -//W3C//DTD HTML 4.01//EN' echo 'http://www.w3.org/TR/html40/strict.dtd;'; echo 'htmlheadtitleDocumentation Links/title/headbody'; find /usr/doc -name index.html \ -printf 'href=file:%p%P/abr\n'; echo '/body/html'; } links.html -- Leonard Stiles [EMAIL PROTECTED]
Re: man command made easy?
On Mon, Jul 16, 2001 at 10:35:30PM +0200, Leonard Stiles wrote: Even vi is an overkill here, let alone an advanced editor:-) #!/bin/sh [snip] Even easier: g install package dwww, point browser to: http://localhost/dwww Cheers, Joost
Re: man command made easy?
D-Man uttered: [I haven't been following most of this thread, but] On Mon, Jul 16, 2001 at 10:59:23AM -0700, Paul Mackinney wrote: | Night before last I ran 'find /usr/doc -name index.html foo.txt' and | then spent 2 hours adding links from foo.txt to my local home/start 2 hours!? Wow. Learn vi(m) or some other advanced editor. If you have that foo.txt with each filename on its own line the following will take very little time to create a web page of links out of it. Vim is indeed my editor of choice. The 2 hours was mostly because I got distracted reading checking out the stuff I found. But my edits weren't nearly as slick as what you suggest. Thanks to a conversation at a BAD (Bay Area Debian) meeting last week, I was clued in to visual mode. Here's what I did: 1. At the first line, type 'v' to enter visual mode. 2. Scroll to the last line, type ':' 3. Vim starts the command text for you. Append s/^/a href=file:\/\//g enter 4. Repeat the command, this time appending s/$/\ DESCR \/a/g This turned a line like /usr/share/doc/apache/manual/mod/index.html into a href=file:///usr/share/doc/apache/manual/mod/index.html DESCR /a But your technique for capturing the original line using it for the link description is very cool will save me much effort for my updates. Thanks! Paul
Re: man command made easy?
On Mon, Jul 16, 2001 at 10:59:23AM -0700, Paul Mackinney wrote: All that Will said about the man pages is true, and I completely agree about the need for examples; I to have wasted hours fighting syntax errors, all the while with an ugly feeling that I might not even be trying the right command or option. General advice based on things I've done: 1. Use less as you man pager, learn the search tools. 2. Start by searching manpages for 'example'. 3. Use info -- it will run man-pages for programs that don't have info pages, and programs that do have info pages usually have good documentation. And for those who, like me, don't like the key bindings in info, check out pinfo, apt-get install pinfo. Bec
Re: man command made easy?
On Mon, Jul 16, 2001 at 03:41:01PM -0700, Paul Mackinney wrote: | D-Man uttered: | | [I haven't been following most of this thread, but] | | On Mon, Jul 16, 2001 at 10:59:23AM -0700, Paul Mackinney wrote: | | Night before last I ran 'find /usr/doc -name index.html foo.txt' and | | then spent 2 hours adding links from foo.txt to my local home/start | | 2 hours!? Wow. Learn vi(m) or some other advanced editor. If you | have that foo.txt with each filename on its own line the following | will take very little time to create a web page of links out of it. | | Vim is indeed my editor of choice. The 2 hours was mostly because I got | distracted reading checking out the stuff I found. But my edits Oh, ok. That's better. Two hours reading docs, not two hours creating HTML links. (BTW, thanks guys for those other generation techniques) | weren't nearly as slick as what you suggest. | | Thanks to a conversation at a BAD (Bay Area Debian) meeting last week, I | was clued in to visual mode. Here's what I did: | 1. At the first line, type 'v' to enter visual mode. | 2. Scroll to the last line, type ':' | 3. Vim starts the command text for you. Append | s/^/a href=file:\/\//g enter | | 4. Repeat the command, this time appending | s/$/\ DESCR \/a/g | | This turned a line like | /usr/share/doc/apache/manual/mod/index.html | | into | a href=file:///usr/share/doc/apache/manual/mod/index.html DESCR /a Yes, visual mode is great when you want to operate on a subset of the buffer. The '%' at the beginning of my command means use the whole buffer. | But your technique for capturing the original line using it for the | link description is very cool will save me much effort for my updates. Thanks. Actually, I'm not 100% sure that vim supports backreferences like that (the \1 in the replacement text). I know that Python's and Perl's regex engines do. I think I've heard/read that vim does do backreferences. BTW, I probably spent more time making my sample commands a little shorter than you spent with your slightly simpler version. Also, the simpler the command is the more likely it is correct ;-). -D
Re: man command made easy?
john smith 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. 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. 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? well, you might want to get a book or read some unix intro on 'net. man pages are more like a dictionary, not a best book to learn language... some of them have examples at the end... once you get used to unix a bit the man pages are easy to understand... you might also try to file wishlist bugs for the ones that are extra cryptic... erik
Re: man command made easy?
On Sat, Jul 14, 2001 at 04:41:21AM -, john smith wrote: 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. 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. 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? 'nuff said... Hope this helps! Cheers, Joost woman(1)Improvement for manual self-support utilities woman(1) NAME woman - an emotionally responsive system support interface SYNOPSIS (undocumented.) OPTIONS --do-what-I-mean The only option to woman, it is always implicitly enabled. DESCRIPTION Woman is a powerful and highly seductive control application, dressed up as a pretty tool to suit your needs and desires. USAGE The user may start a conversation at any time. If there is a telephone device available, there are no spatial limitations. Instead of boring you with dull technical details, woman will tell you what it feels like and what colour of dress would go best with it. For continued correct functioning, woman needs regular attention and casual gifts. Woman becomes unresponsive when upset for some reason or no reason at all. When this happens, woman returns you know what I mean on all requests, until the mood passes, for some reason or no reason at all. FILES Woman does not keep any files, but remembers everything you type. SEE ALSO girlfriend(6), gifts(5), sex(8), marriage(7), mistress(4) BUGS There are no bugs. Woman meticulously hides all of them. AUTHOR Unknown to man.
Re: man command made easy?
You might want to check out linuxnewbie.org. It has a lot of newbie-oriented howtos. It's not as fine granularity as manpages, but will help with a lot of basic tasks, and has some great forums. I would also suggest the book Linux in a Nutshell from O'Reilly. This is actually very close to what you are looking for from the man pages. Nathan On Saturday 14 July 2001 12:41 am, john smith 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. 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. 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? 'nuff said... _ Get your FREE download of MSN Explorer at http://explorer.msn.com
Re: man command made easy?
On Sat, Jul 14, 2001 at 04:41:21AM -, john smith 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. 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. 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? You're probably looking in the wrong place. Man pages are not meant to be true manuals. As you've noticed, they're typically quite terse and only really useful if you already have some knowledge of the command. You'll find quite quite a bit more information (FAQ's, examples, READMEs) in /usr/share/doc/. -- Brian Nelson [EMAIL PROTECTED]
Re: man command made easy?
On Sat, Jul 14, 2001 at 12:14:30PM +0200, Joost Kooij wrote: FILES Woman does not keep any files, but remembers everything you type. In addition, multiple instances of woman have an extensive shared memory implementation. BUGS There are no bugs. Woman meticulously hides all of them. Even so, unpredictable behavior may occur at any time. This is a feature, not a bug.
Re: man command made easy?
caveat -- if your VCR is still blinking 12:00 then you're not ready for linux... On Sat, Jul 14, 2001 at 04:41:21AM -, john smith 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. 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. 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? as others have said, man shows the reference manual, which is typically a feature-by-feature, option-by-option discussion of what a particular program does, or what a particular config file will accept. you're not likely to glean much on what a particular program is actually FOR, at least not from a manpage. (some include examples, and those help a lot.) and sometimes there's not much manpage at all -- you gotta go look under info or /usr/share/doc/package instead. or maybe even out to the web, on the author's own website. and sometimes there's no documentation at all... but that's rare. (even the most self-satisfied programmer wants her program to be USED, so she'll likely write up an intro, at the very least.) so here it is, anyway -- at least i think this is what you might be asking for: man command shows you the nitty-gritty for command, as in man ls man chmod man apt-get you can also try man configfilename which discusses the syntax and options expected in a particular configuration file, such as man sources.list man inted.conf man inittab the unix 'manual' is broken up into several sections, and occasionally you'll get the manpage from section 3 but you're wanting the one from section 8. if you know which section to ask for, try man section itemToReadAbout man -a itemToReadAbout== shows ALL matching manpages in sequence for example, locale has manpages in sections 1, 3, 5 and 7. to see the one from section 5, i'd do man 5 locale NOTE each section has a terse intro: to see it, do man 4 intro man 8 intro ... how do you know which section you've been reading? the section appears in parentheses after the title on every page: GETHOSTNAME(2) Linux Programmer's Manual GETHOSTNAME(2) so man gethostname is from section two. (when something refers you to locale(3) read the right one via man 3 locale.) to see which commands are RELATED to a certain term, also try apropos term whatis term -- at the newbieDoc project (newbieDoc.sourceForge.net) we've just discovered a package that's been around for quite some time: apt-get install dhelp dhelp try that, and see what it gets you. and, if you have a task you'd like to apply your debian machine to, write it up and send it to debian user, asking how it can be made to do what you want it to. the folks 'round these parts don't mind sharing their brain cells with a new friend. :) that's probably the best way to learn linux. you wouldn't think that grep has anything to do with finding which files contain certain patterns, would you? not unless you already knew unix. so ask those who do know. we'll get you started. -- DEBIAN NEWBIE TIP #85 from USM Bish [EMAIL PROTECTED] : Where should you SEARCH FOR DEBIAN PACKAGES? http://www.debian.org/distrib/packages Also, apt-cache search package might get you the info as well. Also see http://newbieDoc.sourceForge.net/ ...