如何在AsciiDoctor转换DocBook5时添加自定义xmlns:xi命名空间

我完全理解你的需求——要给Asciidoctor转换生成的DocBook5顶层<book>标签加上xmlns:xi="http://www.w3.org/2001/XInclude"命名空间，用来支持XInclude引入Docinfo文件和Passthrough Blocks里的特殊XML内容（比如数学公式）。默认转换确实只带DocBook的默认命名空间，内置属性也只适配DocBook4.5，这里有两个简单可行的解决方法：

方法1：使用内置属性快速添加（推荐） #

Asciidoctor提供了docbook-namespace-attributes属性，专门用来给DocBook根元素添加额外的命名空间或属性。你有两种方式设置这个属性：

方式A：命令行直接指定 #

在转换命令中通过-a参数传递该属性，注意根据shell环境转义引号：

asciidoctor -b docbook5 -d book -a docbook-namespace-attributes="xmlns:xi=\"http://www.w3.org/2001/XInclude\"" -o out.xml source.txt

方式B：在AsciiDoc文档内部定义 #

在你的source.txt开头添加属性设置，这样不用每次命令行都重复输入：

:docbook-namespace-attributes: xmlns:xi="http://www.w3.org/2001/XInclude"

= 你的文档标题
// 剩下的文档内容

执行转换后，生成的<book>标签就会自动带上XInclude的命名空间了。

方法2：自定义DocBook模板实现更灵活控制 #

如果你需要对DocBook输出做更多自定义修改，可以直接修改DocBook5的模板：

1. 找到Asciidoctor的默认DocBook5模板目录（如果是通过gem安装的，路径通常是$(gem which asciidoctor)/../data/templates/docbook5），或者创建一个本地的模板目录。
2. 复制默认的book.xml.erb模板到你的自定义目录，修改其中的<book>标签行，添加XInclude命名空间：

<book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:lang="<%= document.lang %>">

3. 转换时通过-T参数指定你的自定义模板目录：

asciidoctor -b docbook5 -d book -T /path/to/your/custom/templates -o out.xml source.txt

完成后，打开生成的out.xml检查顶层<book>标签，就能看到xmlns:xi属性已经成功添加，接下来就可以正常使用XInclude功能了。

内容的提问来源于stack exchange，提问作者Yasushi Shoji