discuss: Thread: man pages

>From: "Guru -" ####@####.####
>To: ####@####.####
>Subject: Re: man pages
>Date: Fri, 16 May 2003 13:31:45 +1000
>
>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.....

I am willing to expand my 'Linux Dictionary' to include these as well. 
However, it is starting to become very difficult to work with due to its 
sheer size. All I need are references. First draft will be definitely out in 
six weeks.

Binh.

_________________________________________________________________
Add photos to your e-mail with MSN 8. Get 2 months FREE*.  
http://join.msn.com/?page=features/featuredemail

this discussion makes me think at an other way to improve doc.

do you know of any utility that could detecte automatically _all_ the 
doc available for an application?

some sort of "locate_doc"

I mean I use mostly man pages or google. but I have no way to know if 
there is an info file, HOWTO's, /usr/share/doc... and I can miss some 
important thing.

browsing all by hand is quite tedious.

I would like to type "locate_doc ls" and have a list of all the relevant 
doc.

if LDP was leading this, we could propose some way of indexing non 
standard doc.

an utility can find man or info page, /usr/share/doc README or such 
pretty usual thing but not html courses, but there could be a 
registration form (as fresmeat) at ldp or any html tag, LDP recommended, 
to easy web index.

jdd

-- 
<http://www.dodin.net>
Formation Linux débutants open

Hi,

On Fri, May 16, 2003 at 08:43:51AM +0200, jdd wrote:
> this discussion makes me think at an other way to improve doc.
> 
> do you know of any utility that could detecte automatically _all_ the 
> doc available for an application?
> 
> some sort of "locate_doc"
> 
> I mean I use mostly man pages or google. but I have no way to know if 
> there is an info file, HOWTO's, /usr/share/doc... and I can miss some 
> important thing.
> 
> browsing all by hand is quite tedious.
> 
> I would like to type "locate_doc ls" and have a list of all the relevant 
> doc.
> 
> if LDP was leading this, we could propose some way of indexing non 
> standard doc.
> 
> an utility can find man or info page, /usr/share/doc README or such 
> pretty usual thing but not html courses, but there could be a 
> registration form (as fresmeat) at ldp or any html tag, LDP recommended, 
> to easy web index.


For debian users, I would like to recall that dwww is doing that work
pretty well. (It's still buggy, but it's an interssant tool)


Cheers,
-- 
                                Pierre Machard
####@####.####                                  TuxFamily.org
####@####.####                                     techmag.info
+33(0)668 178 365                    http://migus.tuxfamily.org/gpg.txt
GPG: 1024D/23706F87 : B906 A53F 84E0 49B6 6CF7 82C2 B3A0 2D66 2370 6F87

Pierre Machard wrote:

> For debian users, I would like to recall that dwww is doing that work
> pretty well. (It's still buggy, but it's an interssant tool)

why only for debian users? this seems to be exactly what I looked for, 
very nice

thanks
jdd

-- 
<http://www.dodin.net>
Formation Linux débutants open

hi

just bcoz u like scrolling up with those keys dont
assume everyone will do so. the power of linux
shouldnt scare people of. ls can have umpteen
options.i am not against that but i want the relevant
ones first in a help page.is that bad?
regards
rahul

 --- David Lawyer ####@####.#### wrote: > 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
> 
> ______________________
> http://lists.tldp.org/
>  

________________________________________________________________________
Missed your favourite TV serial last night? Try the new, Yahoo! TV.
       visit http://in.tv.yahoo.com

Rahul Sundaram wrote:
> just bcoz u like scrolling up with those keys dont
> assume everyone will do so. the power of linux
> shouldnt scare people of. ls can have umpteen
> options.i am not against that but i want the relevant
> ones first in a help page.is that bad?

What are "relevant" options? How is the documentation author supposed to
know which options you think are relevant? The options are all there. the
user just needs to read or search to find what they need.

If users expect to look at web pages, they need to know how to navigate
around in a browser. If they expect to look at man pages, they need to
know how to navigate around using their pager (probably 'less' on Linux).

On GNOME and KDE systems, they can use the file manager to view man, info,
and HTML pages in an interface that should be easily usable to any GUI user.

Generally man pages are for reference, not for inroducing newbies to a new
tool. Web pages and HOWTOs are spcifically designed for that. But most
people are only newbies for a relatively short period over the life of the
time they use Linux. Redesigning all the docs for that short period is
simply not reasonable. Most people quickly learn that man pages are
(mostly) not the place to look for detailed explanations and examples. I
spent a few months figuring out the best places to find docs and how to
use the basic tools. After that, I spent more than 5 years using Linux
daily. rewriting the man pages for those few months would have resulted in
me having to read newbied docs for the next five years.

There are docs for learning, and there are docs for using. That is a good
design.

What would be good is an easily findable way for new GNOME and KDE users
to find tutorial docs on their local system. That is a desktop and
distribution issue though. The LDP should stay focused on providing good
tutorial and cookbook docs. Trying to create a whole new set of docs is
not practical, for a whole slew of reasons. This would basically involve
changing an established standard way of doing things.

As widespread as the GNU utilities are, I don't know anyone who routinely
uses the GNU info pages instead of the established man pages.

What you're talking about is a huge project. Huge. And the proposed
benefit is to make it easier during the first few months.

There are ways to accomplish that that do not involve a complete redesign
of the Linux documentation system.

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/>

On Fri, May 16, 2003 at 09:04:02AM -0400, Greg Ferguson wrote:
> On Fri, 16 May 2003 08:43:51 +0200 jdd ####@####.#### wrote:
> 
> > this discussion makes me think at an other way to improve doc.
> > 
> > do you know of any utility that could detecte automatically _all_ the 
> > doc available for an application?
> > 
> > some sort of "locate_doc"
> 
> scrollkeeper was/is meant to provide that type of functionality.
> http://scrollkeeper.sourceforge.net/ 
> 

The problem here is that this requires packagers to register their
documentation with ScrollKeeper when the package is installed on the user's
computer, and there has been less than universal buy-in.

Cheers,
John

On Thu, 15 May 2003, Rahul Sundaram wrote:
> 	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.
> [ SNIP ]
> 
> An example would demonstrate my point 
> 
> This is the present form
> 
> ?
> Man less
> 
> Less- less is opposite of more. (supposed to be brief
> information)

Odd, here's my version:

       Less is a program similar to more (1),  but  which  allows
       backward movement in the file as well as forward movement.
       Also, less does not have to read  the  entire  input  file
       before  starting,  so  with large input files it starts up
       faster than text editors like vi (1).  Less  uses  termcap
       (or  terminfo on some systems), so it can run on a variety
       of terminals.  There is even limited support for  hardcopy
       terminals.  (On a hardcopy terminal, lines which should be
       printed at the top of  the  screen  are  prefixed  with  a
       caret.)

       Commands  are  based on both more and vi.  Commands may be
       preceded by a decimal number, called N in the descriptions
       below.  The number is used by some commands, as indicated.

(debian-woody, for the curious)

Remember, your distribution of linux is not everyone's distribution 
of linux.

You seem to be confusing "Redhat" or "Redhat-based" with linux.  

> [SNIP]
> 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.

Now you seem to be confusing your limited usage of the 'cat' 
command with all of its usages.

The cat command is used for concatenating files, either from 
stdout, or from the files listed, and to stdout.

Lets say I want to take two log files and combine them into one 
log file.  A simple 'cat log1 log2 | sort > log3' works wonders, 
if each logfile is of the format "timestamp information".

I agree with you, cat is a horrible way to read all but the 
shortest files.  OTOH, cat does work very well for concatenating 
files.

> Let me know what you people think of all this.

When I first started using linux, I thought that the man pages 
sucked.  I looked online, bought a few books, read a few howtos, 
and basically avoided the man pages.

Now, I'm to the point where I find the man pages very useful, 
and those howtos and books seem rather limited.  I either use 
manpages for refreshing my memory, or to see if I can find 
some obscure option to do what I wish.

Your proposal seems to cater to the new users and penalizes the 
power users.  Lets keep the man pages clean and complete, excess 
information can either go into howtos or into the shared document 
directory, which is /usr/share/doc, on FHS-compliant systems, IIRC.

I agree, a lot of man pages need a rewrite, since man are out of 
date or a tad too sparse.  OTOH, I don't think linux needs to transform 
each and every man page into a hand-holding tutorial.

Just my $.02,

Jesse Meyer

-- 
        ...crying "Tekeli-li! Tekeli-li!"... ~ HPL
 icq : 34583382              |     === ascii ribbon campaign ===
 msn : ####@####.####    |  ()  - against html mail
 yim : tsunad                |  /\  - against proprietary attachments