9.5. Elementos Block

9.5.1. Parágrafos

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

Quase todos os parágrafos da documentação do FreeBSD usam para. formalpara inclui um elemento title, e simpara desabilita alguns elementos de um para. Utilize mais o para .

Exemplo 9.6. Exemplo de um para

Uso:

<para>This is a paragraph.  It can contain just about any
  other element.</para>

Aparência:

This is a paragraph. It can contain just about any other element.


9.5.2. Bloco de Citações

Uma cotação em bloco é uma cotação estendida de outro documento que não deve aparecer no parágrafo atual. Estes raramente são necessários.

Os blockquotes podem, opcionalmente, conter um título e uma atribuição (ou podem ser deixados sem título e sem atribuição).

Exemplo 9.7. Exemplo blockquote

Uso:

<para>A small excerpt from the US Constitution:</para>

<blockquote>
  <title>Preamble to the Constitution of the United States</title>

  <attribution>Copied from a web site somewhere</attribution>

  <para>We the People of the United States, in Order to form a more
    perfect Union, establish Justice, insure domestic Tranquility,
    provide for the common defence, promote the general Welfare, and
    secure the Blessings of Liberty to ourselves and our Posterity, do
    ordain and establish this Constitution for the United States of
    America.</para>
</blockquote>

Aparência:

A small excerpt from the US Constitution:

 
Preamble to the Constitution of the United States

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

 
 --Copiado de um site qualquer

9.5.3. Dicas, Notas, Avisos, Cuidados e Informações Importantes

Informações adicionais podem precisar ser separadas do texto principal. Normalmente, essa é a informação meta da qual o usuário deve estar ciente.

Vários tipos de informações estão disponíveis: tip, note, warning, caution, e important.

O tipo a ser escolhido depende da situação. A documentação do DocBook sugere:

  • A nota é para informações onde todos os leitores devem prestar atenção.

  • Importante é uma variação de Nota.

  • Cuidado é para informações sobre possíveis perdas de dados ou danos ao software.

  • Aviso é para informações sobre possíveis danos ao hardware, sobre risco de vida ou de ferimento a um membro.

Exemplo 9.8. Example de tip e important

Uso:

<tip>
  <para>&os; may reduce stress.</para>
</tip>

<important>
  <para>Please use admonitions sparingly.  Too many admonitions
    are visually jarring and can have the opposite of the
    intended effect.</para>
</important>

Aparência:

Dica:

FreeBSD may reduce stress.

Importante:

Please use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect.

9.5.4. Exemplos

Exemplos podem ser apresentados com example.

Exemplo 9.9. example

Uso:

<example>
  <para>Empty files can be created easily:</para>

  <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen>
</example>

Aparência:

Exemplo 9.10. example Renderizado

Empty files can be created easily:

% touch file1 file2 file3

9.5.5. Listas e Procedimentos

Muitas vezes, as informações precisam ser apresentadas como listas ou como uma série de etapas que devem ser realizadas para atingir um objetivo específico.

Para fazer isso, utilize itemizedlist, orderedlist, variablelist ou procedure. Existem outros tipos de elementos de lista no DocBook, mas não os cobriremos aqui.

itemizedlist e orderedlist são semelhantes às suas contrapartes em HTML, ul e ol. Cada um consiste em um ou mais elementos listitem, e cada listitem contém um ou mais elementos de bloco. Os elementos listitem são análogos às tags li do HTML. No entanto, ao contrário do HTML, eles são obrigatórios.

Exemplo 9.11. Exemplo de itemizedlist e orderedlist

Uso:

<itemizedlist>
  <listitem>
    <para>This is the first itemized item.</para>
  </listitem>

  <listitem>
    <para>This is the second itemized item.</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>This is the first ordered item.</para>
  </listitem>

  <listitem>
    <para>This is the second ordered item.</para>
  </listitem>
</orderedlist>

Aparência:

  • This is the first itemized item.

  • This is the second itemized item.

  1. This is the first ordered item.

  2. This is the second ordered item.


Uma maneira alternativa e frequentemente útil de apresentar informações é a variablelist. Estas são listas onde cada entrada tem um termo e uma descrição. Eles são adequados para muitos tipos de descrições e apresentam informações de uma forma que geralmente é mais fácil para o leitor do que seções e subseções.

Uma variablelist tem um title e, em seguida, pares de entradas term e listitem.

Exemplo 9.12. Exemplovariablelist

Uso:

<variablelist>
  <varlistentry>
    <term>Parallel</term>

    <listitem>
      <para>In parallel communications, groups of bits arrive
	at the same time over multiple communications
	channels.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>Serial</term>

    <listitem>
      <para>In serial communications, bits arrive one at a
	time over a single communications
	channel.</para>
    </listitem>
  </varlistentry>
</variablelist>

Aparência:

Parallel

In parallel communications, groups of bits arrive at the same time over multiple communications channels.

Serial

In serial communications, bits arrive one at a time over a single communications channel.


Um procedure mostra uma série de steps, que por sua vez consistem em mais steps ou substeps. Cada step contém elementos de bloco e pode incluir um título opcional.

Às vezes, os passos não são sequenciais, mas apresentam uma escolha: fazer isso ou fazer aquilo, mas não ambos. Para essas escolhas alternativas, use stepalternatives.

Exemplo 9.13. Exemplo procedure

Uso:

<procedure>
  <step>
    <para>Do this.</para>
  </step>

  <step>
    <para>Then do this.</para>
  </step>

  <step>
    <substeps>
      <step>
        <para>And now do this smaller thing.</para>
      </step>

      <step>
        <para>And now do this other smaller thing.</para>
      </step>
    </substeps>
  </step>

  <step>
    <para>Finally, do one of these:</para>

    <stepalternatives>
      <step>
	<para>Go left.</para>
      </step>

      <step>
	<para>Go right.</para>
      </step>
    </stepalternatives>
  </step>
</procedure>

Aparência:

  1. Do this.

  2. Then do this.

    1. And now do this small thing.

    2. And this other small thing.

  3. Finally, do one of these:

    • Go left.

    • Go right.


9.5.6. Mostrando Exemplos de Arquivos

Fragmentos de um arquivo (ou talvez um arquivo completo) são mostrados agrupando-os no elemento programlisting.

Espaço em branco e quebra de linha dentro de programlisting são importantes. Em particular, isso significa que a tag de abertura deve aparecer na mesma linha que a primeira linha da saída, e a tag de fechamento deve aparecer na mesma linha da última linha da saída, caso contrário linhas vazias podem ser incluídas.

Exemplo 9.14. Exemplo programlisting

Uso:

<para>When finished, the program will look like
  this:</para>

<programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("hello, world\n");
    return 0;
}</programlisting>

Observe como os colchetes angulares na linha #include precisam ser referenciados por suas entidades, em vez de serem incluídos literalmente.

Aparência:

When finished, the program will look like this:

#include <stdio.h>

int
main(void)
{
    printf("hello, world\n");
    return 0;
}

9.5.7. Chamadas

Uma chamada é um marcador visual para se referenciar a um texto ou a uma posição específica em um exemplo.

As chamadas são marcadas com o elemento co. Cada elemento deve ter um id único atribuído a ele. Após o exemplo, inclua uma calloutlist que descreve cada frase de destaque.

Exemplo 9.15. Exemplo co e calloutlist
<para>When finished, the program will look like
  this:</para>

<programlisting>#include &lt;stdio.h&gt; <co xml:id="co-ex-include"/>

int <co xml:id="co-ex-return"/>
main(void)
{
    printf("hello, world\n"); <co xml:id="co-ex-printf"/>
}</programlisting>

<calloutlist>
  <callout arearefs="co-ex-include">
    <para>Includes the standard IO header file.</para>
  </callout>

  <callout arearefs="co-ex-return">
    <para>Specifies that <function>main()</function> returns an
      int.</para>
  </callout>

  <callout arearefs="co-ex-printf">
    <para>The <function>printf()</function> call that writes
      <literal>hello, world</literal> to standard output.</para>
  </callout>
</calloutlist>

Aparência:

When finished, the program will look like this:

#include <stdio.h> 1

int 2
main(void)
{
    printf("hello, world\n"); 3
}

1

Includes the standard IO header file.

2

Specifies that main() returns an int.

3

The printf() call that writes hello, world to standard output.


9.5.8. Tabelas

Ao contrário de HTML, o DocBook não precisa de tabelas para fins de layout, já que a folha de estilo lida com esses problemas. Em vez disso, basta usar tabelas para marcar dados tabulares.

Em termos gerais (e veja a documentação do DocBook para mais detalhes), uma tabela (que pode ser formal ou informal) consiste em um elemento table. Este contém pelo menos um elemento tgroup, que especifica (como um atributo) o número de colunas neste grupo de tabelas. Dentro do tgroup há um elemento thead, que contém elementos para os títulos da tabela (cabeçalhos da coluna), e um tbody que contém o corpo da tabela.

Ambos tgroup e thead contêm elementos row, que por sua vez contêm elementos entry. Cada elemento entry especifica uma célula na tabela.

Exemplo 9.16. Exemplo informaltable

Uso:

<informaltable pgwide="1">
  <tgroup cols="2">
    <thead>
      <row>
        <entry>This is Column Head 1</entry>
        <entry>This is Column Head 2</entry>
      </row>
    </thead>

    <tbody>
      <row>
	<entry>Row 1, column 1</entry>
	<entry>Row 1, column 2</entry>
      </row>

      <row>
	<entry>Row 2, column 1</entry>
	<entry>Row 2, column 2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

Aparência:

This is Column Head 1This is Column Head 2
Row 1, column 1Row 1, column 2
Row 2, column 1Row 2, column 2

Sempre use o atributo pgwide com um valor 1 com o elemento informaltable. Um erro no Internet Explorer pode fazer com que a tabela seja renderizada incorretamente se isso for omitido.

As bordas da tabela podem ser escondidas configurando o atributo frame para none no elemento informaltable. Por exemplo, informaltable frame="none".

Exemplo 9.17. Exemplo de Tabela com frame="none"

Aparência:

This is Column Head 1This is Column Head 2
Row 1, column 1Row 1, column 2
Row 2, column 1Row 2, column 2

9.5.9. Exemplos para o Usuário Seguir

Exemplos para o usuário seguir são freqüentemente necessários. Normalmente, eles consistem em diálogos com o computador; o usuário digita um comando, o usuário recebe uma resposta de volta, o usuário digita outro comando e assim por diante.

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

screen

Tudo o que o usuário vê neste exemplo estará na tela do computador, então o próximo elemento é screen .

Dentro da screen, o espaço em branco é significativo.

prompt, &prompt.root; and &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.

Nota:

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

userinput

Ao exibir o texto que o usuário deve digitar, coloque-o nas tags userinput. Ele provavelmente será mostrado diferente para o usuário.

Exemplo 9.18. Exemplos 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'

Nota:

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ções do usuário.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.