Publishing eBooks with AsciiDoc3
================================
// Web page meta data.
:keywords:    AsciiDoc3, EPUB tools, EPUB, PDF, ebooks
:description: How to create EPUB and PDF ebooks using https://asciidoc3.org[AsciiDoc3].

*! This document is partly outdated !*

It's easy to write and publish books in
http://en.wikipedia.org/wiki/EPUB[EPUB] and PDF formats using
http://asciidoc3.org/[AsciiDoc3].

Here are three examples: The first is a <<X1,minimal example>>
introducing the AsciiDoc3 format, the second <<X2,The Brothers
Karamazov>> is a rather long multi-part book and the third <<X3,The
Adventures of Sherlock Holmes>> includes a front cover image and
customized page styling.


[[X1]]
Minimal Book
------------
This didactic example contains a title and two chapters.  The AsciiDoc3
source is a plain text file named `minimal-book.txt` (save the content of
the following block to a file of this name):

---------------------------------------------------------------------
= The Book Title

== The first chapter
Nec vitae mus fringilla eu vel pede sed pellentesque. Nascetur fugiat
nobis. Eu felis id mauris sollicitudin ut. Sem volutpat feugiat.
Ornare convallis urna vitae.

Nec mauris sed aliquam nam mauris dolor lorem imperdiet.

== The second chapter
Ut suspendisse nulla. Auctor felis facilisis. Rutrum vivamus nec
lectus porttitor dui dapibus eu ridiculus tempor sodales et. Sit a
cras. Id tellus cubilia erat.

Quisque nullam et. Blandit dui tempor. Posuere in elit diam egestas
sem vivamus vel ac.
---------------------------------------------------------------------

To generate the EPUB formatted book file `minimal-book.epub` run
AsciiDoc's 'a2x3' toolchain wrapper command from the command-line:

  a2x3 -f epub -d book minimal-book.txt

The `-f` option specifies the output format, the `-d` option specifies
the document type (book, article or manpage).  The optional
`--epubcheck` option tells 'a2x3' to validate the EPUB file using
https://github.com/IDPF/epubcheck[epubcheck]. To generate a PDF
version (`minimal-book.pdf`) with 'dblatex' run:

  a2x3 -f pdf -d book minimal-book.txt

The distributed example PDFs were built using FOP -- if you prefer
http://xmlgraphics.apache.org/fop/[FOP] over
http://dblatex.sourceforge.net/[dblatex] use:

  a2x3 -f pdf -d book --fop minimal-book.txt

You can also generate an HTML formatted book, either using DocBook XSL
Stylesheets:

  a2x3 -f xhtml -d book minimal-book.txt

or directly using the 'asciidoc3' command:

  asciidoc3 -d book minimal-book.txt

[NOTE]
======
The 'a2x3' toolchain wrapper included in the AsciiDoc3 distribution uses
the following programs (most will be available prepackaged for your
Linux distribution):

- http://xmlsoft.org/XSLT/[xsltproc]
- http://docbook.sourceforge.net/projects/xsl/[DocBook XSL
  Stylesheets]
- http://dblatex.sourceforge.net/[dblatex] (PDF file generator)
- http://xmlgraphics.apache.org/fop/[FOP] (alternative PDF file
  generator)
- https://github.com/IDPF/epubcheck[epubcheck] (optional EPUB file
  validator)
======


[[X2]]
The Brothers Karamazov
----------------------
'The Brothers Karamazov' is an example of a multi-part book. To
generate the AsciiDoc3 source you have to download the
http://www.gutenberg.org[Project Gutenberg] plain text source and
edit it manually (this took around 15 minutes). To generate the
`brothers-karamazov.epub` EPUB file run this command:

  a2x3 brothers-karamazov.txt


[frame="topbot",options="header",caption=""]
.Brothers Karamazov source files and eBooks
|====================================================================
|EPUB |PDF |AsciiDoc3 source |Project Gutenburg text
| (empty, to be cont.)

| (empty, to be cont.)

| (empty, to be cont.)

|http://www.gutenberg.org/etext/28054

|====================================================================

Here's the start of the AsciiDoc3 source file showing the AsciiDoc3
specific meta-data:

---------------------------------------------------------------------
//
// Text from Project Gutenburg http://www.gutenberg.org/etext/28054
//
//
// a2x3 default options.
//    a2x3: -f epub -d book --epubcheck
// Suppress revision history in dblatex outputs.
//    a2x3: --dblatex-opts "-P latex.output.revhistory=0"
// Suppress book part, chapter and section numbering in DocBook XSL outputs.
//    a2x3: --xsltproc-opts
//    a2x3: "--stringparam part.autolabel 0
//    a2x3: --stringparam chapter.autolabel 0
//    a2x3: --stringparam section.autolabel.max.depth 0"
//

= The Brothers Karamazov
:author: Fyodor Dostoyevsky
:encoding: iso-8859-1
:plaintext:

..........................................................................
Translated from the Russian of Fyodor Dostoyevsky by Constance Garnett
The Lowell Press New York

 :
 :

***START OF THE PROJECT GUTENBERG EBOOK THE BROTHERS KARAMAZOV***
..........................................................................


= PART I

== The History Of A Family

=== Fyodor Pavlovitch Karamazov

Alexey Fyodorovitch Karamazov was the third son of Fyodor Pavlovitch
...
---------------------------------------------------------------------

- The book, book part and chapter titles have been edited to conform
  to AsciiDoc3 title conventions.

- Book part titles must be level zero titles:

  = Book title (level 0)
  = Part one title (level 0)
  == Chapter 1 title (level 1)
    :

- Sub-chapter levels can be accommodated with `===`, `====` and
  `=====` title prefixes.

- In this example the 'Project Gutenberg' front matter was put in the
  untitled preface inside an AsciiDoc literal block.

- The comment lines starting with `// a2x3:` contain 'a2x3' command
  options for this document (it's easier to put them in the document
  once than type them every time on the command-line).

- A number of 'xsltproc' options are passed to 'a2x3' to suppress book
  part, chapter and section numbering.

- Setting the AsciiDoc3 'plaintext' attribute suppresses most of
  AsciiDoc3's text formatting and substitution conventions, this allows large
  amounts of text to be imported with little or no manual editing.

  * Once you have defined the AsciiDoc3 'plaintext' attribute the only
    requisite manual editing will be to format the titles and rectify
    the odd paragraph being interpreted as some other AsciiDoc3 block
    element.
  * In the combined 49 thousand lines of imported 'Sherlock Holmes'
    and 'Brothers Karamazov' text I only encountered two
    misinterpreted list items, neither affected the rendered output or
    necessitated editing.
  * You can selectively enable and disable the 'plaintext' attribute
    throughout your document using AsciiDoc3 attribute entries.


[[X3]]
The Adventures of Sherlock Holmes
---------------------------------
This book includes a front cover image and a customized page design.
To generate the `adventures-of-sherlock-holmes.epub` EPUB file run
this command:

  a2x3 adventures-of-sherlock-holmes.txt

[frame="topbot",options="header",caption=""]
.Sherlock Holmes source files and eBooks
|====================================================================
|EPUB |PDF |AsciiDoc3 source |Project Gutenburg text
| (empty, to be cont.)

| (empty, to be cont.)

| (empty, to be cont.)

|http://www.gutenberg.org/etext/1661

|====================================================================

Here's the start of the AsciiDoc3 source file showing the AsciiDoc3
specific meta-data:

---------------------------------------------------------------------
//
// Text from Project Gutenburg http://www.gutenberg.org/etext/1661
//
//
// a2x3 default options.
//    a2x3: -f epub -d book -a docinfo --epubcheck
//    a2x3: --stylesheet adventures-of-sherlock-holmes.css
// Suppress revision history in dblatex outputs.
//    a2x3: --dblatex-opts "-P latex.output.revhistory=0"
// Suppress book part, chapter and section numbering in DocBook XSL outputs.
//    a2x3: --xsltproc-opts
//    a2x3: "--stringparam part.autolabel 0
//    a2x3: --stringparam chapter.autolabel 0
//    a2x3: --stringparam section.autolabel.max.depth 0"
// Additional resources.
//    a2x3: --resource underline.png
//

= The Adventures of Sherlock Holmes
:author: Sir Arthur Conan Doyle
:encoding: iso-8859-1
:plaintext:

== A Scandal in Bohemia

To Sherlock Holmes she is always THE woman. I have seldom heard
...
---------------------------------------------------------------------

Sherlock Holmes only has two title levels:

---------------------------------------------------------------------
= The Adventures of Sherlock Holmes
== A Scandal in Bohemia
== The Red-Headed League
== A Case of Identity
== The Boscombe Valley Mystery
== The Five Orange Pips
== The Man with the Twisted Lip
== The Adventure of the Blue Carbuncle
== The Adventure of the Speckled Band
== The Adventure of the Engineer's Thumb
== The Adventure of the Noble Bachelor
== The Adventure of the Beryl Coronet
== The Adventure of the Copper Beeches
== Colophon
---------------------------------------------------------------------


Styling your books
------------------
You can customize the appearance of a document with CSS.  CSS file.
Either create your own or copy and edit the existing default
`docbook-xsl.css` file (located in the AsciiDoc3 `stylesheets`
configuration directory) then place it in the same directory as your
AsciiDoc source file. Use the 'a2x3' `--stylesheet` option if you want
to use a different stylesheet file.


Including embedded fonts
------------------------
See ./doc/faq.txt 'How can I include embedded fonts in an EPUB document?'


Non-fiction Books and Manuals
-----------------------------
AsciiDoc3 supports a rich set of markup conventions and can generate
reference works and technical manuals complete with tables,
illustrations, indexes, bibliographies and appendices. All the
examples included in the AsciiDoc3 distribution can be formatted as EPUB eBooks.
