[moose] Some notes on the user documentation format

[Niraj D. <ni...@nc...>]

Dear all,

I'm sending this mail to kick off activity on the developer's mailing
list. For now, I'm also CC'ing members of the core team, until we can see
that it is working.

This mail concerns the file format we're using for our documentation
(Emacs' org-mode), and suggests that Markdown may be a better choice. This
is a low level issue, with low importance, but your thoughts are welcome.

----------------------------------------
Issues faced with Emacs Org-mode format.
----------------------------------------

I faced a few minor issues with user-documentation files, which are
encoded in Emacs Org-mode, and thought I'd share. I also mention below
that it may be worth considering switching to Markdown -- thoughts
welcome.

  - 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 HTML files produced work just fine from the local machine, but
were causing the Apache webserver to get confused, and only a blank page
would load. The fix is very simple: One needs to remove the first line
from the HTML, which basically says that this is an XML file. Minor issue,
mentioning for future reference.

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

Thanks,
Niraj

[*]
http://emacs-fu.blogspot.in/2011/04/nice-looking-pdfs-with-org-mode-and.html