| Primer do Projeto de Documentação do FreeBSD para novos colaboradores | ||
|---|---|---|
| Anterior | Capítulo 3 SGML Primer | Próxima |
O SGML fornece um mecanismo para indicar que uma parte particular do documento deve ser processada de uma forma especial. Estas partes são denominadas “sessões marcadas”.
Como você esperaria, sendo uma construção SGML, uma sessão marcada inicia com um <!.
O primeiro colchete começa a limitar a sessão marcada.
A Palavra-chave descreve como esta sessão marcada deve ser processada pelo interpretador.
O segundo colchete indica que o conteúdo da sessão marcada inicia aqui.
A sessão marcada é finalizada pelo fechamento dos dois colchetes e então retornando ao contexto do documento a partir do contexto SGML com o >.
Estas palavras chave denotam o modelo do conteúdo das sessões marcadas, e permitem que você o altere a partir do padrão.
Quando um interpretador SGML esta processando um documento ele tenta seguir o que chamamos de “modelo de conteúdo”
Resumidamente, o modelo de conteúdo descreve que tipo de conteúdo o interpretador esta esperando encontrar, e o que fará com ele quando o encontrar.
Os dois modelos de conteúdo que você provavelmente irá achar mais úteis são o CDATA e o RCDATA.
O CDATA é para “Dados de Caracter”. Se o interpretador está neste modelo de conteúdo então ele está esperando encontrar caracteres, e apenas caracteres. Neste modelo os símbolos < e o & perdem o seu status especial, e serão tratados como caracteres ordinários.
O RCDATA é para “Referências de entidade e dados de caracter ”. Se o interpretador está neste modelo de conteúdo ele está esperando encontrar caracteres e entidades. O símbolo < perde o seu status especial, mas o & continuará sendo tratado como o inicio de uma entidade geral.
Isto é particularmente útil se você está incluindo algum texto literal o qual contém muitos caracteres < e &. Ao invés de atravessar o texto todo tendo que verificar se todos os < estão convertidos para um < e todos os & estão convertidos para um & pode ser mais simples marcar a sessão como contendo apenas CDATA. Quando o interpretador SGML encontrá-los ele irá ignorar os símbolos < e & embutidos no conteúdo.
Nota: Quando você utiliza CDATA ou RCDATA nos exemplos de texto marcado em SGML, tenha em mente que o conteúdo do CDATA não é validado. Você tem que verificar o SGML incluso no texto utilizando algum outro meio. Você pode, por exemplo, escrever o exemplo em outro documento, validar o código de exemplo, e então colá-lo para o seu conteúdo CDATA.
Exemplo 3-15. Utilizando uma sessão marcada como CDATA
<para>Aqui está um exemplo de como você incluiria algum texto que contenha muitos
símbolos <literal><</literal> e <literal>&</literal>.
O texto de exemplo é um fragmento de HTML.
O texto circunvizinho (<para> e <programlisting>) é do
DocBook.</para>
<programlisting>
<![ CDATA [
<p>Esta é uma amostra que apresenta alguns elementos de HTML.
Uma vez que os símbolos de < e > são utilizados muitas vezes, é
mais fácil dizer que o exemplo todo é uma sessão marcada do
tipo CDATA, do que utilizar nomes de entidades para representar
estes símbolos ao longo de todo o texto.</p>
<ul>
<li>Este é um item de lista</li>
<li>Este é um segundo item de lista</li>
<li>Este é um terceiro item de lista</li>
</ul>
<p>Este é o final do exemplo.</p>
]]>
</programlisting>
Se você examinar o fonte deste documento você irá ver que esta técnica foi utilizada por toda parte.
Se a palavra chave for INCLUDE então o conteúdo da sessão marcada será processado. Se a palavra chave for IGNORE então a sessão marcada será ignorada e não será processada. Ela não irá aparecer no output.
Exemplo 3-16. Utilizando INCLUDE e IGNORE nas sessões marcadas
<![ INCLUDE [ Este texto será processado e incluído. ]]> <![ IGNORE [ Este texto não será processado nem incluído. ]]>
Por si só, isto não é muito útil. Se você desejar remover o texto do seu documento você pode cortá-lo fora, ou comentá-lo.
Torna-se mais útil quando você utilizar entidades de parâmetro para controlá-lo. Lembre-se que entidades de parâmetro só podem ser utilizadas em um contexto SGML, e que a palavra chave de uma sessão marcada é um contexto SGML.
Por exemplo, suponha que você produza uma cópia impressa e uma versão eletrônica de alguma documentação. Você pode desejar incluir na versão eletrônica algum conteúdo extra, o qual não deve aparecer na versão impressa.
Crie uma entidade de parâmetro, e configure seu valor para INCLUDE. Escreva seu documento, usando uma sessão marcada para delimitar o conteúdo que deve aparecer apenas na versão eletrônica. Nesta sessão marcada utilize a entidade de parâmetro no lugar da palavra chave.
Quando você desejar produzir uma cópia impressa do documento, altere o valor da entidade de parâmetro para IGNORE e reprocesse o documento.
Exemplo 3-17. Utilizando uma entidade de parâmetro para controlar uma sessão marcada
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <!ENTITY % electronic.copy "INCLUDE"> ]]> ... <![ %electronic.copy [ Este conteúdo deve aparecer apenas na versão eletrônica do documento. ]]>
Quando for produzir uma versão impressa do documento, altere a definição da entidade para;
<!ENTITY % electronic.copy "IGNORE">
Ao reprocessar o documento, a sessão marcada que utilizar a entidade %electronic.copy como a sua palavra chave será ignorada.
Crie um novo arquivo chamado section.xml, o qual deve conter o seguinte conteúdo:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % text.output "INCLUDE">
]>
<html>
<head>
<title>Um exemplo utilizando uma sessão marcada.</title>
</head>
<body>
<p>Este parágrafo <![ CDATA [contêm muitos caracteres <
(< < < < <) de forma que é mais simples utilizar
uma sessão marcada do tipo CDATA.]]></p>
<![ IGNORE [
<p>Este parágrafo definitivamente não será incluído
no output.</p>
]]>
<![ %text.output [
<p>Este parágrafo pode ou não aparecer no output.</p>
<p>A sua ocorrência é controlada pela entidade de parâmetro %text.output
.</p>
]]>
</body>
</html>
Normalize este arquivo utilizando o osgmlnorm e examine o resultado. Observe quais parágrafos apareceram, quais desapareceram e o que aconteceu com o conteúdo da sessão marcada como CDATA.
Altere a definição da entidade text.output de INCLUDE para IGNORE. Re-normalize o arquivo, e observe o resultado para ver o que foi alterado.
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 <[email protected]>.
Para perguntas sobre esta documentação, envie e-mail para <[email protected]>.