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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5b988f6863043a9a22bf55cdbbef3a12a9c9a16
-  data.tar.gz: a623fe7f63d9311404fadca17ff1f17f97b13add
+  metadata.gz: ed86baf3f76110d88dcb2e25c13f99a22fdaa42c
+  data.tar.gz: bc58645703cf1a7682d6032765c193c077ca49ec
 SHA512:
-  metadata.gz: 1311807ce5e4b061faddbb7dd2cce3bc8f563c4a004849f082de2a8e625e90b1d097524e26e1bc97a21b3f363f5de262c649f6888c009e2cd6a6234135d95b21
-  data.tar.gz: b296d8fbc882739a27b033032c0be761fb0cc9ad0b03a245865e2869be49d8608d9f6b64fc43af061c369c99b217c6846a5da66a14a8dafb3751942e8a1eef66
+  metadata.gz: 9fad7aff67713993469f08ff73ee9ff8a81d29c0182d4c38c93830561b9c3e149fe159b9b4ef9fe71a3e4faa831d795251d1691cbddc803e2b2a2cc34030a561
+  data.tar.gz: 3c07404a84deb2aac522cac10d0ab56ecd174e3349aec168105ecc79e9f5232c6586204617d230f45ea206b6c3936912b3e28c448c3c7f515fecd40fcff93c5b

data/CHANGELOG.adoc

@@ -0,0 +1,325 @@
+= {project-name} Changelog
+:project-name: Asciidoctor PDF
+:uri-repo: https://github.com/asciidoctor/asciidoctor-pdf
+
+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.13 (2016-09-19) - @mojavelinux
+
+* Add support for double-sided (recto/verso) margins when media=prepress attribute is set (#383)
+* 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)
+* 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)
+* Size the line number gutter correctly (accounting for width of largest line number) (#402)
+* Allow theme to specify default value for pdfwidth attribute on image and document in README (#455)
+* Fix front matter page numbering by adding page labels for all front matter pages in outline (#458)
+* Allow image type to be specified explicitly using format attribute on image macro (#540)
+* Add support for literal and verse table cell styles
+* 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)
+* Add more control over position of elements on title page, including support for vw units (#418)
+* Allow table caption position/side to be controlled by theme (#531)
+* Use base_align setting from theme as default alignment for headings
+* Resolve bare image-related attribute values relative to base_dir
+* Only allow Prawn SVG to fetch remote images if the allow-uri-read attribute is set (#548)
+* Introduce page_margin_inner and page_margin_outer keys to theme
+* Start title page, toc, main content, parts, and chapters on recto page when media=prepress and doctype=book
+* Allow default font style for table to be set via theme (table_font_style)
+* Use correct default bullet per nested unordered list level (#529)
+* Call start_new_part at start of each book part
+* Delegate to layout_part_title method to layout part title
+* Don't match a special section as a chapter unless the doctype is book
+* Fix list marker placement when list item touches bottom of page
+* Eliminate excessive spacing between list items that contain nested lists
+* Drop lines in running (header/footer) content with unresolved attributes (#522)
+* Ensure start_new_chapter is always executed at a chapter transition (#524)
+* Add support for root xref (e.g., <<included-doc#>>) (#521)
+* Prevent block from spilling to next page if there's no more content (#361)
+* 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 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
+* Fix settings for table header cell
+* Fix padding around content of quote block in default theme
+* Read theme file with UTF-8 encoding (#533)
+* Allow temporary image file to be deleted on Windows (#425)
+* Don't crash if theme file is empty (#551)
+* Don't crash if cover image can't be read; warn instead
+* Clarify in theming guide how to write numbers with 3 or more digits (#555)
+* Document how inline images are sized
+* Document how to disable default footer from theme
+* Update explanation of WINANSI encoding behavior in theming guide
+* Restore support for Ruby 1.9.3 (#528)
+* Upgrade prawn-icon to 1.2.0 (which upgrades Font Awesome to 4.6.3)
+* Upgrade prawn-svg to 0.25.2 (by way of more lenient version range)
+* Fix Ruby warnings
+* Document in README how image paths are resolved
+* Configure README for better preview on GitHub
+* Update chronicles example to modern AsciiDoc syntax; update content
+
+== 1.5.0.alpha.12 (2016-08-05) - @mojavelinux
+
+* Fix incompatibility with Rouge 2 source highlighter (#471)
+* Declare rouge gem in Gemfile for use with examples
+* Add option to make URLs visible in printed PDF using show-link-uri or media=print attributes (#435, #463)
+* Document options for scaling an image (#453)
+* Add support for images to span width of page (#424)
+* Fix embedding of remote images; fix case when imagesdir is a URI (#467)
+* Collapse non-significant whitespace (#465)
+* Document how to inherit font size for a given heading level (#460)
+* Decode character references in link URIs (#448)
+* Use arrow as caret for menu path instead of pipe (#441)
+* Document theme-related AsciiDoc attributes in theming guide (#428)
+* Section title alignment should be customizable via theme (#343)
+* Collapse all whitespace when normalizing (#355)
+* Require space on either side of math operator to avoid interpretting dates as math equations (#429)
+* Allow specifying a font style for a title on the title page (#423)
+* Fix Prawn SVG to support arrow heads on lines (#75)
+* Upgrade prawn-svg to 0.25.1
+* Upgrade prawn-icon to 1.1.0
+* Fix rendering of two images in header or footer (#421)
+* Allow table grid color and width to be controlled by theme (@ntfc)
+* Fix undefined local variable or method `dest_y' when adding auto-generated anchor to section (#419)
+* SVG files that include image elements are not rendered correctly improvement (@AlexanderZobkov) (#414)
+* Fix Prawn SVG to support currentColor keyword (#407)
+* Parser should recognize up to 6 digit character references (#404)
+* Properly convert a negative measurement value in theme
+* Coerce percentage value to float instead of integer in theme
+* Set minimum required Ruby version to 1.9.3 instead of 1.9
+* Use title capitalization for section titles in theming guide
+* Update and reorganize keys in theming guide; document numerous keys previous missing
+* 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
+
+== 1.5.0.alpha.11 (2016-01-05) - @mojavelinux
+
+* Allow font style for first line of abstract to be controlled by theme (@nawroth) (#378)
+* Add option to make builds reproducible (@bk2204) (#338)
+* Set default page size to A4 (@stephenhay) (#319)
+* Preprocess all hex color values (#381)
+* Add note about preprocessing hex color values to theming guide (#381)
+* Honor base font style (#373)
+* Don't fail to delete tmp file (#369)
+* Lazy load icon fonts if detected (#364)
+* Reduce heading line height in default theme (#351)
+* Set default (fallback) SVG font from theme (#210)
+* Expand last column to fit width of table (#372)
+* Don't cache resolved imagesdir attribute value
+* Use fallback when merging icon data
+* Defer to built-in caching in prawn-icon
+* Document replacements and numeric character refs in header/footer content
+* Document base_font_size_min setting in theming guide
+* Document that page background colors & images do not currently work in AsciidoctorJ PDF
+* Use failproof relative require logic in bin script
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.11[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.11[git tag]
+
+== 1.5.0.alpha.10 (2015-11-01) - @mojavelinux
+
+* Allow admonition icon to be customized by theme (#121) (@jessedoyle)
+* Update to prawn-icon 1.0.0 (#335) (@jessedoyle)
+* Only generate the pdfmarks file if the pdfmarks attribute is set
+* Honor table alignment (via align attribute or role) (#299)
+* Use Hash for ViewerPreferences; set initial magnification (#303)
+* Handle case when colpcwidth is unspecified (#314)
+* Show title for lists (olist, ulist, dlist) (#316)
+* Don't attempt to add running content if document has no content pages
+* Correctly calculate toc page range (#322)
+* Don't insert blank page after back cover (#328)
+* Document theme key that sets sidebar padding (#344)
+* Handle case when CodeRay passes nil text to text_token
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.10[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.10[git tag]
+
+== 1.5.0.alpha.9 (2015-08-02) - @mojavelinux
+
+* Apply point conversion to image widths (#221)
+* Restore missing glyphs in Noto Serif font; adds support for Cyrillic languages (#72, #99)
+* Add support for the Rouge source highlighter (#247)
+* Fix parsing of style attribute in inline markup when it contains spaces; fixes Pygments highlighting
+* Expand tabs to spaces in source document (#236)
+* Scale down SVG if width is wider than page (#242)
+* Load a base theme with defaults for required keys (#132)
+* Enable PDF page import using block image macro (#177)
+* Restore method in PDF::Core needed to import PDF page (#237)
+* Restore text rendering mode after PDF import (#251)
+* Support writing to STDOUT and other IO objects (#254)
+* Enable pagenums by default; allow noheader & nofooter to control running header/footer (#205)
+* Implement explicit table width, including autowidth (#258)
+* Handle conversion to windows-1252 more gracefully when using built-in (AFM) fonts (#290)
+* Disable warning if using a built-in (AFM) font
+* Remove use of rhythm theme keys from converter (#289)
+* Allow font_style to be set on literal text (#291)
+* Parse inline image macro value of page_background_image (#222)
+* Allow theme to control header cells in table body (#272)
+* Make line height in running header/footer configurable (#274)
+* Normalize text content in running header/footer (#266)
+* Modify vertical alignment setting for running header/footer (#264)
+* Use table background color, even if white; upgrade to Prawn Table 0.2.2 (#214)
+* Delete trailing content page if empty (#147)
+* Fix dry run calculation of block height...again (#215)
+* Move footnotes to inline in a lighter shade
+* Fix for JRuby 1.7 running in 2.0 mode
+* Upgrade Prawn SVG to 0.21.0; fixes most badge SVGs
+* Upgrade thread_safe gem
+* Prevent crash if doc has no sections (@abatalev)
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.9[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.9[git tag]
+
+== 1.5.0.alpha.8 (2015-06-23) - @mojavelinux
+
+* Support inline images (#9)
+* Support link attribute on inline images (#209)
+* Support inline icon macro (#97)
+* Allow fine-grained control over image width (#76)
+* Size conversion not yet applied to images on title page or in running header/footer
+* Enable checklists (#181)
+* Fix block height calculation when content is indented by propagating bounds to scratch document (#215)
+* Don't insert page break before content whose height exceeds a single page (#183)
+* Dash border of literal/listing block at page boundary when broken across pages (#190)
+* Don't crash if toc entry is too long (#200)
+* Add missing methods on OpenStruct to fix Rubinius compatibility (#81)
+* Autofit font size in listing & literal blocks if autofit option is specified (#185)
+* Support border style (e.g., double, dashed, dotted) (#196)
+* Allow font color of outline list marker to be set by theme (#170)
+* Allow use of hyphen in property names in the theme (#193)
+* Only include table of contents if toc attribute is defined in header (#187)
+* Improve parsing of pdf-page-size attribute
+* Handle case in colist converter when previous block isn't found (#173)
+* Print Asciidoctor PDF version in CLI output
+* Upgrade Prawn (< 3.0.0, >= 1.3.0) (#68)
+* Upgrade Prawn SVG to 0.20.0
+* Document gem installation in README (#112)
+* Perform code cleanups (#195)
+* Silence warning about toc block macro
+* Add -example suffix to example file names
+* Use CodeRay as syntax highlighter in examples (#207)
+* Use proper font names in default them to support custom fonts in SVGs
+* Rework parser to parse void elements
+* Apply first line formatting correctly (no dropped words)
+* Add support for text-center role on paragraphs
+* Update theming guide
+* Fix cross references in README
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.8[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.8[git tag]
+
+== 1.5.0.alpha.7 (2015-05-31) - @mojavelinux
+
+* Add support for font-based icons (Jesse Doyle) (#15)
+* Enable font fallback support (Rei)
+* Support single value for font_fallbacks key in theme
+* Reenable M+ 1p as the fallback font
+* Add option to specify the background color for even table rows (Tord Heimdal) (#104)
+* Add block title for paragraphs (David Gamba) (#67)
+* Allow custom page size setting (Otavio Salvador) (#84)
+* Fix xref to sections (#56)
+* Fix xrefs to non-section content (#110)
+* Allow theme to control layout of title page (#135)
+* Allow theme to control style of table of contents (#167)
+* Allow running header & footer content to be customized (#89)
+* Tighten spacing between list items, make value configurable (#92)
+* Support CMYK color values (#155)
+* Add support for measurement values in theme (#156)
+* Name per-level heading theme keys consistently (e.g., heading_h<n>_font_size) (#157)
+* Preprocess theme data to allow # in front of hex colors (#158)
+* Support linkable images (#51)
+* Render table footer row (#123)
+* Don't crash if sectids attribute is disabled (#70)
+* Support text transform in theme (uppercase / lowercase) (#138)
+* Keep together shouldn't create blank pages (#150)
+* Properly resolve image target as system path (#87)
+* Show warning when image cannot be read (#148)
+* Allow page background image to be specified (#134)
+* Support PDF format as cover page (#113)
+* Accomodate numbered list with large numbers (#91)
+* Position list marker correctly (#140)
+* Allow theme to set font size & family of table cells (#139)
+* Unencode character entities in document title (#136)
+* Process callouts in listing & literal blocks (#31)
+* Use :center to vertically align table cell (#118)
+* Normalize endlines in table cell text (#116)
+* Support setting page size via attribute (#65)
+* Remove unused fonts; update version of NotoSerif font license file
+* Remove Asciidoctor theme until we're ready to fully implement
+* Restore source highlighting when nested inside block
+* Allow keys in theme to be nested to an arbitrary depth
+* Assign width to border for blockquote if not specified in theme
+* Add support for font family and style per heading level
+* Implement basic converter for inline_indexterm
+* Coerce negative values in theme if they slip through
+* Use preserve_indentation in layout_prose
+* Support remote images
+* Add warning about unsupported gif format
+* Abort cli if option parsing returns exit code
+* Use SafeYAML to load theme files
+* Handle transparent value for table background colors
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.7[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.7[git tag]
+
+== 1.5.0.alpha.6 (2014-11-28) - @mojavelinux
+
+* Add pdf-fontsdir attributes to redefine fonts directory (andrey)
+* Use require_relative to load Asciidoctor PDF in asciidoctor-pdf script (Ryan Bigg)
+* Add example for specifying theme file (Leif Gruenwoldt) (#61)
+* Add thread_safe gem to remove warning when registering converter
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.6[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.6[git tag]
+
+== 1.5.0.alpha.5 (2014-09-15) - @mojavelinux
+
+* Allow chapter label to be controlled using the `chapter-label` attribute (#47)
+* Prevent toc from overflowing content (#35)
+* Fix page numbering for various permutations of front matter
+* Don't activate implicit header include processor by default (#48, #25)
+* Draw box around listings and literal blocks than span more than one page (#11)
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.5[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.5[git tag]
+
+== 1.5.0.alpha.4 (2014-09-09) - @mojavelinux
+
+* Fix yield statement so Asciidoctor PDF can be used with JRuby
+* Document that the coderay gem must be installed to run the examples (#42)
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.4[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.4[git tag]
+
+== 1.5.0.alpha.3 (2014-09-08) - @mojavelinux
+
+* Remove unnecessary dependencies (tilt, slim, thread_safe)
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.3[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.3[git tag]
+
+== 1.5.0.alpha.2 (2014-09-05) - @mojavelinux
+
+* Add magic encoding header to source file so Asciidoctor PDF can be used with Ruby 1.9.3 (#33, #36)
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.2[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.2[git tag]
+
+== 1.5.0.alpha.1 (2014-09-04) - @mojavelinux
+
+* Rewrite as proper Asciidoctor converter (#29)
+* Initial pre-release
+
+{uri-repo}/issues?q=milestone%3Av1.5.0.alpha.1[issues resolved] |
+{uri-repo}/releases/tag/v1.5.0.alpha.1[git tag]

data/Gemfile

@@ -6,5 +6,5 @@ gem 'prawn', '1.3.0' if (Gem::Version.new RUBY_VERSION) < (Gem::Version.new '2.0
 gemspec
 
 group :examples do
-  gem 'rouge', '2.0.5'
+  gem 'rouge', '2.0.6'
 end

data/README.adoc

@@ -1,29 +1,42 @@
 = 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.12, 2016-08-05
+v1.5.0.alpha.13, 2016-09-19
 // Settings:
-:compat-mode!:
 :experimental:
 :idprefix:
 :idseparator: -
-:icons: font
-ifdef::env-github,env-browser[:outfilesuffix: .adoc]
-:pagenums:
-//:pdf-page-size: [8.25in, 11.69in]
-//:pdf-page-size: A4
-ifdef::env-browser[:toc: preamble]
+ifndef::env-github[:icons: font]
+ifdef::env-github,env-browser[]
+:toc: macro
+:toclevels: 1
+endif::[]
+ifdef::env-github[]
+:status:
+:outfilesuffix: .adoc
+:!toc-title:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
 // Aliases:
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // URIs:
-//ifdef::env-github[:relfileprefix: /blob/master/]
+:uri-asciidoctor: http://asciidoctor.org
+:uri-gem: http://rubygems.org/gems/asciidoctor-pdf
 :uri-project: https://github.com/asciidoctor/asciidoctor-pdf
 :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-rvm: http://rvm.io
-:uri-asciidoctor: http://asciidoctor.org
+
+ifdef::status[]
+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::[]
 
 _Lo and behold_, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! +
 _No more middleman._ +
@@ -35,7 +48,9 @@ CAUTION: {project-name} is currently _alpha_ software.
 While the converter handles most AsciiDoc content, there's still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented.
 See the milestone v1.5.0 in the {uri-project-issues}[issue tracker] for details.
 
-== Prawn, the majestic PDF generator
+toc::[]
+
+== Prawn, the Majestic PDF Generator
 
 {uri-project}[{project-name}] is made possible by an amazing Ruby gem named Prawn.
 And what a gem it is!
@@ -68,31 +83,33 @@ Picking up from there, {project-name} takes the pain out of creating PDF documen
 
 == Features
 
-=== Notable features
+=== Notable Features
 
 * Direct AsciiDoc to PDF conversion
 * <<docs/theming-guide.adoc#,Configuration-driven style and layout>>
+* SVG support
 * PDF document outline (i.e., bookmarks)
 * Table of contents page(s)
 * Document metadata (title, authors, subject, keywords, etc)
 * Internal cross reference links
-* Syntax highlighting with CodeRay or Pygments
+* Syntax highlighting with Rouge, Pygments, or CodeRay
 * Page numbering
 * Customizable running content (header and footer)
 * “Keep together” blocks (i.e., page breaks avoided in certain block content)
+* Orphaned section titles avoided
 * Autofit verbatim blocks (as permitted by base_font_size_min setting)
-* Orphan section titles avoided
 * Table border settings honored
 * Font-based icons
-* Custom fonts
+* Custom (TTF) fonts
+* Double-sided printing mode (margins alternate on recto and verso pages)
 
-=== Missing features
+=== Missing Features
 
 See <<WORKLOG.adoc#,WORKLOG>>.
 
 == Prerequisites
 
-All that's needed is Ruby (1.9.3 or above; 2.2.x recommended) and a few Ruby gems, which we explain how to install in the next section.
+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.
 
 To check if you have Ruby available, use the `ruby` command to query the version installed:
 
@@ -100,15 +117,17 @@ To check if you have Ruby available, use the `ruby` command to query the version
 
 [WARNING]
 ====
-Prawn 2.0.0 and above requires Ruby >= 2.0.0 at installation (though it still works with Ruby 1.9.3 once you get beyond installation).
-If you need to use Asciidoctor PDF with Ruby 1.9.3, you must first install Prawn 1.3.0 using:
+By default, Asciidoctor PDF selects the latest version of Prawn to install.
+Since version 2.0.0, Prawn requires Ruby >= 2.0.0 during installation (though it may still work with Ruby 1.9.3 if you get past installation).
+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 prawn-svg --version 0.21.0
 
-You can then proceed with installation of Asciidoctor PDF.
+You can then proceed with installation of Asciidoctor PDF on Ruby 1.9.3.
 ====
 
-=== System encoding
+=== System Encoding
 
 Asciidoctor assumes you're using UTF-8 encoding.
 To minimize encoding problems, make sure the default encoding of your system is set to UTF-8.
@@ -121,11 +140,11 @@ To solve these problems, we recommend at least changing the active code page in
 
 Once you make this change, all your Unicode headaches will be behind you.
 
-== Getting started
+== Getting Started
 
 You can get {project-name} by <<install-the-published-gem,installing the published gem>> or <<development,running the code from source>>.
 
-=== Install the published gem
+=== Install the Published Gem
 
 {project-name} is published as a pre-release on RubyGems.org.
 You can install the published gem using the following command:
@@ -159,7 +178,7 @@ If you see the version of {project-name} printed, you're ready to use {project-n
 
 Let's grab an AsciiDoc document to distill and start putting {project-name} to use!
 
-=== An example AsciiDoc document
+=== 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.
 
@@ -207,7 +226,7 @@ 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>>.
 You can use the built-in theme files, which you can find in the [file]_data/themes_ directory, as examples.
 
-== Font-based icons
+== Font-Based Icons
 
 You can use icons in your PDF document using any of the following icon sets:
 
@@ -259,10 +278,20 @@ You can enable use of fonts during PDF generation (instead of in the document he
 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 scaling
+== Image Paths
+
+Images 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.
+
+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.
 
-Since PDF is a fixed-width canvas, you almost always need to specify an image width to get the image to fit properly on the page.
-There are four ways to specify the width of the image, listed here in order of precedence:
+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.
+
+== 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.
+There are five ways to specify the width of an image, listed here in order of precedence:
 
 [cols="1s,3d"]
 |===
@@ -276,19 +305,23 @@ _Intended to be used for the PDF converter only._
 |The display width of the image as a percentage of the content width (e.g., 75%).
 _Intended to be used for print output such as PDF._
 
+|image_width key from theme
+|Accepts the same values as pdfwidth.
+_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.
 
 |_unspecified_
-|If you don't specify one of the width attributes, 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) unless the width exceeds the content width, in which case the image is scaled down to the content width.
 |===
 
-The sizing is always controlled by the width (explicit or intrinsic) and the size of the image is scaled proporationally.
-The height of the image is ignored by the PDF converter, with one exception.
-If the height of the image exceeds the height of the page, the image is scaled down to fit on a single page.
+The image is always sized according to the explicit or intrinsic width and its height is scaled proporationally.
+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.
 
-=== pdfwidth attribute
+=== Using the pdfwidth Attribute
 
 The pdfwidth attribute is the recommended way to set the image size for the PDF output.
 This attribute is provided for two reasons.
@@ -307,7 +340,32 @@ The pdfwidth attribute supports the following units:
 
 In all cases, the width is converted to pt.
 
-== Optional scripts
+=== Specifying a default pdfwidth
+
+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.
+
+[source,yaml]
+----
+image:
+  width: 100%
+----
+
+=== Inline Image Sizing
+
+Inline images are handled different than block images.
+In particular, inline images do not support sizing using the pdfwidth attribute.
+
+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
+
+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.
+
+== 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.
 You must have Ghostscript installed to use it.
@@ -342,14 +400,14 @@ Feel free to use the {uri-project-issues}[issue tracker] or {uri-project-list}[A
 To help develop {project-name}, or to simply use the development version, you need to get the source from GitHub.
 Follow the instructions below to learn how to clone the source and run it from your local copy.
 
-=== Retrieve the source code
+=== Retrieve the Source Code
 
 You can retrieve the source of {project-name} in one of two ways:
 
 . Clone the git repository
 . Download a zip archive of the repository
 
-==== Option 1: Fetch using git clone
+==== Option 1: Fetch Using Git
 
 If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to the `git clone` command:
 
@@ -359,7 +417,7 @@ Next, change to the project directory:
 
  $ cd asciidoctor-pdf
 
-==== Option 2: Download the archive
+==== Option 2: Download the Archive
 
 If you want to download a zip archive, click the btn:[Download Zip] button on the right-hand side of the repository page on GitHub.
 Once the download finishes, extract the archive, open a console and change to that directory.
@@ -368,11 +426,11 @@ TIP: Instead of working out of the {project-handle} directory, you can simply ad
 
 We'll leverage the project configuration to install the necessary dependencies.
 
-=== Install dependencies
+=== Install Dependencies
 
 If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:
 
- $ rvm use 2.2@asciidoctor-pdf --create
+ $ rvm use 2.3@asciidoctor-pdf --create
 
 We like RVM because it keeps the dependencies required by various projects isolated.
 
@@ -395,10 +453,6 @@ NOTE: You need to call `bundle` from the project directory so that it can find t
 
 Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:
 
- $ ruby ./bin/asciidoctor-pdf -v
-
-or
-
  $ bundle exec ./bin/asciidoctor-pdf -v
 
 If you see the version of {project-name} printed, you're ready to use {project-name}!