Re: documentation!???
Hi, IMHO, mixing website and FOP doc doesn't help. Look at BATIK javadoc: with the current process, there is no chance to manage it correctly. If website and various docs were in separate processes, we could attach easily docs to the appropriate project. I agree with GA's old remark: FOP doc should remain in a xml form to have a chance to get it in either a web form, or a pdf form. On the other side, Website in its current form is very easy to maintain. So, a better solution should be: - FOP doc in FOP project, if possible in a form that can be easily transformed to either html, or pdf (docbook?) - FOP website in markdown format (IMO, repository location has no importance; can be either in XGC CMS or FOP specific CMS - FOP javadoc, in the same way as FOP doc. WDYT? 2013/2/11 Clay Leeds the.webmaes...@gmail.com: On Feb 10, 2013, at 1:03 PM, Glenn Adams gl...@skynav.com wrote: On Sun, Feb 10, 2013 at 10:50 AM, Clay Leeds the.webmaes...@gmail.comwrote: Hi folks, I've eradicated Forrest-based documentation from FOP. Now we need to ensure that FOP builds properly. BTW, I also need to do the same for Batik and XML Graphics Commons, but I thought I'd wait until other folks had a chance to ensure I didn't munge stuff! As for getting documentation into their respective project sources, I'm thinking of one of the following: 1. svn hook to copy the MarkDown docs *to* their respective location *from* the current 'ASF-CMS' (vice ;-) 2. svn hook to copy the MarkDown docs *to* the current 'ASF-CMS' *from* their respective location (versa ;-) I suspect the desired approach would be #2, but the ASF-CMS system is geared toward editing the docs in ASF-CMS, which would make #1 easier. Another possibility would be to somehow create a system to copy the rendered HTML output to the repo… Thoughts? Preferences? My preference is #2, i.e., to keep the doc sources in the same repositories as their non-doc sources. Figures that would be the preference… ;-) I suspect Option #1 be easiest to maintain (and implement). I imagine it working this way: a. Edit the files/pages directly from within the CMS as is currently the case * no change to current web site/documentation editing on the ASF-CMS b. commit the change to see it in STAGING * an SVN hook would need to be created, which copies site changes to the appropriate local repository (FOP, Batik or Commons) c. Check your changes on Staging d. publish the site to see the changes on PRODUCTION Migrating to Option #2 would mean modifying how ASF-CMS works, and we wouldn't be able to edit using the ASF-CMS user-interface. I have to wonder what other projects are doing about this? From what I can tell, most of the others are either Top-Level Projects (TLPs like Apache XML Project, which hosts retired projects Crimson Xindice and which gave birth to XML Graphics, and from whence Xerces Xalan were born), or they're still using a combination of Forrest and/or Maven[2] (e.g., Apache Web Services Project). [1] Apache XML Project http://xml.apache.org [2] http://ws.apache.org - To unsubscribe, e-mail: general-unsubscr...@xmlgraphics.apache.org For additional commands, e-mail: general-h...@xmlgraphics.apache.org -- pascal - To unsubscribe, e-mail: general-unsubscr...@xmlgraphics.apache.org For additional commands, e-mail: general-h...@xmlgraphics.apache.org
Re: documentation!???
Hi folks, I've eradicated Forrest-based documentation from FOP. Now we need to ensure that FOP builds properly. BTW, I also need to do the same for Batik and XML Graphics Commons, but I thought I'd wait until other folks had a chance to ensure I didn't munge stuff! As for getting documentation into their respective project sources, I'm thinking of one of the following: 1. svn hook to copy the MarkDown docs *to* their respective location *from* the current 'ASF-CMS' (vice ;-) 2. svn hook to copy the MarkDown docs *to* the current 'ASF-CMS' *from* their respective location (versa ;-) I suspect the desired approach would be #2, but the ASF-CMS system is geared toward editing the docs in ASF-CMS, which would make #1 easier. Another possibility would be to somehow create a system to copy the rendered HTML output to the repo… Thoughts? Preferences? Clay
Re: documentation!???
On Sun, Feb 10, 2013 at 10:50 AM, Clay Leeds the.webmaes...@gmail.comwrote: Hi folks, I've eradicated Forrest-based documentation from FOP. Now we need to ensure that FOP builds properly. BTW, I also need to do the same for Batik and XML Graphics Commons, but I thought I'd wait until other folks had a chance to ensure I didn't munge stuff! As for getting documentation into their respective project sources, I'm thinking of one of the following: 1. svn hook to copy the MarkDown docs *to* their respective location *from* the current 'ASF-CMS' (vice ;-) 2. svn hook to copy the MarkDown docs *to* the current 'ASF-CMS' *from* their respective location (versa ;-) I suspect the desired approach would be #2, but the ASF-CMS system is geared toward editing the docs in ASF-CMS, which would make #1 easier. Another possibility would be to somehow create a system to copy the rendered HTML output to the repo… Thoughts? Preferences? My preference is #2, i.e., to keep the doc sources in the same repositories as their non-doc sources. I have to wonder what other projects are doing about this?
Re: documentation!???
On Feb 10, 2013, at 1:03 PM, Glenn Adams gl...@skynav.com wrote: On Sun, Feb 10, 2013 at 10:50 AM, Clay Leeds the.webmaes...@gmail.comwrote: Hi folks, I've eradicated Forrest-based documentation from FOP. Now we need to ensure that FOP builds properly. BTW, I also need to do the same for Batik and XML Graphics Commons, but I thought I'd wait until other folks had a chance to ensure I didn't munge stuff! As for getting documentation into their respective project sources, I'm thinking of one of the following: 1. svn hook to copy the MarkDown docs *to* their respective location *from* the current 'ASF-CMS' (vice ;-) 2. svn hook to copy the MarkDown docs *to* the current 'ASF-CMS' *from* their respective location (versa ;-) I suspect the desired approach would be #2, but the ASF-CMS system is geared toward editing the docs in ASF-CMS, which would make #1 easier. Another possibility would be to somehow create a system to copy the rendered HTML output to the repo… Thoughts? Preferences? My preference is #2, i.e., to keep the doc sources in the same repositories as their non-doc sources. Figures that would be the preference… ;-) I suspect Option #1 be easiest to maintain (and implement). I imagine it working this way: a. Edit the files/pages directly from within the CMS as is currently the case * no change to current web site/documentation editing on the ASF-CMS b. commit the change to see it in STAGING * an SVN hook would need to be created, which copies site changes to the appropriate local repository (FOP, Batik or Commons) c. Check your changes on Staging d. publish the site to see the changes on PRODUCTION Migrating to Option #2 would mean modifying how ASF-CMS works, and we wouldn't be able to edit using the ASF-CMS user-interface. I have to wonder what other projects are doing about this? From what I can tell, most of the others are either Top-Level Projects (TLPs like Apache XML Project, which hosts retired projects Crimson Xindice and which gave birth to XML Graphics, and from whence Xerces Xalan were born), or they're still using a combination of Forrest and/or Maven[2] (e.g., Apache Web Services Project). [1] Apache XML Project http://xml.apache.org [2] http://ws.apache.org - To unsubscribe, e-mail: general-unsubscr...@xmlgraphics.apache.org For additional commands, e-mail: general-h...@xmlgraphics.apache.org
Re: documentation!???
Thanks Glenn On 07/02/2013 16:12, Glenn Adams wrote: On Thu, Feb 7, 2013 at 3:43 AM, Chris Bowditch bowditch_ch...@hotmail.comwrote: Hi All, I agree with Glenn's concerns. However as Pascal pointed out we were forced by the Apache board to move to their new website infrastructure. Clay researched that and came up with the current solution which works well for the website, but means the releases don't include documentation. In my mind that is a shame, but I don't know what the solution is. Someone would need to develop a way to copy the documentation for the project being built from the new location in SVN into the release artifacts at build time. I suggest we log a Jira for that so this isn't forgotten. I've created two new JIRA tasks for this (for at least handling the FOP part... the same should apply to Batik and XGC). Previously, doc sources lived in separate per-project repos and were copied by the publish.xml process into the deployment repository. In the new arrangement, the CMS repository is being used both as a source and deployment repo, which I believe is undesirable. We need to move the markdown sources back into the per-project repos and then invoke a new publish process that deploys them to the deployment repository in a manner similar to the former pre-CMS process. I've assigned the new JIRA tasks to Clay. - To unsubscribe, e-mail: general-unsubscr...@xmlgraphics.apache.org For additional commands, e-mail: general-h...@xmlgraphics.apache.org
Re: documentation!???
Hi, IIRC, CMS migration was an Apache requirement. So, I don't think that undoing that is possible. By the way, we can start a new discussion on how to separate website Vs product documentation, the latter coming back to product project. 2013/2/6 Glenn Adams gl...@skynav.com: On Wed, Feb 6, 2013 at 8:43 AM, Pascal Sancho psancho@gmail.com wrote: Hi, 2013/2/6 Glenn Adams gl...@skynav.com: On Wed, Feb 6, 2013 at 4:29 AM, Pascal Sancho psancho@gmail.com wrote: Hi, Since XCG website repository includes now all XCG sub-projects, there should be a Jira entry for that. By include all do you mean includes all documentation for XCG sub-projects? Yes, this is a fact. The whole XCG CMS, with sub-projects parts, is now in its own SVN project, outside XCG projects sources. Can these be migrated back into their own original repositories? I don't recall a discussion of the present organization when we started the move to CMS. -- pascal - To unsubscribe, e-mail: general-unsubscr...@xmlgraphics.apache.org For additional commands, e-mail: general-h...@xmlgraphics.apache.org
Re: documentation!???
Hi All, I agree with Glenn's concerns. However as Pascal pointed out we were forced by the Apache board to move to their new website infrastructure. Clay researched that and came up with the current solution which works well for the website, but means the releases don't include documentation. In my mind that is a shame, but I don't know what the solution is. Someone would need to develop a way to copy the documentation for the project being built from the new location in SVN into the release artifacts at build time. I suggest we log a Jira for that so this isn't forgotten. Thanks, Chris On 07/02/2013 08:19, Pascal Sancho wrote: Hi, IIRC, CMS migration was an Apache requirement. So, I don't think that undoing that is possible. By the way, we can start a new discussion on how to separate website Vs product documentation, the latter coming back to product project. 2013/2/6 Glenn Adams gl...@skynav.com: On Wed, Feb 6, 2013 at 8:43 AM, Pascal Sancho psancho@gmail.com wrote: Hi, 2013/2/6 Glenn Adams gl...@skynav.com: On Wed, Feb 6, 2013 at 4:29 AM, Pascal Sancho psancho@gmail.com wrote: Hi, Since XCG website repository includes now all XCG sub-projects, there should be a Jira entry for that. By include all do you mean includes all documentation for XCG sub-projects? Yes, this is a fact. The whole XCG CMS, with sub-projects parts, is now in its own SVN project, outside XCG projects sources. Can these be migrated back into their own original repositories? I don't recall a discussion of the present organization when we started the move to CMS. - To unsubscribe, e-mail: general-unsubscr...@xmlgraphics.apache.org For additional commands, e-mail: general-h...@xmlgraphics.apache.org
Re: documentation!???
Hi, Since XCG website repository includes now all XCG sub-projects, there should be a Jira entry for that. In the same way, the doc management page should be moved to XCG general website; WDYT? 2013/2/5 Clay Leeds the.webmaes...@gmail.com I'll investigate the ANT stuff. As for including the docs in the dist, I don't believe there's an option at present. I'll investigate that as well. Clay On Feb 5, 2013, at 1:56 PM, Glenn Adams gl...@skynav.com wrote: ok; how about the question about future releases? until now, batik, xgc-commons, and fop could be released with source artifacts that contained document sources; but now, it doesn't seem like that is possible, or at least the dist-src build targets do not go out to collect the new documentation sources and copy them into the generated source artifact; while you are at it, the old publish.xml ant files seem to be obsolete as well; are there any other ant updates needed to rid us of obsolete doc work flow? On Tue, Feb 5, 2013 at 2:17 PM, Clay Leeds the.webmaes...@gmail.comwrote: Hi Glenn, The documentation exists solely in the ASF CMS, and so fop/src/documentation is obsolete. We purposely did not delete the src/documentation path until we were completely sure we weren't going back. I suppose we're there… I'm happy to nuke ye olde documentation Forrest-based 'xdoc' directories. After I do that, I'll update the Document Management page with updated instructions: http://xmlgraphics.apache.org/fop/dev/doc.html On Feb 5, 2013, at 9:44 AM, Glenn Adams gl...@skynav.com wrote: where do we edit documentation now? is fop/src/documentation now obsolete? if so, then why is it still in the tree? how will we do releases and still include documentation if it lives in another tree? -- pascal
Re: documentation!???
On Wed, Feb 6, 2013 at 4:29 AM, Pascal Sancho psancho@gmail.com wrote: Hi, Since XCG website repository includes now all XCG sub-projects, there should be a Jira entry for that. By include all do you mean includes all documentation for XCG sub-projects? I'm personally not comfortable with this arrangement, because it complicates releases and doesn't properly separate distinct project assets. In the same way, the doc management page should be moved to XCG general website; WDYT? 2013/2/5 Clay Leeds the.webmaes...@gmail.com I'll investigate the ANT stuff. As for including the docs in the dist, I don't believe there's an option at present. I'll investigate that as well. Clay On Feb 5, 2013, at 1:56 PM, Glenn Adams gl...@skynav.com wrote: ok; how about the question about future releases? until now, batik, xgc-commons, and fop could be released with source artifacts that contained document sources; but now, it doesn't seem like that is possible, or at least the dist-src build targets do not go out to collect the new documentation sources and copy them into the generated source artifact; while you are at it, the old publish.xml ant files seem to be obsolete as well; are there any other ant updates needed to rid us of obsolete doc work flow? On Tue, Feb 5, 2013 at 2:17 PM, Clay Leeds the.webmaes...@gmail.comwrote: Hi Glenn, The documentation exists solely in the ASF CMS, and so fop/src/documentation is obsolete. We purposely did not delete the src/documentation path until we were completely sure we weren't going back. I suppose we're there… I'm happy to nuke ye olde documentation Forrest-based 'xdoc' directories. After I do that, I'll update the Document Management page with updated instructions: http://xmlgraphics.apache.org/fop/dev/doc.html On Feb 5, 2013, at 9:44 AM, Glenn Adams gl...@skynav.com wrote: where do we edit documentation now? is fop/src/documentation now obsolete? if so, then why is it still in the tree? how will we do releases and still include documentation if it lives in another tree? -- pascal
Re: documentation!???
On Wed, Feb 6, 2013 at 8:43 AM, Pascal Sancho psancho@gmail.com wrote: Hi, 2013/2/6 Glenn Adams gl...@skynav.com: On Wed, Feb 6, 2013 at 4:29 AM, Pascal Sancho psancho@gmail.com wrote: Hi, Since XCG website repository includes now all XCG sub-projects, there should be a Jira entry for that. By include all do you mean includes all documentation for XCG sub-projects? Yes, this is a fact. The whole XCG CMS, with sub-projects parts, is now in its own SVN project, outside XCG projects sources. Can these be migrated back into their own original repositories? I don't recall a discussion of the present organization when we started the move to CMS. I'm personally not comfortable with this arrangement, because it complicates releases and doesn't properly separate distinct project assets. I'm not sure; the whole release process can be now divided into 2 distinct stages: 1/ make the release (decide, build, push, test) 2/ update website/doc and announce when release is ready But I agree that doc should come with the product then added to website. World is not perfect. Let's fix it then. In the same way, the doc management page should be moved to XCG general website; WDYT? 2013/2/5 Clay Leeds the.webmaes...@gmail.com I'll investigate the ANT stuff. As for including the docs in the dist, I don't believe there's an option at present. I'll investigate that as well. Clay On Feb 5, 2013, at 1:56 PM, Glenn Adams gl...@skynav.com wrote: ok; how about the question about future releases? until now, batik, xgc-commons, and fop could be released with source artifacts that contained document sources; but now, it doesn't seem like that is possible, or at least the dist-src build targets do not go out to collect the new documentation sources and copy them into the generated source artifact; while you are at it, the old publish.xml ant files seem to be obsolete as well; are there any other ant updates needed to rid us of obsolete doc work flow? On Tue, Feb 5, 2013 at 2:17 PM, Clay Leeds the.webmaes...@gmail.com wrote: Hi Glenn, The documentation exists solely in the ASF CMS, and so fop/src/documentation is obsolete. We purposely did not delete the src/documentation path until we were completely sure we weren't going back. I suppose we're there… I'm happy to nuke ye olde documentation Forrest-based 'xdoc' directories. After I do that, I'll update the Document Management page with updated instructions: http://xmlgraphics.apache.org/fop/dev/doc.html On Feb 5, 2013, at 9:44 AM, Glenn Adams gl...@skynav.com wrote: where do we edit documentation now? is fop/src/documentation now obsolete? if so, then why is it still in the tree? how will we do releases and still include documentation if it lives in another tree? -- pascal -- pascal - To unsubscribe, e-mail: general-unsubscr...@xmlgraphics.apache.org For additional commands, e-mail: general-h...@xmlgraphics.apache.org
