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

[Kenneth Lundin]

On Tue, Sep 27, 2016 at 1:03 PM, Martin Karlsson <
martin@REDACTED> wrote:

> Hi guys,
>
> > Interesting would be to know how many % of the users that actually are
> using the man and pdf pages.
> The man pages is the erlang documentation I use the most. In fact I Iike
> them so much I had to reply to this thread to reduce the risk of them going
> away :). They are much quicker than anything if you have a console based
> work-flow. I even miss the man pages for all external libraries. I would
> love if there was a common erlang documentation system making it easy for
> external libraries to produce the same style and type of documentation as
> the official documentation.
>

erl_docgen included in OTP is such a toll with which you can build
documentation in the same style as the official one. Of course the
documentation for erl_docgen itself could be improved as well:) But we are
using it for the
OTP documentation and the intention has always been that it can be used for
the users applications as well.


> I am not overly attached to a documentation system but there are a few
> that does conversion to lots of formats with good quality, for example
> sphinx which can generate html, latex, man pages, epub among others.
>
> A final comment regarding html generated documentation. Please don't rely
> on javascript for more than enhancing the experience. I see lots of modern
> html documentation which doesn't display all data (for example code
> examples) or can't do navigation without javascript.
>
> Cheers,
> Martin
>


> /Kenneth Erlang/OTP , Ericsson
>
>
>
> _______________________________________________
> 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/4b8a7e49/attachment.htm>