This guide is created as self-sample guide is compounded of a few files:
This file containing main XML text.
File containing entities definitions - entitiesusedef.ent
Sample file with parsable XML content - entxml.xml.
The simplest possible entity use it to use identifier string for commonly used characters string. For example we can define entity for author name and use this entity instead of real name. Real name will be inserted in place of entity during parsing time.
If we have defined above entity we can use this identifier in whole text so if we put: &guideauthor; we should get in target text: “Artur Hefczyc”.
Before we can use entities we must have them defined somewhere. The most efficient way is to place all entities in external file and include this file in DOCTYPE declaration. For example, for this tutorial sample entities definition file was created entitiesusedef.ent. To use this file your DOCTYPE declaration should look like:
Example 2. Sample DOCTYPE declaration.
<!DOCTYPE section PUBLIC "-//OASIS//DTD Simplified DocBook XML V4.1.2.5//EN" "http://www.oasis-open.org/docbook/xml/simple/4.1.2.5/sdocbook.dtd" [<!ENTITY % entitiesusedef SYSTEM "entitiesusedef.ent"> %entitiesusedef; ]> |
In Entity definition file there is also variable for including whole, external XML file instead of simple text. The external file name is entxml.xml and it's content is included in example below:
Example 3. Content of external XML file included as entity.
Following XML code in separate file:
<para> This is sample file conaining XML code. It can't contain XML <systemitem>DOCTYPE</systemitem> declaration because it is included to main document as entity value. Entity definition is located in <filename>entitiesusedef.ent</filename> file.</para> |
will result as such text when included as entity:
This is sample file conaining XML code. It can't contain XML DOCTYPE declaration because it is included to main document as entity value. Entity definition is located in entitiesusedef.ent file.
Although entities could be defined in this XML file in XML prolog (DOCTYPE declaration) it is much more convenient to define them in external file. So they can be easily used in other XML documents and also every change of particular entity is easy. Sample entitty definition file (containing all entities used in this file) can looks as follows:
Example 4. Sample entity definition file content.
<!ENTITY guideauthor "Artur Hefczyc"> <!ENTITY samplexmlname "entxml.xml"> <!ENTITY sampleasxml SYSTEM "entxml.xml"> <!ENTITY entdefname "entitiesusedef.ent"> <!ENTITY entdeffile SYSTEM "entitiesusedef.ent"> |
During editing XML document entities use makes sense, however in output target format (HTML or PDF) we want to have entities replaced with expected values. Many of XML processing tools replace entities with their values by default SAXON for example, others need additional parameter to replace entities with their values. xmllint from XMLTools package needs --noent parameter to replace entities with values in result document.