.\" -*-nroff-*-
.\"
-.\" $Id: sw.1,v 1.6 1999/07/30 08:18:23 mdw Exp $
+.\" $Id$
.\"
.\" Manual page for `sw'
.\"
.\" along with sw-tools; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
-.\"----- Revision history ---------------------------------------------------
-.\"
-.\" $Log: sw.1,v $
-.\" Revision 1.6 1999/07/30 08:18:23 mdw
-.\" Sweep with ispell and fix some typos.
-.\"
-.\" Revision 1.5 1999/07/16 12:45:37 mdw
-.\" Internal formatting improvements.
-.\"
-.\" Revision 1.4 1999/06/24 15:52:12 mdw
-.\" Add documentation for the `sw-precommit' script.
-.\"
-.\" Revision 1.3 1999/06/18 18:58:25 mdw
-.\" Various tidyings.
-.\"
-.\" Revision 1.2 1999/06/04 13:56:09 mdw
-.\" Changes, extensions, polishings, spelling fixes...
-.\"
-.\" Revision 1.1.1.1 1999/06/02 16:53:33 mdw
-.\" Initial import.
-.\"
-.
.\"----- Style hacking ------------------------------------------------------
.
.de VS \" Start a sort-of verbatim block
.
.\"----- Main manual text ---------------------------------------------------
.
-.TH sw 1 "25 May 1999" "EBI tools"
+.TH sw 1 "25 May 1999" sw-tools
.PD 1
.
.\"--------------------------------------------------------------------------
.
-.SH NAME
+.SH "NAME"
.
sw \- tool for convenient software installation
.
.\"--------------------------------------------------------------------------
.
-.SH SYNOPSIS
+.SH "SYNOPSIS"
.
.nf
\fBsw \-\-help
\fBsw all\-arch
\fBsw arch
\fBsw commit
-\fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBconfigure \fR[\fIconfigure-arg\fR...]
+\fBsw \fR[\fB\-fbip\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBconfigure \fR[\fIconfigure-arg\fR...]
\fBsw host \fIarch
\fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBlinktree
\fBsw listarch
-\fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBmake \fR[\fImake-arg\fR...]
+\fBsw \fR[\fB\-fbip\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBmake \fR[\fImake-arg\fR...]
\fBsw only\-arch \fIarch \fR[\fIarch\fR...]
\fBsw reset
\fBsw rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
-\fBsw \fR[\fB\-fbi\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBrun \fIcommand \fR[\fIargument\fR...]
+\fBsw \fR[\fB\-fbip\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] [\fB\-o \fIstyle\fR] \fBrun \fIcommand \fR[\fIargument\fR...]
\fBsw setup \fIpackage version \fR[\fImaintainer\fR]
\fBsw \fR[\fB\-f\fR] [\fB\-a \fIarch\fB,\fIarch\fR...] \fBsnaplink \fIfile \fR[\fIfile\fR...]
\fBsw status
.B "\-b, \-\-beep"
For build commands: make a beep noise when the build finishes. This
provides a handy reminder if you're getting on with something else while
-waiting for a long build.
+waiting for a long build. Use
+.RB ` +b '
+or
+.RB ` \-\-no\-beep '
+to turn this option off. This option is disabled by default, although
+may be enabled in the
+.B SW
+environment variable.
+.TP
+.B "\-p, \-\-percent"
+For build commands: enable translation of
+.RB ` % '-escape
+sequences in command strings. These are described in more detail
+in the section
+.B "`%'-escape sequences"
+below. Use
+.RB ` +p '
+or
+.RB ` --no-percent '
+to turn the option off. This option is enabled by default, although may
+be disabled in the
+.B SW
+environment variable.
.PP
The remaining options aren't really intended for users. They're helpful
for \*(sw's own purposes, though, and described here for completeness' sake. They
.
.\"--------------------------------------------------------------------------
.
-.SH TERMINOLOGY
+.SH "TERMINOLOGY"
.
The descriptions below make use of some technical terms:
.TP
passing it the given
.IR argument s.
.PP
+The command name and arguments may be subject to
+.RB ` % '-escape
+substitution, depending on whether the
+.B \-p
+option is enabled.
+.RB ` % '-escape
+sequences are described in the section
+.B "`%'-escape sequences"
+below.
+.PP
Output from the command is both appended to the file
.IB arch/.build-log
and output in some
.
.\"--------------------------------------------------------------------------
.
+.SH "`%'-ESCAPE SUBSTITUTION"
+.
+If the
+.B \-p
+option is enabled, build commands and arguments are subject to
+.RB ` % '-escape
+substitution before being executed. Certain two-character sequences,
+with the first character
+.RB ` % '
+are replaced with strings, as follows:
+.TP
+.B %a
+The architecture name of the host executing the command.
+.TP
+.B %h
+The hostname of the host executing the command.
+.TP
+.B %P
+The directory prefix with which \*(sw was installed.
+.TP
+.B %p
+The name of the package being built.
+.TP
+.B %v
+The version number of the package being built.
+.TP
+.B %u
+The name of the maintainer of the package being built.
+.TP
+.B %%
+A literal
+.RB ` % '
+character.
+.PP
+Any
+.RB ` % '
+sequences which aren't understood are left as they are.
+.
+.\"--------------------------------------------------------------------------
+.
.SH "OUTPUT STYLES"
.
Output from a build command is presented in one of a number of named
.
.\"--------------------------------------------------------------------------
.
-.SH LOCAL QUIRKS
+.SH "LOCAL QUIRKS"
.
This section describes how non-vendor software works at EBI. Chances
are that other sites will work differently. This description is here as
.
.\"--------------------------------------------------------------------------
.
-.SH ENVIRONMENT
+.SH "ENVIRONMENT"
.
-The following environment variables are of interest to
-.BR sw :
+The following environment variables are of interest to \*(sw:
.TP
.B SW
Contains a space-separated list of default command-line options. These
.
.\"--------------------------------------------------------------------------
.
-.SH FILES
+.SH "FILES"
.
-The following files are of interest to
-.BR sw :
+The following files are of interest to \*(sw:
.TP
.IB prefix /sw\-index
The main index file, containing the list of which packages have been
.
.\"--------------------------------------------------------------------------
.
-.SH BUGS
+.SH "BUGS"
.
There are no bugs in
.BR sw ,
merely unexpected behaviour modes. Silly you for thinking otherwise.
.
-.SH AUTHOR
+.SH "SEE ALSO"
+.BR sw-cgi (1),
+.BR sw-share (1),
+.BR sw-tidy (1),
+.BR archtab (5),
+.BR sw-env (5),
+.BR sw-info (5)
+.
+.SH "AUTHOR"
.
The \*(sw program, and this manual, are \*(mw productions, in association
with the European Bioinformatics Institute. They were written by Mark