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.
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
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"
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.
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.
Exemplo 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.
O HTML suporta elementos formados de um único parágrafo <p>.
Um bloco de citação é uma citação estendida de outro documento que não deveria aparecer no parágrafo atual.
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 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.
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>
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>:
Exemplo 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 <URL:http://people.FreeBSD.org/~nik/primer/index.html> 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 < ao invés de <. Para manter a consistência, o > 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.
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 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>.
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 isto, coloque o atributo rowspan e/ou colspan, com valores que indiquem o número de linhas ou colunas a serem ocupados.
Exemplo 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>
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>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>
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.
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.
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. Existem 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: Os 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 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.
Exemplo 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.
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.
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 para 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>.