2.5. Docbook开发过程中的一些有用的提示

2.5.1. Docbook最佳实践

此处总结一些,在写docbook源码的时候,一些常见的做法。

这些做法,多数都是我自己总结出来的,仅作参考。

2.5.1.1. Docbook中id的命名规则

在给docbook的元素添加id(或xml:id)属性的时候,名字的命名,我的做法是:

表 2.1. Docbook中id命名规则

Docbook元素 id命名规则 举例
figure fg.xxx
<figure xml:id="fg.npp_code_collapse"><title>XML文件中的Notepad++的代码折腾功能</title>
table tbl.xxx
<table xml:id="tbl.docbook_id_abbrev"><title>Docbook中id命名规则</title>
example eg.xxx
<example xml:id="eg.npp_show_special_char"><title>Notepad++可以查看特殊字符的用途举例</title>
某section xxx
<sect1 xml:id="docbook_dev_notes"><title>Docbook开发过程中的一些有用的提示</title>
co和callout co.xxx和co.note.xxx

<programlistingco>
    <programlisting>
    ...
&lt;revhistory<co id="co.revh" linkends="co.note.revh" /> text-align="left"
    ...
    </programlisting>
    <calloutlist>
        <callout id="co.note.revh" arearefs="co.revh">
            ...
        </callout>
        ...
    </calloutlist>
</programlistingco>

                                

  1. 最新的stylesheet:xsl-ns

    想要去下载最新的xsl-ns,可以去这里下载:DocBook Project Snapshots,其中有最新的xsl-ns下载。

  2. 参数

    docbook-xsl-ns-1.76.1\fo下面,有个param.xsl,该文件是对应的param.xml生成出来的。

    该文件中包括了,所有的参数的默认的设置。而对应的每一个参数,都还有一个对应的配置文件,都放在了docbook-xsl-ns-1.76.1\params路径下了。

    之所以说这个,是因为,关于各种参数的配置,最开始是没有头绪,找不到哪些内容都有哪些参数去控制输出的效果。现在找到了这些,就可以在遇到问题的时候,来找找这些参数了。

  3. NS=namespace

    关于xsl配置文件,之前叫做docbook-xsl-1.76.1,后来又有个docbook-xsl-ns-1.76.1

    其中的ns,意思是namespace的意思,即支持命名空间版本的xsl

  4. formal的含义

    参考Graphics而知道了之前就想要知道的formal的含义:formal是包含了figure, table, example和equation的

  5. 只包含部分内容

    根据Using XIncludes with DocBook 5中的描述,如果想要只包含(include)某个xml文件的其中一部分内容,比如某个章节,也是可以通过include相应的xml:id去实现的此需求的。

    详情参考:Selecting part of a file

  6. 关于xml文件中,为何不直接写id而要写xml:id

    之前一直没搞懂,为何很多地方,在解释在xml文件中的添加某个id的时候,写成xml:id,而为何不直接写id,毕竟很多地方,也都是这么写的,为何还非要麻烦地写成xml:id呢?

    后来在学习了xml的命名空间namespace之后,才知道,原来为由于docbook5中,会通过:

    
    <book version="5.0"
        xmlns="http://docbook.org/ns/docbook"
        xmlns:xi="http://www.w3.org/2001/XInclude"
        xmlns:xl="http://www.w3.org/1999/xlink"
        >
    
                        

    的写法,设置默认的命名空间(default namespace)为http://docbook.org/ns/docbook,通过也添加了xi和xl的命令空间。

    因此,在xml文件中,如果直接写id的话,其实意味着是属于docbook的属性的id,此处由于id没有和其他关键字冲突,所以,xml:id和id都是可以的,只是前者更加能保证不会发生关键字冲突。

    相应的,如果是别的某个关键字,而多个域名中都可能会出现,则必须要添加对应的命名空间的前缀了。

    比如我之前遇到的,将ulink改为link的时候,在写<link xl:href="xxx">的时候,如果写成<link href="xxx">,即没有加xl的命名空间的话,则生成出来的HTML和PDF中,都是没有链接的效果的,必须写成xl:href才可以的。

    所以,更好的习惯,还是写成xml:id之类的,添加了命名空间的形式,这样更加准确,也可以避免未来可能的和其他命名空间发生关键字冲突的问题。