8. Entities (shortcuts, text macros and re-usable text)

There may be some segments of text, or markup that you want to use over and over again. Instead of typing it up multiple times (and then having to edit it multiple times if you want to make a change) you can use external entities. Entities can give you a short cut to: re-using whole documents, text snippets, and special markup. Some common ways to use an entity would be for:

Example D.12. Adding Entities

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ 
<-- I can add comments here --> 
<!ENTITY shortcut "Replace 'shortcut' with this text."> 

<!ENTITY sc-to-a-file SYSTEM "anotherfile.xml">
<-- note: the square bracket on the third line is closed on the next
line--> ]>
			

To use these entities simply insert the name you gave the entity between a & (ampersand) and a ; (semicolon). For example: &shortcut; would expand into Replace 'shortcut' with this text; &sc-to-a-file; would include the full contents of whatever is in anotherfile.xml.

An important feature while writing a text is the ability to check whether or not it will be presented in the final draft. It is common to have several parts of the text marked as draft, especially when updating an already existing document.

With the use of parameter entities, you can include or eliminate these drafts by altering only one line at the beginning of a document.

Example D.13. Use of parameter entities

<!ENTITY % review "INCLUDE"> ...
<![%review;[ <para>This paragraph will
be included on the draft when the entity "review" is defined with the
value "INCLUDE". </para> ]]>
	

The entity review might have several texts defined, as in Example D.13, “Use of parameter entities”. When the changes to the text are considered final, you need only to remove parts of the text between the 3rd. and 6th. lines.

To keep the draft definitions and hide the text in the final draft, just alter the specification of the entity from INCLUDE to IGNORE.