asciidoctor-pdf 1.5.0.alpha.8 → 1.5.0.alpha.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2b2c65350b1794de68fc1396284903bb5e15efde
-  data.tar.gz: 29a3cfea5ef7f61d77e241518d1b26440c1f58cc
+  metadata.gz: 22493470e3006991e099beb8ddeb65c08eb033c0
+  data.tar.gz: c90d7a56f0140153feda21773e7875758b86e020
 SHA512:
-  metadata.gz: a6e7506596f8d5446e9275a00f916648f336c69543d372680a4d11d77065676de4dd7721b429d49e585386639ff3d9c7eaaca776040a0afc4f1e107e1d6e98eb
-  data.tar.gz: 173008d8b6d048722150da22616202c118f2d46929cc67f1b4ea097e0dd8b02b8fe7f13f0a6d1a933709844ad736af1eabbc1dc49c28f1315e1fea3e4e9e137c
+  metadata.gz: c7d1c228af54e9c88d796a5b9b75631e850b30cc2cafead887ee5309338bfe9cf488c211f3058aa98b6dd1153f996c409939df0b80510287971174390bcd25ef
+  data.tar.gz: 96010a61d4c6d16502e4d0418923a96cb917e5d0bbcd714826c567c060f997749f8349254df5c1c696ae4a2a453b9cff37488490e5769ba58f837ad4a389a42e

data/README.adoc

@@ -120,10 +120,18 @@ You can install the published gem using the following command:
 
  $ gem install --pre asciidoctor-pdf
  
-If you want to syntax highlight source listings, you'll also want to install CodeRay (or Pygments).
+If you want to syntax highlight source listings, you'll also want to install CodeRay, Rouge or Pygments.
+Choose one (or more) of the following:
 
+.CodeRay
  $ gem install coderay
 
+.Rouge
+ $ gem install rouge
+
+.Pygments
+ $ gem install pygments.rb
+
 Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:
 
  $ asciidoctor-pdf -v

data/Rakefile

@@ -12,6 +12,7 @@ begin
   #Rake::Task[:release].enhance [:commit_release]
 
   # NOTE you don't need to push after updating version and committing locally
+  # WARNING no longer works; it's now necessary to get master in a state ready for tagging
   task :commit_release do
     Bundler::GemHelper.new.send :guard_clean
     sh %(git commit --allow-empty -a -m 'Release #{Asciidoctor::Pdf::VERSION}')

data/data/themes/base-theme.yml

@@ -0,0 +1,90 @@
+# NOTE file is read "as is"; variables are not parsed; key layout must be flat
+# QUESTION should vertical_spacing be block_spacing instead?
+vertical_spacing: 12
+page_background_color: 'FFFFFF'
+page_layout: portrait
+# 36 is equivalent to 0.5in
+page_margin: 36
+page_size: LETTER
+base_align: left
+#base_font_color: '333333'
+base_font_color: '000000'
+#base_font_family: Times-Roman
+base_font_family: Helvetica
+base_font_size: 12
+# QUESTION should we rename to min_font_size?
+base_font_size_min: 9
+base_font_style: normal
+base_line_height: 1.15
+base_line_height_length: 13.8
+base_border_color: 'EEEEEE'
+base_border_width: 0.5
+link_font_color: '0000EE'
+literal_font_family: Courier
+heading_font_style: bold
+heading_h1_font_size: 24
+heading_h2_font_size: 18
+heading_h3_font_size: 16
+heading_h4_font_size: 14
+heading_h5_font_size: 12
+heading_h6_font_size: 10
+heading_line_height: 1.15
+heading_margin_top: 4
+heading_margin_bottom: 12
+title_page_align: center
+title_page_line_height: 1.15
+title_page_logo_top: 10%
+title_page_title_top: 40%
+title_page_title_font_size: 18
+title_page_subtitle_font_size: 14
+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_spacing: 4
+block_margin_top: 0
+block_margin_bottom: 12
+caption_align: left
+caption_font_style: italic
+caption_margin_inside: 4
+caption_margin_outside: 0
+abstract_font_size: 13.5
+abstract_line_height: 1.4
+abstract_padding: 0
+admonition_border_color: 'EEEEEE'
+admonition_border_width: 0.5
+admonition_padding: [0, 12, 0, 12]
+blockquote_border_color: 'EEEEEE'
+blockquote_border_width: 4
+blockquote_padding: [6, 12, -6, 14]
+code_font_family: Courier
+code_font_size: 10.5
+code_line_height: 1.2
+code_padding: 9
+code_border_color: 'EEEEEE'
+code_border_width: 0.5
+conum_line_height: 1.15
+example_border_color: 'EEEEEE'
+example_border_width: 0.5
+# FIXME reenable margin bottom once margin collapsing is implemented
+example_padding: [12, 12, 0, 12]
+image_align: left
+lead_font_size: 13.5
+lead_line_height: 1.4
+prose_margin_top: 0
+prose_margin_bottom: 12
+sidebar_background_color: 'EEEEEE'
+# FIXME reenable margin bottom once margin collapsing is implemented
+sidebar_padding: [12, 12, 0, 12]
+sidebar_title_align: center
+sidebar_title_font_style: bold
+table_border_color: '000000'
+table_border_width: 0.5
+table_cell_padding: 2
+table_head_font_style: bold
+thematic_break_border_color: 'EEEEEE'
+thematic_break_border_style: solid
+thematic_break_border_width: 0.5
+toc_indent: 15
+toc_line_height: 1.4

data/data/themes/default-theme.yml

@@ -1,33 +1,33 @@
 font:
   catalog:
+    # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
     Noto Serif:
-      normal: notoserif-regular-latin.ttf
-      bold: notoserif-bold-latin.ttf
-      italic: notoserif-italic-latin.ttf
-      bold_italic: notoserif-bolditalic-latin.ttf
+      normal: notoserif-regular-subset.ttf
+      bold: notoserif-bold-subset.ttf
+      italic: notoserif-italic-subset.ttf
+      bold_italic: notoserif-bold_italic-subset.ttf
+    # M+ 1mn supports ASCII and the circled numbers used for conums
     M+ 1mn:
       normal: mplus1mn-regular-ascii-conums.ttf
       bold: mplus1mn-bold-ascii.ttf
       italic: mplus1mn-italic-ascii.ttf
-      bold_italic: mplus1mn-bolditalic-ascii.ttf
+      bold_italic: mplus1mn-bold_italic-ascii.ttf
+    # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols
+    # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font
     M+ 1p Fallback:
-      normal: mplus1p-regular-multilingual.ttf
-      bold: mplus1p-regular-multilingual.ttf
-      italic: mplus1p-regular-multilingual.ttf
-      bold_italic: mplus1p-regular-multilingual.ttf
+      normal: mplus1p-regular-fallback.ttf
+      bold: mplus1p-regular-fallback.ttf
+      italic: mplus1p-regular-fallback.ttf
+      bold_italic: mplus1p-regular-fallback.ttf
   fallbacks:
-    # NOTE M+ 1p doesn't support all CJK characters, but it at least has some coverage
-    # NOTE M+ 1p provides the arrows for ->, <-, => and <=
     - M+ 1p Fallback
 page:
   background_color: ffffff
   layout: portrait
-  # NOTE multiply inches by 72 to get pt values
-  #margin: [0.5 * 72, 0.67 * 72, 0.67 * 72, 0.67 * 72]
   margin: [0.5in, 0.67in, 0.67in, 0.67in]
-  # size can be a named size (e.g., A4) or custom dimensions (e.g., [8.25in, 11.69in])
-  size: Letter
+  size: LETTER
 base:
+  align: justify
   # color as hex string (leading # is optional)
   font_color: 333333
   # color as RGB array
@@ -54,15 +54,16 @@ base:
   font_size_small: round($base_font_size * 0.85)
   font_size_min: $base_font_size * 0.75
   font_style: normal
-  align: justify
+  border_color: eeeeee
   border_radius: 4
   border_width: 0.5
-  border_color: eeeeee
 # FIXME vertical_rhythm is weird; we should think in terms of ems
 #vertical_rhythm: $base_line_height_length * 2 / 3
-# correct line height for Noto Serif metrics
+# correct line height for Noto Serif metrics (comes with built-in line height)
 vertical_rhythm: $base_line_height_length
 horizontal_rhythm: $base_line_height_length
+# QUESTION should vertical_spacing be block_spacing instead?
+vertical_spacing: $vertical_rhythm
 link:
   font_color: 428bca
 # literal is currently used for inline monospaced in prose and table cells
@@ -73,6 +74,7 @@ heading:
   #font_color: 181818
   font_color: $base_font_color
   font_family: $base_font_family
+  font_style: bold
   # h1 is used for part titles
   h1_font_size: floor($base_font_size * 2.6)
   # h2 is used for chapter titles
@@ -81,109 +83,110 @@ heading:
   h4_font_size: $base_font_size_large
   h5_font_size: $base_font_size
   h6_font_size: $base_font_size_small
-  font_style: bold
   #line_height: 1.4
-  # correct line height for Noto Serif metrics
+  # correct line height for Noto Serif metrics (comes with built-in line height)
   line_height: 1.2
   margin_top: $vertical_rhythm * 0.2
   margin_bottom: $vertical_rhythm * 0.8
 title_page:
   align: right
-  title_top: 55%
-  title_font_size: $heading_h1_font_size
-  title_font_color: 999999
-  title_line_height: 0.9
-  subtitle_font_size: $heading_h3_font_size
-  subtitle_font_style: bold_italic
-  subtitle_line_height: 1
-  authors_margin_top: $base_font_size * 1.25
-  authors_font_size: $base_font_size_large
-  authors_font_color: 181818
-  revision_margin_top: $base_font_size * 1.25
-#prose:
-#  margin_top: 0
-#  margin_bottom: $vertical_rhythm 
+  logo:
+    top: 10%
+  title:
+    top: 55%
+    font_size: $heading_h1_font_size
+    font_color: 999999
+    line_height: 0.9
+  subtitle:
+    font_size: $heading_h3_font_size
+    font_style: bold_italic
+    line_height: 1
+  authors:
+    margin_top: $base_font_size * 1.25
+    font_size: $base_font_size_large
+    font_color: 181818
+  revision:
+    margin_top: $base_font_size * 1.25
 block:
-  #margin_top: 0
-  #margin_bottom: $vertical_rhythm
-  padding: [$vertical_rhythm, $vertical_rhythm * 1.25, $vertical_rhythm, $vertical_rhythm * 1.25]
-# code is used for source blocks (perhaps change to source or listing?)
+  margin_top: 0
+  margin_bottom: $vertical_rhythm
 caption:
-  font_style: italic
   align: left
+  font_style: italic
   # FIXME perhaps set line_height instead of / in addition to margins?
-  margin_inside: $vertical_rhythm * 0.25
+  margin_inside: $vertical_rhythm / 3
+  #margin_inside: $vertical_rhythm / 4
   margin_outside: 0
+lead:
+  font_size: $base_font_size_large
+  line_height: 1.4
+abstract:
+  font_color: 5c6266
+  font_size: $lead_font_size
+  line_height: $lead_line_height
+  font_style: italic
+admonition:
+  border_color: $base_border_color
+  border_width: $base_border_width
+  padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm]
+blockquote:
+  font_color: $base_font_color
+  font_size: $base_font_size_large
+  border_color: $base_border_color
+  border_width: 5
+  padding: [$vertical_rhythm / 2, $horizontal_rhythm, $vertical_rhythm / -2, $horizontal_rhythm + $blockquote_border_width / 2]
+  cite_font_size: $base_font_size_small
+  cite_font_color: 999999
+# code is used for source blocks (perhaps change to source or listing?)
 code:
   font_color: $base_font_color
-  #font_family: Liberation Mono
-  #font_size: floor($base_font_size * 0.9)
-  #font_size: 10
-  #padding: [9.5, 9.5, 9.5, 9.5]
-  # LiberationMono carries extra gap below line
-  #padding: [10, 10, 7.5, 10]
-  #line_height: 1.45
   font_family: $literal_font_family
   font_size: ceil($base_font_size)
-  #padding: [$base_font_size, $code_font_size, $base_font_size, $code_font_size]
   padding: $code_font_size
   line_height: 1.25
   background_color: f5f5f5
   border_color: cccccc
   border_radius: $base_border_radius
   border_width: 0.75
-blockquote:
-  font_color: $base_font_color
-  font_size: $base_font_size_large
-  border_width: 5
-  border_color: $base_border_color
-  cite_font_size: $base_font_size_small
-  cite_font_color: 999999
-sidebar:
-  border_color: $page_background_color
-  border_radius: $base_border_radius
-  border_width: $base_border_width
-  background_color: eeeeee
-  title_font_color: $heading_font_color
-  title_font_family: $heading_font_family
-  title_font_size: $heading_h4_font_size
-  title_font_style: $heading_font_style
-  title_align: center
-example:
-  border_color: $base_border_color
-  border_radius: $base_border_radius
-  border_width: 0.75
-  background_color: transparent
-admonition:
-  border_color: $base_border_color
-  border_width: $base_border_width
 conum:
   font_family: M+ 1mn
   font_color: $literal_font_color
   font_size: $base_font_size
   line_height: 4 / 3
+example:
+  border_color: $base_border_color
+  border_radius: $base_border_radius
+  border_width: 0.75
+  background_color: transparent
+  # FIXME reenable margin bottom once margin collapsing is implemented
+  padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm]
 image:
-  align_default: left
-  scaled_width_default: 0.5
-lead:
-  # QUESTION what about $base_font_size_large?
-  #font_size: floor($base_line_height_length * 0.8)
-  #font_size: floor($base_font_size * 1.15)
-  #line_height: 1.3
-  font_size: $base_font_size_large
-  line_height: 1.4
-abstract:
-  #font_color: 404040
-  font_color: 5c6266
-  font_size: $lead_font_size
-  line_height: $lead_line_height
-  font_style: italic
+  align: left
+prose:
+  margin_top: 0
+  margin_bottom: $vertical_rhythm
+sidebar:
+  border_color: $page_background_color
+  border_radius: $base_border_radius
+  border_width: $base_border_width
+  background_color: eeeeee
+  # FIXME reenable margin bottom once margin collapsing is implemented
+  padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25]
+  title:
+    align: center
+    font_color: $heading_font_color
+    font_family: $heading_font_family
+    font_size: $heading_h4_font_size
+    font_style: $heading_font_style
 thematic_break:
   border_color: $base_border_color
+  border_style: solid
+  border_width: $base_border_width
   margin_top: $vertical_rhythm * 0.5
   margin_bottom: $vertical_rhythm * 1.5
 description_list:
   term_font_style: italic
+  term_spacing: $vertical_rhythm / 4
   description_indent: $horizontal_rhythm * 1.25
 outline_list:
   indent: $horizontal_rhythm * 1.5
@@ -194,6 +197,7 @@ table:
   background_color: $page_background_color
   #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>
   foot_background_color: f0f0f0
@@ -202,9 +206,9 @@ table:
   # HACK accounting for line-height
   cell_padding: [3, 3, 6, 3]
 toc:
-  indent: $horizontal_rhythm
   dot_leader_color: dddddd
-  #dot_leader_content: ". "
+  #dot_leader_content: '. '
+  indent: $horizontal_rhythm
   line_height: 1.4
 # NOTE In addition to footer, header is also supported
 footer:
@@ -214,9 +218,10 @@ footer:
   border_color: dddddd
   border_width: 0.25
   height: $base_line_height_length * 2.5
+  line_height: 1
   padding: [$base_line_height_length / 2, 1, 0, 1]
-  valign: top
-  #image_valign: <alignment> or <number>
+  vertical_align: top
+  #image_vertical_align: <alignment> or <number>
   # additional attributes for content:
   # * {page-count}
   # * {page-number}

data/docs/theming-guide.adoc

@@ -76,7 +76,7 @@ outline_list:
   indent: $base_font_size * 1.5
 ----
 
-When creating a new theme, you only have to define the keys you want to override from the base theme (PENDING, see https://github.com/asciidoctor/asciidoctor-pdf/issues/132[#132]).
+When creating a new theme, you only have to define the keys you want to override from the base theme, which is loaded prior to loading your custom theme.
 The converter uses the information from the theme map to help construct the PDF.
 All the available keys are documented in <<keys>>.
 
@@ -675,8 +675,8 @@ TBW
 |background_color: #ffffff
 
 |page_background_image
-|path (relative to pdf-stylesdir)
-|background_image: watermark.jpg
+|path (absolute or relative to pdf-stylesdir)
+|background_image: \image:watermark.png[]
 
 |page_layout
 |portrait, landscape +
@@ -879,13 +879,21 @@ The literal key is used for inline monospaced text in prose and table cells.
 |left, center, right, justify
 |align: right
 
+|title_page_background_color
+|<<colors,color>>
+|background_color: #eaeaea
+
+|title_page_background_image
+|path (absolute or relative to pdf-stylesdir)
+|background_image: \image:title.png[]
+
 |title_page_logo_align
 |left, center, right
 |logo_align: right
 
 |title_page_logo_image
 |inline image macro
-|+logo_image: image:logo.png[scaledwidth=25%]+
+|logo_image: \image:logo.png[scaledwidth=25%]
 
 |title_page_logo_top
 |percentage
@@ -936,6 +944,8 @@ The literal key is used for inline monospaced text in prose and table cells.
 |revision_margin_top: 13.125
 |===
 
+TIP: The title page can be disabled from the document by setting the `notitle` attribute in the document header.
+
 === Block
 
 [cols="3,3,5m"]
@@ -1190,9 +1200,9 @@ Block styles are applied to the following block types:
 |===
 |Key |Value Type |Example
 
-|image_align_default
-|left, center, right, justify
-|align_default: left
+|image_align
+|left, center, right
+|align: left
 |===
 
 === Lead
@@ -1302,6 +1312,10 @@ Block styles are applied to the following block types:
 |<<colors,color>>
 |background_color: #ffffff
 
+|table_head_background_color
+|<<colors,color>>
+|background_color: #f0f0f0
+
 |table_even_row_background_color
 |<<colors,color>>
 |even_row_background_color: #f9f9f9
@@ -1310,6 +1324,30 @@ Block styles are applied to the following block types:
 |<<colors,color>>
 |foot_background_color: #f0f0f0
 
+|table_header_cell_align
+|left, center, right
+|align: center
+
+|table_header_cell_background_color
+|<<colors,color>>
+|background_color: #f0f0f0
+
+|table_header_cell_font_color
+|<<colors,color>>
+|font_color: #1a1a1a
+
+|table_header_cell_font_family
+|<<fonts,font family name>>
+|font_family: Noto Sans
+
+|table_header_cell_font_size
+|<<values,number>>
+|font_size: 12
+
+|table_header_cell_font_style
+|normal, italic, bold, bold_italic
+|font_style: italic
+
 |table_border_color
 |<<colors,color>>
 |border_color: #dddddd
@@ -1414,17 +1452,22 @@ Block styles are applied to the following block types:
 |<<measurement-units,measurement>>
 |height: 0.75in
 
+|header_line_height
+|<<values,number>> +
+(default: $base_line_height)
+|height: 1.2
+
 |header_padding
 |<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
 |padding: [0, 3, 0, 3]
 
-|header_image_valign
-|top, center, bottom, <<measurement-units,measurement>>
-|image_valign: 4
+|header_image_vertical_align
+|top, middle, bottom, <<measurement-units,measurement>>
+|image_vertical_align: 4
 
-|header_valign
-|top, center, bottom
-|valign: center
+|header_vertical_align
+|top, middle, bottom
+|vertical_align: center
 
 |header_<side>_content_<align>^[1]^
 |quoted string
@@ -1467,17 +1510,22 @@ Block styles are applied to the following block types:
 |<<measurement-units,measurement>>
 |height: 0.75in
 
+|footer_line_height
+|<<values,number>> +
+(default: $base_line_height)
+|height: 1.2
+
 |footer_padding
 |<<measurement-units,measurement>>, <<measurement-units,measurement array [4]>>
 |padding: [0, 3, 0, 3]
 
-|footer_image_valign
-|top, center, bottom, <<measurement-units,measurement>>
-|image_valign: 4
+|footer_image_vertical_align
+|top, middle, bottom, <<measurement-units,measurement>>
+|image_vertical_align: 4
 
-|footer_valign
-|top, center, bottom
-|valign: top
+|footer_vertical_align
+|top, middle, bottom
+|vertical_align: top
 
 |footer_<side>_content_<align>^[1]^
 |quoted string
@@ -1489,6 +1537,10 @@ Block styles are applied to the following block types:
 
 IMPORTANT: You must define a height for the running header or footer, respectively, or it will not be shown.
 
+TIP: The running header and footer can be disabled from the document by setting the `noheader` and the `nofooter` attributes, respectively, in the document header.
+
+NOTE: If content is not specified for the running footer, the page number (i.e., `+{page-number}+`) will be shown on the left side on verso pages and the right side on recto pages.
+
 NOTE: The background color spans the width of the page.
 When a background color is specified, the border also spans the width of the page.
 
@@ -1510,12 +1562,32 @@ Here's an example that shows how these attributes can be used in the running foo
 ----
 footer:
   height: 0.75in
+  line_height: 1
   recto_content:
     right: '{section-or-chapter-title} | *{page-number}*'
   verso_content:
     left: '*{page-number}* | {chapter-title}'
 ----
 
+You can split the content value across multiple lines using YAML's multiline string syntax.
+In this case, the single quotes around the string are not necessary.
+To force a hard line break in the output, add [x-]+{space}{plus}+ to the end of the line in normal AsciiDoc fashion.
+
+[source,yaml]
+----
+footer:
+  height: 0.75in
+  line_height: 1.2
+  recto_content:
+    right: |
+      Section Title - Page Number +
+      {section-or-chapter-title} - {page-number}
+  verso_content:
+    left: |
+      Page Number - Chapter Title +
+      {page-number} - {chapter-title}
+----
+
 TIP: You can use most AsciiDoc inline formatting in the values of these keys.
 For instance, to make the text bold, surround it in asterisks (as shown above).
 One exception to this rule are inline images, which are described in the next section.
@@ -1532,13 +1604,13 @@ Here's an example of how to use an image in the running header (which also appli
 ----
 header:
   height: 0.75in
-  image_valign: 2 # <1>
+  image_vertical_align: 2 # <1>
   recto_content:
     center: image:footer-logo.png[width=80]
   verso_content:
     center: $header_recto_content_center
 ----
-<1> You can use the `footer_valign` attribute to slighly nudge the image up or down.
+<1> You can use the `footer_vertical_align` attribute to slighly nudge the image up or down.
 
 CAUTION: The image must fit in the allotted space for the running header or footer.
 Otherwise, you will run into layout issues.