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 partes 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: head/pt_BR.ISO8859-1/books/fdp-primer/book.xml 52952 2019-04-21 13:28:34Z ebrandi $</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: head/pt_BR.ISO8859-1/books/fdp-primer/book.xml 52952 2019-04-21 13:28:34Z ebrandi $</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 nn indica o número da seção, que identifica o nível da seção.
A primeira sect é nsect1. 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
partes adiciona outro nível de organização entre book e chapter com uma ou mais partes. 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>.