[SciPy-dev] Accessible SciPy (ASP) project

[Perry Greenfield]

On Nov 1, 2004, at 3:20 PM, eric jones wrote:

> Pearu Peterson wrote:
>
[...]
>>
>> - different output formats are possible: PDF, HTML, PS,..
>> - native math markup support
>
> The math is the real advantage of LaTeX.
>
This really is the hard part of the decision of which to use.

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

I have to say that I found trying to use the Python documentation 
system a horror
(very brittle and hard to maintain). Then again, I'm probably stupid. 
Still, after
doing a few that way, I would definitely want to avoid using that.

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

On the other hand, LaTeX's strength is equations. I don't think any of 
the other common
tools comes close to it for either ease of use (gui equation editors 
are imho far more
painful to use). But that is really about its only strength. Tables are 
a nightmare in
TeX/LaTeX (and far easier with GUI's!). And it seems to me that tables 
are pretty painful
with ReST. Sure, visually they look ok in the ASCII, but editing them 
is a major pain
(not that I've used it for that, but it sure looks that way).

So none of the tools does everything easily. Undoubtedly LaTeX is 
arcane for many.

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

In the end I would agree, provided that embedding LaTeX for math is 
permitted. Even though
it won't be needed by most documents (thus many may never need to deal 
with it), I think
it is essential to be able to have math in the document. So my 
preference would be

1) ReST (with embedded LaTeX for math)
2) OO
3) Pure LaTeX
4) MS Word
...

Perry