Re: ls manpage incomplete

[Richard Guy Briggs]

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__(*)__(*)________(*)(*)_________________