DocBook使用XIncludes指定圖像路徑的方法

設有一DocBook的文檔如下：

<book …
    xml:base="./">
......
<xi:include href="chapter_overview.xml" />

在使用XIncludes導入chapter_overview.xml時，XSL處理器將在該文件的路徑前添加xml.base，因此就成爲“./chapter_overview.xml”，這表示chapter_overview.xml在<book>元素所在文檔的同一目錄下。

這是XIncludes的基本用法。

但在使用XIncludes查找圖像時，卻非簡單。生成HTML或PDF時，XSL查找圖像時基於以下條件進行：

1. 如果是絕對路徑，則按絕對路徑來查找。
2. 如果是相對路徑，且未使用XIncludes，則按fileref指定的路徑查找。
3. 如果是相對路徑，但使用XIncludes，且keep.relative.image.uris="1"，則按fileref指定的路徑查找。
4. 如果是相對路徑，但使用XIncludes，且keep.relative.image.uris="0"，則按xml:base + fileref指定的路徑查找。

此外，生成HTML時keep.relative.image.uris默認值爲1;而生成PDF時keep.relative.image.uris默認值爲0。

因此，當使用了XIncludes後，設有一個名爲test.xml的文件（被上述<book>所在文檔通過XIncludes包含）通過fileref指定了一個相對的圖像路徑：

<imagedata fileref="images/custom/test.jpg" />

在生成HTML時，keep.relative.image.uris默認值爲1，符合第3種情況，則直接按fileref指定的路徑"images/custom/test.jpg"來查找，該路徑相對於所生成的HTML文件。因此，只要文件路徑符合下列條件：

test.html
images
    |--> custom
                |--> test.jpg

圖像就能正常顯示。

而在生成PDF時，由於keep.relative.image.uris默認值爲0，符合第4種情況，則在計算路徑時需添加xml:base的前綴。但xml:base值爲“./”，是相對於xml文件所在的路徑而非相對於所生成的PDF文件所在的路徑，因此當我們需要在另外一個目錄，如Dist，中生成PDF時，則導致找不到相應的圖像。這就導致了使用同一標籤

<imagedata fileref="images/custom/test.jpg" />

生成HTML時圖像正常，而生成PDF卻找不到圖像。

解決的方法是在生成PDF的XSL文件中通過指定img.src.path的方式，可以讓處理器相對於所生成的PDF文件的路徑來查找圖像。

<xsl:param name="img.src.path">Dist/pdf/</xsl:param>

加上上面的配置後，fileref的路徑就會變成"Dist/pdf/images/custom/test.jpg",且是相對於所生成的PDF所在的路徑。因此，只要生成的PDF文件路徑符合下列條件：

Dist
    |--> pdf
             |--> test.pdf
             |--> images
                       |--> custom
                                  |--> test.jpg

生成的PDF文件就能正確地將圖像加進來。

[

注：計算PDF圖像的完整公式是：${img.src.path} + ${xml:base} + ${rev_path} + ${fileref}

上例中，

${img.src.path} = Dist/pdf/

${xml:base} = "./"，在計算路徑時，”./“將被忽略

${rev_path} = 含有imagedata標籤的XML文檔相對於主幹XML文檔的路徑。如：

a.xml是主幹文檔，其中有：

<xi:include href="chapters/b.xml" />

b.xml文檔位於chapters文件夾中，且有：

<imagedata fileref="images/custom/test.jpg" />

則${rev_path} = chapters/

由於這個例子沒有給出這種特殊情況，因此${rev_path}爲空字符串，也將被忽略。

${fileref} = images/custom/test.jpg

因此，上例的結果是${img.src.path} + ${xml:base} + ${rev_path} + ${fileref} = "Dist/pdf/" + "" + "" + "images/custom/test.jpg" = "Dist/pdf/images/custom/test.jpg" 

]

再進一步觀察HTML及PDF圖像所在的路徑，均爲

images
    |--> custom
               |--> test.jpg

因此，

<imagedata fileref="images/custom/test.jpg" />

總能簡化爲：

<imagedata fileref="test.jpg" />

當然，生成PDF的XSL文件需改爲：

<xsl:param name="img.src.path">Dist/pdf/images/custom/</xsl:param>

而生成HTML的XSL文件需改爲：

<xsl:param name="img.src.path">images/custom/</xsl:param>

這樣，既可以簡化了圖像文件的引用路徑，且可以確保同時適用於HTML及PDF的正確生成。