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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 94832dc67ed7ce7dfc52ecd5245bcd47d1a13ad7
-  data.tar.gz: fe2c218069cc009756e83c8e8aacaa3d15b48a88
+  metadata.gz: 33a408180f820e2def56daa216f2993e059faa37
+  data.tar.gz: a375982bb4846383206446e61b5151c0928f2f0a
 SHA512:
-  metadata.gz: 881736c11065cddaf7cbef76d587016267605b6acb9c09a7f694f6a0c347e4aeec09e2ba151dd3528dbcd9198e8f4322c15956e7fa61c6e9c675756ec386aaa9
-  data.tar.gz: f37f79944645d1139fbd347761d028f80595f3f0a827b8cd9b65d8ef177929336882f93f1f2ea66a15a79a4ad3998117f9d9c0f8c4f8f3ecb5e5220e62cd03ff
+  metadata.gz: 7fd089829761e7ba27f54cda90169aece0fa6e3f7bb564ad35ca9889b806e2685796cb26836e8ff8295bc4ec42d8aa1ea62a7fc81dad745c98dbd6d6e2dea3d4
+  data.tar.gz: cb2ffc4ae5b0d69538583e4a992787185b5bec827c64df6d7bf15cb619355e30740a929dfb91f7feea9231670bbe07c335557552e9f0658efea454f413b63981

data/CHANGELOG.adoc

@@ -5,6 +5,37 @@
 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.15 (2017-03-27) - @mojavelinux
+
+* fix compatibility with Prawn 2.2.0 (#775)
+* add workaround for TTFunk bug when font table has empty data
+* take fallback font into account when calculating width of string (#651)
+* fill and stroke bounds of sidebar across all pages (#259) (@TobiasHector)
+* allow page margin to be set using pdf-page-margin attribute (#749)
+* implement none, no-bullet and unstyled unordered list styles
+* add dots to all levels in TOC if toc_dot_leader_levels is all
+* use bold style for description list term by default (#776)
+* always escape index term text (#761)
+* don't crash if color value on text span is invalid
+* implement start line number for source listing (Rouge) (#752)
+* enable "start inline" option when highlighting PHP (#755)
+* persuade CodeRay to handle html+ source languages
+* introduce stripes attribute to table to control zebra-striping (#724)
+* allow theme to set style of table border and grid (#766)
+* allow theme to set text transform on header cell in table body (#750)
+* set top border width of first body row to match bottom border width of header row
+* don't add TOC if empty (#747)
+* optimize code that generates outline level
+* don't recalculate header_cell_data for each row
+* use slightly more efficient way to find Pygments lexer
+* upgrade rouge to 2.0.7
+* upgrade prawn-templates to 0.0.5
+* revise information in theming guide pertaining to custom fonts
+* document in README how to get full support for CJK languages
+* document in theming guide that Asciidoctor PDF subsets font when embedding
+* document that background images are scaled to fit bounds of page
+* add note in theming guide about using double quoted strings
+
 == 1.5.0.alpha.14 (2017-02-05) - @mojavelinux
 
 * add support for AsciiDoc table cells (including nested tables) (#6)
@@ -12,16 +43,16 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * 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)
+* implement converter for index (#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
+* show alt text when image fails to embed (#693)
+* always show block 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)
+* 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

data/Gemfile

@@ -10,7 +10,7 @@ end
 gemspec
 
 group :examples do
-  gem 'rouge', '2.0.6'
+  gem 'rouge', '2.0.7'
   # 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')

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.14, 2017-02-05
+v1.5.0.alpha.15, 2017-03-27
 // Settings:
 :experimental:
 :idprefix:
@@ -123,13 +123,17 @@ To check if you have Ruby available, use the `ruby` command to query the version
 ====
 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:
+Therefore, to use Asciidoctor PDF with Ruby 1.9.3, you must first explicitly install the following dependencies, including Prawn 1.3.0:
 
   $ 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.
+
+For all other versions of Ruby, you can simply install the Asciidoctor PDF gem.
+It will transitively install all required dependencies.
 ====
 
 === System Encoding
@@ -152,7 +156,8 @@ You can get {project-name} by <<install-the-published-gem,installing the publish
 === 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:
+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
  
@@ -231,6 +236,28 @@ 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.
 
+=== 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. 
+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.
+
+If you're writing in a non-Latin language, you need to use a dedicated theme that provides the necessary fonts.
+For example, to produce a PDF from a document written in a CJK language such as Chinese, you need to use a CJK theme.
+You can get such a theme by installing the `asciidoctor-pdf-cjk-kai_gen_gothic` gem.
+See the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project for detailed instructions.
+
+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). 
+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.
+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:
@@ -333,6 +360,9 @@ 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.
 
+Page background images are automatically scaled to fit the bounds of the page.
+Any explicit sizing is ignored for those images.
+
 === Using the pdfwidth Attribute
 
 The pdfwidth attribute is the recommended way to set the image size for the PDF output.

data/asciidoctor-pdf.gemspec

@@ -39,15 +39,16 @@ An extension for Asciidoctor that converts AsciiDoc documents to PDF using the P
   #s.add_development_dependency 'rdoc', '~> 4.1.0'
 
   s.add_runtime_dependency 'asciidoctor', '>= 1.5.0'
-  # Prawn >= 2.0.0 requires Ruby >= 2.0.0, so we must cast a wider net to support Ruby 1.9.3
-  s.add_runtime_dependency 'prawn', '>= 1.3.0', '< 3.0.0'
+  # prawn >= 2.0.0 requires Ruby >= 2.0.0, so we must cast a wider net to support Ruby 1.9.3
+  s.add_runtime_dependency 'prawn', '>= 1.3.0', '< 2.3.0'
   s.add_runtime_dependency 'prawn-table', '0.2.2'
-  s.add_runtime_dependency 'prawn-templates', '0.0.3'
-  # Prawn SVG >= 0.22.1 requires Ruby >= 2.0.0, so we must cast a wider net to support Ruby 1.9.3
+  # prawn-templates >= 0.0.5 requires prawn >= 2.2.0, so we must cast a wider net to support Ruby 1.9.3
+  s.add_runtime_dependency 'prawn-templates', '>= 0.0.3', '<= 0.0.5'
+  # prawn-svg >= 0.22.1 requires Ruby >= 2.0.0, so we must cast a wider net to support Ruby 1.9.3
   s.add_runtime_dependency 'prawn-svg', '>= 0.21.0', '< 0.27.0'
   s.add_runtime_dependency 'prawn-icon', '1.3.0'
   s.add_runtime_dependency 'safe_yaml', '~> 1.0.4'
-  s.add_runtime_dependency 'thread_safe', '~> 0.3.5'
+  s.add_runtime_dependency 'thread_safe', '~> 0.3.6'
   # For our usage, treetop 1.6.2 is slower than 1.5.3
   s.add_runtime_dependency 'treetop', '1.5.3'
 end

data/data/themes/base-theme.yml

@@ -43,7 +43,7 @@ title_page_authors_margin_top: 12
 outline_list_indent: 30
 outline_list_item_spacing: 6
 description_list_description_indent: 30
-description_list_term_font_style: normal
+description_list_term_font_style: bold
 description_list_term_spacing: 4
 block_margin_top: 0
 block_margin_bottom: 12
@@ -87,9 +87,11 @@ sidebar_padding: [12, 12, 0, 12]
 sidebar_title_align: center
 sidebar_title_font_style: bold
 table_border_color: '000000'
+table_border_style: solid
 table_border_width: 0.5
 table_cell_padding: 2
 table_head_font_style: bold
+table_body_stripe_background_color: 'EEEEEE'
 thematic_break_border_color: 'EEEEEE'
 thematic_break_border_style: solid
 thematic_break_border_width: 0.5

data/data/themes/default-theme.yml

@@ -190,10 +190,10 @@ prose:
   margin_top: $block_margin_top
   margin_bottom: $block_margin_bottom
 sidebar:
-  border_color: $page_background_color
+  background_color: eeeeee
+  border_color: e1e1e1
   border_radius: $base_border_radius
   border_width: $base_border_width
-  background_color: eeeeee
   # FIXME reenable padding bottom once margin collapsing is implemented
   padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25]
   title:
@@ -209,7 +209,7 @@ thematic_break:
   margin_top: $vertical_rhythm * 0.5
   margin_bottom: $vertical_rhythm * 1.5
 description_list:
-  term_font_style: italic
+  term_font_style: bold
   term_spacing: $vertical_rhythm / 4
   description_indent: $horizontal_rhythm * 1.25
 outline_list:
@@ -222,8 +222,8 @@ table:
   #head_background_color: <hex value>
   #head_font_color: $base_font_color
   head_font_style: bold
-  even_row_background_color: f9f9f9
-  #odd_row_background_color: <hex value>
+  #body_background_color: <hex value>
+  body_stripe_background_color: f9f9f9
   foot_background_color: f0f0f0
   border_color: dddddd
   border_width: $base_border_width

data/docs/theming-guide.adoc

@@ -22,7 +22,6 @@ ifdef::backend-pdf[:conum-guard-yaml: # #]
 
 ////
 Topics remaining to document:
-* document which attributes can be set in document (pdf-page-size, front-cover-image, back-cover-image, etc) (issue #428)
 * line height and line height length (and what that all means)
 * title page layout / title page images (logo & background)
 * document that unicode escape sequences can be used inside double-quoted strings
@@ -32,8 +31,8 @@ Topics remaining to document:
 The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file Asciidoctor PDF generates from AsciiDoc.
 This document describes how the theming system works, how to define a custom theme in YAML and how to activate the theme when running Asciidoctor PDF.
 
-IMPORTANT: If you're using a custom theme, you're expected to override some of keys described in the sections below, in particular fonts.
-If you don't define your own fonts, the built-in PDF fonts will be used.
+IMPORTANT: If you're using a custom theme, you're expected to bring your own fonts or declare the fonts from the default theme.
+If you don't declare your own fonts, the built-in PDF (afm) fonts will be used, which only support WINANSI characters (similar to Basic Latin).
 
 toc::[]
 
@@ -412,7 +411,7 @@ Images can be aligned as follows:
 === Font Styles
 
 In most cases, whereever you can specify a custom font family, you can also specify a font style.
-These two settings are combined to locate which font to select.
+These two settings are combined to locate the font to use.
 
 The following font styles are recognized:
 
@@ -597,6 +596,8 @@ Here's an example of using formatting in the content of the menu caret:
 menu_caret_content: " <font size=\"1.15em\"><color rgb=\"#b12146\">\u203a</color></font> "
 ----
 
+NOTE: The string must be double quoted in order to use a Unicode escape code like `\u203a`.
+
 Additionally, normal substitutions are applied to the value of content keys for <<Running Content (Header & Footer),running content>>, so you can use most AsciiDoc inline formatting (e.g., `+*strong*+` or `+{attribute-name}+`) in the values of those keys.
 
 == Fonts
@@ -605,9 +606,9 @@ You can select from <<built-in-afm-fonts,built-in PDF fonts>>, <<bundled-fonts,f
 If you want to use custom fonts, you must first declare them in your theme file.
 
 IMPORTANT: Asciidoctor has no challenge working with Unicode.
-In fact, it prefers Unicode and considers the whole range.
+In fact, it prefers Unicode and considers the entire range.
 However, once you convert to PDF, you have to meet the font requirements of PDF in order to preserve Unicode characters.
-There's nothing Asciidoctor can do to convince PDF to work without the right fonts in play.
+There's nothing Asciidoctor can do to convince PDF to work with extended characters without the right fonts in play.
 
 === Built-In (AFM) Fonts
 
@@ -658,9 +659,9 @@ For more information about how Prawn handles character encodings for built-in fo
 
 === Bundled Fonts
 
-Asciidoctor PDF bundles several fonts that are used in the default theme.
-You can also use these fonts in your custom theme.
-These fonts provide more characters than the built-in PDF fonts, but still only a subset of UTF-8.
+Asciidoctor PDF bundles several fonts that are used by the default theme.
+You can also use these fonts in your custom theme by simply declaring them.
+These fonts provide more characters than the built-in PDF fonts, but still only a subset of UTF-8 (to reduce the size of the gem).
 
 The family name of the fonts bundled with Asciidoctor PDF are as follows:
 
@@ -674,9 +675,9 @@ Also provides the circuled numbers used in callouts.
 http://mplus-fonts.osdn.jp/mplus-outline-fonts/design/index-en.html#mplus_1p[M+ 1p Fallback]::
 A sans-serif font that provides a very complete set of Unicode glyphs.
 Cannot be styled as italic, bold or bold_italic.
-Useful as a fallback font.
+Used as the fallback font.
 
-CAUTION: At the time of this writing, you cannot use the bundled fonts if you define your own custom fonts.
+CAUTION: At the time of this writing, you cannot use the bundled fonts if you change the value of the `pdf-fontsdir` attribute (and thus define your own custom fonts).
 This limitation may be lifted in the future.
 
 === Custom Fonts
@@ -693,7 +694,7 @@ A collection typically consists of all four styles of a font:
 * bold_italic
 
 You'll need all four styles to support AsciiDoc content properly.
-_Asciidoctor PDF cannot italicize a font that is not italic like a browser can._
+_Asciidoctor PDF cannot italicize a font dynamically like a browser can, so you need the italic style._
 
 Once you've obtained the TTF files, put them into a directory in your project where you want to store the fonts.
 It's recommended that you name them consistently so it's easier to type the names in the theme file.
@@ -719,7 +720,7 @@ font:
       bold_italic: roboto-bold_italic.ttf
 ----
 
-You can use the key you gave to the font in the font catalog anywhere a `font_family` property is accepted in the theme file.
+You can use the key that you assign to the font in the font catalog anywhere the `font_family` property is accepted in the theme file.
 For instance, to use the Roboto font for all headings, you'd use:
 
 [source,yaml]
@@ -734,6 +735,11 @@ When you execute Asciidoctor PDF, you need to specify the directory where the fo
 
 WARNING: Currently, all fonts referenced by the theme need to be present in the directory specified by the `pdf-fontsdir` attribute.
 
+When Asciidoctor PDF creates the PDF, it only embeds the glyphs from the font that are needed to render the characters present in the document.
+In other words, Asciidoctor PDF automatically subsets the font.
+However, if you're storing the fonts in a repository, you may want to subset the font (for instance, by using FontForge) to reduce the space the font occupies in that storage.
+This is simply a personal preference.
+
 You can add any number of fonts to the catalog.
 Each font must be assigned a unique key, as shown here:
 
@@ -889,7 +895,9 @@ See <<Title Page>> for details.
   size: Letter
 |===
 
-. Page backgrounds do not currently work when using AsciidoctorJ PDF.
+. Page background images are automatically scaled to fit within the bounds of the page.
++
+NOTE: Page backgrounds do not currently work when using AsciidoctorJ PDF.
 This limitation is due to a bug in Prawn 1.3.1.
 The limitation will remain until AsciidoctorJ PDF upgrades to Prawn 2.x (an upgrade that is waiting on AsciidoctorJ to migrate to JRuby 9000).
 For more details, see http://discuss.asciidoctor.org/Asciidoctor-YAML-style-file-for-PDF-and-maven-td3849.html[this thread].
@@ -1534,7 +1542,9 @@ TIP: The title page can be disabled from the document by setting the `notitle` a
     margin_bottom: 5
 |===
 
-. Page backgrounds do not currently work when using AsciidoctorJ PDF.
+. Page background images are automatically scaled to fit within the bounds of the page.
++
+NOTE: Page backgrounds do not currently work when using AsciidoctorJ PDF.
 This limitation is due to a bug in Prawn 1.3.1.
 The limitation will remain until AsciidoctorJ PDF upgrades to Prawn 2.x (an upgrade that is waiting on AsciidoctorJ to migrate to JRuby 9000).
 For more details, see http://discuss.asciidoctor.org/Asciidoctor-YAML-style-file-for-PDF-and-maven-td3849.html[this thread].
@@ -1811,7 +1821,7 @@ The keys in this category apply to the menu label (generated from the inline men
 
 |caret_content
 |<<quoted-string,Quoted string>> +
-(default: ' \u203a ')
+(default: " \u203a ")
 |menu:
   caret_content: ' > '
 |===
@@ -2490,7 +2500,7 @@ The keys in this category control the arrangement and style of definition list i
 
 |term_font_style
 |<<font-styles,Font style>> +
-(default: normal)
+(default: bold)
 |description_list:
   term_font_style: italic
 
@@ -2562,6 +2572,12 @@ The keys in this category control the arrangement and style of tables and table
 |table:
   border_color: #dddddd
 
+|border_style
+|solid {vbar} dashed {vbar} dotted +
+(default: solid)
+|table:
+  border_style: solid
+
 |border_width
 |<<values,Number>> +
 (default: 0.5)
@@ -2604,6 +2620,12 @@ The keys in this category control the arrangement and style of tables and table
 |table:
   grid_color: #eeeeee
 
+|grid_style
+|solid {vbar} dashed {vbar} dotted +
+(default: solid)
+|table:
+  grid_style: dashed
+
 |grid_width
 |<<values,Number>> +
 (default: $table_border_width)
@@ -2661,6 +2683,22 @@ The keys in this category control the arrangement and style of tables and table
   head:
     text_transform: uppercase
 
+3+|[#key-prefix-table-body]*Key Prefix:* <<key-prefix-table-body,table_body>>
+
+|background_color
+|<<colors,Color>> +
+(default: $table_background_color)
+|table:
+  body:
+    background_color: #fdfdfd
+
+|stripe_background_color^[1]^
+|<<colors,Color>> +
+(default: #eeeeee)
+|table:
+  body:
+    stripe_background_color: #efefef
+
 3+|[#key-prefix-table-foot]*Key Prefix:* <<key-prefix-table-foot,table_foot>>
 
 |background_color
@@ -2698,14 +2736,15 @@ The keys in this category control the arrangement and style of tables and table
   foot:
     font_style: italic
 
-3+|[#key-prefix-table-row]*Key Prefix:* <<key-prefix-table-row,table_<parity>_row>>^[1]^
-
-|background_color
-|<<colors,Color>> +
-(default: $table_background_color)
-|table:
-  even_row:
-    background_color: #f9f9f9
+//deprecated
+//3+|[#key-prefix-table-row]*Key Prefix:* <<key-prefix-table-row,table_<parity>_row>>^[1]^
+//
+//|background_color
+//|<<colors,Color>> +
+//(default: $table_background_color)
+//|table:
+//  even_row:
+//    background_color: #f9f9f9
 
 3+|[#key-prefix-table-cell]*Key Prefix:* <<key-prefix-table-cell,table_cell>>
 
@@ -2760,15 +2799,15 @@ The keys in this category control the arrangement and style of tables and table
   header_cell:
     font_style: italic
 
-//|text_transform
-//|<<text-transforms,Text transform>> +
-//(default: $table_head_text_transform)
-//|table:
-//  header_cell:
-//    text_transform: uppercase
+|text_transform
+|<<text-transforms,Text transform>> +
+(default: $table_head_text_transform)
+|table:
+  header_cell:
+    text_transform: uppercase
 |===
-
-. `<parity>` can be `odd` (odd rows) or `even` (even rows).
+. Applied to even rows by default; controlled using `stripes` attribute (even, odd, all, none) on table.
+//. `<parity>` can be `odd` (odd rows) or `even` (even rows).
 
 [#keys-table-of-contents]
 === Table of Contents (TOC)
@@ -3345,11 +3384,11 @@ These settings override equivalent keys defined in the theme file, where applica
 |screen {vbar} print {vbar} prepress
 |:media: prepress
 
-|page-background-image
+|page-background-image^[4]^
 |path^[2]^ {vbar} image macro^[3]^
 |+:page-background-image: image:bg.jpg[]+
 
-|pagenums^[4]^
+|pagenums^[5]^
 |flag (default: _set_)
 |:pagenums:
 
@@ -3357,15 +3396,19 @@ These settings override equivalent keys defined in the theme file, where applica
 |portrait {vbar} landscape
 |:pdf-page-layout: landscape
 
+|pdf-page-margin
+|<<measurement-units,Measurement>> {vbar} <<measurement-units,Measurement[top,right,bottom,left]>>
+|:pdf-page-margin: [1in, 0.5in]
+
 |pdf-page-size
 |https://github.com/prawnpdf/pdf-core/blob/0.6.0/lib/pdf/core/page_geometry.rb#L16-L68[Named size^] {vbar} <<measurement-units,Measurement[width, height]>>
 |:pdf-page-size: 6in x 9in
 
-|pdfmark^[5]^
+|pdfmark^[6]^
 |flag (default: _not set_)
 |:pdfmark:
 
-|text-alignment^[6]^
+|text-alignment^[7]^
 |<<text-alignments,Text alignment>>
 |:text-alignment: left
 
@@ -3381,6 +3424,12 @@ These settings override equivalent keys defined in the theme file, where applica
 . `<face>` can be `front` or `back`.
 . The path is resolved relative to base_dir.
 . The target of the image macro is resolved relative to `imagesdir`.
+. Page background images are automatically scaled to fit within the bounds of the page.
++
+NOTE: Page backgrounds do not currently work when using AsciidoctorJ PDF.
+This limitation is due to a bug in Prawn 1.3.1.
+The limitation will remain until AsciidoctorJ PDF upgrades to Prawn 2.x (an upgrade that is waiting on AsciidoctorJ to migrate to JRuby 9000).
+For more details, see http://discuss.asciidoctor.org/Asciidoctor-YAML-style-file-for-PDF-and-maven-td3849.html[this thread].
 . Controls whether the `page-number` attribute is accessible to the running header and footer content specified in the theme file.
 Use the `noheader` and `nofooter` attributes to disable the running header and footer, respectively, from the document.
 . Enables generation of the http://milan.kupcevic.net/ghostscript-ps-pdf/#marks[pdfmark] file, which contains metadata that is fed to Ghostscript when optimizing the PDF file.