[cctbxbb] Documentation .... again

David Waterman dgwaterman at gmail.com
Tue Dec 11 03:02:31 PST 2012


I would be happy to contribute in any way that I can, though that might be
more reading, testing and commenting on documentation rather than producing
new pieces for 'core' cctbx tasks.

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.

Some form of simple and concise markup language seems most appropriate. I
use LaTeX, but arguably it fails on both of these requirements. Also, the
mess of packages on CTAN, many of which are mutually incompatible, make
portability and concatenation of documents a real pain. Some of the obscure
documentation for these packages really makes advanced LaTeX use feel like

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.


-- David

On 11 December 2012 09:33, Luc Bourhis <luc_j_bourhis at mac.com> wrote:

> Hi Pavel,
> I agree 100% with everything you said.
> I have zero experience with Google Docs, so these couple of questions are
> rather out of my ignorance. Does it allow to 1) insert formulas, 2) put
> pieces of code that can be extracted automatically for exercising ?
> I would recommend using ReStructureText as we did for the Comp. Comm. news
> letter and put the file on our Sourceforge repo of course.
> Best wishes,
> Luc
> _______________________________________________
> cctbxbb mailing list
> cctbxbb at phenix-online.org
> http://phenix-online.org/mailman/listinfo/cctbxbb
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20121211/850236d0/attachment.htm>

More information about the cctbxbb mailing list