another pass over the plaintext documentation

Mostly minor changes, bringing things up to date. I did revert part of
r879 regarding the alpha* sorting at least for now.

src/usr/doc/KNOWN_ISSUES

@@ -6,7 +6,7 @@ the tools it uses:
 * In dialog versions before 20100119 the left/right arrows in
   '--inputbox' widgets (the boxes the user types text into) do not
   navigate in a button context. (They do navigate in an editing
-  context.) This does not seem to be an sbopkg issue.
+  context.)
 
   Workaround: navigate with up/down arrows or tab/shift-tab.
 
@@ -42,16 +42,20 @@ the tools it uses:
 
   Workaround: pager-specific
 
-* Some SlackBuild scripts in the SlackBuilds.org repo have a source
+* In Slackware 13.1 and earlier and sbopkg 0.33.2 and earlier, sbopkg
-  download that is only available through https. By default, sbopkg will
+  would initially fail to download SlackBuilds only available through
-  initially fail to download these sources, but will then offer to turn
+  https. With more recent versions of sbopkg, it will offer to retry
-  off certificate checking temporarily and should then succeed.
+  with certificate checking temporarily disabled and should then
+  succeed. With more recent versions of Slackware, everything should
+  Just Work unless there is an issue with 'self-signed' certificates or
+  the like. Then the prompt to disable should still work.
 
-  Workaround: The best step, in many cases, is to install
+  Workaround: In Slackware 13.1 and earlier, the best step, in many
-  'openssl-certs' from SBo, though this will not help for 'self-signed'
+  cases, is to install 'openssl-certs' from SBo, though this will not
-  certificates which will still trigger the prompt. To avoid it
+  help for 'self-signed' certificates which will still trigger the
-  altogether you can permanently turn off certificate checking by adding
+  prompt. To avoid it altogether you can permanently turn off
-  '--no-check-certificate' to WGETFLAGS in sbopkg.conf.
+  certificate checking by adding '--no-check-certificate' to WGETFLAGS
+  in sbopkg.conf.
 
 * Certain packages build kernel modules and need to (re)set the ARCH to
   'x86' on i?86 (32-bit) systems which may result in packages with 'x86'
@@ -68,3 +72,14 @@ the tools it uses:
   http://sbopkg.org/pipermail/sbopkg-users/2010-May/000477.html
 
   Workaround: see above links
+
+* When using the sbopkg bash completion file, 'sbopkg -V <TAB>' produces
+  only branches as output rather than 'repo/branch'es. Currently, this
+  works fine (just as if you typed 'sbopkg -V branch' yourself) but
+  means you need to know which branches go to which repos. Also, it
+  might have been more convenient to drop this in /etc/bash_completion.d
+  but the full Slackware bash completion package (in extra) had an
+  sbopkg completion file and may again someday and placing it in
+  doc/contrib avoids any namespace or loading collisions.
+
+  Workaround: none needed

src/usr/doc/NEWS

@@ -23,16 +23,27 @@ sbopkg xxxVERSIONxxx (xxxDATExxx)
           clobber them. See each of the two following sections for more
           repo-related modifications and bugfixing.
 
+        * Added a bash completion file for sbopkg. This is independent
+          of the bash-completion package. It can be found in the new
+          doc/contrib directory. Source the file (in your shell startup
+          files if you want it always on automatically) from its current
+          location or wherever you wish to copy it and you should be
+          able to complete some of sbopkg's flags and their arguments.
+          Also see the KNOWN_ISSUES file. Thanks to Sergey V. for this
+          contribution.
+
     MODIFICATIONS
 
         * Updated French man pages. Thanks to Marie-Claude Collilieux.
 
-        * Revised documentation: renamed the README-*.d documents,
+        * Revised documentation: moved the queuefiles directory into a
+          new contrib directory, renamed the README-*.d documents,
           stripping the '.d'. Clarified/updated the dialog nav/certcheck
           sections of KNOWN_ISSUES, brought the missing 0.27.0 and
           0.33.1 branch changes from their ChangeLogs into NEWS, added a
           block in README describing all the plain text documents, added
-          a note about making corrections to THANKS, etc.
+          a note about making corrections to THANKS, a couple of TODO
+          items, etc.
 
         * Note also that symlinks are now made from README-repos and
           README-renames to READMEs in the corresponding /etc/sbopkg/*.d
@@ -90,6 +101,10 @@ sbopkg xxxVERSIONxxx (xxxDATExxx)
           be switched anyway, despite the directory not being created.
           Now, the original repo is restored as the active one.
 
+        * Fixed a bug in a previous bugfix that would still let sbopkg
+          download source files whose DOWNLOAD value ended in
+          '/download' even when the source files were cached.
+
 sbopkg 0.34.1 (2011-02-05 04:20 UTC)
 
     FEATURES

src/usr/doc/README

@@ -55,6 +55,7 @@ GETTING HELP
     README-repos      Details on repo files and their format
     THANKS            Appreciation of contributors to sbopkg
     TODO              Things that may be added or modified in the future
+    contrib/          Additional user-contributed files
 
     If you have read the manuals and the relevant documents and still
     need help, you may want to join the sbopkg mailing list. Subscribe

src/usr/doc/README-queuefiles

@@ -3,7 +3,7 @@ README-queuefiles
 Sbopkg queuefiles are very simple to create, maintain, and share with
 other users. Each queuefile can contain a list of packages to build in
 order, from top to bottom, and should be named with a .sqf extension.
-Several sample queuefiles are provided in the ./doc/queuefiles
+Several sample queuefiles are provided in the ./contrib/queuefiles
 directory. Please note that these queuefiles are, in fact, only samples
 and have not necessarily been tested on the latest release of Slackware
 or on Slackware -current. If you wish to use these at your own risk,
@@ -47,7 +47,7 @@ RECURSIVE QUEUEFILES
         app2
         app3
 
-    And then the user might have another queuefile named 'mydesktop.sqf'
+    And then the user might have another queuefile named 'desktop.sqf'
     with these items:
 
         app4
@@ -80,9 +80,10 @@ PASSING BUILD OPTIONS
     Only use one pipe to separate the application name and the
     variables.
 
-    In case the user has saved build options individually in the dialog
+    In cases where the user has passed options on the command line
-    interface, and also puts build options for that same application in
+    and/or saved build options individually via the dialog interface,
-    the queuefile, sbopkg will ask the user which set should be used.
+    and also puts build options for that same application in the
+    queuefile, sbopkg will ask the user which set should be used.
 
 DUPLICATE BUILDS/OPTIONS
 

src/usr/doc/README-renames

@@ -14,7 +14,7 @@ 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
 and list your renamed files in those local files.
 
-The files are loaded in alphanumeric order (like the files in, e.g.,
+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:
 

src/usr/doc/README-repos

@@ -2,14 +2,14 @@ README-repos
 
 In sbopkg terminology, a "repository" (or "repo") is a local or remote
 service used as a source of SlackBuilds. For example, slackbuilds.org is
-a repository. The builds.slamd64.com project is another repository.
+a repository. Every repository has one or more "branches". Branches
-Every repository has one or more "branches". Branches consist of a
+consist of a single tree of scripts in a category/application hierarchy.
-single tree of scripts in a category/application hierarchy. For example,
+For example, slackbuilds.org has an 11.0 branch, a 12.0 branch and so
-slackbuilds.org has an 11.0 branch, a 12.0 branch and so on.
+on.
 
 The repos and their branches that sbopkg will use are defined in a set
 of files which are stored in /etc/sbopkg/repos.d. All *.repo files are
-scanned in alphanumeric order. Every line in a *.repo file defines a
+scanned in alphabetical order. Every line in a *.repo file defines a
 branch except those _containing_ a '#' which are ignored. Lines
 containing backslashes (\) are not allowed.
 
@@ -27,7 +27,8 @@ applicable, it still _must_ be present in the form of an empty quote
     than 50 characters long; e.g., '"SBo repository for Slackware
     11.0"'.
 4. TAG
-    The tag the built packages will have; e.g., '_SBo'.
+    The tag the built packages will have. (If the built package is
+    'app-1.0-i486-1_SBo', the tag is '_SBo'.)
 5. TOOL
     The tools used to download the repository/branch. The currently
     supported value is 'rsync'. Using 'git' is also possible. Local

src/usr/doc/THANKS

@@ -76,3 +76,4 @@ Thank you!
  863 vbatts (bug report)
  864 Bill Kirkpatrick (bug report)
  875 dmotaleite (suggestion)
+ 894 Sergey V. (bash completion)

src/usr/doc/TODO

@@ -7,7 +7,10 @@ MEDIUM PRIORITY
 
     Feature Category
 
-        * Allow lftp as a sync method.
+        * Add lftp to sync methods.
+
+        * Add flag to skip prompts and force building packages or queues
+          when both exist with the same name. (Suggested by OzanBurada.)
 
     Modification Category
 
@@ -27,3 +30,8 @@ LOW PRIORITY
         * Replace all calls to dialog with a DIALOG variable (which
           would still default to dialog), allowing users to more easily
           try other interfaces.
+
+    Modification Category
+
+        * Smooth out the oddities regarding which vars can be passed how
+          (such as BUILD and TAG).