brian m. carlson wrote: > Bob Proulx wrote: > > This illustrates a basic philosophical difference between GNU systems > > and traditional Unix systems. In a traditional Unix system the > > standard for documentation was the man page. Mostly because there > > wasn't anything better. But as "GNU is not Unix" the GNU system > > vision was to improve upon Unix. One area of improvement was > > documentation. Man pages have been around for a very long time but > > they also have a lot of drawbacks. It isn't suitable for printing as > > a book. There is no linking between manuals. Other things. > > Therefore in the upstream GNU system the preferred documentation > > format is texinfo documentation which was specifically designed for > > those needs. > > I personally think man pages are fine for printing. groff formats them > very nicely indeed.
Note that I said "printing as a book" and man pages don't print well as books. They print fine as reference pages. > But I'm aware of the philosophical difference between Debian and the > GNU project. I tend to agree with Debian on this one, and I far > prefer man pages over info documents. Fair enough. As they say, there is no accounting for taste. :-) > I don't view info as an improvement on man, except maybe that its > HTML support is better. I strongly disagree. Info is a huge improvement over man pages. Man pages make good quick reference pages. But man pages are not well suited to other types of documentation such as user guides and books. > > On a Debian system that command will give you access to the full tsort > > manual. If you don't like the default 'info' (because perhaps you are > > a vi key user) then you may also use 'pinfo' or 'info --vi-keys' > > instead to get vi-style keybinding. > > > > pinfo coreutils 'tsort invocation' > > info --vi-keys coreutils 'tsort invocation' > > I honestly avoid info if at all possible. I was not aware of --vi-keys, > but even with that option, the keybindings are bizarre (like the fact > that Page Up and Page Down don't stop at the top of the page) which > makes it miserable to work with. pinfo's keybindings are not much > better. Perhaps a vi user could improve the keybindings for those programs? > (Also, the pinfo invocation you provided doesn't actually work.) Oh! Sorry. It does get to the coreutils section but not to tsort. I guess it needs the node set as an option. This works: pinfo coreutils --node='tsort invocation' And 'j' and 'k' go up and down. It stops at the top and bottom of the page. PageUp and PageDown work and both stop at the top and bottom of the page. (shrug) I probably should mention that the latest upstream version of the documetantion is also available online as web pages: http://www.gnu.org/software/coreutils/manual/ And tsort in particular is here: http://www.gnu.org/software/coreutils/manual/html_node/tsort-invocation.html#tsort-invocation But the latest upstream version and any particular packaged version may be different. Therefore I still prefer to use the installed documentation that matches the installed version of the programs. The standards documents are also online. http://pubs.opengroup.org/onlinepubs/009695399/utilities/tsort.html And just because I will note that the FreeBSD man pages are also available online too. A useful resource for an alternate free(dom) implementation. http://www.freebsd.org/cgi/man.cgi > I much prefer man and groff because they actually use my pager, which I > can configure with whatever keybindings and highlighting I'd like. A good point. > I can go on and on about the reasons I don't like info, but that really > isn't relevant to this bug report. > > > Your bug report implies that there isn't any documentation on the > > tsort input format. But that is incorrect since there *is* > > documentation on it. The documentation is in texinfo format. And it > > describes the input format that you are wishing to know about. > > My bug report indicates clearly that the *manual page* is inadequate > because it does not specify the input format. I did not comment on the > info documentation, mostly because I don't care very much about its > adequacy. Well... The man page documents that the full documentation is elsewhere. It describes how to access it. The access does work. The documentation is there. The information you are asking for is there. It is frustrating to me that you are dismissing info out of hand due to subjectively not liking it. That type of reasoning is symetrical but opposite to the GNU reasoning for requiring info documentation. But there is one difference that breaks the symmetry. The upstream primary documentation format exists in info format not man format. To do anything else requires work to do something else. So far no one has decided to replace the upstream GNU man pages with something different and continuously do the work keep them updated as the programs change. That would be an unreasonable amount of effort. > Honestly, I feel the manual page is inadequate because it tells me > nothing about how the program is to be invoked, other than the standard > GNU options. In this state, you might as well not have a man page. I > don't think Debian Policy requires a man page solely for the purpose of > having a man page, but rather to describe how the program works such > that someone can get some basic usage out of it, and currently that > isn't the case. > > Therefore, I still think it's reasonable to describe the format in the > manual page. The POSIX standard manages to specify it in one > three-sentence paragraph, so I suspect that the change can be easily > made. Suggestions to improve the online help wording are always welcome. (Although better to post upstream because that is where the work is done.) Upstream discussion is at coreut...@gnu.org by the way. What would you say to create a good description? > > Did you look at the texinfo documentation for tsort as described in > > the man page? > > Yes, because I ended up having to. That does not change the fact that > the manual page is deficient. Then I don't think saying that the man page was of no use is fair nor correct since it does instruct the user how to get to the full documentation which is available and fully descriptive. If you choose to avoid it then it is your choice to avoid it. That is not a bug in the program or package. Bob
signature.asc
Description: Digital signature
