asciidoctor-pdf 1.5.0.alpha.13 → 1.5.0.alpha.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed86baf3f76110d88dcb2e25c13f99a22fdaa42c
-  data.tar.gz: bc58645703cf1a7682d6032765c193c077ca49ec
+  metadata.gz: 94832dc67ed7ce7dfc52ecd5245bcd47d1a13ad7
+  data.tar.gz: fe2c218069cc009756e83c8e8aacaa3d15b48a88
 SHA512:
-  metadata.gz: 9fad7aff67713993469f08ff73ee9ff8a81d29c0182d4c38c93830561b9c3e149fe159b9b4ef9fe71a3e4faa831d795251d1691cbddc803e2b2a2cc34030a561
-  data.tar.gz: 3c07404a84deb2aac522cac10d0ab56ecd174e3349aec168105ecc79e9f5232c6586204617d230f45ea206b6c3936912b3e28c448c3c7f515fecd40fcff93c5b
+  metadata.gz: 881736c11065cddaf7cbef76d587016267605b6acb9c09a7f694f6a0c347e4aeec09e2ba151dd3528dbcd9198e8f4322c15956e7fa61c6e9c675756ec386aaa9
+  data.tar.gz: f37f79944645d1139fbd347761d028f80595f3f0a827b8cd9b65d8ef177929336882f93f1f2ea66a15a79a4ad3998117f9d9c0f8c4f8f3ecb5e5220e62cd03ff

data/CHANGELOG.adoc

@@ -5,12 +5,134 @@
 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.14 (2017-02-05) - @mojavelinux
+
+* add support for AsciiDoc table cells (including nested tables) (#6)
+* patch text cell to remove cursor advancement
+* make header cell in body inherit styles from table head (#239)
+* don't crash if table is empty and cols are explicitly set (#610)
+* fix vertical centering for cells in table head row
+* implement converter for index (PR #386)
+* record page number for index term when writing anchor (#639)
+* support the underline and line-through roles on phrases (#339)
+* allow printed URI to break at break opportunities (#563)
+* don't drop subsequent images after inline image fails to load
+* show alt text when image fails to embed (#693)
+* don't crash if inline image is an unsupported format; issue warning instead (#587)
+* always show image caption even if image fails to embed
+* delegate to method to handle missing image
+* permit use of gif image format if prawn-gmagick is available (#573)
+* add support for image macros that have a data URI target (#318)
+* don't crash if format of image in running content is unrecognized
+* only fit image within bounds of running content if contain option is set
+* document fit attribute for image in running content
+* fix alignment for SVG image in running content
+* keep block image with caption (#690)
+* place destination for block image on same page as image
+* set color space when block image occurs on page by itself (#688)
+* resize SVG to fit page (#691)
+* backport resize method from prawn-svg and use it
+* disable system font scan in Prawn SVG
+* use character spacing to fine-tune width of placeholder for inline image (#686)
+* fix duplicate inline image rendering (@fap-) (#388)
+* constrain inline image to width of bounds
+* add support for pdfwidth to inline images (@fap-) (#620)
+* honor pdfwidth attribute for image in running content (#625)
+* add support for absolute measurement units to scaledwidth attribute (#674)
+* resize inline SVG without an explicit width (#684)
+* resize inline image to fit within content height (#700)
+* calculate height of inline image correctly in table cell (#295)
+* fix bug in calculation when image overflows page (#708)
+* simplify calculation of rendered width and height of images
+* add square brackets around alt text for inline image
+* don't surround alt text of block image with non-breaking spaces
+* specify width & height when embedding (inline) raster image to avoid recalc
+* resize title logo image to keep on page (#714)
+* don't leave blank page when importing PDF page (#614)
+* fix running content dimensions (#616)
+* introduce document attribute to control default text alignment (#396)
+* allow setting a default columns spec for running content on both recto and verso pages; set if not defined
+* show example of center column alignment in default theme
+* 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
+* 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)
+* use correct number of dots when font style is applied to toc level (#621)
+* allow theme to control which toc levels have dot leaders; default to 2-3 (#631)
+* set font color of page number for parts in toc
+* don't crash when toc dot leader is empty string
+* list preface with title in table of contents (#732)
+* allow theme to apply text decoration to link text (#567)
+* allow page layout to be controlled from document (#565)
+* 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
+* 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
+* add support for image-based icons (#479) (@JBR69)
+* preliminary support for vertical alignment of admonition icon/label
+* allow side padding on admonition label to be controlled separately from admonition content
+* add more control over vertical rule in admonition block (#601)
+* allow theme to control font properties for admonition content (#592)
+* only add lead role to first paragraph of preamble (#654)
+* display poster image for video with link to video URI (#287)
+* add link to audio file (#475)
+* don't drop anchor within text that overruns page (#638)
+* display title for abstract (#582)
+* display title for open block (#577)
+* display block title on quote and verse blocks (#416)
+* don't draw border for quote/verse block on empty page or if border width is 0
+* allow delimiter between author names on title page to be configured in theme
+* coerce resolved value of content key in theme to String (#653)
+* honor background color from Pygments theme
+* set default inner/outer margins in base theme
+* document missing glyph encoding warning in theming guide; minor rewording
+* document how to configure fonts in SVG images (#739)
+* document how to use Asciidoctor Mathematical to enable STEM support (#45)
+* transform text containing multibyte characters (#363)
+* document in theming guide how to transform unicode letters with Ruby < 2.4
+* show unmodified text if text_transform is none (#584)
+* make performance optimization to formatted text transform
+* use reference_bounds instead of @margin_box to move past bottom
+* handle negative bottom padding properly at page boundary
+* use value of docdatetime & localdatetime attributes in PDF info (#590)
+* use truncate_to_precision instead of round to truncate floats; map to native method in Ruby >= 2.4
+* upgrade prawn-svg dependency to 0.26.x
+* upgrade prawn-icon to 1.3.0
+* document in the README how to use the autofit option on verbatim blocks
+* clarify in README how inline image are sized
+* clarify instructions in README about how to specify a page number range for printing
+* document in theming guide how to define and apply a custom Rouge theme
+* rename pdfmarks to pdfmarks; document pdfmark attribute in theming guide
+* describe the quoted string value type in the theming guide
+* add self-referencing anchor to each key prefix in theming guide
+* document nonfacing option for sections (@jnerlich)
+* fix documentation for toc_dot_leader_font_color in theming guide (@davidgamba)
+* document that dot leader inherits font properties from toc category
+* fill in missing defaults for keys in theming guide
+* rewrite intro to Keys section in theming guide
+* add keys for prose, menu, and conum categories to theming guide
+* document outline_list_marker_font_color key in theming guide
+* refactor measurement value helpers into module (#677)
+* add reproducible flag to examples
+* add inline ref and corresponding xref to chronicles example
+* fix Ruby warnings
+* update instructions and Gemfile config to use with Ruby 1.9.3
+* configure build as the default rake task
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.14[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.14[git tag]
+
 == 1.5.0.alpha.13 (2016-09-19) - @mojavelinux
 
-* Add support for double-sided (recto/verso) margins when media=prepress attribute is set (#383)
+* Add support for mirror (recto/verso) margins and facing pages when media=prepress
 * Add non-breaking hyphen glyph to built-in fonts so its intended behavior is honored (#462)
 * Add page break before a book part (#329)
-* Allow running (header/footer) content to be arrange in columns (#449)
+* Allow running (header/footer) content to be arranged in columns (#449)
+* Allow font properties to be set per element in running content (#454)
 * Prevent the SVG from modifying the document font (#494)
 * Implement decorative border for multipage quote and verse blocks (#270, #557, #558)
 * Encode anchors in hex that contain characters outside of ASCII range (#481, #301)
@@ -22,7 +144,6 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * Preserve indentation in literal and verse table cells
 * Preserve paragraph breaks in normal table cells
 * Honor value of width attribute even when autowidth option is set on table (#519)
-* Allow font properties to be set per element in running content (#454)
 * Align table title to left edge of table, regardless of table alignment (#469)
 * Add support for reversed option on ordered list (#491)
 * Don't drop whitespace in front of conum on final line of source block (#470)
@@ -47,7 +168,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * Add support for px units to pdf-page-size attribute
 * Fix parsing error when value of pdf-page-size attribute is unitless
 * Don't crash if table is empty (#480)
-* Don't crash when deleting last remaining page; don't delete last page if empty
+* Don't crash when deleting last remaining page; don't delete last page if empty (#317)
 * Don't orphan space between conums when extracting from verbatim block (#506)
 * Properly scope attr and attr? lookups
 * Rename internal page_start and page_end attributes to pdf-page-start and pdf-page-end, respectively
@@ -69,6 +190,9 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * Configure README for better preview on GitHub
 * Update chronicles example to modern AsciiDoc syntax; update content
 
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.13[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.13[git tag]
+
 == 1.5.0.alpha.12 (2016-08-05) - @mojavelinux
 
 * Fix incompatibility with Rouge 2 source highlighter (#471)
@@ -103,6 +227,9 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * Add hints to theming guide about how to apply styles when using Maven or Gradle (@fwilhe)
 * Fix gemspec to collect files when project is not a git repository or git is not available
 
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.12[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.12[git tag]
+
 == 1.5.0.alpha.11 (2016-01-05) - @mojavelinux
 
 * Allow font style for first line of abstract to be controlled by theme (@nawroth) (#378)

data/Gemfile

@@ -1,10 +1,17 @@
 source 'https://rubygems.org'
 
-gem 'prawn', '1.3.0' if (Gem::Version.new RUBY_VERSION) < (Gem::Version.new '2.0.0')
+if (Gem::Version.new RUBY_VERSION) < (Gem::Version.new '2.0.0')
+  gem 'addressable', '2.4.0'
+  gem 'prawn', '1.3.0'
+  gem 'prawn-svg', '0.21.0'
+end
 
 # Look in asciidoctor-pdf.gemspec for runtime and development dependencies
 gemspec
 
 group :examples do
   gem 'rouge', '2.0.6'
+  # Add unicode (preferred) or activesupport to transform case of text containing multibyte chars on Ruby < 2.4
+  #gem 'activesupport', '4.2.7.1' if (Gem::Version.new RUBY_VERSION) < (Gem::Version.new '2.4.0')
+  #gem 'unicode' if (Gem::Version.new RUBY_VERSION) < (Gem::Version.new '2.4.0')
 end

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.13, 2016-09-19
+v1.5.0.alpha.14, 2017-02-05
 // Settings:
 :experimental:
 :idprefix:
@@ -31,7 +31,11 @@ endif::[]
 :uri-project-issues: {uri-project-repo}/issues
 :uri-project-list: http://discuss.asciidoctor.org
 :uri-prawn: http://prawn.majesticseacreature.com
+: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
 :uri-rvm: http://rvm.io
+:uri-graphicsmagick: http://www.graphicsmagick.org
 
 ifdef::status[]
 image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={uri-gem}]
@@ -86,7 +90,7 @@ Picking up from there, {project-name} takes the pain out of creating PDF documen
 === Notable Features
 
 * Direct AsciiDoc to PDF conversion
-* <<docs/theming-guide.adoc#,Configuration-driven style and layout>>
+* <<docs/theming-guide#,Configuration-driven style and layout>>
 * SVG support
 * PDF document outline (i.e., bookmarks)
 * Table of contents page(s)
@@ -105,7 +109,7 @@ Picking up from there, {project-name} takes the pain out of creating PDF documen
 
 === Missing Features
 
-See <<WORKLOG.adoc#,WORKLOG>>.
+See <<WORKLOG#,WORKLOG>>.
 
 == Prerequisites
 
@@ -122,6 +126,7 @@ Since version 2.0.0, Prawn requires Ruby >= 2.0.0 during installation (though it
 Therefore, to use Asciidoctor PDF with Ruby 1.9.3, you must first explicitly install Prawn 1.3.0 and Prawn SVG 0.21.0 using the following commands:
 
   $ gem install prawn --version 1.3.0
+    gem install addressable --version 2.4.0
     gem install prawn-svg --version 0.21.0
 
 You can then proceed with installation of Asciidoctor PDF on Ruby 1.9.3.
@@ -151,23 +156,23 @@ 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 CodeRay, Rouge or Pygments.
+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:
 
-.CodeRay
- $ gem install coderay
-
-.Rouge
+.Rouge (preferred)
  $ gem install rouge
 
 .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):
+
+.CodeRay
+ $ gem install coderay
+
+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 
 ----
 
 Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:
@@ -183,7 +188,7 @@ Let's grab an AsciiDoc document to distill and start putting {project-name} to u
 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.
 
 ifeval::[{safe-mode-level} >= 20]
-See <<examples/basic-example.adoc#,basic-example.adoc>>.
+See <<examples/basic-example#,basic-example.adoc>>.
 endif::[]
 ifeval::[{safe-mode-level} < 20]
 .basic-example.adoc
@@ -223,7 +228,7 @@ The pain of the DocBook toolchain should be melting away about now.
 == Themes
 
 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.adoc#,Asciidoctor PDF Theme Guide>>.
+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.
 
 == Font-Based Icons
@@ -284,7 +289,7 @@ Images are resolved relative to the value of the `imagesdir` attribute at the ti
 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.
 
-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.
+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.
 
@@ -298,11 +303,14 @@ There are five ways to specify the width of an image, listed here in order of pr
 |Attribute{nbsp}Name | Description
 
 |pdfwidth
-|The display width of the image as an absolute size (e.g., 2in), percentage of the content width (e.g., 75%), or percentage of the page width (e.g., 100vw).
+|The display width of the image as an absolute size (e.g., 2in), percentage of the content area width (e.g., 75%), or percentage of the page width (e.g., 100vw).
+If a unit of measurement is not specified (or not recognized), pt (points) is assumed.
 _Intended to be used for the PDF converter only._
 
 |scaledwidth
-|The display width of the image as a percentage of the content width (e.g., 75%).
+|The display width of the image as an absolute size (e.g., 2in) or percentage of the content area width (e.g., 75%).
+If a unit of measurement is not specified, % (percentage) is assumed.
+If a unit of measurement is recognized, pt (points) is assumed.
 _Intended to be used for print output such as PDF._
 
 |image_width key from theme
@@ -311,16 +319,20 @@ _Only applies to block images._
 
 |width
 |The unitless display width of the image (assumed to be pixels), typically matching the intrinsic width of the image.
-If the width exceeds the content width, the image is scaled down to the content width.
+If the width exceeds the content area width, the image is scaled down to the content area width.
 
 |_unspecified_
-|If you don't specify one of the aforementioned width settings, the intrinsic width of the image is used (the px value is multiplied by 75% to convert to pt) unless the width exceeds the content width, in which case the image is scaled down to the content width.
+|If you don't specify one of the aforementioned width settings, the intrinsic width of the image is used (the px value is multiplied by 75% to convert to pt, assuming canvas is 96 dpi) unless the width exceeds the content area width, in which case the image is scaled down to the content area width.
 |===
 
-The image is always sized according to the explicit or intrinsic width and its height is scaled proporationally.
+The image is always sized according to the explicit or intrinsic width and its height is scaled proportionally.
 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.
 
+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.
+
 === Using the pdfwidth Attribute
 
 The pdfwidth attribute is the recommended way to set the image size for the PDF output.
@@ -332,17 +344,18 @@ The pdfwidth attribute supports the following units:
 
 * pt (default)
 * in
-* mm
 * cm
+* mm
 * px
-* % (percentage of content width)
+* pc
 * vw (percentage of page width)
+* % (percentage of content area width)
 
 In all cases, the width is converted to pt.
 
-=== Specifying a default pdfwidth
+=== Specifying a default width
 
-If you want to scale all block images that don't have a pdfwidth (or scaledwidth) attribute the same, assign a value to the image_width key in your theme.
+If you want to scale all block images that don't have a pdfwidth or scaledwidth attribute specified, assign a value to the image_width key in your theme.
 
 [source,yaml]
 ----
@@ -352,18 +365,168 @@ image:
 
 === Inline Image Sizing
 
-Inline images are handled different than block images.
-In particular, inline images do not support sizing using the pdfwidth attribute.
+Inline images can be sized in much the same way as block images (using the pdfwidth, scaledwidth or width attributes), with the following exceptions:
+
+* The viewport width unit (i.e., vw) is not recognized in this context.
+* The image will be scaled down, if necessary, to fit the width and height of the content area.
+* Inline images do not currently support a default width controlled from the theme.
+
+If the resolved height of the image is less than or equal to 1.5 times the line height, the image won't disrupt the line height and is centered vertically in the line.
+This is done to maximize the use of available space.
+Once the resolved height exceeds this amount, the height of the line is increased (by increasing the font size of the invisible placeholder text) to accommodate the image.
+In this case, the surrounding text will be aligned to the bottom of the image.
+If the image height exceeds the height of the page, the image will be scaled down to fit on a single page (this may cause the image to advance to the subsequent page).
+
+== Fonts in SVG Images
+
+Asciidoctor PDF uses {uri-prawn-svg}[prawn-svg] to embed SVGs in the PDF document, including SVGs generated by Asciidoctor Diagram.
+
+Actually, it's not accurate to say that prawn-svg embeds the SVG.
+Rather, prawn-svg is an SVG _renderer_.
+prawn-svg translates an SVG into native PDF text and graphic objects.
+You can think of the SVG as a sequence of drawing commands.
+The result becomes indistinguishable from other PDF objects.
+
+What that means for text is that any font family used for text in the SVG _must_ be registered in the Asciidoctor PDF theme file (and thus with Prawn).
+Otherwise, Prawn will fallback to using the closest matching built-in (afm) font from PDF (e.g., sans-serif becomes Helvetica).
+Recall that afm fonts only support basic Latin.
+As we like to say, PDF is <<docs/theming-guide#built-in-afm-fonts,bring your own font>>.
+
+If you're using Asciidoctor Diagram to generate SVGs to embed in the PDF, you likely need to specify the default font the diagramming tool uses.
+Let's assume you are making a plantuml diagram.
+
+To set the font used in the diagram, first create a file named [.path]_plantuml.cfg_ and populate it with the following content:
+
+----
+skinparam defaultFontName Noto Serif
+----
+
+TIP: You can choose any font name that is registered in your Asciidoctor PDF theme file.
+When using the default theme, your options are "Noto Serif", "M+ 1mn", and "M+ 1p Fallback".
+
+Next, pass that path to the `plantumlconfig` attribute in your AsciiDoc document (or set the attribute via the CLI or API):
+
+----
+:plantumlconfig: plantuml.cfg
+----
+
+Clear the cache of your diagrams and run Asciidoctor PDF with Asciidoctor Diagram enabled.
+The diagrams will be generated using Noto Serif as the default font, and Asciidoctor PDF will know what to do.
+
+The bottom line is this:
+If you're using fonts in your SVG, and you want those fonts to be preserved, those fonts must be defined in the Asciidoctor PDF theme file.
+
+== Supporting Additional Image File Formats
+
+In order to embed an image into a PDF, Asciidoctor PDF must understand how to read it.
+To perform this work, Asciidoctor delegates to the underlying libraries.
+{uri-prawn}[Prawn] provides support for reading JPG and PNG images.
+{uri-prawn-svg}[prawn-svg] brings support for SVG images.
+Without any additional libraries, those are the only supported image file formats.
+
+If you need support for additional file formats, such as GIF or TIFF, you must install the {uri-prawn-gmagick}[prawn-gmagick] Ruby gem.
+prawn-gmagick is an extension for Prawn based on {uri-graphicsmagick}[GraphicsMagick] and brings supports all the formats recognized by that library.
+
+The prawn-gmagick gem uses native extensions to compile against GraphicsMagick.
+This system prerequisite limits installation to Linux and OSX.
+Please refer to the {uri-prawn-gmagick}[README for prawn-gmagick] to learn how to install it.
+
+Once this gem is installed, Asciidoctor automatically switches over to it to handle embedding of all images.
+In addition to support for more additional image file formats, this gem also speeds up image processing considerably, so we highly recommend using it if you can.
+
+== STEM Support
+
+Unlike the built-in HTML converter, Asciidoctor PDF does not provide native support for STEM blocks and inline macros.
+That's because Asciidoctor core doesn't actually process STEM equations.
+In the HTML output, Asciidoctor relies on the JavaScript-based MathJax library to parse and render the equations in the browser.
+All the HTML converter does is wrap the equations so MathJax is able to find them.
+
+In order to insert a rendered equation into the PDF, the toolchain has to parse the equations and convert them to a format the PDF writer (Prawn) can understand.
+That typically means converting to an image.
+
+The recommended solution is an extension named Asciidoctor Mathematical, which we'll cover here.
+Another solution still under development uses Mathoid to convert STEM equations to images.
+Mathoid is a library that invokes MathJax using a headless browser.
+That prototype can be found in the https://github.com/asciidoctor/asciidoctor-extensions-lab#extension-catalog[Asciidoctor extensions lab].
+
+=== Asciidoctor Mathematical
+
+{uri-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros.
+After the document has been parsed, the extension locates all the STEM blocks and inline macros, converts the equations to images using Mathematical, then replaces them with image nodes.
+Conversion then proceeds as normal.
+
+Asciidoctor Mathematical is a Ruby gem that uses native extensions.
+It has a few system prerequisites which limit installation to Linux and OSX.
+Please refer to the {uri-asciidoctor-mathematical}#installation[installation section] in the Asciidoctor Mathematical README to learn how to install it.
+
+Once Asciidoctor Mathematical is installed, you just need to enable it when invoking Asciidoctor PDF using the `-r` flag:
+
+ $ asciidoctor-pdf -r asciidoctor-mathematical sample.adoc
+
+If you're invoking Asciidoctor via the API, all you need to do is require the gem before invoking Asciidoctor:
+
+[source,ruby]
+----
+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:
+
+ $ asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg sample.adoc
+
+Refer to the {uri-asciidoctor-mathematical}#readme[README] for Asciidoctor Mathematical to learn about additional settings and options.
+
+== Autofitting Text
+
+Verbatim blocks often have long lines that don't fit within the fixed width of the PDF canvas.
+And unlike on the web, the PDF reader cannot scroll horizontally to reveal the overflow text.
+Therefore, the long lines are forced to wrap.
+Wrapped lines can make the verbatim blocks hard to read or even cause confusion.
+
+To help address this problem, Asciidoctor PDF provides the `autofit` option on all verbatim (i.e., literal, listing and source) blocks to attempt to fit the text within the available width.
+When the `autofit` option is enabled, Asciidoctor PDF will decrease the font size until the longest line fits without wrapping.
+
+CAUTION: The font size will not be decreased beyond the value of the `base_font_size_min` key specified in the PDF theme.
+If that threshold is reached, lines may still wrap.
+
+Here's an example of the autofit option enabled on a source block:
+
+[source,asciidoc]
+....
+[source%autofit,java]
+----
+@SessionScoped
+public class WidgetRepository {
+    @GET
+    @Produces("application/json")
+    public List<String> listAll(@QueryParam("start") Integer start, @QueryParam("max") Integer max) {
+        ...
+    }
+}
+----
+....
+
+If you want to enable the autofit option globally, set the `autofit-option` document attribute in the document header (or somewhere before the relevant blocks):
+
+[source,asciidoc]
+----
+:autofit-option:
+----
 
-Here's how an inline image is sized.
-The image height is scaled down to 75% of the specified width (px to pt conversion).
-If the image height is more than 1.5x the height of the surrounding line of text, the font size and line metrics of the fragment are modified to fit the image in the line.
+== Printing Page Ranges
 
-== Printing
+The print dialog doesn't understand the page numbers labels (which appear in the running content).
+Instead, it only considers physical pages.
+Therefore, to print a range of pages as they are labeled in the document, you need to add the number of front matter pages (i.e., the non-numbered pages) to the page number range in the print dialog.
 
-To print a range of pages as labeled in the document, you need to add the number of front matter pages (the pages labeled with a roman numeral) to the printed page number(s).
-The print dialog doesn't understand the page numbers labels.
-Instead, it only considers the physical pages.
+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.
 
 == Optional Scripts
 
@@ -383,7 +546,7 @@ IMPORTANT: The `optimize-pdf` script relies on Ghostscript >= 9.10.
 Otherwise, it may actually make the PDF larger.
 Also, you should only consider using it if the file size of the original PDF is > 5MB.
 
-If a file is found with the extension `.pdfmarks` and the same rootname as the input file, it is used to add metadata to the generated PDF document.
+If a file is found with the extension `.pdfmark` and the same rootname as the input file, it is used to add metadata to the generated PDF document.
 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.
 
@@ -471,8 +634,8 @@ For best results, be sure to always use `bundle exec` whenever invoking the `./b
 
 == Copyright
 
-Copyright (C) 2014-2016 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-2017 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.adoc#,LICENSE>> file.
-Refer to the <<NOTICE.adoc#,NOTICE>> file for information about third-party Open Source software in use.
+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.