7.7. 在引用檔使用 Entities

Both general and parameter entities are particularly useful for including one file inside another.

7.7.1. 在引用檔使用一般 Entities

Consider 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 that will contain these chapters.

In order to use the contents of these files as the values for entities, they are declared with the SYSTEM keyword. This directs the XML parser to include the contents of the named file as the value of the entity.

範例 7.10. 在引用檔使用一般 Entities
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">
<!-- And so forth -->
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  <!-- Use the entities to load in the chapters -->

  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>

警告:

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.

7.7.2. 在引用檔使用參數 Entities

Parameter entities can only be used inside an XML context. Including a file in an XML context can be used to ensure that general entities are reusable.

Suppose that there are many chapters in the document, and these chapters were reused in two different books, each book organizing the chapters in a different fashion.

The entities could be listed at the top of each book, but that quickly becomes cumbersome to manage.

Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within the document.

範例 7.11. 在引用檔使用參數 Entities

Place the entity definitions in a separate file called chapters.ent and containing this text:

<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">

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:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!-- Define a parameter entity to load in the chapter general entities -->
<!ENTITY % chapters SYSTEM "chapters.ent">

<!-- Now use the parameter entity to load in this file -->
%chapters;
]>

<html xmlns="http://www.w3.org/1999/xhtml">
  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>

7.7.3. 待辦事項...

7.7.3.1. 在引用檔使用一般 Entities

  1. Create three files, para1.xml, para2.xml, and para3.xml.

    Put content like this in each file:

    <p>This is the first paragraph.</p>
  2. Edit example.xml so that it looks like this:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
    <!ENTITY version "1.1">
    <!ENTITY para1 SYSTEM "para1.xml">
    <!ENTITY para2 SYSTEM "para2.xml">
    <!ENTITY para3 SYSTEM "para3.xml">
    ]>
    
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>An Example XHTML File</title>
      </head>
    
      <body>
        <p>The current version of this document is: &version;</p>
    
        &para1;
        &para2;
        &para3;
      </body>
    </html>
  3. Produce example.html by normalizing example.xml.

    % xmllint --dropdtd --noent example.xml > example.html
  4. Load example.html into the web browser and confirm that the paran.xml files have been included in example.html.

7.7.3.2. 在引用檔使用參數 Entities

注意:

The previous steps must have completed before this step.

  1. Edit example.xml so that it looks like this:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
    <!ENTITY % entities SYSTEM "entities.ent"> %entities;
    ]>
    
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>An Example XHTML File</title>
      </head>
    
      <body>
        <p>The current version of this document is: &version;</p>
    
        &para1;
        &para2;
        &para3;
      </body>
    </html>
  2. Create a new file called entities.ent with this content:

    <!ENTITY version "1.1">
    <!ENTITY para1 SYSTEM "para1.xml">
    <!ENTITY para2 SYSTEM "para2.xml">
    <!ENTITY para3 SYSTEM "para3.xml">
  3. Produce example.html by normalizing example.xml.

    % xmllint --dropdtd --noent example.xml > example.html
  4. Load example.html into the web browser and confirm that the paran.xml files have been included in example.html.

本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

若有 FreeBSD 方面疑問,請先閱讀 FreeBSD 相關文件,如不能解決的話,再洽詢 <questions@FreeBSD.org>。

關於本文件的問題,請洽詢 <doc@FreeBSD.org>。