Project documentation format (fwd)

From: David Mertz, Ph_dot_D_dot_ <voting-project_at_gnosis_dot_cx>
Date: Fri Aug 01 2003 - 02:08:18 CDT

   I was fortunate enough to be able to participate, by telephone, in
   today's meeting with Alan Dechert, Arthur Keller and Adrianne Yu Wang
   (unfortunately with a bad connection; I leave it to Alan and Adrianne
   to summarize the meeting).

* Documentation formats

   One minor administrative issue was raised that I would like to comment
   on, and make a proposal for going forward. We discussed the need to
   develop a variety of documentation associated with the project. I
   expressed a concern to avoid the proprietary MS-Word as a format--if
   for no other reason than it excludes me (and any other users of open
   source OSs) from participating in the documentation process. Beyond
   its proprietary nature, MS-Word does not play nice with versioning and
   collaboration systems like CVS on Sourceforge (although I am aware it
   has its own versioning tools, to an extent).

* Finding simplicity

   Arthur suggested <<LaTeX>> as an open alternative, which indeed it is.
   But on reflection, I believe the learning curve for <<LaTeX>> is
   excessive for documentation contributors who may not themselves be
   programmers.

   I believe a good alternative is to adopt <APT> (Almost Plain Text) as
   an intermediate documentation format. This allows export to targets
   such as:

     * RTF
     * LaTeX
     * DocBook
     * PDF/PS
     * HTML

   In case you haven't figured it out by now, this note is written using
   somewhat contrived <APT> formatting. You can read all the details at
   {{{http://www.xmlmind.com/aptconvert.html}The aptconvert homepage}}.
   <aptconvert> is the Java-based conversion tool to add markup to <APT>.

* Versioning and output friendliness

   I wrote my book <Text Processing in Python> using my own conceptually
   similar format that I call "smart ASCII." However, when
   Addison-Wesley asked me to help convert someone else's book that was
   created in a custom XML format, I did some research into similar tools
   that had a more flexible range of targets. Python programmers will be
   familiar with reStructuredText--but I find it both just a bit too
   complicated for novices, and a bit too Python specific. I arrived at
   <APT> as the best such format (at least for my purpose then).

   The nice thing about these formats is that they make running a context
   diff between document versions REALLY easy. And they play nice with
   CVS. And the look quite a lot like what people normally send in
   uncluttered email (with occassional minor variations). With <APT>,
   you can even include verbatim code like:

+-------------------------------------------+
#!/usr/bin/env python
from gnosis.xml.objectify import make_instance
doc = make_instance('document.xml')
+-------------------------------------------+

   But really what the benefit amounts to is that the document
   maintainer(s) can take a plain ASCII writeup that a non-technical user
   writes, and with only minimal effort, add a little indentation and
   emphasis to make it good APT. From there, we can regularly publish
   nice looking RTF, HTML or PDF versions of the same content on our
   Sourceforge project "Docs" section.

   I would be very happy to take responsibility for the markup and export
   of such contributed documentation, if the group agrees this is a good
   way to go. I imagine I will also contribute to the actual writing of
   some of the documentation, but a commitment to such minor
   documentation massaging is a much smaller one than is one to writing
   it.

   Yours, David...
Received on Fri, 01 Aug 2003 03:08:18 -0400

This archive was generated by hypermail 2.1.8 : Wed Aug 06 2003 - 12:50:26 CDT