Can I use entities and xincludes in the same XML file?

[jbzech]

Hi,

I believe it is technically feasible for me to use entities and xincludes in the same XML file. But I believe it is not considered good practice. I'm wondering if anyone could suggest a more orthodox way of doing what I am doing.

I'm working in DocBook 5.0, using a heavily customized XSLT to output a few different formats. We use Subversion to edit our XML across various machines/locations, and the project file with project transformation scenarios to keep everyone on the same page.

Most of my editors and writers are not highly technical, so I am trying to keep the XML as easy to work with as possible.

I use xinclude to separate my book projects into multiple files (chapters, usually), and this works fine.

But I have a series of special characters that I prefer to keep as codes so as to avoid ambiguity in editorial work. For example, I was using – and — in my XML because when using the actual em-dash and en-dash characters, it's hard to tell them apart. To help my editors, I've created a series of easy-to-read entities to replace those codes: &enDash; and &emDash, among others. I put them in an external entities file and pull them into the XML.

My files all start generally like this:

Code: Select all

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

<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" type="xml"?>



<!DOCTYPE book [

<!ENTITY % entities SYSTEM "utilities/entities/entities.ent">

%entities;

]>



<book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf" version="5.0" xml:id="book">

So I'm using both entities and xincludes. My transforms seem to work fine, and my editors seem happy. Is there a problem here I should be watching for? Is there a simpler way to do what I am doing here that doesn't mix the two methods?

Thanks.

[adrian]

Hi,

I don't see any issues with using both entities and XInclude. They don't exclude each other.
XInclude is meant to replace the old method of chunking large documents by using system entities. So now, it's considered bad practice to combine XInclude with such system entities that contribute significantly to the content. In short, don't use an entity if you can easily use an XInclude instead.
But that's not what you're doing here, you're using entities to define some characters, so I don't see a problem with that.

You can find examples of entities being used for DocBook modularity here:
DoxBook XSL: The Complete Guide/Modular DocBook files
and here
DoxBook XSL: The Complete Guide/Modular DocBook files/Shared text entities

Regards,
Adrian

[jbzech]

Thanks, Adrian. That's what I thought. Using xinclude to substitute for characters would be really cumbersome, but I like using xinclude for large files. I'm glad to see they work okay together.

Thanks for your response.