On Thu, Jun 27, 2013 at 08:43:53PM -0600, Bob Proulx wrote: > brian m. carlson wrote: > > Topological sorting requires a list of directed edges. In order to > > describe these edges, one must have at least two pieces of information > > per edge, namely the vertices defining that edge. tsort presumably > > requires some specific format for this information, but the manual page > > does not say what it is. Thus, a user cannot be expected to make any > > reasonable use of tsort based on reading only the manual page. > > > > The manual page should be improved so that a user can determine what > > input format tsort takes by reading the manual page alone. > > 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. 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. I don't view info as an improvement on man, except maybe that its HTML support is better. > 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. (Also, the pinfo invocation you provided doesn't actually work.) I much prefer man and groff because they actually use my pager, which I can configure with whatever keybindings and highlighting I'd like. 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. 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. > 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. -- brian m. carlson / brian with sandals: Houston, Texas, US +1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187
signature.asc
Description: Digital signature
