asciidoctor-pdf 1.5.0.alpha.16 → 1.5.0.alpha.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f8bc83ea1a53067222edc4efed9a4e23d7b98824
-  data.tar.gz: 55b679cc587279f0491af7aec91878c6acca01c9
+SHA256:
+  metadata.gz: fcb6c79a944028551c1ec56650df511a0f4be9984d379de22c891031ce743fe2
+  data.tar.gz: d75bce156557910b7aa82c703b97fd266a5035cd4b37707756ca2f3e29359363
 SHA512:
-  metadata.gz: 632d25962bc66acf9b8b015a1e76b85e69a4f7a7b516cc9ea24c411e4b4db6e5280f23145c9beae321cfcd7b835821e86f0d81f6b4fa1731847eb6fa27e90bf7
-  data.tar.gz: 477e19845f08bba51aee292c662e2ec6cad47d814ba683959ec23c7eaf0615e7c32a6b1ebe4b565f036d47bc88b02971f7e83c6cfcb2083c26ef148ffe838ffc
+  metadata.gz: be77878203c03b479682a80f50baf8278599b6c9d5d24e3dba46e2ad798f26641f223a6b620cff240d6e893eed4d12804b0693f5dbbd926b79e65c40c704e4cc
+  data.tar.gz: 2c3d80e93665b076bda8c1c6b4d6dd59225eb6437d9ad679ebed6995ad1523cadf215a0d6dbe3bab461a089ecf1433bab259cc8bdab519737029659acc175355

data/.yardopts

@@ -0,0 +1,12 @@
+--charset UTF-8
+--readme README.adoc
+--no-private
+--hide-api private
+--title "Asciidoctor PDF API Docs"
+--output-dir apidoc
+--exclude /(?:asciidoctor_ext|core_ext)(?:\.rb$|/)
+lib/**/*.rb
+-
+CHANGELOG.adoc
+LICENSE.adoc
+NOTICE.adoc

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.17 (2019-04-23) - @mojavelinux
+
+* drop support for Ruby < 2.3 (and installation will fail for Ruby < 2.1)
+* add asciidoctor/pdf and asciidoctor/pdf/version require aliases (#262)
+* rename module to Asciidoctor::PDF and define Asciidoctor::Pdf alias for backwards compatibility (#262)
+* switch to tilde dependency versions (flexible patch number) instead of ranges
+* upgrade prawn-svg to 0.29.1; resolves numerous SVG rendering issues (#886, #430)
+* drop support for Rouge < 2
+* add a test suite (#37)
+* allow running content (header and footer) to be enabled on title and toc pages; controlled by running_content_start_at property in theme (#606)
+* add support for nbsp named entity (i.e., `+&nbsp;`); replace occurances of nbsp named entity with a single space in outline
+* upgrade to FontAwesome 5; introduce the fas, far, and fab icon sets, now preferred over fa; drop support for octicons (#891) (@jessedoyle)
+* place footnotes at end of chapters in books or end of document otherwise (#85) (@bcourtine)
+* place toc directly after document title when doctype is not book (#233) (@ogmios-voice)
+* add page layout control to page break (#490) (@resort-diaper)
+* allow additional style properties to be set per heading level (#176) (@billybooth)
+* add support for hexadecimal character references, including in link href (#486)
+* force set data-uri attribute on document so Asciidoctor Diagram returns absolute image paths (#1033)
+* set line spacing for non-AsciiDoc table cells (#296)
+* consider all scripts when looking for leading alpha characters in index (#853)
+* don't create title page for article doctype unless title-page attribute is set (#105)
+* don't show article title if notitle attribute is set (#998)
+* generate name section for manpage doctype automatically (#882)
+* remove unprocessed passthroughs in literal cells
+* apply font style from theme to formatted text description list term (#854)
+* prevent tempfile for remote image from being deleted before it's used (#947)
+* handle case when uri to make breakable is empty (#936)
+* add support for frame=ends as alternative to frame=topbot on table
+* allow table frame and grid to be set globally using the table-frame and table-grid attributes (#822)
+* disable table stripes by default
+* allow table stripes to be enabled globally using table-stripes attribute
+* use new logging subsystem, if available; otherwise, use shim (#905)
+* allow alignment of list text to be controlled using roles (#182)
+* allow text alignment to be set for abstract (#893)
+* prevent text from overlapping page number in TOC (#839)
+* allow ulist marker to be controlled by theme (#798)
+* add support for reftext for bibliography entry (#864)
+* add support for fw (full-width) icons (#890)
+* decouple vw units with alignment (#948)
+* add align-to-page option for block images (#948)
+* add support for SVG admonition icons (#828) (@keith-packard)
+* rename pastie theme for Rouge to asciidoctor_pdf_default
+* add bw theme for Rouge (#1018)
+* reset top margin of index columns when overflowing to new page (#929)
+* add support for line numbers in source listings (#224)
+* add U+2060 (word joiner) character to built-in Noto Serif font and fallback font (#877)
+* add U+202F (narrow no-break space) character to fallback font (#807)
+* ensure callout number ends up on same page as item text (#914)
+* guard against pygments returning nil (#884)
+* encode quotes in alt text of inline image (#977)
+* fix crash when menu macro is used in a section or block title (#934)
+* only look for the start attribute on the code block itself when highlighting with rouge
+* apply block styling to background for line-oriented tokens in rouge by default
+* detect pagenum ranges in index when media is print or prepress (#906)
+* ignore style when resolving icon font (#956, #874)
+* remove correct width method when overloading Prawn::Text::Formatted::Fragment
+* remove ZWSP from alt text of image to prevent fragment from being duplicated (#958)
+* avoid call to super in prepended module to fix Ruby 1.9.3
+* look for correct file to require in bin script
+* upgrade prawn-icon from 1.3.0 to 1.4.0
+* upgrade rouge to 2.2.1 
+* add concurrent-ruby to runtime dependencies for compatiblity w/ Asciidoctor 1.5.8
+
 == 1.5.0.alpha.16 (2017-07-30) - @mojavelinux
 
 * add support for xrefstyle attribute (#464)
@@ -117,6 +180,8 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * map dynamic section-title attribute in running content to current section if page has no section (#709)
 * assign dynamic part-title attribute for use in running content (#596)
 * don't set dynamic chapter-title attribute in running content for preface unless doctype is book
+* clear section and chapter title in running content when part changes (#910, #879)
+* clear section title in running content when chapter changes (#910)
 * assign page number label to each page (#641)
 * don't set dynamic page-number attribute in running content of pagenums is disabled
 * allow toc title properties to be controlled by theme (#701)
@@ -130,6 +195,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * don't crash if image in running content fails to embed (#728)
 * treat abstract section as abstract block (#703)
 * set example block background to white by default
+* automatically wire unspecified code and conum font family to literal font family
 * add support for background colors when highlighting code with Rouge
 * add support underline style for token in Rouge theme (#665)
 * drop background colors on strings in rouge pastie theme

data/LICENSE.adoc

@@ -1,6 +1,6 @@
 .The MIT License
 ....
-Copyright (C) 2014-2016 OpenDevise Inc. and the Asciidoctor Project
+Copyright (C) 2014-2019 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

data/README.adoc

@@ -1,6 +1,6 @@
 = Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
-v1.5.0.alpha.16, 2017-07-30
+v1.5.0.alpha.17, 2019-04-23
 // Settings:
 :experimental:
 :idprefix:
@@ -23,6 +23,8 @@ endif::[]
 // Aliases:
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
+// Variables:
+:release-version: 1.5.0.alpha.17
 // URIs:
 :uri-asciidoctor: http://asciidoctor.org
 :uri-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -30,7 +32,7 @@ endif::[]
 :uri-project-repo: {uri-project}
 :uri-project-issues: {uri-project-repo}/issues
 :uri-project-list: http://discuss.asciidoctor.org
-:uri-prawn: http://prawn.majesticseacreature.com
+:uri-prawn: http://prawnpdf.org
 :uri-prawn-gmagick: https://github.com/packetmonkey/prawn-gmagick
 :uri-prawn-svg: https://github.com/mogest/prawn-svg
 :uri-asciidoctor-mathematical: https://github.com/asciidoctor/asciidoctor-mathematical
@@ -38,10 +40,18 @@ endif::[]
 :uri-graphicsmagick: http://www.graphicsmagick.org
 
 ifdef::status[]
+image:https://img.shields.io/travis/asciidoctor/asciidoctor-pdf/master.svg[Build Status (Travis CI),link=https://travis-ci.org/asciidoctor/asciidoctor-pdf]
 image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={uri-gem}]
 image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright]
 endif::[]
 
+ifdef::env-site[]
+Asciidoctor PDF is a native PDF converter for AsciiDoc.
+It bypasses the requirement to generate an interim format such as DocBook, Apache FO, or LaTeX.
+Instead, you can use it to convert directly from AsciiDoc to PDF.
+Its aim is to take the pain out of creating PDF documents from AsciiDoc.
+endif::[]
+ifndef::env-site[]
 _Lo and behold_, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! +
 _No more middleman._ +
 _No more DocBook toolchain._ +
@@ -84,10 +94,9 @@ Skip ahead to <<getting-started,Getting started>> to start putting it use.
 Prawn is the _killer library_ for PDF generation we've needed to close this critical gap in Asciidoctor.
 It absolutely takes the pain out of creating printable documents.
 Picking up from there, {project-name} takes the pain out of creating PDF documents _from AsciiDoc_.
+endif::[]
 
-== Features
-
-=== Notable Features
+== Highlights
 
 * Direct AsciiDoc to PDF conversion
 * <<docs/theming-guide#,Configuration-driven style and layout>>
@@ -107,44 +116,16 @@ Picking up from there, {project-name} takes the pain out of creating PDF documen
 * Custom (TTF) fonts
 * Double-sided printing mode (margins alternate on recto and verso pages)
 
-=== Missing Features
-
-See <<WORKLOG#,WORKLOG>>.
-
 == Prerequisites
 
-All that's needed is Ruby (1.9.3 or above; 2.3.x recommended) and a few Ruby gems, which we explain how to install in the next section.
+All that's needed is Ruby 2.3 or better and a few Ruby gems, which we explain how to install in the next section.
 
 To check if you have Ruby available, use the `ruby` command to query the version installed:
 
  $ ruby --version
 
-[WARNING]
-====
-By default, Asciidoctor PDF automatically installs the latest version of Prawn if you don't already have Prawn installed.
-This will fail on older versions of Ruby.
-To workaround, you need to install certain dependencies first.
-
-Starting with Prawn 2.0.0, Prawn requires Ruby >= 2.0.0 during installation.
-Therefore, to use Asciidoctor PDF with Ruby 1.9.3, you must first explicitly install the following dependencies to lock the versions:
-
- $ gem install prawn --version 1.3.0
-   gem install addressable --version 2.4.0
-   gem install prawn-svg --version 0.21.0
-   gem install prawn-templates --version 0.0.3
-
-You can then proceed with installation of Asciidoctor PDF on Ruby 1.9.3.
-
-Starting with Prawn 2.2.0, Prawn requires Ruby >= 2.1.0 during installation.
-Therefore, to use Asciidoctor PDF with Ruby 2.0.0, you must first explicitly install the following dependencies to lock the versions:
-
- $ gem install prawn --version 2.1.0
-   gem install prawn-svg --version 0.26.0
-   gem install prawn-templates --version 0.0.4
-
-For all other versions of Ruby, you can simply install the Asciidoctor PDF gem.
-It will transitively install the required dependencies.
-====
+Make sure this command reports a Ruby version that's at least 2.3.
+If so, you may proceed.
 
 === System Encoding
 
@@ -161,7 +142,8 @@ Once you make this change, all your Unicode headaches will be behind you.
 
 == Getting Started
 
-You can get {project-name} by <<install-the-published-gem,installing the published gem>> or <<development,running the code from source>>.
+You can get {project-name} by <<install-the-published-gem,installing the published gem>>.
+ifndef::env-site[You can also <<development,run the code from source>> if you want to use a development version or participate in development.]
 
 === Install the Published Gem
 
@@ -170,11 +152,11 @@ First, make sure you have satisfied the <<Prerequisites,prerequisites>>.
 Then, you can install the published gem using the following command:
 
  $ gem install asciidoctor-pdf --pre
- 
+
 If you want to syntax highlight source listings, you'll also want to install Rouge, Pygments, or CodeRay.
 Choose one (or more) of the following:
 
-.Rouge (preferred)
+.Rouge (preferred, minimum version: 2.0.0)
  $ gem install rouge
 
 .Pygments
@@ -187,20 +169,22 @@ You then activate syntax highlighting for a given document by adding the `source
 
 [source,asciidoc]
 ----
-:source-highlighter: rouge 
+:source-highlighter: rouge
 ----
 
+=== Run the Application
+
 Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:
 
  $ asciidoctor-pdf -v
 
-If you see the version of {project-name} printed, you're ready to use {project-name}.
+If you see the version of {project-name} printed, you're ready to use {project-name}!
 
-Let's grab an AsciiDoc document to distill and start putting {project-name} to use!
+Let's grab an AsciiDoc document to distill and start putting {project-name} to use.
 
 === An Example AsciiDoc Document
 
-If you don't already have an AsciiDoc document, you can use the [file]_basic-example.adoc_ file found in the examples directory of this project.
+If you don't already have an AsciiDoc document, you can use the <<examples/basic-example#,basic-example.adoc>> file found in the examples directory of this project.
 
 ifeval::[{safe-mode-level} >= 20]
 See <<examples/basic-example#,basic-example.adoc>>.
@@ -230,13 +214,15 @@ This command is just a shorthand way of running:
 The `asciidoctor-pdf` command just saves you from having to remember all those flags.
 That's why we created it.
 
-When the script completes, you should see the file [file]_basic-example.pdf_ in the same directory.
-Open the [file]_basic-example.pdf_ file with a PDF viewer to see the result.
+When the script completes, you should see the file [.path]_basic-example.pdf_ in the same directory.
+Open the [.path]_basic-example.pdf_ file with a PDF viewer to see the result.
 
 .Example PDF document rendered in a PDF viewer
-image::examples/example-pdf-screenshot.png[Screenshot of PDF document,width=800,scaledwidth=100%]
+image::examples/example-pdf-screenshot.png[Screenshot of PDF document,width=850,467,scaledwidth=100%]
 
+ifndef::env-site[]
 You're also encouraged to try converting this <<README#,README>> as well as the documents in the examples directory to see more of what {project-name} can do.
+endif::[]
 
 The pain of the DocBook toolchain should be melting away about now.
 
@@ -244,12 +230,20 @@ The pain of the DocBook toolchain should be melting away about now.
 
 The layout and styling of the PDF is driven by a YAML configuration file.
 To learn how the theming system works and how to create and apply custom themes, refer to the <<docs/theming-guide#,Asciidoctor PDF Theme Guide>>.
-You can use the built-in theme files, which you can find in the [file]_data/themes_ directory, as examples.
+You can use the built-in theme files, which you can find in the [.path]_data/themes_ directory, as examples.
+
+If you've enabled a source highlighter, you can control the style (aka theme) it applies to source blocks using the `coderay-style`, `pygments-style`, and `rouge-style` attributes, respectively.
+For example, to configure Rouge to use the built-in monokai theme, run Asciidoctor PDF as follows:
+
+ $ asciidoctor-pdf -a rouge-style=monokai basic-example.adoc
+
+It's possible to develop your own theme for Rouge.
+Refer to the <<docs/theming-guide#,Asciidoctor PDF Theme Guide>> for details.
 
 === Support for Non-Latin Languages
 
 Asciidoctor can process the full range of characters in the UTF-8 character set.
-That means you can write your document in any language, save the file with UTF-8 encoding, and expect Asciidoctor to convert the text properly. 
+That means you can write your document in any language, save the file with UTF-8 encoding, and expect Asciidoctor to convert the text properly.
 However, you may notice that certain characters for certain languages, such as Chinese, are missing in the PDF.
 Read on to find out why and how to address it.
 
@@ -260,22 +254,27 @@ See the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoct
 
 Using a dedicated theme is necessary because PDF is a "`bring your own font`" kind of system.
 In other words, the font you provide must provide glyphs for all the characters.
-There's no one font that supports all the worlds languages (though some, like Noto Serif, certainly come close). 
+There's no one font that supports all the worlds languages (though some, like Noto Serif, certainly come close).
 Even if there were such a font, bundling that font with the main gem would make the package enormous.
 It would also severely limit the style choices in the default theme, which targets Latin-based languages.
 
 Therefore, we're taking the strategy of creating separate dedicated theme gems that target each language family, such as CJK.
-The base theme for CJK languages is provided by the https://github.com/chloerei/asciidoctor-pdf-cjk[asciidoctro-pdf-cjk] project and a concrete implementation provided by the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project that's based on the kai_gen_gothic font.
+The base theme for CJK languages is provided by the https://github.com/chloerei/asciidoctor-pdf-cjk[asciidoctor-pdf-cjk] project and a concrete implementation provided by the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project that's based on the kai_gen_gothic font.
 Of course, you're free to follow this model and create your own theme gem that uses fonts of your choice.
 
 == Font-Based Icons
 
 You can use icons in your PDF document using any of the following icon sets:
 
-* *fa* - https://fortawesome.github.io/Font-Awesome/[Font Awesome^] (default)
-* *octicon* - https://octicons.github.com/[Octicons^]
+* *fa* - https://fontawesome.com/v4.7.0/icons (default)
+* *fas* - https://fontawesome.com/icons?d=gallery&s=solid[Font Awesome - Solid^]
+* *fab* - https://fontawesome.com/icons?d=gallery&s=brands[Font Awesome - Brands^]
+* *far* - https://fontawesome.com/icons?d=gallery&s=regular[Font Awesome - Regular^]
 * *fi* - http://zurb.com/playground/foundation-icon-fonts-3[Foundation Icons^]
-* *pf* - http://paymentfont.io/[Payment font^]
+* *pf* - https://paymentfont.com/[Payment font^]
+
+The fa icon set is deprecated.
+Please use one of the other three FontAwesome icon sets.
 
 You can enable font-based icons by setting the following attribute in the header of your document:
 
@@ -292,7 +291,7 @@ If you want to override the font set globally, also set the `icon-set` attribute
 :icon-set: pf
 ----
 
-Here's an example that shows how to use the Amazon icon from the payment font (pf) icon set in a sentence:
+Here's an example that shows how to use the Amazon icon from the payment font (pf) icon set in a sentence (assuming the `icon-set` is set to `pf):
 
 [source,asciidoc]
 ----
@@ -306,6 +305,13 @@ You can use the `set` attribute on the icon macro to override the icon set for a
 Available now at icon:amazon[set=pf].
 ----
 
+You can also specify the font set using the following shorthand.
+
+[source,asciidoc]
+----
+Available now at icon:amazon@pf[].
+----
+
 In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc).
 
 [source,asciidoc]
@@ -315,21 +321,37 @@ icon:android[size=40em]
 
 You can enable use of fonts during PDF generation (instead of in the document header) by passing the `icons` attribute to the `asciidoctor-pdf` command.
 
- $ asciidoctor-pdf -a icons=font -a icon-set=octicon sample.adoc
+ $ asciidoctor-pdf -a icons=font -a icon-set=pf sample.adoc
 
 Icon-based fonts are handled by the `prawn-icon` gem.
 To find a complete list of available icons, consult the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon] repository.
 
 == Image Paths
 
-Images are resolved relative to the value of the `imagesdir` attribute at the time the converter is run.
+Relative images paths are resolved relative to the value of the `imagesdir` attribute at the time the converter is run.
 This is effectively the same as how the built-in HTML converter works when the `data-uri` attribute is set.
-The `imagesdir` is blank by default, which means images are resolved relative to the input document.
+The `imagesdir` is blank by default, which means relative images paths are resolved relative to the input document.
+Absolute image paths are used as is.
 
 If the image is an SVG, and the SVG includes a nested raster image (PNG or JPG) with a relative path, that path is resolved relative to the directory that contains the SVG.
 
 The converter will refuse to include an image if the target is a URI unless the `allow-uri-read` attribute is enabled via the CLI or API.
 
+If the image is an SVG and that SVG links to another image, the linked image will be resolved using the same rules as the original image.
+However, note that a width and height must be specified on the linked image or else the SVG library will fail to process it.
+
+=== Asciidoctor Diagram Integration
+
+As of Asciidoctor PDF 1.5.0.alpha.17 running on Asciidoctor 2 or better, Asciidoctor PDF provides better integration with Asciidoctor Diagram by setting the `data-uri` attribute by default.
+When the `data-uri` attribute is set, Asciidoctor Diagram returns the absolute path to the generated image, which Asciidoctor PDF can then locate.
+(This makes sense since technically, Asciidoctor Diagram must embed the image in the document, similar in spirit to the `data-uri` feature for HTML).
+This means the input directory and the output directory (and thus the imagesoutdir) can differ and Asciidoctor PDF will still be able to locate the generate image.
+
+Prior to Asciidoctor PDF 1.5.0.alpha.17 (or prior to Asciidoctor 2), the way to solve this problem is to set the `imagesdir` attribute to an absolute path.
+That way, it won't matter where the generated image is written.
+Asciidoctor PDF will still be able to find it.
+Keep in mind that this strategy may introduce other side effects you'll have to work around.
+
 == Image Scaling
 
 Since PDF is a fixed-width canvas, you almost always need to specify a width to get the image to fit properly on the page.
@@ -366,6 +388,9 @@ The image is always sized according to the explicit or intrinsic width and its h
 The height of the image is ignored by the PDF converter unless the height of the image exceeds the content height of the page.
 In this case, the image is scaled down to fit on a single page.
 
+If you want a block image to align to the boundaries of the page (not the content margin), specify the `align-to-page` option (e.g., `opts="align-to-page"`).
+This is most useful when using vw units because you can make the image cover the entire width of the page.
+
 Images in running content also support the `fit` attribute.
 If the value of this attribute is `contain`, the image size is increased or decreased to fill the available space while preserving its aspect ratio.
 If the value of this attribute is `scaled-down`, the image size is first resolved in the normal way, then scaled down further to fit within the available space, if necessary.
@@ -513,9 +538,6 @@ require 'asciidoctor-mathematical'
 Asciidoctor.convert_file 'sample.adoc', safe: :safe
 ----
 
-CAUTION: Asciidoctor Mathematical does not currently process STEM blocks and inline macros inside AsciiDoc table cells or STEM inline macros in normal table cells.
-You can track the progress of these improvements by following {uri-asciidoctor-mathematical}/issues/20[issue #20] and {uri-asciidoctor-mathematical}/issues/19[issue #19], respectively.
-
 To get the best quality equations, and the maximize speed of conversion, we recommend configuring Asciidoctor Mathematical to convert equations to SVG.
 You control this setting using the `mathematical-format` AsciiDoc attribute:
 
@@ -523,6 +545,41 @@ You control this setting using the `mathematical-format` AsciiDoc attribute:
 
 Refer to the {uri-asciidoctor-mathematical}#readme[README] for Asciidoctor Mathematical to learn about additional settings and options.
 
+== Skipping Passthrough Content
+
+Asciidoctor PDF does not support arbitrary passthrough content.
+While the basebackend for the PDF converter is html, it only recognizes a limited subset of inline HTML elements that can be mapped to PDF (e.g., a, strong, em, code, ).
+Therefore, if your content contains passthrough blocks or inlines, you most likely have to use a conditional preprocessor to skip them (and make other arrangements).
+
+Here's an example of how to skip a passthrough block when converting to PDF:
+
+[source,asciidoc]
+----
+\ifndef::backend-pdf[]
+<script>
+//...
+</script>
+\endif::[]
+----
+
+Here's an example of how to only enable a passthrough block when convertering to HTML5:
+
+[source,asciidoc]
+----
+\ifdef::backend-html5[]
+<script>
+//...
+</script>
+\endif::[]
+----
+
+== Shaded Blocks and Performance
+
+Certain blocks are rendered with a shaded background, such as verbatim (listing, literal, and source), sidebar, and example blocks.
+In order to calculate the dimensions of the shaded region, Asciidoctor PDF has to "`dry run`" the block to determine how many pages it consumes.
+While this strategy has a low impact when processing shorter blocks, it can drastically deteriorate performance when processing a block that spans dozens of pages.
+As a general rule of thumb, you should avoid using shaded blocks which span more than a handful of pages.
+
 == Autofitting Text
 
 Verbatim blocks often have long lines that don't fit within the fixed width of the PDF canvas.
@@ -569,6 +626,40 @@ Therefore, to print a range of pages as they are labeled in the document, you ne
 For example, if you only want to print the first 5 pages labeled with a page number (e.g., 1-5), and there are 2 pages before the page labeled as page 1, you need to add 2 to both numbers in the range, giving you a physical page range of 3-7.
 That's the range you need to enter into the print dialog.
 
+== Table of Contents
+
+The table of contents (TOC) is not included by default.
+The TOC is only included if the `toc` attribute is set on the document.
+
+The placement of the table of contents is fixed, and thus the value of the `toc` attribute is effectively ignored in this backend.
+For documents that have the book doctype, the TOC is inserted using discrete pages between the title page and the first page of content.
+For all other doctypes (unless the `title-page` attribute is set), the TOC is inserted in the flow of text in between the document title and the first block of content.
+
+While the table of contents is not included by default, the PDF outline is always included.
+The `toclevels` attribute controls the depth of both the TOC and the PDF outline (regardless of whether the TOC is enabled).
+
+NOTE: If a document that has the book doctype includes a preface, an entry for the preface is only included in the TOC if the `preface-title` is assigned a value (e.g., `preface-title=Preface`).
+This value is used as the heading of the preface and as the text of the entry in the TOC.
+
+== Index Catalog
+
+Asciidoctor PDF supports generating an index catalog that itemizes all index terms defined in the document, allowing the reader to navigate the document by keyword.
+
+To get Asciidoctor PDF to generate an index, simply add an level-1 section flagged with the `index` style near the end of your document.
+The converter will automatically populate the catalog with the list of index terms in the document, organized by first letter.
+
+[source,asciidoc]
+----
+[index]
+= Index
+----
+
+You can use any text you want for the title of the section.
+The only restriction is that no index terms may be defined below this section.
+
+NOTE: Although the catalog is generated automatically, you have to mark the index terms manually.
+However, you could use an extension, such as a TreeProcessor, to automatically mark index terms.
+
 == Optional Scripts
 
 {project-name} also provides a shell script that invokes GhostScript (`gs`) to optimize and compress the generated PDF with minimal impact on quality.
@@ -578,7 +669,7 @@ Here's an example usage:
 
  $ ./bin/optimize-pdf basic-example.pdf
 
-The command will generate the file [file]_example-optimized.pdf_ in the current directory.
+The command will generate the file [.path]_example-optimized.pdf_ in the current directory.
 
 WARNING: The `optimize-pdf` script currently requires a Bash shell (Linux, OSX, etc).
 We plan to rewrite the script in Ruby so it works across platforms (see https://github.com/asciidoctor/asciidoctor-pdf/issues/1[issue #1])
@@ -591,11 +682,14 @@ If a file is found with the extension `.pdfmark` and the same rootname as the in
 This file is necessary to preserve the document metadata since Ghostscript will otherwise drop it.
 That's why {project-name} always creates this file in addition to the PDF.
 
+ifndef::env-site[]
 == Contributing
 
 In the spirit of free software, _everyone_ is encouraged to help improve this project.
 
 To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
+*All pull requests must include a) tests that verify the code change and b) an entry in the CHANGELOG.adoc file to document what changed.*
+If a pull request is missing tests or a CHANGELOG entry, *it will not be merged*.
 
 Feel free to use the {uri-project-issues}[issue tracker] or {uri-project-list}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.
 
@@ -634,11 +728,11 @@ We'll leverage the project configuration to install the necessary dependencies.
 
 If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:
 
- $ rvm use 2.3@asciidoctor-pdf --create
+ $ rvm use 2.5@asciidoctor-pdf --create
 
 We like RVM because it keeps the dependencies required by various projects isolated.
 
-The dependencies needed to use {project-name} are defined in the [file]_Gemfile_ at the root of the project.
+The dependencies needed to use {project-name} are defined in the [.path]_Gemfile_ at the root of the project.
 We can use Bundler to install the dependencies for us.
 
 To check you have Bundler available, use the `bundle` command to query the installed version:
@@ -653,16 +747,75 @@ Then use the `bundle` command to install the project dependencies:
 
  $ bundle
 
-NOTE: You need to call `bundle` from the project directory so that it can find the [file]_Gemfile_.
+NOTE: You need to call `bundle` from the project directory so that it can find the [.path]_Gemfile_.
+
+=== Run the Tests
+
+Tests are written using RSpec.
+To run the tests, simply invoke rspec via bundler.
+
+ $ bundle exec rspec
+
+If you want to see the name of each test that is run, add the `-fd` option:
+
+ $ bundle exec rspec -fd
+
+You can also use the provided Rake task (note the name difference):
+
+ $ bundle exec rake spec
+
+Running tests using `rspec` directly gives you the advantage of being able to specify additional options.
 
+To run a single test, you can filter by the name of the test.
+For example, to run all tests that pertain to failures, use:
+
+ $ bundle exec rspec -e fail -fd
+
+You can also run all tests in a given file by passing the file's path to rspec:
+
+ $ bundle exec rspec -fd spec/toc_spec.rb
+
+For a full list of options that rspec provides, run `rspec -h`.
+
+=== Run the Application (optional)
+
+Like with Bundler, you have to run the application from the project directory.
 Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:
 
- $ bundle exec ./bin/asciidoctor-pdf -v
+ $ bundle exec asciidoctor-pdf -v
 
 If you see the version of {project-name} printed, you're ready to use {project-name}!
 
-CAUTION: If you get an error message--and you're not using a Ruby manager like RVM--you may need to invoke the script through `bundle exec`:
-For best results, be sure to always use `bundle exec` whenever invoking the `./bin/asciidoctor-pdf` script in development mode.
+You can use the application to convert a document as follows:
+
+ $ bundle exec asciidoctor-pdf /path/to/sample.adoc
+
+endif::[]
+
+=== Test a Pull Request
+
+To test a pull request (PR), you first need to fetch the branch that contains the change and switch to it.
+The steps below are covered in detail in the https://help.github.com/articles/checking-out-pull-requests-locally[GitHub help].
+
+Let's assume you want to test PR 955.
+Here's how you fetch and switch to it:
+
+ $ git fetch origin pull/955/head:pr-955-review
+   git checkout pr-955-review
+
+IMPORTANT: Make sure you replace the number with the number of the PR you want to test.
+
+In case any dependencies have changed, you should run the `bundle` command again:
+
+ $ bundle
+
+Now you can run the application as modified by the PR:
+
+ $ bundle exec asciidoctor-pdf /path/to/sample.adoc
+
+To switch back to master, just type:
+
+ $ git checkout master
 
 [[resources,Links]]
 == Resources
@@ -675,7 +828,7 @@ For best results, be sure to always use `bundle exec` whenever invoking the `./b
 
 == Copyright
 
-Copyright (C) 2014-2017 OpenDevise Inc. and the Asciidoctor Project.
+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.