Misc textual fixes/changes to the man pages

Fixed the NAME sections and man page cross references; tried to make
VARIABLES reflect whether they were used in an expanded sense or not;
changed an .IP list with non-standard bullets to a .TP with standard;
added standard NOTES section to sbopkg.conf and changed the .SH under it
to .SS and also changed the INSTRUCTIONS .SH in sbopkg(8) to an .SS of
DESCRIPTION; changed the FILES section from dashed .PP to undashed .TPs,
and changed the font to .I; changed the SEE ALSO section by removing
quotes, adding commas, reducing individual file references to the
general doc dir which was given a full path and changing its font to
.IR; and redid the tags in the OPTIONS section of sbopkg(8), making
replaceable args italic, changing the dashes, adding the missing
argument to the -f option.

src/usr/doc/HACKING

@@ -242,3 +242,11 @@ Manual Page Style Guidelines
 * Leave no blank lines in the file. E.g., .PP will often serve under .SH and
   .IP under .TP.
 * Wrap lines at 72 columns and begin all sentences on new lines.
+* If variables are being used in the sense of their value, use $VAL but if
+  they are being used in reference to themselves, use VAR.
+* Where sensible, try to make .TPs have a consistent indent.
+* Try to use standard headers where possible, filing other information
+  under subsections of the relevant section header.
+* Add options as .TP 5 (or current default), with \- and bold options,
+  followed by italic replaceable arguments to those options or bold literal
+  arguments, if any.

src/usr/man/man5/sbopkg.conf.5

@@ -2,17 +2,16 @@
 .TH SBOPKG.CONF 5 "May 2010" sbopkg-SVN ""
 .\"=====================================================================
 .SH NAME
-.B sbopkg.conf
+sbopkg.conf \- configuration file for sbopkg
-\- Configuration file for sbopkg
 .\"=====================================================================
 .SH DESCRIPTION
 The sbopkg.conf file contains configuration settings for
-.B sbopkg
+.BR sbopkg (8),
-(8), a tool for interacting with the SlackBuilds.org ("SBo") repository,
+a tool for interacting with the SlackBuilds.org ("SBo") repository, a
-a collection of third-party SlackBuild scripts to build Slackware
+collection of third-party SlackBuild scripts to build Slackware
 packages.
 A sample file is provided at /etc/sbopkg/sbopkg.conf.new.
-Also, please see a note below about $ARCH.
+Also, please see a note below about ARCH.
 .PP
 Boolean options are case-insensitive.
 .PP
@@ -150,19 +149,24 @@ by yourself doing improper things.
 .IP
 For reference, these are some of the things you shouldn't do with this
 option enabled:
-.RS 6
+.RS 5
-.IP \[bu] 2
+.TP 3
+\(bu
 run an ALLOW_MULTI=NO instance together with one or more having
 ALLOW_MULTI=YES
-.IP \[bu]
+.TP
+\(bu
 sync a repository when another instance is using it
-.IP \[bu]
+.TP
+\(bu
 change the branch of a git repository when another instance is using it
 (you can do this with rsync -- i.e. SlackBuild.org -- repos)
-.IP \[bu]
+.TP
+\(bu
 simultaneously build or install the same package from different
 instances
-.IP \[bu]
+.TP
+\(bu
 save a queue file while using it from another instance
 .RE
 .IP
@@ -244,7 +248,9 @@ The default value of DIFFOPTS is:
 .IP
 DIFFOPTS=${DIFFOPTS:--u}
 .\"=====================================================================
-.SH OVERRIDING ENVIRONMENTAL VARIABLES
+.SH NOTES
+.\"---------------------------------------------------------------------
+.SS Overriding Environmental Variables
 It is possible to set or override environmental variables and pass them
 to the SlackBuild scripts when they are built from within sbopkg.
 This is already demonstrated in the following line in the sbopkg.conf
@@ -252,15 +258,15 @@ file:
 .PP
 export TMP=${TMP:-/tmp/SBo}
 .PP
-This sets $TMP to /tmp/SBo for building SBo packages within sbopkg
+This sets TMP to /tmp/SBo for building SBo packages within sbopkg (which
-(which is currently the default for SBo SlackBuilds already).
+is currently the default for SBo SlackBuilds already).
 Since this variable is exported, it could be changed for both sbopkg and
 for building SBo packages within sbopkg.
 For example, changing this line so it reads:
 .PP
 export TMP=${TMP:-/home/sbo/tmp}
 .PP
-would then set $TMP to /home/sbo/tmp for building SBo packages.
+would then set TMP to /home/sbo/tmp for building SBo packages.
 OUTPUT can also be changed to save compiled packages in a location other
 than the default of /tmp.
 .PP
@@ -269,8 +275,8 @@ is ignored.
 .PP
 You can also export variables in sbopkg.conf that are not used by sbopkg
 at all.
-.\"=====================================================================
+.\"---------------------------------------------------------------------
-.SH ABOUT THE ARCH VARIABLE
+.SS About the ARCH Variable
 You may be wondering why ARCH is not a configuration setting in the
 default sbopkg.conf file.
 The reason is that it does not have to be.
@@ -291,25 +297,24 @@ Note that the SlackBuild may, in certain instances, discard or override
 previous ARCH settings if this is required for the build.
 .\"=====================================================================
 .SH FILES
-.B /etc/sbopkg/sbopkg.conf
+.TP 3
-\ - File to specify configuration options.
+.I /etc/sbopkg/sbopkg.conf
-.PP
+File to specify configuration options.
-.B /etc/sbopkg/renames.d/50-default
+.TP
-\ - Default file that lists software in SBo repository that has been
+.I /etc/sbopkg/renames.d/50-default
+Default file that lists software in SBo repository that has been
 renamed.
 See the README-renames.d document in the sbopkg doc/ directory for more
 information.
-.PP
+.TP
-.B /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
+.I /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
-\ - Three default files for various types of sbopkg repositories.
+Three default files for various types of sbopkg repositories.
 See the README-repos.d document in the sbopkg doc/ directory for more
 information.
 .\"=====================================================================
-.SH "SEE ALSO"
+.\" Make the release process handle a DOCDIR here? But the files from
-.BR sbopkg (8)
+.\" the official tarball go here.
-.BR doc/README
+.SH SEE ALSO
-.BR doc/README-queuefiles
+.BR sbopkg (8),
-.BR doc/README-renames.d
+.IR /usr/doc/sbopkg-SVN/*
-.BR doc/README-repos.d
-.BR doc/queuefiles/*
 .\" vim:set tw=72:

src/usr/man/man8/sbopkg.8

@@ -2,19 +2,18 @@
 .TH SBOPKG 8 "May 2010" sbopkg-SVN ""
 .\"=====================================================================
 .SH NAME
-.B sbopkg
+sbopkg \- the SlackBuilds.org package browser
-\ - The SlackBuilds.org Package Browser
 .\"=====================================================================
 .SH SYNOPSIS
 .B sbopkg
-.B [options]
+.RI [ options ]
 .\"=====================================================================
 .SH DESCRIPTION
 Sbopkg is a command-line and dialog-based tool to interact with the
 SlackBuilds.org ("SBo") repository, a collection of third-party
 SlackBuild scripts to build Slackware packages.
 .\"=====================================================================
-.SH INSTRUCTIONS
+.SS Instructions
 Sbopkg usage assumes an understanding of SlackBuild scripts, generally,
 and the third-party repository SlackBuilds.org, specifically.
 A thorough reading of http://www.slackbuilds.org/howto/ and the pages at
@@ -24,16 +23,16 @@ Before sbopkg can be used, a configuration file must be created at
 /etc/sbopkg/sbopkg.conf.
 A sample file is provided at /etc/sbopkg/sbopkg.conf.new.
 See
-.B sbopkg.conf
+.BR sbopkg.conf (5)
-(5) for more information about the configuration file.
+for more information about the configuration file.
 .PP
 Sbopkg can be run from the command line by simply invoking "sbopkg."
 Sbopkg must be run as the root user (since the SlackBuild scripts at
 SlackBuilds.org are written with the intention of being run as root).
 Furthermore, using 'su -' instead of 'su' is strongly encouraged.
 The reason is that some SlackBuild scripts rely on certain tools that
-are only available in root's $PATH when root's $PATH is inherited (i.e.
+are only available in root's PATH when root's PATH is inherited (i.e.
-texmf to build man pages) and root's $PATH is not inherited when only
+texmf to build man pages) and root's PATH is not inherited when only
 using 'su'.
 In any evnet, invoking 'sbopkg' from the command line will launch the
 dialog-based interface, and the menus provided should be fairly
@@ -84,19 +83,19 @@ information.
 Certain features of sbopkg rely on outside binaries, such as a pager to
 view the text files when sbopkg is run from the comamnd line, and an
 editor to edit the .info or SlackBuild files.
-The pager function will look to the environmental variable $PAGER and if
+The pager function will look to the environmental variable PAGER and if
 that variable is not defined then it will default to 'more.'
 Similarly, the edit function found when sbopkg is used with the dialog
-interface will look to $EDITOR and will default to 'vi' if no $EDITOR
+interface will look to the EDITOR variable and will default to 'vi' if
-has been defined.
+EDITOR is undefined.
-If the user wants sbopkg to use another $EDITOR, such as nano, then
+If the user wants sbopkg to use another editor, such as nano, then
 adding the requisite information in ~/.bashrc, /etc/profile, or other
-similar configuration file to export $EDITOR will suffice.
+similar configuration file to export EDITOR will suffice.
 .\"=====================================================================
 .SH OPTIONS
 .\"---------------------------------------------------------------------
 .TP 5
-.B -b PACKAGE(s)/QUEUE(s)
+.BI \-b " PACKAGE(s)/QUEUE(s)"
 Search for and build PACKAGE(s) from the local SBo repository.
 If more than one package is specified, they must be in quotes.
 For example:
@@ -116,16 +115,16 @@ If a package is specified more than once, it gets queued only the first
 time it is encountered.
 .\"---------------------------------------------------------------------
 .TP
-.B -c
+.B \-c
 Display list of installed SBo packages and potential updates.
 .\"---------------------------------------------------------------------
 .TP
-.B -d DIRECTORY
+.BI \-d " DIRECTORY"
 Manually specify the full path to the DIRECTORY containing the local SBo
 repository.
 .\"---------------------------------------------------------------------
 .TP
-.B -e ask|continue|stop
+.B \-e \fBask\fR|\fBcontinue\fR|\fBstop
 Specify what sbopkg should do when it encounters an error while building
 a package.
 Valid options are:
@@ -142,12 +141,12 @@ Valid options are:
 questions).
 .\"---------------------------------------------------------------------
 .TP
-.B -f
+.BI \-f " FILE"
 Override the default configuration file, which is located by default at
 /etc/sbopkg/sbopkg.conf, with another configuration file.
 .\"---------------------------------------------------------------------
 .TP
-.B -g PACKAGE(s)
+.BI \-g " PACKAGE(s)"
 General search for PACKAGE(s) by glob.
 For example:
 .IP
@@ -158,11 +157,11 @@ konversation, and other packages with 'nv' in their name.
 If more than one glob is specified, they must be in quotes.
 .\"---------------------------------------------------------------------
 .TP
-.B -h
+.B \-h
 Display the help.
 .\"---------------------------------------------------------------------
 .TP
-.B -i PACKAGE(s)
+.BI \-i " PACKAGE(s)"
 Search for and build and then install PACKAGE(s) from the local SBo
 repository.
 If more than one package is specified, they must be in quotes, and the
@@ -184,7 +183,7 @@ Queuefile names are supported, too.
 See the explanation for the '-b' command for details.
 .\"---------------------------------------------------------------------
 .TP
-.B -k
+.B \-k
 When used together with -b or -i, this option tells sbopkg to skip (i.e.
 don't build) any package it finds to be already installed.
 .IP
@@ -193,11 +192,11 @@ option is specified sbopkg will also omit the build of different
 versions of installed packages.
 .\"---------------------------------------------------------------------
 .TP
-.B -l
+.B \-l
 Display the SBo ChangeLog.txt and quit.
 .\"---------------------------------------------------------------------
 .TP
-.B -o
+.B \-o
 List the currently installed cached source files which are deemed as
 obsolete, and optionally delete them.
 .IP
@@ -210,32 +209,32 @@ repositories (e.g. for different Slackware versions) the source files
 only used in the "other" repository will be listed.
 .\"---------------------------------------------------------------------
 .TP
-.B -P
+.B \-P
 List the cached package files which are not currently installed on the
 system and optionally delete them.
 .\"---------------------------------------------------------------------
 .TP
-.B -p
+.B \-p
 List installed SlackBuilds.org packages.
 .\"---------------------------------------------------------------------
 .TP
-.B -q
+.B \-q
 Enable the "quiet mode."
 When this flag is specified, the output of some of the command-line
 options is minimized.
 .\"---------------------------------------------------------------------
 .TP
-.B -r
+.B \-r
 Rsync the local repository with SlackBuilds.org and quit.
 .\"---------------------------------------------------------------------
 .TP
-.B -R
+.B \-R
 Show all the README files of the queued packages before starting the
 build.
 This is useful when you want to make a final check.
 .\"---------------------------------------------------------------------
 .TP
-.B -s PACKAGE(s)
+.BI \-s " PACKAGE(s)"
 Specific search for PACKAGE(s) by PACKAGE name and, if found, display
 the README, SlackBuild, .info, and slack-desc files in that order using
 $PAGER, which defaults to 'more' as described above.
@@ -247,17 +246,17 @@ For example:
 will search for foo and then bar.
 .\"---------------------------------------------------------------------
 .TP
-.B -u
+.B \-u
 Check for an update to sbopkg itself and then quit.
 .\"---------------------------------------------------------------------
 .TP
-.B -V REPO/BRANCH
+.BI \-V " REPO/BRANCH"
 Set the repository and branch to use.
 .IP
 For a list of valid versions, invoke sbopkg as
 .BR "sbopkg -V ?" .
 See the
-.B sbopkg.conf (5)
+.BR sbopkg.conf (5)
 man page for more information about the 'local' repository.
 .IP
 The VERSION format is repository/branch (e.g. SBo/13.1).
@@ -267,31 +266,30 @@ If that attempt fails, sbopkg will look for the first matching branch in
 any repository.
 .\"---------------------------------------------------------------------
 .TP
-.B -v
+.B \-v
 Prints the current version of sbopkg on stdout.
 .\"=====================================================================
 .SH FILES
-.B /etc/sbopkg/sbopkg.conf
+.TP 5
-\ - File to specify configuration options.
+.I /etc/sbopkg/sbopkg.conf
-.PP
+File to specify configuration options.
-.B /etc/sbopkg/renames.d/50-default
+.TP
-\ - Default file that lists software in SBo repository that has been
+.I /etc/sbopkg/renames.d/50-default
+Default file that lists software in SBo repository that has been
 renamed.
 See the README-renames.d document in the sbopkg doc/ directory for more
 information.
-.PP
+.TP
-.B /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
+.I /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
-\ - Three default files for various types of sbopkg repositories.
+Three default files for various types of sbopkg repositories.
 See the README-repos.d document in the sbopkg doc/ directory for more
 information.
 .\"=====================================================================
-.SH "SEE ALSO"
+.\" Make the release process handle a DOCDIR here? But the files from
-.BR sbopkg.conf (5)
+.\" the official tarball go here.
-.BR doc/README
+.SH SEE ALSO
-.BR doc/README-queuefiles
+.BR sbopkg.conf (5),
-.BR doc/README-renames.d
+.IR /usr/doc/sbopkg-SVN/*
-.BR doc/README-repos.d
-.BR doc/queuefiles/*
 .\"=====================================================================
 .SH AUTHOR
 Chess Griffin