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
.
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.
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).
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 |
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.
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:
FreeBSD may reduce stress.
Please use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect.
Exemplos podem ser apresentados com example
.
example
Uso:
<example>
<para>
Empty files can be created easily:</para>
<screen>
&prompt.user;<userinput>
touch file1 file2 file3</userinput>
</screen>
</example>
Aparência:
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.
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.
This is the first ordered item.
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
.
variablelist
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:
In parallel communications, groups of bits arrive at the same time over multiple communications channels.
In serial communications, bits arrive one at a time over a single communications channel.
Um procedure
mostra uma série de step
s, que por sua vez consistem em mais step
s ou substep
s. 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
.
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:
Do this.
Then do this.
And now do this small thing.
And this other small thing.
Finally, do one of these:
Go left.
Go right.
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.
programlisting
Uso:
<para>
When finished, the program will look like this:</para>
<programlisting>
#include <stdio.h> 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; }
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.
co
e calloutlist
<para>
When finished, the program will look like this:</para>
<programlisting>
#include <stdio.h><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>int
main(void) { printf("hello, world\n");
}
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.
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 1 | This is Column Head 2 |
---|---|
Row 1, column 1 | Row 1, column 2 |
Row 2, column 1 | Row 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"
.
frame="none"
Aparência:
This is Column Head 1 | This is Column Head 2 |
---|---|
Row 1, column 1 | Row 1, column 2 |
Row 2, column 1 | Row 2, column 2 |
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
.
&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.
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'
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>.