Re: skaware manpages?

From: Buck Evan <buck_at_yelp.com>
Date: Fri, 21 Aug 2015 15:57:03 -0700

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 - 22:57:03 UTC