# [SciPy-dev] Accessible SciPy (ASP) project

Tue Nov 2 01:43:08 CST 2004

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