obscure documentation

[Robert Stone]

        This is not a bug, so much as a suggestion.
        The description of tsort(1) provided in the infodocs is almost
identical to http://www.opengroup.org/onlinepubs/7908799/xcu/tsort.html,
the Single UNIX ? Specification, which is a technically precise description,
but totally opaque if you're not familiar with classic algorithmics.
        The fact that the sample output provided happens to produce an
alphabetically sorted list leads a naive reader to believe this is closely
related in functionality to sort(1).  The mention of "partial ordering"
combined with the sample input:

a b c
d
e f
b c d e

from the infodoc, causes many people to initially assume that this software
will merge sorted sublists since each line of this file happens to be in
alphabetically sorted order.
        This idea of directed graphs can be conveyed very simply to a
naive reader by careful example selection.  Though this may be too verbose
for your tastes, the traditional example of morning routines may help many
people understand the dependency resolution problems this software can
be used to help resolve.  Something like:

WakeUp          TurnOffAlarm
WakeUp          Shower
WakeUp          MakeBreakfast
Shower          DryOff
DryOff          GetDressed
ChoosePants     GetDressed
ChooseShirt     GetDressed
GetDressed      Leave
MakeBreakfast   MakeCoffee
MakeBreakfast   PourCereal
MakeCoffee      EatBreakfast
PourCereal      EatBreakfast
EatBreakfast    BrushTeeth
TurnOffAlarm    Leave
BrushTeeth      Leave

as sample input would remove any ideas in readers minds of any relationship
between ordering and string values.  Hopefully, this would make the software
usable for a wider audience.  Also, the fact that the given output is one of
possibly many correct outputs satisfying the dependencies stated would
probably be worth mentioning.
        Graph theory is not a difficult thing to grasp, unfortunately, their
computatable representations are rarely the most intuitive way for humans
to think about them.  I don't mean to gripe.  Less than six months ago I
personally wrote an implementation of this algorithm and it still took me
twenty minutes with the infodoc and referral to a textbook to understand the
functionality of tsort(1).
                                                thanks,
                                                Robert Stone
-- 
address@hidden          | "Bother," said Pooh as he struggled with
finger for (pgp|gpg) key        | sendmail.cf, "It never does quite what I
                                | want.  I wish Christopher Robin was here."