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