asciidoctor-epub3 1.5.0.alpha.13 → 1.5.0.alpha.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4f831d387c7237550665244c656f6ca2dac2647653c6cf7610bc89c36b06a8c
-  data.tar.gz: 06aef58ded0b2fb74c209ed0fadf778bbb24fecea8eeb6f2afb68fa35abaaf01
+  metadata.gz: 352b650ba19d840c6f0eb7cdcc1f6abe941d05316b4d92d220faf2e21b63ba87
+  data.tar.gz: fd2a164d0c20c9ee6415e47d9d77db71f6ba09500219778508794e6210b93130
 SHA512:
-  metadata.gz: 9bf6101b7f06ed604fece602f37de8ddc80aedf76f5737cb9a45b2aa374a9bb4ce2e41f2b0c5a9eba566f337e9612daefcafbf53fe414bc2316677b5d40f965a
-  data.tar.gz: fe597bf15bdcec4b6774b74a881a6228908db92f178c8c364c511c40edc24db993159c0bbf819705cd2414d40d8ffed63c2a556cadeb373ef1593da7ac5f8f38
+  metadata.gz: be30f10eaa7309066230c86e3f124cda27a9668a0b1eac7ac2d68f70eddacb2ab9886dadcd96ac292845d4da28c52ffefa63ded60282cbf0d55c39fa8efbf0df
+  data.tar.gz: 3e1ec0eef64136a609d402a5cae8b4bb03007ea462a362f2e33df55ed0b84bdc624c61b9813cafca1a35d81401c31859fef28f487505aaaaa036944134f7ad77

data/CHANGELOG.adoc

@@ -5,6 +5,69 @@
 This document provides a high-level view of the changes to the {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== 1.5.0.alpha.18 (2020-07-27) - @slonopotamus
+
+* remove <b> from chapter subtitle (#123)
+* improve tables support: cell content alignment, column width (#350)
+* fix chapter titles to actually be chapter titles instead of document title (#343)
+* store syntax highlighter CSS in a separate file (#339)
+* initial landmarks support: appendix, bibliography, bodymatter, cover, frontmatter, glossary, index, preface, toc (#174)
+* add support for in-document table of contents via `:toc:` document attribute (#174)
+* add support for MathML (#10)
+* rescale color palette to use darker shades of gray (#338)
+* gracefully handle invalid `:front-cover-image:` value (#353)
+
+== 1.5.0.alpha.17 (2020-05-25) - @slonopotamus
+
+* support remote URLs for audio/video/image (#333, #334)
+
+== 1.5.0.alpha.16 (2020-04-26) - @slonopotamus
+
+* add basic audio and video support (#9)
+* add support for `[horizontal]` definition list (#165)
+* add proper handling of `:data-uri:` document attribute (#324)
+* add support for customizable document splitting into chapters via `epub-chapter-level` attribute (#327)
+* avoid outputting 'true' for unsupported blocks (#332)
+
+== 1.5.0.alpha.15 (2020-03-11) - @slonopotamus
+
+* support section numbering and captions (#20)
+* fix `\<<anchor,link text>>` to show link text (#317)
+* add xref ids to paragraphs (#317)
+* support syntax highlighting with CodeRay and Rouge (#262)
+* pygments.rb is no longer auto-activated
+* add series metadata (#307)
+* fix Sony Reader crash (#152)
+
+== 1.5.0.alpha.14 (2020-02-29) - @slonopotamus
+
+* support conversion of article documents to a single-chapter file
+* stop requiring specific include file scheme (#47)
+* support special chapters like bibliography (#205)
+* `basedir` now points to main document directory when processing chapter files (#190)
+* fix image and listing numbers being reset in each chapter (#178)
+* fix xref resolving between sub-includes of chapter files (#166)
+* add support for contentless include files (#151)
+* drop nonstandard `<<chapter#>>` xref syntax and instead support vanilla `<<anchor>>` or `<<file#anchor>>` syntax (#136)
+* properly include bibliography generated by asciidoctor-bibtex (#206)
+* require Asciidoctor 1.5.6+
+* add support for book preamble (#303)
+* add basic support for multi-part books (#304)
+* do not include current date if `:reproducible:` attribute is set (#203)
+* respect `SOURCE_DATE_EPOCH` environment variable for reproducible builds
+* fix invalid markup produced for tables with footer (#295)
+* add support for image width/height attributes (#183)
+* log KindleGen warnings with WARNING log level (#291)
+* convert stem blocks to `<code>$stem_text</code>` (#10)
+* use imagedir from an image's context during packaging (#282)
+* fix images in tables not included in epub archive (#169)
+* search for `front-matter.html` in document dir instead of CWD (#300)
+* fix inline images not being included in epub archive (#30)
+* add support for Font Awesome Solid 5.12.0 (#155)
+* fix inline anchors missing their ids (#201)
+* support multiple front-matter files via `epub3-frontmatterdir` attribute
+* add support for multiple authors in book metadata
+
 == 1.5.0.alpha.13 (2020-02-04) - @slonopotamus
 
 * remove kindlegen and epubcheck-ruby from runtime dependencies (#288)

data/Gemfile

@@ -5,17 +5,16 @@ source 'https://rubygems.org'
 # Look in asciidoctor-epub3.gemspec for runtime and development dependencies.
 gemspec
 
-gem 'asciidoctor', ENV['ASCIIDOCTOR_VERSION'], require: false if ENV.key? 'ASCIIDOCTOR_VERSION'
+if ENV.key? 'ASCIIDOCTOR_VERSION'
+  gem 'asciidoctor', ENV['ASCIIDOCTOR_VERSION'], require: false
+  # Newer asciidoctor-diagram 1.5.x require asciidoctor >=1.5.7
+  gem 'asciidoctor-diagram', '1.5.16', require: false if Gem::Version.new(ENV['ASCIIDOCTOR_VERSION']) < Gem::Version.new('2.0.0')
+end
 
 group :optional do
   # epubcheck-ruby might be safe to be converted into runtime dependency, but could have issues when packaged into asciidoctorj-epub3
-  gem 'epubcheck-ruby', '~> 4.2.2.0'
+  gem 'epubcheck-ruby', '~> 4.2.4.0'
   # We would like to make kindlegen a runtime dependency, but can't because of the way asciidoctorj-epub3 packaging works
   # See https://github.com/asciidoctor/asciidoctor-epub3/issues/288
   gem 'kindlegen', '~> 3.0.3'
-  gem 'pygments.rb', '1.2.1'
-end
-
-group :docs do
-  gem 'yard', require: false
 end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2014-2020 OpenDevise Inc. and the Asciidoctor Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

data/NOTICE.adoc

@@ -36,15 +36,15 @@ Noto Serif font::
 
   - https://code.google.com/p/noto/
 
-Font Awesome icon font (v4.0.3)::
+Font Awesome icon font (v5.12.0)::
   Font Awesome, the iconic font designed for Bootstrap by David Gandy, is used for the admonition icons and other icons in author's content and bundled in the EPUB3 archive.
   Font Awesome is fully open source and GPL compatible.
   The font is licensed under the SIL Open Font 1.1 License (OFL).
   You may obtain a copy of the license at:
 
-  http://scripts.sil.org/OFL
+  https://scripts.sil.org/OFL
 
-  - http://fontawesome.io
+  - https://fontawesome.io
 
 normalize.css (v3.0.1)::
   A customized version of normalize.css is used to provide cross-reader consistency in the default styling of HTML elements.

data/README.adoc

@@ -1,6 +1,6 @@
 = {project-name}: A _native_ EPUB3 converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.alpha.13, 2020-02-04
+v1.5.0.alpha.18, 2020-07-27
 // Settings:
 :experimental:
 :idprefix:
@@ -27,31 +27,30 @@ endif::[]
 :project-handle: asciidoctor-epub3
 // URIs:
 :uri-project: https://github.com/asciidoctor/{project-handle}
-:uri-gem: http://rubygems.org/gems/asciidoctor-epub3
+:uri-gem: https://rubygems.org/gems/asciidoctor-epub3
 :uri-repo: {uri-project}
 :uri-issues: {uri-repo}/issues
-:uri-ci: {uri-repo}/actions?query=workflow%3ACI
-:uri-discuss: http://discuss.asciidoctor.org
+:uri-ci: {uri-repo}/actions?query=branch%3Amaster
+:uri-discuss: https://discuss.asciidoctor.org/
 :uri-rvm: https://rvm.io
-:uri-asciidoctor: http://asciidoctor.org
+:uri-asciidoctor: https://asciidoctor.org/
 :uri-idpf: http://www.idpf.org/
 :uri-epub: http://www.idpf.org/epub/31/spec/epub-spec.html
-:uri-epubcheck: https://github.com/idpf/epubcheck
-:uri-kindlegen: http://www.amazon.com/gp/feature.html?docId=1000765211
+:uri-epubcheck: https://github.com/w3c/epubcheck
+:uri-kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211
 :uri-kf8: http://www.amazon.com/gp/feature.html?docId=1000729511
 :uri-send-to-kindle: https://www.amazon.com/gp/sendtokindle/
 :uri-metadata-elem: http://www.idpf.org/epub/30/spec/epub30-publications.html#sec-metadata-elem
-:uri-dc: http://dublincore.org/documents/2004/12/20/dces
+:uri-dc: https://www.dublincore.org/specifications/dublin-core/dces/2004-12-20/
 :uri-github-guides: https://guides.github.com
 :uri-github-guides-fork: https://github.com/opendevise/github-guides-asciidoc
-:uri-asciidoctor-i18n: http://asciidoctor.org/docs/user-manual/#builtin-attributes-i18n
+:uri-asciidoctor-i18n: https://asciidoctor.org/docs/user-manual/#builtin-attributes-i18n
 :uri-epubreadingsystem: http://www.idpf.org/epub/301/spec/epub-contentdocs.html#app-epubReadingSystem
-:uri-android-sdk: http://developer.android.com/sdk/index.html
+:uri-android-sdk: https://developer.android.com/sdk/index.html
 
 ifdef::status[]
 image:https://img.shields.io/gem/v/asciidoctor-epub3.svg[Latest Release,link={uri-gem}]
-image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License,link=#copyright]
-image:{uri-repo}/workflows/CI/badge.svg[GitHub Actions,link={uri-ci}]
+image:{uri-repo}/workflows/CI/badge.svg?branch=master[GitHub Actions,link={uri-ci}]
 endif::[]
 
 {project-name} is a set of Asciidoctor extensions for converting AsciiDoc documents directly to the EPUB3 and KF8/MOBI e-book formats.
@@ -103,12 +102,13 @@ Of course, there's always room for improvement, so we'll continue to work with y
 * EPUB3 metadata, manifest and spine (assembled by Gepub)
 * Document metadata (title, authors, subject, keywords, etc.)
 * Internal cross reference links
-* Syntax highlighting with CodeRay or Pygments (must use inline styles)
+* Syntax highlighting with Rouge, CodeRay or Pygments
 * Unicode callout numbers
 * Page breaks avoided in block content (so much as it's supported by the e-reader)
 * Orphan section titles avoided (so much as it's supported by the e-reader)
 * Table border settings honored
 * Support for SVG images in the content
+* Stem blocks via AsciiMath
 
 === Project Status
 
@@ -122,7 +122,7 @@ We may explore the use of fixed layout documents in the future if the need arise
 ifdef::env-github[]
 === Planned Features and Work In Progress
 
-See <<WORKLOG#,WORKLOG.adoc>>.
+See link:WORKLOG.adoc[].
 endif::[]
 
 == Converter Workflow
@@ -137,121 +137,47 @@ The EPUB3 publication, which can be thought of as the “digital master”, is a
 
 An EPUB3 archive is composed of multiple files. The content of each “chapter” is typically stored in a dedicated XHTML file.
 Therefore, the {project-name} converter “chunks” the AsciiDoc source document into multiple XHTML files to add to the EPUB3 archive.
-While other converters handle this chunking task by automatically slicing up the XHTML output at predetermined heading levels, this converter takes a different approach, outlined next.
-
-=== Composition Rules
-
-There are several rules you must follow to successfully convert your AsciiDoc source documents into an EPUB3 publication archive.
-These rules may be loosened in the future, but they are mandatory at the moment.
-
-Rule 1::
-Each chapter must begin in a dedicated file that resides at the root of the project.
-It must be included into the main document using the AsciiDoc include directive.
-The main document, which we call the “spine”, may only contain a document header and a sequence of include directives.
-See <<Declaring the Spine>> for details.
-+
-TIP: The include directive may be used in the chapter files to include other files (even files in other folders).
-
-Rule 2::
-Each chapter must start with a document title (i.e., level-0 heading).
-The document header must declare an ID that matches the chapter filename (minus its file extension).
-
-Rule 3::
-No sections in a chapter may have the same ID as the chapter ID.
-
-Rule 4::
-The cross reference (i.e., xref) from one chapter to another must be in the format `+xref:chapter-id#chapter-id[optional reftext]+` (or `+<<chapter-id#chapter-id,optional reftext>>+`).
-If you want to reference a section in a chapter, update the fragment (i.e., the value that follows the hash) to match the target section ID.
-The reftext is optional since the reftext of the target is used by default.
-+
-TIP: To assign reference text (i.e., reftext) for a chapter title, set the document attribute `docreftext` in the header for that chapter.
-+
-TIP: Rule 2 states that the chapter ID must match the basename of the chapter file.
-In truth, the chapter ID can be a _derivative of_ the chapter filename.
-In that case, an attribute reference can be used to prepend a prefix to an inter-document cross reference.
-For example, if you want each chapter file to begin with `chapter-`, you'd write the xref as `+xref:{chapter-prefix}chapter-id#chapter-id[]+`.
-You'd then assign an empty value to the `chapter-prefix` attribute when converting to an e-book and `chapter-` for all other formats.
-
-The next section goes into more detail about how to set up the spine document and include the chapter files.
-
-=== Declaring the Spine
-
-The spine (or master document) must be well-formed.
-Otherwise, {project-name} will not convert the document properly.
-If your AsciiDoc documents are not structured as explained in this section, you'll need to change them.
-
-Asciidoctor uses top-level include directives (i.e., include directives in the master document) to indicate where each chapter split should occur.
-The chapter files should begin with an AsciiDoc document header, which consists of an ID, a document title (i.e., level-0 heading), an author name, and a set of attribute entries.
-Only the document title is required.
-
-The document title in the chapter file is used as the chapter title and the label for the chapter in the TOC.
-The chapter ID, combined with the _.xhtml_ suffix, is used as the filename of the chapter inside the EPUB3 archive (though this could change in the future).
-We recommend that you base the filename of the chapter on the chapter ID.
-
-If you don't specify an ID for a chapter, one will be generated automatically from the document title.
-The rules for generating a chapter ID from the document title are as follows:
-
-* apply inline formatting, then remove XML elements
-* remove the `\&#8217;` character reference (so `John\&#8217;s` becomes `Johns`)
-* replace `\&amp;` with the word `and` (so `John \&amp; Jane` becomes `John and Jane`)
-* expand all other character references
-* lowercase all characters
-* replace illegal ID characters with the character defined by the `idseparator` attribute
-* prepend the value of the `idprefix` attribute
-* prepend an underscore if the ID begins with a number
-
-You can think of the master document as the spine of the book and the include directives the individual items being bound together.
-The target of each include directive in the master document is parsed and converted as a separate AsciiDoc document, with certain options and attributes passed down from the master to ensure consistent behavior.
-Each resulting XHTML document is then added to the EPUB3 archive as a chapter document and the master document becomes the navigation file (i.e, the table of contents).
-
-Here's an example showing the structure of a spine document:
+Like other converters, Asciidoctor EPUB3 handles this chunking task by automatically slicing up the XHTML output at predetermined heading levels.
 
-[source,asciidoc]
-----
-= Book Title
-Author Name
-:doctype: book
-:imagesdir: images
-\ifndef::ebook-format[:leveloffset: 1]
-//...and so on
+When `doctype` attribute is set to `book`, each top-level section will become a separate ebook "chapter" file.
+This includes preface, bibliography, appendix, etc.
+This behavior can be configured via `epub-chapter-level` document attribute.
 
-\include::chapter-one.adoc[]
-
-\include::chapter-two.adoc[]
+Otherwise, whole document is converted to a single ebook chapter.
 
-\include::chapter-three.adoc[]
-----
+You may specify custom chapter filenames by assigning IDs to sections:
 
-IMPORTANT: The spine document cannot contain any content other than include directives.
+[source,asciidoc]
+-----
+[#custom-chapter-id]
+= Chapter
+-----
 
-Here's an example showing the structure of a chapter document:
+Here's an example showing the structure of a book:
 
 [source,asciidoc]
 ----
-[#chapter-one]
-= Chapter One
+= Book Title
+Author Name
+:doctype: book
+:imagesdir: images
+//...and so on
 
-chapter content
-----
+== Chapter One
 
-CAUTION: Although an explicit ID over the chapter title is not required, it's recommended for stability.
+Some interesting text here.
 
-If your chapter files start with a level-1 section instead of a level-2 section, you need to make the opposite adjustment in the header of the spine document:
+== Chapter Two
 
-[source,asciidoc]
-----
-\ifndef::ebook-format[:leveloffset: -1]
+Even more exciting stuff.
 ----
 
-If the master document does not contain any include directives, then the converter treats the document as the sole chapter in the EPUB3 archive and automatically produces a navigation file that references it.
-(Currently broken. See issue {uri-issues}/47[#47]).
-
-NOTE: Eventually, we envision introducing a dedicated block macro to represent a spine item so that we don't overload the meaning of the include directive.
-However, for the time being, the include directive fills this role.
+In older Asciidoctor EPUB3 versions, there were strict rules on document organization: 'spine' master document with chapter includes.
+This is no longer the case. If you followed old rules, chances are your document will work with newer Asciidoctor EPUB3 either as-is or after minor adjustments.
 
 == Prerequisites
 
-All that's needed to use {project-name} is Ruby 2.3 or newer and a few Ruby gems (including at least Asciidoctor 1.5.3), which we'll explain how to install in the next section.
+All that's needed to use {project-name} is Ruby 2.3 or newer and a few Ruby gems (including at least Asciidoctor 1.5.6), which we'll explain how to install in the next section.
 
 To check if you have Ruby available, use the `ruby` command to query the installed version:
 
@@ -272,26 +198,28 @@ You can install the published gem using the following command:
 This optional environment variable tells the gem installer to link against the C libraries on the system, if available, instead of compiling the libraries from scratch.
 This speeds up the installation of Nokogiri considerably.
 
-If you want to syntax highlight source listings, you'll also want to install CodeRay or Pygments.
+If you want to syntax highlight source listings, you'll also want to install Rouge, CodeRay or Pygments.
 Choose one (or more) of the following:
 
+.Rouge
+ $ gem install rouge
+
 .CodeRay
  $ gem install coderay
 
 .Pygments
  $ gem install pygments.rb
 
-You then activate syntax highlighting for a given document by adding the `source-highlighter` attribute to the document header (CodeRay shown):
+You then activate syntax highlighting for a given document by adding the `source-highlighter` attribute to the document header (Rouge shown):
 
 [source,asciidoc]
 ----
-:source-highlighter: coderay
+:source-highlighter: rouge
 ----
 
-NOTE: At the moment, Pygments is automatically used if it's available.
-If a style is not specified, the black and white theme (i.e., bw) is used.
-This default is used so that the syntax highlighting is legibile regardless of which reading mode the reader selects (white, black, sepia, etc).
-To override this default, you must pass a valid Pygments style name to the `pygments-style` attribute when invoking the `asciidoctor-epub3` script (e.g., `-a pygments-style=pastie`).
+NOTE: If a style is not specified, the black and white theme (i.e., bw) is used.
+This default is used so that the syntax highlighting is legible regardless of which reading mode the reader selects (white, black, sepia, etc).
+To override this default, you must set `<highlighter>-style` document header attribute to a valid highlighter style name (e.g., `:rouge-style: pastie`).
 
 Assuming all the required gems install properly, verify you can run the `asciidoctor-epub3` script:
 
@@ -300,31 +228,6 @@ Assuming all the required gems install properly, verify you can run the `asciido
 If you see the version of {project-name} printed, you're ready to use {project-name}.
 Let's get an AsciiDoc document ready to convert to EPUB3.
 
-=== Prepare an AsciiDoc Document
-
-If you don't already have an AsciiDoc document, you can use the [file]_sample-book.adoc_ file and its chapters found in the [path]_data/samples_ directory of this project.
-
-.Master file named sample-book.adoc
-```asciidoc
-= Asciidoctor EPUB3: Sample Book
-Author Name
-v1.0, 2014-04-15
-:doctype: book
-:creator: {author}
-:producer: Asciidoctor
-:keywords: Asciidoctor, samples, e-book, EPUB3, KF8, MOBI, Asciidoctor.js
-:copyright: CC-BY-SA 3.0
-:imagesdir: images
-
-\include::asciidoctor-epub3-readme.adoc[]
-
-\include::sample-content.adoc[]
-
-\include::asciidoctor-js-introduction.adoc[]
-
-\include::asciidoctor-js-extension.adoc[]
-```
-
 === EPUB-related AsciiDoc Attributes
 
 The metadata in the generated EPUB3 file is populated from attributes in the AsciiDoc document.
@@ -363,7 +266,7 @@ The title is added to the metadata in plain text format.
 The authors in each chapter document are aggregated together with the authors in the master file.
 
 |username
-|Used to resolve an avatar for the author that is displayed in the header of a chapter when the `publication-type` is set to a value other than `book`.
+|Used to resolve an avatar for the author that is displayed in the header of a chapter when the `doctype` is set to a value other than `book`.
 The avatar image should be located at the path _\{imagesdir}/avatars/\{username}.jpg_, where `\{username}` is the value of this attribute.
 
 |producer
@@ -397,17 +300,34 @@ The recommended practice is to identify the referenced resource by means of a st
 |An optional override of the properties attribute for this document's item in the manifest.
 _Only applies to a chapter document._
 
+|epub-chapter-level
+|Specify the section level at which to split the EPUB into separate "chapter" files.
+This attribute only affects documents with `:doctype: book`.
+The default is to split into chapters at level-1 sections.
+This attribute only affects the internal composition of the EPUB, not the way chapters and sections are displayed to users.
+Some readers may be slow if the chapter files are too large, so for large documents with few level-1 headings, one might want to use a chapter level of 2 or 3.
+
+|series-name, series-volume, series-id
+|Populates the series statements (`belongs-to-collection`) in the package metadata.
+Volume is a number, ID probably a UUID that is constant for all volumes in the series.
+
+|epub3-frontmatterdir
+|The path to a directory that contains frontmatter files. The file names must match `front-matter*.html` and will be included in alphabetic order. The files are expected to be valid EPUB HTML files. _If only one front matter page is
+ required, the default 'front-matter.html' file can be used instead._
+
 |epub3-stylesdir
 |The path to a directory that contains alternate epub3.css and epub3-css3-only.css files to customize the look and feel.
 
 |doctype
-|Effectively ignored.
-The master document is assumed to be a book and each chapter an article.
-
-|publication-type
 |Used to control the inclusion of special content in the generated HTML.
 If set to a value other than book, the byline information (author and avatar) is included below the chapter header and a typographic end mark is added at the end of the last paragraph.
-Suggested values include: book (default), anthology, magazine, journal, article.
+Suggested values include: book (default), article.
+
+|toc
+|Adds table of contents at the beginning of the book. Depth is controlled by `:toclevels:` attribute.
+
+|outlinelevels
+|Sets the depth of table of contents metadata. If not set, defaults to `:toclevels:`
 |===
 
 When using the EPUB3 converter, the `ebook-format` attribute resolves to the name of the e-book format being generated (epub3 or kf8) and the corresponding attribute `ebook-format-<name>` is defined, where `<name>` is `epub3` or `kf8`.
@@ -581,9 +501,10 @@ Here's a sample manifest of files found in an EPUB3 document produced by {projec
 ....
 META-INF/
   container.xml
-OEBPS/
+EPUB/
   fonts/
-    font-awesome.ttf
+    awesome/
+      fa-solid-900.ttf
     font-icons.ttf
     mplus-1mn-latin-bold.ttf
     mplus-1mn-latin-light.ttf
@@ -618,17 +539,14 @@ mimetype
 
 Images referenced in your AsciiDoc document must be stored in the images catalog.
 The images catalog is defined by the `imagesdir` attribute.
-If set, the value of this attribute is resolved relative to the spine document and must be at or below (i.e., within) the directory of that document.
+If set, the value of this attribute is resolved relative to the document and must be at or below (i.e., within) the directory of that document.
 (In other words, it cannot point to a location outside the document directory).
-If this attribute is not set, the images catalog defaults to the directory of the spine document.
+If this attribute is not set, the images catalog defaults to the directory of the document.
 {project-name} will discover all local image references and insert those images into the EPUB3 archive at the same relative path.
 
-WARNING: {project-name} does not currently discover and package inline images.
-See issue {uri-issues}/30[#30].
-
 === Default Images
 
-The sample book contains placeholder images for an author avatar and a book cover.
+The sample book contains placeholder image for an author avatar.
 
 // TODO explain the avatar and book cover images
 
@@ -648,7 +566,7 @@ Once your image is ready, you can set the cover image by defining the `front-cov
 :front-cover-image: image:cover.png[Front Cover,1050,1600]
 ----
 
-The image is resolved relative to the directory specified in the `imagesdir` attribute, which defaults to the directory of the spine document.
+The image is resolved relative to the directory specified in the `imagesdir` attribute, which defaults to the directory of the3 document.
 The image can be in any format, though we recommend using PNG, JPG, or SVG as they are the most portable formats.
 
 IMPORTANT: *You should always specify the dimensions of the cover image.*
@@ -691,7 +609,7 @@ The theme's fonts are located in the [path]_data/fonts_ directory.
 The M+ Outline fonts are used for titles, headings, literal (monospace) text, and annotation numbers.
 The body text uses Noto Serif.
 Admonition icons and the end-of-chapter mark are from the Font Awesome icon font.
-Refer to the <<NOTICE#,NOTICE>> file for further information about the fonts.
+Refer to the link:NOTICE.adoc[] file for further information about the fonts.
 
 // TODO document command to generate the M+ 1p latin fonts
 
@@ -986,8 +904,8 @@ endif::[]
 Copyright (C) 2014-2019 OpenDevise Inc. and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.
 
-For the full text of the license, see the <<LICENSE#,LICENSE>> file.
-Refer to the <<NOTICE#,NOTICE>> file for information about third-party Open Source software in use.
+For the full text of the license, see the link:LICENSE[] file.
+Refer to the link:NOTICE.adoc[] file for information about third-party Open Source software in use.
 
 ////
 == Additional Points of Note