[SciPy-dev] Accessible SciPy (ASP) project

[Fernando Perez]

Travis Oliphant wrote:
> I should chime in here on SciPy documentation, as I am trying to set-up 
> a system that would allow users to contribute documentation to Python in 
> a more fluid manner.
> 
> First of all,  tools such as LyX and TeXMacs make the LaTeX-is-too-hard 
> line out of date.    LyX for example is not hard to use to write 
> documentation.  Native binaries are available on Windows.    People who 
> still flounder in raw LaTeX have just not made use of the more useful 
> front ends.

+1

I'd like to encourage others to have a second look at lyx as a potentially 
good compromise.  Here are some of lyx's strengths for a project like this one:

- It provides a very good GUI environment where users of traditional word 
processing software will probably feel quite comfortable right off the bat. 
It is possible to generate Latex, PostScript, PDF and HTML straight from lyx's 
GUI without having to know a single Latex command.  Knowing latex can 
certainly help in fine-tuning output for complex tasks, but it is not 
necessary for most normal needs.

- Existing latex users, when in math mode, can still type \alpha and things 
work as usual (lyx does NOT impose the use of a gui click panel for building 
equations, though it provides one if desired).  I grant that hardcore latex 
users who run a latex compiler in their head as they write may find it a bit 
limiting, but hopefully not to the point of driving them away.

- Since its internal format is plain text, the usual dangers and annoyances of 
binary document formats like .doc (CVS management, easy corruption, 
diff/grep/etc hostile,...) are just not there.

- There is an excellent bibliography management tool, incidentally written in 
python (pybliographic) which integrates very well with it.

- It runs on the Unices, OSX (both via fink and as a native Aqua app) and Win32.

- It's free.

- It has all the known benefits of latex, which I'd argue go well beyond 
mathematical typesetting.  For writing complex documents, the phenomenal 
structural robustness of latex (cross-referencing, numbering, bibliographies, 
tables of contents, etc...) should not be underestimated.

- It makes some of latex's more annoying aspects a non issue: tables and 
figures.  Adding/formatting tables in lyx (unless you want a lot of 
fine-tuning) is trivial, as is including figures setting all kinds of options 
for them.

- It also has DocBook support, but I can't vouch for it, since I've never used it.

I have been using lyx exclusively for all my documents since about 1998, with 
much success.  While it's not necessarily what everybody would want to use for 
their daily activities, perhaps it can provide a good compromise tool which 
satisfies most of our needs.

Incidentally, ipython's documentation is all written using lyx, and the 
setup.py file automatically generates PDF and HTML for distribution from the 
sources.

Note that the manual includes large sections which are auto-generated from 
python files and ipython's docstrings (the whole magic section is pulled from 
the docstrings).  While ipython's manual has no equations, it's still a 70 
page document which shows what the tool can do in this context.

> With that said,  I agree with Eric that we should worry less about a 
> standard and more about the actual documentation.     I also agree that 
> there are multiple documents to be produced and these may use multiple 
> formats.

I completely agree with this.  If a tool is chosen it can be publicized as a 
suggestion for contributors, but with a clear statement that any format is 
ultimately welcome.

Best,

f