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

[Lloyd R. Prentice]

Hats off to Vlad and Dmytro!

Looks like promising work.

Thanks, guys!

Best wishes,

Lloyd

Sent from my iPad

> On Oct 2, 2016, at 6:23 AM, 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.
> 
> 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
> _______________________________________________
> 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/c52455d3/attachment.htm>