[<<] [<] Page 1 of 4 [>] [>>] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
man pages
From: Rahul ####@####.#### Date: 15 May 2003 14:58:05 -0000 Message-Id: <20030515145802.69786.qmail@web8004.mail.in.yahoo.com> Hi Here I am presenting my opinion on man pages and making a few suggestions on how LDP can deal with this. The GNU has been calling man pages outdated stuff and replaced them with info pages. Man pages cater to the expert who already knows what he deals. If I am a new user trying to learn say what ls does from the command line, the almost infinite number of options would scare me off Linux for the rest of my life. We can either make man pages more user friendly, replace them with info pages or make a complete new set of alternative documentation (which is really heavy work) but I don’t think that man pages in their present form should be given as a form of help for anybody new to Linux. Are info pages better?. For new users it probably explains much more than a typical man page does. It should start out with a brief explanation of the command. The important options first, the example and then the other commands and related files etc. An example would demonstrate my point This is the present form “ Man less Less- less is opposite of more. (supposed to be brief information) More geeky information here Alphabetical list of options with no indication of what is more commonly used Optional examples – most probably not there Files Bugs Author information” Ya this is probably some very funny guy expressing his classic nerd jokes and pun but what am I supposed to learn from this. More is definitely not opposite of more and even will not be able to understand what less does that soon from the man pages. My initial reaction would be “ what – less is opposite of more”. So? What the heck? I would get bogged down with options, bored and irritated with the terseness and give up in frustration. Here would be my idea of writing a friendly man page. Man less Less – less is a command that can also act as a filter used for viewing information one screen at a time. It is similar to the more command but has the capability to move both back and forward when viewing information. Users can scroll through any text information. For example, /Cat myfile.txt/ - would display a text file on screen but you can only see the last part if the file contains more information than what would typically fit in a single screen(24 lines). Less myfile.txt This command would display the file “myfile.txt” one screen at a time (ie) if the file has more information than can be displayed in a single screen it would wait for the user to scroll through the document using arrow keys. You can use q to quit reading. It can also be used a filter. For example, Rpm – qa lists all the packages installed in your system. This would probably not fit in a single screen. So we can use Rpm –qa | less For viewing information one screen at time. Here less acts a filter. Good list of examples More relevant options in probable order of usage Bugs Author information. Web links to latest copy in LDP? This probably insults the expert but would be much more readable to newbies. We can be redundant and tutorial like with no terse explanations and try to explain things as much as we can. One more issue with man pages is how relevant they are. Like I said a alphabetical listing of options is irrelevant most of the time. How am I supposed to understand which of the ls umpteen options are probably more useful?. The command should illustrate common usage patterns and help the users understand not only how but also why a command is usually used. For example, The man page for cat says that it is used to concatinating files. This is definitely true but is it relevant to the user? We all know that cat is more used for displaying files and also that the less command is more appropriate for that usually. So why isnt it reflected in the man pages. We can start such a project specifically to rewrite or write an alternative set of documentation. If we are writing an alternative set, we don’t need to mention each and every command, we can start off with the important stuff and refer users to man pages for more advanced stuff. If we are writing an alternative set, The format can either be the man or info page formats. Why? We can concentrate on writing documentation and existing tools would be able to use the stuff we write without any changes. Example: help less Would display user friendly “helpful” information while internally using man or info/ pman or pinfo. Today when I don’t know something about a command, asking someone else who does know how it is used is much better than going through the comprehensive but terse manual pages. I think this should change. Let me know what you people think of all this. Regards Rahul Sundaram ________________________________________________________________________ Missed your favourite TV serial last night? Try the new, Yahoo! TV. visit http://in.tv.yahoo.com | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: "Anthony E. Greene" ####@####.#### Date: 15 May 2003 15:34:38 -0000 Message-Id: <3EC3B459.4050904@pobox.com> Rahul Sundaram wrote: > Today when I don’t know something about a command, > asking someone else who does know how it is used is > much better than going through the comprehensive but > terse manual pages. I think this should change. I think there are two different needs here that are best addressed with two different sets of documentation. When learning how to use Linux, users need tutorial documents. The HOWTOs and web sites are generally good for teaching. They offer lots of explanations and examples, which is exactly right for learning a new tool. But when trying to remember how to use a command that I'm already familiar with, I do not want to wade through pages and pages of HOWTOS or search all over the Web. A terse, but comprehensive man or info page is just right. Tony -- Anthony E. Greene ####@####.#### OpenPGP Key: 0x6C94239D/7B3D BD7D 7D91 1B44 BA26 C484 A42A 60DD 6C94 239D AOL/Yahoo Chat: TonyG05 HomePage: <http://www.pobox.com/~agreene/> Linux. The choice of a GNU generation. <http://www.linux.org/> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: "Anthony E. Greene" ####@####.#### Date: 15 May 2003 15:55:45 -0000 Message-Id: <3EC3B94C.9050100@pobox.com> Greg Ferguson wrote: > While on the topic - would people be interested in a collection of man > pages (filtered to HTML via man2html; browseable, etc.) on the LDP site? GNOME includes a tool to do this locally on a machine. Using Galeon, I can enter a URL like this: man:less to view the manpage for 'less'. It also works for GNOME Help pages (ghelp:subject). I tried it with GNU info pages, but I don't remember the results. Tony -- Anthony E. Greene ####@####.#### OpenPGP Key: 0x6C94239D/7B3D BD7D 7D91 1B44 BA26 C484 A42A 60DD 6C94 239D AOL/Yahoo Chat: TonyG05 HomePage: <http://www.pobox.com/~agreene/> Linux. The choice of a GNU generation. <http://www.linux.org/> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: Machtelt Garrels ####@####.#### Date: 15 May 2003 16:10:09 -0000 Message-Id: <Pine.LNX.4.44.0305151108490.4684-100000@server1.us.soti.org> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Thu, 15 May 2003, Anthony E. Greene wrote: > Greg Ferguson wrote: > > While on the topic - would people be interested in a collection of man > > pages (filtered to HTML via man2html; browseable, etc.) on the LDP site? > > GNOME includes a tool to do this locally on a machine. Using Galeon, I can > enter a URL like this: > > man:less > > to view the manpage for 'less'. It also works for GNOME Help pages > (ghelp:subject). I tried it with GNU info pages, but I don't remember the > results. Yes, and there are several other possibilities, but it would be nice to have them online for people who don't have a working Linux system at hand, I think. Sometimes. Tille. - -- My Penguin, my freedom. http://tille.soti.org -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (GNU/Linux) Comment: For info see http://www.gnupg.org iD8DBQE+w7vgsIIUbMXbBA8RAjPLAKCx1mgoUkp8I8SwegB2OrAnWhDUfwCgkx3p syZdNPiXZo7Uj3fxDB/GmOk= =K0iy -----END PGP SIGNATURE----- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: Howard Shane ####@####.#### Date: 15 May 2003 18:35:40 -0000 Message-Id: <3EC3DDE3.2060902@charter.net> You raise some outstanding points. > The GNU has been calling man pages outdated stuff and > replaced them with info pages. The GNU info browser (in my unesteemed opinion) is confusing for anyone not familiar with the Emacs way of doing things. The paging is the biggest problem; it's very easy to get stuck at the end of a page if you don't remember the correct combination of keys. The one thing it does well is allow moving between cross-referrenced *-headings. Pinfo is better, but how is a newbie going to know to use that program preferrentially? > Man pages cater to the > expert who already knows what he deals. If I am a new > user trying to learn say what ls does from the command > line, the almost infinite number of options would > scare me off Linux for the rest of my life. Some manpages are like this. Most aren't. Maybe this is a formatting issue as opposed to a content issue? > We can > either make man pages more user friendly, replace them > with info pages I've been disappointed with most of the info pages I've consulted. The info page in question is usually a) marginally more readable, b) less comprehensive, or c) doesn't exist for the program in question. (Rarely they do get it right, though, as in the textutils documentation.) > We all know that cat is more used for displaying files > and also that the less command is more appropriate for > that usually. So why isnt it reflected in the man > pages. We can start such a project specifically to > rewrite or write an alternative set of documentation. IMHO we need a new form of documentation like we need another linux distro. Writing and compiling it would consume hours of volunteer work that more efficiently used refining documentation that's already there. If the system's not broken, should we fix it with a gnu one that's worse? ;^) If manpage authors would simply expand on their documents I daresay there would be no issue. > If we are writing an alternative set, we don't need to > mention each and every command, we can start off with > the important stuff and refer users to man pages for > more advanced stuff. Interesting. When I consult documentation it's usually to have a question answered or to learn about an application. I doubt people sit down to read man/info pages like a novel. My biggest gripe with all documentation is that it is incomplete and/or it doesn't give enough examples. So how would you decide on the content to cut when even a newbie might have a relatively specific question? I suggest instead a well-written manpage for everyone to consult from the start that is the standard reference for that application, sort of a definitive text complete with hints, examples, etc., but synopsis and options for the experienced and impatient. How do we get better manpages? Maybe TLDP should offer to preview, proof or rewrite manpages at the discretion of the author. I'm sure a lot of developers wouldn't object, and for those who write substandard manpages and don't participate, maybe a 'manpage hall of shame' could be used to pressure offenders. I was a newbie only a few short years ago and remember it well, so I feel somewhat qualified to comment on the subject. hs | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: Machtelt Garrels ####@####.#### Date: 15 May 2003 18:46:30 -0000 Message-Id: <Pine.LNX.4.44.0305151340450.5449-100000@server1.us.soti.org> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Thu, 15 May 2003, Howard Shane wrote: > How do we get better manpages? Maybe TLDP should offer to preview, proof > or rewrite manpages at the discretion of the author. I'm sure a lot of > developers wouldn't object, and for those who write substandard manpages > and don't participate, maybe a 'manpage hall of shame' could be used to > pressure offenders. Well yes, and make it known that there is such a service, in case people only want to develop programs and are no natural born writers. I know a lot of those. The form under which the doc is made available (man/info page, --help, apropos, graphic browsers, ..) is less important than the general accessability. However, if you say the daily publishing rate at freshmeat, sourceforge and other software sites, I imagine we will need an awful lot of volunteers. Tille. - -- My Penguin, my freedom. http://tille.soti.org -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (GNU/Linux) Comment: For info see http://www.gnupg.org iD8DBQE+w+CEsIIUbMXbBA8RAqW7AJwMHKPTXzqGU9LRpK2w3XrlM+nGgACgp1ib QzHcITJ76tlYrMX3NOsVvvc= =Tku0 -----END PGP SIGNATURE----- | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: Togan Muftuoglu ####@####.#### Date: 15 May 2003 18:47:09 -0000 Message-Id: <20030515184701.GR1190@dinamizm.com> * Howard Shane; ####@####.#### on 15 May, 2003 wrote: >I've been disappointed with most of the info pages I've consulted. The >info page in question is usually a) marginally more readable, b) less >comprehensive, or c) doesn't exist for the program in question. (Rarely >they do get it right, though, as in the textutils documentation.) Well said, being able to program does not necessarily mean being able to document what is intended. IMHO 95% of info and man pages do suck and thats one of the reasons I pay X amount of dollars to publishers like Oreilly to get a better documentation of what I should have already by having the program. -- Togan Muftuoglu | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: "Kurt Pfeifle" ####@####.#### Date: 15 May 2003 19:07:35 -0000 Message-Id: <3EC3E4D6.7030409@danka.de> Anthony E. Greene wrote: > Greg Ferguson wrote: > >> While on the topic - would people be interested in a collection of man >> pages (filtered to HTML via man2html; browseable, etc.) on the LDP site? > > > GNOME includes a tool to do this locally on a machine. Using Galeon, I > can enter a URL like this: > > man:less > > to view the manpage for 'less'. It also works for GNOME Help pages > (ghelp:subject). I tried it with GNU info pages, but I don't remember > the results. > > Tony KDE Konqueror does the same. Just enter "man:less" (or "man:/less") into the address field. It also handles GNU info pages ("info:/info") very well -- finally I was able to read them, because there are hyperlinks "Which Just Work (tm)". KDE help pages and manuals are shown with "help:/kdeprint" for example. Cheers, Kurt | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: David Lawyer ####@####.#### Date: 15 May 2003 22:11:26 -0000 Message-Id: <20030515221133.GB547@lafn.org> On Thu, May 15, 2003 at 03:58:02PM +0100, Rahul Sundaram wrote: > Here I am presenting my opinion on man pages and making a few > suggestions on how LDP can deal with this. This is part of the overall problem of integrating Linux documentation. It's a big project that needs at lot of volunteer effort which the LDP hasn't available at present. > The GNU has been calling man pages outdated stuff and > replaced them with info pages. But I think they are still more widely used that info pages. > Man pages cater to the expert who already knows what he deals. Not always. Some are tutorial with examples, etc. > If I am a new user trying to learn say what ls does from the command > line, the almost infinite number of options would scare me off Linux > for the rest of my life. If you type ls --help it shows all the options and then by using <shift><PageUp> you can go scroll back to the first screenfull of them. The large number of options also illustrates the power of Linux. [snip] > /Cat myfile.txt/ - would display a text file on screen but you can > only see the last part if the file contains more information than what > would typically fit in a single screen(24 lines). Use <shift><PageUp> to read what scrolled by too fast. <shift><PageDown> scrolls back down. David Lawyer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Subject:
Re: man pages
From: "Guru -" ####@####.#### Date: 16 May 2003 03:32:13 -0000 Message-Id: <Sea2-F46IIZS2TRqf6900003527@hotmail.com> Sure, rewriting all documentation seems like a good idea, lol, I don't think so, there's no way the LDP has time to create a simplified manual page for every existant tool. Sure, I think the idea is great but its not practical, I mean you could rewrite pages for the core utilities. My HOWTO does this (to a point, its not designed to be a man page rewrite of every existant tool). The GNU/Linux Tools Summary HOWTO is hosted here: www.karakas-online.de/LinuxCommands/t1.html So if you did want to go ahead with the idea feel free to reference material from there. The idea is good but I don't think its very practical to carry out........ Also we don't need to get rid of man pages (as previously stated by someone else) they are important for power-users and administrators, we simply need a simplified version of man pages for new users..... _________________________________________________________________ ninemsn Extra Storage is now available. Get larger attachments - send/receive up to 2MB attachments (up to 100 percent more per e-mail). Go to http://join.msn.com/?page=dept/home&pgmarket=en-au | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[<<] [<] Page 1 of 4 [>] [>>] |