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).
blockquoteUso:
<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 importantUso:
<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.
exampleUso:
<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 orderedlistUso:
<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.
variablelistUso:
<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 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.
procedureUso:
<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.
programlistingUso:
<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.
informaltableUso:
<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.
screenTudo 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.
userinputAo 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 userinputUso:
<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 -1foo1 foo2 foo3%ls -1 | grep foo2foo2%suPassword:#cat foo2This 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>.