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

[Patrick Sanan]

I have slowly been doing some work to clean up the manual a little
bit, mainly just fixing the formatting where it needs attention, but
also updating the content where it is obviously out of date, so I'm
interested in working on resolving this. The latex version is of
course nice in that it can look pretty with latex tools, but the
advantage of having html documentation which is more friendly to
search engines is undeniable.

Which latex packages are giving trouble? Maybe we can figure out a way
to sufficiently reduce the dependencies.

On Sat, Jul 23, 2016 at 5:25 AM, Marco Zocca <zocca.marco at gmail.com> wrote:
> 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