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

[Kenneth Lundin]

On Tue, Sep 27, 2016 at 10:39 AM, Loïc Hoguin <essen@REDACTED> 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
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160927/3d713ec1/attachment.htm>