1Manweb Reference Documentation(0)            Manweb Reference Documentation(0)
2
3
4

NAME

6       manweb - browse netpbm (and other) documentation
7
8

SYNOPSIS

10       manweb -help
11
12       manweb [-config=configfile] [topic [ subtopic ... ] ]
13
14

EXAMPLES

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
34
35

DESCRIPTION

37       manweb displays reference documentation via quick shell  commands.   It
38       is a replacement for the well-known man.
39
40

Differences Between Man and Manweb

42       manweb's advantages over man are:
43
44
45
46       ·
47
48                     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
54
55       ·
56
57                     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
63
64       ·
65
66                     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
76
77       ·
78
79                     Documentation can be hyperlinked.
80
81
82       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
86       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
93       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
99       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
108
109   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
113       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
117       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
121       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
125
126
127       ·
128
129
130              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
135
136       ·
137
138
139              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
146
147       ·
148
149
150              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
158
159       ·
160
161
162              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
175
176       It  gets a little more interesting when you have subtopics.  Looking at
177       each of the 4 cases above:
178
179
180
181       ·
182
183                     Where maintopic.html exists, subtopics are invalid.
184                     You get a warning message and the subtopics are ignored.
185
186
187       ·
188
189                     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
199              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
206       ·
207
208                     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
216       ·
217
218                     When  there  are  subtopics,  the PATH thing doesn't make
219              sense,
220                     so manweb doesn't do it.
221
222
223              If you give subtopics, the PATH thing described  above  for  one
224              topic doesn't apply.
225
226       If  you  give  no parameters at all, manweb generates a URL for the web
227       directory itself as described above for subdirectories.
228
229       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
235
236   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
241       Lines starting with "#" are comments and  are  ignored,  as  are  blank
242       lines.
243
244       All  other  lines  have the format keyword=value.  The keywords defined
245       are:
246
247
248       webdir
249
250                     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
254       browser
255
256                     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
265              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
269
270              Example:
271              # Configuration file for Manweb
272
273              webdir=/usr/share/manweb
274              browser=netscape
275
276
277
278
279
280
281netpbm documentation                         Manweb Reference Documentation(0)
Impressum