docbook / xslt10-stylesheets

XSLT 1.0 Stylesheets for DocBook
99 stars 76 forks source link

provide backward compatibility for system identifier change #201

Open petere opened 4 years ago

petere commented 4 years ago

In docbook-xsl 1.79.2, the system identifier was changed from

 http://docbook.sourceforge.net/release/xsl/current/...

to

 http://cdn.docbook.org/release/xsl/current/...

However, this was done in a backward-incompatible way. So now, in your customization layer or build system, you have to pick one of these URLs, and users who have a different docbook-xsl version installed locally will suffer, either because the stylesheets have to be fetched from a remote server, or the build will fail entirely.

This didn't use to be a real problem in practice because 1.79.2 saw very little adoption, but it's now trickling into various distributions and packagings, and it's becoming a real source of frequent build problems.

This should be fixed by making the supplied catalog files include backward-compatible mappings. For example, the currently built catalog file

<?xml version="1.0" encoding="utf-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <!-- XML Catalog file for DocBook XSL Stylesheets vsnapshot -->
  <rewriteURI uriStartString="https://cdn.docbook.org/release/xsl/current/" rewritePrefix="./"/>
  <rewriteSystem systemIdStartString="https://cdn.docbook.org/release/xsl/current/" rewritePrefix="./"/>
  <rewriteURI uriStartString="https://cdn.docbook.org/release/xsl/snapshot/" rewritePrefix="./"/>
  <rewriteSystem systemIdStartString="https://cdn.docbook.org/release/xsl/snapshot/" rewritePrefix="./"/>
</catalog>

could be expanded to contain the old URI as well, like:

<?xml version="1.0" encoding="utf-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <!-- XML Catalog file for DocBook XSL Stylesheets vsnapshot -->
  <rewriteURI uriStartString="https://cdn.docbook.org/release/xsl/current/" rewritePrefix="./"/>
  <rewriteSystem systemIdStartString="https://cdn.docbook.org/release/xsl/current/" rewritePrefix="./"/>
  <rewriteURI uriStartString="https://cdn.docbook.org/release/xsl/snapshot/" rewritePrefix="./"/>
  <rewriteSystem systemIdStartString="https://cdn.docbook.org/release/xsl/snapshot/" rewritePrefix="./"/>

  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="./"/>
  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="./"/>
  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/snapshot/" rewritePrefix="./"/>
  <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/snapshot/" rewritePrefix="./"/>
</catalog>
ryandesign commented 3 years ago

In docbook-xsl 1.79.2, the system identifier was changed from

 http://docbook.sourceforge.net/release/xsl/current/...

to

 http://cdn.docbook.org/release/xsl/current/...

Be very careful! The old non-namespaced URL

http://docbook.sourceforge.net/release/xsl/current/

must map to the new non-namespaced URL

https://cdn.docbook.org/release/xsl-nons/current/

while the old namespaced URL

http://docbook.sourceforge.net/release/xsl-ns/current/

must map to the new namespaced URL

https://cdn.docbook.org/release/xsl/current/

The request to provide backward compatibility with the old URLs was already made in #65.

ryandesign commented 3 years ago

I also want to point out that in 1.79.2, the CDN URLs are http, not https. I don't know whether the URL matching cares about differences in protocol. If it does, then http CDN backward compatibility URLs are needed as well, now that the CDN URLs were changed to https.