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.
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
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"
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.
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.
HTML suporta elementos formados de um único parágrafo <p>.
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>
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>
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>
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é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>
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>
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.
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.
Se você tiver conteúdo que deve ser apresentado em fonte fixa (typewriter), use <tt> (de teletipo).
Você pode indicar que o conteúdo deve ser apresentado em uma fonte maior ou menor. Há três maneiras de fazer isto:
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.
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.
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>
Nota: Links também são elementos in-line.
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.
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 #).
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>.