[cctbxbb] Documentation .... again

[Graeme.Winter at diamond.ac.uk]

+1 for latex

Certainly for DIALS much mathematics will be needed in the documentation. That said, since RST to Latex is a doable transformation there is no need to "choose one." I also like the way Latex deals with images...

Cheerio,

Graeme

-----Original Message-----
From: cctbxbb-bounces at phenix-online.org [mailto:cctbxbb-bounces at phenix-online.org] On Behalf Of Nathaniel Echols
Sent: 11 December 2012 16:23
To: cctbx mailing list
Subject: Re: [cctbxbb] Documentation .... again

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
_______________________________________________
cctbxbb mailing list
cctbxbb at phenix-online.org
http://phenix-online.org/mailman/listinfo/cctbxbb

-- 
This e-mail and any attachments may contain confidential, copyright and or privileged material, and are for the use of the intended addressee only. If you are not the intended addressee or an authorised recipient of the addressee please notify us of receipt by returning the e-mail and do not use, copy, retain, distribute or disclose the information in or attached to the e-mail.
Any opinions expressed within this e-mail are those of the individual and not necessarily of Diamond Light Source Ltd. 
Diamond Light Source Ltd. cannot guarantee that this e-mail or any attachments are free from viruses and we cannot accept liability for any damage which you may sustain as a result of software viruses which may be transmitted in or with the message.
Diamond Light Source Limited (company no. 4375679). Registered in England and Wales with its registered office at Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire, OX11 0DE, United Kingdom