Entities (both general and parameter) are particularly useful when used to include one file inside another.
Suppose you have some content for an XML book organized
into files, one file per chapter, called
chapter1.xml
,
chapter2.xml
, and so forth, with a
book.xml
file that will contain these
chapters.
In order to use the contents of these files as the values
for your entities, you declare them with the
SYSTEM
keyword. This directs the XML
parser to use the contents of the named file as the value of
the entity.
When using general entities to include other files
within a document, the files being included
(chapter1.xml
,
chapter2.xml
, and so on)
must not start with a DOCTYPE
declaration. This is a syntax error because entities
are low-level constructs and they are resolved before
any parsing happens.
Recall that parameter entities can only be used inside an XML context. Why then would you want to include a file within an XML context?
You can use this to ensure that you can reuse your general entities.
Suppose that you had many chapters in your document, and you reused these chapters in two different books, each book organizing the chapters in a different fashion.
You could list the entities at the top of each book, but this quickly becomes cumbersome to manage.
Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within your document.
First, place your entity definitions in a separate file,
called chapters.ent
. This file
contains the following:
Now create a parameter entity to refer to the contents of the file. Then use the parameter entity to load the file into the document, which will then make all the general entities available for use. Then use the general entities as before:
Create three files, para1.xml
,
para2.xml
, and
para3.xml
.
Put content similar to the following in each file:
Edit example.xml
so that it
looks like this:
Produce example.html
by
normalizing example.xml
.
%
xmllint --dropdtd --noent example.xml > example.html
Load example.html
into your web
browser, and confirm that the
para
files have been included in
n
.xmlexample.html
.
You must have taken the previous steps first.
Edit example.xml
so that it
looks like this:
Create a new file,
entities.ent
, with this
content:
Produce example.html
by
normalizing example.xml
.
%
xmllint --dropdtd --noent example.xml > example.html
Load example.html
into your web
browser, and confirm that the
para
files have been included in
n
.xmlexample.html
.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.