diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/manweb.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/manweb.1 | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/manweb.1 b/upstream/mageia-cauldron/man1/manweb.1 new file mode 100644 index 00000000..9e73250a --- /dev/null +++ b/upstream/mageia-cauldron/man1/manweb.1 @@ -0,0 +1,278 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Manweb Reference Documentation" 0 "" "netpbm documentation" + + .SH NAME +manweb - browse netpbm (and other) documentation + +.UN synopsis +.SH SYNOPSIS + +\fBmanweb\fP \fB-help\fP +.PP +\fBmanweb\fP +[\fB-config=\fIconfigfile\fP\fP] +[\fItopic\fP [ \fIsubtopic\fP ... ] ] + +.UN examples +.SH EXAMPLES + +.nf +manweb + +.fi +This gets a master index of documentation. +.nf +manweb netpbm + +.fi +This gets the main documentation page for the Netpbm package, with hyperlinks +to the rest of the documentation. +.nf +manweb netpbm pngtopam + +.fi +This goes directly to the documentation page for the Pngtopam program in +the Netpbm package. +.nf +manweb pngtopam + +.fi +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 \fBpngtopam\fP +shell command (your \fBPATH\fP environment variable is involved). +.nf +manweb 3 fopen + +.fi +This gets the traditional man page for the fopen() subroutine using +\fBman\fP. +.nf +manweb cp + +.fi +This gets the GNU Info manual for the \fBcp\fP program, using \fBinfo\fP. + + +.UN description +.SH DESCRIPTION +.PP +\fBmanweb\fP displays reference documentation via quick shell +commands. It is a replacement for the well-known \fBman\fP. + +.SH Differences Between Man and Manweb +.PP +\fBmanweb\fP's advantages over \fBman\fP are: + + +.IP \(bu + + 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. + +.IP \(bu + + Documentation can be in HTML, which is more widely known, more widely + useful, and more expressive than the nroff/troff format used by + \fBman\fP. + +.IP \(bu + + \fBmanweb\fP puts your topics in a tree for multilevel documentation. + \fBman\fP 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. + +.IP \(bu + + Documentation can be hyperlinked. + +.PP +Web servers need not be involved -- the documentation can be in local +files. Graphics need not be involved -- the \fBlynx\fP browser works fine +in the same kind of terminals in which \fBman\fP works. +.PP +\fBmanweb\fP finds the documentation you specify and calls a web +browser of your choice to display it. The documentation \fBmanweb\fP +finds can be either an HTML file on your system, in which case, +\fBmanweb\fP gives a \fBfile:\fP URL to your browser, or an explicit +URL. That explicit URL might be an \fBhttp:\fP URL referring to an +HTML file on a web server somewhere, or anything else your browser +understands. +.PP +If \fBmanweb\fP finds neither an HTML file nor a URL, but your parameters +look like they could mean something to \fBman\fP, \fBmanweb\fP calls +\fBman\fP. Therefore, you can use a single command to access the vast +body of traditional man pages, plus any newer \fBmanweb\fP documentation. +You can make "man" a shell alias of "manweb". +.PP +\fBmanweb\fP 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 \fBman\fP. If \fBmanweb\fP finds a +corresponding Info topic, it runs the program \fBinfo\fP 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. + +.SS How Manweb Finds Documentation +.PP +\fBmanweb\fP passes a URL to a web browser. This section tells +how your \fBmanweb\fP invocation parameters turn into that URL. +.PP +\fBmanweb\fP's search starts in the "web directory" directory. +That's either the value of the \fBwebdir\fP keyword in your +\fBmanweb\fP configuration file, or the default \fB/usr/man/web\fP. +.PP +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. +.PP +Let's look at the simple case where you specify exactly one parameter -- +a main topic. We'll call it \fImaintopic\fP and look at 4 ways +\fBmanweb\fP might find it: + + +.IP \(bu + +.sp +If \fBmanweb\fP finds a file named \fImaintopic\fP\fB.html\fP + in the web directory, the URL \fBmanweb\fP passes to the + browser is just a \fBfile:\fP URL that specifies that .html + file. + +.IP \(bu + +.sp +If there's no .html file, but there is a file named + \fImaintopic\fP\fB.url\fP, the contents of the first line of + that .url file is what \fBmanweb\fP passes to the browser. It + doesn't interpret the contents at all. If it's garbage, the + browser chokes on it. + +.IP \(bu + +.sp +If there's neither a .html nor a .url file, but there is a + directory named \fImaintopic\fP, \fBmanweb\fP looks in the + directory for a file named \fIindex.html\fP. If there is one, + \fBmanweb\fP passes a \fBfile:\fP URL specifying that + index.html file to the browser. If there's no + \fIindex.html\fP, \fBmanweb\fP uses a \fBfile:\fP URL that + specifies the directory itself. + +.IP \(bu + +.sp +If \fBmanweb\fP doesn't find documentation in any of the + above ways, it searches your executable search path (as defined + by your \fBPATH\fP environment variable) for a program named + \fImaintopic\fP. If it finds one, it looks in the directory + that contains the program for a file named \fBdoc.url\fP. If + it finds one, it appends \fImaintopic\fP\fB.html\fP to the + first line of the file and passes that to the browser. Unless + the first line does \fInot\fP end with a slash -- in that + case, \fBmanweb\fP passes the first line of the file unmodified + to the browser. + +.PP +It gets a little more interesting when you have subtopics. Looking +at each of the 4 cases above: + + +.IP \(bu + + Where \fImaintopic\fP\fB.html\fP exists, subtopics are invalid. + You get a warning message and the subtopics are ignored. + +.IP \(bu + + Where there's no .html file but \fImaintopic\fP\fB.url\fP exists, + \fBmanweb\fP appends the subtopic chain to the URL it gets from the + .url file as in the following example: .url file contains + \fBhttp://acme.com/productxyz/\fP and subtopics are + \fBcreate\fP and + \fBdatabase\fP. The URL \fBmanweb\fP passes to the browser is + \fBhttp://acme.com/productxyz/create/database.html\fP. +.sp +\fBmanweb\fP 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 (\fB/\fP), \fBmanweb\fP + issues a warning and doesn't append anything (ignores the subtopics). +.IP \(bu + + Where there's neither a .html file nor a .url file, but there's a + \fImaintopic\fP directory, \fBmanweb\fP 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. +.IP \(bu + + When there are subtopics, the \fBPATH\fP thing doesn't make sense, + so \fBmanweb\fP doesn't do it. + + +If you give subtopics, the \fBPATH\fP thing described above for one +topic doesn't apply. +.PP +If you give no parameters at all, \fBmanweb\fP generates a URL for the +web directory itself as described above for subdirectories. +.PP +The above is simplified by the assumption of a single web +directory. In reality, the \fBwebdir\fP keyword in the configuration +file can specify a chain of web directories. \fBmanweb\fP searches +each one in turn, doing all the kinds of searches in each web directory +before moving on to the next one. + +.SS The Configuration File +.PP +The default location of the \fBmanweb\fP configuration file is +\fB/etc/manweb.conf\fP. But you can override this with the environment +variable \fBMANWEB_CONF_FILE\fP, and override that with the +\fB-config\fP invocation option. +.PP +Lines starting with "#" are comments and are ignored, as are blank lines. +.PP +All other lines have the format \fIkeyword\fP=\fIvalue\fP. The +keywords defined are: + +.TP +webdir + + A colon-delimited sequence of directories to search for + documentation as described above. If you + don't specify this, the default is \fB/usr/man/web\fP alone. +.TP +browser + + The file specification \fBmanweb\fP of the web browser \fBmanweb\fP + is to invoke + to display documentation (except when it uses \fBman\fP to display + a conventional man page). + If the file specification does not include a slash, \fBmanweb\fP + searches for the file in the PATH search path. +.sp +If you don't specify this, the default is the value of the + \fBBROWSER\fP environment variable, and if that is not set, + \fBlynx\fP. + + +Example: +.nf +# Configuration file for Manweb + +webdir=/usr/share/manweb +browser=netscape + +.fi + +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/manweb.html +.PP
\ No newline at end of file |