7.8. Seções Marcadas

XML fornece um mecanismo para indicar que partes específicas do documento devem ser processadas de uma maneira especial. Estes são chamados de seções marcadas.

Exemplo 7.12. Estrutura de uma Seção Marcada
<![KEYWORD[
  Contents of marked section
]]>

Como esperado de um construct XML, uma seção marcada começa com <!.

O primeiro colchete inicia a seção marcada.

KEYWORD descreve como esta seção marcada deve ser processada pelo parser.

O segundo colchete indica o início do conteúdo da seção marcada.

A seção marcada é concluída, fechando os dois colchetes e, em seguida, retornando ao contexto do documento do contexto XML com >.

7.8.1. Palavras-chave da Seção Marcada

7.8.1.1. CDATA

Essas palavras-chave indicam as seções marcadas pelo modelo de conteúdo e permitem que você a altere do padrão.

Quando um XML parser está processando um documento, ele acompanha o modelo de conteúdo.

O modelo de conteúdo descreve o conteúdo que o parser espera ver e o que ele fará com esse conteúdo.

O modelo de conteúdo CDATA é um dos mais úteis.

CDATA é para Dados de Caractere. Quando o parser está neste modelo de conteúdo, ele espera ver apenas caracteres. Nesse modelo, os símbolos < e & perdem seu status especial e serão tratados como caracteres comuns.

Nota:

Ao usar CDATA em exemplos de texto marcados em XML, lembre-se de que o conteúdo de CDATA não é validado. O texto incluído deve ser verificado por outros meios. Por exemplo, o conteúdo poderia ser escrito em outro documento, validado e depois colado na seção CDATA.

Exemplo 7.13. Usando uma Seção Marcada CDATA
<para>Here is an example of how to include some text that contains
  many <literal>&lt;</literal> and <literal>&amp;</literal>
  symbols.  The sample text is a fragment of
  <acronym>XHTML</acronym>.  The surrounding text (<para> and
  <programlisting>) are from DocBook.</para>

<programlisting><![CDATA[<p>This is a sample that shows some of the
  elements within <acronym>XHTML</acronym>.  Since the angle
  brackets are used so many times, it is simpler to say the whole
  example is a CDATA marked section than to use the entity names for
  the left and right angle brackets throughout.</p>

    <ul>
      <li>This is a listitem</li>
      <li>This is a second listitem</li>
      <li>This is a third listitem</li>
    </ul>

    <p>This is the end of the example.</p>]]></programlisting>

7.8.1.2. INCLUDE e IGNORE

Quando a palavra-chave é INCLUDE, o conteúdo da seção marcada será processado. Quando a palavra-chave é IGNORE, a seção marcada é ignorada e não será processada. Não aparecerá na saída.

Exemplo 7.14. Usando INCLUDE e IGNORE em Seções Marcadas
<![INCLUDE[
  This text will be processed and included.
]]>

<![IGNORE[
  This text will not be processed or included.
]]>

Por si só, isso não é muito útil. O texto a ser removido do documento pode ser recortado ou estar em forma de comentários.

Ele se torna mais útil quando controlado por entidades de parâmetro, mas esse uso é limitado a arquivos de entidades.

Por exemplo, suponha que a documentação tenha sido produzida em uma versão impressa e em uma versão eletrônica. Algum texto extra é desejado no conteúdo da versão eletrônica que não deveria aparecer na cópia impressa.

Crie um arquivo de entidade que defina entidades gerais para incluir cada capítulo e proteja essas definições com uma entidade de parâmetro que pode ser definida como INCLUDE ou IGNORE para controlar se a entidade está definida . Após essas definições de entidades gerais condicionais, coloque mais uma definição para cada entidade geral para defini-las como um valor vazio. Essa técnica faz uso do fato de que as definições de entidade não podem ser substituídas, mas a primeira definição sempre entra em vigor. Assim, a inclusão do capítulo é controlada com a entidade de parâmetro correspondente. Definido como INCLUDE, a primeira definição de entidade geral será lida e a segunda será ignorada. Definido como IGNORE, a primeira definição será ignorada e a segunda será utilizada.

Exemplo 7.15. Usando uma Entidade de Parâmetro para Controlar uma Seção Marcada
<!ENTITY % electronic.copy "INCLUDE">

<![%electronic.copy;[
<!ENTITY chap.preface	SYSTEM "preface.xml">
]]>

<!ENTITY chap.preface "">

Ao produzir a versão impressa, altere a definição do parâmetro de entidade para:

<!ENTITY % electronic.copy "IGNORE">

7.8.2. Para Fazer…

  1. Modifique entidades.ent para conter o seguinte texto:

    <!ENTITY version "1.1">
    <!ENTITY % conditional.text "IGNORE">
    
    <![%conditional.text;[
    <!ENTITY para1 SYSTEM "para1.xml">
    ]]>
    
    <!ENTITY para1 "">
    
    <!ENTITY para2 SYSTEM "para2.xml">
    <!ENTITY para3 SYSTEM "para3.xml">
  2. Normalize example.xml e observe que o texto condicional não está presente no documento de saída. Altere o parâmetro de entidade para INCLUDE e gere novamente o documento normalizado, dessa forma e o texto aparecerá novamente. Esse método faz sentido se houver mais partes condicionais dependendo da mesma condição. Por exemplo, para controlar a geração de texto impresso ou on-line.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.