MANWEB(1)

💖 MANWEB 💖

okay so bestie, this is the manual for manweb — it lives in section 0 of the docs, which is literally called Manweb Reference Documentation. she's a browser for reference documentation, and she's about to become your whole personality. 💅

---

🌸 NAME 🌸

manweb — browse netpbm (and other) documentation 🦋

---

✨ SYNOPSIS ✨

manweb -help

manweb [-config=configfile] [topic [ subtopic ... ] ]

---

🎀 EXAMPLES 🎀

okay these are the vibes, watch:

manweb

This gets a master index of documentation. like, the whole menu. 🌈

manweb netpbm

This gets the main documentation page for the Netpbm package, with hyperlinks to the rest of the documentation. click around, live your life. ✨

manweb netpbm pngtopam

This goes directly to the documentation page for the Pngtopam program in the Netpbm package. no detours, straight to the good stuff. 💅

manweb pngtopam

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 pngtopam shell command (your PATH environment variable is involved 👀). yes bestie, your PATH is in the group chat.

manweb 3 fopen

This gets the traditional man page for the fopen() subroutine using man. old school, still iconic.

manweb cp

This gets the GNU Info manual for the cp program, using info. yes, info. we'll talk about it.

---

💜 DESCRIPTION 💜

manweb displays reference documentation via quick shell commands. she is a replacement for the well-known man. no cap.

🦋 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. she's giving range.
• manweb puts your topics in a tree for multilevel documentation. 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 properly 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. lowkey humble, highkey powerful. 💅

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 anything else your browser understands. she's flexible like that. 🌸

If manweb finds neither an HTML file nor a URL, but your parameters look like they could mean something to man, manweb calls man. Therefore, you can use a single command to access the vast body of traditional man pages, plus any newer manweb documentation. You can make "man" a shell alias of "manweb". periodt. 👑

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. so we still ride for her.

---

🔥 How Manweb Finds Documentation 🔥

manweb passes a URL to a web browser. This section tells how your manweb invocation parameters turn into that URL. the pipeline, bestie. the lore.

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. it's a chain, it's a vibe. ⛓️

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. easy. iconic. ✨
• 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. 😭 no validation, no safety net, we die like adults.
• 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. sorry bestie, she said no. 🙈
• 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: the .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. she goes deeper. 🌊
• 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. n/a, moving on. 💅

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. thorough queen. 👑

---

💖 The Configuration File 💖

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. layers, bestie. 🧚

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

---

🌈 How To Make HTML Documentation 🌈

Pages displayed by manweb don't have to have any particular format. You can write anything you want in HTML, using any web page generation tools or just by typing HTML in a text editor. you do you, bestie. 💅

Readers might appreciate something roughly in the format of classic Unix man pages (Name, Synopsis, etc.).

You can convert legacy nroff/troff man pages to passable HTML with the program mandoc. You don't have to do this just to access the information with manweb, because manweb falls back to invoking man if it doesn't find HTML pages, but if you are maintaining documentation, you might use this as a starting point for maintaining it in HTML in the future. glow-up arc. ✨

Example:

$ mandoc -T html foo.1 >foo.html

With a large number of pages, you could use find to do them all at once and parallel to do them more quickly. 💨

If you're converting a large collection of man pages, you'll have to deal with linked header files and linked manuals (where the troff man page refers to other pages) with something like this:

$ mandoc -T html -O includes='./%N.html'; -O man='%N.%S.html' ...

This creates similar HTML links to HTML file names, and you then make symbolic links for those names. 🔗

---

🫶 DOCUMENT SOURCE 🫶

This manual page was generated by the Netpbm tool makeman from HTML source. The master documentation is at

http://netpbm.sourceforge.net/doc/manweb.html

---

okay that's the whole page, bestie 💜 she came from netpbm documentation, and yeah, the title up top and the footer at the bottom both say Manweb Reference Documentation(0) — same energy, top and bottom, like a lil sandwich. 🥪 go read your docs. periodt. 👑🎀