tsort docs: steep learning curve

[Dan Jacobson]

Documentation critique, by Dan Jacobson.
|`tsort': Topological sort
|=========================
|
|   `tsort' performs a topological sort on the given FILE, or standard
|input if no input file is given or for a FILE of `-'.  For more details
|and some history, see *Note tsort background::.  Synopsis:
|
|     tsort [OPTION] [FILE]
|
|   `tsort' reads its input as pairs of strings, separated by blanks,
|indicating a partial ordering.  The output is a total ordering that
|corresponds to the given partial ordering.
|
|   For example
|
|     tsort <<EOF
|     a b c
|     d
|     e f
|     b c d e
|     EOF
|
|will produce the output
|
|     a
|     b
|     c
|     d
|     e
|     f

I see, it is just
xargs <<EOF -n 1|sort -u


|   Consider a more realistic example.  You have a large set of
|functions all in one file, and they may all be declared static except
|one.  Currently that one (say `main') is the first function defined in
|the file, and the ones it calls directly follow it, followed by those
|they call, etc.  Let's say that you are determined to take advantage of

can you guys please add one more intermediate example, before you get
into this heavy stuff.

|prototypes, so you have to choose between declaring all of those
|functions (which means duplicating a lot of information from the
|definitions) and rearranging the functions so that as many as possible
|are defined before they are used.  One way to automate the latter
|process is to get a list for each function of the functions it calls
|directly.  Many programs can generate such lists.  They describe a call
|graph.  Consider the following list, in which a given line indicates
|that the function on the left calls the one on the right directly.

can you add an example like the first one, but with just a little more
stuff, showing we are not just dealing with xargs -n 1|sort
and at the same time not needing a big explanation.
Yes, add an example that needs no explaining, that even a non-English
person could use.