Improve documentation.

3 files changed, 68 insertions, 45 deletions

diff --git a/pkgtools/revbump/files/check-cvs-diff.1 b/pkgtools/revbump/files/check-cvs-diff.1
index 4c75ee6c96f..e017da8fecd 100644
--- a/pkgtools/revbump/files/check-cvs-diff.1
+++ b/pkgtools/revbump/files/check-cvs-diff.1
@@ -1,4 +1,4 @@
-.\"	$NetBSD: check-cvs-diff.1,v 1.1 2014/12/15 23:25:54 mef Exp $
+.\"	$NetBSD: check-cvs-diff.1,v 1.2 2014/12/16 11:38:54 wiz Exp $
 .\"
 .\" Copyright (c) 2003, 2004, 2005 The NetBSD Foundation, Inc.
 .\"
@@ -31,24 +31,26 @@
 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 14, 2014    
+.Dd December 14, 2014
 .Dt CHECK-CVS-DIFF 1
 .Os
 .Sh NAME
 .Nm check-cvs-diff
-.Nd tool to check if revbump process described in revbump(1) results including py27, py34 or ruby200
-in the files. And then replaces the strings by the variable notation.
+.Nd clean up unintended revbump(1) replacements
 .Sh SYNOPSIS
 .Nm
-.Op Fl h
+.Op Fl hv
 .Op Fl p Ar pkgsrcdir
-.Op Fl v
-cvs-diff-u_output-file
+.Ar cvs-diff-u_output-file
 .Sh DESCRIPTION
 .Nm
 is a perl script for pkgsrc developers that simplifies checking and replacing fixed
-version number in revbump resultant tree, Makefile and buildlink3.mk files.
-It reads `cvs diff -u' output written in named file, and if above mentioned strings found in the diff, replaces it in corresponding file by apropriate variable notation.
+version number in
+.Xr revbump 1
+resultant tree, Makefile and buildlink3.mk files.
+It reads `cvs diff -u' output written in named file, and if above
+mentioned strings are found in the diff, replaces them in corresponding
+file by the appropriate variables.
 .Pp
 .Nm Fl h
 displays a short usage.
@@ -63,15 +65,15 @@ is used instead of the default
 If
 .Fl v
 is given,
-it outputs some verbose information.
-
+.Nm
+outputs more verbose information.
+.Pp
 .Nm
 prints the package name
 (in
 .Ar category/package
 form) on stdout for each package where it failed, but usually none.
-
 .Sh SEE ALSO
-.Xr revbump 1 ,
 .Xr finddepends 1 ,
-.Xr replace-commonbump 1
+.Xr replace-commonbump 1 ,
+.Xr revbump 1
diff --git a/pkgtools/revbump/files/replace-commonbump.1 b/pkgtools/revbump/files/replace-commonbump.1
index d5fddfa9e2c..4772e1996c3 100644
--- a/pkgtools/revbump/files/replace-commonbump.1
+++ b/pkgtools/revbump/files/replace-commonbump.1
@@ -1,4 +1,4 @@
-.\"	$NetBSD: replace-commonbump.1,v 1.1 2014/12/15 23:25:54 mef Exp $
+.\"	$NetBSD: replace-commonbump.1,v 1.2 2014/12/16 11:38:54 wiz Exp $
 .\"
 .\" Copyright (c) 2014 The NetBSD Foundation, Inc.
 .\"
@@ -36,17 +36,25 @@
 .Os
 .Sh NAME
 .Nm replace-commonbump
-.Nd tool to help expanding (replacing) commonbump file to the real list of Makefile's.
+.Nd tool to help expanding (replacing) commonbump file to the real list of Makefiles
 .Sh SYNOPSIS
 .Nm
-.Op Fl a
-.Op Fl h
+.Op Fl ah
 .Op Fl p Ar pkgsrcdir
 .Op Fl T Ar list_file
 .Sh DESCRIPTION
 .Nm
-is a perl script for pkgsrc developers. It simplifies the process expanding
-`commonbump' file into `commonbump-replace'. Commonbump file is to be created by the first stage of revbump process, as is described in revbump(1).
+is a perl script for pkgsrc developers.
+It simplifies the process expanding
+.Pa commonbump
+file into
+.Pa commonbump-replace .
+The
+.Pa commonbump
+file is to be created by the first stage of the
+.Dv PKGREVISION
+bump process as described in
+.Xr revbump 1 .
 .Pp
 .Nm Fl h
 displays a short usage.
@@ -61,46 +69,59 @@ is used instead of the default
 If
 .Fl a
 is given,
-check all pkgsrc tree, disregard neither to
+check the whole pkgsrc tree, disregard both the
 .Fl T
-option nor to the default `commonbump' file.
-It will check if "# used by" is included or not, usually in Makefile.common in the package.
+option and the default
+.Pa commonbump
+file.
+It will check if
+.Dq # used by
+is included or not, usually in Makefile.common in the package.
 .Pp
 If
 .Fl T
 is given,
 .Ar list_file
 is used instead of the default
-.Pa `commonbump' .
+.Pa commonbump .
 .Pp
 .Nm
 prints the package name
 (in
 .Ar category/package
 form) on stdout for each package where it failed, but usually none.
-
+.Pp
 The internal process is divided into three stages.
-
-.item
-(1)
-Read entire pkgsrc tree and check a
+.Bl -enum
+.It
+Read entire pkgsrc tree and check the
 .Ar referer -> referenced
 relation,
 then internally keeps (opposite)
 .Ar referenced -> referer
 relation table.
-
-.item
-(2) Read a file, named `commonbump' or the other name given with -T, which
-usually lists Makefile.common or *common.mk files to be expanded.
-
-.item
-(3) Now expands the filename listed in `commonbump' into the list of packagename/Makefile by
-referenced -> referer relation. It then outputs to the file
-`commonbump.replaced' (currently the name is fixed).
-
+.It
+Read a file, named
+.Pa commonbump
+or the argument given with
+.Fl T ,
+which usually lists
+.Pa Makefile.common
+or
+.Pa *common.mk
+files to be expanded.
+.It
+Expand the filenames listed in
+.Pa commonbump
+into the list of packagename/Makefile by the
+referenced -> referer relation.
+.Nm
+then outputs to the file
+.Pa commonbump.replaced
+(currently the name is fixed).
+.El
 .Sh SEE ALSO
-.Xr revbump 1 ,
 .Xr blbump 1 ,
 .Xr check-cvs-diff 1 ,
-.Xr finddepends 1
+.Xr finddepends 1 ,
+.Xr revbump 1
diff --git a/pkgtools/revbump/files/revbump.1 b/pkgtools/revbump/files/revbump.1
index 5cd4f6a8128..ae3306dd133 100644
--- a/pkgtools/revbump/files/revbump.1
+++ b/pkgtools/revbump/files/revbump.1
@@ -1,4 +1,4 @@
-.\"	$NetBSD: revbump.1,v 1.22 2014/12/15 23:25:54 mef Exp $
+.\"	$NetBSD: revbump.1,v 1.23 2014/12/16 11:38:54 wiz Exp $
 .\"
 .\" Copyright (c) 2003, 2004, 2005, 2006, 2010, 2012, 2013, 2014 The NetBSD Foundation, Inc.
 .\"
@@ -96,12 +96,12 @@ blbump \*[Lt] bl3bump | tee bl3bump.manual ;
 # [handle the *ABI_DEPENDS* bumps in bl3bump.manual manually, usually none] ;
 cvs diff -u `cat makebump` > cvs-diff ;
 check-cvs-diff  ;
-cvs diff `cat bl3bump makebump` | less 
+cvs diff `cat bl3bump makebump` | less
 cvs commit `cat bl3bump makebump`
 rm allbump bl3bump* makebump* commonbump* cvs-diff
 .Ed
 .Sh SEE ALSO
 .Xr blbump 1 ,
+.Xr check-cvs-diff 1 ,
 .Xr finddepends 1 ,
-.Xr replace-commonbump 1,
-.Xr check-cvs-diff 1 
+.Xr replace-commonbump 1