On Thu, Jul 9, 2009 at 9:57 PM, Richard Guy Briggs<r...@tricolour.net> wrote: > > The ls(1) manpage is incomplete. Why?
On Fri, Jul 10, 2009 at 4:29 AM, Richard Guy Briggs<r...@tricolour.net> 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. _______________________________________________ Bug-coreutils mailing list Bug-coreutils@gnu.org http://lists.gnu.org/mailman/listinfo/bug-coreutils
