Re: [moose] Some notes on the user documentation format

[Subhasis R. <ray...@gm...>]

>   - I tried exporting to PDF, and the PDF was quite garbled up. Apparently
> this is common, and there are alternatives[*] which are supposed to give
> clean PDFs, but they look quite involved. For now I've printed the HTML ->
> PDF manually, for putting up on the site, like Chaitanya suggested.
>

The PDF export works via LaTeX and it was getting confused by non-standard
equations/syntax. These are now fixed in the moose repository. Also, I
suspect that markdown to PDF export may have similar issues with complex
equations.

  - I've seen the 'Markdown' format (similar to Org-mode) mentioned a lot,
> and also the 'reStructuredText' format. Of the three, Markdown seems to be
> the most widely adopted. Also, it will be nice to create HTML and PDF
> output from a script, so that the website can be automatically updated.
> Since Org-mode seems to be mainly tied to Emacs, not sure how simple it is
> to do this. Finally, even though the Org-mode format is already very
> simple, I find Markdown to be the simplest of the 3.
>
> Nothing pressing, and certainly not worth putting in the effort to
> manually re-encode the existing docs. If the need is felt, and if Org-mode
> -> reST/Markdown conversion tools work well, we can consider.
>
> There several conversion tools: pandoc [http://johnmacfarlane.net/pandoc/]
and orgmode-markdown [https://github.com/alexhenning/ORGMODE-Markdown] seem
to be functional.

Major disadvantages of org-mode are (1) it is tied to emacs and (2) it
requires a bit of configuration to be able to export to various formats.
While it is an extremely powerful system (you can even write code snippets
and insert the result of its evaluation into the same document - which can
be useful for interactive tutorials), all that may be an overkill for our
purpose.

The other plain-text formats are definitely worth a look.

- Subhasis