[Doc-SIG] Some random thoughts

[Laurence Tratt]

In message <NDBBJAKILMEBBFEDCMKKCEHFCBAA.willguaraldi@mediaone.net>
          "will" <willguaraldi@mediaone.net> wrote:

[Laurie]
>> 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 did say mostly: you're the honourable exception :)

> 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.

Documentation is an issue, and I apologise again... But themes are
definitely something I want to do (I had the concept, but stupidly didn't
call them themes. So thanks to Will for pointing out the obvious!), and then
hopefully I can keep more people happy.

If anyone's got something specifically they dislike (perhaps the indices),
then I can take it from there.

> 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">

The first of those is definitely a fault; the second I'm ambivalent about
(I'm a tab person myself). If it's a problem, a search and replace "\t" with
"   " in lib/crystal/Defaults/Python_To_HTML3.py is a quick hack fix.

> 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.

OK. I think that's reasonable; I only put it in there to test the address
tag in Netscape (it's broken. Surprise). I'll change it so that by default
it's "Generated at 07:15AM Sunday 05 March 2000 using Crystal Copyright
Laurence Tratt" etc. I actively *don't* want to copyright anyones HTML!

> 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.

Currently what's implemented is a subset of StructuredText. You can get a
rough idea of what's what:

  http://www.zope.org/Members/millejoh/structuredText

But please note it's not a perfect implementation since some of those rules
are currently open for debate. Specifically, intra-page links are currently
not at all supported (not that I don't like them. I just haven't done them).

> 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.

I'm going to work on that. ATM Crystal itself uses an initial single "_" to
do this; adding in overrides for specific variables etc will be pretty hard
to do sensibly (it'll grow like wildfire is my first thought), but it is on
my list.

I might make another release in a few days time to just clear up a couple of
the HTML issues (my current version doesn't cause browser windows to
oversize horizontally). There won't be much other difference though.


Laurie
-- 
http://eh.org/~laurie/comp/python/