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 <[email protected]> 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 <[email protected]> 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 >
