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

[Dmytro Lytovchenko]

Here tonight I have experimented with XSLT which generates man pages and
made it produce RestructuredText instead:
It is not perfect, but i have cut my time at 6 hours and here's the result.
http://imgur.com/3kbecSI (using 'classic' template, output has Man page
sections because it was based on man page XSLT)
http://imgur.com/7IFr30X

It is using python function markers, so it ignores arity and args just
takes the function name, i am able to link to specific functions and types
(this works across whole documentation project, if i'd have more than 1
file).

It produces still erlang.3 man file which is RST inside (did not bother to
modify the Makefile yet)

My offer was to take this in stages:

1. Add a RST target XSLT (taking my POC as a base or not), generate
temporary RST files into a temporary project and build HTML, PDF, man (also
Sphinx offers epub format) without affecting original docs, and keep
working to make it better.
2. Work on XSLT until it produces desired results. Add new entities to
Sphinx with Erlang funcs/types support (includes some Python scripting).
Sphinx also can do autodoc (i.e. refer into existing modules for some doc
pieces), possibly we can shift complex postprocessing ERL/BEAM files to a
shorter Python script reading from them.
3. When the output is good enough, scrap the XML and XSLT. XSLT is bad,
XSLT 1.0 is even worse. It lacks many features of modern XSLT and both of
them are pain to edit. From then on RST and module edoc will contain the
primary source of documentation. From here we can edit RST manually instead
of generating it -- this is better control over the output.
4. Restyle. Add javascript to show/hide examples, etc. This is done by
Sphinx templating and is much easier than XSLT (1.0 bah!).
5. Enjoy the pleasure of editing RestructuredText.

The screenshot how it may look is here: http://imgur.com/3kbecSI
http://imgur.com/7IFr30X Using template 'classic'
The branch is here https://github.com/kvakvs/otp/tree/xslt-sphinx-rst
The diff with master is here
https://github.com/erlang/otp/compare/master...kvakvs:xslt-sphinx-rst?expand=1
Sphinx project (a simple Makefile and conf.py are not included).

P.S .I am not going into dragon realm of "not invented here" and "it
introduces a dependency". Well, yes, yes it does, it passes the task to a
better tool, which is designed to build documentation.

sön 2 okt. 2016 kl 11:31 skrev Vlad Dumitrescu <vladdu55@REDACTED>:

> 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
>
> _______________________________________________
> 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/20161002/a22883b3/attachment.htm>