FreeBSD 文件計畫入門書
Prev | Chapter 3 SGML Primer | Next

# 3.7 Using entities to include files

Entities (both general and parameter) are particularly useful when used to include one file inside another.

## 3.7.1 Using general entities to include files

Suppose you have some content for an SGML book organized into files, one file per chapter, called `chapter1.sgml`, `chapter2.sgml`, and so forth, with a `book.sgml` 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 SGML parser to use the contents of the named file as the value of the entity.

Example 3-12. Using general entities to include files

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY chapter.1 SYSTEM "chapter1.sgml">
    <!ENTITY chapter.2 SYSTEM "chapter2.sgml">
    <!ENTITY chapter.3 SYSTEM "chapter3.sgml">
    <!-- And so forth -->
    ]>

    <html>
      <!-- Use the entities to load in the chapters -->

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

> Warning: When using general entities to include other files within a document, the files being included (`chapter1.sgml`, `chapter2.sgml`, and so on) must not start with a DOCTYPE declaration. This is a syntax error.

## 3.7.2 Using parameter entities to include files

Recall that parameter entities can only be used inside an SGML context. Why then would you want to include a file within an SGML 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.

Example 3-13. Using parameter entities to include files

First, place your entity definitions in a separate file, called `chapters.ent`. This file contains the following:

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

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:

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!-- 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>
      &chapter.1;
      &chapter.2;
      &chapter.3;
    </html>

## 3.7.3 For you to do...

### 3.7.3.1 Use general entities to include files

1. Create three files, `para1.sgml`, `para2.sgml`, and `para3.sgml`.

   Put content similar to the following in each file:

       <p>This is the first paragraph.</p>

2. Edit `example.sgml` so that it looks like this:

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
       <!ENTITY version "1.1">
       <!ENTITY para1 SYSTEM "para1.sgml">
       <!ENTITY para2 SYSTEM "para2.sgml">
       <!ENTITY para3 SYSTEM "para3.sgml">
       ]>

       <html>
         <head>
           <title>An example HTML 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.sgml`.

       % sgmlnorm -d example.sgml > example.html

4. Load `example.html` into your web browser, and confirm that the `para`n`.sgml` files have been included in `example.html`.

### 3.7.3.2 Use parameter entities to include files

> Note: You must have taken the previous steps first.

1. Edit `example.sgml` so that it looks like this:

       <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
       <!ENTITY % entities SYSTEM "entities.sgml"> %entities;
       ]>

       <html>
         <head>
           <title>An example HTML file</title>
         </head>

         <body>
           <p>The current version of this document is: &version;</p>

           &para1;
           &para2;
           &para3;
         </body>
       </html>

2. Create a new file, `entities.sgml`, with this content:

       <!ENTITY version "1.1">
       <!ENTITY para1 SYSTEM "para1.sgml">
       <!ENTITY para2 SYSTEM "para2.sgml">
       <!ENTITY para3 SYSTEM "para3.sgml">

3. Produce `example.html` by normalizing `example.sgml`.

       % sgmlnorm -d example.sgml > example.html

4. Load `example.html` into your web browser, and confirm that the `para`n`.sgml` files have been included in `example.html`.

Prev | Home | Next
Entities | Up | Marked sections

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

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