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

[Loïc Hoguin]

On 09/27/2016 09:44 AM, Kenneth Lundin wrote:
> Man pages or not?
> -------------------------
>
> I understand that some of you are using the man pages. But the question
> is why are you using them?
> Is it because it is easy to type "man lists" or "erl -man lists"? What
> if "erl -man lists" pops up in a web-browser window of you choice
> instead?, Note that it is exactly the same information shown in the
> lists.html and in the man page for lists.

It would be terrible for many reasons:

* lack of search; command line manual search is very useful (man -k and 
others)
* man pages are readable in 80x24 windows; browsers aren't
* opening in a separate window is awkward; currently I need to do this 
to have what I need: Menu key (opens a terminal), "man lists"; with what 
you suggest I need at least a couple more steps
* if i want to have the manual side by side with the code, I need a 
different browser or browser window; I already fight with Dialyzer 
because it runs out of memory on some modules, I don't need the waste 
browsers add on top of that

Also note that in the absence of man pages, I'd look first into 'info' 
or PDF formats before I consider local HTML. HTML is just not practical 
for manuals.

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.

-- 
Loïc Hoguin
http://ninenines.eu
Author of The Erlanger Playbook,
A book about software development using Erlang