On 21/08/2015 22:10, Buck Evan wrote:
@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