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 <buck_at_yelp.com> 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 <ska-skaware_at_skarnet.org>
> wrote:
>
>> 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 - 23:03:04 UTC