Sounds good. I'll probably put some stub manpages with the link to the web as you suggest. If Debian won't stomach it, I'll then try to reformat your html in a script.
The mapping from markdown to html is quite simple. I may redo one of your pages as markdown to give you something more concrete to hate. On Fri, Aug 21, 2015 at 2:34 PM, Laurent Bercot <[email protected]> wrote: > 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 > >
