From 7e26d3b5d509b2e8d4406c1b8c721446b624f88d Mon Sep 17 00:00:00 2001 From: slakmagik Date: Wed, 2 Jun 2010 23:04:50 +0000 Subject: [PATCH] General textual revisions to manpages Also corrected one point in HACKING relevant to earlier revisions and added three more points relevant to this one. However, the vast majority of changes in this revision don't fall under those three points or any easily generalizable description. They're just attempts at more clarity, consistency, accuracy, etc. Oh, and some punctuation, too. --- src/usr/doc/HACKING | 11 +++- src/usr/man/man5/sbopkg.conf.5 | 43 ++++++------ src/usr/man/man8/sbopkg.8 | 115 +++++++++++++++++++-------------- 3 files changed, 99 insertions(+), 70 deletions(-) diff --git a/src/usr/doc/HACKING b/src/usr/doc/HACKING index 14211c3..d4545fb 100644 --- a/src/usr/doc/HACKING +++ b/src/usr/doc/HACKING @@ -237,8 +237,8 @@ Manual Page Style Guidelines ---------------------------- * Separate all text header and section header requests with commented lines of - equal (=) signs. Separate all tagged paragraphs that serve as subsections - with commented lines of minus (-) signs. + equal (=) signs. Separate all subsections and 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 .IP under .TP. * Wrap lines at 72 columns and begin all sentences on new lines. @@ -250,3 +250,10 @@ Manual Page Style Guidelines * Add options as .TP 5 (or current default), with \- and bold options, followed by italic replaceable arguments to those options or bold literal arguments, if any. +* Refer to the user as 'the user' rather than 'you'. +* Collect all referenced programs (unless used purely as an example) in the + SEE ALSO section. (The SEE ALSO section is not *limited* to referenced + programs, however.) +* 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. diff --git a/src/usr/man/man5/sbopkg.conf.5 b/src/usr/man/man5/sbopkg.conf.5 index 1209c34..c33df60 100644 --- a/src/usr/man/man5/sbopkg.conf.5 +++ b/src/usr/man/man5/sbopkg.conf.5 @@ -22,7 +22,8 @@ The different configuration options are: This option allows the user to choose the repository to use. The default options are SBo, SB64 and local. The 'local' choice corresponds to a user-maintained repository whose -structure must be the same as the one used by SlackBuilds.org. +structure must be the same as the one used by SlackBuilds.org, in the +sense of a category/package/files hierarchy. NOTE: all of the REPO_* variables are affected by the repository files maintained in /etc/sbopkg/repos.d. Please see the README-repos.d document in the sbopkg /doc directory. @@ -34,10 +35,8 @@ REPO_NAME=${REPO_NAME:-SBo}. .TP .B REPO_BRANCH This option allows the user to set the default active repository branch. -The current options are 11.0, 12.0, 12.1, 12.2, 13.0, and 13.1 for the -SBo repository and local for the local repository. -The Slamd64Builds repository is 'master' but is not officially -supported. +The current options are listed in the default repos.d/* files and can +also be listed by issuing 'sbopkg -V ?'. .IP The default value of REPO_BRANCH is: .IP @@ -47,8 +46,7 @@ REPO_BRANCH=${REPO_BRANCH:-13.1}. .B REPO_ROOT 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 less than -50MB. +Currently, the size of a local copy of the SBo repository is about 70MB. .IP The default value of REPO_ROOT is: .IP @@ -77,8 +75,11 @@ SBOPKGTMP=${SBOPKGTMP:-/tmp/sbopkg}. This option sets the default directory where built packages should be stored. TMP must be exported as it is used by the SlackBuilds. -Also note that the default value of TMP is the same as in the SBo -SlackBuild scripts. +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 +setting is ignored. .IP The default value of TMP is: .IP @@ -118,7 +119,7 @@ The default value of KEEPLOG is: YES. .TP .B LOGDIR This option sets the location for the sbopkg permanent log if KEEPLOG is -set to YES (see previous paragraph). +set to YES. .IP The default value of LOGDIR is: .IP @@ -127,15 +128,18 @@ LOGDIR=${LOGDIR:-/var/log/sbopkg}. .TP .B CLEANUP This option should be set to YES or NO. -When set to YES, the source files and the various residuals from the -process of building a package are deleted right after the build. -A side effect of setting CLEANUP to YES is that the TMP setting got from -the environment or from the configuration files is ignored. +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 +internal value and any other TMP setting is ignored. .IP The default value of CLEANUP is: NO. .\"--------------------------------------------------------------------- .TP .B ALLOW_MULTI +This option should be set to YES or NO. When set to YES, this option allows the user to run multiple instances of sbopkg. .IP @@ -160,7 +164,7 @@ 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) +(you can do this with rsync -- i.e., SlackBuild.org -- repos) .TP \(bu simultaneously build or install the same package from different @@ -172,6 +176,8 @@ save a queue file while using it from another instance .IP There can be more unsafe situations we haven't thought about. Take care. +.IP +The default value of ALLOW_MULTI is: NO. .\"--------------------------------------------------------------------- .TP .B DEBUG @@ -270,9 +276,6 @@ would then set TMP to /home/sbo/tmp for building SBo packages. OUTPUT can also be changed to save compiled packages in a location other than the default of /tmp. .PP -Please note that if the CLEANUP variable is set to YES, the TMP setting -is ignored. -.PP You can also export variables in sbopkg.conf that are not used by sbopkg at all. .\"--------------------------------------------------------------------- @@ -315,6 +318,10 @@ information. .\" Make the release process handle a DOCDIR here? But the files from .\" the official tarball go here. .SH SEE ALSO +.BR diff (1), +.BR rsync (1), .BR sbopkg (8), +.BR uname (1), +.BR wget (1), .IR /usr/doc/sbopkg-SVN/* .\" vim:set tw=72: diff --git a/src/usr/man/man8/sbopkg.8 b/src/usr/man/man8/sbopkg.8 index f54b215..e6fb33d 100644 --- a/src/usr/man/man8/sbopkg.8 +++ b/src/usr/man/man8/sbopkg.8 @@ -19,30 +19,43 @@ and the third-party repository SlackBuilds.org, specifically. A thorough reading of http://www.slackbuilds.org/howto/ and the pages at http://www.slackwiki.org about SlackBuild scripts is strongly advised. .PP -Before sbopkg can be used, a configuration file must be created at +In order for sbopkg to be used, a configuration file must exist at /etc/sbopkg/sbopkg.conf. -A sample file is provided at /etc/sbopkg/sbopkg.conf.new. +An initial install will provide the user with an /etc/sbopkg/sbopkg.conf +while upgrades will add an /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 can be run from the command line by simply invoking "sbopkg." 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. The reason is that some SlackBuild scripts rely on certain tools that -are only available in root's PATH when root's PATH is inherited (i.e. -texmf to build man pages) and root's PATH is not inherited when only -using 'su'. -In any evnet, invoking 'sbopkg' from the command line will launch the -dialog-based interface, and the menus provided should be fairly -self-explanatory. -The main menu allows the user to rsync with the SlackBuilds.org -repository (currently, the size of a local copy of the SBo repository is -less than 50MB), view the SlackBuilds.org Changelog, check for potential -updates to SBo packages, display the contents of the local cache -directory where source tarballs are saved, display the permanent build -log, and browse or search the local copy of the SBo repository. +are only available in root's PATH when the scripts in /etc/profile.d +have been run (i.e., texmf to build man pages), which is only done for +login shells, or otherwise require a 'truer' root environment than that +given by only 'su'. +In any event, invoking +.B sbopkg +with no arguments (or with just +.BR -d , +.B -f +or +.BR -V ) +will launch the 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 +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 +contents of the local cache directory where source tarballs are saved, +display the 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 @@ -56,16 +69,16 @@ either the original SlackBuild or the locally-edited one, if present. If using the dialog interface, and if sbopkg finds a built package for a particular piece of software in the OUTPUT directory, then sbopkg will automatically add a new menu entry allowing the user to install the -package if he so chose. +package if he so chooses. Alternatively, the user can choose to automatically build or build and install individual packages or several packages in a build queue. Finally, if KEEPLOG is set to YES in the sbopkg.conf file then a -permanent log of the build process is saved in /tmp/sbopkg-build-log. +permanent log of the build process is saved to wherever LOGFILE is set +to in that same file. .PP Alternatively, sbopkg can be run from the command line without using the dialog interface. -Executing "sbopkg -h" will display a list of options available from the -command line. +See below for the available command line options. .PP Sbopkg also has the capability of loading, saving, and using user-created queuefiles. @@ -76,7 +89,7 @@ application is selected, or "ON." This can be changed by inserting a "-" in front of the application name in the queuefile. Also, queuefiles can reference other queuefiles when the first character -is a "@". +is an "@". See the readme-queuefiles document in the doc/ directory for more information. .PP @@ -100,13 +113,13 @@ Search for and build PACKAGE(s) from the local SBo repository. If more than one package is specified, they must be in quotes. For example: .IP -#sbopkg -b "foo bar" +# sbopkg -b "foo bar" .IP will build foo and then 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 name (i.e., the user named a queuefile with the name of a package), sbopkg will ask the user which one should be used. 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 @@ -129,28 +142,27 @@ Specify what sbopkg should do when it encounters an error while building a package. Valid options are: .IP -.B ask -: This is the default behavior, asking the user what to do; +.BR ask : +This is the default behavior, asking the user what to do. .IP -.B continue -: Ignore the error and continue processing (act as if the user answered -"Yes" to all questions); +.BR continue : +Ignore the error and continue processing (act as if the user answered +"Yes" to all questions). .IP -.B stop -: Stop the processing (act as if the user answered "No" to all -questions). +.BR stop : +Stop the processing (act as if the user answered "No" to all questions). .\"--------------------------------------------------------------------- .TP .BI \-f " FILE" -Override the default configuration file, which is located by default at -/etc/sbopkg/sbopkg.conf, with another configuration file. +Override the default configuration file, /etc/sbopkg/sbopkg.conf, with +another configuration file. .\"--------------------------------------------------------------------- .TP .BI \-g " PACKAGE(s)" General search for PACKAGE(s) by glob. For example: .IP -#sbopkg -g nv +# sbopkg -g nv .IP will return a list of matches, such as the nvidia packages, konversation, and other packages with 'nv' in their name. @@ -161,14 +173,13 @@ If more than one glob is specified, they must be in quotes. Display the help. .\"--------------------------------------------------------------------- .TP -.BI \-i " PACKAGE(s)" -Search for and build and then install PACKAGE(s) from the local SBo -repository. +.BI \-i " PACKAGE(s)/QUEUE(s)" +Build and install PACKAGE(s) from the local SBo repository. If more than one package is specified, they must be in quotes, and the packages will be built and then installed in the listed order. For example: .IP -#sbopkg -i "foo bar" +# sbopkg -i "foo bar" .IP will build and install foo and then build and install bar. By carefully considering the order of the packages listed, the user may @@ -184,8 +195,8 @@ 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 (i.e. -don't build) any package it finds to be already installed. +When used together with -b or -i, this option tells 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 @@ -193,20 +204,20 @@ versions of installed packages. .\"--------------------------------------------------------------------- .TP .B \-l -Display the SBo ChangeLog.txt and quit. +Display the SBo ChangeLog and quit. .\"--------------------------------------------------------------------- .TP .B \-o -List the currently installed cached source files which are deemed as +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. .IP Please note that only the currently active repository is used to -identify the obsoleted sources, so if you build packages with different -repositories (e.g. for different Slackware versions) the source files -only used in the "other" repository will be listed. +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. .\"--------------------------------------------------------------------- .TP .B \-P @@ -231,7 +242,7 @@ Rsync the local repository with SlackBuilds.org and quit. .B \-R Show all the README files of the queued packages before starting the build. -This is useful when you want to make a final check. +This is useful when the user wants to make a final check. .\"--------------------------------------------------------------------- .TP .BI \-s " PACKAGE(s)" @@ -241,7 +252,7 @@ $PAGER, which defaults to 'more' as described above. If more than one package is specified, they must be in quotes. For example: .IP -#sbopkg -s "foo bar" +# sbopkg -s "foo bar" .IP will search for foo and then bar. .\"--------------------------------------------------------------------- @@ -250,7 +261,7 @@ will search for foo and then bar. Check for an update to sbopkg itself and then quit. .\"--------------------------------------------------------------------- .TP -.BI \-V " REPO/BRANCH" +.BI \-V " VERSION" Set the repository and branch to use. .IP For a list of valid versions, invoke sbopkg as @@ -259,7 +270,7 @@ See the .BR sbopkg.conf (5) man page for more information about the 'local' repository. .IP -The VERSION format is repository/branch (e.g. SBo/13.1). +The VERSION format is repository/branch (e.g., SBo/13.1). If the repository is omitted, sbopkg will first look for the specified branch in the default repository. If that attempt fails, sbopkg will look for the first matching branch in @@ -272,10 +283,10 @@ Prints the current version of sbopkg on stdout. .SH FILES .TP 5 .I /etc/sbopkg/sbopkg.conf -File to specify configuration options. +Default system-wide 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 repositories that has been renamed. See the README-renames.d document in the sbopkg doc/ directory for more information. @@ -288,7 +299,11 @@ information. .\" 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 rsync (1), .BR sbopkg.conf (5), +.BR vi (1), .IR /usr/doc/sbopkg-SVN/* .\"===================================================================== .SH AUTHOR