[cctbxbb] Documentation .... again

[Nathaniel Echols]

On Tue, Dec 11, 2012 at 3:02 AM, David Waterman <dgwaterman at gmail.com> wrote:
> I use Google Docs/Drive for my own notes, but find it inadequate for any
> form of polished documentation. The equation editor started off well, being
> a simple text input field that rendered LaTeX markup, but they scrapped that
> for a graphical Word style editor that was an enormous step backwards in my
> opinion. It has improved slightly since then, accepting some LaTeX-like
> shortcut keys like '_' and '^' for sub- and superscript, but still lacks
> certain symbols, and the inter-operability with LaTeX that it once had.
> Also, Google has occasionally changed their Docs engine, requiring me to
> 'upgrade' my documents to the latest version, which has invariably mangled
> some of the formatting. For these reasons, much as I like Google Docs for
> convenience, I would strongly recommend avoiding it for the purpose in mind.

Point taken.  Since everyone who might contribute has SVN write access
anyway, we don't really need the added convenience.

> I briefly explored reStructuredText a while ago, but concluded that it was
> great for code blocks, but didn't have rich enough math rendering
> capabilities. Now, revisiting the documentation I wonder if I was wrong? I
> would like to be able to do vectors and matrices, equation arrays with
> control over which lines are numbered, and labels to refer to equations in
> the text. If this is covered easily by reStructuredText then I nominate it
> as a serious contender.

Well, it does support embedded LaTeX equations:

http://docutils.sourceforge.net/docs/ref/rst/directives.html#math

But I suspect it is much less flexible than what you're asking for.
So I guess we need to decide whether we want/need to include equations
in the tutorial, or just code - if the latter, then RST will suffice,
otherwise I have no objection to using LaTeX.  (Actually, since we
already have a BibTeX bibliography started, that's a very appealing
option.)

-Nat