xmlgraphics-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Clay Leeds <the.webmaes...@gmail.com>
Subject Getting XML Graphics Documentation into the SOURCE & BINARY Releases
Date Thu, 06 Jun 2013 05:25:07 GMT
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:


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/

$ 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/

- 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 &
- 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

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,


  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message