Re: Documentation format

From: David Mertz <voting-project_at_gnosis_dot_cx>
Date: Wed Aug 06 2003 - 17:21:03 CDT

VanL <vlindberg@verio.net> wrote:
|1. I concur that the documentation format be something that is
|human-readable in a text editor.

Good... I think that is very important (as I wrote, of course).

|2. APT appears fine; however, the only implementation I was able to
|find was in Java.

That's correct, AFAIK. But I envision 'aptconvert' as simply a tool
we'll use, not part of the development itself. Likewise, the program I
use to mirror the mail archive is written in C... and I'd even be
willing to use a Perl application that helped the development process
:-). And I'll certainly use sed, grep, wc, and friends, even though
they aren't written in Python. Or LaTeX.

Of course, sticking with Free Software tools is highly desirable, for
many reasons.

|documentation format such that the docs can be automatically built from
|the source tree without the invocation of a separate language.

I think we're coming from slightly different directions. I think using
something like DocUtils (in Python) can still be very useful. But only
a minority of the documentation will be documentation of programs per
se. We also need to document laws, goals, press releases, and so on.

So there I have a couple problems with reStructuredText (I like it, of
course... see my article on it, for example). I'd rather teach APT to a
lawyer or polisci professor than than I would reST. It's just a bit
less picky, and a bit closer to what folks already write in email. And
there is a good chunk of reST that is really about *Python*
specifically, rather than just about documents.

But also, reST currently lacks some desirable targets: RTF (for people
who want to import into MS-Word...shudder); and the LaTeX/PDF targets
are still very experimental for reST. APT is ready to go on those
targets (no custom classes, and "should be possible", just run with a
switch).

|4. I would personally prefer using something like APT or StructuredText
|to write the documentation than something like XML, if for no other
|reason than writing XML of even moderately complex dialect can be a
|pain.

Absolutely, no one without a highly specialized tool chain should be
forced to try to write XML.

Yours, David...

--
 mertz@  _/_/_/_/ THIS MESSAGE WAS BROUGHT TO YOU BY: \_\_\_\_    n o
gnosis  _/_/             Postmodern Enterprises            \_\_
.cx    _/_/                                                 \_\_  d o
      _/_/_/ IN A WORLD W/O WALLS, THERE WOULD BE NO GATES \_\_\_ z e
==================================================================
= The content of this message, with the exception of any external 
= quotations under fair use, are released to the Public Domain    
==================================================================
Received on Sun Aug 31 23:17:02 2003

This archive was generated by hypermail 2.1.8 : Sun Aug 31 2003 - 23:17:17 CDT