1Manweb Reference Documentation(0) Manweb Reference Documentation(0)
2
6 manweb - browse netpbm (and other) documentation
7
10 manweb -help
11 manweb [-config=configfile] [topic [ subtopic ... ] ]
13
16 manweb
17 This gets a master index of documentation.
18 manweb netpbm
19 This gets the main documentation page for the Netpbm package, with
20 hyperlinks to the rest of the documentation.
21 manweb netpbm pngtopam
22 This goes directly to the documentation page for the Pngtopam program
23 in the Netpbm package.
24 manweb pngtopam
25 This also goes directly to the documentation page for the Pngtopam pro‐
26 gram in the Netpbm package, if that's what would run in response to a
27 pngtopam shell command (your PATH environment variable is involved).
28 manweb 3 fopen
29 This gets the traditional man page for the fopen() subroutine using
30 man.
31 manweb cp
32 This gets the GNU Info manual for the cp program, using info.
33
37 manweb displays reference documentation via quick shell commands. It
38 is a replacement for the well-known man.
39
42 manweb's advantages over man are:
43 ·
47 You can access documentation that is on the worldwide web
49 instead of
50 having locally installed copies. This saves installation
51 work and gets
52 you more current documentation.
53 ·
56 Documentation can be in HTML, which is more widely known,
58 more widely
59 useful, and more expressive than the nroff/troff format
60 used by
61 man.
62 ·
65 manweb puts your topics in a tree for multilevel documen‐
67 tation.
68 man is intended for a single level of documentation. For
69 example, you can have a man page for each shell command,
70 but not for
71 the subcommands of a shell command. And you cannot prop‐
72 erly have
73 man pages for the members of multiple subroutine
74 libraries.
75 ·
78 Documentation can be hyperlinked.
80 Web servers need not be involved -- the documentation can be in local
83 files. Graphics need not be involved -- the lynx browser works fine in
84 the same kind of terminals in which man works.
85 manweb finds the documentation you specify and calls a web browser of
87 your choice to display it. The documentation manweb finds can be
88 either an HTML file on your system, in which case, manweb gives a file:
89 URL to your browser, or an explicit URL. That explicit URL might be an
90 http: URL referring to an HTML file on a web server somewhere, or any‐
91 thing else your browser understands.
92 If manweb finds neither an HTML file nor a URL, but your parameters
94 look like they could mean something to man, manweb calls man. There‐
95 fore, you can use a single command to access the vast body of tradi‐
96 tional man pages, plus any newer manweb documentation. You can make
97 "man" a shell alias of "manweb".
98 manweb finds Info documentation as well. It looks for the topic you
100 specify as an Info topic after looking for HTML and URL documentation
101 and before running man. If manweb finds a corresponding Info topic, it
102 runs the program info on it. Info is the documentation system that the
103 GNU project invented to, among other things, replace traditional Unix
104 man pages. However, HTML and the Worldwide Web were invented shortly
105 afterward, so Info fizzled. But there is still a lot of GNU software
106 that is documented as Info topics.
107 How Manweb Finds Documentation
110 manweb passes a URL to a web browser. This section tells how your man‐
111 web invocation parameters turn into that URL.
112 manweb's search starts in the "web directory" directory. That's either
114 the value of the webdir keyword in your manweb configuration file, or
115 the default /usr/man/web.
116 Your invocation parameters form a "topic chain." Going from left to
118 right, the first parameter is the main topic, the 2nd is a subtopic of
119 the main topic, and so on.
120 Let's look at the simple case where you specify exactly one parameter
122 -- a main topic. We'll call it maintopic and look at 4 ways manweb
123 might find it:
124 ·
128 If manweb finds a file named maintopic.html
131 in the web directory, the URL manweb passes to the
132 browser is just a file: URL that specifies that .html
133 file.
134 ·
137 If there's no .html file, but there is a file named
140 maintopic.url, the contents of the first line of
141 that .url file is what manweb passes to the browser. It
142 doesn't interpret the contents at all. If it's garbage,
143 the
144 browser chokes on it.
145 ·
148 If there's neither a .html nor a .url file, but there is a
151 directory named maintopic, manweb looks in the
152 directory for a file named index.html. If there is one,
153 manweb passes a file: URL specifying that
154 index.html file to the browser. If there's no
155 index.html, manweb uses a file: URL that
156 specifies the directory itself.
157 ·
160 If manweb doesn't find documentation in any of the
163 above ways, it searches your executable search path (as
164 defined
165 by your PATH environment variable) for a program named
166 maintopic. If it finds one, it looks in the directory
167 that contains the program for a file named doc.url. If
168 it finds one, it appends maintopic.html to the
169 first line of the file and passes that to the browser.
170 Unless
171 the first line does not end with a slash -- in that
172 case, manweb passes the first line of the file unmodified
173 to the browser.
174 It gets a little more interesting when you have subtopics. Looking at
177 each of the 4 cases above:
178 ·
182 Where maintopic.html exists, subtopics are invalid.
184 You get a warning message and the subtopics are ignored.
185 ·
188 Where there's no .html file but maintopic.url exists,
190 manweb appends the subtopic chain to the URL it gets from
191 the
192 .url file as in the following example: .url file con‐
193 tains
194 http://acme.com/productxyz/ and subtopics are
195 create and
196 database. The URL manweb passes to the browser is
197 http://acme.com/productxyz/create/database.html.
198 manweb doesn't check that this kind of appendage makes
200 any sense for the URL in question, except that if the URL
201 in the
202 .url file doesn't end with a slash (/), manweb
203 issues a warning and doesn't append anything (ignores the
204 subtopics).
205 ·
207 Where there's neither a .html file nor a .url file, but
209 there's a
210 maintopic directory, manweb recurses into that
211 directory and begins a whole new search using the first
212 subtopic
213 as the main topic and the rest of the subtopics as
214 subtopics of that.
215 ·
217 When there are subtopics, the PATH thing doesn't make
219 sense,
220 so manweb doesn't do it.
221 If you give subtopics, the PATH thing described above for one
224 topic doesn't apply.
225 If you give no parameters at all, manweb generates a URL for the web
227 directory itself as described above for subdirectories.
228 The above is simplified by the assumption of a single web directory.
230 In reality, the webdir keyword in the configuration file can specify a
231 chain of web directories. manweb searches each one in turn, doing all
232 the kinds of searches in each web directory before moving on to the
233 next one.
234 The Configuration File
237 The default location of the manweb configuration file is /etc/man‐
238 web.conf. But you can override this with the environment variable MAN‐
239 WEB_CONF_FILE, and override that with the -config invocation option.
240 Lines starting with "#" are comments and are ignored, as are blank
242 lines.
243 All other lines have the format keyword=value. The keywords defined
245 are:
246 webdir
249 A colon-delimited sequence of directories to search for
251 documentation as described above. If you
252 don't specify this, the default is /usr/man/web alone.
253 browser
255 The file specification manweb of the web browser manweb
257 is to invoke
258 to display documentation (except when it uses man to dis‐
259 play
260 a conventional man page).
261 If the file specification does not include a slash, man‐
262 web
263 searches for the file in the PATH search path.
264 If you don't specify this, the default is the value of the
266 BROWSER environment variable, and if that is not set,
267 lynx.
268 Example:
271 # Configuration file for Manweb
272 webdir=/usr/share/manweb
274 browser=netscape
275netpbm documentation Manweb Reference Documentation(0)