Re: ls manpage incomplete

[James Youngman]

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?

James.