Having a problem with xi: and <link>

[robert3L]

Not sure if this is an issue anyone on this forum can address, but here goes. I have a rather large DocBook based Help system inherited quite some time ago. It's DocBook 4.0, and it uses system entities in the master document file to include various other topic files. The problem is that the system has grown to over 400 pages of documentation and really needs to be much more modular.

I am thinking to move to DocBook 4.5 and use xinclude. I am trying to construct a basic framework to give to our developers to see what changes they would need to make to the build script if any.

I've run into a problem with xinclude, where <link> elements are not resolving. I can't tell if it's a problem with the tool, or with the way I have structured my files. I have basically 3 levels:
- master document
- chapter files in different folders
- topic files, in the same folder as the chapter file that xincludes them.

Here is the master document. Chapter files are included with xi: (fallbacks omitted here for simplicity):

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://docbook.org/xml/4.5/docbookx.dtd"

[ <!ENTITY % xinclude SYSTEM "internal/xinclude.mod">

%xinclude;

]>



<part label="III" id="partAdminGuide">

...

<!-- Project Administration chapter -->

        <xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="adminguide/projectadmin/agchProjectAdmin.xml"  />

</part>

Then I have chapter files that include some topic files:
File: adminguide/projectadmin/agchProjectAdmin.xml

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://docbook.org/xml/4.5/docbookx.dtd"

[ <!ENTITY % xinclude SYSTEM "internal/xinclude.mod">

%xinclude;

]>

<chapter label="5" id="agchProjectAdmin">

    <title>Project Administration</title>

    <?dbhtml filename="agchProjectAdmin.html"?>

   <para>SOME TEXT HERE...</para>



<!-- Administrating Projects -->

    <xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="agAdministrateProjects.xml"  />

    

</chapter>

Finally, I have some topic files that get included into a chapter:
File: adminguide/projectadmin/agAdministrateProjects.xml

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<sect1 id="agAdministrateProjects">

    <title>Administrating Projects</title>

    <?dbhtml filename="agAdmininstratProjects.html"?>

    <para>SOME TEXT HERE...</para>

   <sect2 id="admin_projects_externalRepo">

      <title>Using External Repositories</title>

      <para>some text...</para>

      <para>

            <link linkend="admin_projects_externalRepos">Setting Up External Repositories</link>.

      </para>

   </sect2>

</sect1>

The target of the linkend attribute above is in a topic file which is xi included in a different chapter file in a different folder that lives on the same level as the topic and chapter files above.
File: adminguide/portaladmin/agch-PortalAdmin.xml

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://docbook.org/xml/4.5/docbookx.dtd"

[ <!ENTITY % xinclude SYSTEM "internal/xinclude.mod">

%xinclude;

]>



<chapter label="4" id="agch-SystemAdmin">

    <title>System Administration</title>

    <?dbhtml filename="agch-SystemAdmin.html"?>

    <para>SOME TEXT...</para>

    ...

   <!-- Repositories topic -->

      <xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="agConfigRepositories.xml" />

</chapter>

Included topic file agConfigRepositories.xml looks like this:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<sect1 id="admin_projects_externalRepos">

    <?dbhtml filename="agConfigExternalRepos.html"?>

    <title>Setting Up Repositories</title>

    <para>Some text here...</para>

</sect1>

When I validate the master document, everything is valid. But when I validate the chapter file agchProjectAdmin.xml I get an error:

An element with identifier "admin_projects_extrenalRepos must appear in the document"

Apparently that chapter does not know how to resolve the reference to the topic that is xi included in a different chapter file. I don't see anything in the DocBoc doc on xinclude that would help me resolve the error. Maybe I need to change the folder structure? That would be fairly easy at this point, as I'm just prototyping a skeleton. Any suggestions would be much appreciated.

[Radu]

Hi Robert,

So by itself the module is not valid, but the entire publication is self contained and valid.
You can instruct Oxygen that when a module is validated, it should actually validate the main publication XML file.

You can either do this by defining a validation scenario:

http://www.oxygenxml.com/doc/ug-oxygen/ ... nario.html

or by enabling master files support at project level and add in the special Master Files folder the main Docbook XML file:

http://www.oxygenxml.com/doc/ug-oxygen/ ... files.html

Regards,
Radu