They’re written a so-called “minilanguage”, or rather, several minilanguages, yes, PROGRAMMING LANGUAGES, which facilitate TYPSETTING, NOT FORMATTING.

Typesetting, as in, preparing and formatting a book for print!

Displaying formatted ASCII text with the man(1) command just happens to be a sideeffect of how flexible and powerful the tbl(1), eqn(1) and troff(1) tools are.

A typical book-for-print preparation might look like:

eqn file | tbl | troff -Tps > ready-to-print-file.ps

While a manual page formatting might look like

tbl command.tbl > /opt/abcd/share/man/command.1

Your statement that “man pages live in their own little world” is indicative of your misunderstanding of the capabilities of the said tools and intent; I suggest you educate yourself on the subject before you go off on a tangent with HTML and CSS and XML/XSLT and RST next time.

A good start is a book called “UNIX text processing” written by Dale Dougherty and Tim O’Reilly of the O’Reilly fame.

No excuses in the form of “I don’t have enough time” will be recognized as valid; after all, you had the time to scribble all this, TIME YOU COULD HAVE SPENT LEARNING TROFF.

Here is the source reST file:

http://kaizer.se/wiki/kupfer-man-rst

Rendered to man looks like this (missing bold, underline and that kind of style here though):

http://kaizer.se/wiki/kupfer-man-out

The program to render it is rst2man.

I think reST is very well specified and as a programmer, easy to understand. A programmer’s editor (such as vim) also makes it easy to format it well (text wrapping and keeping indent is done automatically).

You have a problem with man. Okay, that’s fine. Why don’t you supply patches for every single app out there that change the format to some standard? No? You can write a generator that changes man to XML. How about using a different mode of documenting your software to squeeze man out of the market? Emacs and vim are losing popularity among the new generation of programmers because they grew up on WYSIWYG alternatives.

I don’t write man pages for my apps because my users read documentation online. You can wait until the collective mass of users put market pressure on it to switch because clearly, the status quo is working out for most people.

The world is what it is. You can try to change it or change your way of thinking about things to deal with it. Complaining about it here is not going to start a mass movement.

A lot was different in 1971, but it doesn’t mean it was technically superior nor gained adoption — I hear betamax was great.

Your analogy is flawed, technology evolves, the idea of manpages is good it just needs a refresh.

Your complaint about man would be roughly comparable to a typical American who can only speak English going to Slovenia and complaining that they haven’t adopted English as the official language.

In your case, I would suggest learning man if you want to create man pages or give up and not use it. In any case, it’s unfair to complain about it. The “not enough time” excuse is not really valid since everyone has the same amount of time; it’s just that you value spending time on other things than whatever you do that involves man. Case in point: I’m sure that if some company hired you for a huge contract to make man pages for their product, you’d have no trouble finding time for it.

Tex has more features than required. I am talking about a minimal subset of HTML would be used. GROFF is absolutely never the best choice. It may be your habit, but not the intelligent / pragmatic choice.

However, GROFF is alive and developing further, although it might not be your choice. You can of course prefer XML or TeX to write documentation (inlcuding manual pages). But for a short manual page I have learned that it is much easier to write it in GROFF. And for the purpose of providing a manual page for every binary in a Debian package, GROFF is often the best choice. All alternatives need a large dependency chain and require more “writing work”. You don’t need much knowledge of GROFF to write short manual pages. You can even create some nice PDF/PS output via GROFF as the docbook-xsl project prooves.

You dont understand. We are not talking about the presentation, but the format. Display would be the same.

As for writing man pages for your applications, there’s nothing preventing you from eschewing that and putting your documentation online.

When I am logged in to a machine wanting to know how to use a command, I want to be able to type “man $foo” and find out what the options to $foo are. I don’t want to have to bring up a web browser or PDF reader. In my opinion if all “man” would be doing is interpreting HTML or whatever into something readable on a terminal screen then great, but not if the expectation is greater than this.

When it comes to more in-depth documentation on larger software packages then yes it is appropriate in my opinion to go to their web site and read their documentation in HTML format.