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

3.6 Entidades

Entidades são um mecanismo para atribuir nomes para pedaços de conteúdo. Quando o interpretador SGML processar o seu documento, qualquer entidade que ele encontrar será substituída pelo conteúdo da entidade.

Esta é uma boa forma de ter pedaços de conteúdo reutilizáveis e facilmente alteráveis em seus documentos SGML. Esta é também a única forma de incluir um arquivo marcado dentro de outro utilizando SGML.

Existem dois tipos de entidades que podem ser utilizadas em duas situações diferentes; Entidades gerais e Entidades de parâmetros.

3.6.1 Entidades gerais

Você não pode utilizar uma entidade geral em um contexto SGML (embora você as defina em um). Elas podem ser utilizadas apenas no seu documento. Compare isto com as entidades de parâmetros.

Cada entidade geral possui um nome. Quando você quer referenciar uma entidade geral (e consequentemente incluir o texto que ela representa no seu documento), você escreve &nome-da-entidade;. Por exemplo, suponha que você possui uma entidade chamada current.version, a qual expande para a versão atual do seu produto. Você pode escrever:

<para>A versão atual do nosso produto é &current.version;.</para>

Quando o número de versão mudar, você pode simplesmente alterar a definição do valor da entidade geral e reprocessar o seu documento.

Você também pode utilizar entidades gerais para incorporar caracteres que você não poderia incorporar de outra forma em um documento SGML. Por exemplo, os caracteres < e & não podem aparecer normalmente em um documento SGML. Quando o interpretador SGML vê o símbolo < ele assume que aquilo é uma tag (uma tag de abertura ou de fechamento) que está a ponto de aparecer, e quando ele vê o símbolo & ele assume que o próximo texto será o nome de uma entidade.

Felizmente, você pode utilizar as duas entidades gerais &lt; e &amp; sempre que você precisar incluí-los.

Uma entidade geral só pode ser definida dentro de um contexto SGML. Tipicamente, isto é feito imediatamente depois da declaração DOCTYPE.

Exemplo 3-10. Definindo uma entidade geral

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY current.version    "3.0-RELEASE">
<!ENTITY last.version       "2.2.7-RELEASE">
]>

Observe como a declaração DOCTYPE foi estendida adicionando-se um colchete no final da primeira linha. As duas entidades estão definidas nas próximas duas linhas, antes que o colchete seja fechado, e então a declaração DOTYPE é fechada.

O colchete é necessário para indicar que nós estamos extendendo o DTD indicado pela declaração DOCTYPE.

3.6.2 Entidades de parâmetro

Assim como as entidades gerais , as entidades de parâmetro são utilizadas para atribuir um nome a pedaços reutilizáveis de texto. Entretanto, enquanto as entidades gerais só podem ser utilizadas com o seu documento, as entidades de parâmetro podem ser utilizadas apenas dentro de um contexto SGML.

As entidades de parâmetro são definidas de uma forma similar as entidades gerais. Entretanto, ao invés de utilizar &nome-da-entidade; como referência, utiliza %nome-da-entidade; [1]. A definição também inclui o % entre a palavra chave ENTITY e o nome da entidade.

Exemplo 3-11. Definindo entidades de parâmetros

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % param.some "some">
<!ENTITY % param.text "text">
<!ENTITY % param.new  "%param.some more %param.text">

<!-- %param.new agora contém "some more text" -->
]>

Isto pode não parecer particularmente útil. Mas ele será.

3.6.3 Para você fazer…

  1. Adicione uma entidade geral ao example.xml.

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY version "1.1">
]>	  

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

  <!-- Você pode ter alguns comentários aqui também -->
	  
  <body>	    
    <p>Este é um parágrafo contendo algum texto.</p>

    <p>Este parágrafo contém mais algum texto.</p>

    <p align="right">Este parágrafo pode estar alinhado a direita.</p>

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

  2. Valide o documento utilizando o onsgmls

  3. Carregue o arquivo example.xml no seu navegador web (Você pode precisar copiá-lo para example.html antes que o seu navegador possa reconhecê-lo como um documento HTML).

    A menos que o seu navegador seja muito avançado, você não irá ver a entidade referenciada por &version; substituída pelo número de versão. A maioria dos navegadores web possuem interpretadores muito simplistas os quais não manuseiam corretamente SGML [2].

  4. A solução é normalizar seu documento utilizando um normalizador SGML. Um normalizador lê um SGML válido e retorna um SGML igualmente válido o qual foi transformado de alguma forma. Uma das formas em que o normalizador transforma o SGML é expandindo todas as entidades referenciadas no documento, substituindo as entidades pelo texto que elas representam.

    Você pode utilizar o osgmlnorm para fazer isto:

    % osgmlnorm example.xml > example.html

    Você deve encontrar uma cópia normalizada (isto é, entidades referenciadas expandidas) do seu documento no arquivo example.html, pronta para ser carregada no seu navegador web.

  5. Se você examinar o retorno do osgmlnorm você ira ver que ele não inclui a declaração DOCTYPE no inicio. Para incluí-la você precisa utilizar a opção -d:

    % osgmlnorm -d example.xml > example.html

Notas

[1]

Entidades de Parâmetro utilizam o símbolo de Porcentagem.
[2]

Isto é uma vergonha. Imagine todos os problemas e hacks (tais como os Server Side Includes) que poderiam ser evitados se eles o fizessem.
Anterior Principal Próxima
Comentários Acima Utilizando entidades para incluir arquivos

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