Docbook中用XInclude引入源文件至programlisting无显示问题排查

Alright, let's figure out why your main.cpp code isn't showing up in the PDF generated by XMLMind, and fix it step by step.

1. You Forgot the XInclude Namespace Declaration #

This is the most frequent mistake. Your introduction.xml root element must declare the XInclude namespace so the XML processor recognizes the inclusion tags. Add this to your chapter or section root:

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0">

Without the xmlns:xi attribute, XMLMind will ignore the XInclude elements entirely.

2. Incorrect XInclude Syntax Inside <programlisting> #

You probably missed critical attributes or used the wrong structure. Since main.cpp is plain text (not XML), you need to tell the processor to parse it as text, not markup. Here's the correct syntax:

<programlisting>
  <xi:include href="main.cpp" parse="text"/>
</programlisting>

• Path Check: If main.cpp isn't in the same folder as introduction.xml, use a relative path like ../src/main.cpp (double-check the path—wrong paths are a silent failure).
• Why parse="text"? Without this, the processor will try to read main.cpp as XML. Any characters like <, >, or & in your code will break the parse, resulting in an empty frame.

3. XMLMind Isn't Configured to Resolve XIncludes #

XMLMind's default settings might have XInclude resolution turned off. Let's fix that:

• Open XMLMind and go to Tools > Preferences.
• Navigate to XML > XML Parser.
• Make sure the Resolve XInclude checkbox is ticked.
• For PDF builds: Go to Tools > Configure Transformation Scenarios, edit your DocBook-to-PDF scenario, and confirm that XInclude resolution is enabled in the scenario's parameters (look for options related to "XInclude" or "resolve external entities").

4. File Permissions or Missing File #

Double-check that main.cpp exists at the path you specified, and that XMLMind has read access to it. Test with an absolute path (e.g., href="/home/yourname/projects/main.cpp") to rule out relative path errors. If the code shows up with an absolute path, your relative path was incorrect.

5. Handle Special Characters (If Needed) #

If your main.cpp has XML-special characters like &, <, or >, even with parse="text", some processors might throw warnings. To be safe, you can also add syntax highlighting (optional but helpful) and ensure the code is treated as plain text:

<programlisting language="cpp">
  <xi:include href="main.cpp" parse="text"/>
</programlisting>

Here's a complete snippet for introduction.xml to reference:

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0">
  <title>Introduction</title>
  <para>Below is the core source code for our application:</para>
  <programlisting language="cpp">
    <xi:include href="main.cpp" parse="text"/>
  </programlisting>
</chapter>

And confirm your assembly.xml correctly references the chapter:

<book xmlns="http://docbook.org/ns/docbook" version="5.0">
  <xi:include href="introduction.xml"/>
  <!-- Add other chapters/sections here -->
</book>

After fixing these steps, rebuild your PDF—your main.cpp code should now appear in the programlisting frame.

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