[Matrix-SIG] RE: Authoring tools (was Active arrays)

[hinsen@dirac.cnrs-orleans.fr]

> searching by bisection for the errors. Latex in particular suffered from
> non-portability between authors who had slightly different installations, as
> someone else mentioned.

I remember such problems from the early days of LaTeX, but since LaTeX
2e has become the standard, and since everyone uses one out a small
number of standard distributions, they have disappeared. The remaining
problem to watch out for in collaborative work is personal macros; one
solution is to require personal macros to begin with the initials of
the author.

LaTeX seems the only documentation system at the moment that is free
and open. Yes, it is sometimes difficult to solve some LaTeX problem,
but it is always possible because you have all the sources. With any
proprietary system, you sooner or later reach a point where you just
can't go on because you'd have to fix the program, and can't.

DocBook is also open and free, including some tools to work on it, but
also extremely complicated, and the amount of markup for a typical
text is sufficient to make typing extremely unpleasant with a standard
text editor, even if it is Emacs with SGML support. I used DocBook for
the ScientificPython and MMTK manuals, and I would most definitely not
make that choice again. I ended up modifying the original DTD because
there was no decent markup for documenting Python, and then I wrote
my own translators to HTML and LaTeX because this seemed much simpler
than understanding DSSSL and debugging JadeTeX.

Another option is to develop a special (and simple) DTD for Python
documentation and write translators to other formats (in Python,
of course). This would make sense if the whole Python community
were interested in such a development.

Konrad.
-- 
-------------------------------------------------------------------------------
Konrad Hinsen                            | E-Mail: hinsen@cnrs-orleans.fr
Centre de Biophysique Moleculaire (CNRS) | Tel.: +33-2.38.25.55.69
Rue Charles Sadron                       | Fax:  +33-2.38.63.15.17
45071 Orleans Cedex 2                    | Deutsch/Esperanto/English/
France                                   | Nederlands/Francais
-------------------------------------------------------------------------------