<div dir="ltr"><div><div><br></div></div><div class="gmail_extra"><div class="gmail_quote">On Sun, Oct 2, 2016 at 12:23 PM, Dmytro Lytovchenko <span dir="ltr"><<a href="mailto:dmytro.lytovchenko@gmail.com" target="_blank">dmytro.lytovchenko@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div><div><div><div><div><div><div><div><div>Here tonight I have experimented with XSLT which generates man pages and made it produce RestructuredText instead:<br></div>It is not perfect, but i have cut my time at 6 hours and here's the result.<br><a href="http://imgur.com/3kbecSI" target="_blank">http://imgur.com/3kbecSI</a> (using 'classic' template, output has Man page sections because it was based on man page XSLT)<br><a href="http://imgur.com/7IFr30X" target="_blank">http://imgur.com/7IFr30X</a><br> 

<br></div>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).<br><br>It produces still erlang.3 man file which is RST inside (did not bother to modify the Makefile yet)<br><br></div>My offer was to take this in stages:<br><br></div>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.<br></div><div>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.<br></div><div></div>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.<br></div>4. Restyle. Add javascript to show/hide examples, etc. This is done by Sphinx templating and is much easier than XSLT (1.0 bah!).<br></div>5. Enjoy the pleasure of editing RestructuredText.<br></div></div></div></blockquote><div><br></div><div>Great job, Dmytro! <div><br></div><div>* #2: it looks like there is an Erlang domain for Sphinx, don't know how complete it is. <a href="https://pypi.python.org/pypi/sphinxcontrib-erlangdomain" target="_blank">https://pypi.python.org/pypi/<wbr>sphinxcontrib-erlangdomain</a></div><div><br></div><div>* Regarding the autodoc extension, that would generate RST from edoc comments, right?</div></div><div><br></div><div>* 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).<br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">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.</div></blockquote><div><br></div><div>One added dependency and one that is removed (xsltproc chain) give a net result of zero. :-)</div><div><br></div><div>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. </div><div><br></div><div>best regards,</div><div>Vlad</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="gmail_quote"><div><div class="m_-4866765073234884003gmail-m_3469612759418733611gmail-h5"><div dir="ltr">sön 2 okt. 2016 kl 11:31 skrev Vlad Dumitrescu <<a href="mailto:vladdu55@gmail.com" target="_blank">vladdu55@gmail.com</a>>:<br></div></div></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div class="m_-4866765073234884003gmail-m_3469612759418733611gmail-h5"><div dir="ltr" class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">Hi,</div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"><br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"></div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">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.</div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"><br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"></div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">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.</div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"><br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"></div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">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.</div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"><br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"></div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">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. </div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"><br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"></div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">best regards,<br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"></div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">Vlad</div><div class="gmail_extra m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"><br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg"></div></div></div></div><span class="m_-4866765073234884003gmail-m_3469612759418733611gmail-">
______________________________<wbr>_________________<br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">
erlang-questions mailing list<br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">
<a href="mailto:erlang-questions@erlang.org" class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg" target="_blank">erlang-questions@erlang.org</a><br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg" target="_blank">http://erlang.org/mailman/list<wbr>info/erlang-questions</a><br class="m_-4866765073234884003gmail-m_3469612759418733611gmail-m_-7038370367043096135gmail_msg">
</span></blockquote></div>
</blockquote></div><br></div></div>