【记录】docbook中的实体entity：从使用在线的entity改为使用本地的entity

【背景】

之前折腾docbook，对于entity，不是很了解。

现在虽然也不是很了解，但是知道一个东西：

之前都是默认使用在线的entity的。

比如，编译html：

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$ make html
=============================== cleaning crifanlib_python html ==============================
rm -rf ../output/html/single/*
=============================== generating crifanlib_python html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
        export XML_DEBUG_CATALOG=1 && \
        xsltproc --xinclude --stringparam callout.graphics 1 --stringparam admon.graphics 1  --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/callouts/ --stringparam admon.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/ --stringparam html.stylesheet file:///D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/crifanlib_python.html docbook_html_crl.xsl crifanlib_python.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Catalogs cleanup
Free catalog entry crl.ent
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
#cp -a  ../output/html/single/
#cp -a
cp -a ./images ../output/html/single/
#rm -rf

其中的：

Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent

指的就是，使用在线的我的网站中的entity，去解析entity。

而此处，实际上是本地已经有了此entity的：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crl.ent

所以，希望去更改配置，达到使用本地的entity的目的。

【折腾过程】

1.看看我之前的：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\catalog\catalog.xml

中，其实是已经设置了本地的entity：

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    
    <public publicId="crl.ent"
        uri="&config_dir;/entity/crl.ent"/>
    
    <!--<system systemId="crl.ent"
        uri="file:///E:/Dev_Root/docbook/dev/config/entity/crl.ent"/>-->

的，但是为何没生效，就需要去研究一下了。

2.看到：

Separate DocBook 5 entities file

感觉像是：

需要在自己引用到entity的xml中，指定entity的路径的，所以去看看，之前自己的docbook的xml中所用的entity的路径是啥。

结果发现，比如：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\books\crifanlib_python\src\ch01_crifanlib_py_intro.xml

中，的确是引用的在线的entity：

<!DOCTYPE chapter
[

<!ENTITY % crl_ent PUBLIC "crl.ent" 'https://www.crifan.com/files/res/docbook/entity/crl.ent'>
%crl_ent;

]>

所以，去改为本地的entity试试：

<!-- <!ENTITY % crl_ent PUBLIC "crl.ent" 'https://www.crifan.com/files/res/docbook/entity/crl.ent'>
%crl_ent; -->
<!ENTITY % crl_ent PUBLIC "crl.ent">
%crl_ent;

结果是：

出错了，无法解析：

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$ make html
=============================== cleaning crifanlib_python html ==============================
rm -rf ../output/html/single/*
=============================== generating crifanlib_python html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
        export XML_DEBUG_CATALOG=1 && \
        xsltproc --xinclude --stringparam callout.graphics 1 --stringparam admon.graphics 1  --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/callouts/ --stringparam admon.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/ --stringparam html.stylesheet file:///D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/crifanlib_python.html docbook_html_crl.xsl crifanlib_python.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
ch01_crifanlib_py_intro.xml:8: parser error : Space required after the Public Identifier
<!ENTITY % crl_ent PUBLIC "crl.ent">
                                   ^
ch01_crifanlib_py_intro.xml:8: parser error : SystemLiteral " or ' expected
<!ENTITY % crl_ent PUBLIC "crl.ent">
                                   ^
ch01_crifanlib_py_intro.xml:8: parser error : SYSTEM or PUBLIC, the URI is missing
<!ENTITY % crl_ent PUBLIC "crl.ent">
                                   ^
ch01_crifanlib_py_intro.xml:9: parser error : PEReference: %crl_ent; not found
%crl_ent;
         ^
crifanlib_python.xml:55: element include: XInclude error : could not load ch01_crifanlib_py_intro.xml, and no fallback was found
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Catalogs cleanup
Free catalog entry crl.ent
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
make: *** [../output/html/single/crifanlib_python.html] Error 6

3.参考：

XIncludes and XML catalogs

想起了那个：

rewriteURI

记得是可以实现：

将上述的entity的在线地址：

https://www.crifan.com/files/res/docbook/entity/crl.ent

映射为本地的地址的。

剩下的，就是去搞懂如何设置了。

4.去试试：

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <rewriteURI
        uriStartString="/home/develop/docbook/config_root/entity/"
        rewritePrefix="https://www.crifan.com/files/res/docbook/entity/" />

试试结果：

输出好像没变化：

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$ make html
=============================== cleaning crifanlib_python html ==============================
rm -rf ../output/html/single/*
=============================== generating crifanlib_python html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
        export XML_DEBUG_CATALOG=1 && \
        xsltproc --xinclude --stringparam callout.graphics 1 --stringparam admon.graphics 1  --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/callouts/ --stringparam admon.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/ --stringparam html.stylesheet file:///D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/crifanlib_python.html docbook_html_crl.xsl crifanlib_python.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Catalogs cleanup
Free catalog entry /home/develop/docbook/config_root/entity/
Free catalog entry crl.ent
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
#cp -a  ../output/html/single/
#cp -a
cp -a ./images ../output/html/single/
#rm -rf

5.然后注意到，好像上述结果写反了，改为：

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <!-- <rewriteURI
        uriStartString="/home/develop/docbook/config_root/entity/"
        rewritePrefix="https://www.crifan.com/files/res/docbook/entity/" /> -->
    <rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="/home/develop/docbook/config_root/entity/" />

试试结果，输出是：

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$ make html
=============================== cleaning crifanlib_python html ==============================
rm -rf ../output/html/single/*
=============================== generating crifanlib_python html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
        export XML_DEBUG_CATALOG=1 && \
        xsltproc --xinclude --stringparam callout.graphics 1 --stringparam admon.graphics 1  --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/callouts/ --stringparam admon.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/ --stringparam html.stylesheet file:///D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/crifanlib_python.html docbook_html_crl.xsl crifanlib_python.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Catalogs cleanup
Free catalog entry https://www.crifan.com/files/res/docbook/entity/
Free catalog entry crl.ent
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
#cp -a  ../output/html/single/
#cp -a
cp -a ./images ../output/html/single/
#rm -rf

貌似也看不出变化。

6.为了验证之前的

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\catalog\catalog.xml

中的：

    <public publicId="crl.ent"
        uri="&config_dir;/entity/crl.ent"/>

是否生效，故意改错为：

    <!-- <public publicId="crl.ent"
        uri="&config_dir;/entity/crl.ent"/> -->
    <public publicId="crl.ent"
        uri="&config_dir;/entity/crifanli.ent"/>
    

结果是：

的确是可以对于文件语法出错检测出来的：

Resolve URI /home/develop/docbook/config_root/entity/crifanli.ent
ch01_crifanlib_py_intro.xml:7: warning: failed to load external entity "https://www.crifan.com/files/res/docbook/entity/crl.ent"
%crl_ent;
         ^
Entity: line 1:
 %crl_ent;
          ^
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Resolve URI /home/develop/docbook/config_root/entity/crifanli.ent
ch02_crifanlib_py_functions.xml:7: warning: failed to load external entity "https://www.crifan.com/files/res/docbook/entity/crl.ent"
%crl_ent;
         ^
Entity: line 1:
 %crl_ent;
          ^

但是还是不确定，该键值是否生效了。

7.去故意把本地的：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crl.ent

的文件名改掉，比如为：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crifanli.ent

看看是否会出错：

结果的确会出错：

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$ make html
=============================== cleaning crifanlib_python html ==============================
rm -rf ../output/html/single/*
=============================== generating crifanlib_python html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
        export XML_DEBUG_CATALOG=1 && \
        xsltproc --xinclude --stringparam callout.graphics 1 --stringparam admon.graphics 1  --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/callouts/ --stringparam admon.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/ --stringparam html.stylesheet file:///D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/crifanlib_python.html docbook_html_crl.xsl crifanlib_python.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Resolve URI /home/develop/docbook/config_root/entity/crl.ent
ch01_crifanlib_py_intro.xml:7: warning: failed to load external entity "https://www.crifan.com/files/res/docbook/entity/crl.ent"
%crl_ent;
         ^
Entity: line 1:
 %crl_ent;
          ^
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Resolve URI /home/develop/docbook/config_root/entity/crl.ent
ch02_crifanlib_py_functions.xml:7: warning: failed to load external entity "https://www.crifan.com/files/res/docbook/entity/crl.ent"
%crl_ent;
         ^
Entity: line 1:
 %crl_ent;
          ^
Catalogs cleanup
Free catalog entry https://www.crifan.com/files/res/docbook/entity/
Free catalog entry crl.ent
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
#cp -a  ../output/html/single/
#cp -a
cp -a ./images ../output/html/single/
#rm -rf

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$

貌似就的确证明了：

此处，的确是：

对于：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\books\crifanlib_python\src\ch01_crifanlib_py_intro.xml

中的：

<!ENTITY % crl_ent PUBLIC "crl.ent" 'https://www.crifan.com/files/res/docbook/entity/crl.ent'>
%crl_ent;

其是找到了PUBLIC的crl.ent，然后根据

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\catalog\catalog.xml

中的：

    <public publicId="crl.ent"
        uri="&config_dir;/entity/crl.ent"/>

去找到本地的：

&config_dir;/entity/crl.ent

即：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crl.ent

但是现在由于我故意改为了：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crifanli.ent

从而找不到，而报错。

8.为了，再进一步验证，去故意把网络断掉，然后看看，是否能正常运行：

如果可以正常运行，那么说明，的确是对于：

crl.ent

的

https://www.crifan.com/files/res/docbook/entity/crl.ent

是映射到本地的：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crl.ent

了。

此处，断网了，去运行试试：

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$ make html
=============================== cleaning crifanlib_python html ==============================
rm -rf ../output/html/single/*
=============================== generating crifanlib_python html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
        export XML_DEBUG_CATALOG=1 && \
        xsltproc --xinclude --stringparam callout.graphics 1 --stringparam admon.graphics 1  --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/callouts/ --stringparam admon.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/ --stringparam html.stylesheet file:///D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/crifanlib_python.html docbook_html_crl.xsl crifanlib_python.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Catalogs cleanup
Free catalog entry https://www.crifan.com/files/res/docbook/entity/
Free catalog entry crl.ent
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
#cp -a  ../output/html/single/
#cp -a
cp -a ./images ../output/html/single/
#rm -rf

很明显，是可以正常运行的，说明的确是本地的映射起了效果了。

8.但是不确定是：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\catalog\catalog.xml

中的：

    <public publicId="crl.ent"
        uri="&config_dir;/entity/crl.ent"/>
    

还是：

    <rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="/home/develop/docbook/config_root/entity/" />

起到了本地映射的效果。

所以先去去掉rewriteURI，保留

public publicId="crl.ent"

即：

    <!-- <rewriteURI
        uriStartString="/home/develop/docbook/config_root/entity/"
        rewritePrefix="https://www.crifan.com/files/res/docbook/entity/" /> -->
    <!-- <rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="/home/develop/docbook/config_root/entity/" /> -->

    <public publicId="crl.ent"
        uri="&config_dir;/entity/crl.ent"/>
    
    <!--<system systemId="crl.ent"
        uri="file:///E:/Dev_Root/docbook/dev/config/entity/crl.ent"/>-->

看看效果：

结果是可以的：

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$ make html
=============================== cleaning crifanlib_python html ==============================
rm -rf ../output/html/single/*
=============================== generating crifanlib_python html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
        export XML_DEBUG_CATALOG=1 && \
        xsltproc --xinclude --stringparam callout.graphics 1 --stringparam admon.graphics 1  --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/callouts/ --stringparam admon.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/ --stringparam html.stylesheet file:///D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/crifanlib_python.html docbook_html_crl.xsl crifanlib_python.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Found public match crl.ent
Catalogs cleanup
Free catalog entry crl.ent
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
#cp -a  ../output/html/single/
#cp -a
cp -a ./images ../output/html/single/
#rm -rf

说明是

public publicId="crl.ent"

起的映射效果。

那么再去去掉

public publicId="crl.ent"

只保留：

rewriteURI

即：

    <!-- <rewriteURI
        uriStartString="/home/develop/docbook/config_root/entity/"
        rewritePrefix="https://www.crifan.com/files/res/docbook/entity/" /> -->
    <rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="/home/develop/docbook/config_root/entity/" />

    <!-- <public publicId="crl.ent"
        uri="&config_dir;/entity/crl.ent"/> -->
    
    <!--<system systemId="crl.ent"
        uri="file:///E:/Dev_Root/docbook/dev/config/entity/crl.ent"/>-->

看看效果：

CLi@PC-CLI-1 ~/develop/docbook/books/crifanlib_python/src
$ make html
=============================== cleaning crifanlib_python html ==============================
rm -rf ../output/html/single/*
=============================== generating crifanlib_python html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
        export XML_DEBUG_CATALOG=1 && \
        xsltproc --xinclude --stringparam callout.graphics 1 --stringparam admon.graphics 1  --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/callouts/ --stringparam admon.graphics.path D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/images/system/ --stringparam html.stylesheet file:///D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/crifanlib_python.html docbook_html_crl.xsl crifanlib_python.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Using rewriting rule https://www.crifan.com/files/res/docbook/entity/
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Using rewriting rule https://www.crifan.com/files/res/docbook/entity/
Catalogs cleanup
Free catalog entry https://www.crifan.com/files/res/docbook/entity/
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
#cp -a  ../output/html/single/
#cp -a
cp -a ./images ../output/html/single/
#rm -rf

可以看到，

其第一步是

由于没了

publicId="crl.ent"

的配置，所以即没了本地映射，所以不会去直接找：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crl.ent

但是，发现之前有设置对应的在线网站地址：

https://www.crifan.com/files/res/docbook/entity/crl.ent

但是由于发现有

rewriteURI，将：

https://www.crifan.com/files/res/docbook/entity/

换成：

/home/develop/docbook/config_root/entity/

所以再去找

替换后的地址：

/home/develop/docbook/config_root/entity/crl.ent

然后就真正找到了本地的entity文件了。

所以，对应输出为：

Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Using rewriting rule https://www.crifan.com/files/res/docbook/entity/

【总结】

此处，关于使用本地实体entity的话，想要通过去映射在线的地址到本地地址，目前至少有2种方法：

背景是：

docbook的xml中，写法是带PUBLIC的，即：

<!DOCTYPE chapter
[

<!ENTITY % crl_ent PUBLIC "crl.ent" 'https://www.crifan.com/files/res/docbook/entity/crl.ent'>
%crl_ent;

]>

然后接下来，有2种方法，可以使得：

https://www.crifan.com/files/res/docbook/entity/crl.ent

映射到本地的：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crl.ent

（对应cygwin的路径是：

/home/develop/docbook/config_root/entity/crl.ent

）

（1）rewriteURI将在线地址改写为本地地址

    <!-- <rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="/home/develop/docbook/config_root/entity/" /> -->
    <rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="&config_dir;/entity/" />

（2）使用publicId，将实体名字的地址变成本地地址

<public publicId="crl.ent"
        uri="&config_dir;/entity/crl.ent"/>

其中：

<!-- ============== UNIFY ============== -->
<!ENTITY config_dir         "/home/develop/docbook/config_root">
<!--<!ENTITY config_dir         "E:/Dev_Root/docbook/dev/config">-->
<!ENTITY xsl_ns_base_cygwin "/home/develop/docbook/tools_root/&docbook_xsl_ns;">
<!--<!ENTITY xsl_ns_base_cygwin "E:/Dev_Root/docbook/tools/&docbook_xsl_ns;">-->

<!-- ============== COMMON ============== -->
<!ENTITY config_xls_ns_dir "&config_dir;/&docbook_xsl_ns;">

目前经过实测，两种都是可以的：

即：

对于上面的：

https://www.crifan.com/files/res/docbook/entity/crl.ent

实际上，都（经过解析而）使用了本地的实体：

D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\entity\crl.ent

而没有用在线的实体。

另外，原以为是个问题的问题：

当在线地址解析为本地地址后，当网络正常的话，是不是发现本地地址失效后，也可以转而回到在线地址尝试去解析的？

结果自己就回答了：

不会。

因为刚才就，在网络还正常的时候，故意把本地entity文件改名，而找不到，结果就报错了。

并没有所期望的，智能的，再返回去使用在线地址。

【后记】

1.后来也试了试，对于catalog中，即没有设置publicId，也没有设置rewriteURI的话，则：

对于crl.ent，的确会按照本身的设置，去访问在线地址：

https://www.crifan.com/files/res/docbook/entity/crl.ent

然后去解析了。

而对于每一个docbook的xml文件中的crl.ent都会去访问在线地址去解析：

Administrator@PC-20130611GART /cygdrive/e/Dev_Root/docbook/dev/books/docbook_dev_note/src
$ make html
=============================== cleaning docbook_dev_note html ==============================
rm -rf ../output/html/single/*
=============================== generating docbook_dev_note html ==============================
export XML_CATALOG_FILES="/home/develop/docbook/config_root/catalog/catalog.xml" && \
export XML_DEBUG_CATALOG=1 && \
xsltproc --xinclude  --stringparam callout.graphics 1  --stringparam admon.graphics 1   --stringparam callout.graphics.number.limit 30 --stringparam callout.graphics.extension .png --stringparam admon.graphics.extension .png --stringparam html.stylesheet.type text/css  --stringparam callout.graphics.path E:/Dev_Root/docbook/dev/config/images/system/callouts/ --stringparam admon.graphics.path E:/Dev_Root/docbook/dev/config/images/system/ --stringparam html.stylesheet file:///E:/Dev_Root/docbook/dev/config/docbook-xsl-ns-1.78.1/html/css/common_html.css -o ../output/html/single/docbook_dev_note.html docbook_html_crl.xsl docbook_dev_note.xml
Resolve: sysID docbook_html_crl.xsl
-2147483592 Parsing catalog /home/develop/docbook/config_root/catalog/catalog.xml
/home/develop/docbook/config_root/catalog/catalog.xml added to file hash
Resolve URI docbook_html_crl.xsl
Found URI match docbook_html_crl.xsl
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve: sysID https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve: sysID https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve: sysID https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve: sysID https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve: sysID https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve: sysID https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve: pubID crl.ent sysID https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/crl.ent
Resolve: sysID https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Resolve URI https://www.crifan.com/files/res/docbook/entity/w3centities-f.ent
Catalogs cleanup
Free catalog entry /home/develop/docbook/tools_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html.xsl
Free catalog entry docbook_fo.xsl
Free catalog entry /home/develop/docbook/config_root/docbook-xsl-ns-1.77.1/
Free catalog entry docbook_html_crl.xsl
Free catalog entry chunk_html_crl.xsl
Free catalog entry docbook_htmlhelp_crl.xsl
Free catalog entry docbook_fo_crl.xsl
Free catalog entry /home/develop/docbook/config_root/catalog/catalog.xml
Free catalog entry
#cp -a  ../output/html/single/
#cp -a
cp -a ./images ../output/html/single/
#rm -rf

Administrator@PC-20130611GART /cygdrive/e/Dev_Root/docbook/dev/books/docbook_dev_note/src
$

所以，速度上，相对的确是要比访问本地的要慢的。

2.

后来证实，由于此处文件夹结构是：

catalog
    |-catalog.xml
    
entity
    |-crl.ent
    |-w3centities-f.ent

所以，上述的catalog中的rewriteURI和publicId，都可以写成相对路径的形式。

分别是：

    <rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="../entity/" />

和：

    <public publicId="crl.ent"
        uri="../entity/crl.ent"/>

也都是可以的。

【总结】

折腾越多，越对这个catalog的机制，有了更深入的了解。

至此：

不论设置成绝对路径，还是本地路径，不论是用rewriteURI还是publicId，都是可以的。

总结如下：

对于docbook的xml中的写法：

<!DOCTYPE chapter
[
<!ENTITY % crl_ent PUBLIC "crl.ent" 'https://www.crifan.com/files/res/docbook/entity/crl.ent'>
%crl_ent;
]>

四中形式分别是：

（1）rewriteURI将在线地址映射为本地绝对路径：

<rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="/home/develop/docbook/config_root/entity/" />

（2）rewriteURI将在线地址映射为本地相对路径：

<rewriteURI
        uriStartString="https://www.crifan.com/files/res/docbook/entity/"
        rewritePrefix="../entity/" />

（3）publicId将在线地址映射为本地绝对路径：

<public publicId="crl.ent"
        uri="/home/develop/docbook/config_root/entity/crl.ent"/>

（4）publicId将在线地址映射为本地相对路径：

<public publicId="crl.ent"
        uri="../entity/crl.ent"/>

如果即没有rewriteURI，也还没有publicId，则：

对于每一个docbook的xml中，如果有如上的PUBLIC的crl.ent，则都会去访问在线地址：

https://www.crifan.com/files/res/docbook/entity/crl.ent

去解析，导致结果是：

如果docbook的xml文件很多，则总体速度就会大大降低。

还是映射为本地地址，执行速度快多了。

转载请注明：在路上 » 【记录】docbook中的实体entity：从使用在线的entity改为使用本地的entity