Actually, apparently HTML is the preferred format, so we're good. https://www.debian.org/doc/debian-policy/ch-docs.html#s12.4
On Fri, Aug 21, 2015 at 3:57 PM, Buck Evan <[email protected]> wrote: > 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 >> >> >
