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

[David Ascher]

> > Never tried DocBook.
> >
>
> Me neither, but lots of people use it.  It is SGML at it's core, though.

As I'm sure Travis knows but maybe Paul and others don't, Docbook is an
XML/SGML markup, it's not an editor.  I would hate to have to write tables
with it.  Serious writing w/ docbook requires a serious SGML/XML editor,
although I suppose most users are just using emacs.  I also suspect that
DocBook is overkill for NumPy doc, if it's overkill for Python's main doc
(in the opinion of Fred Drake, IIRC).

> So what is it about Frame that keeps people from munging the basic
> structure?   It is hard to write documentation with multiple people
> involved using a binary-only file.  Aren't the problems you encountered
> with LaTeX the same as those encountered with any group alteration of a
> source?  The same thing could happen with the C and Python code, too.

LaTeX allows people to define macros and makes writers think like
programmers.  Bad idea. =)  Many many folks don't know LaTeX but would be
able to pick up a WYSIWYG editor easily.

> I'm not convinced that LaTeX or DocBook wouldn't be a more useful group
> documentation format.  I use LaTeX an awful lot, and really like it.
> Admitedly, the only multiple-author writing I've done is a paper where we
> both knew and loved LaTeX.  It worked great :-)

I refuse to use LaTeX.  Can't even justify why, it's a gut reaction after
writing too many papers, a several-hundred page dissertation with it,
spending waaaayy too many hours debugging poorly written LaTeX macros,
fussing with DVI, PS, EPS, bounding boxes, BibTeX, fussy installations,
missing fonts, bad HTML conversion, etc.

That said, I don't like Frame on the PC either, after having written the
current document.  The UI was designed for the mac, and it works much better
on the mac (I've typeset two significant books with very complex tagging and
hundreds of plates on the Mac about 4 years ago, and it was far easier than
producing the NumPy doc).  As it stands FrameMaker's UI violates many of the
assumptions of the average Windows user (I can't remember what keystroke
sequence that I use all the time in other software causes a line to be
deleted w/o any possibility to recover)  Overall I think that the state of
the world is pretty rotten when it comes to collaborative authorship outside
of the world of Microsoft, which I realize we can't use.

DocBook or other XML/SGML markup is probably the way to go, but I'm still
quite frustrated with the authoring tools.  Whenever I have to match tags I
feel like i'm back on the IBM VM/CMS machine on a 3278 terminal.  There's a
*reason* we have megapixel displays!  There's *a point* to the megabytes of
memory being used by graphics subsystems!  There's *value* in the decades of
work in user interfaces.  There's *truth* to the feeling my mom has that the
Mac is easier to use than Unix.  </deep breath>.  Sorry, I had to get that
off my chest.

Finally, there's StarOffice, but it seemed quite immature the last time I
checked.  It is available free for Unix and Windows.
http://www.sun.com/staroffice/

I propose that this discussion be shelved until Developer Day at the
conference, and that we figure out in the DOC-SIG section what Python's
going to do for its core doc, and follow along.  Synergy.

--david