Hello,

Mike Cannon-Brookes wrote:
Ken,

<snip/>

Personally I'd vote for xdocs without Maven at the moment, that gives us a
good upgrade path to Maven (if we decide to use it) or to any other XML
based doc format (as xdocs are XML files already).
Sure. However, why not check in the Maven project.xml, project.properties, etc. Aslak wrote so WW is "Maven aware." This doesn't imply that Maven will be used officially but would allow any developer with Maven installed to run it against WW to get the other benefits it provides.

Conceptually, this is really no different than included IDEA project file already in WW.

-Bill

-mike

On 12/12/02 10:37 PM, "Ken Egervari [eXtremePHP]" ([EMAIL PROTECTED])
penned the words:


Hi Mike,

Well, we have a few issues.  I'm thinking about the big picture in that XML
some form of XSLT (or something else) is beneficial, but I also wanted to
stike a balance in that many people didn't want the bloated libraries to be
involved (or to be abstracted away from them if they were).  Maven seemed
like one of those projects.

I just looked at cocoon for the past hour and it's too much for what we have
to do.  I can see this being useful for other projects perhaps, but not this
one.  I was just about to look at Forrest when I got your email, so I
decided to stop and read it.  I'm pretty glad I did.

I wanted to avoid the use with sitemesh since the documentation shouldn't
rely on a servlet engine.  I mentioned this before, but I could also
generate a sitemesh-aware html version of the documentation that strips out
the layout and allows sitemesh to take care of that.  For local
documentation, however, sitemesh won't (and shouldn't) be available.  Tools
like XSLT can help generate both forms of documentation (the website and the
local documentation).  As far as coding 2 stylesheets to do those
transformations, that's not a big deal.  I understand XSLT and can make both
stylesheets in a couple of hours.  This solves the layout problems since it
also contains it in a single spot.

The only reason I suggested using something like iText (or another) is that
I'll have a lot more flexibility in the way I can build the PDF documents.
By looking at others, they seem to be very generic and don't really provide
the feel for a book but rather a text file with a few text styles and that's
it.  I want to make a PDF that have a table of contents with links and a
bookmark list for easy navigating.  Any technology that will do that
automatically is great, but fromt he examples I seen, they never took
advantage of those features  I could also just use a simple template method
pattern to encapsulate the layout as well.

If the project is moving to maven, then maybe there is more merit to using
it.  I don't like projects that try to tackle 100 different things.  They
are hard to learn initially and they expect infrastructural configuration
and code in places that have no importance to the tool you need it for in
the first place.  I'll have to look into it some more as I'm no expect on
it - I've read the website and downloaded it today and played with it for a
bit.  I liked the xdoc format, however and was planning on using that
regardless.

For me, writing is actually the easier part so I wanted to tackle these
issues first.  I'm one of those people that tries to tackle the uncertainty
first so the rest of the project can run smoothly.

If you have any comments than I have said here, be sure to let me know as
I'll keep my email client open.

Regards & Thanks for the comments,
Ken Egervari

---

Ken,

You bring up a lot of interesting things here, Iıll try to reply below
(note: Iım far from a documentation expert).


Well, I've been looking at a bunch of technologies that we can use to
build

the documentation, but I'm not convinced that Maven will help us.  Maven
is an

interesting project in that it does a hundred different things, but in
terms

of simplicity and the information available on the website, it's not
there.  I

think the documentation generation features are not nearly as important in
the

developer's minds in comparison to the project information, tools to
simplify

build/test cycles and all the other stuff it does.  It also seems to
integrate

with Turbine and all these other frameworks that I didn't know exist.  I
think

if people were worried about bloating this part of the project with a tool
like Xalan, then they would definitely have some pretty strong opinion to
not

using Maven (I think I agree with them).  Since we aren't using Maven for
it's

other strengths, it's kind of clumsy to start using it for documentation
now

when simpler solutions make more sense.
I think people suggested Maven because it's 'the way of the future'. We have
just started to use it at work, and it is fantastic once you get it running.
As far as producing 'simple' documentation, it is very good. It uses xdoc
from Apache, which would be my preferred way to generate the documentation
(it's very simple, and 'mere mortals' can actually use it to write!).


I seriously think simple tools like Xalan are more than enough because
everyone probably has them in their classpath already, but I'm looking
into

Cocoon and Forrest right now (I'll put up another post to the newsgroup
about

my opinions on those) to see if they can simplify the required plumbing.
Cocoon and Forrest are huge overkill here I feel.


I'm much more interested in offline documentation generation where I can
simply include the static documents, the PDF files and the source code to
build all of that (rather than include the necessary targets in the
build.xml).  It doesn't make much sense to have every person in WebWork
have

these documentation generation tools on their computer right now since we
haven't rolled out the documentation yet.  I would only include the
documentation generation code and jars into the build.xml when we have
something we are happy with.
Well, I'm quite sure WebWork will end up using Maven after 1.3 (ie in the
next few months), so using it to build documentation probably makes sense
there. As for simplicity, it couldn't be easier to generate 'maven doc' :)


iText was another library I was thinking about using due to its simplicity
and

flexibility.  I'd need to code a few Java classes to convert the xml
document

to PDF, but this wouldn't take more than a day.  Again, I would only do
this

just so we wouldn't need a full-blown framework like Cocoon or Forrest.
Like

others have said, it's not a good idea to have Webwork developers or the
user

base that compiles from the source to be dependant on Cocoon or Forrest
and I

agree with that.  I'd like to look into them anyway just so I know for
myself

how they work.  If one of them will truly make our job much simpler to the
point where I don't have to write a line of Java code, then I'll consider
them.  Otherwise, I don't see the point to use them.
Gah! Let's not fall into the 'not invented here' syndrome, surely we don't
need to write any tools to do this.

This is why people suggested HTML, it's much _simpler_! :)

The point is, surely the tools are an ancilliary issue? It's fairly trivial
to move between tools at any time (half an hour of copy / paste at the
most). Let's concentrate on the big issues!


Since the documentation is going to be static pages, I'll have to redesign
the

layout of the documentation obviously.  This means that the left-side will
be

a little different to accommodate the documentation while I'll probably
keep

the top bar very similar.  We also need to coordinate integrating this on
the

www.opensymphony.com <http://www.opensymphony.com>  website as well as it
won't use sitemesh or whatever other gadgets the site is using now.  These
issues aren't a huge rush, but we could begin to talk about them.
Well, that's the beauty of SiteMesh - just drop the documentation in and it
will be decorated automatically. The actual HTML produced should be _very_
simple, and use CSS to style everything. That way we can reuse it in many
places.

Again - concentrate on the bigger issues of writing it, adding / moving a
logo is trivial!

Good thoughts though all of them - it's great to have someone thinking about
it. My advice, let's start simple and just get things down first - we can
worry about the details of the layout / tools later?

-mike


Regards,
Ken Egervari



-------------------------------------------------------
This sf.net email is sponsored by:
With Great Power, Comes Great Responsibility
Learn to use your power at OSDN's High Performance Computing Channel
http://hpc.devchannel.org/
_______________________________________________
Opensymphony-webwork mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork

Reply via email to