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

[Vlad Dumitrescu]

On Sun, Oct 2, 2016 at 12:23 PM, Dmytro Lytovchenko <
dmytro.lytovchenko@REDACTED> wrote:

> 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.
>

Great job, Dmytro!

* #2: it looks like there is an Erlang domain for Sphinx, don't know how
complete it is. https://pypi.python.org/pypi/sphinxcontrib-erlangdomain

* Regarding the autodoc extension, that would generate RST from edoc
comments, right?

* I'm not sure how to make sure the results are good enough. In the first
stage, there are two levels of unknowns: xml->rst and rst->html/man/pdf. I
would like to be able to test each separately, that is specifying how the
intermediary rst format will look like, taking into account the special
cases found in the xml sources (some of the xslt seems to be there to
handle such cases, but I may be wrong).


> 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.
>

One added dependency and one that is removed (xsltproc chain) give a net
result of zero. :-)

The big hurdle is that the OTP devs need to learn about the new format and
toolchain, while the old ones "just work"(tm). On the other hand, I'm not
sure how easy would be to maintain the xml+xslt sources in face of the
large-ish changes we would like to make: the git history shows only few and
minor changes done since 2009. In the end, it's their decision if a change
is worth it, and an automatic conversion xml->rst helps a lot make the
decision easier.

best regards,
Vlad


> 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/00bb37cb/attachment.htm>