#569310 coreutils: 'info tsort' examples: 1st vague, 2nd too specialized

Package:
coreutils
Source:
coreutils
Description:
GNU core utilities
Submitter:
"A. Costa"
Date:
2010-02-13 10:54:08 UTC
Severity:
normal
#569310#5
Date:
2010-02-11 11:42:12 UTC
From:
To:
The 'info' examples are not too helpful. For instance:

zgrep -n -A 21 "reads its input" /usr/share/info/coreutils.info.gz
4139:   `tsort' reads its input as pairs of strings, separated by blanks,
4140-indicating a partial ordering.  The output is a total ordering that
4141-corresponds to the given partial ordering.
4142-
4143-   For example
4144-
4145-     tsort <<EOF
4146-     a b c
4147-     d
4148-     e f
4149-     b c d e
4150-     EOF
4151-
4152-will produce the output
4153-
4154-     a
4155-     b
4156-     c
4157-     d
4158-     e
4159-     f
4160-

I applaud the abstraction of using letters, but that result isn't
special enough:

    { tr ' ' '\n' <<EOF
    a b c
    d
    e f
    b c d e
    EOF
     } | sort -u
     a
     b
     c
     d
     e
     f

Of course the above code is a coincidental replacement, not a true
'tsort'.  It's as though we had an elite new command  "mul" (short for
"multiply") and our example was:

    % mul 2 2
    4

Novices might wonder if "mul" added 2 & 2.  The example would be
clearer if it showed a more distinctive result that wasn't trivial to
simulate.

The 'info' page's later "more realistic example" is an obscure C code
puzzle, of historic interest, and is perhaps informative to the small
minority that appreciates the puzzle.

#569310#10
Date:
2010-02-13 10:43:06 UTC
From:
To:
A. Costa wrote:

Thanks for the feedback.
Would you like to propose a better example?
Patches are most welcome.