| View previous topic :: View next topic |
| Author |
Message |
miket
Guru
Joined: 28 Apr 2007
Posts: 488
Location: Gainesville, FL, USA
|
 Posted: Mon Oct 14, 2013 3:25 pm Post subject: Docbook stylesheets path [with what I think is a solution] |
 |
|
Most references on the internet that describe the generation of docbook documents inform you that Docbook 5 stylesheets are to be found under the path | Code: | | /usr/share/xml/docbook/xsl-ns-stylesheets/ |
. For some reason for which I have never seen an explanation, Gentoo uses the path | Code: | | /usr/share/sgml/docbook/xsl-ns-stylesheets/ |
Is there an environment variable available to tell you which to use? NO there isn't. Not a standard one from the upstream, and not one specific to Gentoo.
If I were using the handy wrapper script xmlto I might not have to worry so much about the problem. Distribution maintainers can easily patch the package so that it already knows the correct path to use. Alas, that's no help to me. As flameeyes pointed out five years ago, xmlto lacks support for Relax-NG validation of Docbook 5 and assumes that if you're going to get validation at all, it has to be via DTD's (ugh!)
So, as flameeyes points out in his blog post, this leaves me with running xsltproc directly. This isn't so bad--except for the fact that I need to have the full pathname. How can I do this portably?
In the end, a wrapper like xmlto still would not help me out of a deeper pathname problem: when I need to supply XSL customizations, the new stylesheet has to have the pathname for the main set of XSL files. It would be great if this worked | Code: | <?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="html/docbook.xsl"/>
<!-- customizations -->
</xsl:stylesheet> |
I am astounded I can find no mention of this issue at all, especially since I suspect it might be at the root of a number of bug reports related to failures to generate documentation.
After more digging through man pages and references on the internet I have come away with a solution to the problem. I don't know if the is the right, good, and preferable one, but this works.
The xsltproc documentation lists a --path parameter to set up a search path for files. I couldn't make this work. The man page also refers to the environment variables SGML_CATALOG_FILES and XML_CATALOG_FILES, which seem to be a holdover from the bad old days of SGML and DTD's. There is an SGML_CATALOG_FILES environment variable in Gentoo, but the files it points to are full of DTD-ness. What I found, though, is that the URI for an xsl:import element may be a pathname or a web address. It turns out that XML catalogs establish mappings from web addresses to local file names, so now I can find my path. In fact, xsltproc defaults to /etc/xml/catalog when XML_CATALOG_FILES is not set, and Gentoo does fill in that file correctly. This leaves me with a customization file like this. It's funky, but it works. | Code: | <?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/html/docbook.xsl"/>
<!-- customizations -->
</xsl:stylesheet> |
I never suspected that the existence of Sourceforge was so vital to the operation of standard packages! |
|
| Back to top |
|
 |
nemectic
Apprentice
Joined: 20 Aug 2004
Posts: 182
|
| Posted: Mon Oct 14, 2013 5:00 pm Post subject: |
|
|
| Most of that went way over my head, can't you just symlink the directory though? |
|
| Back to top |
|
|
miket
Guru
Joined: 28 Apr 2007
Posts: 488
Location: Gainesville, FL, USA
|
| Posted: Mon Oct 14, 2013 5:30 pm Post subject: |
|
|
| nemectic wrote: | | Most of that went way over my head, can't you just symlink the directory though? |
That's an idea, but there are two problems: 1. it's not portable, and 2. the entries under /usr/share/ are best managed by the package system and not by hand. Besides that, I'm looking for a setup that's amenable to a non-root user.
One big constraint comes from XSL. The xsl:include element leaves no way to pass in a parameter as the path name. It's inconvenient, but that's where it is. |
|
| Back to top |
|
|
|
|
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
|
|
Portage & Programming
