Created attachment 22861 [details] Documentation fixes Currently the site documentation (see URL) is missing information for several latest updates. The proposed changes include: * Reflect Java 1.3 support removed * (revision 666001) * Missing documentation for window.postURL * (already implemented for a while, just not documented [1]) * Missing documentation for window.location * (recently implemented [2], revisions 712954, 712955) * Mention Window Object [3] standard * (within the scripting support, "status.xml") * Add JRE as an alternative requirement and add note for JDK regarding compilation * (only JDK was listed as requirement in "faq.xml") * (clearing JDK need for compilation, although intuitive for advanced users, can be useful for starters) * References to Batik version 1.6 changed to 1.7 * (although only used for example purposes, 1.7 is around for a while) [1] http://xmlgraphics.apache.org/batik/status.html#ecmascript [2] https://issues.apache.org/bugzilla/show_bug.cgi?id=46072 [3] http://www.w3.org/TR/Window/
Created attachment 23093 [details] Documentation fixes v2 One more added to the previous items: * Fix typo in http://xmlgraphics.apache.org/batik/using/scripting/ecmascript.html
I'm thinking if it would be a good idea to add a FAQ item regarding the out of memory issues that haunt the mailing list [1] and the bug tracker itself (bug 44164 [2] and , for example). This was also already explicitly asked for in the mailing list [3]. If it sounds good, I'll be glad to update the current patch. :-) Regards, Helder Magalhães [1] http://www.nabble.com/forum/Search.jtp?forum=308&local=y&query=out+of+memory [2] https://issues.apache.org/bugzilla/show_bug.cgi?id=44164 [3] http://www.nabble.com/FAQ---Memory-td13530949.html#a13530949
I believe there might be interest in breaking this down, in order to allow a commit whenever possible and a later commit (potentially creating a separate bug report) for dealing with things which only make sense after the next release (such as java 1.3 drop and the new window.location interfaces). Does this make sense? Apart from this, I recently stumbled at bug 43950, which could also be addressed within this patch. Should it (by creating a bug dependency), or was it better to create two separate patches?
(In reply to comment #3) > I believe there might be interest in breaking this down, in order to allow a > commit whenever possible and a later commit (potentially creating a separate > bug report) for dealing with things which only make sense after the next > release (such as java 1.3 drop and the new window.location interfaces). Does > this make sense? It brings up a good point. What version of Batik the site documentation reflect? In the Status page at least, I have just had it describe whatever the current SVN trunk can do. FOP has separate pages for trunk vs releases. Duplicating all of the documentation for trunk vs release doesn't seem like a nice way to present it, IMO. There aren't that many changes in trunk vs the 1.7 release anyway, so perhaps the documentation can reflect trunk functionality, but with notes stating if certain aspects are since the release? WDYT? > Apart from this, I recently stumbled at bug 43950, which could also be > addressed within this patch. Should it (by creating a bug dependency), or was > it better to create two separate patches? If you could create a separate patch and attach it to that bug, that would be better I think.
(In reply to comment #4) > It brings up a good point. What version of Batik the site documentation > reflect? In the Status page at least, I have just had it describe whatever > the current SVN trunk can do. FOP has separate pages for trunk vs releases. I was generally thinking that the documentation was meant to reflected the last release, but now that you pointed out the status page, I remember so it seems that this is unclear (you have my memory refreshed )... :-| > Duplicating all of the documentation for trunk vs release doesn't seem like a > nice way to present it, IMO. There aren't that many changes in trunk vs the > 1.7 release anyway, so perhaps the documentation can reflect trunk > functionality, but with notes stating if certain aspects are since the > release? > WDYT? My 2 cents go for having the documentation always reflect the trunk status. One could use something like the @since javadoc keyword for stating newly introduced features, but I'm not sure if this can become confusing for users. I also like the idea of only stating the relevant differences of trunk vs. last release, but this means that changes need to be tracked down whenever a new version is released... I'm comfortable with any of these, please post your opinion(s) and I'll try to review the patch whenever possible. > If you could create a separate patch and attach it to that bug, that would be > better I think. OK, I'll take a look at that whenever possible. ;-)
(In reply to comment #0) > The proposed changes include: > > * Reflect Java 1.3 support removed > * (revision 666001) > * Add JRE as an alternative requirement and add note for JDK regarding > compilation > * (only JDK was listed as requirement in "faq.xml") > * (clearing JDK need for compilation, although intuitive for advanced users, > can be useful for starters) Done in revision 1004565. > * Missing documentation for window.postURL > * (already implemented for a while, just not documented [1]) > * Missing documentation for window.location > * (recently implemented [2], revisions 712954, 712955) Done in revision 1004572. > * Mention Window Object [3] standard > * (within the scripting support, "status.xml") Reworked to use the proper SVG 1.2 Tiny DOM interface instead. > * References to Batik version 1.6 changed to 1.7 > * (although only used for example purposes, 1.7 is around for a while) Reverted this: using 1.6 for examples is fine. (In reply to comment #4) > Duplicating all of the documentation for trunk vs release doesn't seem like a > nice way to present it, IMO. There aren't that many changes in trunk vs the > 1.7 release anyway, so perhaps the documentation can reflect trunk > functionality, but with notes stating if certain aspects are since the release? > WDYT? Added a note to the location interface stating it's available since version 1.8. ;-) > > Apart from this, I recently stumbled at bug 43950, which could also be > > addressed within this patch. Should it (by creating a bug dependency), or was > > it better to create two separate patches? > > If you could create a separate patch and attach it to that bug, that would be > better I think. That issue was (already) fixed in a separate commit. :-)