When you refer to "one set of docs in CVS" are you referring to the
documentation project or are you referring to a fully /**documented*/ src?
Here is what I think of the whole logistics of it all:
A) There are two issues:
1) documenting the source code
2) creating documents in XHTML transitional that will serve as an intro,
reference, example quick start, and detailed tutorial.
Documenting the source will help us mostly with the reference module of the
XHTML document project (plus all the benefits for having tidy and commented
src)
B) In order to automate creating the XHTML reference from the src comments
we will need the following:
1) a comments stripper
(apparently we already have one thanks to Dan, written in Perl)
2) a doc compiler able to recognize the difference between a
constructor function block and all the other types of function
blocks and fields. And be able to determine inherited functions/properties
and all the other things we find important to document. This requires:
i) a well defined strict DynAPI language specification
ii) strict compliance with this specification when coding
iii)preferably some tool to validate compliance
C) We can still use the src document in our reference module without a doc
compiler, however this will be mostly a manual cut and paste mechanism.
Therefore we could still create well documented src and take advantage of it
now, manually. And in the future with a doc compiler automate the process.
D) I agree in having one set of src files in the CVS fully documented all
the time. The stripped version should only be created at package time of new
releases. The XHTML docs should however be part of the CVS in a separate
dir.
The CVS should look like this:
dynapi
|
+-src (fully commented code)
+-docs (intro module, reference module, example module, tutorial module)
+-test (test folder)
A zipped up package should look like this:
dynapi
|
+-src (fully commented code)
+-js (stripped code)
+-docs (intro module, reference module, example module, tutorial module)
No test folder required
E) What are the standardized steps taken at the present when we package up
new versions? Who is responsible for carrying them out? If we don't have any
standards, we should probably create one, or modify the current steps once
we settle on this new doc structure.
NanoFace =;^)
-----Original Message-----
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED]]On Behalf Of Richard
Bennett
Sent: November 15, 2001 12:58 PM
To: martin ström; [EMAIL PROTECTED]
Subject: Re: [Dynapi-Dev] Documentation Project
I think we should have one set of docs in CVS, which are updated daily (or
on demand) , like the snapshots, and a second, public version which is
updated with each release.
Just like it was before, but working properly.
Richard
----- Original Message -----
From: "martin ström" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Thursday, November 15, 2001 6:32 PM
Subject: RE: [Dynapi-Dev] Documentation Project
> > 1) We could either setup two directories under the CVS (src
> > for commented
> > and js for uncommented) and be forced to strip out the
> > comments every time
> > we make a CVS update.
> >
> > or my preferred way:
> > 2) We could maintain just the src CVS folder fully commented
> > and strip out
> > the comments only when we create a new official release package.
> >
>
> If it's possible it would be great if this could be done automaticly
> every time a new snapshot is created. Just a program that uncomments &
> packs the src/-dir into a new js/ dir and make a zip of it all.
>
> /martin
>
>
> _______________________________________________
> Dynapi-Dev mailing list
> [EMAIL PROTECTED]
> http://www.mail-archive.com/dynapi-dev@lists.sourceforge.net/
>
_______________________________________________
Dynapi-Dev mailing list
[EMAIL PROTECTED]
http://www.mail-archive.com/dynapi-dev@lists.sourceforge.net/
_______________________________________________
Dynapi-Dev mailing list
[EMAIL PROTECTED]
http://www.mail-archive.com/dynapi-dev@lists.sourceforge.net/
