You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Peter Donald <pe...@apache.org> on 2002/03/06 13:16:39 UTC
[xdocs] Feature Requests
Hi,
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).
* 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.
* 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 ;)
* 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 ?
* 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. 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
--
Cheers,
Pete
------------------------------------------------------------
militant agnostic: i don't know, and you don't know either.
------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Peter Donald <pe...@apache.org>.
On Thu, 7 Mar 2002 10:01, Bill Burton wrote:
> 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.
excellent!
> 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.
+1
> 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.
+1
--
Cheers,
Pete
---------------------------------------------------------------
The difference between genius, and stupidity? Genius has limits
---------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Bill Burton <bi...@progress.com>.
Hi Erik,
I decided to focus on the task overview generation process so I haven't
looked at the recursive element support yet. I want to get that out of
the way and then convert the rest of the manual pages to xdocs. This will
allow a unified way of building the entire manual.
-Bill
Erik Hatcher wrote:
>
> ----- Original Message -----
> From: "Bill Burton" <bi...@progress.com>
>
> > > 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.
>
> Any luck with this, Bill? I've started work on this and hit some hurdles.
> I was short-sighted in thinking we could just add recursion stop logic when
> it hits a known datatype. The one that gave me a stack overflow(!) was And
> (the conditional) - it, of course, can nest another And, and so on and on.
> And is not a datatype. So, I think the trick will be to wrap the pushClass
> functionality into one of our own tags and keep a stack of classes to
> reference and not allow another push if its already in the stack - this is
> all speculation as I haven't tried it yet. I just thought I'd post to see
> if Bill had made any progress on it and to dump my experiment results.
>
> Erik
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
----- Original Message -----
From: "Bill Burton" <bi...@progress.com>
> > 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.
Any luck with this, Bill? I've started work on this and hit some hurdles.
I was short-sighted in thinking we could just add recursion stop logic when
it hits a known datatype. The one that gave me a stack overflow(!) was And
(the conditional) - it, of course, can nest another And, and so on and on.
And is not a datatype. So, I think the trick will be to wrap the pushClass
functionality into one of our own tags and keep a stack of classes to
reference and not allow another push if its already in the stack - this is
all speculation as I haven't tried it yet. I just thought I'd post to see
if Bill had made any progress on it and to dump my experiment results.
Erik
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Peter Donald <pe...@apache.org>.
On Thu, 7 Mar 2002 11:25, Steve Loughran wrote:
> I am not proposing this for 1.5; I think there are enough radical features
> there once costins and the antlib work is finalized (*) that we have way
> too much to test and document. But for the 2.x model, plug in dependencies
> would seem to go with plug in file name mappings
+1
Add in coloring and an easy API usable from scripts and it would be
fantastic. I believe this has actually been added to Ant2, ant1.9 or myrmidon
todo lists ... I forget which at this point in time.
--
Cheers,
Pete
------------------------------------------------
"No. Try not. Do. Or do not. There is no try."
-- Yoda
------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
Ara - consider it done! :)
Erik
----- Original Message -----
From: "Ara Abrahamian" <ar...@yahoo.com>
To: "'Ant Developers List'" <an...@jakarta.apache.org>
Sent: Thursday, March 07, 2002 11:32 AM
Subject: RE: [xdocs] Feature Requests
> > > Maybe we should make them be .x files! :)
> >
> > Or, maybe .xdt (XDoclet Template). This is the same prefix used for
> all
> > tags (XDt:...).
>
> I like it :o)
> Follow this convention; we'll change xdoclet's templates to this
> extension too. OK?
>
> Ara.
>
>
> _________________________________________________________
> Do You Yahoo!?
> Get your free @yahoo.com address at http://mail.yahoo.com
>
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: [xdocs] Feature Requests
Posted by Ara Abrahamian <ar...@yahoo.com>.
> > Maybe we should make them be .x files! :)
>
> Or, maybe .xdt (XDoclet Template). This is the same prefix used for
all
> tags (XDt:...).
I like it :o)
Follow this convention; we'll change xdoclet's templates to this
extension too. OK?
Ara.
_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Bill Burton <bi...@progress.com>.
Hello,
Erik Hatcher wrote:
>
> ----- Original Message -----
> From: "Bill Burton" <bi...@progress.com>
>
> > 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.
>
> It is indeed a convention, but one I feel worthy of breaking because .j ->
> .java
>
> Maybe we should make them be .x files! :)
Or, maybe .xdt (XDoclet Template). This is the same prefix used for all
tags (XDt:...).
> > 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.
>
> You mean -group? What is <group>? I didn't know about -group but just
> looked it up,
Yes, -group for command line javadoc.
> and it certainly seems reasonable to be able to recategorize
> things after the XML has been generated.
The more I think about it, the more reasonable it seems :) .
> > 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>.
>
> I think you and Peter are missing something (or I am!). If we only feed
> JUnitTask.java into XDoclet because only that file changed, then how would
> we enumerate the elements for FormatterElement (addFormat)? You can't
> (again, unless I'm missing something major here).
>
> I don't currently know a solution for this except to wait the minute and a
> half that it takes to generate all of those files for the current Ant
> codebase. Its not like you'd need to run that process for every build, only
> if you wanted to regenerate docs or defaults.properties.
>
> Or we could just keep bugging Ara to get xjavadoc finished! :) (which
> promises multiple times improvement in speed)
Or, process just datatypes first separately. From that, generate a
patternfile listing all datatypes classes. With proper dependency
checking, this wouldn't need to be run very often. If datatypes XML did
need to be generated, this would trigger a full build of the tasks XML.
Then, assuming no datatypes have changed, process the desired tasks based
or dependency information while also including all datatype classes via
the previously generated patternfile.
Would that do it?
> > 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.
>
> Yes - agreed. Adding more and more templates won't affect our processing
> speed much - its the initial javadoc load of the source code that is slow -
> and with the above mentioned issue I'm not sure there is a way around doing
> that full load.
Another issue is that the static XML documentation associated with each
task/datatype can be edited which currently requires regenerating via
XDoclet because the XDoclet template includes the static XML. So there's
yet another dependency. I'd assumed these static XML files should be
located alongside the respective .java files. However, for dependency
purposes, they may have to be located in xdocs/manual/* in the same
relative location as the generated XML and HTML. Then <dependset> can be
used to delete the XDoclet generate XML causing XDoclet to rebuild the XML
for those tasks and datatypes.
For some of these reasons, I've been thinking it would be better to
include the XDoclet generated XML within the static XML rather than the
other way around as it's happening now. This means the XML static file
can be updated to fix many documentation issues without running XDoclet
because the merge is ocurring when the HTML is generated rather than when
the XML is generated. It makes for one less dependency on XDoclet where
it really isn't necessary anyway.
> Erik
-Bill
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Steve Loughran <st...@iseran.com>.
----- Original Message -----
From: "Erik Hatcher" <ja...@ehatchersolutions.com>
To: "Ant Developers List" <an...@jakarta.apache.org>
Sent: Wednesday, March 06, 2002 15:22
Subject: Re: [xdocs] Feature Requests
> I think you and Peter are missing something (or I am!). If we only feed
> JUnitTask.java into XDoclet because only that file changed, then how would
> we enumerate the elements for FormatterElement (addFormat)? You can't
> (again, unless I'm missing something major here).
if commits are an issue, build to a separate location and then only copy
over to CVS those files which differ from the original
../I wonder if we need a better paradigm for uptodateness than just
timestamps; just like with <mapper> you could have a plugin <depender> which
provided dependency rules for tasks like copy, javac, ftp, etc.
the basic depender would be timestamp, but there is the <depends>
implementation on a bytecode driven depender; checksum and 'filesdifferent'
based dependers would do more detailed matching...etc.
I am not proposing this for 1.5; I think there are enough radical features
there once costins and the antlib work is finalized (*) that we have way too
much to test and document. But for the 2.x model, plug in dependencies would
seem to go with plug in file name mappings
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
----- Original Message -----
From: "Bill Burton" <bi...@progress.com>
> 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.
It is indeed a convention, but one I feel worthy of breaking because .j ->
.java
Maybe we should make them be .x 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.
You mean -group? What is <group>? I didn't know about -group but just
looked it up, and it certainly seems reasonable to be able to recategorize
things after the XML has been generated.
> 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>.
I think you and Peter are missing something (or I am!). If we only feed
JUnitTask.java into XDoclet because only that file changed, then how would
we enumerate the elements for FormatterElement (addFormat)? You can't
(again, unless I'm missing something major here).
I don't currently know a solution for this except to wait the minute and a
half that it takes to generate all of those files for the current Ant
codebase. Its not like you'd need to run that process for every build, only
if you wanted to regenerate docs or defaults.properties.
Or we could just keep bugging Ara to get xjavadoc finished! :) (which
promises multiple times improvement in speed)
> 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.
Yes - agreed. Adding more and more templates won't affect our processing
speed much - its the initial javadoc load of the source code that is slow -
and with the above mentioned issue I'm not sure there is a way around doing
that full load.
Erik
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Bill Burton <bi...@progress.com>.
Hello,
Good suggestions, Peter.
Erik Hatcher wrote:
>
> ----- Original Message -----
> From: "Peter Donald" <pe...@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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [xdocs] Feature Requests
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
----- Original Message -----
From: "Peter Donald" <pe...@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.
> * 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??
> * 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!
> * 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.
> * 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.
> 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.
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
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>