[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: ls manpage incomplete
From: |
Richard Guy Briggs |
Subject: |
Re: ls manpage incomplete |
Date: |
Sat, 11 Jul 2009 08:20:50 -0400 |
User-agent: |
Mutt/1.5.18 (2008-05-17) |
On Sat, Jul 11, 2009 at 09:59:29AM +0100, James Youngman wrote:
> On Thu, Jul 9, 2009 at 9:57 PM, Richard Guy Briggs<address@hidden> wrote:
> >
> > The ls(1) manpage is incomplete. Why?
>
>
> On Fri, Jul 10, 2009 at 4:29 AM, Richard Guy Briggs<address@hidden> wrote:
> > On Thu, Jul 09, 2009 at 08:42:15PM -0600, Eric Blake wrote:
> >> According to Richard Guy Briggs on 7/9/2009 2:57 PM:
> >> > The ls(1) manpage is incomplete. Why? No, I don't want to use info(1).
> >> >
> >> > GNU coreutils 6.10 April 2008
> >>
> >> Consider upgrading - the latest stable version is 7.4.
> >>
> >> That said, the man pages are generated from --help output, which is
> >> necessarily compact. What in particular do you think is missing, that
> >> will not be too lengthy for inclusion? The GNU project favors info pages
> >> over man pages, whether or not you choose to read them.
> >
> > I'm on Ubuntu Hardy, which lags a bit, but this is a standard problem
> > against many GNU project tools. I'm running a number of .deb based
> > systems including Etch, Lenny, Sid, Hardy, Intrepid, Jaunty and all have
> > the same problem.
> >
> > The Bash and GCC manpages are long, but everything is there and
> > searchable without having to resort to info. In particular, I was
> > looking for the file type bits output in the -l option to ls(1), which
> > should just "be there" in the manpage and not have to grovel through
> > info(1) or find a project documentation web page. man(1) is a standard
> > tool across many unixes. All the information should be there. Info(1)
> > is a pet project of the GNU project. IMHO info(1) sucks. What's the
> > justification for putting incomplete information in the manpages that's
> > already available to another text tool on the same package? Even Perl
> > has complete manpages for everything.
>
> Most directly, as other people have stated, the ls(1) manpage is
> incomplete because the standard for documentation in GNU is Info. GNU
> maintainers are directed to produce and maintain Info documentation
> for their software. There is a significant overhead in maintaining
> manpages too, and it requires a significant amount of effort to keep
> the two in sync (for a start because doing so is error-prone,
> necessitating regular careful checking).
>
> Why choose Info though? Essentially because it is navigable (i.e.
> hypertext) and flexible. It cannot have escaped your attention that
> almost every single manual page on any Unix-like system is
> fundamentally of a reference nature. Manpages containing significant
> amounts of tutorial and truly introductory material are very rare
> indeed. Info is much better for this kind of information; people can
> browse through the document to find the information they need and this
> does not much impede the use of the document for other purposes (for
> example reference or reading through worked examples). Info also has
> direct support for useful things like code examples, URLs, email
> addresses and so on. As a bonus it is easy to convert a Texinfo
> manual into a well-typeset book.
>
> It would certainly be possible to maintain manual pages and Info
> documentation in parallel, and keep it all up to date. Some GNU
> packages do this. GNU findutils, for example has both extensive
> manual pages and extensive Texinfo documentation. Is the find(1)
> manual page complete? No, there is a lot of information in the
> Texinfo documentation (notably security discussions, some reference
> information about "-newermt", and worked examples) which is absent
> from the manpage.
>
> In fact, I dare say that if you proposed to "complete" the 70 or so
> manual pages for the coreutils programs and (importantly!) undertake
> to keep them up to date as the software is updated, for example by
> transferring changes the contributors make to the Texinfo source
> files, then the coreutils maintainer would probably work to
> incorporate your patches. What do you say?
I still say the ls(1) manpage is broken if the *reference* material
documenting the meaning of the long listing "-l" option output directory
entry type and mode bits is missing. I'm not talking about examples and
tutorials. This is basic reference material.
> James.
slainte mhath, RGB
--
Richard Guy Briggs -- ~\ -- ~\ <hpv.tricolour.net>
<www.TriColour.net> -- \___ o \@ @ Ride yer bike!
Ottawa, ON, CANADA -- Lo_>__M__\\/\%__\\/\%
Vote! -- <greenparty.ca>_____GTVS6#790__(*)__(*)________(*)(*)_________________
- Re: ls manpage incomplete, (continued)
- Re: ls manpage incomplete, Eric Blake, 2009/07/09
- Re: ls manpage incomplete, Richard Guy Briggs, 2009/07/09
- Re: ls manpage incomplete, Alfred M. Szmidt, 2009/07/10
- Re: ls manpage incomplete, Eric Blake, 2009/07/10
- Re: ls manpage incomplete, Richard Guy Briggs, 2009/07/10
- Re: ls manpage incomplete, Alfred M. Szmidt, 2009/07/10
- Re: ls manpage incomplete, Richard Guy Briggs, 2009/07/10
- Re: ls manpage incomplete, Alfred M. Szmidt, 2009/07/10
- Re: ls manpage incomplete, Matej Cepl, 2009/07/13
- Re: ls manpage incomplete, James Youngman, 2009/07/11
- Re: ls manpage incomplete,
Richard Guy Briggs <=