mdw@git.distorted.org.uk Git - sw-tools/blob - perl/sw-cgi.1

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" $Id: sw-cgi.1,v 1.2 2004/04/08 01:52:19 mdw Exp $
   4 .\"
   5 .\" Man page for `sw' CGI script
   6 .\"
   7 .\" (c) 1999 EBI
   8 .\"
   9 .
  10 .\"----- Licensing notice ---------------------------------------------------
  11 .\"
  12 .\" This file is part of sw-tools.
  13 .\"
  14 .\" sw-tools is free software; you can redistribute it and/or modify
  15 .\" it under the terms of the GNU General Public License as published by
  16 .\" the Free Software Foundation; either version 2 of the License, or
  17 .\" (at your option) any later version.
  18 .\"
  19 .\" sw-tools is distributed in the hope that it will be useful,
  20 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22 .\" GNU General Public License for more details.
  23 .\"
  24 .\" You should have received a copy of the GNU General Public License
  25 .\" along with sw-tools; if not, write to the Free Software Foundation,
  26 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27 .
  28 if [ ! -r "$SW_PREFIX/doc/$SW_PACKAGE" ]; then
  29   echo >&2 "no documentation file \`$SW_PREFIX/doc/$SW_PACKAGE'"
  30   exit 1
  31 fi
  32 .VE
  33 Links to these documentation files are put into the table
  34 automatically.  The script picks out likely-looking references to other
  35 sources of information:
  36 .TP
  37 .I "manual pages"
  38 A reference of the form
  39 .IB name ( section )
  40 is suspected of being a manual page; the script looks in the manual
  41 directories to see if this is the case and if so inserts a hypertext
  42 link to the manual page.  This is the standard form for manual page
  43 references.
  44 .TP
  45 .I "info manuals"
  46 A reference of the form
  47 .BI info: name
  48 is assumed to be a reference to the GNU Info manual called
  49 .I name
  50 and an appropriate link inserted.  There isn't a standard form for Info
  51 references in non-Info manuals, so I've invented one.
  52 .TP
  53 .I "URLs"
  54 A URL which begins with one of
  55 .B http://
  56 or
  57 .B ftp://
  58 is spotted and turned into a link.  Only these two work.
  59 .TP
  60 .I "email addresses"
  61 Something that looks like an email address is turned into a
  62 .B mailto
  63 link.
  64 .PP
  65 Similar transformations are applied to manual pages when they're
  66 formatted.
  67 .
  68 .SS "Script arguments"
  69 The behaviour of the script is determined by the value of the
  70 .B act
  71 key.  Any of the following may be given:
  72 .TP
  73 .B list
  74 Emit the list of packages in tabular form.  This is the default if no
  75 .B act
  76 is given.
  77 .TP
  78 .B doc
  79 Format a textual documentation file.  The name of the package whose
  80 documentation is to be emitted is given as the value of the
  81 .B pkg
  82 key.
  83 .TP
  84 .B man
  85 Format a manual page, or emit a manual index.  If no
  86 .B sec
  87 key is given, an index of all manual pages in the software area is
  88 produced.  If
  89 .B sec
  90 is a manual page section (e.g.,
  91 .BR 1 ,
  92 not
  93 .BR man1 )
  94 but
  95 .B man
  96 is not given then an index of that particular section is emitted.  If
  97 both
  98 .B sec
  99 and
 100 .B man
 101 are supplied then the manual page whose name is given by the
 102 .B man
 103 key in the section given by the
 104 .B sec
 105 key is formatted (using
 106 .BR nroff (1))
 107 and displayed.  Manual page references, URLs and email addresses are
 108 transformed into links in the output.
 109 .TP
 110 .B info
 111 Format a GNU Info node.  If the
 112 .B file
 113 key is given, its value names an Info manual to open; the default is
 114 .BR dir .
 115 If the
 116 .B node
 117 key is given, its value names a node within the manual; the default is
 118 .BR Top .
 119 .TP
 120 .B show-config
 121 Emits a table showing the configuration settings which the script is
 122 aware of.  See
 123 .B Configuration
 124 below.  This is useful during debugging.
 125 .TP
 126 .B show-environment
 127 Displays the environment variables passed to the script by the Web
 128 server.  This is useful during debugging.
 129 .TP
 130 .B show-query
 131 Displays the query string passed by the Web server, decomposed into keys
 132 and values and decoded.  This is useful during debugging.
 133 .
 134 .SS "Configuration"
 135 The
 136 .B sw
 137 CGI script needs some configuration before it can do its work properly.
 138 Indeed, it will refuse to run until the configuration file has been
 139 edited.
 140 .PP
 141 The configuration file is in
 142 .IB prefix /share/sw.conf\fR.
 143 The format is simple.  A line may be empty, or a comment, in which case
 144 it is ignored.  Comments have
 145 .RB ` # '
 146 as their first non-whitespace character; blank lines contain only
 147 whitespace.  A line may also contain a configuration variable
 148 assignment, of the form
 149 .I key
 150 .RB  [ = ]
 151 .IR value .
 152 The
 153 .I key
 154 may be anything you like; only certain keys make sense to the script.
 155 .PP
 156 Configuration keys currently used are:
 157 .TP
 158 .B pkg
 159 The name of the package in which the script came.  This is set
 160 automatically and you should not change the value.
 161 .TP
 162 .B version
 163 The version number of the package.  This is set automatically and you
 164 should not change the value.
 165 .TP
 166 .B edited-config-file
 167 Must be assigned the value
 168 .BR yes .
 169 If this is not the case the script will immediately report an error.
 170 The default configuration file comes with a commented-out assignment to
 171 this variable.
 172 .TP
 173 .B prefix
 174 The installation prefix where your software gets installed.  You
 175 shouldn't need to change this, although it's handy for debugging.
 176 .TP
 177 .BR index ", " doc " and " datadir
 178 The name of the index file, documentation directory and shared data
 179 directory respectively.  The default values of these variables are set
 180 automatically and you shouldn't need to change them.
 181 .TP
 182 .B domain
 183 Your email domain.  Set this to the domain part for email addresses of
 184 people at your site, and the script will generate correct links in its
 185 main list page.
 186 .
 187 .\"--------------------------------------------------------------------------
 188 .
 189 .SH "SEE ALSO"
 190 .BR sw (1),
 191 .BR sw-info (5).
 192 .
 193 .SH "AUTHOR"
 194 .
 195 The \*(sw program, and this manual, are \*(mw productions, in association
 196 with the European Bioinformatics Institute.  They were written by Mark
 197 Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
 198 .
 199 .\"----- That's all, folks --------------------------------------------------