961ce1c2 |
1 | .\" -*-nroff-*- |
2 | .\" |
9796a787 |
3 | .\" $Id: sw-cgi.1,v 1.2 2004/04/08 01:52:19 mdw Exp $ |
961ce1c2 |
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 | . |
961ce1c2 |
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 -------------------------------------------------- |