9.4. Estrutura do Documento

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.

9.4.1. Iniciando um Livro

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.

Exemplo 9.1. Exemplo de 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>

9.4.2. Iniciando um Artigo

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.

Exemplo 9.2. Exemplo de 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>

9.4.3. Criando Capítulos

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.

Exemplo 9.3. Um Capítulo Simples
<chapter>
  <title>The Chapter's Title</title>

  ...
</chapter>

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.

Exemplo 9.4. Capítulos Vazios
<chapter>
  <title>This is An Empty Chapter</title>

  <para></para>
</chapter>

9.4.4. Seções Abaixo dos Capítulos

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 sectn. O n indica o número da seção, que identifica o nível da seção.

A primeira sectn é 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.

Exemplo 9.5. Seções em Capítulos
<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>

Nota:

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

9.4.5. Subdividindo Utilizando Elementos part

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>.