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

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>
```

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>

Produza o arquivo example.html através da normalização do arquivo example.xml.
```
% osgmlnorm -d example.xml > example.html
```
Carregue o arquivo example.html no seu navegador web, e confirme que os arquivos paran.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.

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>

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">

Produza o arquivo example.html através da normalização do arquivo example.xml.
```
% osgmlnorm -d example.xml > example.html
```
Carregue o arquivo example.html no seu navegador web e confirme que os arquivos paran.xml foram incluídos no arquivo example.html.

Anterior	Principal	Próxima
Entidades	Acima	Sessões marcadas