4.2. DocBook
Prev | Chapter 4. Marcação SGML | Next

## 4.2. DocBook

O DocBook foi originalmente desenvolvido por HaL Computer Systems e O'Reilly & Associates como um DTD para escrever documentação técnica [3]. E desde 1998 tem sido mantido pelo DocBook Technical Committee. Desta forma, ao contrário do LinuxDoc e do HTML, o DocBook é fortemente orientado a marcação que descreve o que é alguma coisa, ao invés de descrever como ela deve ser apresentada.

### Formal Versus Informal:

Alguns elementos podem existir em duas formas, formal e informal. Tipicamente, a versão formal dos elementos consistirá de um título seguido da versão informal do elemento. A versão informal não terá um título.

O DocBook DTD está disponível na coleção de ports como `textproc/docbook`. Ele é automaticamente instalado como parte do port `textproc/docproj`.

### 4.2.1. Extensões FreeBSD

O Projeto de Documentação do FreeBSD ampliou o DocBook DTD adicionando alguns elementos novos. Estes elementos têm como objetivo tornar algumas marcações mais precisas.

Os elementos específicos introduzidos pelo FreeBSD estarão claramente destacados quando forem listados abaixo.

No restante deste documento, o termo “DocBook” deve ser interpretado como sendo a versão do DocBook DTD ampliado pelo projeto de documentação do FreeBSD.

### Note:

Não existe nada nestas extenssões que seja específico ao FreeBSD, apenas percebemos que elas seriam melhorias para este projeto em particular. Se alguém dos demais projetos *nix (NetBSD, OpenBSD, Linux, ...) tiver interesse em colaborar para a criação de um conjunto de extensões DocBook padrão, por favor entre em contato com Equipe de Engenharia de Documentação `<doceng@FreeBSD.org>`.

As extensões FreeBSD não estão (atualmente) na coleção de ports. Elas estão armazenadas na árvore Subversion do FreeBSD, como head/share/xml/freebsd.dtd.

### 4.2.2. Identificador Formal Público (IFP)

De acordo com as diretrizes DocBook para a escrita de IPF's para adaptação do DocBook, o IPF para o DocBook estendido do FreeBSD é:

PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"

### 4.2.3. Estrutura dos Documentos

DocBook permite que você estruture sua documentação de várias maneiras. No projeto de documentação do FreeBSD nós estamos utilizando dois tipos primários de documentos DocBook: o livro e o artigo.

Um livro é organizado em `chapter`s (capítulos). Isso é um requerimento obrigatório. Podem existir `part`s (partes) entre o livro e os capítulos para fornecer mais uma camada de organização. O Handbook, por exemplo, é organizado desta maneira.

Um capítulo pode (ou não) conter uma ou mais sessões. Estas são indicadas pelo elemento `sect1`. Se uma sessão contém outra sessão, então use o elemento `sect2`, e assim por diante até `sect5`.

Capítulos e sessões contém o restante do conteúdo.

Um artigo é mais simples do que um livro, e não usa capítulos. Ao invés disso, o conteúdo de um artigo é organizado em uma ou mais sessões, usando os mesmos elementos `sect1` (e `sect2` e assim por diante) que são usados nos livros.

Obviamente, você deve considerar a natureza da documentação que você esta escrevendo para poder decidir se é melhor uma marcação formatada como um livro ou um artigo. Artigos suportam bem informações que não precisam ser divididas em capítulos, isto é, relativamente pequena, com mais ou menos 20 a 25 páginas de conteúdo. Livros suportam melhor informações que se dividem em capítulos com apêndices e conteúdos similares.

Os tutoriais sobre FreeBSD estão marcados na forma de artigos, enquanto por exemplo este documento, o FAQ do FreeBSD, e o Handbook do FreeBSD estão marcados na forma como livros.

#### 4.2.3.1. Iniciando um Livro

O conteúdo de um livro deve estar contido dentro do elemento `book`. Assim como outros elementos de marcação estrutural, esse elemento pode conter elementos que incluam informações adicionais sobre o livro. Isto é tanto meta-informação, utilizada para fins de referência, ou conteúdo adicional usado para produzir uma página de título.

Estas informações adicionais devem estar contidas dentro do elemento `bookinfo`.

Example 4.21. Modelo padrão `book` com `bookinfo`
<book> <bookinfo> <title>`Seu título aqui`</title> <author> <firstname>`Seu primeiro nome aqui`</firstname> <surname>`Seu sobrenome`</surname> <affiliation> <address><email>`Seu endereço de correio eletrônico aqui`</email></address> </affiliation> </author> <copyright> <year>`1998`</year> <holder role="mailto:`seu endereço de email`">`Seu nome`</holder> </copyright> <releaseinfo>$FreeBSD$</releaseinfo> <abstract> <para>`Inclua um resumo do conteúdo do seu livro aqui.`</para> </abstract> </bookinfo> … </book>

#### 4.2.3.2. Começando um Artigo

O conteúdo do artigo deve estar contido dentro do elemento `article`. Assim como outros elementos de marcação estrutural, esse elemento pode conter elementos que incluam informações adicionais sobre o artigo. Isto é tanto meta-informação, utilizada para fins de referência, ou conteúdo adicional usado para produzir uma página de título.

Estas informações adicionais devem estar contidas dentro do elemento `articleinfo`.

Example 4.22. Modelo padrão `article` com `articleinfo`
<article> <articleinfo> <title>`Seu título aqui`</title> <author> <firstname>`Seu primeiro nome`</firstname> <surname>`Seu sobrenome`</surname> <affiliation> <address><email>`Seu endereço de email`</email></address> </affiliation> </author> <copyright> <year>`1998`</year> <holder role="mailto:`seu endereço de email`">`Seu nome`</holder> </copyright> <releaseinfo>$FreeBSD$</releaseinfo> <abstract> <para>`Inclua um resumo do conteúdo do artigo aqui.`</para> </abstract> </articleinfo> … </article>

#### 4.2.3.3. Indicando Capítulos

Utilize `chapter` para marcar seus capítulos. Cada capítulo tem obrigatoriamente um `title`. Artigos não contêm capítulos, estes são reservados para os livros.

Example 4.23. Um capítulo simples
<chapter> <title>Título do capítulo</title> ... </chapter>

Um capítulo não pode ser vazio; ele precisa conter elementos além do `title`. Se você precisar incluir um capítulo vazio então você precisará incluir um parágrafo vazio.

Example 4.24. Capítulos Vazios
<chapter> <title>Isto é um capítulo vazio</title> <para></para> </chapter>

#### 4.2.3.4. Sessões Abaixo dos Capítulos

Em um livro, os capítulos podem (mas não é obrigatoriamente necessário) ser quebrados em seções, subseções, e assim por diante. Em um artigo, as seções são os principais elementos estruturais, e cada artigo deve conter pelo menos uma seção. Utilize o elemento `sect`n``. O `n` indica o número da seção o qual identifica o nível da seção.

A primeira `sect`n`` é `sect1`. Você pode ter uma ou mais desta em um só capítulo. Elas podem conter um ou mais elementos `sect2`, e assim por diante, até `sect5`.

Example 4.25. Seções em Capítulos
<chapter> <title>Um exemplo de capítulo</title> <para>Algum texto dentro do capítulo</para> <sect1> <title>Primeira seção (1.1)</title> &hellip; </sect1> <sect1> <title>Segunda seção (1.2)</title> <sect2> <title>Primeira subseção (1.2.1)</title> <sect3> <title>Primeira sub-subseção (1.2.1.1)</title> &hellip; </sect3> </sect2> <sect2> <title>Segunda subseção (1.2.2)</title> &hellip; </sect2> </sect1> </chapter>

### Note:

Este exemplo inclui os números das seções nos títulos de seções. Você não deve fazer isso nos seus documentos. A inserção dos números de seção é realizada pelas folhas de estilo (falaremos delas mais a frente), e você não precisa gerenciá-los manualmente.

#### 4.2.3.5. Subdividindo Utilizando o Elemento `Part`

Você pode introduzir outra camada de organização entre `book` e `chapter` utilizando uma ou mais `part`s. Isto não pode ser feito em um `article`.

<part> <title>Introdução</title> <chapter> <title>Visão Geral</title> ... </chapter> <chapter> <title>O que é FreeBSD?</title> ... </chapter> <chapter> <title>História</title> ... </chapter> </part>

### 4.2.4. Elementos de Blocos

#### 4.2.4.1. Parágrafos

O DocBook suporta três tipos de parágrafos: `formalpara`, `para`, e `simpara`.

Na maioria das vezes você só vai precisar usar `para`. O `formalpara` inclui um elemento `title`, e o `simpara` desabilita alguns elementos dentro de `para`. Fique com o `para`.

Example 4.26. `para`

Uso:

<para>Isso é um parágrafo. E pode conter quase qualquer outro elemento.</para>

Aparência:

Isso é um parágrafo. E pode conter quase qualquer outro elemento.

#### 4.2.4.2. Bloco de Citações

Um bloco de citação é uma longa citação de outro documento que não deveria aparecer no parágrafo atual. Você não irá usá-lo com muita frequência.

Um bloco de citação pode conter opcionalmente um título e uma atribuição (ou eles podem ser deixados sem título e sem atributos)

Example 4.27. `blockquote`

Uso:

<para>Um pequeno pedaço da Constituição dos Estados Unidos:</para> <blockquote> <title>Preâmbulo da constituição dos Estados Unidos.</title> <attribution>Copiado de um site qualquer</attribution> <para>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.</para> </blockquote>

Aparência:

Um pequeno pedaço da Constituição dos Estados Unidos

| Preâmbulo da constituição dos Estados Unidos. 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. |
| --Copiado de um site qualquer

#### 4.2.4.3. Dicas, notas, avisos, informações importantes e sidebars.

Talvez você precise incluir informações extras separadas do corpo principal do texto. Tipicamente isto é “meta” informação que o usuário deve tomar conhecimento.

Dependendo da natureza da informação, devemos utilizar o elemento `tip`, `note`, `warning`, `caution`, ou `important`. Alternativamente, se a informação é relacionada ao corpo principal do texto e não se encaixa em nenhum dos objetos acima, utilize `sidebar`.

As circunstâncias na qual se deve escolher um elemento ao invés do outro não é clara. A documentação do DocBook sugere que:

- A `note` é uma informação que deve ser lida por todos os leitores.

- A `important` é uma variação do `note`.

- A `caution` é usada para informar sobre uma possível perda de dados ou possível dano causado pelo software.

- O `warning` é usado para informações sobre possíveis danos ao hardware, sobre risco de vida ou de ferimento a um membro.

Example 4.28. `warning`

Uso:

<warning> <para>Instalar o FreeBSD talvez faça com que você queira desinstalar o Windows do seu Hard disk.</para> </warning>

Aparência:

### Warning:

Instalar o FreeBSD talvez faça com que você queira desinstalar o Windows do seu Hard disk.

#### 4.2.4.4. Listas e Procedimentos

Você frequentemente vai precisar listar fragmentos de informação para o usuário, ou apresentar para eles um passo a passo o qual eles devem seguir para alcançar um objetivo específico.

Para fazer isso, utilize `itemizedlist`, `orderedlist`, ou `procedure` [4].

Os elementos `itemizedlist` e `orderedlist` são similares aos seus equivalentes em HTML, `ul` e `ol`. Cada um consiste de um ou mais elementos `listitem`, e cada `listitem` contém um ou mais elementos de bloco. O elemento `listitem` é analogo à `li` do HTML. Entretanto, ao contrário do que ocorre no HTML, aqui elas são obrigatórias.

O elemento `procedure` é ligeiramente diferente. Ele consiste de `step`s, que por sua vez consistem de mais `step`s ou `substep`s. Cada `step` contém elementos de bloco.

Example 4.29. `itemizedlist`, `orderedlist`, e `procedure`

Uso:

<itemizedlist> <listitem> <para>Esse é o primeiro item enumerado.</para> </listitem> <listitem> <para>Esse é o segundo item enumerado.</para> </listitem> </itemizedlist> <orderedlist> <listitem> <para>Esse é o primeiro item ordenado.</para> </listitem> <listitem> <para>Esse é o segundo item ordenado.</para> </listitem> </orderedlist> <procedure> <step> <para>Faça isto.</para> </step> <step> <para>Depois faça isto.</para> </step> <step> <para>E agora faça isto.</para> </step> </procedure>

Aparência:

- Esse é o primeiro item enumerado.

- Esse é o segundo item enumerado.

1. Esse é o primeiro item ordenado.

2. Esse é o segundo item ordenado.

1. Faça isto.

2. Depois faça isto.

3. E agora faça isto.

#### 4.2.4.5. Mostrando Amostras de Arquivos

Se você quiser mostrar um trecho de um arquivo (ou talvez um arquivo inteiro) ao usuário, use o elemento `programlisting`

Espaços e quebras de linha são importantes dentro do `programlisting`. Em particular, isso significa que a tag de abertura deve aparecer na mesma linha que a primeira linha do programa, e a tag de fechamento deve estar na última linha do programa, do contrário linhas em branco espúrias podem ser incluídas.

Example 4.30. `programlisting`

Uso:

<para>Quando você tiver terminado, seu programa deve estar assim:</para> <programlisting>#include &lt;stdio.h&gt; int main(void) { printf("hello, world\n"); }</programlisting>

Note como os colchetes na linha `#include` precisaram ser referenciados através de suas entidades ao invés de incluídas literalmente.

Aparência:

Quando você tiver terminado, seu programa deve estar assim;

#include <stdio.h> int main(void) { printf("hello, world\n"); }

#### 4.2.4.6. Chamadas

Uma chamada é um mecanismo para fazer referência a um pedaço de texto ou uma posição específica de um exemplo anterior sem ligar a ele no texto.

Para fazer isso, marque as áreas de interesse no seu exemplo (`programlisting`, `literallayout`, ou o que for) com o elemento `co`. Cada elemento deve ter um `id` único atribuído a ele. Insira um `calloutlist` no final do exemplo acima fazendo referência de volta a ele, exibindo comentários adicionais.

Example 4.31. `co` e `calloutlist`
<para>Quando você tivert terminado, seu prograva deve estar assim;</para> <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include"/> int <co id="co-ex-return"/> main(void) { printf("hello, world\n"); <co id="co-ex-printf"/> }</programlisting> <calloutlist> <callout arearefs="co-ex-include"> <para>Inclui o arquivo padrão de IO.</para> </callout> <callout arearefs="co-ex-return"> <para>Especifica que <function>main()</function> retorna um inteiro.</para> </callout> <callout arearefs="co-ex-printf"> <para>A chamada <function>printf()</function> que escreve <literal>hello, world</literal> na saída padrão.</para> </callout> </calloutlist>

Aparência:

Quando você tiver terminado, seu programa deve estar assim;

#include <stdio.h> int main(void) { printf("hello, world\n"); }

| Inclui o arquivo padrão de IO.
| Especifica que `main()` retorna um inteiro.
| A chamada `printf()` escreve `hello, world` na saída padrão

#### 4.2.4.7. Tabelas

Ao contrário do HTML, você não precisa usar tabelas para acertar o layout, as folhas de estilo cuidam disto para você. Utilize tabelas apenas para marcação de dados tabulares.

De maneira geral (veja a documentação do DocBook para mais detalhes) uma tabela (que pode ser formal ou informal) consiste de um elemento `table`. O qual contém ao menos um elemento `tgroup`, que especifica (como um atributo) o número de colunas neste grupo da tabela. Dentro do grupo tabela você pode ter um elemento `thead`, que contém os elementos para o cabeçalho da tabela (cabeçalho da coluna), e um `tbody` que contém o corpo da tabela.

Tanto o `tgroup` quanto o `thead` contém elementos `row`, que por sua vez contém elementos `entry`. Cada elemento `entry` especifica uma célula da tabela.

Example 4.32. `informaltable`

Uso:

<informaltable pgwide="1"> <tgroup cols="2"> <thead> <row> <entry>Este é o cabeçalho da coluna 1</entry> <entry>Este é o cabeçalho da coluna 2</entry> </row> </thead> <tbody> <row> <entry>Linha 1, coluna 1</entry> <entry>Linha 1, coluna 2</entry> </row> <row> <entry>Linha 2, coluna 1</entry> <entry>Linha 2, coluna 2</entry> </row> </tbody> </tgroup> </informaltable>

Aparência:

Este é o cabeçalho da coluna 1 | Este é o cabeçalho da coluna 2
--- | ---
Linha 1, coluna 1 | Linha 1, coluna 2
Linha 2, coluna 1 | Linha 2, coluna 2

Sempre utilize o atributo `pgwide` com o valor `1` junto ao elemento `informaltable`. Um bug no Internet Explorer pode fazer com que a tabela renderize de forma incorreta se ele for omitido.

Se você não quiser borda na tabela adicione o atributo `frame` ao elemento `informaltable` com o valor `none` (i.e., `<informaltable frame="none">`).

Example 4.33. Tabelas com `frame="none"`

Aparência:

Este é o cabeçalho da coluna 1 | Este é o cabeçalho da coluna 2
--- | ---
Linha 1, coluna 1 | Linha 1, coluna 2
Linha 2, coluna 1 | Linha 2, coluna 2

#### 4.2.4.8. Exemplos para o Usuário Seguir

Muitas vezes você irá precisar mostrar exemplos para que o usuário siga. Normalmente, isso irá consistir de diálogos com o computador, nos quais o usuário digita um comando, e obtém uma resposta de volta, ele digita outro comando e recebe outra reposta, e assim por diante.

Vários elementos e entidades podem ser utilizados nestes casos.

`screen`

  Tudo que o usuário visualizar neste exemplo estará na tela do computador, assim o próximo elemento é `screen`.

  Dentro da marcação do `screen`, espaços em branco são significativos.

`prompt`, `&prompt.root;` e `&prompt.user;`

  Algumas das coisas que o usuário irá visualizar na tela são prompts do computador (seja do sistema operacional, da linha de comando shell ou de uma aplicação). Estes prompts devem ser marcados usando `prompt`.

  Por serem especiais, os prompts de shell do usuário normal e do usuário root estão disponíveis como uma entidade. Sempre que quiser indicar que o usuário está em um prompt do shell, use `&prompt.root;` para o usuário root e `&prompt.user;` para o usuário normal, conforme for necessário. Estas entidades não precisam estar dentro de um `prompt`.

  ### Note:

  `&prompt.root;` e `&prompt.user;` são extensões do FreeBSD ao DocBook, e não são parte do DTD original.

`userinput`

  Quanto estiver mostrando um texto que o usuário deva digitar, envolva-o com as tags `userinput`. Ele provavelmente será mostrado diferente para o usuário.

Example 4.34. `screen`, `prompt`, e `userinput`

Uso:

<screen>&prompt.user; <userinput>ls -1</userinput> foo1 foo2 foo3 &prompt.user; <userinput>ls -1 | grep foo2</userinput> foo2 &prompt.user; <userinput>su</userinput> <prompt>Password: </prompt> &prompt.root; <userinput>cat foo2</userinput> This is the file called 'foo2'</screen>

Aparência:

`%` `ls -1` foo1 foo2 foo3 `%` `ls -1 | grep foo2` foo2 `%` `su` `Password:` `#` `cat foo2` This is the file called 'foo2'

### Note:

Ainda que estejamos mostrando o conteúdo do arquivo `foo2`, ele não está marcado como `programlisting`. Deixe o `programlisting` para mostrar fragmentos de arquivos fora do contexto de ação do usuário.

### 4.2.5. Elementos In-line

#### 4.2.5.1. Enfatizando a Informação

Quando você quiser enfatizar uma palavra ou frase em particular, use `emphasis`. Ela pode ser apresentada em itálico, ou negrito, ou pode ser falada diferentemente com um sistema texto-para-fala.

Não há uma maneira de mudar a apresentação da ênfase no seu documento, não existe um equivalente ao `b` e ao `i` do HTML. Se a informação que você está apresentando é importante então considere usar `important` ao invés de `emphasis`.

Example 4.35. `emphasis`

Uso:

<para>O FreeBSD é sem dúvida <emphasis>o</emphasis> melhor sistema operacional tipo Unix para a arquitetura Intel.</para>

Aparência:

O FreeBSD é sem dúvida o melhor sistema operacional tipo Unix para a arquitetura Intel.

#### 4.2.5.2. Citações

Para citar um texto de outro documento ou fonte, ou para denotar uma frase que está sendo usada figuradamente, use `quote`. Dentro da tag `quote`, você pode usar a maioria das marcações disponíveis para um texto normal.

Example 4.36. Citações

Uso:

<para>Entretanto, certifique-se que a busca não vá além do <quote>limite entre a administração local e pública</quote> como diz o RFC 1535.</para>

Aparência:

Entretanto, certifique-se que a busca não vá além do “limite entre a administração local e pública” como diz o RFC 1535.

#### 4.2.5.3. Teclas, Mouse e Combinações

Para se referir a uma tecla específica do teclado, use `keycap`. Para se referir a um botão do mouse, use `mousebutton`. E para se referir a combinação de digitar uma tecla e um clique do mouse, envolva-os com `keycombo`.

O `keycombo` tem um atributo chamado `action`, que pode ser `click`, `double-click`, `other`, `press`, `seq`, ou `simul`. Os dois últimos dizem se teclas ou botões devem ser pressionados em sequência ou simultaneamente.

As folhas de estilo colocam automaticamente o símbolo de ligação, tal como `+`, entre os nomes das teclas, quando elas estiverem envolvidas com `keycombo`.

Example 4.37. Teclas, Mouse e Combinações

Uso:

<para>Para mudar para o segundo terminal virtual, digite <keycombo action="simul"><keycap>Alt</keycap> <keycap>F1</keycap></keycombo>.</para> <para>Sair do <command>vi</command> sem salvar o seu trabalho, digite <keycombo action="seq"> <keycap>Esc</keycap><keycap>:</keycap> <keycap>q</keycap><keycap>!</keycap></keycombo>.</para> <para>Meu gerenciador de janela é configurado de forma que <keycombo action="simul"><keycap>Alt</keycap> <mousebutton>botão direito</mousebutton> </keycombo> do mouse é usado para mover as janelas.</para>

Aparência:

Para mudar para o segundo terminal virtual, digite Alt+F1.

Sair do `vi` sem salvar o seu trabalho, digite Esc : q !.

Meu gerenciador de janela é configurado de forma que Alt+botão direito do mouse é usado para mover as janelas.

#### 4.2.5.4. Aplicações, Comandos, Opções e Citações

Frequentemente você irá fazer referência tanto a aplicações quanto a comandos quando estiver escrevendo a documentação. A distinção entre eles é simples: uma aplicação é o nome de um pacote de programas (ou possivelmente apenas um) que executa uma tarefa em particular. Um comando é o nome de um programa que o usuário pode executar.

Além disso, você eventualmente precisará listar uma ou mais opções que um comando pode aceitar.

Finalmente, você irá querer listar um comando com o número da sua seção no manual, na forma “comando(número)” que é tão comum nos manuais de Unix.

Você deve marcar o nome de uma aplicação com `application`.

Quando você quiser listar um comando com o número da sua seção no manual (o que deve acontecer na maioria das vezes) o elemento do DocBook que deve ser utilizado é o `citerefentry`. Ele irá ter mais dois elementos, `refentrytitle` e `manvolnum`. O conteúdo de `refentrytitle` é o nome do comando, e o conteúdo de `manvolnum` é a seção da página do manual.

Pode ser trabalhoso escrever desta forma, para facilitar este processo foram criadas uma série de entidades gerais. Cada entidade está na forma `&man.`manual-page`.`manual-section`;`.

O arquivo que contém estas entidades é o `doc/share/xml/man-refs.ent`, o qual pode ser referenciado utilizando o seguinte FPI:

PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

Portanto, a introdução à sua documentação provavelmente será assim:

<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> %man; … ]>

Use o elemento `command` quando quiser incluir um comando “in-line” para ser apresentado como algo que deveria ser digitado pelo usuário.

Use o elemento `option` para marcar as opções que serão passadas para um comando.

Quando diversas referências a um mesmo comando estiverem próximas é melhor usar a notação `&man.`command`.`section`;` para marcar a primeira referência ao mesmo e depois utilizar `command` para marcar as referências subsequentes. Isto fará a saída gerada, especialmente em HTML, ficar visualmente melhor.

Isto pode ser confuso, e muitas vezes a escolha nem sempre é clara. Acredito que o exemplo abaixo ajudará a tornar as coisas mais claras.

Example 4.38. Aplicações, Comandos, Opções

Uso:

<para>O <application>Sendmail</application> é a aplicação de email mais utilizada em Unix.</para> <para>O <application>Sendmail</application> inclui os programas <citerefentry> <refentrytitle>Sendmail</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>, &man.mailq.1;, e &man.newaliases.1;.</para> <para>Um dos parâmetros de linha de comando para o <citerefentry> <refentrytitle>Sendmail</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>, <option>-bp</option>, ira mostrar o atual estado da mensagem na fila de email. Verifique isto na linha de comando usando <command>sendmail -bp</command>.</para>

Aparência:

O Sendmail é a aplicação de email mais utilizada em Unix.

O Sendmail inclui os programas sendmail(8), mailq(1), and newaliases(1).

Um dos parâmetros de linha de comando para o sendmail(8), `-bp`, irá mostrar o atual estado da mensagem na fila de email. Verifique isto na linha de comando usando `sendmail -bp`.

### Note:

Veja como a notação `&man.`command`.`section`;` é mais fácil de acompanhar.

#### 4.2.5.5. Arquivos, Diretórios, Extensões

Sempre que quiser se referir ao nome de um arquivo, diretório ou uma extensão de arquivo, use o elemento `filename`.

Example 4.39. `filename`

Uso:

<para>O fonte SGML do Handbook em Inglês pode ser encotrado em <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. O primeiro arquivo neste diretório é chamado <filename>book.xml</filename>. Você também deve ver o <filename>Makefile</filename> e alguns arquivos com a extensão <filename>.ent</filename>.</para>

Aparência:

O fonte SGML do Handbook em Inglês pode ser encotrado em `/usr/doc/en/handbook/`. O primeiro arquivo neste diretório é chamado `handbook.xml`. Você também deve ver o `Makefile` e alguns arquivos com a extensão `.ent`.

#### 4.2.5.6. O Nome dos Ports

### Extensões FreeBSD:

Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

Você pode precisar incluir o nome de um programa da Coleção de Ports do FreeBSD na documentação. Use a tag `filename` com o atributo `role` ajustado para `package` para identificá-lo. Uma vez que a coleção de ports pode ser instalada em diversos lugares, inclua apenas a categoria e o nome do port, não inclua o `/usr/ports`.

Example 4.40. Tag `filename` com o atributo `package`

Use:

<para>Instale o port <filename role="package">net/ethereal</filename> para ver o tráfego na rede.</para>

Aparência:

Instale o port `net/ethereal` para ver o tráfego na rede.

#### 4.2.5.7. Dispositivos

### Extensões FreeBSD:

Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

Você tem 2 opções para se referir a um dispositivo. Você pode se referir ao dispositivo da forma como ele aparece no `/dev`, ou você pode usar o nome do dispositivo como ele aparece no kernel. No segundo caso, use o elemento `devicename`.

Em alguns casos você não terá escolha. Alguns dispositivos, como as placas de rede, não tem entrada no `/dev`, ou as entradas são muito diferentes das esperadas.

Example 4.41. `devicename`

Uso:

<para><devicename>sio</devicename> é usado para comunicação serial no FreeBSD. <devicename>sio</devicename> se manifesta através de entradas em <filename>/dev</filename>, incluindo <filename>/dev/ttyd0</filename> e <filename>/dev/cuaa0</filename>. </para> <para>Por outro lado, dispositivos de rede, tais como <devicename>ed0</devicename> não aparecem <filename>/dev</filename>. </para> <para>No MS-DOS, o primeiro disco flexível é chamado de <devicename>a:</devicename>. No FreeBSD é <filename>/dev/fd0</filename>. </para>

Aparência:

`sio` é usado para comunicação serial no FreeBSD. `sio` se manifesta através de entradas em `/dev`, incluindo `/dev/ttyd0` e `/dev/cuaa0`.

Por outro lado, dispositivos de rede, tais como `ed0` não aparecem `/dev`.

No MS-DOS, o primeiro disco flexível é chamado de `a:`. No FreeBSD é `/dev/fd0`.

#### 4.2.5.8. Hosts, Domínios, Endereços IP e etc.

### Extensões FreeBSD:

Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

Você pode marcar a informação sobre a identificação de computadores em rede (hosts) de diversas maneiras. Todas elas usam `hostid` como elemento, com o atributo `role` dizendo o tipo da informação marcada.

Sem o atributo `role`, ou `role="hostname"`

  Sem o atributo `role` (i.e., `hostid`...`/hostid`) a informação marcada é simplesmente o nome do computador, tal como `freefall` ou `wcarchive`. Você pode especificar explicitamente com `role="hostname"`.

`role="domainname"`

  O texto é um nome de domínio, tal como `FreeBSD.org` ou `ngo.org.uk`. Não há o componente do nome do computador (hostname).

`role="fqdn"`

  O texto é um nome completo, com o nome do computador e do domínio. O termo `fqdn` significa “Fully Qualified Domain Name” - Nome de Domínio Completamente Qualificado.

`role="ipaddr"`

  O texto é um endereço IP, provavelmente expresso como `dotted quad`.

`role="ip6addr"`

  O texto é um endereço IPv6.

`role="netmask"`

  O texto é uma máscara de rede, que pode ser expressa como `dotted quad`, uma string hexadecimal ou como `/` seguido de um número.

`role="mac"`

  O texto é um endereço MAC Ethernet, expresso como números hexadecimais de 2 digitos separados por dois pontos (:).

Example 4.42. `Hostid` e `Roles`

Use:

<para>A máquina local sempre pode ser referida pelo nome <hostid>localhost</hostid>, que terá o endereço IP <hostid role="ipaddr">127.0.0.1</hostid>.</para> <para>O domínio <hostid role="domainname">FreeBSD.org</hostid> contém vários hosts diferentes, incluindo <hostid role="fqdn">freefall.FreeBSD.org</hostid> e <hostid role="fqdn">pointyhat.FreeBSD.org</hostid>.</para> <para>Quando estiver adicionando um apelido para uma interface (usando <command>ifconfig</command>) <emphasis>sempre</emphasis> use a máscara de rede <hostid role="netmask">255.255.255.255</hostid> (que também pode ser expressa como <hostid role="netmask">0xffffffff</hostid>). </para> <para>O endereço MAC identifica unicamente cada placa de rede existente. Um endereço MAC típico se parece com <hostid role="mac">08:00:20:87:ef:d0</hostid>).</para>

Aparência:

A máquina local sempre pode ser referida pelo nome `localhost`, que terá o endereço IP `127.0.0.1`.

O domínio `FreeBSD.org` contém vários hosts diferentes, incluindo `freefall.FreeBSD.org` e `bento.FreeBSD.org`.

Quando estiver adicionando um apelido para uma interface (usando `ifconfig`) sempre use a máscara de rede `255.255.255.255` (que também pode ser expressa como `0xffffffff`).

O endereço MAC identifica unicamente cada placa de rede existente. Um endereço MAC típico se parece com `08:00:20:87:ef:d0`.

#### 4.2.5.9. Usernames

### Extensões FreeBSD:

Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

Quando precisar se referir a um nome de usuário específico, tal como `root` ou `bin`, use o elemento `username`.

Example 4.43. `Username`

Uso:

<para>Para executar a maioria das funções administrativas você precisará ser <username>root</username>.</para>

Aparência:

Para executar a maioria das funções administrativas você precisará ser `root`.

#### 4.2.5.10. Descrevendo `Makefile`s

### Extensões FreeBSD:

Estes elementos são parte das extensões do FreeBSD ao DocBook, e não existem no DTD DocBook original.

Existem dois elementos para descrever partes de `Makefile`s, `maketarget` e `makevar`.

O `maketarget` identifica uma alvo de construção exportado por um `Makefile` que pode ser passado como um parâmetro ao `make`. O `makevar` identifica uma variável que pode ser ajustada (no ambiente, na linha de comando do `make`, ou dentro do `Makefile`) para influenciar o processo.

Example 4.44. `Maketarget` e `Makevar`

Uso:

<para>Dois alvos comuns em um <filename>Makefile</filename> são <maketarget>all</maketarget> e <maketarget>clean</maketarget>.</para> <para>Tipicamente, usar <maketarget>all</maketarget> irá refazer a aplicação, usar <maketarget>clean</maketarget> irá remover os arquivos temporários (<filename>.o</filename> por exemplo) criados pelo processo de construção.</para> <para><maketarget>clean</maketarget> pode ser controlado por muitas variáveis, incluindo <makevar>CLOBBER</makevar> e <makevar>RECURSE</makevar>.</para>

Aparência:

Dois alvos comuns em um `Makefile` são `all` e `clean`.

Tipicamente, usar `all` irá refazer a aplicação, usar `clean` irá remover os arquivos temporários (`.o` por exemplo) criados pelo processo de construção.

O `clean` pode ser controlado por muitas variáveis, incluindo `CLOBBER` e `RECURSE`.

#### 4.2.5.11. Texto Literal

Com frequência você irá precisar incluir texto “literal” na documentação. Este texto que é originado de outro arquivo, ou que deve ser copiado de forma fiel da documentação para outro arquivo.

Às vezes, o `programlisting` será suficiente. Mas o `programlisting` nem sempre é apropriado, particularmente quando você quer incluir uma parte de um arquivo “in-line” com todos os parágrafos.

Nestas ocasiões, use `literal`.

Example 4.45. `Literal`

Uso:

<para>A linha <literal>maxusers 10</literal> no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema, e diz aproximadamente quantos logins simultâneos o sistema irá suportar.</para>

Aparência:

A linha `maxusers 10` no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema, e diz aproximadamente quantos logins simultâneos o sistema irá suportar.

#### 4.2.5.12. Mostrando Itens que o Usuário Deve Preencher

Muitas vezes você irá querer mostrar ao usuário o que fazer, ou precisará se referir a um arquivo, a uma linha de comando ou coisa parecida, na qual ele não poderá simplesmente copiar o exemplo que você forneceu, mas na qual ele terá deve dar alguma informação por ele mesmo.

O elemento `replaceable` foi criado para estas ocasiões. Use ele dentro de outros elementos para indicar partes do conteúdo do elemento que o usuário deve substituir.

Example 4.46. `replaceable`

Uso:

<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>

Aparência:

`%` `man `comando``

O `replaceable` pode ser usado em muitos elementos diferentes, incluindo `literal`. Este exemplo também mostra que `replaceable` só deve envolver o conteúdo que o usuário deve fornecer. O outro conteúdo não deve ser alterado.

Uso:

<para>A linha <literal>maxusers <replaceable>n</replaceable></literal> no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema, e diz aproximadamente quantos logins simultâneos o sistema irá suportar. </para> <para>Para uma estação de trabalho, <literal>32</literal> é um bom valor para <replaceable>n</replaceable>.</para>

Aparência:

A linha `maxusers `n`` no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema, e diz aproximadamente quantos logins simultâneos o sistema irá suportar.

Para uma estação de trabalho, `32` é um bom valor para `n`.

#### 4.2.5.13. Citando erros do sistema

Você pode querer mostrar erros gerados pelo FreeBSD. Marque-os com `errorname`. Isto indicará o erro exato que aparece.

Example 4.47. `errorname`

Uso:

<screen><errorname>Panic: cannot mount root</errorname></screen>

Aparência:

Panic: cannot mount root

### 4.2.6. Imagens

### Important:

O suporte a imagem na documentação ainda é extremamente experimental. O mecanismo aqui descrito provavelmente não irá mudar, mas isto não é garantido.

Você precisará instalar o port `graphics/ImageMagick` que é usado para converter entre os diferentes formatos de imagens. Ele é grande e a sua maior parte não é necessária. Entretanto, enquanto nós ainda estamos trabalhando nos `Makefile`s e em outros itens da infraestrutura, ele torna as coisas mais fáceis. Este port não está no meta port `textproc/docproj`, você deve instalá-lo manualmente.

O melhor exemplo do que acontece na prática é o documento `doc/en_US.ISO8859-1/articles/vm-design/` . Se você se sentir inseguro na descrição que segue, dê uma olhada nos arquivos deste diretório e veja como tudo se encaixa. Experimente criar versões com diferentes formatos de saída do documento para ver como a marcação de imagem aparece no documento final.

#### 4.2.6.1. Formatos de Imagens

Atualmente suportamos dois formatos de imagens. O formato que você deve usar depende da natureza da sua imagem.

Para imagens vetoriais, tais como diagramas de rede, linhas temporais e similares, use Encapsulated Postscript, e certifique-se que suas imagens tenham a extensão `.eps`.

Para bitmaps, tais como a captura de uma tela, use o formato Portable Network Graphic, e certifique-se que suas imagens tenham a extensão `.png`.

Estes são os únicos formatos de imagem que podem ser gravados no repositório Subversion.

Use o formato correto para a imagem correta. Espera-se que a sua documentação tenha tanto imagens EPS quanto PNG. Os `Makefile`s asseguram que o formato correto seja escolhido dependendo do formato de saída da sua documentação. Não faça commit da mesma imagem nos dois formatos diferentes para o repositório.

### Important:

É esperado que o projeto de documentação passe a utilizar no futuro o formato Scalable Vector Graphic (SVG) para imagens vetoriais. Entretanto, o atual estado das ferramentas de edição torna isto impraticável.

#### 4.2.6.2. Marcação

A marcação para uma imagem é relativamente simples. Primeiro, marque um `mediaobject`. O `mediaobject` pode conter outros objetos mais específicos. Estamos interessandos em dois, o `imageobject` e o `textobject`.

Você deve incluir um `imageobject`, e dois elementos `textobject`. O `imageobject` irá apontar para o nome do arquivo da imagem que será usada (sem a extensão). Os elementos `textobject` contém a informação que será apresentada ao usuário junto, ou não, com a imagem.

Há duas circunstâncias em que isso pode ocorrer.

- Quando o leitor estiver vendo a documentação em HTML. Neste caso, cada imagem precisará ter um texto alternativo associado para mostrar ao usuário, tipicamente enquanto a imagem estiver sendo carregada, ou se ele parar o ponteiro do mouse sobre a imagem.

- Quando o leitor estiver vendo a documentação em modo texto. Neste caso, cada imagem deve ter uma ASCII art equivalente para mostrar ao usuário.

Um exemplo provavelmente irá tornar as coisas mais fáceis de se entender. Suponha que você tenha uma imagem, chamada `fig1.png`, que você queira incluir no documento. Esta imagem é um retângulo com um A dentro dele. A marcação para isso será:

<mediaobject> <imageobject> <imagedata fileref="fig1"> </imageobject> <textobject> <literallayout class="monospaced">+---------------+ | A | +---------------+</literallayout> </textobject> <textobject> <phrase>Uma figura</phrase> </textobject> </mediaobject>

| Inclua um elemento `imagedata` dentro do elemento `imageobject`. O atributo `fileref` deve conter o nome da imagem a ser incluída, sem a extensão. As folhas de estilo irão decidir qual a extensão deve ser adicionada ao nome do arquivo automaticamente.
| O primeiro `textobject` deve conter um elemento `literallayout`, onde o atributo `class` é ajustado para `monospaced`. Esta é a oportunidade para você demonstrar suas habilidades com ASCII art. O conteúdo será usado se o documento for convertido para texto puro. Veja como as primeras e últimas linhas do conteúdo do elemento `literallayout` fica próximo a tag do elemento. Isso assegura que não sejam incluídos espaços extras.
| O segundo `textobject` deve conter um único elemento `phrase`. O conteúdo deste elemento se tornará o atributo `alt` para as imagens quando o documento for convertido para HTML.

#### 4.2.6.3. Entradas no `Makefile`

Suas imagens devem estar listadas na variável `IMAGES` do `Makefile`. Esta variável deve conter o nome de todos fontes das suas imagens. Por exemplo, se você criou três figuras, `fig1.eps`, `fig2.png`, `fig3.png`, então o seu `Makefile` deve ter linhas como estas.

… IMAGES= fig1.eps fig2.png fig3.png …

ou

… IMAGES= fig1.eps IMAGES+= fig2.png IMAGES+= fig3.png …

De novo, o `Makefile` irá fazer uma lista completa das imagens necessárias para criar o seu documento fonte, você precisa listar apenas as imagens que você fornece.

#### 4.2.6.4. Imagens e Capítulos em Subdiretórios

Você precisa ser cuidadoso quando separar a sua documentação em arquivos menores (veja Section 3.7.1, “Utilizando entidades gerais para incluir arquivos”) em diretórios diferentes.

Suponha que você tenha um livro com três capítulos, e os capítulos estão armazenados cada um no seu próprio diretório, chamados `chapter1/chapter.xml`, `chapter2/chapter.xml`, e `chapter3/chapter.xml`. Se cada capítulo tiver imagens associadas a eles, é sugerido que você as coloque dentro do respectivo subdiretório de cada capítulo (`chapter1/`, `chapter2/`, `chapter3/`).

Entretanto, se você fizer isso você deve incluir o nome dos diretórios na variável `IMAGES` no `Makefile`, e deve incluir o nome do diretório no elemento `imagedata` do seu documento.

Por exemplo, se você tiver `chapter1/fig1.png`, então `chapter1/chapter.xml` deve conter:

<mediaobject> <imageobject> <imagedata fileref="chapter1/fig1"> </imageobject> … </mediaobject>

| O nome do diretório deve ser incluído no atributo `fileref`

O `Makefile` deve conter:

… IMAGES= chapter1/fig1.png …

Desta forma tudo deve funcionar.

### 4.2.7. Links

### Note:

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

#### 4.2.7.1. Ligando-se a outras partes no mesmo documento

Links dentro do mesmo documento exigem que você especifique de onde você esta se ligando (i.e., o texto no qual o usuário irá clicar, ou indicando de outra maneira a origem do link) e para onde você está se ligando (o destino do link).

Cada elemento dentro do DocBook tem um atributo chamado `id`. Você pode por um texto neste atributo para identificar unicamente o elemento associado a ele.

Este valor será usado quando você especificar a origem do link.

Normalmente, você irá se ligar apenas a capítulos ou seções, assim você irá colocar o atributo `id` nestes elementos.

Example 4.48. O atributo `id` em capítulos ou seções
<chapter id="chapter1"> <title>Introdução</title> <para>Esta é a introdução. Contém uma subseção que também será identificada. </para> <sect1 id="chapter1-sect1"> <title>Subseção 1</title> <para>Esta é a subseção.</para> </sect1> </chapter>

Obviamente, você deve usar nomes mais descritivos. Estes nomes devem ser únicos dentro do documento (i.e., não apenas no arquivo, mas sim no documento no qual o arquivo está incluído). Repare como o `id` é construído adicionando-se texto ao `id` do capítulo. Isto ajuda a garantir que eles sejam únicos.

Se você quiser permitir ao usuário saltar para uma parte específica do documento (possivelmente para o meio do parágrafo ou um exemplo), use o elemento `anchor`. Este elemento não tem conteúdo, mas aceita o atributo `id`.

Example 4.49. `anchor`
<para> Este parágrafo tem um <anchor id="para1">alvo dentro dele. O qual não irá aparecer no documento </para>

Quando você quiser dar ao usuário um link que possa ser ativado (provavelmente clicando-se) para ir para outra seção do documento que tenha um atributo `id`, você pode usar `xref` ou `link`.

Ambos os elementos têm um atributo `linkend`. O valor deste atributo deve ser o mesmo usado no atributo `id` (não importa se ele ainda não ocorreu no documento; isto funciona tanto para um link à frente quanto para trás).

Se você utilizar o `xref` então você não terá controle sobre o texto do link. Ele será gerado para você.

Example 4.50. Usando `xref`

Assuma que este fragmento apareça em algum lugar de um documento que inclua o `id` do exemplo.

<para>Maiores informações podem ser encontradas em <xref linkend="chapter1"/></para> <para>Informações mais específicas podem ser encontradas na <xref linkend="chapter1-sect1"/>.</para>

O texto do link será gerado automaticamente, e irá se parecer com (As palavras em itálico indicam o texto que será o link):

> Maiores informações podem ser encontradas no Capítulo Um.

> Informações mais específicas podem ser encontradas na seção chamada Subseção 1.

Observe como o texto do link é deduzido a partir do título da seção ou do número do capítulo.

### Note:

Isto significa que você não pode usar `xref` para se ligar a um atributo `id` em um elemento `anchor`. O `anchor` não tem conteúdo, desta forma o `xref` não pode gerar o texto para o link.

Se você quiser controlar o texto do link você deverá utilizar `link`. Este elemento envolve o conteúdo, e o conteúdo será usado para o link.

Example 4.51. Usando `link`

Assuma que este fragmento aparece em algum lugar em um documento que inclui o `id` do exemplo.

<para>Maiores informações podem ser encontradas <link linkend="chapter1">no primeiro capítulo</link>. </para> <para>Informações mais específicas podem ser encontradas <link linkend="chapter1-sect1">nesta</link> seção </para>

Isto irá gerar o seguinte (Palavras em itálico indicam o texto que será o link):

> Maiores informações podem ser encontradas no primeiro capítulo .

> Informações mais específicas podem ser encontradas nesta seção

### Note:

Este último é um mau exemplo. Nunca use palavras como “esta” ou “aqui” como origem do link. O leitor terá que procurar no contexto próximo para ver para onde o link o está levando.

### Note:

Você pode usar o elemento `link` para incluir um link para um `id` em um elemento `anchor`, uma vez que o conteúdo de `link` define o texto que será usado para o link.

#### 4.2.7.2. Ligando-se a documentos na WWW

Ligar-se a um documento externo é muito mais simples, desde que você saiba o URL do documento ao qual deseja se ligar. Basta utilizar o elemento `ulink`. O atributo `url` é o URL da página para o qual o link aponta, e o conteúdo do elemento é o texto que será mostrado para o usuário ativar.

Example 4.52. `ulink`

Uso:

<para>É claro que você pode parar de ler este documento e ir para a <ulink url="&url.base;/index.html">Página principal do FreeBSD</ulink> </para>

Aparência:

É claro que você pode parar de ler este documento e ir para a Página principal do FreeBSD

[3] Uma pequena história sobre este assunto pode ser encontrada em http://www.oasis-open.org/docbook/intro.shtml#d0e41.

[4] Há outros tipos de elementos de lista no DocBook, mas não vamos nos preocupar com eles no momento.

Prev | Up | Next
Chapter 4. Marcação SGML | Home | Chapter 5. * Folhas de Estilo

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