Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Ant Developers List" <ant-dev@jakarta.apache.org>
Message-ID: <3C869FAD.F6795C38@progress.com>
Date: Wed, 06 Mar 2002 18:01:01 -0500
From: "Bill Burton" <billb@progress.com>
Organization: Progress Software Corporation
MIME-Version: 1.0
To: Ant Developers List <ant-dev@jakarta.apache.org>
Subject: Re: [xdocs] Feature Requests
References: <200203061220.g26CKVU07452@mail004.syd.optusnet.com.au>
 <001c01c1c50d$e28e2e20$6401a8c0@darden.virginia.edu>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Hello,

Good suggestions, Peter.

Erik Hatcher wrote:
> 
> ----- Original Message -----
> From: "Peter Donald" <peter@apache.org>
> 
> > I was just playing around with the xdocs proposal and I have a few
> requests ;)
> >
> > * Could you rename your templates to end with .j as that *seems* to be the
> > standard that most other xdoclet templates use (though I could be wrong).
> 
> Ummm, no!  :)  I don't like the .j extension.  I have a feeling it was a
> holdover from when XDoclet was EJBDoclet and it was designed to be .java
> template. We aren't creating .java files - but a lot of XDoclet's builtin
> stuff is.
> 
> I prefer .template.

A while ago when I went hunting for the XDoclet stuff in myrmidon, I had
no idea that the files with .template were related to XDoclet.  On the
other hand if they were .j,  I wouldn't have known either because I didn't
know anything about XDoclet :) . Although .j may not be a very good
convention, it is a convention nonetheless.

> > * If someone was to create "summary" pages for each category of
> > tasks/datatypes that listed all the types in that category and maybe gave
> a
> > blurb about category (blurb got via merge external xml operation?) then
> that
> > would be fantastic.
> 
> Bill??

Yes.  I was occupied tracking down a bug in jaxen which is used by dom4j
which is used by DVSL.  With that fixed, I'm now able to generate
correctly formatted pages for the datatypes as well as tasks with only
minor changes to the existing stylesheet.  Now that this is working, I'll
look at generating a tasks and datatypes overview page.

> > * Rather than defaulting to "other" as catgory if it is undefined -
> perhaps
> > it would be a good idea to default to the last element in package name in
> > which the task is contained. So tasks in
> >
> > o.a.t.a.taskdefs.optional.vss
> >
> > would be in the "vss" category if none other was specified. This would
> make
> > it much easier to also use code unchanged for ant2 ;)
> 
> Thats a good idea!  Perhaps we could have that as a configurable option what
> the default category is.  I'm not going to concern myself much with the
> category stuff at the moment beside perhaps making this change because I
> feel the most important thing is for us to get the generated documentation
> as good as the current HTML documentation.  Once there, we can then migrate
> that proposal to the main code base.  Then we can have a field day with
> categories and other such features!

I like the idea generally but because the XDoclet process doesn't know all
the categories at any given time, I'd use the last two elements of the
package to avoid collisions.  So for optional tasks, they would go in
optional/vss (to use your example) eliminating namespace collisions.  This
would also work better for third party tasks.

Something I'm considering in the short run, is to ignore the categories
and generate the XML (and respective HTML) in the same directory structure
currently used.  For the most part, the new doc would be a drop in
replacement for the old.   Links to ../CoreTypes, etc. everywhere would
still work.  The category meta info would still be used to generate an
overview page but it would have nothing to do with the physical location
of the files.

What I'd really like is a way of specfying how tasks are classified into
categories at the Ant task level much the way the <group> element works
for javadoc or in an XML file.  That allows much more flexibility in how
things are organized over hard coding all categories in the @ant.task tag
in each task source file.  Which categories a task belongs to is strictly
a documentation issue and not at all related to the behavior of the task.

> > * Also it does not seem that nested elements are processed proeprly - or
> am I
> > missing something. ie Are top level elements and nested elements treated
> > identically? ie will the structure of a nested element be fully documented
> ?
> 
> We're going to work on this.  I haven't had a look at Ara's pointer to the
> recursive templates, but will do so soon and likely integrate that (unless
> Bill beats me to it) into our templates to have it recursively output nested
> elements.  We'll add some "stop" logic for it to cease the recursion when a
> known datatype is found.

Right.  It's not yet recursing on sub elements.  Will see what I can do to
fix this.

> > * Also it would be great to write the task so that only the changed files
> are
> > passed to the xdoclet engine. Because each file generates a separate xml
> then
> > this should not be a problem.
> 
> I think we'd have problems when doing the element recusion then though -
> we'd need all the classes in the XDoclet "model" when generating task
> documentation.

I think getting the dependency checking working well under most cases is
rather important.  If committers have to regenerate all the XML because of
a little change to one task, it won't go over well.  Initially, the task
could handle dependency checking like the <style> or <dvsl> tasks where a
newer source causes the respective target XML to be regenerated.  But if
the XDoclet template is newer, then everything is regenerated.  Handling
other dependencies such as changes to datatypes or source XML's could be
done with <uptodate>.

> > To generate the defaults.properties files you
> > can post-process all the generated xml files to extract filenames as
> > appropriate. This would allows us to have xdoclet fully integrated into
> our
> > buikld process with virtually no speed hit
> 
> True - we'd need to capture the "ignore" flag into the XML files then
> though, which we aren't currently.

Yes, I'd considered that as well.  The problem is both the <dvsl> and
<style> tasks don't have a way to use a fileset is input with only a
single file as output.  I was considering fixing this in the <dvsl> task
or even implementing support for a merge mapper.  However, XDoclet already
has all info for the classes loaded in memory so it's really quick to run
another template to generate a single file like default.properties.  I
used the same technique to have XDoclet generate a single XML file listing
all the tasks which I was then planning on using to generate a table of
contents.  Such an XML file could then be used for many different things
where you wanted a listing of all tasks and datatypes.  In the future, it
could even replace default.properties :) .

> I am also going to add the output of general (currently unrecognized)
> "@ant." tags to the XML so that its extensible and grabs stuff without even
> needing to know about it explicitly.  This will allow us to drop special
> tags in, have them appear in the XML, and then do what we want with them
> later without having to modify the template.
> 
>     Erik

Sounds good Erik.

-Bill

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>