Add a pre-generated .0 manpage; only regen under SunOS or AIX.

2 files changed, 328 insertions, 13 deletions

diff --git a/pkgtools/pkgdepgraph/Makefile b/pkgtools/pkgdepgraph/Makefile
index 15df3526dc3..c4d7feebf85 100644
--- a/pkgtools/pkgdepgraph/Makefile
+++ b/pkgtools/pkgdepgraph/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.14 2004/01/29 22:25:06 snj Exp $
+# $NetBSD: Makefile,v 1.15 2004/04/11 21:31:10 jschauma Exp $
 #
 
 DISTNAME=	pkgdepgraph-2.5
@@ -24,17 +24,10 @@ DISTVER=	${DISTNAME:S/pkgdepgraph-//}
 
 .include "../../mk/bsd.prefs.mk"
 
-.if ${OPSYS} == "SunOS"
-# This doesn't create readable manual pages. "mandoc" should be added
-# to zoularis.
-NROFF=		nroff -man
-.else
-NROFF=		nroff -mandoc
-.endif
-
 do-extract:
 	${CP} ${FILESDIR}/pkgdepgraph.pl ${WRKSRC}/pkgdepgraph.pl
 	${CP} ${FILESDIR}/pkgdepgraph.1 ${WRKSRC}/pkgdepgraph.1.in
+	${CP} ${FILESDIR}/pkgdepgraph.0 ${WRKSRC}/pkgdepgraph.0.in
 
 do-build:
 .for FILE in pkgdepgraph
@@ -45,13 +38,16 @@ do-build:
 		< ${WRKSRC}/${FILE}.pl 		\
 		> ${WRKSRC}/${FILE}
 .endfor
-.for FILE in pkgdepgraph
+.for FILE in pkgdepgraph.1 pkgdepgraph.0
 	${SED} -e 's|@PKG_DBDIR@|${PKG_DBDIR}|g'	\
 		-e 's|@PKGSRCDIR@|${_PKGSRCDIR}|g'	\
-		< ${WRKSRC}/${FILE}.1.in		\
-		> ${WRKSRC}/${FILE}.1
-	${NROFF} ${WRKSRC}/${FILE}.1 >${WRKSRC}/${FILE}.0
+		< ${WRKSRC}/${FILE}.in		\
+		> ${WRKSRC}/${FILE}
 .endfor
+.if ${OPSYS} == "SunOS" || ${OPSYS} == "AIX"
+	# the pre-generated man-pages are 'mandoc';  these OS need 'man'
+	nroff -man ${WRKSRC}/pkgdepgraph.1 > ${WRKSRC}/pkgdepgraph.0
+.endif
 
 do-install:
 	${INSTALL_SCRIPT} ${WRKSRC}/pkgdepgraph ${PREFIX}/bin/pkgdepgraph
diff --git a/pkgtools/pkgdepgraph/files/pkgdepgraph.0 b/pkgtools/pkgdepgraph/files/pkgdepgraph.0
new file mode 100644
index 00000000000..93cf704d79d
--- /dev/null
+++ b/pkgtools/pkgdepgraph/files/pkgdepgraph.0
@@ -0,0 +1,319 @@
+PKGDEPGRAPH(1)          NetBSD General Commands Manual          PKGDEPGRAPH(1)
+
+NNAAMMEE
+     ppkkggddeeppggrraapphh - visual representation of installed packages
+
+SSYYNNOOPPSSIISS
+     ppkkggddeeppggrraapphh [--AAaaCCccDDeeFFffggLLllooRRrrssvv] [--dd _p_k_g___d_b_d_i_r] [--KK _p_a_c_k_a_g_e_s] [--MM _m_a_k_e]
+                 [--mm _t_a_r_g_e_t] [--OO _p_a_c_k_a_g_e] [--PP _p_k_g_s_r_c_d_i_r] [--SS _p_a_c_k_a_g_e]
+                 [--tt _t_a_r_g_e_t] [--UU _p_a_c_k_a_g_e] [_d_a_t_a _._._.]
+
+DDEESSCCRRIIPPTTIIOONN
+     ppkkggddeeppggrraapphh emits a _d_o_t language description of the locally installed
+     packages, with the inter-dependencies reduced to a minimal set of edges.
+     It scans each directory under the package database directory for files
+     named _+_B_U_I_L_D___I_N_F_O and _+_R_E_Q_U_I_R_E_D___B_Y in order to gather its data.
+
+     ppkkggddeeppggrraapphh will also read any files passed to it as arguments (or stdin
+     if it is not connected to a tty), in search of output that resembles that
+     of either lintpkgsrc(1) --ii, audit-packages(1), or the output from a pre-
+     vious incantation of this program.
+
+     In the latter case, ppkkggddeeppggrraapphh will recolor the graph passed as input
+     based, as usual, on information about currently installed pkgs.  Packages
+     that are in the input graph, but not currently installed, will be colored
+     black, those that are installed will be colored green, and those that
+     remain out of date for some reason will remain red.
+
+     The graph defaults to black, but if data from lintpkgsrc(1) --ii or
+     _a_u_d_i_t_-_p_a_c_k_a_g_e_s is given, or if a specific package is asserted to be out
+     of date (via the --OO option), then nodes (and edges leading from them)
+     will be colored in the following manner:
+
+     green   The package is completely up to date.
+
+     orange  The package is up to date, but some of its dependencies require
+             updating.
+
+     red     The package is out of date or has had a security advisory issued
+             against it, and should be replaced.
+
+     purple  The package was not found in the local pkgsrc tree.
+
+     blue    The package depends on something not found in the local pkgsrc
+             tree.
+
+     black   The package has been removed and not yet replaced, or the graph
+             is uncolored.  The difference between an uncolored graph and a
+             graph that has been recolored almost entirely black as a result
+             of removing all the packages can be visually detected by the
+             color of the ppkkggddeeppggrraapphh package with which the graph was recol-
+             ored.
+
+     It is important to note that all installed packages fall into one (or
+     more) of the following categories:
+
+     installed    Any installed package.
+
+     out of date  Any package that can be upgraded.
+
+     stale        Any package that depends on a package that is out of date.
+
+     leaf         Any package that is not depended on by any other package.
+
+     Selecting the type or types of packages that are listed, and how the
+     information is put to use, can be controlled by the following options:
+
+     --AA       This option modifies the output of --RR to use pkg_add(1) to rein-
+              stall deleted packages, instead of building directly from the
+              pkgsrc tree.
+
+     --aa       All packages.  This option can be specified more than once to
+              augment the meaning of ``all'' as it relates to the selected
+              output mode.  For the default graph output, this option has no
+              effect.  When used with --mm where the default output is the list
+              of out of date packages, one --aa will make ppkkggddeeppggrraapphh also list
+              stale packages, and a second --aa will make it list all installed
+              packages.
+
+     --CC       Asserts --cc and adds ``CLEANDEPENDS=YES'' so that all rebuilt
+              dependencies are cleaned as well.
+
+     --cc       Inserts a ``make clean'' command in the set of instructions to
+              rebuild packages (see the --RR option) after they are installed.
+              The --cc option used to enable graph coloring, but now graph col-
+              oring is done automatically if any coloring data is given.
+
+     --DD       Instead of the standard graph output, ppkkggddeeppggrraapphh lists the
+              packages that need to be deleted, in ``least required first''
+              order, so that they can be deleted without any dependency prob-
+              lems.  This is a good first step to take before rebuilding all
+              your packages that are out of date (see the --RR option).  This
+              option is an alias for --aass.
+
+     --dd _p_k_g___d_b_d_i_r
+              The location of the package database files.  This defaults to
+              the value of the _P_K_G___D_B_D_I_R environment variable, if it is set,
+              or to _@_P_K_G___D_B_D_I_R_@.
+
+     --ee       Adds an ``existence check'' to each of the lines of sh(1) style
+              output so that commands can be skipped if the package is already
+              installed.
+
+     --FF       Makes ppkkggddeeppggrraapphh emit a series of sh(1) commands that will
+              fetch all the required distfiles for rebuilding out of date
+              packages.  This option is an alias for --mm _f_e_t_c_h.
+
+     --ff       Force a rebuild of all dependent packages.  This option is for
+              use in conjunction with the --UU option to force a rebuild of all
+              the dependencies of a package to be updated.
+
+     --gg       Add package subgraph groupings.  This places all packages with a
+              common prefix (e.g., ``p5'' or ``gimp'') in a subgraph with a
+              line around it so you can visually associate packages.
+
+     --KK _p_a_c_k_a_g_e_s
+              The base location or url from which to install binary packages.
+              This defaults to the value of PKG_PATH, or to PACKAGES with
+              ``/All'' added to the end, or to the value determined for pkgsr-
+              cdir (see the --PP option) with ``/packages/All'' appended to it.
+
+     --LL       Limit the graph to those packages that are out of date or ulti-
+              mately depend on some package that is.  When used with --mm or --ss,
+              this limits the list to ``leaf'' packages that are out of date
+              or stale.
+
+     --ll       Adds package ``location'' information to the labels on the
+              nodes.  This is the path to the package under the local pkgsrc
+              tree.
+
+     --MM _m_a_k_e  Sets the name or path of the proper make(1) program for the
+              sh(1) commands generated by the --RR and --FF options.  Some systems
+              may have more than one make(1) command or the correct choice
+              might not be named ``make''.  The default value for this is
+              taken from the MAKE environment variable, if it is set, or is
+              simply ``make''.
+
+     --mm _t_a_r_g_e_t
+              Emits generic sh(1) commands to ``make _t_a_r_g_e_t'' for each listed
+              package.  One interesting target to specify is _'_$_*_' since that
+              will yield a script that will pass its own command line argu-
+              ments to make for processing.
+
+     --OO _p_a_c_k_a_g_e
+              Marks _p_a_c_k_a_g_e as out of date so that you can see the impact of
+              deleting dependent packages and rebuilding everything.  This
+              option can be used as a quick alternative to using the output
+              from lintpkgsrc(1) --ii for graph coloring information.
+
+     --oo       Adds a package ``order'' number to each node's label.  The num-
+              ber indicates only the place of the node in the hierarchy, such
+              that each node has a number greater than that of anything which
+              depends on it, and with the ``leaf'' nodes numbered one.
+
+     --PP _p_k_g_s_r_c_d_i_r
+              The root of the pkgsrc source tree.  This defaults to the value
+              of the _P_K_G_S_R_C_D_I_R environment variable, if it is set, or to
+              _@_P_K_G_S_R_C_D_I_R_@.
+
+     --RR       Instead of the standard graph output, emits a series of sh(1)
+              commands that will rebuild all the out of date packages by
+              rebuilding all the deleted leaf packages.  Packages that are out
+              of date should be deleted first (see the --DD option).  This
+              option is an alias for --eeLLmm _t_a_r_g_e_t.  See the --tt option for a
+              description of what value is used for _t_a_r_g_e_t.
+
+     --rr       Reverses the order in which the packages are listed.
+
+     --SS _p_a_c_k_a_g_e
+              Selects a subgraph of the installed package base around which to
+              generate output.  By default, if a subgraph of _p_a_c_k_a_g_e is
+              requested, only _p_a_c_k_a_g_e and those packages immediately above and
+              below it in the graph will be listed.  To select only those
+              immediately below, prefix a ``-'' to the package name.  To
+              select all packages below _p_a_c_k_a_g_e, prefix ``--'' to the package
+              name.  To select packages above _p_a_c_k_a_g_e, use ``+'' and ``++'' as
+              appropriate.  To select all packages remotely connected to
+              _p_a_c_k_a_g_e, add ``='' to the beginning.  Note: take care when using
+              this option with generated lists or sh scripts.  Since the sub-
+              graph of packages selected by this option may not include all
+              stale or out of date packages involved in a proper package
+              update procedure, the lists may be incomplete and can cause
+              problems.
+
+     --ss       Print a simple list of packages instead of sh commands.  The
+              default output set for this command is out of date packages from
+              the entire package set.  Use combinations of --aa, --LL, --OO _p_a_c_k_a_g_e,
+              and --SS _p_a_c_k_a_g_e to select more or other package lists.
+
+     --tt _t_a_r_g_e_t
+              Changes the target of the --RR output from ``install'' to _t_a_r_g_e_t
+              in case you want to ``make package'' or some other target.
+
+     --UU _p_a_c_k_a_g_e
+              Generates a graph with only the out of date dependencies of
+              _p_a_c_k_a_g_e marked in red (ie, packages that are out of date but not
+              dependencies of _p_a_c_k_a_g_e will not be considered out of date).
+              This will show the entire effect of deleting all related pack-
+              ages in order to update the dependencies of the given package.
+              If the --ff option is used, then all the dependencies of _p_a_c_k_a_g_e
+              will be marked as out of date and the effect on the installed
+              package base will be accordingly greater.
+
+     --vv       Adds the package version number to the node's label in the
+              graph.
+
+EENNVVIIRROONNMMEENNTT
+   MMAAKKEE
+     The default name for the ``make'' program used in the sh(1) commands gen-
+     erated by the --FF and --RR output modes.
+
+   PPKKGG__DDBBDDIIRR
+     Where to find registered packages instead of _@_P_K_G___D_B_D_I_R_@.
+
+   PPKKGGSSRRCCDDIIRR
+     Where the pkgsrc tree is located instead of _@_P_K_G_S_R_C_D_I_R_@.
+
+   PPKKGG__PPAATTHH
+   PPAACCKKAAGGEESS
+     Two variables that can be used as a location for binary packages.  See
+     the --AA and --KK options for more details.
+
+EEXXAAMMPPLLEESS
+     The default output:
+
+           $ pkgdepgraph | dotty -
+
+     To generate graph output for later use, and a postscript image of it:
+
+           $ lintpkgsrc -i > pkgdepgraph.in
+           $ audit-packages >> pkgdepgraph.in
+           $ pkgdepgraph -lv pkgdepgraph.in > pkgdepgraph.dot
+           $ dot -Tps pkgdepgraph.dot > pkgdepgraph.ps
+
+     To generate a graph of just the out of date nodes as a gif:
+
+           $ pkgdepgraph -L pkgdepgraph.in > out-of-date.dot
+           $ dot -Tgif out-of-date.dot > out-of-date.gif
+
+     To make a list of packages that need to be removed in order to bring all
+     packages up to date:
+
+           $ pkgdepgraph -D pkgdepgraph.in > delete_order
+           $ pkgdepgraph -R pkgdepgraph.in > rebuild.sh
+
+     To subsequently delete all out of date and stale packages:
+
+           $ pkg_delete `cat delete_order`
+           $ sh rebuild.sh
+
+     You may also find it useful to ``pre-fetch'' all the required distfiles
+     for the rebuild as below, so that you can do all the rebuilding while
+     off-line:
+
+           $ pkgdepgraph -F pkgdepgraph.in > fetch.sh
+           $ sh fetch.sh
+
+     Running the rebuild script will probably take a while, but if you need to
+     stop it or it stops by itself for any reason, you can rerun the script,
+     and it will pick up where it left off.  If there are certain packages
+     that you want installed before others are reinstalled, feel free to
+     reorder the lines in the script.
+
+     You can also ``make clean'' wherever you like when the rebuild script is
+     not running, or even update your tree in between runs of the script,
+     though in the latter case, it would be prudent to resume the script in
+     the following manner so that any packages that are newly out of date are
+     removed and replaced.
+
+           $ pkgdepgraph -D pkgdepgraph.in > delete_order
+           $ pkgdepgraph -R pkgdepgraph.in >> rebuild.sh
+           $ pkg_delete `cat delete_order`
+           $ sh rebuild.sh
+
+     It is important to note that if you have specifically installed a partic-
+     ular package that is a dependency, and another package (or other pack-
+     ages) exist that can satisfy the same dependency, you should probably
+     pre-install that particular package.  There is no guarantee that the typ-
+     ical processing order will install the same package.
+
+     A similar task is to update all the out of date dependencies of an pack-
+     age, rebuild the package, and any others that might share the same depen-
+     dencies:
+
+           $ pkgdepgraph -U mozilla -D pkgdepgraph.in > delete_order
+           $ pkgdepgraph -U mozilla -R pkgdepgraph.in > rebuild.sh
+           $ pkg_delete `cat delete_order`
+           $ sh rebuild.sh
+
+     Or perhaps to rebuild a specific package and all packages which depend on
+     it:
+
+           $ pkgdepgraph -O glib -D > delete_order
+           $ pkgdepgraph -O glib -R > rebuild.sh
+           $ pkg_delete `cat delete_order`
+           $ sh rebuild.sh
+
+     Finally, to see the current state of the installed packages after some
+     packages have been deleted, and some (but perhaps not all) have been
+     reinstalled:
+
+           $ pkgdepgraph out-of-date.dot | dot -Tps > current.ps
+
+SSEEEE AALLSSOO
+     dot(1), dotty(1), lintpkgsrc(1)
+
+AAUUTTHHOORRSS
+     Andrew Brown <atatat@netbsd.org>
+
+BBUUGGSS
+     ppkkggddeeppggrraapphh was written in perl(1), but I believe the balance of code
+     layout and comments is actually reasonable, despite what you may think of
+     perl.
+
+     The ``rebuild'' output, ``fetch'' output, and the generic ``make target''
+     output (see the --RR, --FF, and --mm options) do not deal very well with pack-
+     ages that have moved within the pkgsrc tree.  It is necessary that you
+     edit the rebuild script by hand to work around this.
+
+NetBSD 1.6                       March 6, 2003                      NetBSD 1.6