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

[Barry Smith]

> On Jul 23, 2016, at 1:40 PM, Julian Andrej <juan at tf.uni-kiel.de> wrote:
> 
> 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.

   This might be possible.

   The drawback to that is markdown and friends are really limited in the types of formatting one can do.

   I like better the idea of generating nice html from latex if that is possible.

    Can you list what "certain external TeX packages used for rendering various custom aspects of the manual" chock pandoc? Maybe they can be redefined or seded out of the .tex file before passing to pandoc? Also if you can process part of the manual can you point to how it looks with pandoc so we can evaluate if it is too "ugly"?

  Thanks

   Barry




   
> 
> 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
>>