[petsc-users] [RFC] Docs: TeX -> HTML

[Marco Zocca]

Dear all,

  following the discussion at PETSc'16, I have tried to render the
TeX-based manual into HTML with latex2html [1] and pandoc [2] .

Neither attempt was successful, because of the presence of certain
external TeX packages used for rendering various custom aspects of the
manual.

There is no 1:1 way of converting such a document. However there are a
number of templates for rendering static websites that use LaTeX math
and verbatim source code (e.g. readthedocs [3] for manual-type
documents, which also supports MathJax [4] and re-renders at every
repository push).

At any rate, the conversion requires copying blocks of text and code
to the web-based version, i.e. removing all the LaTeX markup,
therefore effectively committing to maintaining 2 versions of the
manual up to date and in sync with each other.


Before committing to any approach, I would like your input on this:

1) Do you have any preference for web rendering/site hosting solution?

2) Are you OK with the idea of essentially forking the manual into PDF
output and web output ? It is not huge work (an afternoon of tweaking
initially and a couple minutes at every new release) but we should be
sure about the approach in the first place.

Any and all feedback is welcome;

Thank you and kind regards,
Marco


[1] https://www.ctan.org/tex-archive/support/latex2html/
[2] http://pandoc.org/
[3] https://readthedocs.org/
[4] http://mathjax.readthedocs.io/en/latest/tex.html