| 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 -------------------------------------------------- |