path: root/pt_BR.ISO8859-1/books/fdp-primer/sgml-primer/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1.  Redistributions of source code (SGML DocBook) must retain the above
	 copyright notice, this list of conditions and the following
	 disclaimer as the first lines of this file unmodified.

      2.  Redistributions in compiled form (transformed to other DTDs,
	 converted to PDF, PostScript, RTF and other formats) must reproduce
	 the above copyright notice, this list of conditions and the
	 following disclaimer in the documentation and/or other materials
	 provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED.  IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

     The FreeBSD Documentation Project
     The FreeBSD Brazilian Portuguese Documentation Project

     $FreeBSD$

     Original revision: r38826

-->

<chapter id="sgml-primer">
  <title>SGML Primer</title>

  <para>A maioria dos documentos do FDP é escrita utilizando 
    SGML.  Este capítulo irá explicar exatamente o que 
    isso significa, como ler e compreender os fontes dos documentos 
    e os truques de SGML que você irá se defrontar na 
    documentação.</para>

  <para>Partes desta seção foram inspiradas no documento 
    <ulink url="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">
    Começando a utilizar o DocBook</ulink> de autoria do 
    Mark Galassi.</para>

  <sect1 id="sgml-primer-overview">
    <title>Visão Geral</title>

    <para>Antigamente, era simples de se lidar com um texto
      eletrônico.  Naquela época, você tinha que 
      saber em qual conjunto de caracteres o seu documento havia sido 
      escrito (ASCII, EBCDIC ou um dos inúmeros outros), e mais 
      nada.  O texto era texto, e o que você via era 
      realmente o que você tinha.  Nenhuma frescura, nenhuma 
      formatação, nenhuma inteligência.</para>

    <para>Inevitavelmente, isto não era o suficiente.  
      Uma vez que você tem o texto em uma máquina num 
      formato utilizável, você espera que o equipamento 
      seja capaz de usá-lo e manipulá-lo de forma 
      inteligente.  Você pode desejar indicar que uma 
      determinada frase deve ser enfatizada, ou adicionada a um 
      glossário, ou ser interligada a outra parte do 
      documento.  Você pode querer que os nomes dos arquivos 
      sejam exibidos com uma fonte de estilo <quote>typewriter</quote>
      quando forem exibidos na tela, mas como <quote>itálico
      </quote> quando impresso, ou qualquer outra opção 
      dentre a infinidade de opções disponíveis para
      apresentação.</para>

    <para>Esperava-se que a inteligência artificial (AI) 
      torna-se isso fácil.  O seu computador leria o 
      documento e identificaria automaticamente as frases chave, 
      nomes de arquivos, os campos que o leitor teria que preencher, 
      e muito mais.  Infelizmente, a vida real não evoluiu 
      como esperado, e os nossos computadores necessitam de algum 
      auxílio antes que eles possam processar significativamente 
      nosso texto.</para>

    <para>Mais precisamente, eles precisam de ajuda para identificar
      o que é o que.  Vejamos o texto abaixo:</para>

      <blockquote>
	<para>Para remover o <filename>/tmp/foo</filename> utilize 
	  &man.rm.1;.</para>

	<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>
      </blockquote>

      <para>Nele podemos facilmente visualizar quais partes 
	são nomes de arquivos, quais são comandos que 
	devem ser digitados, quais partes são 
	referências às páginas de manual, etc.  
	Mas o computador processando o documento não pode.  
	Para isto nós precisamos utilizar uma 
	marcação (<literal>markup</literal>).</para>

    <para>A <quote>marcação</quote> é comumente 
      utilizada para descrever a <quote>adição de 
      valor</quote> ou o <quote>aumento de custo</quote>.  O termo 
      (term) faz exame de ambos os meios quando aplicados ao texto.  
      A marcação é um texto adicional incluído 
      no documento, e de alguma forma destacado do seu conteúdo,
      de modo que os programas que forem processá-lo possam ler 
      as marcações e utilizá-las ao tomar 
      decisões sobre o documento.  Os editores podem ocultar 
      a marcação do usuário, de forma que o 
      usuário não se distraia com ele.</para>

    <para>As informações extras armazenadas na 
      marcação <emphasis>adicionam valor</emphasis> ao 
      documento.  Tipicamente a adição da 
      marcação ao documento precisa ser realizada por 
      uma pessoa &mdash; apesar de tudo, se os computadores pudessem
      reconhecer suficientemente bem o texto para adicionar as
      marcações, então não haveria 
      necessidade de adicioná-las em primeiro lugar.  Isto 
      <emphasis>aumenta o custo</emphasis> (isto é, o 
      esforço requerido) para criar o documento.</para>

    <para>O exemplo acima foi na verdade escrito neste documento
      como se segue:</para>

    <programlisting><![CDATA[
<para>Para remover <filename>/tmp/foo</filename> utilize &man.rm.1;.</para>

<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting>

    <para>Como você pode ver, a marcação 
      está claramente separada do conteúdo.</para>

    <para>Obviamente, se você estiver iniciando no uso de 
      marcações, você precisa definir o que a 
      sua marcação significa, e como ela será 
      interpretada.  Você vai precisar de uma linguagem de
      marcação a qual você possa seguir quando 
      estiver marcando os seus documentos.</para>

    <para>Naturalmente, uma linguagem de marcação pode 
      não ser o bastante.  Os requisitos de uma linguagem de 
      marcação destinada formatação de 
      documentos técnicos são diferentes dos requisitos
      de uma linguagem de marcação destinada a 
      formatação de receitas culinárias.  Esta, 
      por sua vez, seria muito diferente de uma linguagem de 
      marcação usada para formatar poemas.  O que 
      você realmente precisa é de uma linguagem 
      primária, a qual você possa utilizar para 
      escrever estas e outras linguagens de marcação.
      Uma <emphasis>meta linguagem de 
      marcação</emphasis>.</para>

    <para>É exatamente isso que a <foreignphrase>Standard 
      Generalized Markup Language</foreignphrase> (SGML) é.  
      Muitas linguagens de marcação foram escritas em 
      SGML, incluindo as duas mais utilizadas pelo FDP, o HTML e o 
      DocBook.</para>

    <para>Cada definição de linguagem é mais 
      corretamente chamada de Definição de Tipo de 
      Documento (DTD).  O DTD especifica o nome dos elementos que 
      podem ser utilizados, em qual ordem eles aparecem (e se alguma 
      marcação pode ser utilizada dentro de outra
      marcação) e as informações 
      relacionadas.  Um DTD é algumas vezes referenciado como 
      uma <emphasis>aplicação</emphasis> do SGML.</para>

    <para id="sgml-primer-validating">Um DTD é uma 
      especificação <emphasis>completa</emphasis> de 
      todos os elementos que podem ser utilizados, da ordem em que 
      podem aparecer, quais elementos são obrigatórios,
      quais são opcionais, e assim por diante.  Isto torna 
      possível escrever um interpretador (parser) SGML, que 
      leia ambos os DTD e um documento que reividique se adequar ao 
      DTD.  O interpretador pode então confirmar se todos os 
      elementos obrigatórios do DTD estão (ou 
      não) presentes no documento na ordem correta, e se 
      existem erros na marcação.  Isto é 
      normalmente referenciado como <quote>validação 
      do documento</quote>.</para>

    <note>
      <para>Este processamento simplesmente confirma se a escolha 
	dos elementos, a sua ordenação, etc, 
	estão de acordo com o especificado no DTD.  Ele <emphasis>
	não</emphasis> verifica se você utilizou a 
	marcação <emphasis>adequada</emphasis> para o
	conteúdo.  Se você tentasse marcar todos os 
	nomes de arquivo em seu documento como nomes de 
	funções, o interpretador não iria 
	apontar isto como um erro (assumindo, naturalmente, que a sua
	DTD define elementos para nomes de arquivos e para 
	funções, e que eles podem ser utilizados nos 
	mesmos lugares).</para>
    </note>

    <para>É provável que a maioria das suas 
      contribuições ao projeto de 
      documentação irão se constituir de 
      conteúdos marcados tanto em HTML quanto em DocBook,  
      em vez de alterações nos DTDs.
      Por esta razão este livro não irá abordar 
      a criação de um DTD.</para>
  </sect1>

  <sect1 id="sgml-primer-elements">
    <title>Elementos, tags, e atributos</title>

    <para>Todos os DTDs escritos em SGML compartilham certas
      características.  Isto é uma dura surpresa, 
      como a filosofia por de trás do SGML nos  
      mostrará ser completamente inevitável.  Uma das 
      manifestações mais óbvias desta filosofia 
      está no <emphasis>conteúdo</emphasis> e nos 
      <emphasis>elementos</emphasis>.</para>

    <para>A sua documentação (independente se é 
      uma única página web ou um livro longo) é 
      composta de conteúdo.  Este conteúdo é 
      então dividido (e de novo subdividido) em elementos.  O 
      propósito da adição de 
      marcações é atribuir nome e identidade 
      para os limites destes elementos de forma a possibilitar o 
      processamento adicional.</para>

    <para>Por exemplo, considere um livro típico.  No 
      nível mais alto, o livro por si só é um 
      elemento.  Este elemento <quote>livro</quote> (book) obviamente
      contém capítulos, os quais também podem
      ser considerados elementos em sua própria forma.  Cada 
      capítulo irá conter mais elementos, tais como 
      parágrafos, citações, notas de 
      rodapé, etc.  Cada parágrafo pode conter 
      elementos adicionais, identificando o conteúdo que era 
      de discurso direto, ou o nome de um personagem da 
      história.</para>

    <para>Você pode preferir pensar nisto como uma
      <quote>quebra</quote> do conteúdo.  No nível 
      mais alto você tem um pedaço, o Livro.  Olhando 
      um pouco mais abaixo, você tem mais pedaços, os 
      capítulos individuais.  Estes estão divididos 
      em pedaços ainda menores, os parágrafos, notas 
      de rodapé, nomes de personagens, etc.</para>

    <para>Observe que você pode fazer esta 
      diferenciação entre os diferentes elementos do 
      conteúdo sem recorrer a nenhum termo SGML.  Na 
      realidade é surpreendentemente fácil de usar.
      Você pode fazer isso utilizando uma caneta de 
      marcação e uma cópia impressa do livro, 
      utilizando diferentes cores para indicar os diferentes 
      pedaços do conteúdo.</para>

    <para>Naturalmente, nós não possuímos uma caneta 
      eletrônica de marcação, assim nós 
      necessitamos de alguma outra maneira de indicar a que elemento 
      cada peça de conteúdo pertence.  Nas linguagens 
      escritas em SGML (HTML, DocBook, etc) isto é feito
      através do uso de <emphasis>tags</emphasis>.</para>

    <para>Uma tag é utilizada para identificar onde um elemento
      particular começa e onde ele termina.  <emphasis>A tag 
      não é uma parte própria do elemento
      </emphasis>.  Porque cada DTD foi normalmente escrito para 
      marcar um tipo específico de informação, 
      cada um deles reconhecerá diferentes elementos, e
      terá nomes diferentes para cada tag.</para>

    <para>Para um elemento chamado <replaceable>element-name
      </replaceable> a tag de início normalmente irá 
      se parecer com 
      <sgmltag><replaceable>element-name</replaceable></sgmltag>.  E 
      a tag correspondente de fechamento para este elemento seria 
      <sgmltag>/<replaceable>element-name</replaceable></sgmltag>.
      </para>

    <example>
      <title>Utilizando um elemento (tags de inicio e fim)</title>

      <para>O HTML possui um elemento para indicar que o 
	conteúdo envolvido por este elemento é um 
	parágrafo, chamado <sgmltag>p</sgmltag>.  Este 
	elemento possui ambas as tags de início e de fim.
	</para>

      <programlisting><![CDATA[<p>Este é um parágrafo.  Ele inicia com a tag de inicio do 
  elemento 'p', e irá terminar com a tag de fim para o 
  elemento 'p'.</p>

<p>Este é um outro parágrafo.  Mas este é muito menor.</p>]]></programlisting>	  
    </example>

    <para>Nem todos os elementos requerem uma tag de 
      finalização.  Alguns elementos não 
      possuem conteúdo.  Por exemplo, em HTML você pode 
      indicar que deseja que uma linha horizontal apareça no
      documento.  Obviamente, esta linha não possui 
      conteúdo, assim apenas a tag de inicio é 
      requerida para este elemento.</para>

    <example>
      <title>Utilizando um elemento (Apenas tag de início)
	</title>

      <para>O HTML possui um elemento para indicar uma linha 
	horizontal, chamado <sgmltag>hr</sgmltag>.  Este elemento 
	não contém nenhum conteúdo, assim ele 
	possui apenas uma tag de inicio.</para>

      <programlisting><![CDATA[<p>Este é um parágrafo.</p>

<hr>

<p>Este é outro parágrafo.  Uma linha horizontal o separa do 
  parágrafo anterior.</p>]]></programlisting>
    </example>

    <para>Se isto não é óbvio agora, os 
      elementos podem conter outros elementos.  No exemplo anterior 
      do livro, o elemento livro continha todos os elementos 
      capítulos, os quais por sua vez continham todos os 
      elementos parágrafos, etc.</para>

    <example>
      <title>Elementos contendo elementos; <sgmltag>em</sgmltag>
	</title>

      <programlisting><![CDATA[<p>Este é um <em>parágrafo</em> simples no qual 
  algumas das <em>palavras</em> foram <em>enfatizadas</em>.</p>]]></programlisting>
    </example>

    <para>O DTD irá especificar as regras detalhando quais 
      elementos podem conter outros elementos, e o que exatamente 
      eles podem conter.</para>

    <important>
      <para>As pessoas sempre confundem os termos tags e elementos, 
	e utilizam os termos como se eles fossem 
	intercambiáveis.  Eles não são.</para>

      <para>Um elemento é uma parte conceitual do seu 
	documento.  Um elemento possui um inicio e fim determinados.  
	As tags marcam onde os elementos começam e terminam.
      </para>

      <para>Quando este documento (ou qualquer pessoa que 
	conheça SGML) se refere a <quote>tag 
	<sgmltag>p</sgmltag></quote> estamos nos referindo 
	literalmente ao texto de três caracteres
	<literal>&lt;</literal>, <literal>p</literal> e
	<literal>&gt;</literal>.  Mas a frase <quote>o elemento
	<sgmltag>p</sgmltag></quote> se refere ao elemento inteiro.
	</para>

      <para>Esta distinção 
	<emphasis>é</emphasis> muito sutil.  Mas mantenha ela 
	em mente</para>
    </important>

    <para>Os elementos podem ter atributos.  Um atributo possui um
      nome e um valor, e é utilizado para adicionar 
      informações extras ao elemento.  Esta pode ser 
      a informação a qual indica como o conteúdo
      deve ser renderizado, ou pode ser algo que identifique a 
      ocorrência única do elemento, ou pode ser qualquer
      outra coisa.</para>

    <para>O atributo de um elemento é sempre escrito
      <emphasis>dentro</emphasis> da tag de início para 
      aquele elemento, e assume a forma
      <literal><replaceable>nome-do-atributo</replaceable>="<replaceable>valor-do-atributo</replaceable>"</literal>.</para>

    <para>Nas versões suficientemente recentes do HTML, o 
      elemento <sgmltag>p</sgmltag> possui um atributo chamado 
      <sgmltag>align</sgmltag>, o qual sugere o alinhamento 
      (Justificação) de um parágrafo para o programa 
      que estiver exibindo o HTML.</para>

    <para>O atributo <literal>align</literal> pode assumir um de
      quatro valores possíveis, <literal>left</literal> 
      (esquerda), <literal>center</literal> (centralizado), 
      <literal>right</literal> (direita) e <literal>justify</literal>
      (justificado).  Se o atributo não for especificado 
      será assumido o valor padrão
      <literal>left</literal>.</para>

    <example>
      <title>Utilizando um elemento com um atributo</title>

      <programlisting><![CDATA[<p align="left">A inclusão de um atributo de alinhamento neste 
  parágrafo foi supérfluo, uma vez que o alinhamento 
  padrão é left (esquerda).</p>

<p align="center">Isto pode aparecer no centro.</p>]]></programlisting>
    </example>

    <para>Alguns atributos irão assumir apenas valores 
      específicos, como o <literal>left</literal> ou 
      <literal>justify</literal>.  Outros irão permitir que 
      você entre com qualquer coisa que deseje.  Se você 
      precisar incluir aspas (<literal>"</literal>) no valor de um 
      atributo, você deve envolver o valor do atributo com 
      aspas simples (<literal>'</literal>).</para>

    <example>
      <title>Aspas simples envolta de atributos</title>

      <programlisting><![CDATA[<p align='right'>Eu estou a direita!</p>]]></programlisting>
    </example>

    <para>Algumas vezes você não precisa utilizar aspas 
      em volta de todos os valores dos atributos.  Entretanto, a 
      regra para fazer isso é muito sutil, e é muito 
      mais simples <emphasis>sempre</emphasis> utilizar as aspas em 
      volta dos valores dos seus atributos.</para>

    <para>A informação nos atributos, elementos e tags 
      são armazenados nos catálogos SGML.  Várias 
      ferramentas do projeto de documentação utilizam 
      estes arquivos de catalogo para validarem o seu trabalho.  As 
      ferramentas no <filename role="package">textproc/docproj</filename> 
      incluem uma variedade de arquivos de catalogo 
      SGML.  O projeto de documentação do FreeBSD 
      inclui seu próprio conjunto de arquivos de catálogos.  
      Suas ferramentas precisam reconhecer ambos os tipos de 
      arquivos de catalogo.</para>

    <sect2>
      <title>Para você fazer&hellip;</title>

      <para>Para poder praticar com os exemplos deste documento 
	você precisará instalar alguns aplicativos no 
	seu sistema, além de assegurar que as variáveis
	de ambiente estejam corretamente configuradas.</para>

      <procedure>
	<step>
	  <para>Faça o download e instale o 
	    <filename role="package">textproc/docproj</filename>
	    a partir do sistema de ports do FreeBSD.  Ele é um
	    <emphasis>meta-port</emphasis> o qual deve efetuar o
	    download e a instalação de todos os 
	    aplicativos e arquivos de suporte que são 
	    utilizados pelo projeto de documentação.
	    </para>
	</step>
	
	<step>
	  <para>Adicione linhas ao seu arquivo de 
	    inicialização do shell para configurar a 
	    variável de ambiente 
	    <envar>SGML_CATALOG_FILES</envar>. (Se você 
	    não estiver trabalhando com a versão no 
	    idioma inglês da documentação,
	    você pode precisar substituir o caminho com o 
	    diretório correto para o seu idioma.)</para>
	
	  <example id="sgml-primer-envars">
	    <title><filename>.profile</filename>, para os 
	      usuários dos shells &man.sh.1; e &man.bash.1;
	      </title>
	
	    <programlisting>SGML_ROOT=/usr/local/share/xml	    
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=/usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES</programlisting>
	  </example>

	  <example>
	    <title><filename>.cshrc</filename>, para os 
	      usuários dos shell &man.csh.1; e &man.tcsh.1;
	      </title>
	
	    <programlisting>setenv SGML_ROOT /usr/local/share/xml
setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/share/xml/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES</programlisting>
	  </example>

	  <para>Para carregar estas variáveis, execute um 
	    logout do sistema, logando novamente em seguida, ou 
	    execute os comandos acima na sua linha de comando para 
	    configurar os valores das variáveis.</para>
	</step>
      </procedure>

      <procedure>
	<step>
	  <para>Crie o arquivo <filename>example.xml</filename>, e 
	    entre com o seguinte texto:</para>

	  <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

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

  <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>
  </body>	    
</html>]]></programlisting>
	</step>

	<step>
	  <para>Tente validar este arquivo utilizando um interpretador
	    SGML.</para>

	  <para>Um dos componentes do 
	    <filename role="package">textproc/docproj</filename> 
	    é o <command>onsgmls</command>, um <link
	    linkend="sgml-primer-validating">interpretador de 
	    validação</link>.  Normalmente, o 
	    <command>onsgmls</command> lê um documento marcado 
	    de acordo com um DTD SGML e retorna uma cópia do 
	    conjunto de informações sobre a estrutura 
	    dos elementos (ESIS, mas isso não é 
	    importante agora).</para>
	
	  <para>Entretanto, quando o <command>onsgmls</command> 
	    é executado com o parâmetro 
	    <option>-s</option>, ele irá suprimir o output
	    normal, e imprimir apenas as mensagens de erro.  Isto o
	    torna um meio útil de verificar se o seu documento
	    é válido ou não.</para>
	
	  <para>Utilize o <command>onsgmls</command> para verificar 
	    se o seu documento é válido:</para>

          <screen>&prompt.user; <userinput>onsgmls -s example.xml</userinput></screen>

	  <para>Como você irá ver, o 
	    <command>onsgmls</command> irá executar sem 
	    retornar nenhuma mensagem.  Isto significa que o seu
	    documento foi validado com sucesso.</para>
	</step>

	<step>
	  <para>Veja o que acontece quando um elemento 
	    obrigatório é omitido.  Tente remover as 
	    tags <sgmltag>title</sgmltag> e <sgmltag>/title</sgmltag>
	    , e execute novamente a validação.</para>

          <screen>&prompt.user; <userinput>onsgmls -s example.xml</userinput>
onsgmls:example.xml:5:4:E: character data is not allowed here
onsgmls:example.xml:6:8:E: end tag for "HEAD" which is not finished</screen>

	  <para>As mensagens de erro emitidas pelo 
	    <command>onsgmls</command> são organizadas em 
	    grupos separados por dois pontos, ou colunas.</para>
	
	  <informaltable frame="none" pgwide="1">
	    <tgroup cols="2">
	      <thead>
		<row>
		  <entry>Coluna</entry>
		  <entry>Propósito</entry>
		</row>
	      </thead>
	
	      <tbody>
		<row>
		  <entry>1</entry>
		  <entry>O nome do programa que está gerando 
		    o erro.  Ela será sempre 
		    <literal>onsgmls</literal>.</entry>
		</row>

		<row>
		  <entry>2</entry>
		  <entry>O nome do arquivo que contém o erro.
		    </entry>
		</row>

		<row>
		  <entry>3</entry>
		  <entry>Número da linha na qual o erro 
		    aparece.</entry>
		</row>

		<row>
		  <entry>4</entry>
		  <entry>Número da coluna na qual o erro 
		    aparece.</entry>
		</row>

		<row>
		  <entry>5</entry>
		  <entry>Um código de uma letra indicando a 
		    natureza da mensagem.  <literal>I</literal> indica
		    uma mensagem informativa, <literal>W</literal> 
		    é para um aviso, e <literal>E</literal> 
		    é para um erro <footnote>
		      <para>Ele não está sempre na 
			quinta coluna.  O
			<command>onsgmls -sv</command> exibe
			<literal>onsgmls:I: "OpenSP" version "1.5.2"
			</literal> (depende da versão 
			instalada).  Como você pode ver,
			esta é uma mensagem informativa.</para>
		    </footnote>, e <literal>X</literal> é 
		    para uma referência cruzada.  Como 
		    você pode ver, estas mensagens são 
		    erros.</entry>
		</row>

		<row>
		  <entry>6</entry>
		  <entry>O texto da mensagem.</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>

	  <para>A simples omissão das tags 
	    <sgmltag>title</sgmltag> gerou 2 erros diferentes.</para>

	  <para>O primeiro erro indica que o conteúdo (neste caso,
	    caracteres, ou melhor, a tag de inicio de um elemento)
	    ocorreu onde o interpretador SGML estava esperando outra
	    coisa.  Neste caso, o interpretador estava esperando
	    encontrar uma das tags de início para os elementos
	    que são válidos dentro do 
	    <sgmltag>head</sgmltag> (como a <sgmltag>title</sgmltag>
	    ).</para>

	  <para>O segundo erro é porque o elemento 
	    <sgmltag>head</sgmltag> <emphasis>deve</emphasis> conter 
	    o elemento <sgmltag>title</sgmltag>.  Por causa disso o 
	    <command>onsgmls</command> considera que o elemento 
	    não foi corretamente finalizado.  Entretanto, a 
	    tag de finalização indica que o elemento 
	    foi fechado antes que estivesse terminado.</para>
	</step>

	<step>
	  <para>Coloque de volta o elemento 
	    <sgmltag>title</sgmltag>.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-doctype-declaration">
    <title>A declaração DOCTYPE</title>

    <para>O inicio de cada documento que você escrever deve
    especificar o nome do DTD o qual se aplica ao seu documento.  Isto
    deve ser feito para que os interpretadores SGML possam determinar
    o DTD e assegurar que o documento esta em conformidade com o
    mesmo.</para>

    <para>Esta informação é geralmente 
      expressada em uma linha, na declaração 
      DOCTYPE.</para>

    <para>Uma declaração típica para um 
      documento escrito para conformar-se com a versão 4.0 
      do DTD HTML se parece com esta:</para>

    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting>

    <para>Esta linha contém diferentes componentes.</para>

    <variablelist>
      <varlistentry>
	<term><literal>&lt;!</literal></term>
	
	<listitem>
	  <para>É o <emphasis>indicador</emphasis> que indica 
	    que se trata de uma declaração SGML.  Esta 
	    linha está declarando o tipo do documento.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>DOCTYPE</literal></term>
	
	<listitem>
	  <para>Mostra que esta é uma declaração
	    SGML para o tipo de documento.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>html</literal></term>
	
	<listitem>
	  <para>O nome do primeiro 
	    <link linkend="sgml-primer-elements">elemento</link> o 
	    qual irá aparecer no documento</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal>
	  </term>

	<listitem>
	  <para>Lista o Identificador Público Formal (FPI)
	    <indexterm> <primary>Identificar Público 
	    Formal</primary> </indexterm> para o DTD ao qual este 
	    documento conforma-se.  O seu interpretador SGML 
	    irá utiliza-lo para encontrar o DTD correto quando
	    estiver processando o documento.</para>

	  <para>O <literal>PUBLIC</literal> não faz parte do 
	    FPI, ele indica para o processador SGML como localizar 
	    o DTD referenciado na FPI.  Outras formas de informar ao
	    interpretador SGML como localizar o DTD serão 
	    abordadas <link
	    linkend="sgml-primer-fpi-alternatives">mais tarde</link>
	    .</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>&gt;</literal></term>
	
	<listitem>
	  <para>Retorno ao documento.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <sect2>
      <title>Identificadores públicos formais (FPIs)
	<indexterm significance="preferred"><primary>Identificadores 
	Públicos Formais</primary></indexterm>
</title>

      <note>
	<para>Você não precisa conhecê-los, mas 
	  eles são um background útil, e podem 
	  ajudá-lo a depurar problemas quando o seu
	  processador SGML não puder localizar o DTD que 
	  você esta utilizando.</para>
      </note>

      <para>Os FPIs devem seguir uma sintaxe específica.  
	Esta sintaxe é a seguinte:</para>

      <programlisting>"<replaceable>Proprietário</replaceable>//<replaceable>Palavra-Chave</replaceable> <replaceable>Descrição</replaceable>//<replaceable>Idioma</replaceable>"</programlisting>

      <variablelist>
	<varlistentry>
	  <term><replaceable>Proprietário</replaceable></term>
	
	  <listitem>
	    <para>Isto indica o proprietário da FPI.</para>

	    <para>Se este conjunto de caracteres começar 
	      com <quote>ISO</quote> significará que o FPI 
	      é de propriedade do ISO.  Por exemplo, a FPI 
	      <literal>"ISO 8879:1986//ENTITIES Greek Symbols//EN"
	      </literal> lista o <literal>ISO 8879:1986</literal> 
	      como sendo o proprietário do conjunto de 
	      entidades dos símbolos Gregos.  O ISO 8879:1986 
	      é o numero da ISO para o padrão SGML.
	      </para>

	    <para>De outra forma, este conjunto de caracteres 
	      irá se parecer com <literal>-//<replaceable>
	      Proprietário</replaceable></literal> ou
	      <literal>+//<replaceable>Proprietário
	      </replaceable></literal> (Observe que a única 
	      diferença é a introdução do 
	      <literal>+</literal> ou do <literal>-</literal>).</para>

	    <para>Se o conjunto de caracteres começar com
	      <literal>-</literal> significa que o 
	      proprietário da informação 
	      não é registrado, se começar com 
	      um <literal>+</literal> significa que ele é 
	      registrado.</para>

	    <para>O ISO 9070:1991 define como os nomes registrados 
	      são gerados; ele pode ser derivado do numero de 
	      uma publicação ISO, de um código 
	      ISBN, ou um código de organização
	      atribuído de acordo com o ISO 6523.  Além disso,
	      uma autoridade de registro pode ser criada a fim de 
	      atribuir nomes registrados.  O conselho ISO delegou 
	      isto ao <literal>American National Standards 
	      Institute</literal> (ANSI).</para>

	    <para>Como o Projeto FreeBSD não foi registrado o 
	      conjunto de caracteres de proprietário é 
	      <literal>-//FreeBSD</literal>.  E como você pode 
	      ver, o W3C também não é um 
	      proprietário registrado.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><replaceable>Palavra-Chave</replaceable></term>
	
	  <listitem>
	    <para>Existem diversas palavras-chave as quais indicam o
	      tipo de informação no arquivo.  Algumas 
	      das palavras chaves mais comuns são
	      <literal>DTD</literal>, <literal>ELEMENT</literal>,
	      <literal>ENTITIES</literal>, e <literal>TEXT</literal>.
	      A palavra chave <literal>DTD</literal> é 
	      utilizada apenas para os arquivos DTD, a 
	      <literal>ELEMENT</literal> é normalmente 
	      utilizada para fragmentos DTD os quais contenham 
	      apenas entidades e declarações de 
	      elementos.  A palavra <literal>TEXT</literal> é 
	      utilizada para o conteúdo SGML (texto e tags).
	      </para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><replaceable>Descricão</replaceable></term>
	
	  <listitem>
	    <para>Qualquer descrição que você 
	      deseje fornecer para o conteúdo deste arquivo.  
	      O que pode incluir um número de versão ou 
	      qualquer texto curto o qual seja significativo para 
	      você e único para o sistema SGML.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><replaceable>Idioma</replaceable></term>
	
	  <listitem>
	    <para>Este é um código ISO de duas letras o 
	      qual identifica o idioma nativo do arquivo.  O 
	      código <literal>EN</literal> é utilizado
	      para o idioma inglês.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <sect3>
	<title>Arquivos de <filename>catálogo</filename>
	  </title>
	
	<para>Se você utilizar a sintaxe acima e processar este
	  documento utilizando um processador SGML, o processador 
	  irá precisar de uma forma de associar a FPI ao nome 
	  do arquivo no seu computador o qual contém o DTD.
	  </para>
	
	<para>Para isto devemos utilizar um arquivo de
	  catálogo.  Um arquivo de catálogo (tipicamente
	  chamado de <filename>catalog</filename>) contém 
	  linhas as quais mapeiam FPIs para nomes de arquivos.  Por 
	  exemplo, se o arquivo de catálogo contiver a linha:
	  </para>
	
	<programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>

	<para>O processador SGML saberia que deveria procurar pelo 
	  DTD <filename>strict.dtd</filename> no subdiretório 
	  <filename>4.0</filename> de qualquer diretório que 
	  possuísse um arquivo <filename>catalog</filename> contendo 
	  esta linha.</para>

	<para>Veja o conteúdo do 
	  <filename>/usr/local/share/xml/html/catalog</filename>. 
	  Este é o arquivo de catálogo para o DTD HTML 
	  o qual será instalado como parte do port
	  <filename role="package">textproc/docproj</filename>.</para>
      </sect3>

      <sect3>
	<title><envar>SGML_CATALOG_FILES</envar></title>

	<para>A fim de encontrar um arquivo de
	  <filename>catálogo</filename>, o seu processador SGML
	  precisará saber onde procurar.  Muitos deles possuem
	  recursos de parâmetros de linha de comando para 
	  especificar o caminho para um ou mais catálogos.
	  </para>
	
	<para>Adicionalmente, você pode definir a 
	  variável de ambiente 
	  <envar>SGML_CATALOG_FILES</envar> para apontar para os
	  arquivos.  Esta variável deve consistir de uma 
	  lista, separada por dois pontos (":"), de arquivos de 
	  catálogo (incluindo seus caminhos completos).</para>
	
	<para>Tipicamente, você precisará incluir os 
	  seguintes arquivos:</para>

	<itemizedlist>
	  <listitem>
	    <para><filename>/usr/local/share/xml/docbook/4.1/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/xml/html/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/xml/iso8879/catalog</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/share/xml/jade/catalog</filename></para>
	  </listitem>
	</itemizedlist>

	<para>Você <link linkend="sgml-primer-envars">já
	  deve ter feito isto</link>.</para>
      </sect3>
    </sect2>

    <sect2 id="sgml-primer-fpi-alternatives">
      <title>Alternativas aos FPIs</title>

      <para>Ao invés de utilizar um FPI para indicar o DTD ao 
	qual o documento conforma-se (e consequentemente, quais 
	arquivos no sistema contém o DTD), você pode 
	especificar explicitamente o nome do arquivo.  </para>

      <para>A sintaxe para isto é ligeiramente diferente:
	</para>

      <programlisting><![CDATA[<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>

      <para>A palavra chave <literal>SYSTEM</literal> indica que o
	processador SGML deve encontrar o DTD em um local 
	específico do sistema.  Isto tipicamente (mas 
	não sempre) significa que o DTD será fornecido 
	como um nome de arquivo.</para>

      <para>O uso de FPIs é preferido por razões de 
	portabilidade.  Você pode não desejar ter que 
	enviar uma cópia do DTD junto com seu documento, e 
	se você utilizasse um identificador
	<literal>SYSTEM</literal> todos necessitariam manter os seus
	DTDs no mesmo lugar que você.</para>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-sgml-escape">
    <title>Voltando para o SGML</title>

    <para>Como mencionado anteriormente, o SGML é utilizado 
      somente quando escrevemos um DTD.  Isto não é
      estritamente verdade.  Existem certas sintaxes SGML as quais
      você poderá desejar utilizar com os seus 
      documentos.  Por exemplo,  você pode incluir 
      comentários no seu documento, e eles serão 
      ignorados pelo interpretador.  Os comentários são
      adicionados utilizando sintaxe SGML.  Outros usos para a sintaxe
      SGML no seu documento serão mostrados mais tarde.</para>

    <para>Obviamente, você precisa indicar de alguma forma ao
      processador SGML que o conteúdo seguinte não se 
      trata de elementos do documento, mas sim de SGML sobre o qual 
      o interpretador deve atuar.</para>

    <para>Estas sessões são marcadas no seu documento 
      com <literal>&lt;! ...  &gt;</literal>.  Tudo entre estes
      delimitadores é sintaxe SGML tal como você pode 
      encontrar dentro de um DTD.</para>

    <para>Como você pode perceber, a 
      <link linkend="sgml-primer-doctype-declaration">
      declaração DOCTYPE </link> é um exemplo 
      de sintaxe SGML a qual você precisa incluir no seu 
      documento.</para>
  </sect1>

  <sect1 id="sgml-primer-comments">
    <title>Comentários</title>

    <para>Comentários são uma construção 
      SGML, e são normalmente válidos apenas dentro de 
      um DTD.  Entretanto, como mostrou a
      <xref linkend="sgml-primer-sgml-escape"/>, é possível 
      utilizar sintaxe SGML com os seus documentos.</para>

    <para>O delimitador para um comentário SGML é o 
      conjunto de caracteres <quote><literal>--</literal></quote>.  
      A primeira ocorrência deste conjunto de caracteres abre 
      um comentário e a segunda fecha.</para>

    <example>
      <title>Comentário SGML genérico</title>

      <programlisting>&lt;!-- Teste de comentário --></programlisting>

      <programlisting><![CDATA[
<!-- Este é o interior do comentário -->

<!-- Este é outro comentário    -->

<!-- Esta é uma forma 
     de fazer comentários de várias linhas -->

<!-- Esta é outra forma  --
  -- de fazer comentários de várias linhas -->]]></programlisting>
    </example>

    <para>Se você já utilizou HTML antes, você pode ter 
      sido exposto a regras diferentes para comentários.  Em 
      particular, você pode pensar que o conjunto de caracteres
      <literal>&lt;!--</literal> abre um comentário e que ele 
      apenas é fechado por um <literal>--&gt;</literal>.</para>

    <para>Este <emphasis>não</emphasis> é o caso.  
      Muitos dos navegadores web possuem interpretadores HTML 
      quebrados, e irão aceitar isso como válido.  
      Entretanto, os interpretadores SGML utilizados pelo projeto 
      de documentação são muito mais 
      rígidos, e irão rejeitar os documentos que 
      contiverem este erro.</para>

    <example>
      <title>Comentários SGML errados</title>

      <programlisting><![CDATA[
<!-- Este é o comentário --

     Isto está fora do comentário!

  -- de volta para dentro do comentário -->]]></programlisting>

      <para>O interpretador SGML irá tratar isto como ele 
	é realmente;</para>

      <programlisting>&lt;!Isto está fora do comentário&gt;</programlisting>

      <para>Isto não é um SGML válido, e pode 
	dar mensagens de erro confusas.</para>

      <programlisting><![CDATA[<!--------------- Isto é uma idéia muito ruim --------------->]]></programlisting>

      <para>E como o exemplo sugere, <emphasis>não escreva
	</emphasis> comentários como esse.</para>

      <programlisting><![CDATA[<!--===================================================-->]]></programlisting>

      <para>Esta é uma abordagem (ligeiramente) melhor, mas 
	ele ainda é potencialmente confuso para as pessoas 
	novas no uso do SGML.</para>

    </example>

    <sect2>
      <title>Para você fazer&hellip;</title>

      <procedure>
	<step>
	  <para>Adicione alguns comentários ao arquivo
	  <filename>example.xml</filename> e verifique se ele 
	  continua válido usando o <command>onsgmls</command>.
	  </para>
	</step>

	<step>
	  <para>Adicione alguns comentários inválidos ao
	    <filename>example.xml</filename> e veja as mensagens de 
	    erro que o <command>onsgmls</command> emite quando 
	    encontra um comentário inválido.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-entities">
    <title>Entidades</title>

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

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

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

    <sect2 id="sgml-primer-general-entities">
      <title>Entidades gerais</title>

      <para>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 <link linkend="sgml-primer-parameter-entities">
	entidades de parâmetros</link>.</para>

      <para>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 
	<literal>&amp;<replaceable>nome-da-entidade</replaceable>;</literal>.
	Por exemplo, suponha que você possui uma 
	entidade chamada <literal>current.version</literal>, a qual 
	expande para a versão atual do seu produto.  
	Você pode escrever:</para>

      <programlisting><![CDATA[<para>A versão atual do nosso produto é &amp;current.version;.</para>]]></programlisting>

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

      <para>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 <literal>&lt;</literal> e 
	<literal>&amp;</literal> não podem aparecer normalmente
	em um documento SGML.  Quando o interpretador SGML vê 
	o símbolo <literal>&lt;</literal> 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 <literal>&amp;</literal> ele assume que o 
	próximo texto será o nome de uma entidade.
	</para>

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

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

      <example>
	<title>Definindo uma entidade geral</title>

	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY current.version    "3.0-RELEASE">
<!ENTITY last.version       "2.2.7-RELEASE">
]>]]></programlisting>
	
	<para>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.</para>
	
	<para>O colchete é necessário para indicar 
	  que nós estamos extendendo o DTD indicado pela 
	  declaração DOCTYPE.</para>
      </example>
    </sect2>

    <sect2 id="sgml-primer-parameter-entities">
      <title>Entidades de parâmetro</title>

      <para>Assim como as 
	<link linkend="sgml-primer-general-entities">entidades gerais</link>
	, 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 
	<link linkend="sgml-primer-sgml-escape">contexto SGML</link>.
	</para>

      <para>As entidades de parâmetro são definidas de uma 
	forma similar as entidades gerais.  Entretanto, ao 
	invés de utilizar
	<literal>&amp;<replaceable>nome-da-entidade</replaceable>;</literal>
	como referência, utiliza
	<literal>%<replaceable>nome-da-entidade</replaceable>;</literal>
	  <footnote><para>Entidades de 
	  <emphasis>P</emphasis>arâmetro utilizam o símbolo de 
	  <emphasis>P</emphasis>orcentagem.</para> </footnote>.  
	A definição também inclui o 
	<literal>%</literal> entre a palavra chave 
	<literal>ENTITY</literal> e o nome da entidade.</para>
	
      <example>
	<title>Definindo entidades de parâmetros</title>
	
	<programlisting><![CDATA[<!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" -->
]>]]></programlisting>
      </example>
	
      <para>Isto pode não parecer particularmente 
	útil.  Mas ele será.</para>

    </sect2>

    <sect2>
      <title>Para você fazer&hellip;</title>

      <procedure>
	<step>
	  <para>Adicione uma entidade geral ao 
	    <filename>example.xml</filename>.</para>

	  <programlisting><![CDATA[<!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 é: &amp;version;</p>	  
  </body>	    
</html>]]></programlisting>	  
	</step>

	<step>
	  <para>Valide o documento utilizando o <command>onsgmls
	    </command></para>
	</step>

	<step>
	  <para>Carregue o arquivo <filename>example.xml</filename>
	    no seu navegador web (Você pode precisar 
	    copiá-lo para <filename>example.html</filename> 
	    antes que o seu navegador possa reconhecê-lo como 
	    um documento HTML).</para>
	
	  <para>A menos que o seu navegador seja muito 
	    avançado, você não irá ver a 
	    entidade referenciada por <literal>&amp;version;</literal>
	    substituída pelo número de versão.  
	    A maioria dos navegadores web possuem interpretadores 
	    muito simplistas os quais não manuseiam 
	    corretamente SGML <footnote><para>Isto é uma 
	    vergonha.  Imagine todos os problemas e <literal>hacks
	    </literal> (tais como os Server Side Includes) que 
	    poderiam ser evitados se eles o fizessem.</para>
	    </footnote>.</para>
	</step>

	<step>
	  <para>A solução é 
	    <emphasis>normalizar</emphasis>  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.</para>
	
	  <para>Você pode utilizar o <command>osgmlnorm
	    </command> para fazer isto:</para>

          <screen>&prompt.user; <userinput>osgmlnorm example.xml &gt; example.html</userinput></screen>

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

	<step>
	  <para>Se você examinar o retorno do 
	    <command>osgmlnorm</command> você ira ver que ele 
	    não inclui a declaração DOCTYPE no 
	    inicio.  Para incluí-la você precisa 
	    utilizar a opção <option>-d</option>:</para>
	
          <screen>&prompt.user; <userinput>osgmlnorm -d example.xml &gt; example.html</userinput></screen>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-include">
    <title>Utilizando entidades para incluir arquivos</title>

    <para>As entidades (ambas <link
	linkend="sgml-primer-general-entities">gerais</link> e de <link
	linkend="sgml-primer-parameter-entities">parâmetros</link>)
	são particularmente úteis quando utilizadas 
	para incluir um arquivo dentro de outro.</para>

    <sect2 id="sgml-primer-include-using-gen-entities">
      <title>Utilizando entidades gerais para incluir arquivos</title>

      <para>Suponha que você possui algum conteúdo para um 
	livro SGML organizado em arquivos, um arquivo por capítulo, 
	chamados <filename>chapter1.xml</filename>,
	<filename>chapter2.xml</filename>, e assim por diante, com 
	um arquivo <filename>book.xml</filename> que irá 
	conter estes capítulos.</para>
	
      <para>A fim de utilizar o conteúdo destes arquivos como 
	os valores para as suas entidades, você as declara com 
	a palavra chave <literal>SYSTEM</literal>.  Isto direciona o
	interpretador SGML para utilizar o conteúdo dos 
	arquivos nomeados como o valor da entidade.</para>

      <example>
	<title>Utilizando entidades gerais para incluir
	  arquivos</title>
	
	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">
<!-- e assim por diante -->
]>

<html>
  <!-- Utilize as entidades para carregar os capítulos -->

  &chapter.1;
  &chapter.2;
  &chapter.3;
</html>]]></programlisting>
      </example>

      <warning>
	<para>Quando utilizar uma entidade geral para incluir outros
	  arquivos em um documento, os arquivos que estiverem sendo
	  inclusos (<filename>chapter1.xml</filename>,
	  <filename>chapter2.xml</filename>, etc) 
	  <emphasis>não devem</emphasis> iniciar com uma 
	  declaração DOCTYPE.  Isto é um erro 
	  de sintaxe.</para>
      </warning>
    </sect2>

    <sect2>
      <title>Utilizando entidades de parâmetro para incluir 
	arquivos</title>

      <para>Recorde-se que uma entidade de parâmetro só pode 
	ser utilizada dentro de um contexto SGML.  Por que 
	então você desejaria incluir um arquivo dentro 
	de um contexto do SGML?</para>

      <para>Você pode utilizar isto para assegurar-se de que 
	você pode reutilizar as suas entidades gerais.</para>

      <para>Suponha que você possui muitos capítulos em seu 
	documento, e você reutiliza estes capítulos em dois 
	livros diferentes, cada livro organizando os capítulos de 
	uma forma diferente.</para>

      <para>Você pode listar as entidades no topo de cada 
	livro, mas isto rapidamente torna-se incomodo de gerenciar.
	</para>

      <para>Em vez de disso, coloque as definições das 
	suas entidades gerais em um arquivo, e utilize uma entidade 
	de parâmetro para incluir este arquivo dentro do seu 
	documento.</para>

      <example>
	<title>Utilizando entidades de parâmetro para incluir
	  arquivos.</title>

	<para>Primeiro, coloque as suas definições de 
	  entidades em um arquivo separado, chamado 
	  <filename>chapters.ent</filename>.  Este arquivo 
	  contém o seguinte:</para>
	
	<programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml">
<!ENTITY chapter.2 SYSTEM "chapter2.xml">
<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting>

	<para>Agora crie uma entidade de parâmetro para referenciar 
	  o conteúdo do arquivo.  E então utilize a 
	  entidade de parâmetro 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;</para>
	
	<programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!-- Define uma entidade de parâmetro para carregar as entidades gerais de capitulo -->
<!ENTITY % chapters SYSTEM "chapters.ent">

<!-- Agora utilize a entidade de parâmetro para carregar neste arquivo -->
%chapters;
]>

<html>
  &amp;chapter.1;
  &amp;chapter.2;
  &amp;chapter.3;
</html>]]></programlisting>
      </example>
    </sect2>

    <sect2>
      <title>Para você fazer&hellip;</title>

      <sect3>
	<title>Utilizando entidades gerais para incluir arquivos
	  </title>

	<procedure>
	  <step>
	    <para>Crie três arquivos, 
	      <filename>para1.xml</filename>,
	      <filename>para2.xml</filename>, e
	      <filename>para3.xml</filename>.</para>

	    <para>Coloque um conteúdo similar ao seguinte em 
	      cada arquivo:</para>

	    <programlisting><![CDATA[<p>Este é o primeiro parágrafo.</p>]]></programlisting>
	  </step>

	  <step>
	    <para>Edite o arquivo <filename>example.xml</filename>
	      para que ele se pareça com este:</para>

	    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">
]>

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

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

    &amp;para1;
    &amp;para2;
    &amp;para3;
  </body>
</html>]]></programlisting>
	  </step>

	  <step>
	    <para>Produza o arquivo 
	      <filename>example.html</filename> através da
	      normalização do arquivo 
	      <filename>example.xml</filename>.</para>

            <screen>&prompt.user; <userinput>osgmlnorm -d example.xml &gt; example.html</userinput></screen>
	  </step>

	  <step>
	    <para>Carregue o arquivo 
	      <filename>example.html</filename> no seu navegador web,
	      e confirme que os arquivos 
	      <filename>para<replaceable>n</replaceable>.xml</filename>
	      foram incluídos no <filename>example.html</filename>.
	      </para>
	  </step>
	</procedure>
      </sect3>

      <sect3>
	<title>Utilizando uma entidade de parâmetro para incluir
	  arquivos.</title>

	<note>
	  <para>Você deve ter executado os passos anteriores 
	    primeiro.</para>
	</note>
	
	<procedure>
	  <step>
	    <para>Edite o arquivo 
	      <filename>example.xml</filename> para que ele se
	      pareça com este:</para>
	
	    <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entities SYSTEM "entities.xml"> %entities;
]>

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

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

    &amp;para1;
    &amp;para2;
    &amp;para3;
  </body>
</html>]]></programlisting>
	  </step>

	  <step>
	    <para>Crie um novo arquivo chamado 
	      <filename>entities.xml</filename>, com este 
	      conteúdo:</para>

	    <programlisting><![CDATA[<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.xml">
<!ENTITY para2 SYSTEM "para2.xml">
<!ENTITY para3 SYSTEM "para3.xml">]]></programlisting>
	  </step>

	  <step>
	    <para>Produza o arquivo <filename>example.html</filename>
	      através da normalização do arquivo
	      <filename>example.xml</filename>.</para>

            <screen>&prompt.user; <userinput>osgmlnorm -d example.xml &gt; example.html</userinput></screen>
	  </step>

	  <step>
	    <para>Carregue o arquivo 
	      <filename>example.html</filename> no seu navegador web
	      e confirme que os arquivos
	      <filename>para<replaceable>n</replaceable>.xml</filename>
	      foram incluídos no arquivo 
	      <filename>example.html</filename>.</para>
	  </step>
	</procedure>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-marked-sections">
    <title>Sessões marcadas</title>

    <para>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 
      <quote>sessões marcadas</quote>.</para>

    <example>
      <title>Estrutura de uma sessão marcada</title>

      <programlisting>&lt;![ <replaceable>Palavra-chave</replaceable> [
  Conteúdo da sessão marcada
]]&gt;</programlisting>
    </example>

    <para>Como você esperaria, sendo uma 
      construção SGML, uma sessão
      marcada inicia com um <literal>&lt;!</literal>.</para>

    <para>O primeiro colchete começa a limitar a sessão
      marcada.</para>

    <para>A <replaceable>Palavra-chave</replaceable> descreve como 
      esta sessão marcada deve ser processada pelo 
      interpretador.</para>

    <para>O segundo colchete indica que o conteúdo da 
      sessão marcada inicia aqui.</para>

    <para>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 
      <literal>&gt;</literal>.</para>

    <sect2>
      <title>Palavras-Chave de sessões marcadas</title>

      <sect3>
	<title><literal>CDATA</literal>, 
	  <literal>RCDATA</literal></title>
	
	<para>Estas palavras chave denotam o <emphasis>modelo do 
	  conteúdo</emphasis> das sessões marcadas, e 
	  permitem que você o altere a partir do padrão.
	  </para>
	
	<para>Quando um interpretador SGML esta processando um
	  documento ele tenta seguir o que chamamos de <quote>modelo 
	  de conteúdo</quote></para>
	
	<para>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.
	  </para>
	
	<para>Os dois modelos de conteúdo que você 
	  provavelmente irá achar mais úteis 
	  são o <literal>CDATA</literal> e o
	  <literal>RCDATA</literal>.</para>
	
	<para>O <literal>CDATA</literal> é para 
	  <quote>Dados de Caracter</quote>.  Se o interpretador 
	  está neste modelo de conteúdo então ele
	  está esperando encontrar caracteres, e apenas 
	  caracteres.  Neste modelo os símbolos 
	  <literal>&lt;</literal> e o <literal>&amp;</literal>
	  perdem o seu status especial, e serão tratados como 
	  caracteres ordinários.</para>
	
	<para>O <literal>RCDATA</literal> é para 
	  <quote>Referências de entidade e dados de caracter
	  </quote>.  Se o interpretador está neste
	  modelo de conteúdo ele está esperando 
	  encontrar caracteres <emphasis>e</emphasis> entidades.  
	  O símbolo <literal>&lt;</literal> perde
	  o seu status especial, mas o <literal>&amp;</literal> 
	  continuará sendo tratado como o inicio de uma 
	  entidade geral.</para>

	<para>Isto é particularmente útil se você
	  está incluindo algum texto literal o qual 
	  contém muitos caracteres <literal>&lt;</literal> e 
	  <literal>&amp;</literal>.  Ao invés de atravessar o 
	  texto todo tendo que verificar se todos os  
	  <literal>&lt;</literal> estão convertidos para um
	  <literal>&amp;lt;</literal> e todos os
	  <literal>&amp;</literal> estão convertidos para um
	  <literal>&amp;amp;</literal> pode ser mais simples marcar 
	  a sessão como contendo apenas 
	  <literal>CDATA</literal>.  Quando o interpretador SGML 
	  encontrá-los ele irá ignorar os símbolos 
	  <literal>&lt;</literal> e <literal>&amp;</literal> 
	  embutidos no conteúdo.</para>
	
	<note>
	  <para>Quando você utiliza <literal>CDATA</literal> ou
	    <literal>RCDATA</literal> nos exemplos de texto marcado em
	    SGML, tenha em mente que o conteúdo do
	    <literal>CDATA</literal> 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
	    <literal>CDATA</literal>.</para>
	</note>

	<!-- O assentamento de CDATA dentro do exemplo seguinte é repugnante -->
	
	<example>
	  <title>Utilizando uma sessão marcada como 
	    CDATA</title>
	
	  <programlisting>&lt;para&gt;Aqui está um exemplo de como você incluiria algum texto que contenha muitos 
  símbolos &lt;literal&gt;&lt;&lt;/literal&gt; e &lt;literal&gt;&gt;&lt;/literal&gt;.
  O texto de exemplo é um fragmento de HTML.  
  O texto circunvizinho (&lt;para&gt; e &lt;programlisting&gt;) é do
  DocBook.&lt;/para&gt;
	  
&lt;programlisting&gt;
  &lt;![CDATA[&gt;![RCDATA[
    &lt;p&gt;Esta é uma amostra que apresenta alguns elementos de HTML.
       Uma vez que os símbolos de &lt; e &gt; 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.&lt;/p&gt;

    &lt;ul&gt;
      &lt;li&gt;Este é um item de lista&lt;/li&gt;
      &lt;li&gt;Este é um segundo item de lista&lt;/li&gt;
      &lt;li&gt;Este é um terceiro item de lista&lt;/li&gt;
    &lt;/ul&gt;

    &lt;p&gt;Este é o final do exemplo.&lt;/p&gt;]]&gt;
  ]]&gt;
&lt;/programlisting&gt;</programlisting>

	  <para>Se você examinar o fonte deste documento 
	    você irá ver que esta técnica foi 
	    utilizada por toda parte.</para>
	</example>
      </sect3>

      <sect3>
	<title><literal>INCLUDE</literal> and
	  <literal>IGNORE</literal></title>
	
	<para>Se a palavra chave for <literal>INCLUDE</literal> 
	  então o conteúdo da sessão marcada 
	  será processado.  Se a palavra chave for 
	  <literal>IGNORE</literal> então a sessão 
	  marcada será ignorada e não será 
	  processada.  Ela não irá aparecer no
	  output.</para>
	
	<example>
	  <title>Utilizando <literal>INCLUDE</literal> e
	    <literal>IGNORE</literal> nas sessões marcadas</title>

	  <programlisting>&lt;![ INCLUDE [
  Este texto será processado e incluído.
]]&gt;

&lt;![ IGNORE [
  Este texto não será processado nem incluído.
]]&gt;</programlisting>
	</example>
	
	<para>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.</para>
	
	<para>Torna-se mais útil quando você utilizar 
	  <link linkend="sgml-primer-parameter-entities">entidades de
	  parâmetro</link> 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 <emphasis>é</emphasis> um contexto 
	  SGML.</para>

	<para>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.</para>
	
	<para>Crie uma entidade de parâmetro, e configure seu valor
	  para <literal>INCLUDE</literal>.  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.</para>
	
	<para>Quando você desejar produzir uma cópia 
	  impressa do documento, altere o valor da entidade de 
	  parâmetro para <literal>IGNORE</literal> e reprocesse o 
	  documento.</para>
	
	<example>
	  <title>Utilizando uma entidade de parâmetro para 
	    controlar uma sessão marcada</title>
	
	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
&lt;!ENTITY % electronic.copy "INCLUDE">	     
]]&gt;

...

&lt;![ %electronic.copy [
  Este conteúdo deve aparecer apenas na versão eletrônica do
  documento.
]]&gt;</programlisting>

	  <para>Quando for produzir uma versão impressa do 
	    documento, altere a definição da entidade 
	    para;</para>
	
	  <programlisting>&lt;!ENTITY % electronic.copy "IGNORE"></programlisting>

	  <para>Ao reprocessar o documento, a sessão marcada 
	    que utilizar a entidade <literal>%electronic.copy
	    </literal> como a sua palavra chave será 
	    ignorada.</para>
	</example>
      </sect3>
    </sect2>

    <sect2>
      <title>Para você fazer&hellip;</title>

      <procedure>
	<step>
	  <para>Crie um novo arquivo chamado 
	    <filename>section.xml</filename>, o qual deve conter o 
	    seguinte conteúdo:</para>

	  <programlisting>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
&lt;!ENTITY % text.output "INCLUDE">
]&gt;

&lt;html>
  &lt;head>
    &lt;title>Um exemplo utilizando uma sessão marcada.&lt;/title>
  &lt;/head>

  &lt;body>	    
    &lt;p>Este parágrafo &lt;![CDATA[contêm muitos caracteres &lt;
      (&lt; &lt; &lt; &lt; &lt;) de forma que é mais simples utilizar
      uma sessão marcada do tipo CDATA.]]&gt;&lt;/p>

    &lt;![ IGNORE [
    &lt;p>Este parágrafo definitivamente não será incluído
      no output.&lt;/p>
    ]]&gt;

    &lt;![ <![CDATA[%text.output]]> [
    &lt;p>Este parágrafo pode ou não aparecer no output.&lt;/p>

    &lt;p>A sua ocorrência é controlada pela entidade de parâmetro <![CDATA[%text.output]]>
      .&lt;/p>	    
    ]]&gt;
  &lt;/body>
&lt;/html></programlisting>	    
	</step>

	<step>
	  <para>Normalize este arquivo utilizando o 
	    <command>osgmlnorm</command> 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.</para>
	</step>

	<step>
	  <para>Altere a definição da entidade 
	    <literal>text.output</literal> de <literal>INCLUDE
	    </literal> para <literal>IGNORE</literal>.  Re-normalize 
	    o arquivo, e observe o resultado para ver o que foi 
	    alterado.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 id="sgml-primer-conclusion">
    <title>Conclusão</title>

    <para>Esta é a conclusão da introdução
      ao SGML.  Devido a restrições de espaço e 
      complexidade, diversos assuntos não foram abordados em 
      profundidade (ou sequer foram abordados).  Entretanto, as 
      sessões prévias cobriram o suficiente do SGML 
      para que você possa seguir a organização 
      da documentação do FDP.</para>
  </sect1>
</chapter>