On 21/08/2015 22:10, Buck Evan wrote:
> _at_Laurent: What's your take on man pages?
Short version: I like them, as long as I don't have to write them
or move a finger to generate them.
Long version:
I honestly believe man pages are obsolete. They were cool in the
90's when they were all we had; but today, *everyone* has a web
browser, and can look at HTML documentation. Even if they don't have
an Internet access.
I still find myself typing "man" sometimes. It's a reflex because
I'm a dinosaur. But if it doesn't work, I don't mind: the documentation
*is* somewhere, I just have to grab my browser.
GNU people never write man pages. They write info pages. That blows,
and I'd rather look at the source code to understand what it does
than install and run an info client. Fortunately, the documentation is
also available in HTML, so I go read the doc on the web. When I was
writing my build system, I was very, very glad that the make manual
was available in HTML; I spent hours on that document, with several
tabs open at various places - browsers are user-friendly. Much more
so than xterms running a rich text visualizer.
So, info2html, man2html, or SGML/DocBook source, and so on?
Well, as much as I love Unix, one aspect of it that I really dislike
is the proliferation of markup languages. nroff is one, info is
another one, pod is one, and so on; I've stopped counting the number
of initiatives aiming to produce rich text. I've always managed to
avoid learning those languages. I've only learned LaTeX and HTML;
I quickly forgot the former as soon as I was out of academia and
didn't need it anymore, and I only memorized the latter because it's
ubiquitously useful. Markup, or markdown, languages, are really
not my cup of tea; and if I didn't learn nroff in 1995, when there
actually was a serious use case for it, I'm definitely not going
to learn it today.
I'll keep providing HTML docs, and only HTML docs. If you want to
provide man pages, you're very welcome to it, as long as I don't
have to do anything. :P
Since I don't believe in the future of man pages, I even think
that only providing stub man pages would be perfectly acceptable:
in the man page, only have a link to the relevant HTML document,
on the local machine as well as on the Web.
If you don't like stubs, heinous scripts should produce more
acceptable results than you think. I try to keep a reasonably
regular format for the doc pages of executables; I don't mind
enforcing the regularity a bit more seriously if it makes your
scripts easier or more accurate.
--
Laurent
Received on Fri Aug 21 2015 - 21:34:50 UTC