[SciPy-dev] Accessible SciPy (ASP) project
eric at enthought.com
Mon Nov 1 14:20:45 CST 2004
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
> progress has been made in the last 1.5 years in docutils with this
> 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.
> - 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
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
> 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
> 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.
More information about the Scipy-dev