revise most of doc/*

- KNOWN_ISSUES: rephrase the dialog navigation section in a way that
    should be more suitable for the forthcoming (when it's ready)
    Slackware release which will have an updated dialog. Rephrase the
    certcheck section to discuss the prompt behavior and to point out
    how the 'openssl-certs' package can help with, but not eliminate,
    the issue.

  - NEWS: add an item summarizing these document revisions and add the
    branch ChangeLog sections.

    When we started what became 0.30.0, we created an 0.27.0 stable
    branch and the changes in that branch were only included in that
    branch's ChangeLog.txt. Ditto the 0.33.1 security branch. But all
    releases should be documented in the NEWS file, so now they are.

  - README: add a block that describes all the other doc/ files, add a
    note about GPG checking, change the name of the HELP section to
    GETTING HELP.

    Some of the doc files are mentioned in the CONTRIBUTING section but
    a comprehensive list with descriptions in the GETTING HELP section
    is more, um, helpful.

  - README-*: tweak the wording, mostly to reflect the last commit's
    name change, and reorder some text to put the emphasis on the files
    rather than the directory. Also make a couple of other tweaks.

  - THANKS: add a note about making corrections and slightly reorder the
    text around that change for better flow and emphasis.

src/usr/doc/KNOWN_ISSUES

@@ -3,14 +3,12 @@ SBOPKG KNOWN ISSUES
 The following are the known user-visible issues in sbopkg or upstream in
 the tools it uses:
 
-* In dialog '--inputbox' widgets (the boxes the user types text into)
+* In dialog versions before 20100119 the left/right arrows in
-  the left/right arrows do not navigate in a button context. (They do
+  '--inputbox' widgets (the boxes the user types text into) do not
-  navigate in an editing context.) This does not seem to be an sbopkg
+  navigate in a button context. (They do navigate in an editing
-  issue.
+  context.) This does not seem to be an sbopkg issue.
 
-  Workaround: navigate with up/down arrows or tab/shift-tab Note: there
+  Workaround: navigate with up/down arrows or tab/shift-tab.
-  is a newer dialog version available which fixes this issue, but we
-  encourage users to stick with the dialog Slackware ships.
 
 * If dialog is run in a terminal emulator and the user exits using the
   window manager's 'close' (or equivalent) button/command, dialog may
@@ -44,11 +42,16 @@ the tools it uses:
 
   Workaround: pager-specific
 
-* A few SlackBuild scripts in the slackbuilds.org repo have a source
+* Some SlackBuild scripts in the SlackBuilds.org repo have a source
-  download that is only available through an https download.  By
+  download that is only available through https. By default, sbopkg will
-  default, sbopkg will not be able to download these sources.
+  initially fail to download these sources, but will then offer to turn
+  off certificate checking temporarily and should then succeed.
 
-  Workaround: add --no-check-certificate to WGETFLAGS in sbopkg.conf
+  Workaround: The best step, in many cases, is to install
+  'openssl-certs' from SBo, though this will not help for 'self-signed'
+  certificates which will still trigger the prompt. To avoid it
+  altogether you can permanently turn off 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'

src/usr/doc/NEWS

@@ -15,6 +15,13 @@ sbopkg xxxVERSIONxxx (xxxDATExxx)
 
         * Updated French man pages. Thanks to Marie-Claude Collilieux.
 
+        * Revised documentation: 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.
+
     BUGFIXES
 
         * Fixed an issue where URL redirects and SSL certificate check
@@ -143,6 +150,10 @@ sbopkg 0.34.0 (2010-11-12 03:37 UTC)
       download, invoking wget with '--no-check-certificate', as this can
       be caused by 'self-signed certificates' and the like.
 
+sbopkg 0.33.2 (2010-07-20 02:10 UTC)
+
+    * fix security issue involving unsafe creation of temp{dir,file}
+
 sbopkg 0.33.1 (2010-05-27 18:13 UTC)
 
     * The ARCH assignment was modified to accord with the latest SBo
@@ -507,6 +518,81 @@ sbopkg 0.30.0 (2009-08-24 17:28 UTC)
       and obsolete sources and packages dialogs; thanks to dive for the
       suggestion.
 
+sbopkg 0.27.4 (2009-06-24 16:13 UTC)
+
+    * Fix rare issue where incorrect file was upgraded; thanks to neonflux for
+      the bug report.
+
+    * Fix issue where custom build options may not be correctly exported.
+
+    * Improve cleanup after building or installing a package.
+
+sbopkg 0.27.3 (2009-06-15 00:51 UTC)
+
+    * Add museek-plus->museek+ to sbopkg-renames.new.
+
+    * Modify the source fetching code to check the md5sum also of cached
+      sources, to fix problems arising with those programs whose source archive
+      doesn't change name on version updates. Thanks to David Spencer for
+      raising the issue.
+
+    * Exit edit_build_queue menu with 'ESC'; thanks to Nille for the bug report.
+
+    * Modify do_install() to correctly invoke upgradepkg to avoid a fairly rare
+      but serious case of removing the wrong package; thanks to NaCl for the
+      bug report.
+
+sbopkg 0.27.2 (2009-04-30 14:36 UTC)
+
+    * Remove a stale 'find' call, which slightly improves the update feature.
+
+    * Add acroread->adobe-reader and GNOME-Colors->gnome-colors to
+      sbopkg-renames.new.
+
+    * Display a message when no packages are installed instead of doing nothing.
+
+    * Properly quote the current working directory variable in the event there
+      are spaces in the directory name.
+
+    * Fix a bug where 'sbopkg -c -v local' would display a dialog even though
+      running in cli mode.
+
+    * Fix issue where the 'games' directory was non-browsable due to a
+      slack-desc file containing double-quotes in the first line; thanks to
+      Glenn Becker for the original bug report.
+
+sbopkg 0.27.1 (2009-04-07 13:32 UTC)
+
+    * Remove some useless code from check_for_latest and also fix the
+      download folder for sbopkg updates.  Thanks to David Somero for the bug
+      report.
+
+    * Re-implement the code that checks for renamed software; fix upgrading
+      of renamed packages; thanks to Phillip Warner for raising the issues
+      with the older code; add wbxml2->libwbxml to sbopkg-renames; thanks to
+      Mauro Giachero for working on these fixes.
+
+    * Fix a tr invocation issue where in certain instances, sbopkg would not run
+      from certain directories; thanks to Marie-Claude Collilieux for the bug
+      report.
+
+    * Alter sed expression in download code to work around calcurse filename
+      idiosyncrasy; thanks to Glenn Becker for the bug report.
+
+    * Move French man pages into correct /usr/man/fr* location and remove them
+      from the /docs directory; update French man pages; thanks to
+      Marie-Claude Collilieux.
+
+    * Fix a problem with the Pre-Check Log dialog being non-scrollable and
+      having a visual glitch. Thanks to Erik Hanson for the bug report.
+
+    * Remove a problem where the "Using the queuefile QUEUEFILE" messages could
+      be incorrect.
+
+    * Fix a possible infinite loop when building in CLI mode.
+
+    * Fix an issue with an ncurses check and the cleanup() function.
+
 sbopkg 0.27.0 (2009-02-26 14:48 UTC)
 
     * Commit a patch that adds a new sbopkg.conf configuration variable,

src/usr/doc/README

@@ -26,27 +26,40 @@ ABOUT
     .info, and slack-desc and other files for each package, and make
     manual edits to a copy of the original .info or SlackBuild files.
     Sbopkg will also allow the user to select packages to build and it
-    will download the source code, check the md5sum, build a Slackware
+    will download the source code, check the md5sum and GPG signature,
-    package, and optionally install the package. The user can also build
+    build a Slackware package, and optionally install the package. The
-    and optionally install more than one package by using the 'build
+    user can also build and optionally install more than one package by
-    queue' feature. Sbopkg will not check dependencies since that is not
+    using the 'build queue' feature. Sbopkg will not check dependencies
-    a feature native to Slackware, but since the build queue will
+    since that is not a feature native to Slackware, but since the build
-    process packages in the order listed, it is possible to build and
+    queue will process packages in the order listed, it is possible to
-    install dependencies in order prior to building and installing the
+    build and install dependencies in order prior to building and
-    final, desired package.
+    installing the final, desired package.
 
     Sbopkg can also be used strictly from the command line without the
     dialog(1)-provided menu interface to do most of the above items.
     Typing 'sbopkg -h' will display the command line options.
 
-HELP
+GETTING HELP
 
     Sbopkg comes with two man pages: sbopkg.conf(5) and sbopkg(8). These
     are the primary sources of information on how to use sbopkg.
 
-    If you have read the manuals and still need help, you may want to
+    In addition to the manuals and this file, the following documents
-    join the sbopkg mailing list. Subscribe by sending a mail whose body
+    may be of interest:
-    is "subscribe your-email@address-here" to:
+
+    HACKING           Coding and documentation guidelines
+    KNOWN_ISSUES      Problems and workarounds
+    NEWS              History of user-visible changes
+    README-queuefiles Details on queuefiles and their format
+    README-renames    Details on rename files and their format
+    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
+
+    If you have read the manuals and the relevant documents and still
+    need help, you may want to join the sbopkg mailing list. Subscribe
+    by sending a mail whose body is "subscribe your-email@address-here"
+    to:
 
     sbopkg-users-request@sbopkg.org
 

src/usr/doc/README-queuefiles

@@ -1,17 +1,19 @@
 README-queuefiles
 
-Sbopkg queuefiles are very simple to create, maintain, and share amongst
+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 directory.
+Several sample queuefiles are provided in the ./doc/queuefiles
-Please note that these queuefiles are, in fact, only samples and have
+directory. Please note that these queuefiles are, in fact, only samples
-not necessarily been tested on the latest release of Slackware or on
+and have not necessarily been tested on the latest release of Slackware
-Slackware -current. If you wish to use these at your own risk, remove
+or on Slackware -current. If you wish to use these at your own risk,
-the '.sample' extension and either put them in QUEUEDIR or set QUEUEDIR
+remove the '.sample' extension and either put them in $QUEUEDIR or set
-to where they are (see sbopkg.conf(5) for details). Additionally, the
+QUEUEDIR to where they are (see sbopkg.conf(5) for details).
-hope is that user-contributed queues can be shared. Please consider
+Additionally, the hope is that user-contributed queues can be shared.
-sending a copy of your queuefile(s) to the sbopkg mailing list located
+Please consider sending a copy of your queuefile(s) to the sbopkg
-at http://sbopkg.org/mailman/listinfo/sbopkg-users.
+mailing list:
+
+http://sbopkg.org/mailman/listinfo/sbopkg-users
 
 SELECTING ON OR OFF IN DIALOG
 
@@ -80,7 +82,7 @@ PASSING BUILD OPTIONS
 
     In case the user has saved build options individually in the dialog
     interface, and also puts build options for that same application in
-    the queuefile, sbopkg will ask the user which one should be used.
+    the queuefile, sbopkg will ask the user which set should be used.
 
 DUPLICATE BUILDS/OPTIONS
 

src/usr/doc/README-renames

@@ -1,18 +1,20 @@
-README-renames.d
+README-renames
 
-The /etc/sbopkg/renames.d directory is the directory that holds files
+Packages which are renamed in a repository are handled by adding them to
-associated with renamed software in the SlackBuilds.org repository.
+a rename file and placing that file in the /etc/sbopkg/renames.d
+directory.
 
 Renames are written, one per line, in the following format:
 
 oldname=newname
 
 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
+file is kept in sync with the SBo repository and will be overwritten
-local edits to it. Instead, create other files with a higher or lower
+each time sbopkg is upgraded, so do not make local edits to it. Instead,
-number than 50-default and list your renamed files in those local files.
+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.,
+The files are loaded in alphanumeric 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

@@ -1,17 +1,17 @@
-README-repos.d
+README-repos
 
-In sbopkg parlance, a "repository" is a local or remote service used as
+In sbopkg terminology, a "repository" (or "repo") is a local or remote
-a source of SlackBuilds. For example, slackbuilds.org is a repository.
+service used as a source of SlackBuilds. For example, slackbuilds.org is
-The builds.slamd64.com project is another repository. Every repository
+a repository. The builds.slamd64.com project is another repository.
-has one or more "branches". Branches consist of a single tree of scripts
+Every repository has one or more "branches". Branches consist of a
-in a category/application hierarchy. For example, slackbuilds.org has a
+single tree of scripts in a category/application hierarchy. For example,
-11.0 branch, a 12.0 branch and so on.
+slackbuilds.org has an 11.0 branch, a 12.0 branch and so on.
 
-/etc/sbopkg/repos.d is a directory containing files defining the
+The repos and their branches that sbopkg will use are defined in a set
-repositories and branches sbopkg will use. All *.repo files are scanned
+of files which are stored in /etc/sbopkg/repos.d. All *.repo files are
-in alphabetical order. Every line in a *.repo file defines a branch
+scanned in alphanumeric order. Every line in a *.repo file defines a
-except those _containing_ a '#' which are ignored. Lines containing
+branch except those _containing_ a '#' which are ignored. Lines
-backslashes (\) are not allowed.
+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

src/usr/doc/THANKS

@@ -3,9 +3,12 @@ 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
+any), and the type(s) of contributions. If we left anyone out or
-it is without the help of these folks. If we left anyone out, we
+mischaracterized anything, we apologize. Report it to us and, if we can
-apologize. Thank you!
+find a record of it, we'll fix it.
+
+This script would not be where it is without the help of these folks.
+Thank you!
 
    1 Chess Griffin (project initiation, bug reports, suggestions, code)
   14 Bob Lounsbury (suggestion)