From be07bee0ba62d2cdd3d9b4c86e9362c711456f19 Mon Sep 17 00:00:00 2001 From: mdw Date: Fri, 16 Jul 1999 12:45:37 +0000 Subject: [PATCH] Internal formatting improvements. --- archtab.5 | 42 ++++++++++----- sw-env.5 | 50 ++++++++++++------ sw-info.5 | 41 ++++++++++----- sw.1 | 178 ++++++++++++++++++++++++++++++++++++++------------------------ 4 files changed, 200 insertions(+), 111 deletions(-) diff --git a/archtab.5 b/archtab.5 index d2e25c4..d8bc576 100644 --- 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 . 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 --- 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 . 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 --- 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 . Go and ask him if you have problems. +. +.\"----- That's all, folks -------------------------------------------------- diff --git a/sw.1 b/sw.1 index e15f990..78cc17d 100644 --- 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 . Go and ask him if you have problems. -.\" +. .\"----- That's all, folks -------------------------------------------------- -- 2.11.0