[Doc-SIG] Crystal 0.1

[Laurence Tratt]

I'd like to make a sort of low key announcement about a very early version
of a new tool in the gendoc/pythondoc/javadoc mould. It's called Crystal and
0.1 is the first public version. I have been creating this system as part of
my final year undergraduate project, so at the moment it's subject to
whatever license my university wants to put on it.

This first version is *very* rough, not very ready and has much
unimplemented, much buggy etc. There is no documentation. There's no
guaranteed support (but I'll try).

If you're still not put off, here are some things worth noting:

  * Has plugin support for different languages, different doc
      string styles and different output formats
    (Currently only Python, StructuredText & HTML3 implemented
     though)
  * Flexible output (using a built in page layout language)
  * Good quality output (needs some work though)
  * Parses rather than imports .py files

Here are some less good things worth noting:

  * StructuredText is *not* implemented using Jim Fulton's module,
      was only implemented today, and may be very weird
  * No indices yet
  * No list of inherited methods / fields etc yet; HRefs between pages
      mostly lacking
  * Not widely tested (though it runs OKish over the standard 1.5.2
      library); Crystal has only been run on a couple of Unix machines
  * Lots of other little things not implemented
  * Has a tendency to show up Netscape 4.x tables limitations
  * Uses CPython parser interface; may not work under other Python
      implementations

The download URL is:

  http://eh.org/~laurie/comp/python/crystal/

I have put up a few demonstration pages (including a file or two from the
standard Python library as a point of comparison) on the web site to give
people a vague idea of what Crystal does.


I'm making this release because although this is early days, this might
still be useful to some people; at the least, it's got some ideas which I
don't think are seen in any other such tools, and so it might be useful to
people doing the same sort of thing.

Installation is currently a simple decompress.

Crystal makes use of SPARK, and my thanks to John Aycock for that brilliant
little package.

If anyone has any comments, please feel free to mail me (or discuss it on
the doc-sig), and happy documentation creating!


Laurie