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

[Paul F. Dubois]

I started this as a private thread between David and Travis and I, so thi=
s
public discussion is missing the following background:

The current doc for Numerical is in Frame. I made this choice because it =
is a
WSYWIG tool that can make HTML and PDF if needed. Also, Frame is relative=
ly
easy to learn, and is the only choice for books really. And Numerical Pyt=
hon
the Manual could easily become Numerical Python the Book. It has 17 chapt=
ers
already.=20

I have done collaborative manuals before in LateX (disaster) and a
similar product LLNL had (disaster).  ANY document system that used struc=
tures
edited by humans invariably results in the structures being screwed up by
somebody and the next poor person who actually tries to make the output e=
nds up
searching by bisection for the errors. Latex in particular suffered from
non-portability between authors who had slightly different installations,=
 as
someone else mentioned.

While I am quite open to change, the only thing really wrong with Frame i=
s that
it costs money and doesn't run on Linux for one. But it does run on Mac,
Windows, and Solaris, which enables a lot of people.

Anyway, I hardly think any other solution that involves money would be an=
y
better. I disagree that HTML is ok; even if everyone uses a WYSIWIG, the
language is sufficiently inexpressive that it is a problem (especially fo=
r
writing about a language in which indentation counts). Besides, I want to=
ols
that help me make and maintain the index and TOC.