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

# 3.8 Sessões marcadas

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

Exemplo 3-14. Estrutura de uma sessão marcada

    <![ Palavra-chave [
      Conteúdo da sessão marcada
    ]]>

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

## 3.8.1 Palavras-Chave de sessões marcadas

### 3.8.1.1 `CDATA`, `RCDATA`

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 `&lt;` e todos os `&` estão convertidos para um `&amp;` 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>&lt;</literal> e <literal>&amp;</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.

### 3.8.1.2 `INCLUDE` and `IGNORE`

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.

## 3.8.2 Para você fazer…

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

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

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

Anterior | Principal | Próxima
Utilizando entidades para incluir arquivos | Acima | Conclusão

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