You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Jesse Glick <Je...@netbeans.com> on 2001/02/05 16:08:54 UTC
enormous index.html (was: Re: CVS Freeze and 1.3 Beta1)
Conor MacNeill wrote:
> [snip]
> Over the next two weeks, changes will be limited to bug fixes and
> documentation updates. There is a reasonable amount of outstanding
> documentation required and I will be focussing on that. Patches in that
> area are most welcome.
> [snip]
Speaking of which, index.html is unreasonably large... 262k. In the
NetBeans integration the Ant docs are now bundled into a JavaHelp docs
set, and this one page takes about twenty seconds to render with HotSpot
on. :-) Bad rendering performance is to blame, but does anyone else
think that one HTML page per task or major section (like some optional
tasks already) would be an improvement?
Regards,
-Jesse
--
Jesse Glick <ma...@netbeans.com>
NetBeans, Open APIs <http://www.netbeans.org/>
tel (+4202) 3300-9161 Sun Micro x49161 Praha CR
Re: New manual organization
Posted by Conor MacNeill <co...@cortexebusiness.com.au>.
Glenn,
From: "Glenn McAllister" <gl...@somanetworks.com>
>
> I think we all agreed last release that we needed something better, like
> Anakia or stylebook or whatever. The stopper was we wanted to have
pluggable,
> per task docs that came from their pluggin jars (a la Ant 2).
Still a good idea.
>
> Seeing as something like this was I wanted for the 1.2 release, I'm
certainly
> not going to object. :-) My only comment is that you probably do want to
> break out the optional task docs as well. With them still living in the
main
> index.html, its a little confusing as to why you don't get bumped out the
same
> way you do with the core tasks.
Yep, absolutely. There are these issues and a number of things that would
need to be fixed: task to task links, links to other parts of the old
index.html, etc. This was just a proof of concept thing. I didn't want to
put in more effort than was necessary to show the idea.
The documentation file per task feels right.
> Also, you need a link back from the index of
> tasks to the main page (or one on each content page, but thats harder to
> maintain).
>
OK, good idea.
Conor
RE: Pick one and stick with it...please...
Posted by Peter Donald <do...@apache.org>.
At 01:38 7/2/01 +1100, Conor MacNeill wrote:
>Agreed. People have floated these two in the past. My only exposure is to
>Anakia and that is just for the webpage stuff I did recently. Seems nice.
>
>Is there any common approach across Jakarta projects for documentation?
Most still use stylebook from what I can tell but will most likely move to
anakia. Basically it depends on who is going to maintain it - stylebook is
xsl while anakia is velocity. Anakia is faster and can do more complex
stuff (though I don't think we need it) while stylebook is built on
standards. Either one is good.
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
RE: Pick one and stick with it...please...
Posted by Conor MacNeill <co...@cortexebusiness.com.au>.
> -----Original Message-----
> From: Jon Stevens [mailto:jon@latchkey.com]
> Sent: Wednesday, 7 February 2001 13:35
> To: ant-dev@jakarta.apache.org
> Subject: Pick one and stick with it...please...
>
>
> Hey,
>
> I don't care which you choose...Anakia or Stylebook, but *please* pick ONE
> and use it only. Having two different systems for building the
> same thing is
> a bit silly to say the least.
>
> thanks,
>
> -jon
Agreed. People have floated these two in the past. My only exposure is to
Anakia and that is just for the webpage stuff I did recently. Seems nice.
Is there any common approach across Jakarta projects for documentation?
Conor
Pick one and stick with it...please...
Posted by Jon Stevens <jo...@latchkey.com>.
Hey,
I don't care which you choose...Anakia or Stylebook, but *please* pick ONE
and use it only. Having two different systems for building the same thing is
a bit silly to say the least.
thanks,
-jon
Re: New manual organization
Posted by Glenn McAllister <gl...@somanetworks.com>.
Conor MacNeill wrote:
> As Jesse Glick has pointed out, the index.html file is too large and also
> difficult to maintain. I think our long term direction is to have some form
> of structured documentation system, perhaps based on stylebook or Anakia. I
> don't know enough about those yet to know what is reasonable or applicable.
I think we all agreed last release that we needed something better, like
Anakia or stylebook or whatever. The stopper was we wanted to have pluggable,
per task docs that came from their pluggin jars (a la Ant 2).
> At this time, the major change you will notice is on the "built-in tasks"
> link. A similar approach for optional tasks is of course possible.
>
> I am looking for feedback on this approach and whether we should adopt this
> for the 1.3 release.
Seeing as something like this was I wanted for the 1.2 release, I'm certainly
not going to object. :-) My only comment is that you probably do want to
break out the optional task docs as well. With them still living in the main
index.html, its a little confusing as to why you don't get bumped out the same
way you do with the core tasks. Also, you need a link back from the index of
tasks to the main page (or one on each content page, but thats harder to
maintain).
Glenn McAllister
RE: New manual organization
Posted by Peter Donald <do...@apache.org>.
At 12:21 6/2/01 -0500, Chris Todd wrote:
>I might be willing to be the "Ant documentation guy". I am a dot-com
>refugee (recently laid off), so I've got some free time, and I had been
>wanting to contribute. I am only slightly familiar with anakia, but xml/xsl
>isn't a problem, so I could probably learn stylebook pretty easily. Where
>can I get the docs for using stylebook, or where can I check out the
>stylbook cvs module? I seem to remember that the stylebook cvs repository
>is buried someplace hard to find.
Stylebook CVS details:
:pserver:anoncvs@xml.apache.org:/home/cvspublic
xml-stylebook
You may also want to check out the avalon project at
java.apache.org/framework as I redid all the stylesheets for that into the
jakarta look and feel. It should also be significantly easier to understand
as I removed all the cruft that had accumulated over time (like from the
xml.apache.org styles).
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
Re: AW: New manual organization
Posted by Peter Donald <do...@apache.org>.
At 03:27 7/2/01 +0100, Christoph Wilhelms wrote:
>Jesse,
>
>>Looks great to me--far more friendly to online help. Hopefully not
>>unfriendly to printed help.
>
>Who wants to print an 100+ pages document? It is more useful to print single
>task-docs, guides and how-to's, IMHO. If we want a really printable Ant-Doc
>we should provide a set of .pdf-files! No need at the moment, or what do
>think?
It would be nice in the long run - a few people have asked for such things
(I dismissed them out of hand as we were html based). We just got to make
sure someone knows how to use FOP and we are sweet ;)
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
AW: New manual organization
Posted by Christoph Wilhelms <Ch...@tui.de>.
Jesse,
>Looks great to me--far more friendly to online help. Hopefully not
>unfriendly to printed help.
Who wants to print an 100+ pages document? It is more useful to print single
task-docs, guides and how-to's, IMHO. If we want a really printable Ant-Doc
we should provide a set of .pdf-files! No need at the moment, or what do
think?
Greetings,
Chris
Re: New manual organization
Posted by Jesse Glick <Je...@netbeans.com>.
Conor MacNeill wrote:
> I have now updated the whole manual using the framed approach. Try it out
> here
> http://jakarta.apache.org/~conor/manual/
>
> All of the links between pages are now working.
>
> If nobody has a major problem, I'll commit this into the 1.3 branch as the
> release documentation. I'll pick up Glenn's latest changes then.
Looks great to me--far more friendly to online help. Hopefully not
unfriendly to printed help.
-Jesse
--
Jesse Glick <ma...@netbeans.com>
NetBeans, Open APIs <http://www.netbeans.org/>
tel (+4202) 3300-9161 Sun Micro x49161 Praha CR
Re: New manual organization
Posted by Conor MacNeill <co...@cortexebusiness.com.au>.
Christoph,
From: "Christoph Wilhelms" <Ch...@tui.de>
> I LOVE that approch :-))))!
Thanks.:-)
>
> It seems pretty complete to me - BTW: Will Antidote be part of 1.3? It's
> quite usable, and I like it a lot, but there is still a lot to do until a
> release candidate, IMHO. If we include Antidote, we should link the
> Antidote-Docs!
Antidote will not be part of the binary release. It will be part of the
source build but just to let
people know it is there and to try it out, etc. The documentation will not
be linked, therefore.
>
> Do we need a "no-frames" version? I think everyone has a browser, wich is
> capable of frames, right?
I think frames is OK. Lynx may have trouble. If you don't have frames, the
index.html file has a link to toc.html in the noframes section, which is
sufficient.
Try http://jakarta.apache.org/~conor/manual/toc.html to see what I mean.You
get a few extra windows because of the "target" attributes but probably
would not on a non frames capable browser.
> Additionally: Can we exploit the "Dean's Icons" (like in Antidote) for
> navigation-purpose, mainly in the left frame (home, next, back, etc.)?
>
Perhaps. When it is in CVS, you can send me a patch because I want to
update some of the content next. (depend task , tar and untar updates,
general build process changes).
Conor
RE: New manual organization
Posted by Christoph Wilhelms <Ch...@tui.de>.
I LOVE that approch :-))))!
It seems pretty complete to me - BTW: Will Antidote be part of 1.3? It's
quite usable, and I like it a lot, but there is still a lot to do until a
release candidate, IMHO. If we include Antidote, we should link the
Antidote-Docs!
Do we need a "no-frames" version? I think everyone has a browser, wich is
capable of frames, right?
I am no commiter but my 0.02&: +1 ;-) Great work!
Additionally: Can we exploit the "Dean's Icons" (like in Antidote) for
navigation-purpose, mainly in the left frame (home, next, back, etc.)?
Greetings,
Chris
>Ah, not too bad, but definitely harder than writing code :-)
>
>I have now updated the whole manual using the framed approach. Try it out
>here
>http://jakarta.apache.org/~conor/manual/
>
>All of the links between pages are now working.
>
>If nobody has a major problem, I'll commit this into the 1.3 branch as the
>release documentation. I'll pick up Glenn's latest changes then.
Re: New manual organization
Posted by Conor MacNeill <co...@cortexebusiness.com.au>.
From: "Peter Donald" <do...@apache.org>
>
> I like it ! Great work .. must of taken a while ;)
>
Ah, not too bad, but definitely harder than writing code :-)
I have now updated the whole manual using the framed approach. Try it out
here
http://jakarta.apache.org/~conor/manual/
All of the links between pages are now working.
If nobody has a major problem, I'll commit this into the 1.3 branch as the
release documentation. I'll pick up Glenn's latest changes then.
If you find any problems, let me know.
I think the following optional tasks do not have any documentation
<depend> I'll do that in a day or two
<javah>
<jjtree>
<junitreport>
<mparse>
<starteam>
<stylebook>
<test> what is this?
<wljspc>
If there is documentation available for these, please point me to it.
An Ant logo would be really cool, about now, I think. Should we have some
sort of design contest? I actually quite like Christoph's attempt.
Conor
RE: New manual organization
Posted by Chris Todd <ch...@home.com>.
Never mind about the location of the xml-stylebook module, I found it. Just
let me know if you want me to handle xml-izing the ant docs.
Sincerest regards,
Chris Todd
chris.todd@home.com
410-740-1409
>-----Original Message-----
>From: Chris Todd [mailto:chris.todd@home.com]
>Sent: Tuesday, February 06, 2001 12:21 PM
>To: ant-dev@jakarta.apache.org
>Subject: RE: New manual organization
>
>
>I might be willing to be the "Ant documentation guy". I am a dot-com
>refugee (recently laid off), so I've got some free time, and I had been
>wanting to contribute. I am only slightly familiar with anakia,
>but xml/xsl
>isn't a problem, so I could probably learn stylebook pretty easily. Where
>can I get the docs for using stylebook, or where can I check out the
>stylbook cvs module? I seem to remember that the stylebook cvs repository
>is buried someplace hard to find.
>
>Sincerest regards,
>Chris Todd
>chris.todd@home.com
>410-740-1409
>
>
>>-----Original Message-----
>>From: Peter Donald [mailto:donaldp@apache.org]
>>Sent: Tuesday, February 06, 2001 9:52 AM
>>To: ant-dev@jakarta.apache.org
>>Subject: Re: New manual organization
>>
>>
>>At 01:30 7/2/01 +1100, Conor MacNeill wrote:
>>>As Jesse Glick has pointed out, the index.html file is too large and also
>>>difficult to maintain. I think our long term direction is to have
>>some form
>>>of structured documentation system, perhaps based on stylebook or
>>Anakia. I
>>>don't know enough about those yet to know what is reasonable or
>>applicable.
>>
>>both/either are reasonable and applicable IMHO ;) Just as long as some one
>>takes charge of keeping process done. If we go with stylebook then I can
>>handle that (mainly playing with xslt) however anakia is fine (and faster)
>>if we just use the jakarta-site2 as a dependency. Thou if we want to
>>transform arbitrary xml docs (ala taskdocs DTD instances) then we need
>>someone who is happy to work with velocity which looks simple enough.
>>
>>>In the interim, I have reworked index.html into a collection of
>>HTML files,
>>>one per task. You can find my updated version here
>>>
>>>http://jakarta.apache.org/~conor/
>>
>>I like it ! Great work .. must of taken a while ;)
>>
>>>At this time, the major change you will notice is on the "built-in tasks"
>>>link.
>>
>>Note that the heading still exists in main document.
>>
>>>A similar approach for optional tasks is of course possible.
>>
>>and very desirable ;)
>>
>>>I am looking for feedback on this approach and whether we should
>>adopt this
>>>for the 1.3 release.
>>
>>I think it would be a good idea though it is largely up to you being that
>>you are release manager ;)
>>
>>Cheers,
>>
>>Pete
>>
>>*-----------------------------------------------------*
>>| "Faced with the choice between changing one's mind, |
>>| and proving that there is no need to do so - almost |
>>| everyone gets busy on the proof." |
>>| - John Kenneth Galbraith |
>>*-----------------------------------------------------*
>>
>>
>>---------------------------------------------------------------------
>>To unsubscribe, e-mail: ant-dev-unsubscribe@jakarta.apache.org
>>For additional commands, e-mail: ant-dev-help@jakarta.apache.org
>>
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: ant-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: ant-dev-help@jakarta.apache.org
>
RE: New manual organization
Posted by Chris Todd <ch...@home.com>.
I might be willing to be the "Ant documentation guy". I am a dot-com
refugee (recently laid off), so I've got some free time, and I had been
wanting to contribute. I am only slightly familiar with anakia, but xml/xsl
isn't a problem, so I could probably learn stylebook pretty easily. Where
can I get the docs for using stylebook, or where can I check out the
stylbook cvs module? I seem to remember that the stylebook cvs repository
is buried someplace hard to find.
Sincerest regards,
Chris Todd
chris.todd@home.com
410-740-1409
>-----Original Message-----
>From: Peter Donald [mailto:donaldp@apache.org]
>Sent: Tuesday, February 06, 2001 9:52 AM
>To: ant-dev@jakarta.apache.org
>Subject: Re: New manual organization
>
>
>At 01:30 7/2/01 +1100, Conor MacNeill wrote:
>>As Jesse Glick has pointed out, the index.html file is too large and also
>>difficult to maintain. I think our long term direction is to have
>some form
>>of structured documentation system, perhaps based on stylebook or
>Anakia. I
>>don't know enough about those yet to know what is reasonable or
>applicable.
>
>both/either are reasonable and applicable IMHO ;) Just as long as some one
>takes charge of keeping process done. If we go with stylebook then I can
>handle that (mainly playing with xslt) however anakia is fine (and faster)
>if we just use the jakarta-site2 as a dependency. Thou if we want to
>transform arbitrary xml docs (ala taskdocs DTD instances) then we need
>someone who is happy to work with velocity which looks simple enough.
>
>>In the interim, I have reworked index.html into a collection of
>HTML files,
>>one per task. You can find my updated version here
>>
>>http://jakarta.apache.org/~conor/
>
>I like it ! Great work .. must of taken a while ;)
>
>>At this time, the major change you will notice is on the "built-in tasks"
>>link.
>
>Note that the heading still exists in main document.
>
>>A similar approach for optional tasks is of course possible.
>
>and very desirable ;)
>
>>I am looking for feedback on this approach and whether we should
>adopt this
>>for the 1.3 release.
>
>I think it would be a good idea though it is largely up to you being that
>you are release manager ;)
>
>Cheers,
>
>Pete
>
>*-----------------------------------------------------*
>| "Faced with the choice between changing one's mind, |
>| and proving that there is no need to do so - almost |
>| everyone gets busy on the proof." |
>| - John Kenneth Galbraith |
>*-----------------------------------------------------*
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: ant-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: ant-dev-help@jakarta.apache.org
>
Re: New manual organization
Posted by Peter Donald <do...@apache.org>.
At 01:30 7/2/01 +1100, Conor MacNeill wrote:
>As Jesse Glick has pointed out, the index.html file is too large and also
>difficult to maintain. I think our long term direction is to have some form
>of structured documentation system, perhaps based on stylebook or Anakia. I
>don't know enough about those yet to know what is reasonable or applicable.
both/either are reasonable and applicable IMHO ;) Just as long as some one
takes charge of keeping process done. If we go with stylebook then I can
handle that (mainly playing with xslt) however anakia is fine (and faster)
if we just use the jakarta-site2 as a dependency. Thou if we want to
transform arbitrary xml docs (ala taskdocs DTD instances) then we need
someone who is happy to work with velocity which looks simple enough.
>In the interim, I have reworked index.html into a collection of HTML files,
>one per task. You can find my updated version here
>
>http://jakarta.apache.org/~conor/
I like it ! Great work .. must of taken a while ;)
>At this time, the major change you will notice is on the "built-in tasks"
>link.
Note that the heading still exists in main document.
>A similar approach for optional tasks is of course possible.
and very desirable ;)
>I am looking for feedback on this approach and whether we should adopt this
>for the 1.3 release.
I think it would be a good idea though it is largely up to you being that
you are release manager ;)
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
New manual organization
Posted by Conor MacNeill <co...@cortexebusiness.com.au>.
As Jesse Glick has pointed out, the index.html file is too large and also
difficult to maintain. I think our long term direction is to have some form
of structured documentation system, perhaps based on stylebook or Anakia. I
don't know enough about those yet to know what is reasonable or applicable.
In the interim, I have reworked index.html into a collection of HTML files,
one per task. You can find my updated version here
http://jakarta.apache.org/~conor/
You can either view on-line in the manual directory or copy the
manual.tar.gz file down to see how it is organized.
At this time, the major change you will notice is on the "built-in tasks"
link. A similar approach for optional tasks is of course possible.
I am looking for feedback on this approach and whether we should adopt this
for the 1.3 release.
Comments?
Conor