revise documentation

Major reformatting and some textual modifications of
src/usr/doc/sbopkg-*/* including breaking out the credits from the
script into a detailed THANKS file, renaming and reformatting
ChangeLog.txt into NEWS, renaming the sample queuefiles from *.sqf to
*.sqf.sample, and making lesser modifications to all the other docs.

src/usr/doc/HACKING

@@ -1,26 +1,45 @@
-# $Id$
+SBOPKG HACKING
-# vim:set ft=:
+
+INTRODUCTION
+
+    We welcome contributions to sbopkg. If you have a bug report or a
+    feature request, please go to the project's Google Code site and use
+    the Issue Tracker so your bug report/feature request does not get
+    lost.
+
+        http://code.google.com/p/sbopkg/issues/list
+
+    If you cannot post to the Issue Tracker, please consider joining the
+    sbopkg mailing list and post your bug report or feature request
+    there.
 
-We welcome contributions to sbopkg.  If you have a bug report or a feature
-request, please go to the project's Google Code site and use the 'Issue
-Tracker' so your bug report/feature request does not get lost:
-http://code.google.com/p/sbopkg/issues/list.  If you cannot post to the Issue
-Tracker, please consider joining the sbopkg mailing list and post your bug
-report or feature request there:
         http://sbopkg.org/mailman/listinfo/sbopkg-users
 
-As far as hacking on the code, the best thing to do is to checkout the
+    If you cannot join the mailing list, there is an #sbopkg channel on
-latest version from subversion (see http://www.sbopkg.org/devel.php) and then
+    the freenode IRC network.
-contribute patches with something like 'diff -Naurp' or 'svn diff -x -p'.
-Please try to make each patch do one thing and do it well.  Also, please do
-not combine whitespace or other non-functional changes with functional changes
-in the same patch (unless the same lines contain both types of changes).
-Basically, just use common sense -- a one line functional change and a typo
-correction can be a single patch, rather than two one-line patches.
 
-Please make sure your patches conform to these stylistic points:
+    As far as hacking on the code, the best thing to do is to checkout
+    the latest version from subversion using something like the
+    following command:
 
-* Code in Bash.
+        svn checkout http://sbopkg.googlecode.com/svn/trunk \
+            sbopkg-contrib
+
+    (See http://www.sbopkg.org/devel.php for more information.) Then
+    contribute patches with something like 'diff -Naurp' or 'svn diff -x
+    -p'.
+
+    Please try to make each patch do one thing and do it well. Also,
+    please do not combine whitespace or other non-functional changes
+    with functional changes in the same patch (unless the same lines
+    contain both types of changes). Basically, just use common sense --
+    a one line functional change and a typo correction can be a single
+    patch, rather than two one-line patches.
+
+PATCH/SCRIPT GUIDELINES
+
+    * Write code compatible with bash 3.1.17 to the latest stable
+      version.
 
     * Wrap lines at 78 columns.
 
@@ -40,18 +59,19 @@ Please make sure your patches conform to these stylistic points:
               stuff
           }
 
-* In general, variables do not need to be quoted except in cases where the
+    * In general, variables do not need to be quoted except in cases
-  variable may contain spaces.  If unsure, quote the variable just to be safe.
+      where the variable may contain spaces. If unsure, quote the
+      variable just to be safe.
 
     * Use variable names in the form: MYVARNAME except when MYVARNAME is
-  ambiguous or made of more than two or three components.  In that case, use
+      ambiguous or made of more than two or three components. In that
-  MY_VAR_NAME.
+      case, use MY_VAR_NAME.
 
-* If you are going to need a bit of data repeatedly, try to grab it once and
+    * If you are going to need a bit of data repeatedly, try to grab it
-  assign it to a variable rather than re-obtaining it.
+      once and assign it to a variable rather than re-obtaining it.
 
-* If you are going to use a combination of several concatenated variables
+    * If you are going to use a combination of several concatenated
-  multiple times, consider creating a new variable like:
+      variables multiple times, consider creating a new variable like:
       'NEWVAR=$OLDVAR1-$OLDVAR2-$OLDVAR3'.
 
     * Prefer the style:
@@ -75,8 +95,8 @@ Please make sure your patches conform to these stylistic points:
 
     * Prefer shell redirection to piping 'echo' or 'cat'.
 
-* Prefer bash variable substitutions to 'tr', 'sed', 'cut', ..., when
+    * Prefer bash variable substitutions to 'tr', 'sed', 'cut', ...,
-  possible.
+      when possible.
 
     * Error messages should go to standard error:
 
@@ -85,7 +105,8 @@ Please make sure your patches conform to these stylistic points:
     * Make return codes meaningful (i.e. if you redirect to stderr try
       to return or exit 1 at the same time).
 
-* When both 'foo' is simple and 'bar' is a one-liner, the conditional form:
+    * When both 'foo' is simple and 'bar' is a one-liner, the
+      conditional form:
 
           [[ foo ]] && bar
 
@@ -103,24 +124,24 @@ Please make sure your patches conform to these stylistic points:
 
           [[ foo ]] || bar
 
-  only when 'bar' is simple and supposed to be executed on error conditions
+      only when 'bar' is simple and supposed to be executed on error
-  (i.e. almost never)
+      conditions (i.e. almost never)
 
     * Multiple conditionals can be done either as:
 
-  if [[ $CHOICE == 1 ]] || [[ $CHOICE == 0 && -z $CUSTOMOPTS ]]; then
+          if [[ $FOO == 1 ]] || [[ $FOO == 0 && -z $BAR ]]; then
 
       or
 
-  if [[ $CHOICE == 1 || ( $CHOICE == 0 && -z $CUSTOMOPTS ) ]]; then
+          if [[ $FOO == 1 || ( $FOO == 0 && -z $BAR ) ]]; then
 
       but not:
 
-  if [ $CHOICE = 1 ] || [ $CHOICE = 0 -a "$CUSTOMOPTS" = "" ]; then
+          if [ $FOO = 1 ] || [ $FOO = 0 -a "$BAR" = "" ]; then
 
-  The reasons the third example is not as good as the first two are that it
+      The reasons the third example is not as good as the first two are
-  uses single brackets instead of double brackets and uses '-a' instead of
+      that it uses single brackets instead of double brackets and uses
-  '&&'.
+      '-a' instead of '&&'.
 
     * 'case' statements should be indented as:
 
@@ -133,7 +154,8 @@ Please make sure your patches conform to these stylistic points:
                   ;;
           esac
 
-  unless the statements can be short one-liners, in which case the form
+      unless the statements can be short one-liners, in which case the
+      form
 
           case $FOO in
               bar ) short_simple_command ;;
@@ -146,18 +168,19 @@ Please make sure your patches conform to these stylistic points:
 
     * Declare local variables as such at the function start.
 
-* Positional parameters to functions should be assigned to local variables,
+    * Positional parameters to functions should be assigned to local
-  one per 'local' statement, before declaring the other local variables (which
+      variables, one per 'local' statement, before declaring the other
-  can share a single 'local' statement):
+      local variables (which can share a single 'local' statement):
 
           local FILE="$1"
           local DIR="$2"
           local FOO BAR BAZ
 
-* In general, when wrapping long lines, the part going on the next line should
+    * In general, when wrapping long lines, the part going on the next
-  be indented with 8 spaces if there is ambiguity so as to distinguish the
+      line should be indented 8 spaces beyond the initial line if there
-  wrap from other lines before and after it.  The same would be true for line
+      is ambiguity so as to distinguish the wrap from other lines before
-  wraps in conditions.  For example:
+      and after it. The same would be true for line wraps in conditions.
+      For example:
 
           if ASD ||
                   FGH; then
@@ -171,8 +194,8 @@ Please make sure your patches conform to these stylistic points:
               echo "Success"
           fi
 
-  In the latter case, having 'FGH; then' at the same indent level as the echo
+      In the latter case, having 'FGH; then' at the same indent level as
-  is ambiguous.  On the other hand:
+      the echo is ambiguous. On the other hand:
 
           APP=$(grep foo \
               really/long/path/to/file)
@@ -182,9 +205,9 @@ Please make sure your patches conform to these stylistic points:
 
       is ok since there really is no ambiguity.
 
-* Prefer 'foo | bar' over 'foo |bar' or 'foo|bar'.  However, if the line
+    * Prefer 'foo | bar' over 'foo |bar' or 'foo|bar'. However, if the
-  barely goes over 78 columns, then removing spaces is OK to keep it on a
+      line barely goes over 78 columns, then removing spaces is OK to
-  single line.  In other words:
+      keep it on a single line. In other words:
 
           foo |bar |baz
 
@@ -193,8 +216,8 @@ Please make sure your patches conform to these stylistic points:
           foo | bar |
                   baz
 
-* When wrapping between two piped commands, the pipe should be the last
+    * When wrapping between two piped commands, the pipe should be the
-  character of the former line.  For example, prefer:
+      last character of the former line. For example, prefer:
 
           some stuff here foo |
               bar
@@ -208,14 +231,15 @@ Please make sure your patches conform to these stylistic points:
 
     * Always use $( ... ) instead of ` ... `.
 
-* 'Break' and 'continue' should never be used to influence a loop outside of
+    * 'Break' and 'continue' should never be used to influence a loop
-  the function they belong to.
+      outside of the function they belong to.
 
     * Avoid indirect recursion (A calls B that calls A).
 
-* [[ -z "$VAR" ]] vs. [[ ! "$VAR" ]] and [[ "$VAR" ]] vs. [[ -n "$VAR" ]]:
+    * [[ -z "$VAR" ]] vs. [[ ! "$VAR" ]] and [[ "$VAR" ]] vs.
-  -n/-z should be used when $VAR contains a computational result and the other
+      [[ -n "$VAR" ]]: -n/-z should be used when $VAR contains a
-  form should be used where $VAR is a functional flag.  For example:
+      computational result and the other form should be used where $VAR
+      is a functional flag. For example:
 
           VAR=$(grep "^something=" <$SBOPKG_RENAMES)
           if [[ -z $VAR ]]; then
@@ -224,79 +248,90 @@ Please make sure your patches conform to these stylistic points:
 
           if [[ $DIAG ]]; then
 
-* For indices, use FILE and DIR instead of 'f' and 'd'.  However, 'i' is OK as
+    * For indices, use FILE and DIR instead of 'f' and 'd'. However, 'i'
-  a counter since that is fairly universal.
+      is OK as a counter since that is fairly universal.
 
-* When deciding whether or not to use the =~ operator in [[ commands, make
+    * When deciding whether or not to use the =~ operator in [[
-  sure that they work across bash 3.1, 3.2, and 4.0. This means the regexes
+      commands, make sure that they work across bash 3.1, 3.2, and 4.0.
-  must be unquoted for bash >=3.2 and still work in bash 3.1 (i.e., no
+      This means the regexes must be unquoted for bash >=3.2 and still
-  'foo|bar' expressions).
+      work in bash 3.1 (i.e., no 'foo|bar' expressions).
 
-----------------------------
+MANUAL PAGE STYLE GUIDELINES
-Manual Page Style Guidelines
-----------------------------
 
-* Separate all text header and section header requests with commented lines of
+    * Separate all text header and section header requests with
-  equal (=) signs. Separate all subsections and tagged paragraphs that serve
+      commented lines of equal (=) signs. Separate all subsections and
-  as subsections with commented lines of minus (-) signs.
+      tagged paragraphs that serve as subsections with commented lines
+      of minus (-) signs.
 
-* Leave no blank lines in the file. E.g., .PP will often serve under .SH and
+    * Leave no blank lines in the file. E.g., .PP will often serve under
-  .IP under .TP.
+      .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
+    * If variables are being used in the sense of their value, use $VAL
-  they are being used in reference to themselves, use VAR.
+      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
+    * Try to use standard headers where possible, filing other
-  under subsections of the relevant section header.
+      information under subsections of the relevant section header.
 
-* Add options as .TP 5 (or current default), with \- and bold options,
+    * Add options as .TP 5 (or current default), with \- and bold
-  followed by italic replaceable arguments to those options or bold literal
+      options, followed by italic replaceable arguments to those options
-  arguments, if any. Brackets, bars, etc., should be regular font, though.
+      or bold literal arguments, if any. Brackets, bars, etc., should be
+      regular font, though.
 
-* More generally, italicize filenames, URLs, replaceable terms (including
+    * More generally, italicize filenames, URLs, replaceable terms
-  references to unspecified variable values ($VARs)).
+      (including references to unspecified variable values ($VARs)).
 
-* Embolden variables (when used literally rather than replaceably), option
+    * Embolden variables (when used literally rather than replaceably),
-  values, programs, program flags, and all references to sbopkg itself.
+      option values, programs, program flags, and all references to
+      sbopkg itself.
 
-* Make all option dashes in the form \- (or \-\-) unless in a code example.
+    * Make all option dashes in the form \- (or \-\-) unless in a code
+      example.
 
     * Try to refer to the user as 'the user' rather than 'you'.
 
-* Collect all referenced programs (unless used purely as an example) in the
+    * Collect all referenced programs (unless used purely as an example)
-  SEE ALSO section. (The SEE ALSO section is not *limited* to referenced
+      in the SEE ALSO section. (The SEE ALSO section is not *limited* to
-  programs, however.)
+      referenced programs, however.)
 
-* Try to be as specific as conveniently possible, where 'convenient' means to
+    * Try to be as specific as conveniently possible, where 'convenient'
-  generalize wherever constant updates might be necessary and such
+      means to generalize wherever constant updates might be necessary
-  generalization wouldn't compromise clarity and accuracy.
+      and such generalization wouldn't compromise clarity and accuracy.
 
-* Use `` and '' for double-quotes so groff does the fancy stuff for ps output.
+    * Use `` and '' for double-quotes so groff does the fancy stuff for
+      ps output.
+
+    * .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:
 
-* .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.
 
-  In command line examples, prefix the commands with the root prompt (#).
+      If inline, at least embolden them so they're set off in ascii
+      overstrike output.
+
+      In command line examples, prefix the commands with the root prompt
+      (#).
+
+    * Start configuration file option sections with a statement of type,
+      a description, and the following cookie-cutter code:
 
-* 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
+          \fCxxxVARxxx\fP
 
-* Try to refer to SlackBuilds as SlackBuilds rather than SlackBuild scripts
+      ('xxxVARxxx' will be replaced by whatever value VAR has in the
-  unless for a particular need (for instance, explaining what SlackBuilds are
+      default sbopkg.conf file.)
-  in the first place). And once SlackBuilds.org has been properly introduced,
+
-  try to refer to it as SBo.
+    * Try to refer to SlackBuilds as SlackBuilds rather than SlackBuild
+      scripts unless for a particular need (for instance, explaining
+      what SlackBuilds are in the first place). And once SlackBuilds.org
+      has been properly introduced, try to refer to it as SBo.

src/usr/doc/KNOWN_ISSUES

@@ -1,60 +1,67 @@
-The following are the known user-visible issues in sbopkg or upstream in the
+SBOPKG KNOWN ISSUES
-tools it uses:
 
-* in dialog '--inputbox' widgets (the boxes the user types text into) the
+The following are the known user-visible issues in sbopkg or upstream in
-  left/right arrows do not navigate in a button context. (They do navigate in
+the tools it uses:
-  an editing context.) This does not seem to be an sbopkg issue.
 
-  Workaround: navigate with up/down arrows or tab/shift-tab
+* In dialog '--inputbox' widgets (the boxes the user types text into)
-  Note: there is a newer dialog version available which fixes this issue, but
+  the left/right arrows do not navigate in a button context. (They do
-  we encourage users to stick with the dialog Slackware ships.
+  navigate in an editing context.) This does not seem to be an sbopkg
+  issue.
 
-* if dialog is run in a terminal emulator and the user exits using the
+  Workaround: navigate with up/down arrows or tab/shift-tab Note: there
-  window manager's 'close' (or equivalent) button/command, dialog may hang,
+  is a newer dialog version available which fixes this issue, but we
-  using full CPU capacity and have to be killed. This does not seem to be an
+  encourage users to stick with the dialog Slackware ships.
-  sbopkg issue.
+
+* If dialog is run in a terminal emulator and the user exits using the
+  window manager's 'close' (or equivalent) button/command, dialog may
+  hang, using full CPU capacity and have to be killed. This does not
+  seem to be an sbopkg issue.
 
   Details: http://code.google.com/p/sbopkg/issues/detail?id=30
 
-  Workaround: use dialog's own exit methods - its buttons, escape, ^C, etc.
+  Workaround: use dialog's own exit methods - its buttons, escape, ^C,
+  etc.
 
-* when checking for updates, for some packages sbopkg may tell you
+* When checking for updates, for some packages sbopkg may tell you
-  "Note: repo version not obtainable by standard method, may be inaccurate.".
+  "Note: repo version not obtainable by standard method, may be
-  This happens with packages whose version is very difficult/impossible to
+  inaccurate.". This happens with packages whose version is very
-  determine without actually building the package -- one example of this at
+  difficult/impossible to determine without actually building the
-  the time of writing is the google-chrome package, whose version is picked
+  package -- one example of this at the time of writing is the
-  from the source archive itself. In these cases sbopkg falls back to trusting
+  google-chrome package, whose version is picked from the source archive
-  the .info file, and warns the user about it.
+  itself. In these cases sbopkg falls back to trusting the .info file,
+  and warns the user about it.
 
   Workaround: none needed
 
-* while you are free to set PAGER to any value you like, be aware that some
+* While you are free to set PAGER to any value you like, be aware that
-  pagers and settings may cause unexpected behavior. An example is if paging
+  some pagers and settings may cause unexpected behavior. An example is
-  less than a screenful of output from the uninstalled packages option - the
+  if paging less than a screenful of output from the uninstalled
-  default pager 'more' will exit, displaying the packages and a prompt. 'less'
+  packages option - the default pager 'more' will exit, displaying the
-  may prompt for exit and clear its output on exit. Setting the environment
+  packages and a prompt. 'less' may prompt for exit and clear its output
-  variable LESS to include the F and X options will make less behave more like
+  on exit. Setting the environment variable LESS to include the F and X
-  more in this instance. Other pagers may have other behaviors and other means
+  options will make less behave more like more in this instance. Other
-  of configuration.
+  pagers may have other behaviors and other means of configuration.
 
   Workaround: pager-specific
 
-* a few SlackBuild scripts in the slackbuilds.org repo have a source download
+* A few SlackBuild scripts in the slackbuilds.org repo have a source
-  that is only available through an https download.  By default, sbopkg will
+  download that is only available through an https download.  By
-  not be able to download these sources.
+  default, sbopkg will not be able to download these sources.
 
   Workaround: add --no-check-certificate to WGETFLAGS in sbopkg.conf
 
-* certain packages build kernel modules and need to (re)set the ARCH to 'x86'
+* Certain packages build kernel modules and need to (re)set the ARCH to
-  on i?86 (32-bit) systems which may result in packages with 'x86' as the ARCH
+  'x86' on i?86 (32-bit) systems which may result in packages with 'x86'
-  in the file name, while sbopkg will display the specific ARCH of your system
+  as the ARCH in the file name, while sbopkg will display the specific
-  (or the ARCH you've set) in certain cases, such as in widget titles.
+  ARCH of your system (or the ARCH you've set) in certain cases, such as
+  in widget titles.
 
   Workaround: none needed
 
-* when using sbopkg to sync to SBo git repositories (which is possible but
+* When using sbopkg to sync to SBo git repositories (which is possible
-  unsupported) unexpected results may occur. See
+  but unsupported) unexpected results may occur.
-    http://code.google.com/p/sbopkg/issues/detail?id=47
+
+  Details: http://code.google.com/p/sbopkg/issues/detail?id=47
   http://sbopkg.org/pipermail/sbopkg-users/2010-May/000477.html
 
   Workaround: see above links

src/usr/doc/README

@@ -1,64 +1,89 @@
-# $Id$
+SBOPKG README
-# vim:set ft=:
+
+SBOPKG COPYRIGHT/LICENSE
 
-Sbopkg README
     Copyright 2007-2010 Chess Griffin <chess@chessgriffin.com>
     Copyright 2009-2010 Mauro Giachero <mauro.giachero@gmail.com>
                         slakmagik <slakmagik@gmail.com>
 
-Homepage:  http://www.sbopkg.org
+    Sbopkg is released under a one-clause BSD license. See the script
+    itself for the text.
 
 ABOUT
 
-Sbopkg (pronounced s-b-o-package) is a command-line and dialog-based tool to
+    Sbopkg (pronounced 's-b-o-package') is a command-line and
-synchronize with the SlackBuilds.org ("SBo") repository, a collection of
+    menu-based tool to synchronize with the SlackBuilds.org ('SBo')
-third-party SlackBuild scripts to build Slackware packages.  Sbopkg can also
+    repository, a collection of third-party SlackBuild scripts to build
-synchronize with certain third-party repositories or access a
+    Slackware packages. Sbopkg can also synchronize with any repository
-locally-maintained repository.
+    with an SBo-compatible hierarchy, including a locally-maintained
+    repository.
 
-Sbopkg will allow the user to create, synchronize, search, and browse a copy
+    Sbopkg will allow the user to create, synchronize, search, and
-of the active repository (currently, the size of a local copy of the SBo
+    browse a copy of the active repository (currently, the size of a
-repository is xxxSIZExxx), read the ChangeLog (if available), list the
+    local copy of the SBo repository is xxxSIZExxx), read the ChangeLog
-installed SBo packages, display potential updates to SlackBuilds.org packages,
+    (if available), list the installed SBo packages, display potential
-view the README, SlackBuild, .info, and slack-desc files for each package, and
+    updates to SlackBuilds.org packages, view the README, SlackBuild,
-make manual edits to a copy of the original .info or SlackBuild files.  Sbopkg
+    .info, and slack-desc and other files for each package, and make
-will also allow the user to select packages to build and it will download the
+    manual edits to a copy of the original .info or SlackBuild files.
-source code, check the md5sum, build a Slackware package, and, optionally
+    Sbopkg will also allow the user to select packages to build and it
-install the package.  The user can also build, and optionally install, more
+    will download the source code, check the md5sum, build a Slackware
-than one package by using the 'build queue' feature.  Sbopkg will not check
+    package, and optionally install the package. The user can also build
-dependencies since that is not a feature native to Slackware, but since the
+    and optionally install more than one package by using the 'build
-build queue will process packages in the order listed, it sometimes may be
+    queue' feature. Sbopkg will not check dependencies since that is not
-possible to build and install dependencies in order prior to building and
+    a feature native to Slackware, but since the build queue will
-installing the final, desired package.  Given the nature of building
+    process packages in the order listed, it is possible to build and
-dependencies, however, this probably will not always work and is not really a
+    install dependencies in order prior to building and installing the
-supported feature.  Ultimately, Sbopkg is one thing and one thing only: a
+    final, desired package.
-medium to easily browse a local copy of the SlackBuilds.org and certain other
-repositories and build packages from them.
 
-Sbopkg can be also be used strictly from the command line without the
+    Sbopkg can also be used strictly from the command line without the
-dialog interface to do most of the above items.  Typing sbopkg -h
+    dialog(1)-provided menu interface to do most of the above items.
-will display the command line options.
+    Typing 'sbopkg -h' will display the command line options.
 
 HELP
 
     Sbopkg comes with two man pages: sbopkg.conf(5) and sbopkg(8). These
-man pages are kept up-to-date with functional changes in the script
+    are the primary sources of information on how to use sbopkg.
-itself, so they are a good source of information on how to use sbopkg.
 
-If the man pages are not sufficient, please consider joining the sbopkg
+    If you have read the manuals and still need help, you may want to
-mailing list and posting your question there.  You should be able to
+    join the sbopkg mailing list. Subscribe by sending a mail whose body
-subscribe by sending mail to sbopkg-users-request@sbopkg.org whose body
+    is "subscribe your-email@address-here" to:
-is 'subscribe your-email@address-here'. There is also an IRC channel for
-sbopkg on Freenode at #sbopkg.  Further information on all of these
-resources is on the project's website at http://www.sbopkg.org - click
-the "Docs/Help" tab.
 
-CONTRIBUTORS
+    sbopkg-users-request@sbopkg.org
 
-We welcome bug reports, suggestions, patches, or feature requests.
+    or use the web interface:
-Please post any of these to the Issue tracker (kind of like a
+
-Bugzilla) on the project's Google page (click the Issues tab) at
+    http://sbopkg.org/mailman/listinfo/sbopkg-users
-http://code.google.com/p/sbopkg so we can keep track of them.  There
+
-have been many contributors so far, and they are all mentioned near
+    There is also an IRC channel for sbopkg on Freenode at #sbopkg.
-the top of the sbopkg script itself.  Thanks to everyone who has
+
-helped make this script better.
+    Further information on these and other resources is on the project
+    website:
+
+    http://sbopkg.org
+
+    Specifically, the documentation page is:
+
+    http://sbopkg.org/docs.php
+
+CONTRIBUTING
+
+    We welcome bug reports, suggestions/feature requests, and patches.
+    Please post any of these to the issue tracker:
+
+    http://code.google.com/p/sbopkg/issues/list
+
+    Before reporting a bug, please check the KNOWN_ISSUES file. Before
+    contributing a suggestion please check the TODO file. Before
+    submitting a patch, please read the HACKING file.
+
+    Sbopkg's source is available in an svn repository hosted on
+    googlecode. To view a copy of the repo, see:
+
+    http://code.google.com/p/sbopkg/source/browse/
+
+    To obtain a local copy, use something like the following command:
+
+    svn checkout http://sbopkg.googlecode.com/svn/trunk/ sbopkg-contrib
+
+    There have been many contributors so far (see the THANKS file).
+    Thanks to everyone who has helped make this script better.

src/usr/doc/README-queuefiles

@@ -1,22 +1,24 @@
-# $Id$
+README-queuefiles
-# vim:set ft=:
 
-Sbopkg queuefiles are very simple to create, maintain, and share amongst other
+Sbopkg queuefiles are very simple to create, maintain, and share amongst
-users.  Each queuefile can contain a list of applications to build in order,
+other users. Each queuefile can contain a list of packages to build in
-from top to bottom, and should be named with a .sqf extension.  Several sample
+order, from top to bottom, and should be named with a .sqf extension.
-queuefiles are provided in the /doc/queuefiles directory.  Please note that
+Several sample queuefiles are provided in the /doc/queuefiles directory.
-these queuefiles are, in fact, only samples and have not necessarily been
+Please note that these queuefiles are, in fact, only samples and have
-tested on the latest release of Slackware or on Slackware -current.  Please
+not necessarily been tested on the latest release of Slackware or on
-use at your risk.  Additionally, the hope is that user-contributed queues can
+Slackware -current. If you wish to use these at your own risk, remove
-be shared.  Please consider sending a copy of your queuefile to the sbopkg
+the '.sample' extension and either put them in QUEUEDIR or set QUEUEDIR
-mailing list located at: http://sbopkg.org/mailman/listinfo/sbopkg-users.
+to where they are (see sbopkg.conf(5) for details). Additionally, the
+hope is that user-contributed queues can be shared. Please consider
+sending a copy of your queuefile(s) to the sbopkg mailing list located
+at http://sbopkg.org/mailman/listinfo/sbopkg-users.
 
-1.  Selecting ON or OFF in dialog:
+SELECTING ON OR OFF IN DIALOG
 
-If the application's name is left alone, it will default to 'ON,' or
+    If a line starts with an application's name, it will default to 'ON'
-selected, in the sbopkg dialog menus when the queuefile is loaded.  If
+    and be selected in the sbopkg dialog menus when the queuefile is
-the application's name is prepended with a '-' it will default to
+    loaded. If the application's name is prepended with a '-' it will
-'OFF,' or deselected, in the dialog menus.
+    default to 'OFF' and be deselected in the dialog menus.
 
     For example, a queuefile might contain:
 
@@ -24,33 +26,35 @@ foo
         -bar
         baz
 
-In this case, both 'foo' and 'baz' will appear 'ON,' or selected, in the sbopkg
+    In this case, both 'foo' and 'baz' will be 'ON' and appear selected
-dialog menus, and 'bar' will appear 'OFF,' or deselected.
+    in the sbopkg dialog menus, and 'bar' will be 'OFF' and appear
+    deselected.
 
-2.  Recursive queuefiles:
+RECURSIVE QUEUEFILES
 
-Additionally, queuefiles may be loaded recursively.  This means the user can
+    Additionally, queuefiles may be loaded recursively. This means the
-have separate queuefiles for certain applications, or certain queues, and then
+    user can have separate queuefiles for certain applications, or
-a 'master' queuefile can bring them all together.  Recursively-loaded queues
+    certain queues, and then a 'master' queuefile can bring them all
-are indicated by a '@' prepended to the name of the queuefile.
+    together. Recursively-loaded queues are indicated by an '@'
+    prepended to the name of the queuefile.
 
-For example, a user might have one queuefile named 'multimedia.sqf' with these
+    For example, a user might have one queuefile named 'multimedia.sqf'
-items:
+    with these items:
 
         app1
         app2
         app3
 
-And then the user might have another queuefile named 'mydesktop.sqf' with
+    And then the user might have another queuefile named 'mydesktop.sqf'
-these items:
+    with these items:
 
         app4
         app5
         @multimedia.sqf
 
-In this case, when the 'mydesktop.sqf' queuefile is loaded, it will first load
+    In this case, when the 'mydesktop.sqf' queuefile is loaded, it will
-app4, then app5, then the contents of the multimedia.sqf queuefile.  The final
+    first load app4, then app5, then the contents of the multimedia.sqf
-queue will look like this:
+    queuefile. The final queue will look like this:
 
         app4
         app5
@@ -58,23 +62,30 @@ app1
         app2
         app3
 
-3.  Passing build options:
+    (Note that, while a given queuefile must have the .sqf extension to
+    be loaded, the extension is optional within queuefiles. For
+    instance, if multimedia.sqf exists in the QUEUEDIR, '@multimedia'
+    would work in the above example.)
 
-Finally, it is possible to pass build options for an application in a
+PASSING BUILD OPTIONS
-queuefile.  This is done by using a single pipe ('|') character after the
+
-application name.  For example:
+    Finally, it is possible to pass build options for an application in
+    a queuefile. This is done by using a single pipe ('|') character
+    after the application name (spaces are optional). For example:
 
         app | FOO=yes BAR=no
 
-Only use one pipe to separate the application name and the variables.
+    Only use one pipe to separate the application name and the
+    variables.
 
-In case the user has saved build options individually in the dialog interface,
+    In case the user has saved build options individually in the dialog
-and also puts build options for that same application in the queuefile, sbopkg
+    interface, and also puts build options for that same application in
-will ask the user which one should be used.
+    the queuefile, sbopkg will ask the user which one should be used.
 
-4.  Multiple instances.
+DUPLICATE BUILDS/OPTIONS
 
-In all cases, whether loading software names more than once, or indicating
+    In all cases, whether loading software names more than once, or
-build options in more than one queuefile, the first instance will apply.  So
+    indicating build options in more than one queuefile, the first
-if a user has "app" in one queuefile, and "-app" in a recursive queuefile that
+    instance will apply. So if a user has "app" in one queuefile, and
-is loaded further down the list, the first instance, or "app" will prevail.
+    "-app" in a recursive queuefile that is loaded further down the
+    list, the first instance, or "app" will prevail.

src/usr/doc/README-renames.d

@@ -1,14 +1,20 @@
-# $Id$
+README-renames.d
-# vim:set ft=:
 
 The /etc/sbopkg/renames.d directory is the directory that holds files
-associated with renamed software in the SlackBuilds.org repository.  The
+associated with renamed software in the SlackBuilds.org repository.
-default file that is installed with sbopkg is '50-default'.  This file will be
+
-overwritten each time sbopkg is upgraded, so do not make local edits to it.
+Renames are written, one per line, in the following format:
-Instead, create other files with a higher or lower number than 50-default and
+
-list your renamed files in those local files.  The files are loaded in
+oldname=newname
-alphabetical order (like the files in /etc/fonts/conf.d) so 'priority'
+
-is determined from low number to high and the first match wins, so:
+The default file that is installed with sbopkg is '50-default'. This
+file will be overwritten each time sbopkg is upgraded, so do not make
+local edits to it. Instead, create other files with a higher or lower
+number than 50-default and list your renamed files in those local files.
+
+The files are loaded in alphabetical order (like the files in, e.g.,
+/etc/fonts/conf.d) so 'priority' is determined from low number to high
+and the first match wins, so:
 
 $ cat /etc/sbopkg/renames.d/10-local
 foo=bar
@@ -18,7 +24,3 @@ will override anything in a higher-numbered file, including anything in
 
 $ cat /etc/sbopkg/renames.d/50-default
 foo=baz
-
-Renames are written in the following format:
-
-oldname=newname

src/usr/doc/README-repos.d

@@ -1,40 +1,49 @@
-# $Id$
+README-repos.d
-# vim:set ft=:
 
-In sbopkg parlance, a "repository" is a local or remote service used as a
+In sbopkg parlance, a "repository" is a local or remote service used as
-source of scripts.  For example, slackbuilds.org is a repository.  The
+a source of SlackBuilds. For example, slackbuilds.org is a repository.
-builds.slamd64.com project is another repository.  Every repository has one or
+The builds.slamd64.com project is another repository. Every repository
-more "branches".  Branches consist of a single tree of scripts.  For example,
+has one or more "branches". Branches consist of a single tree of scripts
-slackbuilds.org has a 11.0 branch, a 12.0 branch and so on.
+in a category/application hierarchy. For example, slackbuilds.org has a
+11.0 branch, a 12.0 branch and so on.
 
 /etc/sbopkg/repos.d is a directory containing files defining the
-sbopkg-supported repositories and branches.  All *.repo files are scanned in
+repositories and branches sbopkg will use. All *.repo files are scanned
-alphabetical order.  Every line in a *.repo file defines a branch.  Each line
+in alphabetical order. Every line in a *.repo file defines a branch
-is compound of the following seven fields:
+except those _containing_ a '#' which are ignored. Lines containing
-
-1.  REPOSITORY (a _short_ name identifying the repository)
-2.  BRANCH (a _short_ name identifying the branch of that repository)
-3.  DESCRIPTION (a <50 chars description, which _must_be_quoted_)
-4.  TAG (the packages' tag)
-5.  TOOL (rsync, git or "", is the tool able to check out the repository/branch)
-6.  LINK (the tool-dependent link to the branch)
-7.  CHECKGPG (whether the repo provides .asc signature files and signed
-    tarballs that can be verified with GPG)
-
-For example, one branch (line) of the sbo.repo file might look like this (note
-the seven fields):
-
-SBo 12.2 "SBo repository for Slackware 12.2" _SBo rsync slackbuilds.org::slackbuilds/12.2 GPG
-
-If TOOL is set to "", then it will not be possible to automatically update the
-branch (i.e., it has no upstream).  This is most commonly used for
-locally-maintained repositories on the host filesystem that do not use rsync
-or git to pull down the repository tree.  The LINK format is essentially what
-is required to be passed to the specified TOOL.  In case of git links, it
-_must_ be in the form url@branch.  If TOOL is "", LINK is ignored (but _must_
-still be present).  CHECKGPG format can be "GPG" if the repo supports GPG
-checking, or "" (which also must be present) if the repo does not support GPG
-checks.
-
-Lines _containing_ # are ignored when parsing the files.  Lines containing
 backslashes (\) are not allowed.
+
+Each line contains the following seven fields (if a field is not
+applicable, it still _must_ be present in the form of an empty quote
+(""):
+
+1. REPO
+    A _short_ name identifying the repository; e.g., 'SBo'.
+2. BRANCH
+    A _short_ name identifying the branch of that repository; e.g.,
+    '11.0'.
+3. DESCRIPTION
+    A description of the repo, which _must be quoted_ and must be less
+    than 50 characters long; e.g., '"SBo repository for Slackware
+    11.0"'.
+4. TAG
+    The tag the built packages will have; e.g., '_SBo'.
+5. TOOL
+    The tools used to download the repository/branch. The currently
+    supported value is 'rsync'. Using 'git' is also possible. Local
+    repos will have an empty quote. If this field is an empty quote, it
+    will not be possible to automatically update the branch (i.e., it
+    has no upstream).
+6. LINK
+    The link (URL) to the branch that the TOOL will use. Local repos
+    will have an empty quote. In the case of git links, it _must_ be in
+    the form url@branch.
+7. CHECKGPG
+    Filled with 'GPG' if the repo provides .asc signature files and
+    signed tarballs that can be verified with GPG, and an empty quote
+    otherwise.
+
+For example, one branch (line) of the sbo.repo file looks like this
+(note the seven fields):
+
+SBo 11.0 "SBo repository for Slackware 11.0" _SBo rsync slackbuilds.org::slackbuilds/11.0 GPG

src/usr/doc/THANKS

@@ -0,0 +1,71 @@
+SBOPKG THANKS
+
+The following people have contributed to the development of sbopkg. They
+are generally listed by the revision number the effect of their first
+contribution entered the trunk, followed by their alternate name(s) (if
+any), and the type(s) of contributions. This script would not be where
+it is without the help of these folks. If we left anyone out, we
+apologize. Thank you!
+
+   1 Chess Griffin (project initiation, bug reports, suggestions, code)
+  14 Bob Lounsbury (suggestion)
+  14 Robby Workman (suggestion)
+  14 Alan Hicks (suggestion)
+  14 Paul Wisehart (suggestion
+  14 Phillip Warner (bug reports, suggestion)
+  14 slakmagik (bug reports, suggestions, code)
+  ?? Eric Hameleers (?,code)
+  ?? Michiel van Wessem (?)
+  30 hba (patch)
+  77 Erik Hanson (suggestions, patches)
+  ?? Antoine (bug report)
+  97 ktabic (bug report)
+  97 Ken Roberts (bug report)
+ 120 samac (bug report)
+ 122 Bert Babington (patch)
+ 123 Murat D. Kadirov [banderols] (suggestion)
+ 157 The-spiki (bug report, suggestion)
+ 160 David Somero (bug report)
+ 174 LukenShiro (bug reports)
+ 182 Drew Ames (bug report, suggestion)
+ 186 nille (suggestion)
+ 192 acidchild (bug report)
+ ??? mancha (?)
+ 194 macavity (patch, suggestion)
+ 197 Zordrak (suggestion)
+ 201 Joao Felipe Santos (bug report)
+ 205 Jorge Gaton (bug report)
+ 213 cotterochan (bug report)
+ 228 necropresto (bug report)
+ 230 Pierre Cazenave (bug report)
+ 257 Mauro Giachero (bug reports, suggestions, code)
+ 259 The-Croupier (suggestion)
+ 282 Wade Grant (bug report)
+ 283 SpacePlod (bug report)
+ 389 TSquaredF (suggestion)
+ 398 alkos333 (suggestion, code)
+ 418 Gregory Tourte [artourter] (bug reports, suggestions)
+ 464 Marie-Claude Collilieux (translations)
+ 534 Glenn Becker (bug reports)
+ 534 jturning (bug report)
+ 584 David Spencer (bug reports; testing fix)
+ 641 NaCl (bug report)
+ 661 neonflux (bug report)
+ 673 Marco Bonetti (suggestion)
+ 696 dive (suggestion)
+ 700 idknow (bug report)
+ 706 slackhead (bug report)
+ 716 happyslacker (suggestion)
+ 720 pokipoki08 (suggestion)
+ 723 SiegeX (bug report and suggestions)
+ 723 Zmyrgel (bug report and suggestions)
+ 723 BCarey (bug report and suggestions)
+ 735 godling (bug report)
+ 748 Matteo Bernardini (suggestion)
+ 757 agikhan (suggestion)
+ 770 slava18 (bug reports)
+ 772 skalkoto (bug report)
+ 828 Marc Payne (confirming bug report)
+ 847 catkin (bug report)
+ 849 chytraeus (bug report)
+ 850 greinze (bug report)

src/usr/doc/TODO

@@ -1,27 +1,29 @@
-# $Id$
+SBOPKG TODO
-# vim:set ft=:
 
-Sbopkg TODO (in no particular order)
+Items should be grouped by {High,Medium,Low} Priorities with sub-groups
-* Add in better traps and error checks so a user can safely exit (by pressing
+of {Feature,Modification,Bugfix} Categories.
-  Control-C) during the source download or during the package building
+
-  process.  I have spent a _lot_ of time hacking on this but have not come up
+MEDIUM PRIORITY
-  with a workable solution yet.  The problem is that many subprocesses are
+
-  forked off during the package building process and it's difficult to capture
+    Feature Category
-  all the pids.  If anyone wants to help with this, please let me know.
+
-  of sbopkg 0.26.0.
+        * Allow lftp as a sync method.
-* Include a way to change the sync from rsync to lftp for those who have rsync
+
-  blocked.
+    Modification Category
-* Figure out proper way of testing getopts in order to prevent certain cli
+
-  options from being used together, such as -b and -i.  Right now, there is a
+        * Properly test supplied options to ensure that only sensible
-  crude test to prevent -b and -i from being used together, but I know there
+          option combinations are allowed, thus replacing the current
-  is a better way.
+          crude test which only prevents -b and -i from being used
-* Add 'long' switches to the cli options, i.e. --build in addition to the
+          together.
-  current -b switch.  This is pretty low priority, IMHO, and something tells
+
-  me that getopts does not like long options anyway.
+LOW PRIORITY
-* Maybe change all instances of 'dialog' to $DIALOG and set $DIALOG to be a
+
-  variable equal to either 'dialog' or 'xdialog' in case someone wanted to run
+    Feature Category
-  sbopkg using xdialog.  I don't know how compatible dialog is with xdialog so
+
-  if there was breakage, I would not want to really address it as being able
+        * Replace getopts call with custom option parsing and add 'long'
-  to use xdialog is not important to me.  I prefer dialog anyway.
+          switches to the cli options (for example, '--build' in
-* More error checking.
+          addition to the current '-b' switch).
-* General code cleanups.
+
+        * Replace all calls to dialog with a DIALOG variable (which
+          would still default to dialog), allowing users to more easily
+          try other interfaces.

src/usr/sbin/sbopkg

@@ -23,21 +23,6 @@
 #  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 #  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 #  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-#
-#  Slackware is a registered trademark of Patrick Volkerding.
-#  Linux is a registered trademark of Linus Torvalds.
-#
-#  Other contributors:  Bob Lounsbury, Robby Workman, Alan Hicks, Paul
-#  Wisehart, slakmagik, Eric Hameleers, Michiel van Wessem, hba, Erik Hanson,
-#  Antoine, ktabic, Ken Roberts, samac, Bert Babington, Murat D. Kadirov,
-#  The-spiki, David Somero, LukenShiro, Drew Ames, nille, acidchild, mancha,
-#  macavity, Zordrak, João Felipe Santos, cotterochan, necropresto, Pierre
-#  Cazenave, Mauro Giachero, The-Croupier, Wade Grant, TSquaredF, alkos333,
-#  Marco Bonetti and Gregory Tourte.
-#  This script would not be where it is without the help of these folks.
-#  If I left anyone out, I apologize.  Thank you!
-#
-#set -x
 
 dialog_refresh_workaround() {
     # Dialog has refresh problems on some terminals (currently known are some