如何用com.elovirta.ooxml v1.4将DITA转DOCX时保留XML注释

问题背景 #

使用DITA Open Toolkit 3.7.4、com.elovirta.ooxml插件与Java 17，现有如下DITA源文件：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="_1.0">
    <title>Title</title>
    <body>
        <p>First</p>
        <!--pagebreak-->
        <p>Second</p>
        <p>Third</p>
    </body>
</topic>

默认转换为DOCX时，<!--pagebreak-->这类XML注释会丢失。已尝试添加pagebreaks.xsl处理文件：

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
  <xsl:template match="comment()">
    <xsl:copy-of select="."/>
  </xsl:template>
</xsl:stylesheet>

并在document.xsl中引入该文件：

...  
<xsl:import href="pagebreaks.xsl"/>
<xsl:import href="document.utils.xsl"/>
...

但上述方法无效，需要实现转换后DOCX的document.xml中保留注释，期望输出如下：

...
        <w:p>
            <w:pPr>
                <w:pStyle w:val="BodyText"/>
            </w:pPr>
            <w:r>
                <w:t>First</w:t>
            </w:r>
        </w:p>
        <!--pagebreak-->
        <w:p>
            <w:pPr>
                <w:pStyle w:val="BodyText"/>
            </w:pPr>
            <w:r>
                <w:t>Second</w:t>
            </w:r>
        </w:p>
        <w:p>
            <w:pPr>
                <w:pStyle w:val="BodyText"/>
            </w:pPr>
            <w:r>
                <w:t>Third</w:t>
            </w:r>
        </w:p>
...

解决方案 #

1. 调整XSL导入顺序 #

XSL模板的优先级受导入顺序影响，后导入的模板会覆盖先导入的。将pagebreaks.xsl移至document.utils.xsl之后导入，确保注释处理模板能覆盖默认逻辑：

...  
<xsl:import href="document.utils.xsl"/>
<xsl:import href="pagebreaks.xsl"/>
...

2. 增强注释处理逻辑 #

默认DITA转换流程可能会忽略容器元素（如<body>）下的注释节点，需要显式确保容器元素的所有子节点都被处理。修改pagebreaks.xsl：

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
  <!-- 匹配并拷贝所有XML注释 -->
  <xsl:template match="comment()">
    <xsl:copy-of select="."/>
  </xsl:template>

  <!-- 确保<body>元素的所有子节点（包括注释）都被处理 -->
  <xsl:template match="body">
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>
</xsl:stylesheet>

3. 检查插件默认过滤规则 #

com.elovirta.ooxml插件的默认XSL文件可能存在过滤注释的逻辑，需确认是否有匹配comment()的空模板或过滤规则。如果有，需确保你的模板优先级更高（通过导入顺序或priority属性）。

4. 执行转换并验证 #

运行DITA-OT转换命令：

dita -i your_topic.dita -f ooxml -o output_dir

解压生成的DOCX文件，查看word/document.xml，确认注释是否已保留。

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