1Manweb Reference Documentation(0) Manweb Reference Documentation(0)
2 .SH NAME manweb - browse netpbm (and other) documentation
6
9 manweb -help
10 manweb [-config=configfile] [topic [ subtopic ... ] ]
12
15 manweb
16 This gets a master index of documentation.
18 manweb netpbm
19 This gets the main documentation page for the Netpbm package, with hy‐
21 perlinks to the rest of the documentation.
22 manweb netpbm pngtopam
23 This goes directly to the documentation page for the Pngtopam program
25 in the Netpbm package.
26 manweb pngtopam
27 This also goes directly to the documentation page for the Pngtopam pro‐
29 gram in the Netpbm package, if that's what would run in response to a
30 pngtopam shell command (your PATH environment variable is involved).
31 manweb 3 fopen
32 This gets the traditional man page for the fopen() subroutine using
34 man.
35 manweb cp
36 This gets the GNU Info manual for the cp program, using info.
38
42 manweb displays reference documentation via quick shell commands. It
43 is a replacement for the well-known man.
44
47 manweb's advantages over man are:
48 •
52 You can access documentation that is on the worldwide web
54 instead of
55 having locally installed copies. This saves installation
56 work and gets
57 you more current documentation.
58 •
61 Documentation can be in HTML, which is more widely known,
63 more widely
64 useful, and more expressive than the nroff/troff format
65 used by
66 man.
67 •
70 manweb puts your topics in a tree for multilevel documen‐
72 tation.
73 man is intended for a single level of documentation. For
74 example, you can have a man page for each shell command,
75 but not for
76 the subcommands of a shell command. And you cannot prop‐
77 erly have
78 man pages for the members of multiple subroutine li‐
79 braries.
80 •
83 Documentation can be hyperlinked.
85 Web servers need not be involved -- the documentation can be in local
88 files. Graphics need not be involved -- the lynx browser works fine in
89 the same kind of terminals in which man works.
90 manweb finds the documentation you specify and calls a web browser of
92 your choice to display it. The documentation manweb finds can be ei‐
93 ther an HTML file on your system, in which case, manweb gives a file:
94 URL to your browser, or an explicit URL. That explicit URL might be an
95 http: URL referring to an HTML file on a web server somewhere, or any‐
96 thing else your browser understands.
97 If manweb finds neither an HTML file nor a URL, but your parameters
99 look like they could mean something to man, manweb calls man. There‐
100 fore, you can use a single command to access the vast body of tradi‐
101 tional man pages, plus any newer manweb documentation. You can make
102 "man" a shell alias of "manweb".
103 manweb finds Info documentation as well. It looks for the topic you
105 specify as an Info topic after looking for HTML and URL documentation
106 and before running man. If manweb finds a corresponding Info topic, it
107 runs the program info on it. Info is the documentation system that the
108 GNU project invented to, among other things, replace traditional Unix
109 man pages. However, HTML and the Worldwide Web were invented shortly
110 afterward, so Info fizzled. But there is still a lot of GNU software
111 that is documented as Info topics.
112 How Manweb Finds Documentation
115 manweb passes a URL to a web browser. This section tells how your man‐
116 web invocation parameters turn into that URL.
117 manweb's search starts in the "web directory" directory. That's either
119 the value of the webdir keyword in your manweb configuration file, or
120 the default /usr/man/web.
121 Your invocation parameters form a "topic chain." Going from left to
123 right, the first parameter is the main topic, the 2nd is a subtopic of
124 the main topic, and so on.
125 Let's look at the simple case where you specify exactly one parameter
127 -- a main topic. We'll call it maintopic and look at 4 ways manweb
128 might find it:
129 •
133 If manweb finds a file named maintopic.html
136 in the web directory, the URL manweb passes to the
137 browser is just a file: URL that specifies that .html
138 file.
139 •
142 If there's no .html file, but there is a file named
145 maintopic.url, the contents of the first line of
146 that .url file is what manweb passes to the browser. It
147 doesn't interpret the contents at all. If it's garbage,
148 the
149 browser chokes on it.
150 •
153 If there's neither a .html nor a .url file, but there is a
156 directory named maintopic, manweb looks in the
157 directory for a file named index.html. If there is one,
158 manweb passes a file: URL specifying that
159 index.html file to the browser. If there's no
160 index.html, manweb uses a file: URL that
161 specifies the directory itself.
162 •
165 If manweb doesn't find documentation in any of the
168 above ways, it searches your executable search path (as
169 defined
170 by your PATH environment variable) for a program named
171 maintopic. If it finds one, it looks in the directory
172 that contains the program for a file named doc.url. If
173 it finds one, it appends maintopic.html to the
174 first line of the file and passes that to the browser.
175 Unless
176 the first line does not end with a slash -- in that
177 case, manweb passes the first line of the file unmodified
178 to the browser.
179 It gets a little more interesting when you have subtopics. Looking at
182 each of the 4 cases above:
183 •
187 Where maintopic.html exists, subtopics are invalid.
189 You get a warning message and the subtopics are ignored.
190 •
193 Where there's no .html file but maintopic.url exists,
195 manweb appends the subtopic chain to the URL it gets from
196 the
197 .url file as in the following example: .url file con‐
198 tains
199 http://acme.com/productxyz/ and subtopics are
200 create and
201 database. The URL manweb passes to the browser is
202 http://acme.com/productxyz/create/database.html.
203 manweb doesn't check that this kind of appendage makes
205 any sense for the URL in question, except that if the URL
206 in the
207 .url file doesn't end with a slash (/), manweb
208 issues a warning and doesn't append anything (ignores the
209 subtopics).
210 •
212 Where there's neither a .html file nor a .url file, but
214 there's a
215 maintopic directory, manweb recurses into that
216 directory and begins a whole new search using the first
217 subtopic
218 as the main topic and the rest of the subtopics as
219 subtopics of that.
220 •
222 When there are subtopics, the PATH thing doesn't make
224 sense,
225 so manweb doesn't do it.
226 If you give subtopics, the PATH thing described above for one
229 topic doesn't apply.
230 If you give no parameters at all, manweb generates a URL for the web
232 directory itself as described above for subdirectories.
233 The above is simplified by the assumption of a single web directory.
235 In reality, the webdir keyword in the configuration file can specify a
236 chain of web directories. manweb searches each one in turn, doing all
237 the kinds of searches in each web directory before moving on to the
238 next one.
239 The Configuration File
242 The default location of the manweb configuration file is /etc/man‐
243 web.conf. But you can override this with the environment variable MAN‐
244 WEB_CONF_FILE, and override that with the -config invocation option.
245 Lines starting with "#" are comments and are ignored, as are blank
247 lines.
248 All other lines have the format keyword=value. The keywords defined
250 are:
251 webdir
254 A colon-delimited sequence of directories to search for
256 documentation as described above. If you
257 don't specify this, the default is /usr/man/web alone.
258 browser
260 The file specification manweb of the web browser manweb
262 is to invoke
263 to display documentation (except when it uses man to dis‐
264 play
265 a conventional man page).
266 If the file specification does not include a slash, man‐
267 web
268 searches for the file in the PATH search path.
269 If you don't specify this, the default is the value of the
271 BROWSER environment variable, and if that is not set,
272 lynx.
273 Example:
276 # Configuration file for Manweb
277 webdir=/usr/share/manweb
279 browser=netscape
280
284 This manual page was generated by the Netpbm tool 'makeman' from HTML
285 source. The master documentation is at
286 http://netpbm.sourceforge.net/doc/manweb.html
288netpbm documentation Manweb Reference Documentation(0)