Mostly font changes to both man pages

Also added several more points to HACKING which cover most of the other
changes - there are a few semantic/textual changes in here, too. The
largest changes are probably a making the 'type' of the conf values a
part of the 'template', moving and adding complete authors to both

src/usr/doc/HACKING

@@ -257,3 +257,24 @@ Manual Page Style Guidelines
 * Try to be as specific as conveniently possible, where 'convenient' means to
   generalize wherever constant updates might be necessary and such
   generalization wouldn't compromise clarity and accuracy.
+* Italicize filenames, URLs, replaceable terms (including references to
+  unspecified variable values ($VARs).
+* Embolden variables (when used literally rather than replaceably), option
+  values, programs, program flags, and all references to sbopkg itself.
+* Use `` and '' for double-quotes so groff does the fancy stuff for ps output.
+* Make all option dashes in the form \- (or \-\-) unless in a code example.
+* .EX doesn't seem to be very well supported or necessarily what is wanted -
+  code examples can be done with the following cookie-cutter code:
+    .RS
+    .IP \" or .PP or whatever's appropriate
+    .nf
+    \fCline_of_code\fP
+    .fi
+    .RE
+  If inline, at least embolden them so they're set off in ascii overstrike
+  output.
+* Start configuration file option sections with a statement of type, a
+  description, and the following cookie-cutter code:
+    The default assignment is:
+    .IP
+    \fCdefault_assignment\fP

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

@@ -5,29 +5,39 @@
 sbopkg.conf \- configuration file for sbopkg
 .\"=====================================================================
 .SH DESCRIPTION
-The sbopkg.conf file contains configuration settings for
+The
+.I sbopkg.conf
+file contains configuration settings for
 .BR sbopkg (8),
-a tool for interacting with the SlackBuilds.org ("SBo") repository, a
+a tool for interacting with the SlackBuilds.org (``SBo'') repository, a
 collection of third-party SlackBuild scripts to build Slackware
 packages.
-A sample file is provided at /etc/sbopkg/sbopkg.conf.new.
+The default configuration file is installed at
-Also, please see a note below about ARCH.
+.IR /etc/sbopkg/sbopkg.conf .
+Also, please see the subsection below about
+.BR ARCH .
 .PP
-Boolean options are case-insensitive.
+All boolean options require a
+.B YES
+or a
+.B NO
+without regard to case. All path values must be full.
 .PP
-The different configuration options are:
+The default configuration options are:
 .\"---------------------------------------------------------------------
 .TP 3
 .B ALLOW_MULTI
-This option should be set to YES or NO.
+Boolean.
-When set to YES, this option allows the user to run multiple instances
+.IP
-of sbopkg.
+When set to
+.BR YES ,
+this option allows the user to run multiple instances of
+.BR sbopkg .
 .IP
 Please understand that this option is provided for convenience, but
 given the number of potential issues you can face when enabling this
 (and we aren't going to try to work around users doing silly things),
-you should consider working with ALLOW_MULTI=YES as an EXPERIMENTAL
+you should consider this an EXPERIMENTAL UNSUPPORTED feature.
-UNSUPPORTED feature.
 If you encounter problems, please try to make sure these aren't caused
 by yourself doing improper things.
 .IP
@@ -36,15 +46,18 @@ option enabled:
 .RS 5
 .TP 3
 \(bu
-run an ALLOW_MULTI=NO instance together with one or more having
+run instances with a mixture of
-ALLOW_MULTI=YES
+.B YES
+and
+.B NO
+settings
 .TP
 \(bu
 sync a repository when another instance is using it
 .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)
+(this caveat does not apply to rsync repositories)
 .TP
 \(bu
 simultaneously build or install the same package from different
@@ -63,13 +76,27 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B CLEANUP
-This option should be set to YES or NO.
+Boolean.
-When set to YES, the unpacked source files and package tree in $TMP are
-deleted right after the build, though the downloaded source archive and
-completed package are left in $SRCDIR and $OUTPUT.
 .IP
-A side effect of setting CLEANUP to YES is that TMP is set to an
+When set to
-internal value and any other TMP setting is ignored.
+.BR YES ,
+the unpacked source files and package tree in
+.I $TMP
+are deleted right after the build, though the downloaded source archive
+and completed package are left in
+.I $SRCDIR
+and
+.IR $OUTPUT .
+.IP
+A side effect of setting
+.B CLEANUP
+to
+.B YES
+is that
+.B TMP
+is set to an internal value and any other
+.B TMP
+setting is ignored.
 .IP
 The default assignment is:
 .IP
@@ -77,16 +104,33 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B DEBUG
-This option should be set to 0, 1, or 2.
+Enumeration.
-DEBUG sets the default debugging level for the update list feature of
+.IP
-sbopkg.
+This option should be set to
-When DEBUG is set to 0, then only potential updated (or downgraded)
+.BR 0 ,
-packages are listed.
+.BR 1 ,
-When DEBUG is set to 1, then potential updates plus packages not in the
+or
-repo and packages that are newer than the repo are listed.
+.BR 2 .
-When DEBUG is set to 2, all non-updated packages are also listed.
+.B DEBUG
-Changing DEBUG to 1 or 2 may be helpful if it appears the updatelist
+sets the default debugging level for the update list feature of
-might be missing an update.
+.BR sbopkg .
+When set to
+.BR 0 ,
+only potential updated (or downgraded) packages are listed.
+When set to
+.BR 1 ,
+potential updates plus packages not in the repo and packages that are
+newer than the repo are listed.
+When set to
+.BR 2 ,
+all non-updated packages are also listed.
+Changing
+.B DEBUG
+to
+.B 1
+or
+.B 2
+may be helpful if it appears the updatelist might be missing an update.
 .IP
 The default assignment is:
 .IP
@@ -94,7 +138,10 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B DIFF
-This option allows the user to set which diff program to use when sbopkg
+Command.
+.IP
+This option allows the user to set which diff program to use when
+.B sbopkg
 displays differences between edited files.
 .IP
 The default assignment is:
@@ -103,8 +150,13 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B DIFFOPTS
-This option allows the user to set which options are used by the $DIFF
+Command options.
-program when sbopkg displays differences between edited files.
+.IP
+This option allows the user to set which options are used by the
+.I $DIFF
+program when
+.B sbopkg
+displays differences between edited files.
 .IP
 The default assignment is:
 .IP
@@ -112,11 +164,16 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B KEEPLOG
-This option should be set to YES or NO.
+Boolean.
+.IP
 This option allows the user to choose whether to keep a permanent log of
-packages that are built with sbopkg in order to go back and review the
+packages that are built with
-build, and any errors, after exiting sbopkg.
+.B sbopkg
-If set to YES, this permanent log is saved at $LOGDIR/sbopkg-build-log.
+in order to go back and review the build, and any errors, after exiting
+.BR sbopkg .
+See
+.B LOGFILE
+for where this log is.
 .IP
 The default assignment is:
 .IP
@@ -124,8 +181,12 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B LOGFILE
-This option (which must be set to a full path) sets the name for the
+Path.
-build log if KEEPLOG is set to YES.
+.IP
+This option sets the name for the build log if
+.B KEEPLOG
+is set to
+.BR YES .
 .IP
 The default assignment is:
 .IP
@@ -133,13 +194,18 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B MKDIR_PROMPT
-This option may be set to YES or NO.
+Boolean.
-When set to YES, sbopkg will prompt for confirmation before changing the
+.IP
-filesystem by creating its directories.
+When set to
+.BR YES ,
+.B sbopkg
+will prompt for confirmation before changing the filesystem by creating
+its directories.
 If you do not wish to be prompted (for instance, if you have some of the
 directories on a temporary filesystem and don't wish to be prompted for
 confirmation each time the filesystem is reinitialized) you can set this
-to NO.
+to
+.BR NO .
 .IP
 The default assignment is:
 .IP
@@ -147,11 +213,15 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B OUTPUT
+Path.
+.IP
 This option sets the default directory where compiled packages are
 saved.
-OUTPUT must be exported as it is also used by the SBo SlackBuilds.
+.B OUTPUT
-Also note that the default value of OUTPUT is therefore the same as in
+must be exported as it is also used by the SBo SlackBuilds.
-the SBo SlackBuilds.
+Note that the default value of
+.B OUTPUT
+is therefore the same as in the SBo SlackBuilds.
 .IP
 The default assignment is:
 .IP
@@ -159,6 +229,8 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B QUEUEDIR
+Path.
+.IP
 This option defines the directory under which saved queue files will be
 kept.
 .IP
@@ -168,9 +240,18 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B REPO_BRANCH
+Enumeration.
+.IP
 This option allows the user to set the default active repository branch.
-The current options are listed in the default repos.d/* files and can
+The current standard values are listed in the default
-also be listed by issuing 'sbopkg -V ?'.
+.I repos.d/*
+files and can also be listed by issuing
+.RS
+.IP
+.nf
+\fCsbopkg -V ?\fP
+.fi
+.RE
 .IP
 The default assignment is:
 .IP
@@ -178,14 +259,24 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B REPO_NAME
+Enumeration.
+.IP
 This option allows the user to choose the repository to use.
-The default options are SBo, SB64 and local.
+See
-The 'local' choice corresponds to a user-maintained repository whose
+.B REPO_BRANCH
+for how to get an enumeration of standard values.
+The ``local'' choice corresponds to a user-maintained repository whose
 structure must be the same as the one used by SlackBuilds.org, in the
-sense of a category/package/files hierarchy.
+sense of a
-NOTE: all of the REPO_* variables are affected by the repository files
+.I category/package/files
-maintained in /etc/sbopkg/repos.d.
+hierarchy.
-Please see the README-repos.d document in the sbopkg /doc directory.
+Note: all of the
+.B REPO_*
+variables are affected by the repository files maintained in
+.I /etc/sbopkg/repos.d.
+Please see the
+.I README-repos.d
+document in the sbopkg documentation directory.
 .IP
 The default assignment is:
 .IP
@@ -193,6 +284,8 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B REPO_ROOT
+Path.
+.IP
 This option allows the user to set the location of the local mirrors of
 the remote repositories.
 Currently, the size of a local copy of the SBo repository is about 70MB.
@@ -203,15 +296,35 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B RSYNCFLAGS
-Rsync is used by sbopkg to mirror the SlackBuilds.org repository.
+Command options.
-This option allows the user to manually tweak the rsync flags (options)
+.IP
-that are used by sbopkg.
+.B Rsync
+is used by
+.B sbopkg
+to mirror the SlackBuilds.org repository.
+This option allows the user to manually tweak the
+.B rsync
+flags (options) that are used by
+.BR sbopkg .
 Users are cautioned against making any changes to the default values
 since new flags may or may not work.
-Note: the rsync command in sbopkg already uses the --archive, --delete,
+Note: the
---no-owner, and --exclude flags, so there is no need to add them to the
+.B rsync
-RSYNCFLAGS option.
+command in
-Changing these default options is not recommended.
+.B sbopkg
+already uses the
+.BR \-\-archive ,
+.BR \-\-delete ,
+.BR \-\-no-owner ,
+and
+.B \-\-exclude
+flags, so there is no need to add them to the
+.B RSYNCFLAGS
+option.
+Changing those internal default options is not recommended.
+However,
+.B \-\-timeout
+is a useful option to play with if getting syncing errors.
 .IP
 The default assignment is:
 .IP
@@ -219,8 +332,12 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B SBOPKGTMP
-This option sets the default directory where certain working files are
+Path.
-saved on a temporary basis.
+.IP
+This option sets the default directory where certain working files
+specific to
+.B sbopkg
+are saved on a temporary basis.
 .IP
 The default assignment is:
 .IP
@@ -228,6 +345,8 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B SRCDIR
+Path.
+.IP
 This option contains the location of the cache directory where source
 downloads will be saved.
 .IP
@@ -237,13 +356,21 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B TMP
-This option sets the default directory where built packages should be
+Path.
-stored.
-TMP must be exported as it is used by the SlackBuilds.
-Note that the default value of TMP is the same as in the SBo SlackBuild
-scripts.
 .IP
-Also note that if the CLEANUP variable is set to YES, any custom TMP
+This option sets the default directory where built packages are saved.
+.B TMP
+must be exported as it is also used by the SBo SlackBuilds.
+Note that the default value of
+.B TMP
+is therefore the same as in the SBo SlackBuilds.
+.IP
+Also note that if the
+.B CLEANUP
+variable is set to
+.BR YES ,
+any custom
+.B TMP
 setting is ignored.
 .IP
 The default assignment is:
@@ -252,15 +379,31 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .TP
 .B WGETFLAGS
-Wget is used by sbopkg to download the source files for package
+Command options.
-building.
+.IP
-This option allows the user to manually tweak the wget flags (options)
+.B Wget
-that are used by sbopkg.
+is used by
+.B sbopkg
+to download the source files for package building.
+This option allows the user to manually tweak the
+.B wget
+flags (options) that are used by
+.BR sbopkg .
 Users are cautioned against making any changes to the default values
 since new flags may or may not work.
-Note: the wget command in sbopkg already uses the -O flag, so there is
+Note: the
-no need to add that to the WGETFLAGS option.
+.B wget
-Changing these default options is not recommended.
+command in
+.B sbopkg
+already uses the
+.B \-O
+flag, so there is no need to add that to the
+.B WGETFLAGS
+option.
+Changing most of these default options is not recommended.
+However,
+.B \-\-timeout
+is a useful option to play with if getting download errors.
 .IP
 The default assignment is:
 .IP
@@ -270,46 +413,115 @@ The default assignment is:
 .\"---------------------------------------------------------------------
 .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.
+to the SlackBuild scripts when they are built from within
-This is already demonstrated in the following line in the sbopkg.conf
+.BR sbopkg .
+This is already demonstrated in the following example line (and others
+like it) in the
+.I sbopkg.conf
 file:
 .PP
-export TMP=${TMP:-/tmp/SBo}
+.RS
+.nf
+\fCexport TMP=${TMP:-/tmp/SBo}\fP
+.fi
+.RE
 .PP
-This sets TMP to /tmp/SBo for building SBo packages within sbopkg (which
+This sets
-is currently the default for SBo SlackBuilds already).
+.B TMP
-Since this variable is exported, it could be changed for both sbopkg and
+to
-for building SBo packages within sbopkg.
+.I /tmp/SBo
+for building SBo packages within
+.B sbopkg
+(which is currently the default for SBo SlackBuilds already).
+Since this variable is exported, it could be changed for both
+.B sbopkg
+and for building SBo packages within
+.BR sbopkg .
 For example, changing this line so it reads:
 .PP
-export TMP=${TMP:-/home/sbo/tmp}
+.RS
+.nf
+\fCexport TMP=${TMP:-/home/sbo/tmp}\fP
+.fi
+.RE
 .PP
-would then set TMP to /home/sbo/tmp for building SBo packages.
+would then set
-OUTPUT can also be changed to save compiled packages in a location other
+.B TMP
-than the default of /tmp.
+to
+.I /home/sbo/tmp
+for building SBo packages and still allow it to be overridden at runtime
+by invoking
+.B sbopkg
+as
+.RS
 .PP
-You can also export variables in sbopkg.conf that are not used by sbopkg
+.nf
+\fCexport TMP=foo; sbopkg\fP
+.fi
+.RE
+.PP
+.B OUTPUT
+can also be changed to save compiled packages in a location other than
+the default of
+.IR /tmp .
+.PP
+You can also export variables in
+.I sbopkg.conf
+that are not used by
+.B sbopkg
 at all.
 .\"---------------------------------------------------------------------
 .SS About the ARCH Variable
-You may be wondering why ARCH is not a configuration setting in the
+You may be wondering why
-default sbopkg.conf file.
+.B ARCH
+is not a configuration setting in the default
+.I sbopkg.conf
+file.
 The reason is that it does not have to be.
-If ARCH is not set, sbopkg does some checking (using 'uname -m') to
+If
-determine what the system's architecture is.
+.B ARCH
-If the architecture is x86, x86_64, or arm*, then sbopkg automatically
+is not set,
-sets ARCH to i486, x86_64, or arm, respectively.
+.B sbopkg
-If ARCH is set, sbopkg will inherit that setting.
+does some checking (using the output of
-This means the user can add, for example, 'export ARCH=i686' in their
+.BR "uname \-m" )
-\&.bashrc or similar file, or the user can also execute something in the
+to determine what the system's architecture is.
-root terminal like 'export ARCH=i686 && sbopkg'.
+If the architecture is x86, x86_64, or arm*, then
-The user can also manually add it to their sbopkg.conf file if they
+.B sbopkg
-wish.
+automatically sets
-Finally, if ARCH is not set by the user and sbopkg does not detect one
+.B ARCH
-of the previously mentioned architectures, then ARCH will be set by
+to i486, x86_64, or arm, respectively.
-whatever is in the SlackBuild scripts.
+If
+.B ARCH
+is set,
+.B sbopkg
+will inherit that setting.
+This means the user can add, for example,
+.B export ARCH=i686
+in their
+.I .bashrc
+or similar file, or the user can also execute something in the
+root terminal like
+.RS
+.PP
+.nf
+\fCexport ARCH=i686; sbopkg\fP
+.fi
+.RE
+.PP
+The user can also manually add it to their
+.I sbopkg.conf
+file if they wish.
+Finally, if
+.B ARCH
+is not set by the user and
+.B sbopkg
+does not detect one of the previously mentioned architectures, then
+.B ARCH
+will be set by whatever is in the SlackBuild scripts.
 Note that the SlackBuild may, in certain instances, discard or override
-previous ARCH settings if this is required for the build.
+previous
+.B ARCH
+settings if this is required for the build.
 .\"=====================================================================
 .SH FILES
 .TP 3
@@ -317,15 +529,31 @@ previous ARCH settings if this is required for the build.
 File to specify configuration options.
 .TP
 .I /etc/sbopkg/renames.d/50-default
-Default file that lists software in SBo repository that has been
+Default file that lists software in the SBo repository that has been
 renamed.
-See the README-renames.d document in the sbopkg doc/ directory for more
+See the
-information.
+.I README-renames.d
+document in the sbopkg documentation directory for more information.
 .TP
 .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
-See the README-repos.d document in the sbopkg doc/ directory for more
+.B sbopkg
-information.
+repositories.
+See the
+.I README-repos.d
+document in the
+.B sbopkg
+documentation directory for more information.
+.\"=====================================================================
+.SH AUTHORS
+Chess Griffin
+<chess@chessgriffin.com>
+.PP
+Mauro Giachero
+<mauro.giachero@gmail.com>
+.PP
+slakmagik
+<slakmagik@gmail.com>
 .\"=====================================================================
 .\" Make the release process handle a DOCDIR here? But the files from
 .\" the official tarball go here.

src/usr/man/man8/sbopkg.8

@@ -9,42 +9,63 @@ sbopkg \- the SlackBuilds.org package browser
 .RI [ options ]
 .\"=====================================================================
 .SH DESCRIPTION
-Sbopkg is a command-line and dialog-based tool to interact with the
+.B Sbopkg
-SlackBuilds.org ("SBo") repository, a collection of third-party
+is a command-line and
-SlackBuild scripts to build Slackware packages.
+.BR dialog -based
+tool to interact with the SlackBuilds.org (``SBo'') repository, a
+collection of third-party SlackBuild scripts to build Slackware
+packages.
 .\"=====================================================================
 .SS Instructions
-Sbopkg usage assumes an understanding of SlackBuild scripts, generally,
+.B Sbopkg
-and the third-party repository SlackBuilds.org, specifically.
+usage assumes an understanding of SlackBuild scripts, generally, and the
-A thorough reading of http://www.slackbuilds.org/howto/ and the pages at
+third-party repository SlackBuilds.org, specifically.
-http://www.slackwiki.org about SlackBuild scripts is strongly advised.
+A thorough reading of
+.I http://www.slackbuilds.org/howto/
+and the pages at
+.I http://www.slackwiki.org
+about SlackBuild scripts is strongly advised.
 .PP
-In order for sbopkg to be used, a configuration file must exist at
+In order for
-/etc/sbopkg/sbopkg.conf.
+.B sbopkg
-An initial install will provide the user with an /etc/sbopkg/sbopkg.conf
+to be used, a configuration file must exist at
-while upgrades will add an /etc/sbopkg/sbopkg.conf.new which may be
+.IR /etc/sbopkg/sbopkg.conf .
-merged with or replace the older version.
+An initial install will provide the user with that file while upgrades
+will add an
+.I /etc/sbopkg/sbopkg.conf.new
+which may be merged with or replace the older version.
 See
 .BR sbopkg.conf (5)
 for more information about the configuration file.
 .PP
-Sbopkg must be run as the root user (since the SlackBuild scripts at
+.B 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.
+Furthermore, using the
+.B \-
+option with
+.B su
+is strongly encouraged.
 The reason is that some SlackBuild scripts rely on certain tools that
-are only available in root's PATH when the scripts in /etc/profile.d
+are only available in root's
-have been run (i.e., texmf to build man pages), which is only done for
+.B PATH
-login shells, or otherwise require a 'truer' root environment than that
+when the scripts in
-given by only 'su'.
+.I /etc/profile.d
+have been run (i.e.,
+.B texmf
+to build man pages), which is only done for login shells, or otherwise
+require a ``truer'' root environment than that given by only
+.BR su .
 In any event, invoking
 .B sbopkg
 with no arguments (or with just
-.BR -d ,
+.BR \-d ,
-.B -f
+.B \-f
 or
-.BR -V )
+.BR \-V )
-will launch the dialog-based interface, and the menus provided should be
+will launch the
-fairly self-explanatory.
+.BR dialog -based
+interface, and the menus provided should be fairly self-explanatory.
 The main menu allows the user to synchronize with the SlackBuilds.org
 repository.
 This is the first step to take (after configuration) with a new install
@@ -52,75 +73,137 @@ of
 .BR sbopkg .
 Currently, the size of a local copy of the SBo repository is about 70MB.
 The main menu also allows the user to view the SlackBuilds.org
-ChangeLog, check for potential updates to SBo packages, display the
+.IR ChangeLog ,
-contents of the local cache directory where source tarballs are saved,
+check for potential updates to SBo packages, display the contents of the
-display the permanent build log, and browse or search the local copy of
+local cache directory where source tarballs are saved, display the
-the SBo repository.
+permanent build log, and browse or search the local copy of the SBo
+repository.
 Once the browse function is chosen, the user can select the category of
 software to view.
 After choosing a category, the user can then view the various software
 packages available in that category within the local SBo repository.
 Selecting a package will display another menu allowing the user to view
-the package's README, SlackBuild, .info, or slack-desc files.
+the package's
-The user can also edit the .info file and SlackBuild and the edited
+.IR README ,
-files will remain after doing an rsync.
+.IR SlackBuild ,
-Additionally, the user can choose to build a package as well using
+.IR .info ,
-either the original SlackBuild or the locally-edited one, if present.
+or
-If using the dialog interface, and if sbopkg finds a built package for a
+.I slack-desc
-particular piece of software in the OUTPUT directory, then sbopkg will
+files.
-automatically add a new menu entry allowing the user to install the
+The user can also edit the
-package if he so chooses.
+.I .info
-Alternatively, the user can choose to automatically build or build and
+file and
-install individual packages or several packages in a build queue.
+.I SlackBuild
-Finally, if KEEPLOG is set to YES in the sbopkg.conf file then a
+and the edited files will remain after doing a sync.
-permanent log of the build process is saved to wherever LOGFILE is set
+Additionally, the user can choose to build a package using either the
-to in that same file.
+original
+.I SlackBuild
+or the locally-edited one, if present.
+If using the
+.B dialog
+interface, and if
+.B sbopkg
+finds a built package for a particular piece of software in the
+.B OUTPUT
+directory, then
+.B sbopkg
+will automatically add a new menu entry allowing the user to install the
+package if he chooses.
+Alternatively, the user can choose to automatically build, or both build
+and install, individual packages or several packages in a build queue.
+Finally, if
+.B KEEPLOG
+is set to YES in the
+.B sbopkg.conf
+file then a permanent log of the build process is saved.
+See
+.BR sbopkg.conf (5)
+under
+.B KEEPLOG
+and
+.B LOGFILE
+for details.
 .PP
-Alternatively, sbopkg can be run from the command line without using the
+Alternatively,
-dialog interface.
+.B sbopkg
-See below for the available command line options.
+can be run from the command line without using the
+.B dialog
+interface.
+See the OPTIONS section for the available command line options.
 .PP
-Sbopkg also has the capability of loading, saving, and using
+.B Sbopkg
-user-created queuefiles.
+also has the capability of loading, saving, and using user-created
+queuefiles.
 These queuefiles are simple text files with one application name per
 line.
 By default, when a queuefile is loaded in the dialog interface, the
-application is selected, or "ON."
+application is selected, or ``ON.''
-This can be changed by inserting a "-" in front of the application name
+This can be changed by inserting a ``-'' in front of the application
-in the queuefile.
+name in the queuefile.
 Also, queuefiles can reference other queuefiles when the first character
-is an "@".
+is an ``@''.
-See the readme-queuefiles document in the doc/ directory for more
+See the
-information.
+.I readme-queuefiles
+document in the documentation directory for more information.
 .PP
-Certain features of sbopkg rely on outside binaries, such as a pager to
+Certain features of
-view the text files when sbopkg is run from the comamnd line, and an
+.B sbopkg
-editor to edit the .info or SlackBuild files.
+rely on outside binaries, such as a pager to view the text files when
-The pager function will look to the environmental variable PAGER and if
+.B sbopkg
-that variable is not defined then it will default to 'more.'
+is run from the command line, and an editor to edit the
-Similarly, the edit function found when sbopkg is used with the dialog
+.I .info
-interface will look to the EDITOR variable and will default to 'vi' if
+or
-EDITOR is undefined.
+.I SlackBuild
-If the user wants sbopkg to use another editor, such as nano, then
+files.
-adding the requisite information in ~/.bashrc, /etc/profile, or other
+The paging functions will look to the environmental variable
-similar configuration file to export EDITOR will suffice.
+.B PAGER
+and, if that variable is not defined, it will default to
+.BR more .
+Similarly, the editing functions will look to
+.B EDITOR
+and  will default to
+.BR vi .
+If the user wants
+.B sbopkg
+to use another editor, such as
+.BR nano ,
+then adding the requisite information in
+.IR ~/.bashrc ,
+.IR /etc/profile ,
+or other similar configuration file to export
+.B EDITOR
+will suffice.
 .\"=====================================================================
 .SH OPTIONS
 .\"---------------------------------------------------------------------
 .TP 5
 .BI \-b " PACKAGE(s)/QUEUE(s)"
-Search for and build PACKAGE(s) from the local SBo repository.
+Build packages of the argument(s) from the active repository.
-If more than one package is specified, they must be in quotes.
+If more than one package is specified, they must be quoted.
+.IP
 For example:
+.RS
 .IP
-# sbopkg -b "foo bar"
+.nf
+\fC# sbopkg -b "foo bar"\fP
+.fi
+.RE
 .IP
-will build foo and then bar.
+will build
+.I foo
+and then
+.IR bar .
 Queuefile names can also be specified.
 In that case, all the packages specified in the queuefile will be built.
 In the unfortunate case a token matches both a queuefile name and a
 package name (i.e., the user named a queuefile with the name of a
-package), sbopkg will ask the user which one should be used.
+package),
+.B sbopkg
+will ask the user which one should be used.
+A way to avoid this is to specify the queuefile with its
+.I .sqf
+extension.
+Also, a mix of both packages and queuefiles may be given.
 The tokens (package names or queuefiles) are processed in the order they
 are specified on the command line, and the build order specified in the
 queuefiles is retained.
@@ -133,13 +216,15 @@ Display list of installed SBo packages and potential updates.
 .\"---------------------------------------------------------------------
 .TP
 .BI \-d " DIRECTORY"
-Manually specify the full path to the DIRECTORY containing the local SBo
+Manually specify the full path to the
-repository.
+.I DIRECTORY
+containing the local SBo repository.
 .\"---------------------------------------------------------------------
 .TP
 .B \-e \fBask\fR|\fBcontinue\fR|\fBstop
-Specify what sbopkg should do when it encounters an error while building
+Specify what
-a package.
+.B sbopkg
+should do when it encounters an error while building a package.
 Valid options are:
 .IP
 .BR ask :
@@ -147,26 +232,37 @@ This is the default behavior, asking the user what to do.
 .IP
 .BR continue :
 Ignore the error and continue processing (act as if the user answered
-"Yes" to all questions).
+``Yes'' to all questions).
 .IP
 .BR stop :
-Stop the processing (act as if the user answered "No" to all questions).
+Stop the processing (act as if the user answered ``No'' to all questions).
 .\"---------------------------------------------------------------------
 .TP
 .BI \-f " FILE"
-Override the default configuration file, /etc/sbopkg/sbopkg.conf, with
+Override the default configuration file,
-another configuration file.
+.IR /etc/sbopkg/sbopkg.conf ,
+with another configuration file.
 .\"---------------------------------------------------------------------
 .TP
 .BI \-g " PACKAGE(s)"
-General search for PACKAGE(s) by glob.
+General search for
+.I PACKAGE(s)
+by glob.
+If more than one glob is specified, they must be quoted.
+.IP
 For example:
+.RS
 .IP
-# sbopkg -g nv
+.nf
+\fC# sbopkg -g "foo bar"\fP
+.fi
+.RE
 .IP
-will return a list of matches, such as the nvidia packages,
+will return a list of packages with either
-konversation, and other packages with 'nv' in their name.
+.I foo
-If more than one glob is specified, they must be in quotes.
+or
+.I bar
+in their names.
 .\"---------------------------------------------------------------------
 .TP
 .B \-h
@@ -174,37 +270,43 @@ Display the help.
 .\"---------------------------------------------------------------------
 .TP
 .BI \-i " PACKAGE(s)/QUEUE(s)"
-Build and install PACKAGE(s) from the local SBo repository.
+Build and install packages of the argument(s) from the active
-If more than one package is specified, they must be in quotes, and the
+repository.
-packages will be built and then installed in the listed order.
-For example:
 .IP
-# sbopkg -i "foo bar"
+See the
+.B \-b
+option for details since, other than the installation, these two options
+operate similarly.
 .IP
-will build and install foo and then build and install bar.
+Note that by carefully considering the order of the packages listed, the
-By carefully considering the order of the packages listed, the user may
+user may be able to build and install dependencies in the right order
-be able to build and install dependencies in the right order before the
+before the final application is built and installed.
-final application is built and installed.
 Of course, given the nature of dependencies, this may not always be
 possible and so building dependencies like this is not really a
 supported feature.
 Still, when when it works, it can be helpful.
-.IP
-Queuefile names are supported, too.
-See the explanation for the '-b' command for details.
 .\"---------------------------------------------------------------------
 .TP
 .B \-k
-When used together with -b or -i, this option tells sbopkg to skip
+When used together with
-(i.e., don't build) any package it finds to be already installed.
+.B \-b
+or
+.BR \-i ,
+this option tells
+.B sbopkg
+to skip (i.e., don't build) any package it finds to be already
+installed.
 .IP
 Please note that only a name comparison is performed, so when this
-option is specified sbopkg will also omit the build of different
+option is specified
-versions of installed packages.
+.B sbopkg
+will also omit the build of different versions of installed packages.
 .\"---------------------------------------------------------------------
 .TP
 .B \-l
-Display the SBo ChangeLog and quit.
+Display the SBo
+.I ChangeLog
+and quit.
 .\"---------------------------------------------------------------------
 .TP
 .B \-o
@@ -212,12 +314,12 @@ List the currently installed cached source files which are deemed
 obsolete, and optionally delete them.
 .IP
 Source files are obsolete when no SBo script references it any more,
-which is something that can happen after rsync-ing the local repository.
+which is something that can happen after syncing the local repository.
 .IP
 Please note that only the currently active repository is used to
 identify the obsolete sources, so if the user builds packages with
 different repositories (e.g., for different Slackware versions) the
-source files only used in the "other" repository will be listed.
+source files only used in the ``other'' repository will be listed.
 .\"---------------------------------------------------------------------
 .TP
 .B \-P
@@ -230,7 +332,7 @@ List installed SlackBuilds.org packages.
 .\"---------------------------------------------------------------------
 .TP
 .B \-q
-Enable the "quiet mode."
+Enable the ``quiet mode.''
 When this flag is specified, the output of some of the command-line
 options is minimized.
 .\"---------------------------------------------------------------------
@@ -240,45 +342,80 @@ Rsync the local repository with SlackBuilds.org and quit.
 .\"---------------------------------------------------------------------
 .TP
 .B \-R
-Show all the README files of the queued packages before starting the
+Show all the
-build.
+.I README
+files of the queued packages before starting the build.
 This is useful when the user wants to make a final check.
 .\"---------------------------------------------------------------------
 .TP
 .BI \-s " PACKAGE(s)"
-Specific search for PACKAGE(s) by PACKAGE name and, if found, display
+Specific search for
-the README, SlackBuild, .info, and slack-desc files in that order using
+.I PACKAGE(s)
-$PAGER, which defaults to 'more' as described above.
+by name and, if found, display the
-If more than one package is specified, they must be in quotes.
+.IR README ,
+.IR SlackBuild ,
+.IR .info ,
+and
+.I slack-desc
+files in that order for each
+.I PACKAGE
+found, using
+.IR $PAGER .
+If more than one package is specified, they must be quoted.
+.IP
 For example:
+.RS
 .IP
-# sbopkg -s "foo bar"
+.nf
+\fC# sbopkg -s "foo bar"\fP
+.fi
+.RE
 .IP
-will search for foo and then bar.
+will display all the above-mentioned files for packages whose names are
+exactly
+.I foo
+or
+.IR bar .
 .\"---------------------------------------------------------------------
 .TP
 .B \-u
-Check for an update to sbopkg itself and then quit.
+Check for an update to
+.B sbopkg
+itself and then quit.
 .\"---------------------------------------------------------------------
 .TP
 .BI \-V " VERSION"
 Set the repository and branch to use.
 .IP
-For a list of valid versions, invoke sbopkg as
+For a list of valid versions, invoke
-.BR "sbopkg -V ?" .
+.B sbopkg
+as
+.RS
+.IP
+.nf
+\fCsbopkg -V ?\fP
+.fi
+.RE
+.IP
 See the
 .BR sbopkg.conf (5)
-man page for more information about the 'local' repository.
+man page for more information about the ``local'' repository.
 .IP
-The VERSION format is repository/branch (e.g., SBo/13.1).
+The
-If the repository is omitted, sbopkg will first look for the specified
+.I VERSION
-branch in the default repository.
+format is repository/branch (e.g., SBo/13.1).
-If that attempt fails, sbopkg will look for the first matching branch in
+If the repository is omitted,
-any repository.
+.B sbopkg
+will first look for the specified branch in the default repository.
+If that attempt fails,
+.B sbopkg
+will look for the first matching branch in any repository.
 .\"---------------------------------------------------------------------
 .TP
 .B \-v
-Prints the current version of sbopkg on stdout.
+Prints the current version of
+.B sbopkg
+on stdout.
 .\"=====================================================================
 .SH FILES
 .TP 5
@@ -288,25 +425,42 @@ Default system-wide file to specify configuration options.
 .I /etc/sbopkg/renames.d/50-default
 Default file that lists software in the SBo repositories that has been
 renamed.
-See the README-renames.d document in the sbopkg doc/ directory for more
+See the
-information.
+.I README-renames.d
+document in the
+.B sbopkg
+documentation directory for more information.
 .TP
 .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
-See the README-repos.d document in the sbopkg doc/ directory for more
+.B sbopkg
-information.
+repositories.
+See the
+.I README-repos.d
+document in the
+.B sbopkg
+documentation directory for more information.
+.\"=====================================================================
+.SH AUTHORS
+Chess Griffin
+<chess@chessgriffin.com>
+.PP
+Mauro Giachero
+<mauro.giachero@gmail.com>
+.PP
+slakmagik
+<slakmagik@gmail.com>
 .\"=====================================================================
 .\" Make the release process handle a DOCDIR here? But the files from
 .\" the official tarball go here.
 .SH SEE ALSO
 .BR dialog (1),
 .BR more (1),
+.BR removepkg (8),
 .BR rsync (1),
 .BR sbopkg.conf (5),
+.BR su (1),
+.BR upgradepkg (8),
 .BR vi (1),
 .IR /usr/doc/sbopkg-SVN/*
-.\"=====================================================================
-.SH AUTHOR
-Chess Griffin
-<chess@chessgriffin.com>
 .\" vim:set tw=72: