Chapter 4. Marcação SGML

Table of Contents
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 que já está utilizando.

Estas linguagens de marcação contém um grande número de elementos, e as vezes pode ser confuso escolher qual elemento usar em uma situação específica. Esta seção apresenta os elementos que provavelmente você vai precisar e fornece exemplos de como utilizá-los.

Esta não é uma lista detalhada de elementos, uma vez que ela apenas ratifica a documentação de cada linguagem. O objetivo desta seção é listar os elementos mais úteis para você. Se você tiver alguma dúvida sobre qual a melhor forma de marcar um pedaço específico do seu documento, por favor, envie a sua dúvida para a lista de discussão do projeto de documentação do FreeBSD.

Inline Versus Block:

No restante deste documento, quando descrevermos um elemento como inline significará que o elemento pode ocorrer dentro de um bloco de elementos, que ele não acarretará em uma quebra de linha. Um elemento block, por comparação, irá causar uma quebra de linha (e outros processamentos) quando for encontrado.

4.1. HTML

O HTML, Linguagem de Marcação de Hypertexto, é a linguagem de marcação escolhida para a World Wide Web. Maiores informações podem ser encontradas em http://www.w3.org/.

O HTML é utilizado para a marcação das páginas do web site do FreeBSD. Ele não deveria ser utilizado (geralmente) para marcar outros tipos de documentos já que o DocBook oferece uma maior variedade de elementos. Consequentemente, você só irá encontrar páginas em HTML se estiver escrevendo para o web site.

O HTML já 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 na coleção de ports na pasta textproc/html. Eles são automaticamente instalados como parte do port textproc/docproj

4.1.1. Identificador Público Formal (IPF)

Existem vários IPF's para o HTML, os quais dependem 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 web site 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, a qual contém meta-informações sobre o documento, tais como o seu título, o nome do autor, o documento pai e assim por diante. A segunda parte, o body é contém o conteúdo que vai ser exibido para o usuário.

Estas seções são indicadas pelos elementos head e body, respectivamente. Esses elementos estão contidos dentro de um elemento html de alto-nível.

Example 4.1. Estrutura Normal de um Documento HTML
<html>
  <head>
	  <title>Título do Documento</title>
  </head>

  <body>

    …

  </body>
</html>

4.1.3. Bloco de Elementos

4.1.3.1. Cabeçalho

O HTML permite a denotação de cabeçalho em seu documento, de 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 do cabeçalho.

Example 4.2. h1, h2, e outras Tags de Header.

Uso:

<h1>Primeira seção</h1>

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

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

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

<h3>Este é o cabeçalho da primeira subseção</h3>

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

<h2>Este é o heading para a segunda seção</h2>

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

Geralmente, uma página HTML deveria ter um cabeçalho de primeiro nível (h1). Este poderia conter muitos cabeçalhos de segundo nível (h2), os quais por sua vez podem conter muitos cabeçalhos de terceiro nível. Cada elemento hn deve ter o mesmo elemento, sendo que os elementos mais acima na hierarquia estarão subtraídos de um. Deve-se evitar buracos na numeração.

Example 4.3. Má organização de elementos hn

Uso:

<h1>Primeira seção</h1>

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

<h3>Subseção</h3>

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

4.1.3.2. Parágrafos

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

Example 4.4. p

Uso:

<p>Isto é 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 estendida de outro documento que não deveria aparecer no parágrafo atual.

Example 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 pelos elementos ol, ul e dl, respectivamente.

Listas ordenadas e desordenadas contém itens de lista, indicados pelo elemento li. Um item de lista pode conter texto, podendo inclusive 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). A definição de um termo só pode conter elementos inline. A descrição do termo pode conter elementos do tipo block.

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

Example 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><p>Parágrafo 1 da definição 3.</p></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 será mostrado em fonte fixa, múltiplos espaços não serão fundidos em um e que as quebras de linha no texto serão significativas.

Para fazer isto, envolva o conteúdo com o elemento pre:

Example 4.8. pre

Você pode usar pre para marcar uma mensagem de email;

<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

	&lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;

  Comments appreciated.

  N
</pre>

Tenha em mente que o < e o & continuam sendo reconhecidos como caracteres especiais em um texto pré-formatado. É por isto que nos exemplos tivemos que utilizar &lt; ao invés de <. Para manter a consistência, o &gt; também foi utilizado no lugar do >. Fique atento para caracteres especiais que podem aparecer em textos copiados de origens não formatadas, como por exemplo, de uma mensagem de email ou do código fonte de um programa.


4.1.3.6. Tabelas

Note:

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 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élulas 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ágrafo, então não é necessário incluir o elemento p.

Example 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 isto, coloque o atributo rowspan e/ou colspan, com valores que indiquem o número de linhas ou colunas a serem ocupados.

Example 4.10. Utiliizando rowspan

Uso:

<p>Uma célula comprida e estreita na esquerda e duas 
células 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>

Example 4.11. Usando colspan

Uso:

<p>Uma célula longa em cima, duas células abaixo.</p>

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

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

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

Example 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>
    <td>Célula do meio a direita</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. Enfatizando a Informação

Você tem dois níveis de ênfase disponíveis em HTML, em e strong. O em é para uma ênfase simples e o 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.

Example 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

Uma vez que o HTML inclui marcação de apresentação, você também pode indicar que um conteúdo deve ser apresentado em negrito ou itálico. Os elementos são b e i respectivamente.

Example 4.14. b e i
<p><b>Este</b> esta em negrito, 
enquanto <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).

Example 4.15. tt

Uso:

<p> Este documento foi originalmente por
Nik Clayton, que pode ser encontrado por email 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. Existem 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.

Example 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

Note:

Os 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 de destino. O conteúdo do elemento se torna o link, e geralmente é indicado para o usuário de alguma maneira (sublinhado, mudança de cor, o formato do cursor do mouse muda quando está sobre ele, etc.

Example 4.17. Usando <a href="...">

Uso:

<p>Maiores informações estão disponíveis no 
<a href="http://www.FreeBSD.org/">web 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 um Documento

Para fazer um link a um ponto dentro de 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.

Example 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 para aquele documento, mas inclua o nome da âncora após o símbolo #.

Example 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 #).

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