Primer do Projeto de Documentação do FreeBSD para novos colaboradores
Anterior | Capítulo 3 SGML Primer | Próxima

# 3.7 Utilizando entidades para incluir arquivos

As entidades (ambas gerais e de parâmetros) são particularmente úteis quando utilizadas para incluir um arquivo dentro de outro.

## 3.7.1 Utilizando entidades gerais para incluir arquivos

Suponha que você possui algum conteúdo para um livro SGML organizado em arquivos, um arquivo por capítulo, chamados `chapter1.xml`, `chapter2.xml`, e assim por diante, com um arquivo `book.xml` que irá conter estes capítulos.

A fim de utilizar o conteúdo destes arquivos como os valores para as suas entidades, você as declara com a palavra chave `SYSTEM`. Isto direciona o interpretador SGML para utilizar o conteúdo dos arquivos nomeados como o valor da entidade.

Exemplo 3-12. Utilizando entidades gerais para incluir arquivos

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!ENTITY chapter.1 SYSTEM "chapter1.xml">
    <!ENTITY chapter.2 SYSTEM "chapter2.xml">
    <!ENTITY chapter.3 SYSTEM "chapter3.xml">
    <!-- e assim por diante -->
    ]>

    <html>
      <!-- Utilize as entidades para carregar os capítulos -->

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

> Atenção: Quando utilizar uma entidade geral para incluir outros arquivos em um documento, os arquivos que estiverem sendo inclusos (`chapter1.xml`, `chapter2.xml`, etc) não devem iniciar com uma declaração DOCTYPE. Isto é um erro de sintaxe.

## 3.7.2 Utilizando entidades de parâmetro para incluir arquivos

Recorde-se que uma entidade de parâmetro só pode ser utilizada dentro de um contexto SGML. Por que então você desejaria incluir um arquivo dentro de um contexto do SGML?

Você pode utilizar isto para assegurar-se de que você pode reutilizar as suas entidades gerais.

Suponha que você possui muitos capítulos em seu documento, e você reutiliza estes capítulos em dois livros diferentes, cada livro organizando os capítulos de uma forma diferente.

Você pode listar as entidades no topo de cada livro, mas isto rapidamente torna-se incomodo de gerenciar.

Em vez de disso, coloque as definições das suas entidades gerais em um arquivo, e utilize uma entidade de parâmetro para incluir este arquivo dentro do seu documento.

Exemplo 3-13. Utilizando entidades de parâmetro para incluir arquivos.

Primeiro, coloque as suas definições de entidades em um arquivo separado, chamado `chapters.ent`. Este arquivo contém o seguinte:

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

Agora crie uma entidade de parâmetro para referenciar o conteúdo do arquivo. E então utilize a entidade de parâmetro para carregar o arquivo no seu documento, o que tornará todas as entidades gerais disponíveis para uso. Feito isso, utilize as entidades gerais como antes;

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
    <!-- Define uma entidade de parâmetro para carregar as entidades gerais de capitulo -->
    <!ENTITY % chapters SYSTEM "chapters.ent">

    <!-- Agora utilize a entidade de parâmetro para carregar neste arquivo -->
    %chapters;
    ]>

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

## 3.7.3 Para você fazer…

### 3.7.3.1 Utilizando entidades gerais para incluir arquivos

1. Crie três arquivos, `para1.xml`, `para2.xml`, e `para3.xml`.

   Coloque um conteúdo similar ao seguinte em cada arquivo:

       <p>Este é o primeiro parágrafo.</p>

2. Edite o arquivo `example.xml` para que ele se pareça com este:

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

       <html>
         <head>
           <title>Um exemplo de arquivo HTML</title>
         </head>

         <body>
           <p>A versão atual deste documento é: &version;</p>

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

3. Produza o arquivo `example.html` através da normalização do arquivo `example.xml`.

       % osgmlnorm -d example.xml > example.html

4. Carregue o arquivo `example.html` no seu navegador web, e confirme que os arquivos `para`n`.xml` foram incluídos no `example.html`.

### 3.7.3.2 Utilizando uma entidade de parâmetro para incluir arquivos.

> Nota: Você deve ter executado os passos anteriores primeiro.

1. Edite o arquivo `example.xml` para que ele se pareça com este:

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

       <html>
         <head>
           <title>Um exemplo de arquivo HTML</title>
         </head>

         <body>
           <p>A versão atual deste documento é: &version;</p>

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

2. Crie um novo arquivo chamado `entities.xml`, com este conteúdo:

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

3. Produza o arquivo `example.html` através da normalização do arquivo `example.xml`.

       % osgmlnorm -d example.xml > example.html

4. Carregue o arquivo `example.html` no seu navegador web e confirme que os arquivos `para`n`.xml` foram incluídos no arquivo `example.html`.

Anterior | Principal | Próxima
Entidades | Acima | Sessões marcadas

Este, e outros documentos, podem ser obtidos em ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

Para perguntas sobre FreeBSD, leia a documentação antes de contatar <questions@FreeBSD.org>.
Para perguntas sobre esta documentação, envie e-mail para <doc@FreeBSD.org>.