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

[Fred Youhanaie]

I use pandoc on regular basis. Mainly to convert saved html files, blogs/articles, to epub, then from epub to mobi (Kindle) via calibre.

It uses an intermediate internal format, so one only needs to write input/output converters for each format.

Works well, written in Haskell - Erlang's Cousin ;-)

Cheers,
f.

On 27/09/16 17:58, lloyd@REDACTED wrote:
> I haven't used it yet, but Pandoc looks promising.
>
> http://pandoc.org/
>
> Best to all,
>
> LRP
>
> -----Original Message-----
> From: "Kenneth Lundin" <kenneth@REDACTED>
> Sent: Tuesday, September 27, 2016 5:08am
> To: "Loïc Hoguin" <essen@REDACTED>
> Cc: "Lukas Larsson" <lukas@REDACTED>, "erlang-questions@REDACTED" <erlang-questions@REDACTED>
> Subject: Re: [erlang-questions] Erlang documentation -- a modest proposal
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
> 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
>>
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>