xmlgraphics-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chris Bowditch <bowditch_ch...@hotmail.com>
Subject Re: Getting XML Graphics Documentation into the SOURCE & BINARY Releases
Date Fri, 07 Jun 2013 08:45:10 GMT
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


Mime
View raw message