[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

A permanent fix for unstable documentation URL's

From: Jĝrn A Hansen <jornhansen_at_gmail.com>
Date: 2006-02-19 18:29:14 CET


"Cool URL's (like URL's for the TortoiseSVN docs :-) don't change" see
[1] ... or at least they shouldn't IMHO. Some time ago I was bitten by
having a local link to the TSVN docs that was invalid because
chapters/sections was rearranged (maybe it was the introduction of a
new chapter before the DUG in r2869, I can't recall exactly).

There is a solution to avoid this in the future which already is in
use in the 'svnbook'. I would suggest to change the generation of the
TSVN HTML docs into using more stable filenames derived from id
attributes on the chapters and sections like the 'svnbook' does.

From experiments I just made it appears that the DocBook tools used
for TSVN already supports this. All that is required is to add a
`--stringparam use.id.as.filename 1` parameter to the execution of
xsltproc in [2] and then change the rest af the numerical id
attributes in the DocBook sources to something more stable.

These changes for the svnbook were discussed in [3] and [4]. There is
even a small script for replacing DocBook numerical id's in [5] that
use a simple tab delimited mapping file.

The result of this would be:
1. The docbook authors would in the future have the freedom to
rearrange chapters without breaking links from other places again.

2. Link URL's would be more descriptive e.g ending in
"/tsvn-DUG-update.html" instead of "/ch05s05.html"

3. This would of course mean broken URL's when the change is
introduced. So a good time to make the switch would probably either be
"ASAP for the nightly docs from trunk", since 1.3 just went out the
door this allows for maximum soak time before 1.4 or the more
conservative approach "when another major restructuring of the docs
will break the links anyway".

Any thoughts on this?

[1] <http://www.w3.org/Provider/Style/URI>
    Tim Berners-Lee, "the inventor of the WWW" wrote this nice little piece
[2] <http://tortoisesvn.tigris.org/svn/tortoisesvn/trunk/doc/doc.build.include>
[3] <http://www.red-bean.com/pipermail/svnbook-dev/2005-April/000236.html>
[4] <http://www.red-bean.com/pipermail/svnbook-dev/2005-April/000317.html>
[5] <http://svn.red-bean.com/viewcvs/svnbook/trunk/src/tools/idsub.py?view=markup>


To unsubscribe, e-mail: dev-unsubscribe@tortoisesvn.tigris.org
For additional commands, e-mail: dev-help@tortoisesvn.tigris.org
Received on Sun Feb 19 18:29:22 2006

This is an archived mail posted to the TortoiseSVN Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.