You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

80 lines
2.4 KiB

4 years ago
////
Included in:
- user-manual
////
The preface is a special section of a book that precedes the first part or chapter of the book (or the first chapter of a part).
The preface can contain subsections.
An author explains how the idea behind her book manifested and developed in the preface.
The preface can include acknowledgments and may be signed by the author with her name, writing date and location.
For multi-part books, the preface must be defined as a level-0 section and any subsections must start at level 2.
[source]
----
= Book Title
:doctype: book
[preface]
= Documentation Preface
The basis for this documentation germinated when I awoke one morning and was confronted by the dark and stormy eyes of the chinchilla.
She had conquered the mountain of government reports that, over the course of six months, had eroded into several minor foothills and a creeping alluvial plain of loose papers.
=== Acknowledgments in Preface
I'd like to thank the Big Bang and String Theory.
Would we be without them?
= Part 1
...
----
For books without parts, the preface must be defined as a level-1 section and any subsections must start at level 2.
[source]
----
= Book Title
:doctype: book
[preface]
== Documentation Preface
The basis for this documentation germinated when I awoke one morning and was confronted by the dark and stormy eyes of the chinchilla.
She had conquered the mountain of government reports that, over the course of six months, had eroded into several minor foothills and a creeping alluvial plain of loose papers.
=== Acknowledgments in Preface
I'd like to thank the Big Bang and String Theory.
Would we be without them?
== Chapter 1
...
----
The same structure can be used to define a preface for a part.
As an alternative to a special section, Asciidoctor will automatically promote the preamble to a preface.
The title of the preface is set using the `preface-title` document attribute.
When defined this way, the preface may not contain subsections.
[source]
----
= Book Title
:doctype: book
:preface-title: Documentation Preface
The basis for this documentation germinated when I awoke one morning and was confronted by the dark and stormy eyes of the chinchilla.
She had conquered the mountain of government reports that, over the course of six months, had eroded into several minor foothills and a creeping alluvial plain of loose papers.
== Chapter 1
...
----
The special section is the preferred way of defining a preface.