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