O DocBook permite a documentação de estruturação de várias maneiras. O Projeto de Documentação do FreeBSD usa dois tipos principais de documentos do DocBook: o book e o article.
Os livros (books) são organizados em chapter
s. Este é um requisito obrigatório. Pode haver part
es entre o livro e o capítulo para fornecer outra camada de organização. Por exemplo, o Handbook é organizado dessa maneira.
Um capítulo(chapter) pode (ou não) conter uma ou mais seções. Estes são indicados com o elemento sect1
. Se uma seção contiver outra seção, use o elemento sect2
e assim por diante, até sect5
.
Capítulos e seções contêm o restante do conteúdo.
Um artigo é mais simples que um livro e não utiliza capítulos. Em vez disso, o conteúdo de um artigo é organizado em uma ou mais seções, usando os mesmos elementos sect1
(e sect2
e assim por diante) que são usados em livros.
A natureza do documento que está sendo escrito deve ser usada para determinar se ele é melhor marcado como um livro ou um artigo. Os artigos são adequados à informação que não precisa ser dividida em vários capítulos, ou seja, relativamente curta, em até 20-25 páginas de conteúdo. Os livros são mais adequados para informações que podem ser divididas em vários capítulos, possivelmente com apêndices e conteúdo similar também.
Os Tutoriais do FreeBSD estão todos marcados como artigos, enquanto este documento, o FAQ e o Handbook estão todos marcados como livros, por exemplo.
O conteúdo de um livro está dentro do elemento book
. Além de conter marcação estrutural, esse elemento pode conter elementos que incluem informações adicionais sobre o livro. Isso é uma meta-informação, usada para fins de referência ou conteúdo adicional usado para produzir um título de página.
Esta informação adicional está em um elemento info
.
book
com info
<book>
<info>
<title>
Your Title Here
</title>
<author>
<personname>
<firstname>
Your first name
</firstname>
<surname>
Your surname
</surname>
</personname>
<affiliation>
<address>
<email>
Your email address
</email>
</address>
</affiliation>
</author>
<copyright>
<year>
1998
</year>
<holder role="mailto:
your email address
">Your name
</holder>
</copyright>
<releaseinfo>
$FreeBSD$</releaseinfo>
<abstract>
<para>
Include an abstract of the book's contents here.
</para>
</abstract>
</info>
…</book>
O conteúdo do artigo está dentro do elemento article
. Além de conter marcação estrutural, esse elemento pode conter elementos que incluem informações adicionais sobre o artigo. Isso é uma meta-informação, usada para fins de referência ou conteúdo adicional usado para produzir um título de página.
Esta informação adicional está em um elemento info
.
article
com info
<article>
<info>
<title>
Your title here
</title>
<author>
<personname>
<firstname>
Your first name
</firstname>
<surname>
Your surname
</surname>
</personname>
<affiliation>
<address>
<email>
Your email address
</email>
</address>
</address>
</affiliation>
</author>
<copyright>
<year>
1998
</year>
<holder role="mailto:
your email address
">Your name
</holder>
</copyright>
<releaseinfo>
$FreeBSD$</releaseinfo>
<abstract>
<para>
Include an abstract of the article's contents here.
</para>
</abstract>
</info>
…</article>
Use chapter
para marcar seus capítulos. Cada capítulo tem um title
obrigatório. Os artigos não contêm capítulos, eles são reservados para livros.
Um capítulo não pode estar vazio; ele deve conter elementos além do title
. Se você precisar incluir um capítulo vazio, basta usar um parágrafo vazio.
<chapter>
<title>
This is An Empty Chapter</title>
<para>
</para>
</chapter>
Nos livros, os capítulos podem (mas não precisam) ser divididos em seções, subseções e assim por diante. Nos artigos, as seções são o principal elemento estrutural e cada artigo deve conter pelo menos uma seção. Use o elemento sect
. O n
n
indica o número da seção, que identifica o nível da seção.
A primeira sect
é n
sect1
. Você pode ter um ou mais destes em um capítulo. Eles podem conter um ou mais elementos sect2
e assim por diante, até sect5
.
<chapter>
<title>
A Sample Chapter</title>
<para>
Some text in the chapter.</para>
<sect1>
<title>
First Section</title>
…</sect1>
<sect1>
<title>
Second Section</title>
<sect2>
<title>
First Sub-Section</title>
<sect3>
<title>
First Sub-Sub-Section</title>
…</sect3>
</sect2>
<sect2>
<title>
Second Sub-Section (1.2.2)</title>
…</sect2>
</sect1>
</chapter>
Os números de seção são gerados automaticamente e anexados aos títulos quando o documento é renderizado em um formato de saída. Os números de seção e títulos gerados a partir do exemplo acima serão:
1.1. First Section
1.2. Second Section
1.2.1. First Sub-Section
1.2.1.1. First Sub-Sub-Section
1.2.2. Second Sub-Section
part
es adiciona outro nível de organização entre book
e chapter
com uma ou mais part
es. Isso não pode ser utilizado em um article
.
<part>
<title>
Introduction</title>
<chapter>
<title>
Overview</title>
...</chapter>
<chapter>
<title>
What is FreeBSD?</title>
...</chapter>
<chapter>
<title>
History</title>
...</chapter>
</part>
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>.