[SciPy-dev] Accessible SciPy (ASP) project

[Prabhu Ramachandran]

>>>>> "EJ" == eric jones <eric at enthought.com> writes:

    EJ> Pearu Peterson wrote:
    >> The main advantages of using LaTeX are
    >> - documentation writers could start right now without worrying
    >>   that the
    >> tool will change in future

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

    >> - it is available everywhere

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

I agree with the general pragmatic viewpoint that docs should be
accepted regardless of the format and LaTeX should not be a filter.  I
can't agree with this sentiment that OO and reST are better than
LaTeX.  The answer to what tool is better depends on what you want to
do.  I would not write a paper/thesis in anything but LaTeX.

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

    EJ> The math is the real advantage of LaTeX.
[...]
    EJ> LaTeX is dearly beloved by academics.  It produces beautiful
    EJ> output for math markup.  Several of you are very familiar with
    EJ> it.  These are all very good points.

Math, citations, easy referencing and labeling, consistency,
elimination of the mouse, ability to work on any platform (a dumb
terminal will do!) with any text editor of your choice and the ability
to focus on what you want to write rather than how it looks.

    EJ> My dislike is not without reason.  LaTeX has a steep learning
    EJ> curve.  The tool chain requires time to learn.  I have watched

Writing style files may be a pain in the neck, but getting started
with LaTeX is an afternoon's effort and getting fairly productive is a
days work.  So if you don't need to write the style file its pretty
painless.  For more complex stuff, it helps to have a LaTeX guru
around or a good book.

[...]

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

That I agree completely with.  I say, she who writes the docs picks
the format, with just one note, pick something that works cross
platform and not on just one, so reST and OO are good.


cheers,
prabhu