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

[Julian Andrej]

Small suggestion (it also came up at the Meeting)

What is the opinion on a "main" documentation in markdown/restructured
text or something like that? The conversion from one of these formats
into pdf or any other format like html is handled by a variety of
tools pretty well.

On Sat, Jul 23, 2016 at 8:23 PM, Barry Smith <bsmith at mcs.anl.gov> wrote:
>
>    Marco,
>
>     Every rending I've seen of nontrivial latex documents to HTML looks dang ugly in HTML and is extra work to maintain (despite the poor quality). We've tried a couple of times with PETSc to keep an HTML version going and gave up both times.
>
>     I don't like the idea of having two copies of the same thing, we'd never keep them in sync nor do I like the idea of ugly HTML pages.
>
>     The one drawback of just having a PDF manual IMHO is that we cannot currently link directly to bookmarks inside the users manual from, say, a manual page html file. (Bookmarks inside the manual.pdf to other places inside the manual.pdf do work fine). The solution seems to be to use Adobe #nameddest=destination instead of bookmarks. These can be added in latex with \hypertarget{} for example \hypertarget{ch_performance} and then in the browser http://www.mcs.anl.gov/petsc/petsc-current/docs/manual.pdf#nameddest=ch_performance will jump to the correct place. This works with the current chrome but does not work with the current Apple Safari (arg) and if you google nameddest doesn't work you find that often browsers seem to have this broken. If it wasn't so broken I would have (automated) adding all the hypertargets and the manual and augmented all the manual pages to have links to them. Still tempted but it seems they won't work except with Chrome (maybe firefox if properly configured). The problem of badly supported #nameddest goes back 10 years
>
>
>   Barry
>
>
>
>
>
>
>> On Jul 23, 2016, at 4: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
>