9.4. 文件結構

DocBook allows structuring documentation in several ways. The FreeBSD Documentation Project uses two primary types of DocBook document: the book and the article.

Books are organized into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organization. For example, the Handbook is arranged in this way.

A chapter may (or may not) contain one or more sections. These are indicated with the sect1 element. If a section contains another section then use the sect2 element, and so on, up to sect5.

Chapters and sections contain the remainder of the content.

An article is simpler than a book, and does not use chapters. Instead, the content of an article is organized into one or more sections, using the same sect1 (and sect2 and so on) elements that are used in books.

The nature of the document being written should be used to determine whether it is best marked up as a book or an article. Articles are well suited to information that does not need to be broken down into several chapters, and that is, relatively speaking, quite short, at up to 20-25 pages of content. Books are best suited to information that can be broken up into several chapters, possibly with appendices and similar content as well.

The FreeBSD tutorials are all marked up as articles, while this document, the FAQ, and the Handbook are all marked up as books, for example.

9.4.1. 開始撰寫書籍

The content of a book is contained within the book element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page.

This additional information is contained within info.

範例 9.1. 使用 infobook 樣板
<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/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $</releaseinfo>

    <abstract>
      <para>Include an abstract of the book's contents here.</para>
    </abstract>
  </info></book>

9.4.2. 開始撰寫文章

The content of the article is contained within the article element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page.

This additional information is contained within info.

範例 9.2. 使用 infoarticle 樣板
<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/zh_TW.UTF-8/books/fdp-primer/book.xml 50507 2017-07-17 06:35:59Z rcyu $</releaseinfo>

    <abstract>
      <para>Include an abstract of the article's contents here.</para>
    </abstract>
  </info></article>

9.4.3. 標示章節

Use chapter to mark up your chapters. Each chapter has a mandatory title. Articles do not contain chapters, they are reserved for books.

範例 9.3. 簡單的章節
<chapter>
  <title>The Chapter's Title</title>

  ...
</chapter>

A chapter cannot be empty; it must contain elements in addition to title. If you need to include an empty chapter then just use an empty paragraph.

範例 9.4. 空白章節
<chapter>
  <title>This is An Empty Chapter</title>

  <para></para>
</chapter>

9.4.4. 章底下的小節

In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the sectn element. The n indicates the section number, which identifies the section level.

The first sectn is sect1. You can have one or more of these in a chapter. They can contain one or more sect2 elements, and so on, down to sect5.

範例 9.5. 章中的小節
<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>

注意:

Section numbers are automatically generated and prepended to titles when the document is rendered to an output format. The generated section numbers and titles from the example above will be:

  • 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. 使用 part 元素來分部

parts introduce another level of organization between book and chapter with one or more parts. This cannot be done in an article.

<part>
  <title>Introduction</title>

  <chapter>
    <title>Overview</title>

    ...
  </chapter>

  <chapter>
    <title>What is FreeBSD?</title>

    ...
  </chapter>

  <chapter>
    <title>History</title>

    ...
  </chapter>
</part>

本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

若有 FreeBSD 方面疑問,請先閱讀 FreeBSD 相關文件,如不能解決的話,再洽詢 <questions@FreeBSD.org>。

關於本文件的問題,請洽詢 <doc@FreeBSD.org>。