[SciPy-dev] Accessible SciPy (ASP) project

[Pearu Peterson]

On Sun, 31 Oct 2004, eric jones wrote:

> Pearu Peterson wrote:

>> As I have understood from earlier discussions that LaTeX may scare people 
>> away from writing documentation for Scipy. But let me ask may be a bit 
>> harsh question: are these people able to produce good quality technical 
>> documentation for Scipy if they reject to learn LaTeX basics? Afterall, 
>> LaTeX is not that difficult to use, especially when we can provide 
>> documentation templates to get started easy, and there are nice LaTeX 
>> frontends available for Windows as well.
>
> Of the two options, ReST is much more preferable to me.  I, and many others, 
> use Word as my primary documenting tool and dislike LaTeX very much.  Of the 
> open options, I (and many others) would be most comfortable in OpenOffice. 
> However, I also think that ReST has many benefits (better diffs in a code 
> repository, editable in any editor, etc.) that are compelling.  Imposing the 
> LaTeX learning curve and infrastructure requirements on would-be contributors 
> is too limiting in my opinion.  So, of the imperfect solutions, ReST seems 
> the most palatable to the most people.

>From reviewing ReST LaTeX capabilities again I must admit that only little 
progress has been made in the last 1.5 years in docutils with this 
respect.

If we would start using ReST right now then including math in 
documentations would require hackish solutions (raw::latex and mathhack).
I am not sure that 'would-be contributors' (that's a pretty abstract term
considering the urgent need for scipy documentations, imho) would 
accept that path either.

The main advantages of using LaTeX are
- documentation writers could start right now without worrying that the
   tool will change in future
- it is available everywhere
- different output formats are possible: PDF, HTML, PS,..
- native math markup support
Disadvantages:
- Eric dislikes it :)

Btw, I have found that learning ReST is no way simpler than learning 
LaTeX. ReST is still in flux while LaTeX has been stable for 
decades. And setting up infrastructure for LaTeX is not that difficult. 
Google:"latex windows" gives lots of helpful step-by-step instructions.

I have a feeling that if ReST inline support does not improve soon 
and we cannot decide which tool to use then there will be no Scipy docs 
available for other years to come. I am incling to reject 'would-be 
contributors' for the sake of being able to start writing Scipy docs
immidiately.

And last note about OpenOffice: to put it short then it's 
even elementary formula support sucks, pardon my language.

Pearu