Re: [TCLCORE] Re: RFC/PEP format

[Donal K. F. <fel...@cs...>]

Andreas Kupries <a.k...@we...>
> Donal K. Fellows <fel...@cs...>
>> Andreas Kupries <a.k...@we...>

>> I'm trying to generate a useful sidebar quick-index too; the JDK1.2
>> documentation tree is actually quite usable except for a few minor
>> niggles (like the way that most stuff simply doesn't fit in the
>> frames!) so I try to generate HTML to be a bit like that.  Let me
>> know what you think...
> 
> I haven't seen the JDK1.2 docs yet. Some url available I can go to ?

Hmm.  (Rummages around bookmarks...)  Try:
   http://java.sun.com/j2se/1.3/docs/api/

You could also have a look at:
   http://athene.cs.man.ac.uk:8000/
which was produced with the same tool (javadoc) though on a different
source tree (and its served up by a nifty little Java webserver that
lives in the same archive file as the documentation web.)  It would be
very nice indeed if some kind soul developed a similar sort of tool
for Tcl.  (Handling C functions written to follow the _Tcl/Tk
Engineering Manual_ would be a wonderful bonus.)  This sort of thing
is, in my experience, extremely useful in large software projects...

>>> Enclosed the most uptodate versions of the *rules .tcl files and some
>>> _drafts_ I am working on.
>> 
>> Do you have a document specifying the format of a TCT or is it simply
>> what you happen to have implemented?  :^)
> 
> As of now it is what I 'happen to have implemented', with all the
> incongruencies that come from such an approach (TCT- prefix, and not,
> ...). But when working on an adaption of
> 'http://python.sourceforge.net/peps/pep-0001.html' for our needs the
> section 'PEP Style' brought it home that I should (start to) do
> this. Any ideas for the normalization and/or optimization of the
> commands ?

Not yet.  Except perhaps that braces should not be used when passing
arguments to formatting directives...  :^)

I might say more later on this.

> This documententation could be TCTD 3 (Number 2 should be the adapted
> PEP 1). Ne TCTD, this is a shortcut of 'Tcl Core Team Document'. My
> current name for this type of document. I had no desire to use RFC or
> TEP (Tcl Enhancement Proposal). Other names ?

Well, I've been calling them TCTs, but that's easily changeable.  My
main concern is that we should have a format that is easy to read,
write (with a standard text editor) and convert into whatever other
formats we want (definitely HTML, but nroff, LaTeX, XML, etc. would be
good too.)  Doing this all on the fly just makes things even better,
as it means that the exported view is always in sync with the
repository.

I think I'll put my current rendering code up on sourceforge in the
near future.  Once they get back to me with the URL to confirm my
account...

Donal.
-- 
Donal K. Fellows, Department of Computer Science, University of Manchester, UK.
(work) fel...@cs...     Tel: +44-161-275-6137  (preferred email addr.)
(home) do...@ug...  Tel: +44-1274-401017   Mobile: +44-7957-298955
http://www.cs.man.ac.uk/~fellowsd/  (Don't quote my .sig; I've seen it before!)