Manweb Reference Documentation(0) Manweb Reference Documentation(0)NAMEmanweb - browse netpbm (and other) documentation
SYNOPSISmanweb-help
manweb [-config=configfile] [topic [ subtopic ... ] ]
EXAMPLESmanweb
This gets a master index of documentation.
manweb netpbm
This gets the main documentation page for the Netpbm package, with
hyperlinks to the rest of the documentation.
manweb netpbm pngtopam
This goes directly to the documentation page for the Pngtopam program
in the Netpbm package.
manweb pngtopam
This also goes directly to the documentation page for the Pngtopam pro‐
gram in the Netpbm package, if that's what would run in response to a
pngtopam shell command (your PATH environment variable is involved).
manweb 3 fopen
This gets the traditional man page for the fopen() subroutine using
man.
manweb cp
This gets the GNU Info manual for the cp program, using info.
DESCRIPTIONmanweb displays reference documentation via quick shell commands. It
is a replacement for the well-known man.
Differences Between Man and Manweb
manweb's advantages over man are:
·
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.
·
Documentation can be in HTML, which is more widely known,
more widely
useful, and more expressive than the nroff/troff format
used by
man.
·
manweb puts your topics in a tree for multilevel documen‐
tation.
man 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 prop‐
erly have
man pages for the members of multiple subroutine
libraries.
·
Documentation can be hyperlinked.
Web servers need not be involved -- the documentation can be in local
files. Graphics need not be involved -- the lynx browser works fine in
the same kind of terminals in which man works.
manweb finds the documentation you specify and calls a web browser of
your choice to display it. The documentation manweb finds can be
either an HTML file on your system, in which case, manweb gives a file:
URL to your browser, or an explicit URL. That explicit URL might be an
http: URL referring to an HTML file on a web server somewhere, or any‐
thing else your browser understands.
If manweb finds neither an HTML file nor a URL, but your parameters
look like they could mean something to man, manweb calls man. There‐
fore, you can use a single command to access the vast body of tradi‐
tional man pages, plus any newer manweb documentation. You can make
"man" a shell alias of "manweb".
manweb 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 man. If manweb finds a corresponding Info topic, it
runs the program info 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.
How Manweb Finds Documentation
manweb passes a URL to a web browser. This section tells how your man‐
web invocation parameters turn into that URL.
manweb's search starts in the "web directory" directory. That's either
the value of the webdir keyword in your manweb configuration file, or
the default /usr/man/web.
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.
Let's look at the simple case where you specify exactly one parameter
-- a main topic. We'll call it maintopic and look at 4 ways manweb
might find it:
·
If manweb finds a file named maintopic.html
in the web directory, the URL manweb passes to the
browser is just a file: URL that specifies that .html
file.
·
If there's no .html file, but there is a file named
maintopic.url, the contents of the first line of
that .url file is what manweb passes to the browser. It
doesn't interpret the contents at all. If it's garbage,
the
browser chokes on it.
·
If there's neither a .html nor a .url file, but there is a
directory named maintopic, manweb looks in the
directory for a file named index.html. If there is one,
manweb passes a file: URL specifying that
index.html file to the browser. If there's no
index.html, manweb uses a file: URL that
specifies the directory itself.
·
If manweb doesn't find documentation in any of the
above ways, it searches your executable search path (as
defined
by your PATH environment variable) for a program named
maintopic. If it finds one, it looks in the directory
that contains the program for a file named doc.url. If
it finds one, it appends maintopic.html to the
first line of the file and passes that to the browser.
Unless
the first line does not end with a slash -- in that
case, manweb passes the first line of the file unmodified
to the browser.
It gets a little more interesting when you have subtopics. Looking at
each of the 4 cases above:
·
Where maintopic.html exists, subtopics are invalid.
You get a warning message and the subtopics are ignored.
·
Where there's no .html file but maintopic.url exists,
manweb appends the subtopic chain to the URL it gets from
the
.url file as in the following example: .url file con‐
tains
http://acme.com/productxyz/ and subtopics are
create and
database. The URL manweb passes to the browser is
http://acme.com/productxyz/create/database.html.
manweb 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 (/), manweb
issues a warning and doesn't append anything (ignores the
subtopics).
·
Where there's neither a .html file nor a .url file, but
there's a
maintopic directory, manweb 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.
·
When there are subtopics, the PATH thing doesn't make
sense,
so manweb doesn't do it.
If you give subtopics, the PATH thing described above for one
topic doesn't apply.
If you give no parameters at all, manweb generates a URL for the web
directory itself as described above for subdirectories.
The above is simplified by the assumption of a single web directory.
In reality, the webdir keyword in the configuration file can specify a
chain of web directories. manweb searches each one in turn, doing all
the kinds of searches in each web directory before moving on to the
next one.
The Configuration File
The default location of the manweb configuration file is /etc/man‐
web.conf. But you can override this with the environment variable MAN‐
WEB_CONF_FILE, and override that with the -config invocation option.
Lines starting with "#" are comments and are ignored, as are blank
lines.
All other lines have the format keyword=value. The keywords defined
are:
webdir
A colon-delimited sequence of directories to search for
documentation as described above. If you
don't specify this, the default is /usr/man/web alone.
browser
The file specification manweb of the web browser manweb
is to invoke
to display documentation (except when it uses man to dis‐
play
a conventional man page).
If the file specification does not include a slash, man‐
web
searches for the file in the PATH search path.
If you don't specify this, the default is the value of the
BROWSER environment variable, and if that is not set,
lynx.
Example:
# Configuration file for Manweb
webdir=/usr/share/manweb
browser=netscape
netpbm documentation Manweb Reference Documentation(0)
