Misc textual fixes/changes to the man pages

Fixed the NAME sections and man page cross references; tried to make
VARIABLES reflect whether they were used in an expanded sense or not;
changed an .IP list with non-standard bullets to a .TP with standard;
added standard NOTES section to sbopkg.conf and changed the .SH under it
to .SS and also changed the INSTRUCTIONS .SH in sbopkg(8) to an .SS of
DESCRIPTION; changed the FILES section from dashed .PP to undashed .TPs,
and changed the font to .I; changed the SEE ALSO section by removing
quotes, adding commas, reducing individual file references to the
general doc dir which was given a full path and changing its font to
.IR; and redid the tags in the OPTIONS section of sbopkg(8), making
replaceable args italic, changing the dashes, adding the missing
argument to the -f option.
This commit is contained in:
slakmagik 2010-06-02 23:04:40 +00:00
parent bb498e4f15
commit 3a57bf9bd4
3 changed files with 93 additions and 82 deletions

View File

@ -242,3 +242,11 @@ Manual Page Style Guidelines
* 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.
* If variables are being used in the sense of their value, use $VAL 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
under subsections of the relevant section header.
* 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.

View File

@ -2,17 +2,16 @@
.TH SBOPKG.CONF 5 "May 2010" sbopkg-SVN ""
.\"=====================================================================
.SH NAME
.B sbopkg.conf
\- Configuration file for sbopkg
sbopkg.conf \- configuration file for sbopkg
.\"=====================================================================
.SH DESCRIPTION
The sbopkg.conf file contains configuration settings for
.B sbopkg
(8), a tool for interacting with the SlackBuilds.org ("SBo") repository,
a collection of third-party SlackBuild scripts to build Slackware
.BR sbopkg (8),
a tool for interacting with the SlackBuilds.org ("SBo") repository, a
collection of third-party SlackBuild scripts to build Slackware
packages.
A sample file is provided at /etc/sbopkg/sbopkg.conf.new.
Also, please see a note below about $ARCH.
Also, please see a note below about ARCH.
.PP
Boolean options are case-insensitive.
.PP
@ -150,19 +149,24 @@ by yourself doing improper things.
.IP
For reference, these are some of the things you shouldn't do with this
option enabled:
.RS 6
.IP \[bu] 2
.RS 5
.TP 3
\(bu
run an ALLOW_MULTI=NO instance together with one or more having
ALLOW_MULTI=YES
.IP \[bu]
.TP
\(bu
sync a repository when another instance is using it
.IP \[bu]
.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)
.IP \[bu]
.TP
\(bu
simultaneously build or install the same package from different
instances
.IP \[bu]
.TP
\(bu
save a queue file while using it from another instance
.RE
.IP
@ -244,7 +248,9 @@ The default value of DIFFOPTS is:
.IP
DIFFOPTS=${DIFFOPTS:--u}
.\"=====================================================================
.SH OVERRIDING ENVIRONMENTAL VARIABLES
.SH NOTES
.\"---------------------------------------------------------------------
.SS Overriding Environmental Variables
It is possible to set or override environmental variables and pass them
to the SlackBuild scripts when they are built from within sbopkg.
This is already demonstrated in the following line in the sbopkg.conf
@ -252,15 +258,15 @@ file:
.PP
export TMP=${TMP:-/tmp/SBo}
.PP
This sets $TMP to /tmp/SBo for building SBo packages within sbopkg
(which is currently the default for SBo SlackBuilds already).
This sets TMP to /tmp/SBo for building SBo packages within sbopkg (which
is currently the default for SBo SlackBuilds already).
Since this variable is exported, it could be changed for both sbopkg and
for building SBo packages within sbopkg.
For example, changing this line so it reads:
.PP
export TMP=${TMP:-/home/sbo/tmp}
.PP
would then set $TMP to /home/sbo/tmp for building SBo packages.
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
@ -269,8 +275,8 @@ is ignored.
.PP
You can also export variables in sbopkg.conf that are not used by sbopkg
at all.
.\"=====================================================================
.SH ABOUT THE ARCH VARIABLE
.\"---------------------------------------------------------------------
.SS About the ARCH Variable
You may be wondering why ARCH is not a configuration setting in the
default sbopkg.conf file.
The reason is that it does not have to be.
@ -291,25 +297,24 @@ Note that the SlackBuild may, in certain instances, discard or override
previous ARCH settings if this is required for the build.
.\"=====================================================================
.SH FILES
.B /etc/sbopkg/sbopkg.conf
\ - File to specify configuration options.
.PP
.B /etc/sbopkg/renames.d/50-default
\ - Default file that lists software in SBo repository that has been
.TP 3
.I /etc/sbopkg/sbopkg.conf
File to specify configuration options.
.TP
.I /etc/sbopkg/renames.d/50-default
Default file that lists software in SBo repository that has been
renamed.
See the README-renames.d document in the sbopkg doc/ directory for more
information.
.PP
.B /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
\ - Three default files for various types of sbopkg repositories.
.TP
.I /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
Three default files for various types of sbopkg repositories.
See the README-repos.d document in the sbopkg doc/ directory for more
information.
.\"=====================================================================
.SH "SEE ALSO"
.BR sbopkg (8)
.BR doc/README
.BR doc/README-queuefiles
.BR doc/README-renames.d
.BR doc/README-repos.d
.BR doc/queuefiles/*
.\" Make the release process handle a DOCDIR here? But the files from
.\" the official tarball go here.
.SH SEE ALSO
.BR sbopkg (8),
.IR /usr/doc/sbopkg-SVN/*
.\" vim:set tw=72:

View File

@ -2,19 +2,18 @@
.TH SBOPKG 8 "May 2010" sbopkg-SVN ""
.\"=====================================================================
.SH NAME
.B sbopkg
\ - The SlackBuilds.org Package Browser
sbopkg \- the SlackBuilds.org package browser
.\"=====================================================================
.SH SYNOPSIS
.B sbopkg
.B [options]
.RI [ options ]
.\"=====================================================================
.SH DESCRIPTION
Sbopkg is a command-line and dialog-based tool to interact with the
SlackBuilds.org ("SBo") repository, a collection of third-party
SlackBuild scripts to build Slackware packages.
.\"=====================================================================
.SH INSTRUCTIONS
.SS Instructions
Sbopkg usage assumes an understanding of SlackBuild scripts, generally,
and the third-party repository SlackBuilds.org, specifically.
A thorough reading of http://www.slackbuilds.org/howto/ and the pages at
@ -24,16 +23,16 @@ Before sbopkg can be used, a configuration file must be created at
/etc/sbopkg/sbopkg.conf.
A sample file is provided at /etc/sbopkg/sbopkg.conf.new.
See
.B sbopkg.conf
(5) for more information about the configuration file.
.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
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
@ -84,19 +83,19 @@ information.
Certain features of sbopkg rely on outside binaries, such as a pager to
view the text files when sbopkg is run from the comamnd line, and an
editor to edit the .info or SlackBuild files.
The pager function will look to the environmental variable $PAGER and if
The pager function will look to the environmental variable PAGER and if
that variable is not defined then it will default to 'more.'
Similarly, the edit function found when sbopkg is used with the dialog
interface will look to $EDITOR and will default to 'vi' if no $EDITOR
has been defined.
If the user wants sbopkg to use another $EDITOR, such as nano, then
interface will look to the EDITOR variable and will default to 'vi' if
EDITOR is undefined.
If the user wants sbopkg to use another editor, such as nano, then
adding the requisite information in ~/.bashrc, /etc/profile, or other
similar configuration file to export $EDITOR will suffice.
similar configuration file to export EDITOR will suffice.
.\"=====================================================================
.SH OPTIONS
.\"---------------------------------------------------------------------
.TP 5
.B -b PACKAGE(s)/QUEUE(s)
.BI \-b " PACKAGE(s)/QUEUE(s)"
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:
@ -116,16 +115,16 @@ If a package is specified more than once, it gets queued only the first
time it is encountered.
.\"---------------------------------------------------------------------
.TP
.B -c
.B \-c
Display list of installed SBo packages and potential updates.
.\"---------------------------------------------------------------------
.TP
.B -d DIRECTORY
.BI \-d " DIRECTORY"
Manually specify the full path to the DIRECTORY containing the local SBo
repository.
.\"---------------------------------------------------------------------
.TP
.B -e ask|continue|stop
.B \-e \fBask\fR|\fBcontinue\fR|\fBstop
Specify what sbopkg should do when it encounters an error while building
a package.
Valid options are:
@ -142,12 +141,12 @@ Valid options are:
questions).
.\"---------------------------------------------------------------------
.TP
.B -f
.BI \-f " FILE"
Override the default configuration file, which is located by default at
/etc/sbopkg/sbopkg.conf, with another configuration file.
.\"---------------------------------------------------------------------
.TP
.B -g PACKAGE(s)
.BI \-g " PACKAGE(s)"
General search for PACKAGE(s) by glob.
For example:
.IP
@ -158,11 +157,11 @@ konversation, and other packages with 'nv' in their name.
If more than one glob is specified, they must be in quotes.
.\"---------------------------------------------------------------------
.TP
.B -h
.B \-h
Display the help.
.\"---------------------------------------------------------------------
.TP
.B -i PACKAGE(s)
.BI \-i " PACKAGE(s)"
Search for and build and then install PACKAGE(s) from the local SBo
repository.
If more than one package is specified, they must be in quotes, and the
@ -184,7 +183,7 @@ Queuefile names are supported, too.
See the explanation for the '-b' command for details.
.\"---------------------------------------------------------------------
.TP
.B -k
.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.
.IP
@ -193,11 +192,11 @@ option is specified sbopkg will also omit the build of different
versions of installed packages.
.\"---------------------------------------------------------------------
.TP
.B -l
.B \-l
Display the SBo ChangeLog.txt and quit.
.\"---------------------------------------------------------------------
.TP
.B -o
.B \-o
List the currently installed cached source files which are deemed as
obsolete, and optionally delete them.
.IP
@ -210,32 +209,32 @@ repositories (e.g. for different Slackware versions) the source files
only used in the "other" repository will be listed.
.\"---------------------------------------------------------------------
.TP
.B -P
.B \-P
List the cached package files which are not currently installed on the
system and optionally delete them.
.\"---------------------------------------------------------------------
.TP
.B -p
.B \-p
List installed SlackBuilds.org packages.
.\"---------------------------------------------------------------------
.TP
.B -q
.B \-q
Enable the "quiet mode."
When this flag is specified, the output of some of the command-line
options is minimized.
.\"---------------------------------------------------------------------
.TP
.B -r
.B \-r
Rsync the local repository with SlackBuilds.org and quit.
.\"---------------------------------------------------------------------
.TP
.B -R
.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.
.\"---------------------------------------------------------------------
.TP
.B -s PACKAGE(s)
.BI \-s " PACKAGE(s)"
Specific search for PACKAGE(s) by PACKAGE name and, if found, display
the README, SlackBuild, .info, and slack-desc files in that order using
$PAGER, which defaults to 'more' as described above.
@ -247,17 +246,17 @@ For example:
will search for foo and then bar.
.\"---------------------------------------------------------------------
.TP
.B -u
.B \-u
Check for an update to sbopkg itself and then quit.
.\"---------------------------------------------------------------------
.TP
.B -V REPO/BRANCH
.BI \-V " REPO/BRANCH"
Set the repository and branch to use.
.IP
For a list of valid versions, invoke sbopkg as
.BR "sbopkg -V ?" .
See the
.B sbopkg.conf (5)
.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).
@ -267,31 +266,30 @@ If that attempt fails, sbopkg will look for the first matching branch in
any repository.
.\"---------------------------------------------------------------------
.TP
.B -v
.B \-v
Prints the current version of sbopkg on stdout.
.\"=====================================================================
.SH FILES
.B /etc/sbopkg/sbopkg.conf
\ - File to specify configuration options.
.PP
.B /etc/sbopkg/renames.d/50-default
\ - Default file that lists software in SBo repository that has been
.TP 5
.I /etc/sbopkg/sbopkg.conf
File to specify configuration options.
.TP
.I /etc/sbopkg/renames.d/50-default
Default file that lists software in SBo repository that has been
renamed.
See the README-renames.d document in the sbopkg doc/ directory for more
information.
.PP
.B /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
\ - Three default files for various types of sbopkg repositories.
.TP
.I /etc/sbopkg/repos.d/{40-sbo.repo,50-sb64.repo,60-local.repo}
Three default files for various types of sbopkg repositories.
See the README-repos.d document in the sbopkg doc/ directory for more
information.
.\"=====================================================================
.SH "SEE ALSO"
.BR sbopkg.conf (5)
.BR doc/README
.BR doc/README-queuefiles
.BR doc/README-renames.d
.BR doc/README-repos.d
.BR doc/queuefiles/*
.\" Make the release process handle a DOCDIR here? But the files from
.\" the official tarball go here.
.SH SEE ALSO
.BR sbopkg.conf (5),
.IR /usr/doc/sbopkg-SVN/*
.\"=====================================================================
.SH AUTHOR
Chess Griffin