You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@xmlgraphics.apache.org by Clay Leeds <th...@gmail.com> on 2013/06/06 07:25:07 UTC
Getting XML Graphics Documentation into the SOURCE & BINARY Releases
Hi folks,
I hope you're well!
I've been investigating how to get our documentation into our Source & Binary RELEASEs without requiring the duplicate work of trying to maintain two sets of documentation. I noticed the 'advertisement' from Infra@ plugging their willingness to help projects, and so I reached out, and they recommended `svn:externals`.
Before I proceed, I'd like to get your input on how we should proceed, or if anyone has a 'better' idea. I'm leaning toward including the source MarkDown in the distribution via `svn:externals`, perhaps with a README file pointing at the web for better rendering of the docs.
Here's a link that discusses including common code in an SVN project:
http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-howto-common-projects.html#tsvn-howto-common-externals
That page has three recommendations:
1. Use svn:externals
2. Use a nested working copy
3. Use a relative location
I won't get into the details on those three recommendations, and I'm sure there are other solutions, but `svn:externals` seems logical and simple. The other two aren't appropriate for one reason or another.
In a nutshell, we'd effectively `svn include` the documentation into the respective repos by setting an svn property like this:
=== SAMPLE - BATIK ===
$ svn propget svn:externals batik
documentation/ //svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
===
=== SAMPLE - COMMONS ===
$ svn propget svn:externals commons
documentation/ //svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/commons/
===
=== SAMPLE - FOP ===
$ svn propget svn:externals fop
documentation/ //svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/fop/
===
NOTES:
- the above use RELATIVE TO SCHEME PATHS, which require Subversion 1.5+… ABSOLUTE URLs are the Subversion pre-1.5 alternative, which causes issues when switching between HTTP & HTTPS
- We can't use `svn:externals` for the parent XML Graphics Project, since it is also the parent for Batik, Commons & FOP docs, unless we tie it to specific files (which requires Subversion 1.6+).
There are other Subversion 1.5+ options for specifying the `svn:externals` PATH (e.g., using RELATIVE or ABSOLUTE paths since their on the same system), but I'm not convinced of the benefits:
=== SAMPLE - BATIK (ABSOLUTE URL - Subversion pre-1.5) ===
$ svn propget svn:externals batik
documentation/ http://svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
===
=== SAMPLE - BATIK (ABSOLUTE PATH - Subversion 1.5+) ===
$ svn propget svn:externals batik
documentation/ /repos/asf/xmlgraphics/site/trunk/content/batik/
===
=== SAMPLE - BATIK (RELATIVE PATH - Subversion 1.5+) ===
$ svn propget svn:externals batik
documentation/ ../site/trunk/content/batik/
===
=== SAMPLE - BATIK (RELATIVE TO SCHEME - useful for those accessing via HTTP or HTTPS - Subversion 1.5+) ===
$ svn propget svn:externals batik
documentation/ //svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
===
There is a recommendation that specific revisions are used for `svn:externals`, which helps when you don't have control over the other system. I don't think this is necessary or helpful for TRUNK, although I wonder how tagged branches would be affected… It's possible tagged branches would need a revision to ensure they are STATIC respective to their code/documentation versions. This may require the added step to the RELEASE process of switching the specific Documentation Revision to keep it in sync w CODE.
BTW, I did notice that the Batik portion of the documentation is ~330MB. I was going to start with XML Graphics Commons and see how it worked, before I went to FOP and eventually Batik...
Warm regards,
Clay
Re: Getting XML Graphics Documentation into the SOURCE & BINARY Releases
Posted by Pascal Sancho <ps...@gmail.com>.
Hi Clay,
you are right,
for TRUNK, there is no need to set a specific peg revision. That should be
done for TAGs.
Note that with tools like Tortoise SVN (win only) the interface gives
options to directly set peg revs.
2013/6/6 Clay Leeds <th...@gmail.com>
> Hi folks,
>
> I hope you're well!
>
> I've been investigating how to get our documentation into our Source &
> Binary RELEASEs without requiring the duplicate work of trying to maintain
> two sets of documentation. I noticed the 'advertisement' from Infra@plugging their willingness to help projects, and so I reached out, and they
> recommended `svn:externals`.
>
> Before I proceed, I'd like to get your input on how we should proceed, or
> if anyone has a 'better' idea. I'm leaning toward including the source
> MarkDown in the distribution via `svn:externals`, perhaps with a README
> file pointing at the web for better rendering of the docs.
>
> Here's a link that discusses including common code in an SVN project:
>
>
> http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-howto-common-projects.html#tsvn-howto-common-externals
>
> That page has three recommendations:
> 1. Use svn:externals
> 2. Use a nested working copy
> 3. Use a relative location
>
> I won't get into the details on those three recommendations, and I'm sure
> there are other solutions, but `svn:externals` seems logical and simple.
> The other two aren't appropriate for one reason or another.
>
> In a nutshell, we'd effectively `svn include` the documentation into the
> respective repos by setting an svn property like this:
>
> === SAMPLE - BATIK ===
> $ svn propget svn:externals batik
> documentation/ //
> svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
> ===
>
> === SAMPLE - COMMONS ===
> $ svn propget svn:externals commons
> documentation/ //
> svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/commons/
> ===
>
> === SAMPLE - FOP ===
> $ svn propget svn:externals fop
> documentation/ //
> svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/fop/
> ===
>
> NOTES:
> - the above use RELATIVE TO SCHEME PATHS, which require Subversion 1.5+…
> ABSOLUTE URLs are the Subversion pre-1.5 alternative, which causes issues
> when switching between HTTP & HTTPS
> - We can't use `svn:externals` for the parent XML Graphics Project, since
> it is also the parent for Batik, Commons & FOP docs, unless we tie it to
> specific files (which requires Subversion 1.6+).
>
> There are other Subversion 1.5+ options for specifying the `svn:externals`
> PATH (e.g., using RELATIVE or ABSOLUTE paths since their on the same
> system), but I'm not convinced of the benefits:
>
> === SAMPLE - BATIK (ABSOLUTE URL - Subversion pre-1.5) ===
> $ svn propget svn:externals batik
> documentation/
> http://svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
> ===
>
> === SAMPLE - BATIK (ABSOLUTE PATH - Subversion 1.5+) ===
> $ svn propget svn:externals batik
> documentation/ /repos/asf/xmlgraphics/site/trunk/content/batik/
> ===
>
> === SAMPLE - BATIK (RELATIVE PATH - Subversion 1.5+) ===
> $ svn propget svn:externals batik
> documentation/ ../site/trunk/content/batik/
> ===
>
> === SAMPLE - BATIK (RELATIVE TO SCHEME - useful for those accessing via
> HTTP or HTTPS - Subversion 1.5+) ===
> $ svn propget svn:externals batik
> documentation/ //
> svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
> ===
>
> There is a recommendation that specific revisions are used for
> `svn:externals`, which helps when you don't have control over the other
> system. I don't think this is necessary or helpful for TRUNK, although I
> wonder how tagged branches would be affected… It's possible tagged branches
> would need a revision to ensure they are STATIC respective to their
> code/documentation versions. This may require the added step to the RELEASE
> process of switching the specific Documentation Revision to keep it in sync
> w CODE.
>
> BTW, I did notice that the Batik portion of the documentation is ~330MB. I
> was going to start with XML Graphics Commons and see how it worked, before
> I went to FOP and eventually Batik...
>
> Warm regards,
>
> Clay
>
>
--
pascal
Re: Getting XML Graphics Documentation into the SOURCE & BINARY Releases
Posted by Clay Leeds <th...@gmail.com>.
Hi folks,
I just added the `svn:externals` call for getting the MarkDown docs into the SVN repos for Batik, Commons & FOP. Hopefully it executed correctly…
Here're the `propset` calls I executed:
###
cd commons/trunk
svn propset svn:externals 'docs http://svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/commons' . property 'svn:externals' set on '.'
cd ../../batik/trunk
svn propset svn:externals 'docs http://svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik' . property 'svn:externals' set on '.'
cd ../../fop/trunk
svn propset svn:externals 'docs http://svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/fop' . property 'svn:externals' set on '.'
###
BTW, I didn't get an answer on the questions below, so I blew out my */trunk/build.* changes, and decided to check in just the `svn:externals` properties change by itself…
Cheers! Happy Father's Day!
Clay
On Jun 10, 2013, at 5:53 AM, Clay Leeds <th...@gmail.com> wrote:
> On Jun 7, 2013, at 1:45 AM, Chris Bowditch <bo...@hotmail.com> wrote:
>> Hi Clay,
>>
>> Many thanks for looking into this. Whilst I can't offer an opinion on one solution or the other, I do know this is a problem we need to solve. So I'm +1 for your recommendation.
>
> I'll update index.html file to indicate going to http://xmlgraphics.apache.org/[sup-project] for latest updates...
>
>> The only technical point I would make is that SVN 1.5 is quite old now. We've been using SVN 1.7 for over a year now. Therefore I wouldn't worry about remaining 1.5 compatible, especially given the limitations imposed by 1.5.
>
>
> That's what I thought…
>
> While going through the eradication process, I noticed a couple of issues that I'd like address before I can eradicate the xdoc format from the BUILD process (they're intertwined):
>
> 1. batik/javadoc/ generation is part of the Batik BUILD process (don't know if the other projects are similar), and eradicating Forrest might also eradicate the step that generates this:
>
> http://xmlgraphics.apache.org/batik/javadoc/
>
> Is this something I should be concerned about, or are javadocs built at run-time by IDEs (NetBeans, Eclipse, etc.)?
>
> 2. There is a file generated at the time of build, that builds the /batik/jarDependImg.png (it's currently missing on the 'Installing Batik' page):
>
> http://xmlgraphics.apache.org/batik/install.html
>
> I've uploaded the latest available version of the file and am currently waiting for it to show up on the site…
>
> 3. *MINOR* There's a note in fop/trunk/build.xml about `distclean`:
>
> <!-- It would be better to make dist depend on distclean. But as long as the forrest projectInfo plugin depends on a higher Java version (1.5) than we use for the compilation (1.4), leaving it out enables a workaround -->
>
> Does this mean we could switch to `distclean`? If so, let me know and I'll make that adjustment!
>
> Cheers!
>
> Clay
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: general-help@xmlgraphics.apache.org
Re: Getting XML Graphics Documentation into the SOURCE & BINARY Releases
Posted by Clay Leeds <th...@gmail.com>.
On Jun 7, 2013, at 1:45 AM, Chris Bowditch <bo...@hotmail.com> wrote:
> Hi Clay,
>
> Many thanks for looking into this. Whilst I can't offer an opinion on one solution or the other, I do know this is a problem we need to solve. So I'm +1 for your recommendation.
I'll update index.html file to indicate going to http://xmlgraphics.apache.org/[sup-project] for latest updates...
> The only technical point I would make is that SVN 1.5 is quite old now. We've been using SVN 1.7 for over a year now. Therefore I wouldn't worry about remaining 1.5 compatible, especially given the limitations imposed by 1.5.
That's what I thought…
While going through the eradication process, I noticed a couple of issues that I'd like address before I can eradicate the xdoc format from the BUILD process (they're intertwined):
1. batik/javadoc/ generation is part of the Batik BUILD process (don't know if the other projects are similar), and eradicating Forrest might also eradicate the step that generates this:
http://xmlgraphics.apache.org/batik/javadoc/
Is this something I should be concerned about, or are javadocs built at run-time by IDEs (NetBeans, Eclipse, etc.)?
2. There is a file generated at the time of build, that builds the /batik/jarDependImg.png (it's currently missing on the 'Installing Batik' page):
http://xmlgraphics.apache.org/batik/install.html
I've uploaded the latest available version of the file and am currently waiting for it to show up on the site…
3. *MINOR* There's a note in fop/trunk/build.xml about `distclean`:
<!-- It would be better to make dist depend on distclean. But as long as the forrest projectInfo plugin depends on a higher Java version (1.5) than we use for the compilation (1.4), leaving it out enables a workaround -->
Does this mean we could switch to `distclean`? If so, let me know and I'll make that adjustment!
Cheers!
Clay
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: general-help@xmlgraphics.apache.org
Re: Getting XML Graphics Documentation into the SOURCE & BINARY Releases
Posted by Chris Bowditch <bo...@hotmail.com>.
Hi Clay,
Many thanks for looking into this. Whilst I can't offer an opinion on
one solution or the other, I do know this is a problem we need to solve.
So I'm +1 for your recommendation.
The only technical point I would make is that SVN 1.5 is quite old now.
We've been using SVN 1.7 for over a year now. Therefore I wouldn't worry
about remaining 1.5 compatible, especially given the limitations imposed
by 1.5.
Thanks,
Chris
On 06/06/2013 06:25, Clay Leeds wrote:
> Hi folks,
>
> I hope you're well!
>
> I've been investigating how to get our documentation into our Source & Binary RELEASEs without requiring the duplicate work of trying to maintain two sets of documentation. I noticed the 'advertisement' from Infra@ plugging their willingness to help projects, and so I reached out, and they recommended `svn:externals`.
>
> Before I proceed, I'd like to get your input on how we should proceed, or if anyone has a 'better' idea. I'm leaning toward including the source MarkDown in the distribution via `svn:externals`, perhaps with a README file pointing at the web for better rendering of the docs.
>
> Here's a link that discusses including common code in an SVN project:
>
> http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-howto-common-projects.html#tsvn-howto-common-externals
>
> That page has three recommendations:
> 1. Use svn:externals
> 2. Use a nested working copy
> 3. Use a relative location
>
> I won't get into the details on those three recommendations, and I'm sure there are other solutions, but `svn:externals` seems logical and simple. The other two aren't appropriate for one reason or another.
>
> In a nutshell, we'd effectively `svn include` the documentation into the respective repos by setting an svn property like this:
>
> === SAMPLE - BATIK ===
> $ svn propget svn:externals batik
> documentation/ //svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
> ===
>
> === SAMPLE - COMMONS ===
> $ svn propget svn:externals commons
> documentation/ //svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/commons/
> ===
>
> === SAMPLE - FOP ===
> $ svn propget svn:externals fop
> documentation/ //svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/fop/
> ===
>
> NOTES:
> - the above use RELATIVE TO SCHEME PATHS, which require Subversion 1.5+… ABSOLUTE URLs are the Subversion pre-1.5 alternative, which causes issues when switching between HTTP & HTTPS
> - We can't use `svn:externals` for the parent XML Graphics Project, since it is also the parent for Batik, Commons & FOP docs, unless we tie it to specific files (which requires Subversion 1.6+).
>
> There are other Subversion 1.5+ options for specifying the `svn:externals` PATH (e.g., using RELATIVE or ABSOLUTE paths since their on the same system), but I'm not convinced of the benefits:
>
> === SAMPLE - BATIK (ABSOLUTE URL - Subversion pre-1.5) ===
> $ svn propget svn:externals batik
> documentation/ http://svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
> ===
>
> === SAMPLE - BATIK (ABSOLUTE PATH - Subversion 1.5+) ===
> $ svn propget svn:externals batik
> documentation/ /repos/asf/xmlgraphics/site/trunk/content/batik/
> ===
>
> === SAMPLE - BATIK (RELATIVE PATH - Subversion 1.5+) ===
> $ svn propget svn:externals batik
> documentation/ ../site/trunk/content/batik/
> ===
>
> === SAMPLE - BATIK (RELATIVE TO SCHEME - useful for those accessing via HTTP or HTTPS - Subversion 1.5+) ===
> $ svn propget svn:externals batik
> documentation/ //svn.apache.org/repos/asf/xmlgraphics/site/trunk/content/batik/
> ===
>
> There is a recommendation that specific revisions are used for `svn:externals`, which helps when you don't have control over the other system. I don't think this is necessary or helpful for TRUNK, although I wonder how tagged branches would be affected… It's possible tagged branches would need a revision to ensure they are STATIC respective to their code/documentation versions. This may require the added step to the RELEASE process of switching the specific Documentation Revision to keep it in sync w CODE.
>
> BTW, I did notice that the Batik portion of the documentation is ~330MB. I was going to start with XML Graphics Commons and see how it worked, before I went to FOP and eventually Batik...
>
> Warm regards,
>
> Clay
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: general-help@xmlgraphics.apache.org