Internal formatting improvements.

diff --git a/archtab.5 b/archtab.5
index d2e25c4..d8bc576 100644 (file)
--- a/archtab.5
+++ b/archtab.5
@@ -1,11 +1,12 @@
 .\" -*-nroff-*-
 .\"
-.\" $Id: archtab.5,v 1.1 1999/06/04 13:56:18 mdw Exp $
+.\" $Id: archtab.5,v 1.2 1999/07/16 12:45:36 mdw Exp $
 .\"
 .\" Manual page for `archtab' files.
 .\"
 .\" (c) 1999 EBI
 .\"
+.
 .\"----- Licensing notice ---------------------------------------------------
 .\"
 .\" This file is part of sw-tools.
@@ -23,16 +24,19 @@
 .\" You should have received a copy of the GNU General Public License
 .\" 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: archtab.5,v $
+.\" Revision 1.2  1999/07/16 12:45:36  mdw
+.\" Internal formatting improvements.
+.\"
 .\" Revision 1.1  1999/06/04 13:56:18  mdw
 .\" New manual page.
 .\"
-.\"
-.\" --- Useful macro definitions ---
-.\"
+.
+.\"----- Style hacking ------------------------------------------------------
+.
 .de VS \" Start a sort-of verbatim block
 .sp 1
 .in +5n
@@ -45,13 +49,11 @@
 .in -5n
 .sp 1
 ..
-.de HP \" Start an indented paragraph with a bold right-aligned label
+.de hP \" Start an indented paragraph with a bold right-aligned label
 .IP
 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
 ..
-.\"
-.\" --- Style hacking ---
-.\"
+.
 .ie \n(.g \{\
 .      fam P
 .      ds mw \fR[\f(BImdw\fR]
@@ -61,16 +63,22 @@
 .el     .ds o o
 .ds sw \fBsw\fP
 .ds se \fBsw\-env\fP
-.\"
-.\" --- Main manual text ---
-.\"
+.
+.\"----- Main manual text ---------------------------------------------------
+.
 .TH sw 1 "25 May 1999" "EBI tools"
 .PD 1
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH NAME
+.
 archtab \- mapping from architecture names to hosts
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH DESCRIPTION
+.
 The
 .B archtab
 file is a sequence of lines.  A line may be blank, a comment, or a table
@@ -80,7 +88,13 @@ as their first non-whitespace character: both are ignored.  Table
 entries consist an architecture name and a hostname, separated by
 whitespace.  Each architecture should only appear once.  The hostname
 should be the preferred host for building software on that architecture.
+.
+.\"--------------------------------------------------------------------------
+.
 .SH AUTHOR
+.
 The \*(sw program, and this manual, are \*(mw productions, in association
 with the European Bioinformatics Institute.  They were written by Mark
 Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
+.
+.\"----- That's all, folks --------------------------------------------------

diff --git a/sw-env.5 b/sw-env.5
index 6432fc5..c5b2716 100644 (file)
--- a/sw-env.5
+++ b/sw-env.5
@@ -1,11 +1,12 @@
 .\" -*-nroff-*-
 .\"
-.\" $Id: sw-env.5,v 1.1 1999/06/04 13:56:18 mdw Exp $
+.\" $Id: sw-env.5,v 1.2 1999/07/16 12:45:37 mdw Exp $
 .\"
 .\" Manual page for `sw-env' files
 .\"
 .\" (c) 1999 EBI
 .\"
+.
 .\"----- Licensing notice ---------------------------------------------------
 .\"
 .\" This file is part of sw-tools.
@@ -23,16 +24,19 @@
 .\" You should have received a copy of the GNU General Public License
 .\" 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-env.5,v $
+.\" Revision 1.2  1999/07/16 12:45:37  mdw
+.\" Internal formatting improvements.
+.\"
 .\" Revision 1.1  1999/06/04 13:56:18  mdw
 .\" New manual page.
 .\"
-.\"
+.
 .\" --- Useful macro definitions ---
-.\"
+.
 .de VS \" Start a sort-of verbatim block
 .sp 1
 .in +5n
@@ -45,7 +49,7 @@
 .in -5n
 .sp 1
 ..
-.de HP \" Start an indented paragraph with a bold right-aligned label
+.de hP \" Start an indented paragraph with a bold right-aligned label
 .IP
 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
 ..
@@ -53,24 +57,30 @@
 .\" --- Style hacking ---
 .\"
 .ie \n(.g \{\
-.      fam P
-.      ds mw \fR[\f(BImdw\fR]
+.  fam P
+.  ds mw \fR[\f(BImdw\fR]
 .\}
-.el    .ds mw \fR[\fBmdw\fR]
-.ie t   .ds o \(bu
-.el     .ds o o
+.el .ds mw \fR[\fBmdw\fR]
+.ie t .ds o \(bu
+.el .ds o o
 .ds sw \fBsw\fP
 .ds se \fBsw\-env\fP
-.\"
-.\" --- Main manual text ---
-.\"
+.
+.\"----- Main manual text ---------------------------------------------------
+.
 .TH sw 1 "25 May 1999" "EBI tools"
 .PD 1
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH NAME
+.
 sw\-env \- environment variable assignment files for \*(sw.
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH DESCRIPTION
+.
 A \*(se file is a sequence of statements.  The following statements are
 supported:
 .sp 1
@@ -125,7 +135,9 @@ is loosely based on the Bourne
 shell, although there are differences and irregularities due to the
 quick and dirty nature of the parser.  The various quoting and
 substitution operations are described below.
+.
 .SS "Statements"
+.
 The statements behave as follows:
 .TP
 .B :
@@ -175,7 +187,9 @@ A
 .I name
 is read.  Any value assigned to the variable named is discarded, and the
 variable is forgotten.
+.
 .SS "Value syntax"
+.
 The parser usually reads a
 .I value
 a character by character, until it finds a delimiter.  Delimiter
@@ -278,7 +292,13 @@ words and executed as a command.  It is not passed through the shell:
 the author suspects that this would be too confusing.  The standard
 output of the command, with trailing newlines (but not internal or
 leading newlines) removed, is the result of the substitution.
+.
+.\"--------------------------------------------------------------------------
+.
 .SH AUTHOR
+.
 The \*(sw program, and this manual, are \*(mw productions, in association
 with the European Bioinformatics Institute.  They were written by Mark
 Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
+.
+.\"----- That's all, folks --------------------------------------------------

diff --git a/sw-info.5 b/sw-info.5
index 4427b6a..b0d3a55 100644 (file)
--- a/sw-info.5
+++ b/sw-info.5
@@ -1,11 +1,12 @@
 .\" -*-nroff-*-
 .\"
-.\" $Id: sw-info.5,v 1.1 1999/06/04 13:56:18 mdw Exp $
+.\" $Id: sw-info.5,v 1.2 1999/07/16 12:45:37 mdw Exp $
 .\"
 .\" Manual page for `sw-info' files.
 .\"
 .\" (c) 1999 EBI
 .\"
+.
 .\"----- Licensing notice ---------------------------------------------------
 .\"
 .\" This file is part of sw-tools.
@@ -23,16 +24,19 @@
 .\" You should have received a copy of the GNU General Public License
 .\" 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-info.5,v $
+.\" Revision 1.2  1999/07/16 12:45:37  mdw
+.\" Internal formatting improvements.
+.\"
 .\" Revision 1.1  1999/06/04 13:56:18  mdw
 .\" New manual page.
 .\"
-.\"
-.\" --- Useful macro definitions ---
-.\"
+.
+.\"----- Style hacking ------------------------------------------------------
+.
 .de VS \" Start a sort-of verbatim block
 .sp 1
 .in +5n
@@ -45,13 +49,11 @@
 .in -5n
 .sp 1
 ..
-.de HP \" Start an indented paragraph with a bold right-aligned label
+.de hP \" Start an indented paragraph with a bold right-aligned label
 .IP
 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
 ..
-.\"
-.\" --- Style hacking ---
-.\"
+.
 .ie \n(.g \{\
 .      fam P
 .      ds mw \fR[\f(BImdw\fR]
@@ -61,16 +63,22 @@
 .el     .ds o o
 .ds sw \fBsw\fP
 .ds se \fBsw\-env\fP
-.\"
-.\" --- Main manual text ---
-.\"
+.
+.\"----- Main manual text ---------------------------------------------------
+.
 .TH sw 1 "25 May 1999" "EBI tools"
 .PD 1
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH NAME
+.
 sw-info \- description of sw data files
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH DESCRIPTION
+.
 The
 .B .sw\-info
 file contains blank lines, comment lines, and assignments.  A blank line
@@ -122,7 +130,12 @@ The
 file consists of a number of entries, one per line.  Comments and blank
 lines are not allowed.  Each line contains assignments for a particular
 package, separated by semicolons rather than newlines.
+.
+.\"--------------------------------------------------------------------------
+.
 .SH AUTHOR
 The \*(sw program, and this manual, are \*(mw productions, in association
 with the European Bioinformatics Institute.  They were written by Mark
 Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
+.
+.\"----- That's all, folks --------------------------------------------------

diff --git a/sw.1 b/sw.1
index e15f990..78cc17d 100644 (file)
--- a/sw.1
+++ b/sw.1
@@ -1,11 +1,12 @@
 .\" -*-nroff-*-
 .\"
-.\" $Id: sw.1,v 1.4 1999/06/24 15:52:12 mdw Exp $
+.\" $Id: sw.1,v 1.5 1999/07/16 12:45:37 mdw Exp $
 .\"
 .\" Manual page for `sw'
 .\"
 .\" (c) 1999 EBI
 .\"
+.
 .\"----- Licensing notice ---------------------------------------------------
 .\"
 .\" This file is part of sw-tools.
@@ -23,10 +24,13 @@
 .\" You should have received a copy of the GNU General Public License
 .\" 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.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.
 .\"
@@ -39,9 +43,9 @@
 .\" Revision 1.1.1.1  1999/06/02 16:53:33  mdw
 .\" Initial import.
 .\"
-.\"
-.\" --- Useful macro definitions ---
-.\"
+.
+.\"----- Style hacking ------------------------------------------------------
+.
 .de VS \" Start a sort-of verbatim block
 .sp 1
 .in +5n
@@ -54,31 +58,35 @@
 .in -5n
 .sp 1
 ..
-.de HP \" Start an indented paragraph with a bold right-aligned label
+.de hP \" Start an indented paragraph with a bold right-aligned label
 .IP
 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
 ..
-.\"
-.\" --- Style hacking ---
-.\"
+.
 .ie \n(.g \{\
-.       fam P
-.       ds mw \fR[\f(BImdw\fR]
+. fam P
+. ds mw \fR[\f(BImdw\fR]
 .\}
-.el     .ds mw \fR[\fBmdw\fR]
-.ie t   .ds o \(bu
-.el     .ds o o
+.el .ds mw \fR[\fBmdw\fR]
+.ie t .ds o \(bu
+.el .ds o o
 .ds sw \fBsw\fP
-.\"
-.\" --- Main manual text ---
-.\"
+.
+.\"----- Main manual text ---------------------------------------------------
+.
 .TH sw 1 "25 May 1999" "EBI tools"
 .PD 1
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH NAME
+.
 sw \- tool for convenient software installation
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH SYNOPSIS
+.
 .nf
 \fBsw \-\-help
 \fBsw \-\-help-full
@@ -103,9 +111,11 @@ sw \- tool for convenient software installation
 \fBsw status
 .ft R
 .fi
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "INTRODUCTION"
+.
 The \*(sw tool attempts to take a lot of the work out of building and
 installing source packages across multiple architectures.  This section
 will describe how to use \*(sw's features to best advantage in a number
@@ -120,9 +130,11 @@ section below.
 By the way, this is quite a large manual.  I recommend that you print a
 copy onto paper and peruse it in a leisurely fashion, rather than
 squinting at a monitor.
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "SUMMARY OF BUILDING PACKAGES"
+.
 First, the
 .B Autoconf
 case:
@@ -152,9 +164,11 @@ sw make
 sw \-i make install
 sw commit
 .VE
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "8 STEPS TO INSTALLING A PACKAGE"
+.
 The following steps will guide you through your first (and maybe second)
 package installations.  In the description, I'll use
 .RI ` package '
@@ -342,9 +356,11 @@ sw commit
 .VE
 This makes \*(sw update its main index of installed packages, telling it
 which architectures packages are installed on, and who did it.
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "REFERENCE INTRODUCTION"
+.
 That was a gentle introduction.  This section contains the complete
 reference to
 .BR sw :
@@ -380,9 +396,11 @@ or
 .RB ` make '
 so that it knows what to do.  There are some strange command line
 options which cause \*(sw to do more exotic things, though.
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "IMPLEMENTATION ODDITIES"
+.
 The \*(sw program that users use is really a small architecture-neutral
 shell script, which works out the current architecture and executes the
 appropriate architecture-specific main program.  It's done this way so
@@ -392,9 +410,11 @@ quite a lot.  The only feature provided by the front-end shell script is
 the
 .B \-\-archname
 command line option, which shouldn't be used by anyone except \*(sw's build procedure anyway.
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "COMMAND LINE OPTION REFERENCE"
+.
 Any \*(sw command line options can be put in the
 .B SW
 environment variable.  The \*(sw program will read space-separated
@@ -510,9 +530,11 @@ this option, but it shouldn't do any harm.
 Used by \*(sw when running commands on remote hosts.  Don't use this yourself: it puts \*(sw into a very unfriendly mode and requires that you communicate with it
 using a bizarre binary packet protocol.  If you really must know more
 about this, see the source code: it's quite well documented, really.
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH TERMINOLOGY
+.
 The descriptions below make use of some technical terms:
 .TP
 .B "architecture restriction"
@@ -575,9 +597,13 @@ command.  The
 option causes \*(sw to ignore whether architectures have been successfully built when
 determining the
 .IR "default build architectures" .
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "COMMAND REFERENCE"
+.
 This section describes all of the available \*(sw commands, in alphabetical order.
-.\"
+.
 .SS all\-arch
 Clears an architecture restriction set by
 .RB ` only\-arch '.
@@ -587,7 +613,7 @@ yet successfully built, unless overridden by the
 command-line option, or a later
 .RB ` only\-arch '
 command.
-.\"
+.
 .SS arch
 Writes the name of the local host's architecture to standard output.
 The architecture name is built into \*(sw at compile time.
@@ -631,7 +657,7 @@ The installation prefix with which \*(sw was configured.
 .PP
 The script should report any errors it finds to its standard error
 stream.
-.\"
+.
 .SS configure \fR[\fIconfigure-arg\fR...]
 Equivalent to the command
 .VS
@@ -648,14 +674,14 @@ It is expected that administrators will set up a file
 .IB prefix /share/config.site
 which sets up other Autoconf parameters once the prefix has been
 chosen.  See the Autoconf manual for more information.
-.\"
+.
 .SS host \fIarch\fR
 Writes to standard output the name of a host with requested architecture
 .IR arch .
 The hostname is read from the
 .B archtab
 file.
-.\"
+.
 .SS linktree
 Builds symbolic link trees.  For each of the build architectures, a
 directory with the architecture's name is created containing a symbolic
@@ -673,20 +699,20 @@ invalid.
 To turn some of the links in the link trees into real files, use the
 .B snaplink
 command.
-.\"
+.
 .SS listarch
 Writes a list of all known architecture names to standard output.  The
 list is obtained by reading the
 .B archtab
 file.
-.\"
+.
 .SS make \fR[\fImake-arg\fR...]
 Equivalent to
 .VS
 .BI "run make " make-arg\fR...
 .VE
 in all respects.
-.\"
+.
 .SS only\-arch \fIarch arch\fR...
 Imposes an architecture restriction.  Until cancelled by a later
 .B only\-arch
@@ -695,12 +721,12 @@ or
 command, the default build architectures will be limited to the
 architectures listed on the command line.  Architecture names may be
 abbreviated as long as the abbreviation is not ambiguous.
-.\"
+.
 .SS reset
 Clears the
 .I "successfully built"
 status of all architectures.
-.\"
+.
 .SS rsh \fIhost\fR|\fIarch \fR[\fIcommand \fR[\fIargument\fR...]]
 Runs
 .I command
@@ -711,23 +737,23 @@ The
 command is unlike the standard
 .B rsh
 program and its replacements:
-.HP \*o
+.hP \*o
 The
 .I command
 and
 .IR argument s
 are not subjected to further shell expansion on the remote host.
-.HP \*o
+.hP \*o
 The command is run with the remote current directory the same as the
 local current directory, rather than the remote user's home directory.
-.HP \*o
+.hP \*o
 The command is passed an environment constructed from the local
 environment, the default remote environment, and
 .B sw\-env
 files, as described in the section
 .B "Remote environment"
 below.
-.HP \*o
+.hP \*o
 The remote command is run with standard input attached to
 .BR /dev/null :
 there is no way of running an interactive remote command through
@@ -741,7 +767,7 @@ the special name
 .RB ` \- '
 signifying the current host.  (This last option may not sound useful,
 but it's handy for testing.)
-.\"
+.
 .SS run \fIcommand \fR[\fIargument\fR...]
 Runs a command on all build architectures.
 .PP
@@ -751,12 +777,12 @@ For each build architecture
 the local host or reading the hostname from the
 .B archtab
 file.  It then performs the following actions on that host:
-.HP 1.
+.hP 1.
 Sets the current directory to be the subdirectory named
 .I arch
 of the directory from which the command was issued.  This directory is
 created if it doesn't already exist.
-.HP 2.
+.hP 2.
 Sets up an environment constructed from the environment prevailing when
 the command was issued, the default environment set up by
 .B rsh
@@ -766,7 +792,7 @@ the
 files, as described in the section
 .B "Remote environment"
 below.
-.HP 3.
+.hP 3.
 Executes the program named
 .I command
 passing it the given
@@ -792,7 +818,7 @@ and further build commands will not affect it unless the
 command line option is passed, until a
 .B reset
 command is performed.
-.\"
+.
 .SS setup \fIpackage version \fR[\fImaintainer\fR]
 Sets up various pieces of information required by \*(sw.  The
 information here will be added into the main index file by a
@@ -821,7 +847,7 @@ user's name is used as the maintainer.
 The
 .B setup
 command must be run before any build command.
-.\"
+.
 .SS snaplink \fIfile \fR[\fIfile\fR...]
 Creates architecture-specific versions of a file.  Every
 .I file
@@ -834,9 +860,11 @@ overwriting any existing file or symbolic link of that name.  If
 contains leading directories then destination directories are created as
 necessary for the output files.  Note that the `snap' operation doesn't
 actually need to follow creation of link trees.
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "OUTPUT STYLES"
+.
 Output from a build command is presented in one of a number of named
 .IR "output styles" .
 The style name
@@ -875,24 +903,26 @@ sw \-o help run
 .PP
 The author has plans to implement an X-based output style, but hasn't
 got around to it yet.
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH "REMOTE ENVIRONMENT"
+.
 The environment for a remote command (executed either through the
 .B rsh
 command, or a build command) is set up as follows:
-.HP \*o
+.hP \*o
 The complete environment passed to \*(sw is used as a basis.
-.HP \*o
+.hP \*o
 Any environment variables defined by the remote execution program
 (usually
 .BR rsh )
 override corresponding variables in the basis environment.
-.HP \*o
+.hP \*o
 The
 .B SW_ARCH
 variable is set to the name of the remote host's architecture.
-.HP \*o
+.hP \*o
 Variable assignments are read from the global 
 .IB prefix /share/sw\-env
 file.  This makes some assignments which are useful everywhere, and will
@@ -904,9 +934,11 @@ The format of the
 .B sw\-env
 files is documented separately in
 .BR sw\-env (5).
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .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
 an example setup for \*(sw.
@@ -947,9 +979,11 @@ view where every host sees the same mapping between filenames and
 programs which do the same job.
 .PP
 And that's just about it.
-.\"
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH ENVIRONMENT
+.
 The following environment variables are of interest to
 .BR sw :
 .TP
@@ -974,8 +1008,11 @@ similar to
 is chosen.  I recommend using the excellent
 .B ssh
 program instead.
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH FILES
+.
 The following files are of interest to
 .BR sw :
 .TP
@@ -1016,14 +1053,19 @@ for file format details.
 .IB package / arch /.build\-log
 Contains all the build output for a particular architecture.  Usually
 not very interesting, but might be handy one day.
-.\"
+.
+.\"--------------------------------------------------------------------------
+.
 .SH BUGS
+.
 There are no bugs in
 .BR sw ,
 merely unexpected behaviour modes.  Silly you for thinking otherwise.
+.
 .SH AUTHOR
+.
 The \*(sw program, and this manual, are \*(mw productions, in association
 with the European Bioinformatics Institute.  They were written by Mark
 Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
-.\"
+.
 .\"----- That's all, folks --------------------------------------------------