Are we thinking of puting together source documentation like what java
has with its javadocs?
A javadoc style would be:
/**
I put my documentation here for this method
example: foo bar
*/
FooBar.prototype.foo=function() {
...
}
We could put together a web-based documentation compiler.
just some thoughts.
Matt
On Wed, 2001-11-14 at 15:15, Laszlo Teglas wrote:
> >The documentation specs look a little complicated, but I guess that's
> >inevitable.
> I have a feeling that DynAPI will grow to encompass many more widgets, and
> other classes. Especially with Dan's new release, with layout managers ect.
> We need a structured document that can grow with the API easily. For the
> current size of the DynAPI this may look like overkill, however I would
> rather be over organized from the start than unorganized later.
>
> > It would be nice to see what is provided for, and what has to be done.
> Once the basic structure is agreed upon, we can start plugging in what we've
> got. And treat the whole documentation project as part of the overall DynAPI
> CVS, with CVS updates and periodic new releases. Otherwise the document will
> never be updated and will slowly become obsolete and abandoned. Then we'll
> need to start all over again.
>
> >> so.. we build the docs in HTML,
> >XML with parser to HTML would be great, but if that's too much overhead, as
> >a suggestion, it might be nice to gravitate towards XHTML.
> I agree with gravitating toward XHTML, XML with parser maybe really overkill
> Should we go Transitional or Strict XHTML1.0?
>
> Since this will be an extensive documentation we will need some kind of
> navigation system. We want the document to be viewable offline locally,
> therefore we can't use any server side script to include the navigation
> system.
> We have two choices:
> Utilize frames for the navigation, or painstakingly add the navigation
> system to every page (and update every page every time the nav system
> changes). I guess this could be done with some extended search replace tool,
> however this would still require a complete documentation upload every time
> the navsys changes.
>
> I vote for Frames =;^)
>
> Using frames may also help when we want to update different formats of the
> documentation. i.e. pdf files can be set up to list the content files
> consecutively without the need to strip out the navsys from every page. We
> could then replicate the navsys as a table of contents. (I haven't actually
> tried this, I'm just thinking out loud) I don't know much about Win2PDF.
> Does it take a graphical snap shot, or does it copy the text of the document
> and format it into pdf? If it copies the text, does it ignore HTML tags?
> What would it do to a navsys that is made up of tags mixed with content?
>
> NanoFace =;^)
>
> -----Original Message-----
> From: Richard Bennett [mailto:[EMAIL PROTECTED]]
> Sent: November 14, 2001 2:56 PM
> To: Doug Melvin; Laszlo Teglas; [EMAIL PROTECTED]
> Subject: Re: [Dynapi-Dev] Documentation Project
>
>
> The documentation specs look a little complicated, but I guess that's
> inevitable. It would be nice to see what is provided for, and what has to be
> done.
>
> > so.. we build the docs in HTML,
> XML with parser to HTML would be great, but if that's too much overhead, as
> a suggestion, it might be nice to gravitate towards XHTML.
> (purely personal preference)
> However, the whole documentation as we have it now is done in WIKI WIKI or
> something, this is pretty powerful once you get used to it, and is easily
> edited afterwards for updating.
>
> > (pssst.. I would like to be an admin.. it sucks to not be able to DO
> > anything..)
> Actually, being admin doesn't make much difference. In my case, I can edit
> bugs/patches etc in bulk, that's about it. My posts to the cvs list also
> need to get approved, and I can't change anything on the website, as this is
> a separate system all together.
> I think Hendrik Vaglin is still is still adminning the website, so if you
> want to set up a new documentation section, get in touch with him.
>
> Richard.
>
>
>
> ----- Original Message -----
> From: "Doug Melvin" <[EMAIL PROTECTED]>
> To: "Laszlo Teglas" <[EMAIL PROTECTED]>;
> <[EMAIL PROTECTED]>
> Sent: Wednesday, November 14, 2001 7:37 PM
> Subject: Re: [Dynapi-Dev] Documentation Project
>
>
> > I like the structure, and will adopt it.
> > It should be in HTML, but can be in pdf as well..
> > search for and download Win2PDF.. this is a virtual
> > printer which 'prints' to a PDF file.
> > This printer can be used from ANY windows application that can print..
> >
> > so.. we build the docs in HTML,
> > then we offer a link to DL the PDF version..
> > Of course, someone should be resposable for updating the PDF when the HTML
> > is updated..
> >
> > (pssst.. I would like to be an admin.. it sucks to not be able to DO
> > anything..)
> >
> >
> > ----- Original Message -----
> > From: "Laszlo Teglas" <[EMAIL PROTECTED]>
> > To: <[EMAIL PROTECTED]>
> > Sent: Wednesday, November 14, 2001 1:23 PM
> > Subject: [Dynapi-Dev] Documentation Project
> >
> >
> > > Yes we are desperately in need of documentation. I believe we should
> > create
> > > a document structure instead of just adding files and tutorials
> > independent
> > > of each other. I have started to lay out the documentation structure as
> I
> > > perceive it to be logical. I am looking for feedback and expanding the
> > > structure:
> > >
> > > |
> > > +-Introduction Module
> > > | +-What is DynAPI
> > > | +-History and Evolution of DynAPI
> > > | | +-Origin of DynAPI 1.0 (Dans)
> > > | | +-Major diffs between 1.0 and 2.0
> > > | | +-Major diffs between 2.0 and 2.5
> > > | | +-Major diffs between 2.5 and proposed future 2.6/3.0?
> > > | | +-Detailed Revision File
> > > | |
> > > | +-Who Should use DynAPI
> > > | +-Requirements / Supported Browsers and OS's
> > > | +-FAQ
> > > | +-License
> > > | +-Contributors
> > > |
> > > +-Reference Module (To the point breakdown of the DynAPI Class Structure
> > > | | no examples)
> > > | +-dynapi.js
> > > | | +-Purpose/Function
> > > | | +-Requirements/Inheritance Structure
> > > | | +-Constructor/Initializer
> > > | | +-Fields/Constants/Properties
> > > | | +-Fields/Constants/Properties Inherited from other classes
> > > | | +-Methods/Functions
> > > | | +-Methods/Functions Inherited form other classes
> > > | |
> > > | +-api
> > > | | +-browser.js
> > > | | | +-Purpose/Function
> > > | | | +-Requirements/Inheritance Structure
> > > | | | +-Constructor/Initializer
> > > | | | +-Fields/Constants/Properties
> > > | | | +-Fields/Constants/Properties Inherited from other classes
> > > | | | +-Methods/Functions
> > > | | | +-Methods/Functions Inherited form other classes
> > > | | |
> > > | | +-dyndocument.js
> > > | | | +-Function/Function
> > > | | | +-Requirements/Inheritance Structure
> > > | | | +-Constructor/Initializer
> > > | | | +-Fields/Constants/Properties
> > > | | | +-Fields/Constants/Properties Inherited from other classes
> > > | | | +-Methods/Functions
> > > | | | +-Methods/Functions Inherited form other classes
> > > | | |
> > > | | +-dynlayer.js
> > > | | +-Function/Function
> > > | | +-Requirements/Inheritance Structure
> > > | | +-Constructor/Initializer
> > > | | +-Fields/Constants/Properties
> > > | | +-Fields/Constants/Properties Inherited from other classes
> > > | | +-Methods/Functions
> > > | | +-Methods/Functions Inherited form other classes
> > > | |
> > > | +-event
> > > | | +-dragevent.js (same breakdown as above)
> > > | | +-keyboard.js
> > > | | +-listeners.js
> > > | | +-mouse.js
> > > | | +-simple.js
> > > | |
> > > | +-ext (same breakdown as above)
> > > | +-gui
> > > | +-images
> > > | +-util
> > > |
> > > +-Example Module
> > > | +-Examples for each of the classes (Each example would be independent
> of
> > > | any other example) (This is like a quick reference how to get
> started)
> > > |
> > > +-Tutorial Module (Detailed in-depth tutorial each step building on the
> > > previous)
> > > +-The basics of how DynAPI works
> > > | +-dynapi.js (explain how it works)
> > > | +-browser.js (explain how it works)
> > > | +-dyndocument.js (explain how it works)
> > > | +-dynlayer.js (explain how it works and create "Hello dynLayer")
> > > |
> > > +-Gui Tutorial
> > > | +-What are widgets?
> > > | +-Detailed walk through in creating each of the standard guis
> > > |
> > > +-Events Tutorial
> > > | +-What are Listeners and Events
> > > | +-Detailed walk through in utilizing each event file
> > > |
> > > +-Util Tutorial
> > > | +-Detailed walk through in utilizing each Utility file
> > > |
> > > +-Extension Tutorial
> > > | +-Detailed walk through in utilizing each Extension file
> > > |
> > > +-Advanced Topic Tutorials
> > > | +-Create your own widgets
> > > | +-Any other Advanced tutorials we can think of
> > > |
> > > +-Summary Tutorial
> > > +-This tutorial would be like a step through project that would
> > > build an extensive program based on All/most of the DynAPI
> > > components and previous tutorials (perhaps a game or chat room)
> > > maybe someone already has such a thing that they would be willing
> to
> > > donate for the cause.
> > >
> > > As you can see there are 4 modules:
> > > Introduction Module; Reference Module; Example Module; Tutorial Module
> > > They can be incorporated into one manual or be used independently.
> > > A lot of this stuff we already have, we just need to organize it and
> > expand
> > > on it.
> > >
> > > Should this be a plain text document, html, pdf, all of the above?
> > >
> > > Your thoughts and comments appreciated
> > >
> > > NanoFace =;^)
> > >
> > >
> > > _______________________________________________
> > > Dynapi-Dev mailing list
> > > [EMAIL PROTECTED]
> > > http://www.mail-archive.com/[email protected]/
> >
> >
> > _______________________________________________
> > Dynapi-Dev mailing list
> > [EMAIL PROTECTED]
> > http://www.mail-archive.com/[email protected]/
> >
>
>
> _______________________________________________
> Dynapi-Dev mailing list
> [EMAIL PROTECTED]
> http://www.mail-archive.com/[email protected]/
_______________________________________________
Dynapi-Dev mailing list
[EMAIL PROTECTED]
http://www.mail-archive.com/[email protected]/
