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

[Vlad Dumitrescu]

Following the call for doing something rather than talking about it, I went
on looking a little at the docs in more detail (to see if there is some
low-hanging fruit) and I have a few comments and questions.

The generated HTML can be improved by making it HTML5. This means that it
would have more semantic tags and structure, closer to the original XML.
This would make it easier to consume the HTML in other tools (are there
any? I do it in erlide, if the XML sources aren't available) and also to
write reasonably simple CSS for it. On the other hand, if tools already use
the HTML, they would need to use different parsers for different OTP
versions...

As the HTML looks today, it is basically impossible to style nicely. For
example: the html contains formatting-related tags (<center>) and class
names (bold_code); lists look alike (no classes nor ids); enumerations
aren't structured as lists nor are they structured (the functions in a
module are just a sequence of <p> with some of them having certain classes,
for example); headers are not always hierarchical.

Would that be something useful to look at and improve? It's not as useful
as improving the content, but it can improve the reading experience.

I saw someone suggesting AsciiDoc. That is a nice language, better than
Markdown. I don't know how inclined the OTP team is towards replacing the
XML sources, but I believe that an example of a page would help a lot.

I will try to convert a module's docs to "better" HTML and AsciiDoc, let's
see what that gives!

best regards,
Vlad
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160926/7577a049/attachment.htm>