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

[Matthew Knepley]

On Sat, Jul 23, 2016 at 8: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.


1) I am really opposed to two copies of the source. This never works out.

2) My reservation concerning Markdown is that it is so constricted. I am
used to the freedom of TeX. I
    agree that this is not a definitive argument.

   Matt


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



-- 
What most experimenters take for granted before they begin their
experiments is infinitely more interesting than any results to which their
experiments lead.
-- Norbert Wiener
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-users/attachments/20160723/ae5a4179/attachment-0001.html>