[Pyobjc-dev] quick documentation format survey

[Steven D. A. <st...@ne...>]

I looked into the formats suggested by list members as well as consulting
Google on the subject of documentation formats.  My search was brief and
cursory, so I may have missed many different projects.  I'm still open to
other suggestions should list members have any.  My criteria are:

(1) Must be in an easily-parseable format that can be compiled to many
different formats.
(2) Can't be proprietary.
(3) Must support graphics.
(4) Should be easy to read in native format.  XML is better than binary,
something analogous to plain text is better than XML.
(5) Should be fairly mature, not a lot of bugs.
(6) Written in Python is a plus.
(7) It would be beneficial if sophisticated editors existed on Mac OS X for
writing docs using the protocol/tool.


SimTex looks very impressive.  It seems to provide for all needed formats
except Apple Help Format, for which we could add a Python backend.  It
appears to be a fairly mature project from my brief look at it.

I also took a look at the TwistedMatrix project, as recommended by Donovan,
but I wasn't able to find a reference to their twisted.lore.  (Not even on
Google...I searched for "twisted.lore matrix" getting zero hits; "twisted
lore matrix" getting a bunch of unrelated hits, a couple others with similar
results...you get the picture.  If someone provides me with a specific
pointer to this project, I'll take another look.)

I looked at DocBook, a widely used XML DTD.  There are a number of tools for
writing DocBook documentation.  I only found one obvious tool for Mac OS X;
remember though that my search was cursory and there could be others I don't
know about, especially ones written in Java.

Overall, I like SimTex best because (1) It's written in Python; (2) Uses an
OSI license (GPL); (3) Looks more-or-less like regular text before it's
compiled to another format, hence any text editor is a good authoring tool;
and (4) The author is right here with us if questions arise.

The usage of this tool could influence or create more work for future
contributors, including the authors themselves, so if there are any concerns
about using SimTex, please let me know as soon as possible.  Bear in mind
that my search was very much a seat-of-the-pants affair, so one plausible
criticism is that we ought to do a more detailed survey of the options,
perhaps weighting the criteria above, before committing to one alternative.
I'm more in the mindset of "make a reasonable choice quickly and get it out
ASAP," which is what I have tried to do in the survey above, but if there's
a lot of concern about this I'll rethink that attitude.

Thanks again for the feedback,

steve
--