Re: Project documentation format (fwd)

From: Anand Pillai <abpillai_at_nospammail_dot_net>
Date: Fri Aug 01 2003 - 04:11:36 CDT

I agree with David. I normally use for documentation
of my projects since I cannot afford MS Word. I am not much familiar
with TeX
and as David says, I have heard that it got a pretty big learning curve.

I am not familiar with APT, but as long as it has a python interface as
it looks like
from the mail, it would be interesting to learn it.

Btw, do we have any technical documents prepared on our project yet?
I would prefer to start my initial work by reading them and getting
familiarized with the
technical concepts involved here. I am excited about this project, and to
writing some code... :-)


~Anand Pillai,

On Fri, 01 Aug 2003 03:08:18 -0400, "David Mertz, Ph.D."
<> said:
> Telephone Conference
> 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
> {{{}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...
- --
   Anand Pillai

- -- - The professional email service
Received on Fri, 01 Aug 2003 14:41:36 +0530

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