discuss: Thread: man pages

Rahul Sundaram wrote:

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


At the same time Andries Brouwer has expressed
his doubts about the info format in strong language.
Moreover he has started to translate info pages to
man pages.

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


I believe this is attacking the problem from the
wrong direction. For new users even man in itself
might be too complicated; it is my experience that
very few know of the man -k option when they need
it the most: in the beginning.

I therefore believe the best idea is to have a few
reference sheets that show the most common commends
with the most common options in the style you suggest.
make it short so it can be put on the wall next to
the monitor.

After a while, perhaps 2 weeks, the user moves on
and is ready for the more advanced options at which
point the terse but complete man pages are all that
is needed.

There is already a Tips-HOWTO that should cover some
of this ground; could you have a look at it and post
your coments to it?

[snip examples]


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


TLDP has the challenging task of offering useful
information to the novices as well as the experts.
rather than simplifying what we have I believe it
is more productive to write starting points for
the newcomers and let them progress.

Regards,
    Stein Gjoen

El vie, 16 de 05 de 2003 a las 08:43, jdd escribió:
> 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"

The most similar thing is the scrollkeeper register.

It's a distro packager responsability to register documents inside a
Linux package to register them into scrollkeeper.

The registering is from a XML standard OMF file.

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

It's a horrible mix.

My opinion is there is a concrete «labour of love» here:

      * migrating all docs into docbook (at least as source code)
      * spread the scrollkeeper use in all distros
      * write a CLI yelp-like tool. yelp (from Gnome) can navigate with
        all scrollkeeper registered documents

We should to erase of the surface of the earth the use of man and info
and put a bit of order in the system documentation as you suggest.



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

At TLDP-ES we are working in the server equivalente of the
(scrollkeeper) system. We have an advanced prototype yet.

-- 
        A.Ismael Olea González

        ####@####.####  http://www.olea.org
        http://aduaneros.olea.org, la ONG sin futuro.

        El mundo tiene miedo a un planeta BUSH: No a la guerra.

El vie, 16 de 05 de 2003 a las 16:38, John Fleck escribió:

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

A db2omf tool could help to create the register for packagers (and
authors).

-- 
        A.Ismael Olea González

        ####@####.####  http://www.olea.org
        http://aduaneros.olea.org, la ONG sin futuro.

        El mundo tiene miedo a un planeta BUSH: No a la guerra.

El lun, 19 de 05 de 2003 a las 22:47, Stein Gjoen escribió:


> One minor detail: TLDP only provides man pages from a limited
> number of chapter, and not those that come with installed software.
> For completeness I would therefore propose that we supply all
> the TLDP man pages as wel as those from a reasonably large Linux
> distribution such as Debian and note what is from TLDP and what
> is from, here, Debian.


I think it should better to write a proposal of man-page policy, tools
for support that policy and spread it. For example I think is an error
that some manpages are maintained (or translated) outside the sofware
they documents. Is the best way to get outdated. 


-- 
        A.Ismael Olea González

        ####@####.####  http://www.olea.org
        http://aduaneros.olea.org, la ONG sin futuro.

        El mundo tiene miedo a un planeta BUSH: No a la guerra.

The quality of the man pages is a typical Linux distribution
makes me despair for the sanity of users.

There are commands without man pages, there are command
options which are unexplained, there are descriptions
so detailed as to boggle the mind but no example of
the most common usages.

Is there a project which is working on this?

If not, is there are list of best practices for man pages?

Glen
(trying hard not to volunteer a lifetime's work,
 but getting a nasty feeling that it may be
 inevitable)

On 4 Jan 2004, Glen Turner wrote:

> The quality of the man pages is a typical Linux distribution
> makes me despair for the sanity of users.
> 
> There are commands without man pages, there are command
> options which are unexplained, there are descriptions
> so detailed as to boggle the mind but no example of
> the most common usages.

It is my understanding that Debian requires all packages to have a man 
page, so in a sense there is a project working on this.

Man pages are the responsibility of the individual project developer(s). I 
would imagine that individual projects would be willing to accept 
documentation patches, but because there is no central software project, 
there is also no central documentation project.

Cheers,
Mikal

-- 

Michael Still ####@####.#### | "All my life I've had one dream,
http://www.stillhq.com            |  to achieve my many goals"
UTC + 11                          |    -- Homer Simpson

Michael Still wrote:
> On 4 Jan 2004, Glen Turner wrote:
> 
> > The quality of the man pages is a typical Linux distribution
> > makes me despair for the sanity of users.
> >
> > There are commands without man pages, there are command
> > options which are unexplained, there are descriptions
> > so detailed as to boggle the mind but no example of
> > the most common usages.

I agree that man pages leave something to be desired, especially for a
beginner.

One of my objectives in starting WikiLearn is to address things like
this.  I invite you and anyone else to participate.  See, for example:

http://twiki.org/cgi-bin/view/Wikilearn/WebHome

follow the links to: 

AboutThesePages (and then to:
   UsingFtpBeginner 
   UsingFtpReminder 
WebChanges

regards,
Randy Kramer
> 
> It is my understanding that Debian requires all packages to have a man
> page, so in a sense there is a project working on this.
> 
> Man pages are the responsibility of the individual project developer(s). I
> would imagine that individual projects would be willing to accept
> documentation patches, but because there is no central software project,
> there is also no central documentation project.
> 
> Cheers,
> Mikal
> 
> --
> 
> Michael Still ####@####.#### | "All my life I've had one dream,
> http://www.stillhq.com            |  to achieve my many goals"
> UTC + 11                          |    -- Homer Simpson
> 
> ______________________
> http://lists.tldp.org/

----- Original Message ----- 
From: "Michael Still" ####@####.####
To: "Glen Turner" ####@####.####
Cc: ####@####.####
Sent: Monday, January 05, 2004 12:06 AM
Subject: Re: man pages


> On 4 Jan 2004, Glen Turner wrote:
>
> It is my understanding that Debian requires all packages to have a man
> page, so in a sense there is a project working on this.
>
At least, a downloadable man package ( for mini-distros, i.e.).

> Man pages are the responsibility of the individual project developer(s). I
> would imagine that individual projects would be willing to accept
> documentation patches, but because there is no central software project,
> there is also no central documentation project.
>
This would be controlated, for sure, for a better Linux documentation. A GNU
program with MAN file would obtain more "official" support and publicity (
publication, review and so on ) than another one without man file.

Regards.

Interesting link found :
http://www.superant.com/cgi-bin/slencyclopedia.pl?Slencyclopedia

Linux encyclopedia in wiki format (what I was seeking, for long time ago).

On Sun, Jan 04, 2004 at 09:34:29PM +1030, Glen Turner wrote:
> 
> The quality of the man pages is a typical Linux distribution
> makes me despair for the sanity of users.
> 
> There are commands without man pages, there are command
> options which are unexplained, there are descriptions
> so detailed as to boggle the mind but no example of
> the most common usages.
> 
> Is there a project which is working on this?

LDP once intended to work on problems like this, but unfortunately an
effort in this direction a few years ago didn't result in any changes
since the leader left the project.  The problem is that of integrating
all the various Linux documentation.  Right now LDP has more than enough
to do to attempt to keep HOWTOs up-to-date.  Unless you want to again
undertake this project.

> If not, is there are list of best practices for man pages?
> 
> Glen
> (trying hard not to volunteer a lifetime's work,
>  but getting a nasty feeling that it may be
>  inevitable)
It is truly a lifetime project.

			David Lawyer

I receive from time to time notice of the update of man pages.

man pages are one of the LDP referenced documents.

we have to think if we want to include them in the wiki (not sure it's
a good idea). I write to the maintainer ####@####.#### to
know the status

jdd
-- 
jdd for the Linux Documentation Project
http://wiki.tldp.org
http://www.dodin.net