[Doc-SIG] Some random thoughts
Laurence Tratt
laurie@eh.org
Sun, 05 Mar 2000 17:59:28 GMT
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 ©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 ©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/