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

lloyd <>
Tue Sep 27 18:58:46 CEST 2016

I haven't used it yet, but Pandoc looks promising.


Best to all,


-----Original Message-----
From: "Kenneth Lundin" <>
Sent: Tuesday, September 27, 2016 5:08am
To: "Loïc Hoguin" <>
Cc: "Lukas Larsson" <>, "" <>
Subject: Re: [erlang-questions] Erlang documentation -- a modest proposal

erlang-questions mailing list

On Tue, Sep 27, 2016 at 10:39 AM, Loïc Hoguin <> wrote:

> 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)
I don't think the search has to be worse in the html form, it depends on
how we do it.

> * 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.

> * 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.

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.

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

Interesting would be to know how many % of the users that actually are
using the man and pdf pages.

/Kenneth, Erlang/OTP Ericsson

> --
> Loïc Hoguin
> http://ninenines.eu
> Author of The Erlanger Playbook,
> A book about software development using Erlang
> _______________________________________________
> erlang-questions mailing list
> http://erlang.org/mailman/listinfo/erlang-questions

More information about the erlang-questions mailing list