[Doc-SIG] Some random thoughts

[will]

> -----Original Message-----
...
> One thing that's surprised me is that I thought people were
> going to tear me
> to shreds over the HTML output (in terms of both the
> quality and the actual
> look in the browser) and ignore the source (which is still
> rough) whereas so
> far it's been mostly the other way around. Shows you how
> wrong I can be :)

Hey!  I commented on the html output like a week ago...  :(

I've been using Crystal to generate documentation for the mud project
I've been working on with the other Varium folks because I was never
able to get pythondoc working.  I spent a couple hours with pythondoc
trying to make it happy.  In comparison, I think I got Crystal up and
running in a half hour or so.  And had built a script to re-generate
html docs for our varium mud server code every night.

I find the visual parts of the output to be slightly
confusing--certainly not as nice as Ping's thing's output.  Course the
visual output can be changed to some extent to suit one's needs.  In
the test#.py example files, if you call
html3_outputter_styles.update() you can replace various elements in
the html style dictionary and thus affect the visual aspects of the
final html.  I have yet to figure out enough of which elements are
which and then how to adjust them to suit my tastes.  I was telling
Laurence that he's built Crystal in such a way that theoretically you
could build themes without changing/patching the Crystal code.

I also dislike some other things about the html output which comes
from how Crystal translates the html classes into actual html text
files.  Specifically the fact that Crystal is not quoting values in
attributes of the various tags and the use of tabs as indentation
rather than 3 or 4 spaces.

<Table CellSpacing = 0 Align = Center Width = 100% CellPadding = 3>
vs.
<Table CellSpacing="0" Align="Center" Width="100%" CellPadding="3">

This is pretty trivial, but "Generated by Crystal 0.2 (24 February
2000) Copyright &copy;Laurence Tratt 1999 - 2000 at 07:16AM Sunday 05
March 2000" which is printed at the bottom of every html page is
confusing.  It sounds like Lawrence generated and copyrighted MY html
output, not that he created and copyrighted Crystal which generated my
html output.  Actually, that's not trivial.  It should be two
different lines:

   Generated at 07:16AM Sunday 05 March 2000 by willg
   using Crystal 0.2 (24 February 2000) Copyright &copy;Laurence Tratt
1999-2000

Or something to that effect.

Beyond that, it's pretty good about some things.  We've had problems
with doc-string comments being formatted in a funky manner in the html
output.  But that's mostly due to the fact we're pretty ignorant as to
what the markup methods are.

It would be really nice to be able to mark certain variables and
functions and classes as "internal use only" so that they don't show
up in the documentation.

So that's a semi-html-oriented rough review from my perspective.

If you want to look at the output we've got (based on code that's in a
state of constant flux), feel free to look at:
http://www.varium.com/coders/mudserver/index.html

I told Laurence that I was going to play with the style and change it
to something that I find less confusing (less lines).  I haven't done
much since then, though.  I keep getting sidetracked.

/will