Capítulo 4. SGML Markup

Índice
4.1. HTML
4.2. DocBook

Esse capítulo descreve as duas linguagens de marcação que você vai encontrar quando for contribuir para o projeto de documentação do FreeBSD. Cada seção descreve a linguagem de marcação, e detalha a marcação que você provavelmente vai querer usar ou já usando.

Essas linguagens de marcação contém um grande número de elementos, e às vezes pode ficar confuso escolher qual elemento usar em uma situação específica. Essa section fala dos elementos mais prováveis de você precisar e dá exemplos de como você os usaria.

Isso não é uma lista detalhada de elementos, desde que apenas ratifica a documentação para cada linguagem. O alvo dessa seção é para listar os elementos mais útis para você. Se você tiver alguma dúvida em como melhor marcar um pedaço específico do seu documento, por favor envie para a lista de discussão do projeto de documentação do FreeBSD.

Inline vs. block: No restante desse documento, quando descrevendo elementos inline significa que o elemento pode ocorrer dentro de um bloco de elemetos, e não causa quebra de linha. Um elemento block, por comparação, vai causar uma quebra de linha (e outros processamentos) quando esta é encontrado.

4.1. HTML

HTML, Linguagem de marcação de Hypertexto, é a linguagem de escolha da teia mundial de computadores. Mais informações podem ser encontradas em <URL:http://www.w3.org/>.

HTML é usado para marcação de páginas no web site do FreeBSD. Não deveria ser usado (geralmente) para marcar outros tipos de documentos ja que o DocBook oferece uma maior variedade de elementos. Consequentemente, você normalmente vai encontrar páginas em HTML se estiver escrevendo para o sítio www.

HTML ja passou por algumas versões, 1, 2, 3.0, 3.2 e a última, 4.0 (disponível nas duas variantes, strict e loose).

Os HTML DTD's estão disponíveis nas coleções de ports na pasta textproc/html. Elas são automaticamente instaladas como parte do port textproc/docproj

4.1.1. Identificador Público Formal (IPF)

O número de IPF's no HTML depende da versão (também conhecida como nível) do HTML que você quer declarar compatível com seu documento.

A maioria dos documentos HTML no sitío www do FreeBSD estão de acordo com a versão loose do HTML 4.0.

PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

4.1.2. Elementos de seção

Um documento HTML é normalmente dividido em duas partes. A primeira é chamada de head, que contém meta-informação sobre o documento, como o título, o nome do autor e assim por diante. A segunda parte, body é onde fica o conteúdo que vai ser exibido para o usuário.

Essas partes são formadas por elementos específicos para <head> e <body>, respectivamente. Esses elementos estão contidos dentro de um elemento <html> de alto-nível.

Exemplo 4-1. Estrutura normal de um documeno HTML

<html>
  <head>
          <title>Título do documento</title>
  </head>

  <body>

    ...

  </body>
</html>

4.1.3. Block elements

4.1.3.1. Cabeçalho

O HTML permite a denotação de cabeçalho no seu documento, em até seis níveis diferentes.

O maior e mais proeminente cabeçalho é o <h1>, depois vem o <h2>, assim por diante até <h6>.

O conteúdo dos elementos é o texto de um cabeçalho.

Exemplo 4-2. <h1>, <h2>, etc.

Uso:

<h1>Primeira sessão</h1>

<!-- a inrodução do documento entra aqui -->

<h2>Este é o cabeçalho da primeira sessão</h2>

<!-- O conteúdo da primeira sessão entra aqui -->

<h3>Este é o cabeçalho da primeira sub-sessão</h3>

<!-- O conteúdo da primeira sub-sessão entra aqui -->

<h2>Este é o heading para a segundo sessão</h2>

<!-- O conteúdo da segunda sessão entra aqui -->

Geralmente, uma página HTML deveria ter um heading de primeiro nível (<h1>). Esse poderia conter muitos heading de segundo nível (<h2>), onde por sua vez pode conter muitos headings de terceiro nível. Cada elemento <hn> deve ter o mesmo elemento do precedente, exceto um acima na hierarquia. Deve-se evitar buracos na numeração.

Exemplo 4-3. Má organização de elementos <hn>

Uso:

<h1>Primeira sessão</h1>

<!-- Introdução do documento -->

<h3>Sub-sessão</h3>

<!-- Isto é ruim, não foi usado <h2> -->

4.1.3.2. Parágrafos

HTML suporta elementos formados de um único parágrafo <p>.

Exemplo 4-4. <p>

Uso:

<p><p>Isso é um
          parágrafo.  Pode conter qualquer outro elemento</p>

4.1.3.3. Bloco de citação

Um bloco de citação é uma citação extendida de um outro documento que não deveria aparecer no parágrafo corrente.

Exemplo 4-5. <blockquote>

Uso:

<p>Um pequeno trecho da
          constituição dos Estados Unidos:</p>

<blockquote>Nós, povo dos Estados Unidos, com o objetivo de
  fazer uma união mais perfeita, estabelecer justiça,
  garantir tranquilidade doméstica, promover uma defesa comum, promover 
  bem estar geral, assegurar as benções da
  liberdade para nós mesmos e nossa posteridade, organizamos  e
  estabelecemos essa constituição para os estados Unidos
  da América.</blockquote>

4.1.3.4. Listas

Você pode apresentar ao usuário três tipos de listas, ordenadas, desordenadas e de definição.

Tipicamente, cada entrada em uma lista ordenada, é numerada enquanto nas listas desordenadas serão processadas por um bullet point. Listas de definição são compostas de duas partes para cada entrada A primeira é o termo a ser definido, e a segunda, é a definição em si.

As Listas ordenadas, desordenadas e de definição, são indicadas pelo element <ol>, <ul> e <dl>, respectivamente.

Listas ordenadas e desordenadas contém items de lista, indicados pelo elemento <li>. Um item de lista pode conter texto, ou pode até conter um ou mais elementos <p>.

Listas de definição contém o termo a ser definido (<dt>) e a descrição do termo (<dd>). Um termo de definição só pode conter elementos inline. A discrição do termo pode conter outros elementos de bloco.

Exemplo 4-6. <ul> e <ol>

Uso:

<p>Uma lista não ordenada.  
          Os itens serão provavelmente precedidos por uma esfera
          sólida.</p>

<ul>
  <li>Primeiro item</li>

  <li>Segundo item</li>

  <li>Terceiro item</li>
</ul>

<p>Uma lista ordenada, com itens de lista com vários
parágrafos. Cada item (nota: não cada parágrafo)
será numerado.</p>

<ol>
  <li><p>Este é o primeiro item. Tem apenas um parágrafo.</p></li>

  <li><p>Este é o primeiro parágrafo do segundo item.</p>

    <p>Este é o segundo parágrafo do segundo item.</p></li>

  <li><p>Este é o primeiro e único parágrafo do terceiro item.</p></li>
</ol>

Exemplo 4-7. Listas de definição com <dl>

Uso:

<dl>
  <dt>Termo 1</dt>

  <dd><p>Parágrafo 1 da definição 1.</p>

    <p>Parágrafo 2 da definição 1.</p></dd>

  <dt>Termo 2</dt>

  <dd><p>Parágrafo 1 da definição 2.</p></dd>

  <dt>Termo 3</dt>

  <dd>Parágrafo 1 da definição 3.  Note que  
  o elemento <p> não é necessário para o caso
  de um único parágrafo.</dd>
</dl>

4.1.3.5. Texto pré-formatado

Você pode indicar que o texto deve ser apresentado exatamente como esta no arquivo. Tipicamente, isto significa que o texto é mostrado em fonte fixa, multiplos espaços não são fundidos em um e que as quebras de linha no texto são significativas.

Para fazer isto, envolva o conteúdo com o elemento <pre>.

Exemplo 4-8. <pre>

Você pode usar <pre> para marcar uma mensagem de e-mail;

<pre>  From: nik@FreeBSD.org
  To: freebsd-doc@FreeBSD.org
  Subject: New documentation available

  There is a new copy of my primer for contributors to the FreeBSD
  Documentation Project available at

    <URL:http://people.FreeBSD.org/~nik/primer/index.html>

  Comments appreciated.

  N</pre>

4.1.3.6. Tabelas

Nota: A maioria dos navegadores de modo texto (tal como o Lynx) não apresentam tabelas de maneira muito eficiente. Se você quiser que o seu conteúdo seja apresentado em forma de tabelas, você deve considerar uma outra marcação para evitar problemas.

Marque a informação tabular com o elemento <table>. Uma tabela consiste de uma ou mais linhas (<tr>), cada uma contendo uma ou mais células de dados (<td>). As célula podem conter outros elementos de bloco, como parágrafos ou listas. Também pode conter outra tabela (este aninhamento pode ser repetido indefinidamente). Se a célula contém apenas um parágrafos, então não é necessário o elemento <p>.

Exemplo 4-9. Uso simples de <table>

Uso:

<p>Esta é uma simples tabela 
          2x2.</p>

<table>
  <tr>
    <td>Célula esquerda superior</td>

    <td>Célula direita superior</td>
  </tr>

  <tr>
    <td>Célula esquerda inferior</td>

    <td>Célula direita inferior</td>
  </tr>
</table>

Uma célula pode se estender por muitas linhas e colunas. Para indicar, coloque o atributo rowspan e/ou colspan, com valores que indiquem o número de linhas e columas a serem ocupados.

Exemplo 4-10. Usando rowspan

Uso:

<p>Uma célula comprida e estreita
          na esquerda e duas célula pequenas à direita.</p>

<table>
  <tr>
    <td rowspan="2">Comprida e estreita</td>
  </tr>

  <tr>
    <td>Célula superior</td>

    <td>Célula inferior</td>
  </tr>
</table>

Exemplo 4-11. Usando colspan

Uso:

<p>Uma c&eacute;lula longa em cima, duas 
          c&eacute;lulas abaixo.</p>

<table>
  <tr>
    <td colspan="2">C&eacute;lula superior</td>
  </tr>

  <tr>
    <td>C&eacute;lula inferior esquerda</td>

    <td>C&eacute;lula inferior direita</td>
  </tr>
</table>

Exemplo 4-12. Usando rowspan e colspan juntos

Uso:

<p>Numa tabela 3x3, o bloco superior
          esquerdo é um conjunto 2x2 fundidos em um. As outras
          células são normais.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Célula esquerda superior grande</td>

    <td>Célula direita superior</td>
  </tr>

  <tr>
    <!-- Como a célula grande à esquerda funde-se com esta linha,
         o primeiro <td> ocorrerá à a sua direita. -->
    <td>Middle right cell</td>
  </tr>

  <tr>
    <td>Célula inferior esquerda</td>

    <td>Célula inferior central</td>

    <td>Célula inferior direita</td>
  </tr>
</table>

4.1.4. Elementos In-line

4.1.4.1. Emfatizando a informação

Você tem dois níveis de ênfase disponível em HTML, <em> e <strong>. <em> é para uma ênfase simples e <strong> indica uma ênfase mais forte.

Em geral, <em> é apresentada em itálico e <strong> é apresentada em negrito. Mas nem sempre é assim, e você não deve contar com isso.

Exemplo 4-13. <em> e <strong>

Uso:

<p><em>Este</em> foi enfatizado
            enquanto <strong>este</strong> foi fortemente enfatizado.</p>
          

4.1.4.2. Negrito e itálico

HTML inclui marcação de apresentação para indicar que um conteúdo deve ser apresentado em negrito ou itálico. Os elementos são <b> e <i> respectivamente.

Exemplo 4-14. <b> e <i>

<p><b>Este</b> esta em negrito, 
            enaquanto <i>este</i> está em itálico.</p>
          

4.1.4.3. Indicando texto de fonte fixa

Se você tiver conteúdo que deve ser apresentado em fonte fixa (typewriter), use <tt> (de teletipo).

Exemplo 4-15. <tt>

Uso:

<p> Este documento foi originalmente por
  Nik Clayton, que pode ser encontrado por e-mail em
  <tt>nik@FreeBSD.org</tt>.</p>

4.1.4.4. Tamanho do conteúdo

Você pode indicar que o conteúdo deve ser apresentado em uma fonte maior ou menor. Há três maneiras de fazer isto:

  1. Use <big> e <small> em torno do texto que você deseja mudar o tamanho. Estas tags podem ser aninhadas, assim <big><big>Este é muito maior</big></big> é possível.

  2. Use <font> com o atributo size ajustado para +1 ou -1 respectivamente. Isto tem o mesmo efeito que <big> ou <small>. Entretanto esta forma está ultrapassada.

  3. Use <font> com o atributo size com um número entre 1 e 7. O tamanho da fonte padrão é 3. Esta forma está ultrapassada.

Exemplo 4-16. <big>, <small>, e <font>

Todos os fragmentos fazem a mesma coisa.

<p>Este texto é <small>ligeiramente
          menor</small>. Mas este texto é <big>ligeiramente maior</big>.
          </p>

<p>Este texto é <font size="-1">ligeiramente menor</font>. Mas este texto 
é <font size="+1">ligeiramente maior</font.</p>

<p>Este texto é <font size="2">ligeiramente menor</font>.  Mas este texto 
é <font size="4">ligeiramente maior</font>.</p>

4.1.5. Links

Nota: Links também são elementos in-line.

4.1.5.1. Ligando-se a outros documentos

Para incluir um link para outro documento na WWW você deve saber o URL do documento ao qual deseja se ligar.

O link é indicado com <a>, e o atributo href contém o URL do documento alvo. O contúdo do elemento se torna o link, e geralmente é indicado para o usuário de alguma maneira (sublinhado, mudança de cor, o cursor do mouse muda, etc.

Exemplo 4-17. Usando <a href="...">

Uso:

<p>Mais informação disponível no
          <a href="http://www.FreeBSD.org/">site do FreeBSD</a>.</p>

Este link irá levar o usuário ao topo do documento escolhido.

4.1.5.2. Ligando-se a outras partes de documentos

Para fazer um link a um ponto dentro de um outro documento (ou dentro do mesmo documento), é necessário que o autor do documento inclua âncoras ao qual você possa se ligar.

Âncoras são indicadas com <a> e o atributo name ao invés de href.

Exemplo 4-18. Usando <a name="...">

Uso:

<p><a name="para1">Este</a> parágrafo pode ser referenciado
          em outros links com o nome<tt>para1</tt>.</p>

Para fazer um link a uma determinada parte de um documento, faça um link normal a aquele documento, mas inclua o nome da âncora após o símbolo #.

Exemplo 4-19. Link para uma determinada parte de outro documento

Suponha que o exemplo para1 esteja em um documento chamado foo.html.

<p>Mais informação no <a href="foo.html#para1">primeiro 
          parágrafo</a> de <tt>foo.html</tt>.</p>
          

Se você for incluir um link para uma âncora dentro do mesmo documento você pode omitir o URL do documento, e usar apenas o nome da âncora (precedido por #).

Exemplo 4-20. Links para determinada parte do mesmo documento

Suponha que o exemplo para1 esteja neste documento

<p>Mais informação no <a href="#para1">primeiro 
          parágrafo</a> deste documento.</p>

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