tags 714232 + patch kthxbye On Mon, Jul 01, 2013 at 12:09:54AM -0600, Bob Proulx wrote: > 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.
I am dismissing info because its viewers are hard and irritating to use, it is essentially used only by the GNU Project[0], it is frequently used as an excuse not to provide adequate man pages[1], and other formats, such as asciidoc (which can be turned into man pages, HTML, PDF, and EPUB, among other formats), are more flexible. It is not the best or most versatile choice technically, and the ecosystem around it is unpleasant. I understand that maintaining documentation has a non-zero cost, but other upstreams manage to maintain man pages as well as other forms of documentation. I'm not even asking for this to be something coreutils upstream does proactively; I would be happy even if they only fix issues when someone points out a problem. > 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. I've attached a patch to the man page. Upstream is probably not interested in it because I won't assign copyright, but that shouldn't prevent Debian from applying it. > 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. So you're arguing that the man page is not inadequate solely because it points to the info documentation. My argument is that one should be able to determine how to invoke the program in the most ordinary way solely by reading the man page. Having other documentation is great, but if I can't figure out how to run it without the man page, there's a problem. I don't think that's an unreasonable attitude. [0] There are only four non-GNU source packages on my system that provide any info documentation whatsoever, and all of those packages also contain thorough and satisfactory man pages for their utilities. [1] Generally non-GNU upstreams are very interested in providing complete and thorough man pages, regardless of the other documentation they provide. Good examples are Kerberos and zsh. -- 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
diff --git a/man/tsort.1 b/man/tsort.1 index cb3f2b4..9055f04 100644 --- a/man/tsort.1 +++ b/man/tsort.1 @@ -1,4 +1,3 @@ -.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.35. .TH TSORT "1" "October 2012" "GNU coreutils 8.20" "User Commands" .SH NAME tsort \- perform topological sort @@ -10,6 +9,11 @@ tsort \- perform topological sort .PP Write totally ordered list consistent with the partial ordering in FILE. With no FILE, or when FILE is \-, read standard input. +.PP +Input to this utility consists of pairs of whitespace-separated tokens, each +pair representing an edge of the graph, or in case both tokens in a pair are the +same, simply the presence of that vertex in the graph. A message will be +printed to standard error if a loop is detected. .TP \fB\-\-help\fR display this help and exit
signature.asc
Description: Digital signature
