Debian Codegraph @

upstream/mageia-cauldron/man1/manweb.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Manweb Reference Documentation" 0 "" "netpbm documentation"
7
8 .SH NAME
9 manweb - browse netpbm (and other) documentation
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBmanweb\fP \fB-help\fP
15 .PP
16 \fBmanweb\fP
17 [\fB-config=\fIconfigfile\fP\fP]
18 [\fItopic\fP [ \fIsubtopic\fP ... ] ]
19
20 .UN examples
21 .SH EXAMPLES
22
23 .nf
24 manweb
25
26 .fi
27 This gets a master index of documentation.
28 .nf
29 manweb netpbm
30
31 .fi
32 This gets the main documentation page for the Netpbm package, with hyperlinks
33 to the rest of the documentation.
34 .nf
35 manweb netpbm pngtopam
36
37 .fi
38 This goes directly to the documentation page for the Pngtopam program in
39 the Netpbm package.
40 .nf
41 manweb pngtopam
42
43 .fi
44 This also goes directly to the documentation page for the Pngtopam program in
45 the Netpbm package, if that's what would run in response to a \fBpngtopam\fP
46 shell command (your \fBPATH\fP environment variable is involved).
47 .nf
48 manweb 3 fopen
49
50 .fi
51 This gets the traditional man page for the fopen() subroutine using
52 \fBman\fP.
53 .nf
54 manweb cp
55
56 .fi
57 This gets the GNU Info manual for the \fBcp\fP program, using \fBinfo\fP.
58
59
60 .UN description
61 .SH DESCRIPTION
62 .PP
63 \fBmanweb\fP displays reference documentation via quick shell
64 commands. It is a replacement for the well-known \fBman\fP.
65
66 .SH Differences Between Man and Manweb
67 .PP
68 \fBmanweb\fP's advantages over \fBman\fP are:
69
70
71 .IP \(bu
72 You can access documentation that is on the worldwide web instead of
73 having locally installed copies. This saves installation work and gets
74 you more current documentation.
75
76 .IP \(bu
77 Documentation can be in HTML, which is more widely known, more widely
78 useful, and more expressive than the nroff/troff format used by
79 \fBman\fP.
80
81 .IP \(bu
82 \fBmanweb\fP puts your topics in a tree for multilevel documentation.
83 \fBman\fP is intended for a single level of documentation. For
84 example, you can have a man page for each shell command, but not for
85 the subcommands of a shell command. And you cannot properly have
86 man pages for the members of multiple subroutine libraries.
87
88 .IP \(bu
89 Documentation can be hyperlinked.
90
91 .PP
92 Web servers need not be involved -- the documentation can be in local
93 files. Graphics need not be involved -- the \fBlynx\fP browser works fine
94 in the same kind of terminals in which \fBman\fP works.
95 .PP
96 \fBmanweb\fP finds the documentation you specify and calls a web
97 browser of your choice to display it. The documentation \fBmanweb\fP
98 finds can be either an HTML file on your system, in which case,
99 \fBmanweb\fP gives a \fBfile:\fP URL to your browser, or an explicit
100 URL. That explicit URL might be an \fBhttp:\fP URL referring to an
101 HTML file on a web server somewhere, or anything else your browser
102 understands.
103 .PP
104 If \fBmanweb\fP finds neither an HTML file nor a URL, but your parameters
105 look like they could mean something to \fBman\fP, \fBmanweb\fP calls
106 \fBman\fP. Therefore, you can use a single command to access the vast
107 body of traditional man pages, plus any newer \fBmanweb\fP documentation.
108 You can make "man" a shell alias of "manweb".
109 .PP
110 \fBmanweb\fP finds Info documentation as well. It looks for the
111 topic you specify as an Info topic after looking for HTML and URL
112 documentation and before running \fBman\fP. If \fBmanweb\fP finds a
113 corresponding Info topic, it runs the program \fBinfo\fP on it. Info
114 is the documentation system that the GNU project invented to, among
115 other things, replace traditional Unix man pages. However, HTML and the
116 Worldwide Web were invented shortly afterward, so Info fizzled. But there
117 is still a lot of GNU software that is documented as Info topics.
118
119 .SS How Manweb Finds Documentation
120 .PP
121 \fBmanweb\fP passes a URL to a web browser. This section tells
122 how your \fBmanweb\fP invocation parameters turn into that URL.
123 .PP
124 \fBmanweb\fP's search starts in the "web directory" directory.
125 That's either the value of the \fBwebdir\fP keyword in your
126 \fBmanweb\fP configuration file, or the default \fB/usr/man/web\fP.
127 .PP
128 Your invocation parameters form a "topic chain." Going from left to right,
129 the first parameter is the main topic, the 2nd is a subtopic of the main
130 topic, and so on.
131 .PP
132 Let's look at the simple case where you specify exactly one parameter --
133 a main topic. We'll call it \fImaintopic\fP and look at 4 ways
134 \fBmanweb\fP might find it:
135
136
137 .IP \(bu
138 .sp
139 If \fBmanweb\fP finds a file named \fImaintopic\fP\fB.html\fP
140 in the web directory, the URL \fBmanweb\fP passes to the
141 browser is just a \fBfile:\fP URL that specifies that .html
142 file.
143
144 .IP \(bu
145 .sp
146 If there's no .html file, but there is a file named
147 \fImaintopic\fP\fB.url\fP, the contents of the first line of
148 that .url file is what \fBmanweb\fP passes to the browser. It
149 doesn't interpret the contents at all. If it's garbage, the
150 browser chokes on it.
151
152 .IP \(bu
153 .sp
154 If there's neither a .html nor a .url file, but there is a
155 directory named \fImaintopic\fP, \fBmanweb\fP looks in the
156 directory for a file named \fIindex.html\fP. If there is one,
157 \fBmanweb\fP passes a \fBfile:\fP URL specifying that
158 index.html file to the browser. If there's no
159 \fIindex.html\fP, \fBmanweb\fP uses a \fBfile:\fP URL that
160 specifies the directory itself.
161
162 .IP \(bu
163 .sp
164 If \fBmanweb\fP doesn't find documentation in any of the
165 above ways, it searches your executable search path (as defined
166 by your \fBPATH\fP environment variable) for a program named
167 \fImaintopic\fP. If it finds one, it looks in the directory
168 that contains the program for a file named \fBdoc.url\fP. If
169 it finds one, it appends \fImaintopic\fP\fB.html\fP to the
170 first line of the file and passes that to the browser. Unless
171 the first line does \fInot\fP end with a slash -- in that
172 case, \fBmanweb\fP passes the first line of the file unmodified
173 to the browser.
174
175 .PP
176 It gets a little more interesting when you have subtopics. Looking
177 at each of the 4 cases above:
178
179
180 .IP \(bu
181 Where \fImaintopic\fP\fB.html\fP exists, subtopics are invalid.
182 You get a warning message and the subtopics are ignored.
183
184 .IP \(bu
185 Where there's no .html file but \fImaintopic\fP\fB.url\fP exists,
186 \fBmanweb\fP appends the subtopic chain to the URL it gets from the
187 .url file as in the following example: .url file contains
188 \fBhttp://acme.com/productxyz/\fP and subtopics are
189 \fBcreate\fP and
190 \fBdatabase\fP. The URL \fBmanweb\fP passes to the browser is
191 \fBhttp://acme.com/productxyz/create/database.html\fP.
192 .sp
193 \fBmanweb\fP doesn't check that this kind of appendage makes
194 any sense for the URL in question, except that if the URL in the
195 .url file doesn't end with a slash (\fB/\fP), \fBmanweb\fP
196 issues a warning and doesn't append anything (ignores the subtopics).
197 .IP \(bu
198 Where there's neither a .html file nor a .url file, but there's a
199 \fImaintopic\fP directory, \fBmanweb\fP recurses into that
200 directory and begins a whole new search using the first subtopic
201 as the main topic and the rest of the subtopics as subtopics of that.
202 .IP \(bu
203 When there are subtopics, the \fBPATH\fP thing doesn't make sense,
204 so \fBmanweb\fP doesn't do it.
205
206
207 If you give subtopics, the \fBPATH\fP thing described above for one
208 topic doesn't apply.
209 .PP
210 If you give no parameters at all, \fBmanweb\fP generates a URL for the
211 web directory itself as described above for subdirectories.
212 .PP
213 The above is simplified by the assumption of a single web
214 directory. In reality, the \fBwebdir\fP keyword in the configuration
215 file can specify a chain of web directories. \fBmanweb\fP searches
216 each one in turn, doing all the kinds of searches in each web directory
217 before moving on to the next one.
218
219 .SS The Configuration File
220 .PP
221 The default location of the \fBmanweb\fP configuration file is
222 \fB/etc/manweb.conf\fP. But you can override this with the environment
223 variable \fBMANWEB_CONF_FILE\fP, and override that with the
224 \fB-config\fP invocation option.
225 .PP
226 Lines starting with "#" are comments and are ignored, as are blank lines.
227 .PP
228 All other lines have the format \fIkeyword\fP=\fIvalue\fP. The
229 keywords defined are:
230
231 .TP
232 webdir
233
234 A colon-delimited sequence of directories to search for
235 documentation as described above. If you
236 don't specify this, the default is \fB/usr/man/web\fP alone.
237 .TP
238 browser
239
240 The file specification \fBmanweb\fP of the web browser \fBmanweb\fP
241 is to invoke
242 to display documentation (except when it uses \fBman\fP to display
243 a conventional man page).
244 If the file specification does not include a slash, \fBmanweb\fP
245 searches for the file in the PATH search path.
246 .sp
247 If you don't specify this, the default is the value of the
248 \fBBROWSER\fP environment variable, and if that is not set,
249 \fBlynx\fP.
250
251
252 Example:
253 .nf
254 # Configuration file for Manweb
255
256 webdir=/usr/share/manweb
257 browser=netscape
258
259 .fi
260
261 .SS How To Make HTML Documentation
262 .PP
263 Pages displayed by \fBmanweb\fP don't have to have any particular
264 format. You can write anything you want in HTML, using any web page
265 generation tools or just by typing HTML in a text editor.
266 .PP
267 Readers might appreciate something roughly in the format of classic Unix
268 man pages (Name, Synopsis, etc.).
269 .PP
270 You can convert legacy nroff/troff man pages to passable HTML with the
271 program \fBmandoc\fP. You don't have to do this just to access the
272 information with \fBmanweb\fP, because \fBmanweb\fP falls back to
273 invoking \fBman\fP if it doesn't find HTML pages, but if you are
274 maintaining documentation, you might use this as a starting point for
275 maintaining it in HTML in the future.
276 .PP
277 Example:
278
279 .nf
280 \f(CW
281 $ mandoc -T html foo.1 >foo.html
282 \fP
283
284 .fi
285 .PP
286 With a large number of pages, you could use \fBfind\fP to do them all at
287 once and \fBparallel\fP to do them more quickly.
288 .PP
289 If you're converting a large collection of man pages, you'll have
290 to deal with linked header files and linked manuals (where the troff
291 man page refers to other pages) with something like this:
292
293 .nf
294 \f(CW
295 $ mandoc -T html -O includes='./%N.html'; -O man='%N.%S.html' ...
296 \fP
297
298 .fi
299
300 This creates similar HTML links to HTML file names, and you then make symbolic
301 links for those names.
302
303
304 .SH DOCUMENT SOURCE
305 This manual page was generated by the Netpbm tool 'makeman' from HTML
306 source. The master documentation is at
307 .IP
308 .B http://netpbm.sourceforge.net/doc/manweb.html
309 .PP