Hi Ulrich,
At 09:42 AM 8/16/2002 +0200, Ulrich Köster wrote:
>a website for WOLips would be great. Eclipse has a help system and I think
>we should use that for the user documentation. Can you give some insights
>how your help is currently build? May be we can make the help available
>via Eclipse and the website. The javadoc stuff can be made available via
>help system and the website.
Website and docs in WOProject are the same thing. This eliminates any
duplicate effort. The technology WOProject is using to generate it is
called Anakia from Jakarta Velocity. Basically the docs is all *.xml files
found in woproject/xdocs directory. Note that XML files use some logical
(non-HTML) formatting as well as some simple XHTML formatting within the
paragraphs.
There is a common Anakia template at
woproject/xdocs/stylesheets/woproject.vsl. It defines a way to generate
HTML out of the XML files, adding common template (menus, header), and
applying other formatting transformations. This is akin to XSLT, only
syntax is much simpler (and less powerful). The goals we achieve with
Anakia are:
1) freeing the developers from HTML formatting issues when writing the docs,
2) providing consistent look of all pages
3) giving developers the ability to build the website locally by using "ant
doc"
4) website and documentation becomes the same thing. So it has to be
updated in a single place.
Now, where WOLips fits in.
I understand that WOLips would use Eclipse-style HTML for its
documentation. I would still like to keep the website consistent and use
our current formatting. So I guess we may write another VSL file for
WOLips, and have a single set of XML files, just format them differently
depending on what we are generating (the website or the internal WOLips
docs). I will do the new VSL, no problem.
Suggested website structure changes:
1. Update the front page with a paragraph about WOLips
2. Update the contributors page with your name
3. New menu item in the left-hand menu under "Documentation" called "WOLips
Plugin"
I suggest to put WOLips-related XML docs in woproject/src/wolips/xdocs. As
for JavaDocs, I suggest to keep them separate from WOProject with a link
from WOLips table of contents page.
I will start the process by converting your quickstart.html and toc.html
pages to the XML format this weekend. This will give you a sample of how
this should be done, so you can proceed with the docs.
>The next step will be everything missing around woapp(build, launch and so
>on). The woframework stuff works great. If I like it or not the docu have
>to be updated :-). I guess that will take 2 weeks.
If it takes longer, no rush. I just wanted to know what is the WOLips
direction right now.
Andrus
This archive was generated by hypermail 2.0.0 : Fri Aug 16 2002 - 09:55:58 EDT