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

[Vlad Dumitrescu]

Hi,

A short status update. I've spent a couple of evenings looking at the
details for how to make the HTML documentation a little better structured,
so that it can be styled.

The good news is that it's relatively easy to tweak the XSL and get the
HTML that we want. On the other hand, it is a single XSL stylesheet that
handles not only the reference documentation (which I was targeting
foremost), but also everything else (user guides, etc). This requires a bit
more thought and discovery by trial and error, as it is easy to get an
unexpected result in a part that is only present in few places (and
browsing all documentation after every change is not feasible). Debugging
XSLT is difficult, I discover.

Styling the docs just for improving the artistic experience is probably not
a priority, but what would be useful is to make the pages mobile-friendly
and make it possible to filter out parts that are not relevant at the
moment. Most of this can be done in smaller steps, with the downside that
the XSLT will probably become spaghetti; or with a larger scope, convert
the template to HTML5 and make it more modular (easy to maintain), with the
downside that there is a bit longer start-up time.

The latter option brings also up a topic discussed here before: is XSLT a
technology for the future? IMHO the only argument in its favour is that it
works now and there is a *lot* of XML sources that depend on it. What I
have difficulty estimating is if the amount of work needed to modify and
maintain the existing templates might be in the same region as the one
needed to convert the sources to a format for which there are already
templates (asciidoc and restructuredText were mentioned). I really don't
know, but what I know is that I wouldn't want to do the first and then
scrap it and do the second.

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