From 8b3d568e118418635bffde8c07be278a08d94658 Mon Sep 17 00:00:00 2001 From: slakmagik Date: Tue, 8 Mar 2011 03:38:19 +0000 Subject: [PATCH] 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 | 25 +++++----- src/usr/doc/NEWS | 86 +++++++++++++++++++++++++++++++++++ src/usr/doc/README | 37 ++++++++++----- src/usr/doc/README-queuefiles | 24 +++++----- src/usr/doc/README-renames | 16 ++++--- src/usr/doc/README-repos | 24 +++++----- src/usr/doc/THANKS | 9 ++-- 7 files changed, 165 insertions(+), 56 deletions(-) diff --git a/src/usr/doc/KNOWN_ISSUES b/src/usr/doc/KNOWN_ISSUES index dc557fa..07e8ce5 100644 --- a/src/usr/doc/KNOWN_ISSUES +++ b/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) - the left/right arrows do not navigate in a button context. (They do - navigate in an editing context.) This does not seem to be an sbopkg - issue. +* 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. - Workaround: navigate with up/down arrows or tab/shift-tab Note: there - is a newer dialog version available which fixes this issue, but we - encourage users to stick with the dialog Slackware ships. + Workaround: navigate with up/down arrows or tab/shift-tab. * 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 - download that is only available through an https download. By - default, sbopkg will not be able to download these sources. +* Some SlackBuild scripts in the SlackBuilds.org repo have a source + download that is only available through https. By default, sbopkg will + 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' diff --git a/src/usr/doc/NEWS b/src/usr/doc/NEWS index 5757457..7c0bb4c 100644 --- a/src/usr/doc/NEWS +++ b/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, diff --git a/src/usr/doc/README b/src/usr/doc/README index db70348..70f26ca 100644 --- a/src/usr/doc/README +++ b/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 - package, and optionally install the package. The user can also build - and optionally install more than one package by using the 'build - queue' feature. Sbopkg will not check dependencies since that is not - a feature native to Slackware, but since the build queue will - process packages in the order listed, it is possible to build and - install dependencies in order prior to building and installing the - final, desired package. + will download the source code, check the md5sum and GPG signature, + build a Slackware package, and optionally install the package. The + user can also build and optionally install more than one package by + using the 'build queue' feature. Sbopkg will not check dependencies + since that is not a feature native to Slackware, but since the build + queue will process packages in the order listed, it is possible to + build and install dependencies in order prior to building and + 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 - join the sbopkg mailing list. Subscribe by sending a mail whose body - is "subscribe your-email@address-here" to: + In addition to the manuals and this file, the following documents + may be of interest: + + 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 diff --git a/src/usr/doc/README-queuefiles b/src/usr/doc/README-queuefiles index c9659b1..2ce7177 100644 --- a/src/usr/doc/README-queuefiles +++ b/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. -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, remove -the '.sample' extension and either put them in QUEUEDIR or set QUEUEDIR -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. +Several sample queuefiles are provided in the ./doc/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, +remove the '.sample' extension and either put them in $QUEUEDIR or set +QUEUEDIR 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: + +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 diff --git a/src/usr/doc/README-renames b/src/usr/doc/README-renames index 75b5acb..fad5d22 100644 --- a/src/usr/doc/README-renames +++ b/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 -associated with renamed software in the SlackBuilds.org repository. +Packages which are renamed in a repository are handled by adding them to +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 -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. +file is kept in sync with the SBo repository and 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., +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: diff --git a/src/usr/doc/README-repos b/src/usr/doc/README-repos index 279cca9..a55a51f 100644 --- a/src/usr/doc/README-repos +++ b/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 -a source of SlackBuilds. For example, slackbuilds.org is a repository. -The builds.slamd64.com project is another repository. Every repository -has one or more "branches". Branches consist of a single tree of scripts -in a category/application hierarchy. For example, slackbuilds.org has a -11.0 branch, a 12.0 branch and so on. +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. +Every repository has one or more "branches". Branches consist of a +single tree of scripts in a category/application hierarchy. For example, +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 -repositories and branches sbopkg will use. All *.repo files are 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. +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 +branch except those _containing_ a '#' which are ignored. 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 diff --git a/src/usr/doc/THANKS b/src/usr/doc/THANKS index 027d21e..73c7d44 100644 --- a/src/usr/doc/THANKS +++ b/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 -it is without the help of these folks. If we left anyone out, we -apologize. Thank you! +any), and the type(s) of contributions. If we left anyone out or +mischaracterized anything, we apologize. Report it to us and, if we can +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)