alternate description of tsort and example.

Approved by jmc@, with minor corrections coming up.

1 files changed, 44 insertions, 2 deletions

diff --git a/usr.bin/tsort/tsort.1 b/usr.bin/tsort/tsort.1
index 2ec6ac93395..3938b59422b 100644
--- a/usr.bin/tsort/tsort.1
+++ b/usr.bin/tsort/tsort.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: tsort.1,v 1.14 2003/06/10 09:12:12 jmc Exp $
+.\"	$OpenBSD: tsort.1,v 1.15 2004/08/04 15:29:10 espie Exp $
 .\"	$NetBSD: tsort.1,v 1.6 1996/01/17 20:37:49 mycroft Exp $
 .\"
 .\" Copyright (c) 1990, 1993, 1994
@@ -53,6 +53,10 @@
 .Nm tsort
 takes a list of pairs of node names representing directed arcs in
 a graph and prints the nodes in topological order on standard output.
+That is: the input describes a partial ordering relation, from which
+.Nm
+computes a total order compatible with this partial ordering.
+.Pp
 Input is taken from the named
 .Ar file ,
 or from standard input if no file
@@ -96,9 +100,47 @@ Exit with exit code the number of cycles
 .Nm
 had to break.
 .El
+.Sh EXAMPLES
+Faced with the input:
+.Bd -literal
+a b
+b c
+b d
+d f
+c e
+.Ed
+.Pp
+.Nm
+outputs:
+.Bd -literal
+a
+b
+c
+e
+d
+f
+.Ed
+.Pp
+which is one total ordering compatible with the individual relations.
+There is no unicity, another compatible total ordering would be:
+.Bd -literal
+a
+b
+c
+d
+e
+f
+.Ed
+.Pp
+.Nm
+is commonly used to analyze dependencies and find a correct build order
+in a static way, whereas
+.Xr make 1
+accomplishes the same task in a dynamic way.
 .Sh SEE ALSO
 .Xr ar 1 ,
-.Xr lorder 1
+.Xr lorder 1 ,
+.Xr make 1
 .Rs
 .%A Donald E. Knuth
 .%B The Art of Computer Programming