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