[SciPy-dev] Accessible SciPy (ASP) project

[eric jones]

Pearu Peterson wrote:

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

Regardless of tool, people can start write now.  Send in any document, 
and we'll get it coordinated into the final choice.

> - it is available everywhere

OO and ReST both pass this -- and much better I might add.

>
> - different output formats are possible: PDF, HTML, PS,..
> - native math markup support

The math is the real advantage of LaTeX.

> Disadvantages:
> - Eric dislikes it :)

LaTeX is dearly beloved by academics.  It produces beautiful output for 
math markup.  Several of you are very familiar with it.  These are all 
very good points.

My dislike is not without reason.  LaTeX has a steep learning curve.  
The tool chain requires time to learn.  I have watched many people learn 
and curse LaTeX as a grad student.  I just talked to a (smart) guy on 
Friday writing his Masters thesis, and he was struggling with LaTeX, so 
things have changed markedly.   I have worked with and met many more 
people in the course of school and work that are much more comfortable 
with other tools.  The entire group I worked with as a post-doc at Duke 
(27 post-docs and grad students) used Word for all of their techinical 
papers full of equations.  I don't say all this to say LaTeX sucks.  It 
doesn't.  But it does appeal to a fairly narrow niche of people, and, 
even in academia it is loosing market share as people move on to more 
user friendly tools (if less capable).

Other data points.  There was really one person that could build and 
maintain the LaTeX version of the Python docs consistently(Fred Drake).  
Did you ever try building it on Windows (even with MikTeX)?  I'm sure it 
is possible, but I gave it up as not worth the effort a couple of years 
ago.  Bruce Eckel has proven time and time again that Word is a 
reasonable platform for generating photo ready books.  As I remember, 
Alex Martelli used Word for Python in a Nutshell.  David Beazley started 
"Essential Python" in LaTeX and then abandoned it because the publisher 
couldn't deal with it.  I think he ended up using some simple ad-hoc 
formatting scheme (sorta like ReST). 

The big difference, of course, is that none of these use equations as 
much as SciPy docs.  In reality though, we need a lot more prose than we 
need equations, and imposing the LaTeX overhead on people just seems 
overkill.   Looking at the Matlab docs, 70-90% of the docs I looked at 
on their website didn't have any equations in them -- only prose, code 
snippets, and screenshots of plots.  I really want to maximize the 
potential of getting people to contribute this sort of thing and don't 
think LaTeX does that. 

I also don't think the list of people compotent to document SciPy is 
small, so saying that knowing/learning LaTeX is a useful filter for 
screening contributors is wrong to me.  In fact new users are probably 
the best people to document the function set because they know what 
aspects tripped them up.

Another consideration is, our infrastructure for technical writing at 
Enthought continues to grow.  We would love to help coordinate and 
contribute to the effort, but LaTeX isn't really part of our toolset.  
Word, OpenOffice, and RoboHelp are.  ReST is starting to be used more 
and more also.  We are funding David Goodger to get DocUtils further 
along.  Depending on how this goes, ReST may become even more of a tool 
for us.  Using one of these tools makes it much easier for us to 
technical writers here involved in the process.  I did just ask Janet 
Swisher about this, and she did say that she'd be willing to work with 
LaTeX if need be.  So choosing it isn't a show stopper, just a 
slower-downer...
 
If OpenOffice were a palitable solution for everyone, it would be my 
preference for the "users guide" with ReST used for the reference 
manual. People don't like OO though, so ReST seems like a reasonable 
alternative that minimizes the learning curve, simplifies the authoring 
process, and works easily on most platforms.  I think it is a better 
option than LaTeX.  If ReST can't currently do any equations at all, 
then that is a real limitation that would need to be overcome.  Perhaps 
incorporating the Python code from Matplotlib that interprets LaTeX math 
strings into DocUtils should be a goal to solve this??  In the meantime, 
we could just have the latex code there without it being interpreted.

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

The same can be said for many parts of LaTeX on many accounts (usability 
as the primary one).  OpenOffice does a pretty good job on the usability 
side and "well enough" for equations.  If you are going to write a 
mathematics thesis, this would be wrong.  But, if we only need equations 
"occasionally" as suggested by Matlab's docs, then it would do the job fine.

I can't imagine people haven't written docs because of a format issue.  
Travis' documents are all in LaTeX and checked in.  Weave has its 
original docs in Word.  People can write the prose in anything at the 
moment, and it will get incorporated into the final product.

Perhaps the decision should be made on the following.  The first person 
to generate 100 pages of new documentation in any format gets to pick 
the format. :-)  Also, I'd be happy to continue a policy of "send in 
docs in whatever you want, we'll coordinate the final product" to 
maximize the chance of contributions.

For the final format, I still vote for (1st) ReST or (2nd) OO.

eric