.\"	$YahooCvsId: bug2dot.1,v 1.3 2008/08/14 13:22:33 jans Exp $
.\"	$Source: /CVSROOT/yahoo/ops/user/jans/bug2dot/doc/man/bug2dot.1,v $
.\"
.\"	Copyright (c) 2008 Yahoo! Inc.
.\"
.\"	This manual page was originally written by Jan Schaumann
.\"	<jschauma@> in August 2008.
.Dd August 04, 2008
.Dt BUG2DOT 1
.Os
.Sh NAME
.Nm bug2dot
.Nd generate a dot language description of a bug's dependency graph
.Sh SYNOPSIS
.Nm
.Op Fl hno
.Ar bug
.Op Ar bug Oo ... Oc
.Sh DESCRIPTION
The
.Nm
tool emits a
.Ar dot
language description of the dependency graph for the given bug(s).
This description can then be fed to a tool such as
.Xr dotty 1
to create a visual representation thereof.
.Sh OPTIONS
.Nm
accepts the following command-line flags:
.Bl -tag -width n_
.It Fl h
Print a usage statement and exit.
.It Fl n
Only use numbers for all bugs.
Per default,
.Nm
also includes the bug summary in each node.
.It Fl o
Only display open bugs.
Per default,
.Nm
also includes bugs that are marked as 'resolved'.
.El
.Sh DETAILS
For every bug number
.Ar bug
given,
.Nm
will painstakingly parse the dependency tree generated at
http://<bugzilla>/showdependencytree.cgi?id=<bug>
and generate a
.Ar dot
language description representing this tree.
.Pp
If the
.Fl o
flag is specified,
.Nm
will not include bugs that are marked as 'resolved'.
Since that may obviously cause interruptions in the graph, any unresolved
bugs that block a resolved bug (which, oddly, may happen) will be
represented as blocking the requested bug indirectly by using a dotted
line.
.Sh INPUT
.Nm
takes as input any number of bugs separated by spaces.
If a given argument is the literal string '-' (ie a single dash), then
.Nm
will read input from stdin.
.Sh OUTPUT
The
.Ar dot
language description of the graph is emmitted to stdout.
.Pp
Error messages are generated to stderr.
.Sh EXAMPLES
The following examples illustrate common usage of this tool.
.Pp
To visualize the dependencies for the bug 109628:
.Bd -literal -offset indent
bug2dot 2109628 | dotty -
.Ed
.Pp
To create a gif image of the graph:
.Bd -literal -offset indent
bug2dot 2109628 > graph.dot
dot -Tgif graph.dot > graph.gif
.Ed
.Sh SEE ALSO
.Xr dot 1 ,
.Xr dotty 1
.Pp
ports/graphviz
.Pp
http://<bugzilla>/show_bug.cgi?id=2003070                                                              
.Sh HISTORY
.Nm
was originally written by
.An Jan Schaumann
.Aq jschauma@
in August 2008.
It was intended as a temporary solution until Bug
http://<bugzilla>/show_bug.cgi?id=2003070 would be resolved.
(The author is fully aware of the fact that there's nothing as permanent as
a temporary solution.)
.Sh BUGS
Please file bugs and feature requests using Bugzilla, Product "NSS
Architecture", Component "bug2dot"
(http://<bugzilla>/enter_bug.cgi?product=<component>&component=bug2dot).