[erlang-questions] Erlang documentation -- a modest proposal

[Richard A. O'Keefe]

On 27/09/16 10:08 PM, Kenneth Lundin wrote:
>     * lack of search; command line manual search is very useful (man -k
>     and others)
>
> I don't think the search has to be worse in the html form, it depends on
> how we do it.

I don't want to have to depend on how *you* do it.
It *will* be worse *until* you do something about it,
and you already have copious demands on your time.

>
>     * man pages are readable in 80x24 windows; browsers aren't
>
> Have you tried lynx? a text based web-browser I think our html pages
> looks quite good in that one.

Guess what?  lynx doesn't come standard with OSX.
Oh GOODY!  Just what I needed!  In order to read documentation,
I have to install a NEW tool different from everything else I use
to read documentation!  WOW!  Fantastic!
/sarc

Seriously, I mean *really* seriously, every system I use
(Solaris, Linux, OSX, Cygwin) comes with man.  I'm using it all
the time.

If I want a hypertexty thing that works in a terminal window
or in a certain powerful text editor, there's info.  I don't
use that _all_ the time, but I use it a _lot_ more than Lynx.
Info actually came on all the systems I use, possibly as part
of something else, but I didn't have to go and get it.


>     I'm also wondering why the intent to remove man/PDF formats. They're
>     already working, it doesn't sound like they would need much
>     maintenance to be kept, they have users, so why consider removing
>     them? It doesn't make much sense to me.
>
>
> html, pdf and man are 3 different backends for generating documentation
> of course it will cost more to maintain and develop 3 backends instead
> of 1 or 2. This is especially true if new features are introduced in the
> document source format or if we even change the format completely.

This is a very strong argument in favour of keeping the document source
format simple and not getting too fancy with the output.

Of course, the claim that the current HTML pages look good in Lynx
ceases to be relevant if the generated HTML is changed much.

I pointed out to my concurrent programming students yesterday the
need for protocols to be versioned, and specifically pointed to HTML
as something that used to get this right (the doctype line said
which version of HTML a document was intended to be in) where that
has been lost for entirely bogus reasons.  HTML5 doesn't have a DTD,
so the doctype line no longer has *any* form of version information
in it, which would be fine if HTML was now frozen for all time, but
it isn't.  It is still advisable not to get too fancy with the HTML
you generate.  (Does Lynx support all of HTML5?  Thought not.)

The argument for markdown or asciidoc is that they have lots of
back ends that other people are maintaining.  ronn(1)
https://rtomayko.github.io/ronn/ronn.1.html
for example converts a dialect of Markdown to man pages or HTML.
https://github.com/rtomayko/ronn#readme
offers an argument for retaining man pages.
pandoc can also generate man pages, HTML, or PDF from Markdown.

>
> But this is just a possibility (to remove formats that are not so much
> used) , no decision is taken.

Take the existence of man pages as an incentive to focus on content
rather than flashy images.  Form liberates!

I have noticed a common tendency for people to abuse the principle
of mediocrity:

    [Someone tasked with cooking a meal] I am not hungry,
    so nobody is hungry.

    [Someone tasked with supporting Haskell] I do not use Windows,
    so it is not important to support Haskell on Windows.

    [Someone tasked with documentation] I do not use man any more
    so nobody needs man any more.