manweb - Man Page

manweb passes a URL to a web browser.  This section tells how your manweb 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 contains
        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 default location of the manweb configuration file is /etc/manweb.conf.  But you can override this with the environment variable MANWEB_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 display
      a conventional man page).
      If the file specification does not include a slash, manweb
      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