resolves asciidoctor#383 add support for recto/verso margins (PR asci…

…idoctor#415)

- add support for recto/verso margins when attribute media=prepress
- introduce page_margin_inner and page_margin_outer keys to theme
- calculate page margin for recto and verso pages automatically
- add recto/verso support to running content
- start title page, toc, and content on recto page when media=prepress and doctype=book
- add set_page_margin helper
- add page_margin helper
- add page_side helper
- add recto_page? and verso_page? helpers
- resolve asciidoctor#458 add page labels for all front matter pages to fix page numbering in outline
- simplify toc page nums calculation
- document "prepress" publishing mode in theming guide
- use term "periphery" instead of "position" to refer to running content region
- fix some formatting and wording in theming guide

data/themes/default-theme.yml

@@ -25,6 +25,9 @@ page:
   background_color: ffffff
   layout: portrait
   margin: [0.5in, 0.67in, 0.67in, 0.67in]
+  # margin_inner and margin_outer keys are used for recto/verso print margins when media=press
+  margin_inner: 0.75in
+  margin_outer: 0.59in
   size: A4
 base:
   align: justify

docs/theming-guide.adoc

@@ -18,6 +18,7 @@ endif::[]
 // Aliases:
 :conum-guard-yaml: #
 ifndef::icons[:conum-guard-yaml: # #]
+ifdef::backend-pdf[:conum-guard-yaml: # #]
 
 ////
 Topics remaining to document:
@@ -264,7 +265,7 @@ Like programming languages, multiple and divide take precedence over add and sub
 
 The following table lists the supported operations and the corresponding operator for each.
 
-[%header%autowidth]
+[width=25%]
 |===
 |Operation |Operator
 
@@ -330,7 +331,7 @@ You can let the theme do this conversion for you automatically by adding a unit
 
 The following units are supported:
 
-[%header%autowidth]
+[width=25%]
 |===
 |Unit |Suffix
 
@@ -419,17 +420,16 @@ Regardless, we recommend that you always use either a leading `+#+` or surroundi
 
 The following are all equivalent values for the color red:
 
-[%autowidth,cols=4]
+[cols="8*m"]
 |===
-|#f00
-|'f00'
 |#ff0000
+|#FF0000
 |'ff0000'
-
+|'FF0000'
+|#f00
 |#F00
+|'f00'
 |'F00'
-|#FF0000
-|'FF0000'
 |===
 
 Here's how a hex color value appears in the theme file:
@@ -541,7 +541,7 @@ There's nothing Asciidoctor can do to convince PDF to work without the right fon
 
 The names of the built-in fonts (for general-purpose text) are as follows:
 
-[%header%autowidth]
+[width=33.33%]
 |===
 |Font Name |Font Family
 
@@ -788,6 +788,16 @@ See <<Title Page>> for details.
 |page:
   margin: [0.5in, 0.67in, 1in, 0.67in]
 
+|margin_inner^[3]^
+|<<measurement-units,Measurement>>
+|page:
+  margin_inner: 0.75in
+
+|margin_outer^[3]^
+|<<measurement-units,Measurement>>
+|page:
+  margin_outer: 0.59in
+
 |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]>> +
 (default: A4)
@@ -800,6 +810,8 @@ 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].
 . Target may be an absolute path or a path relative to the value of the `pdf-stylesdir` attribute.
+. The margins for `recto` (right-hand, odd-numbered) and `verso` (left-hand, even-numbered) pages are calculated automatically from the margin_inner and margin_outer values.
+These margins and used when the value `prepress` is assigned to the `media` document attribute.
 
 === Base
 
@@ -1331,7 +1343,7 @@ The keys in this category control the spacing around block elements when a more
 
 Block styles are applied to the following block types:
 
-[cols="1a,1a,1a", grid=none, frame=none]
+[cols="3*a",grid=none,frame=none]
 |===
 |
 * admonition
@@ -2350,7 +2362,7 @@ The keys in this category control the arrangement and style of running header an
 |===
 
 . The background color spans the width of the page, as does the border when a background color is specified.
-. `<side>` can be `recto` (right-hand, odd pages) or `verso` (left-hand, even pages).
+. `<side>` can be `recto` (right-hand, odd-numbered pages) or `verso` (left-hand, even-numbered pages).
 . `<placement>` can be `left`, `center` or `right`.
 
 IMPORTANT: You must define a height for the running header or footer, respectively, or it will not be shown.
@@ -2517,12 +2529,12 @@ The only thing you need to add to an existing build is the attributes mentioned
 There are various settings in the theme you control using document attributes.
 These settings override equivalent keys defined in the theme file, where applicable.
 
-[cols="2,3,6m"]
+[cols="2,3,6l"]
 |===
 |Attribute |Value Type |Example
 
 |autofit-option
-|flag (default: _not set_)
+|flag (default: _off_)
 |:autofit-option:
 
 |chapter-label
@@ -2533,16 +2545,20 @@ These settings override equivalent keys defined in the theme file, where applica
 |inline image macro (target is relative to `imagesdir`; can be image or PDF file)
 |+:front-cover-image: image:front-cover.pdf[]+
 
+|media
+|screen {vbar} print {vbar} prepress
+|:media: prepress
+
 |pagenums^[2]^
-|flag (default: _set_)
+|flag (default: _on_)
 |:pagenums:
 
 //|pdf-page-layout
-//|portrait, landscape
+//|portrait {vbar} landscape
 //|:pdf-page-layout: landscape
 
 |pdf-page-size
-|/~https://github.com/prawnpdf/pdf-core/blob/0.6.0/lib/pdf/core/page_geometry.rb#L16-L68[named size^], <<measurement-units,measurement dimensions>> (width x height)
+|/~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
 
 |title-logo-image
@@ -2554,6 +2570,54 @@ These settings override equivalent keys defined in the theme file, where applica
 . 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.
 
+== Publishing Mode
+
+Asciidoctor PDF provides the following features to assist with publishing:
+
+* Double-sided (mirror) page margins
+* Automatic facing pages
+
+These features are activated when you set the `media` attribute to `prepress` in the header of your AsciiDoc document or from the CLI or API.
+The following sections describe the behaviors that this setting activates.
+
+=== Double-Sided Page Margins
+
+The page margins for the recto (right-hand, odd-numbered) and verso (left-hand, even-numbered) pages are automatically calculated by replacing the side page margins with the values of the `page_margin_inner` and `page_margin_outer` keys.
+
+For example, let's assume you've defined the following settings in your theme:
+
+[source,yaml]
+----
+page:
+  margin: [0.5in, 0.67in, 0.67in, 0.67in]
+  margin_inner: 0.75in
+  margin_outer: 0.59in
+----
+
+The page margins for the recto and verso pages will be resolved as follows:
+
+recto page margin:: [0.5in, *0.59in*, 0.67in, *0.75in*]
+verso page margin:: [0.5in, *0.75in*, 0.67in, *0.59in*]
+
+The page margins alternate between recto and verso.
+The first page in the document is a recto page.
+
+=== Automatic Facing Pages
+
+If a document uses the book doctype, a blank page will be inserted, if necessary, to ensure the following pages are recto-facing pages:
+
+* Title page
+* Table of contents
+* First page of body content
+
+Other facing pages may be added in the future.
+
+For documents that use the article doctype, Asciidoctor PDF incorrectly places the document title and table of contents on their own pages.
+This can result in the page numbering and the page facing to be out of sync.
+As a workaround, Asciidoctor PDF inserts a blank page, if necessary, to ensure the first page of body content is a recto-facing page.
+
+You can check on the status of this defect by following /~https://github.com/asciidoctor/asciidoctor-pdf/issues/95[issue #95].
+
 ////
 == Resources for Extending Asciidoctor PDF