Its almost the end of 2009, and I read on Planet Debian today a entry on writing man pages.
So man pages… where do we start? We have HTML / CSS / XML / RST which are all generally globally accepted formats of communication. Unfortunately, man pages do not use those.
And quite frankly, I am a fairly busy person, and have quite enough things to accomplish in a day. Why would I learn yet another formatting language? What justifies these files being in their own little world, when the whole world as a courtesy is supposed to provide them with their packages?
There really needs to be a movement to kill man pages in their current form, and bring them up to speed. A dialect for the sake of having a dialect really isn’t worth it when we have abundant alternatives.
Related posts:
#1 by David Ron on September 15, 2009 - 5:08 pm
Quote
Agreed. How about if there was a movement to consolidate documentation. Perhaps start with a wiki and then use that to automatically generate man pages/html help files/text help from the wiki markup?
This would allow the manual to grow with community input in a more simply and user-friendly way without disrupting the existing man infrastructure.
#2 by aanderse on September 15, 2009 - 6:32 pm
Quote
Yeah… given that things like w3m, links, etc… you’re entirely right.
+1
#3 by ethana2 on September 15, 2009 - 6:48 pm
Quote
++
#4 by ulrik on September 15, 2009 - 8:45 pm
Quote
Man pages are important, but I agree. My preferred format is reStructuredText, readable, easy to write.
#5 by quikee on September 16, 2009 - 1:51 am
Quote
I don’t think that HTML or HTML+CSS is the right thing for this kind of documentation as it defines the document “look” too strictly, but it is a nice format to convert the documentation to.
XML can be… well… anything so I will just skip it.
RST looks like the right thing but it lacks standardization. There is for example APT (Almost Plain Text) which is very similar but I don’t think the formats are compatible.
There is also DocBook format which is more appropriate that html but I think it is still too complicated to write in.
Another thing is also that people should just not write in the groff man format but use RST (or DocBook or any similar format) and then convert to groff man if they dislike the syntax or don’t want to learn the syntax. This is already possible and tools are available.
#6 by dave on September 16, 2009 - 7:20 am
Quote
“HTML is not an output format. HTML is The Format.” A key quote from an article in which
Mark Pilgrim shares his insights on writing a technical book in DocBook and why he’s doing the new version in HTML5 and how/why he converts to different formats:
http://diveintomark.org/archives/2009/03/27/dive-into-history-2009-edition
Note that standardising in HTML doesn’t mean individuals can’t write in Markdown, Textile, DocBook, RST, APT or whatever, they just have to convert it to HTML. I’d suggest writing modern HTML directly is easier than the current system.
#7 by Andy Smith on September 16, 2009 - 9:23 am
Quote
I could support the “man” program supporting different typesetting languages but absolutely do not agree that man pages are the wrong way to distribute simple documentation.
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.
#8 by Richard on September 16, 2009 - 6:02 pm
Quote
I disagree. You have to realize that many machines run headless, so something like html would be excessive for displaying just text. Man pages are designed for ease of reading on the command line. If you dislike the CLI paradigm, that’s another issue.
As for writing man pages for your applications, there’s nothing preventing you from eschewing that and putting your documentation online.
#9 by sharms on September 16, 2009 - 7:53 pm
Quote
Richard,
You dont understand. We are not talking about the presentation, but the format. Display would be the same.
#10 by Daniel Leidert on September 17, 2009 - 6:51 am
Quote
Well, you missed TeX in your list. It is pretty easy to create a manual page in (ROFF, GROFF, troff … whatever) from XML (via DocBook XML/XSLT) or from TeX.
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.
#11 by Steven Harms on September 17, 2009 - 3:03 pm
Quote
Daniel,
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.
#12 by Richard on September 19, 2009 - 10:44 pm
Quote
If you’re talking about the format, then perhaps you’re unfairly blaming man for not being widely adopted. Its origins (1971) precede the other standards for display and there is a large legacy base of man pages that would have to be needlessly rewritten to switch to another format. It’s not man’s fault for existing and being different.
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.
#13 by sharms on September 19, 2009 - 10:47 pm
Quote
Richard,
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.
#14 by Richard on September 20, 2009 - 9:41 pm
Quote
I’m not saying that it’s superior. There are definitely formats that are more suitable. However, man is *entrenched* because of a large user base just like many Microsoft products. Again, that is not a value statement. It’s just a statement of fact.
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.
#15 by ulrik on September 22, 2009 - 4:10 pm
Quote
I can only illustrate RestructuredText for a very simple application I write. The old man pages was written directly in troff (or whatever the language is called), I wrote it anew in reST, and it looked just the same, but the source was so much nicer!
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).
#16 by UX-admin on November 29, 2009 - 12:02 am
Quote
It appears that you misunderstand what manual pages are.
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.