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 parametros) 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 conteudo para um livro SGML organizado em arquivos, um arquivo por capitulo, chamados chapter1.sgml, chapter2.sgml, e assim por diante, com um arquivo book.sgml que irá conter este 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 conteudo dos arquivos nomeados como o valor da entidade.

Exemplo 3-12. Utilizando entiades gerais para incluir arquivos

<!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">
<!-- e assim por diante -->
]>

<html>
  <!-- Utilize as entidades para carregar os capitulos -->

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

AtençãoQuando utilizar uma entidade geral para incluir outros arquivos em um documento, os arquivos que estiverem sendo inclusos ((chapter1.sgml, chapter2.sgml, etc) não devem inciar 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 parametro 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 re-utilizar as suas entidades gerais.

Suponha que você possui muitos capitulos em seu documento, e você reutiliza estes capitulos em 2 livros diferentes, cada livro organizando os capitulos 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 marametro para incluir este arquivo dentro do seu documento.

Exemplo 3-13. Utilizando entidades de parametro 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.sgml">
<!ENTITY chapter.2 SYSTEM "chapter2.sgml">
<!ENTITY chapter.3 SYSTEM "chapter3.sgml">

Agora crie uma entidade de parametro para referenciar o conteúdo do arquivo. E então utilize a entidade de parametro 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 parametro para carregar as entidades gerais de capitulo -->
<!ENTITY % chapters SYSTEM "chapters.ent">

<!-- Agora utilize a entidade de parametro 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.sgml, para2.sgml, e para3.sgml.

Coloque um conteúdo similar ao seguinte em cada arquivo;
```
<p>Este é o primeiro paragrafo.</p>
```

Edite o arquivo example.sgml 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.sgml">
<!ENTITY para2 SYSTEM "para2.sgml">
<!ENTITY para3 SYSTEM "para3.sgml">
]>

<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.sgml.
```
% sgmlnorm -d example.sgml > example.html
```
Carregue o arquivo example.html no seu navegador web, e confirme que os arquivos paran.sgml foram incluidos no example.html.

3.7.3.2. Utilizando uma entidade de parametro para incluir arquivos.

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

Edite o arquivo example.sgml para que ele se pareça com este;

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entities SYSTEM "entities.sgml"> %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.sgml, com este conteúdo:

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

Produza o arquivo example.html através da normalização do arquivo example.sgml.
```
% sgmlnorm -d example.sgml > example.html
```
Carregue o arquivo example.html no seu navegador web e confirme que os arquivos paran.sgml foram incluidos no arquivo example.html.

Anterior	Principal	Próxima
Entidades	Acima	Sessões marcadas