asciidoctor-pdf 1.5.0.alpha.6 → 1.5.0.alpha.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5dc73c6c0fd12b13fd37b6a9001b0b085b3458f7
-  data.tar.gz: 03a98a738a9cf9703488a10380619b1f87812654
+  metadata.gz: 91cb53f52e412fd931bb3682852b067925666959
+  data.tar.gz: d0cd8e53ce01660fc2083acc816c817114c17ba1
 SHA512:
-  metadata.gz: 76147bac174cf98b029674ad882cb35dfb4df5ed9e69b33f1c3b5ab47993a77d9d7423e38d382ec4b6b834e6d3322ecccfb7b746f72a9031a424e6065bf857a2
-  data.tar.gz: 18e4f064a6af705f35ac64c03cf4b3c8850427314e97686ea834662d09507c55574613eb85eadb246cdb3f80bac4eb471b051b182991717a4dd970d181330e5d
+  metadata.gz: e1daccf26ee2383765fb921a184173b27331132579fd24775a353ac5f7fe639529d1155d6e0c5c38f31ff7ed52289c17ea19b9a11f39e51654dfa36685c7d570
+  data.tar.gz: a60d21046bb9653dc6a9c64e4f6720c4805732deb00d5c59ed8933d4369bb78f0a2b5e79194fd8b6e465a5deb9cfba35abb92e9735fd21f7169c9d1402a78562

data/README.adoc

@@ -5,37 +5,38 @@ Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://g
 :experimental:
 :idprefix:
 :idseparator: -
+ifdef::env-github[:relfileprefix: /blob/master]
+//:pdf-page-size: [8.25in, 11.69in]
+//:pdf-page-size: A4
 // Aliases:
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // URIs:
 :uri-project: https://github.com/asciidoctor/asciidoctor-pdf
-:uri-project-repo: 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
-:repo-base-uri: {uri-project-repo}/blob/master/
-ifdef::env-github[:repo-base-uri: link:]
-:uri-notice: {repo-base-uri}NOTICE.adoc
-:uri-license: {repo-base-uri}LICENSE.adoc
-:uri-worklog: {repo-base-uri}WORKLOG.adoc
+
+:original-outfilesuffix: {outfilesuffix}
+:outfilesuffix: .adoc
 
 _Lo and behold_, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! +
-_No more DocBook toolchain._ +
 _No more middleman._ +
-It's just AsciiDoc straight to PDF!
+_No more DocBook toolchain._ +
+It's AsciiDoc straight to PDF!
 
-.Project status
+[caption='Status']
 CAUTION: {project-name} is currently _alpha_ software.
-Use accordingly.
-Though the bulk of AsciiDoc content is converter, there's still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented.
-Once it's ready, the project will be moved into the Asciidoctor organization on GitHub.
+While it handles most of the 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
 
-{uri-project}[{project-name}] is made possible by the amazing Prawn RubyGem.
-_What a gem it is!_
+{uri-project}[{project-name}] is made possible by an amazing Ruby Gem named Prawn.
+And what a Gem it is!
 
 {uri-prawn}[Prawn] is a nimble PDF writer for Ruby.
 More important, it's a hackable platform that offers both high level APIs for the most common needs and low level APIs for bending the document model to accomodate special circumstances.
@@ -43,7 +44,7 @@ More important, it's a hackable platform that offers both high level APIs for th
 With Prawn, you can write text, draw lines and shapes and place images _anywhere_ on the page and add as much color as you like.
 In addition, it brings a fluent API and aggressive code re-use to the printable document space.
 
-To give you a picture, here's an example that shows how to use Prawn to create a basic PDF document.
+Here's an example that demonstrates how to use Prawn to create a basic PDF document.
 
 .Create a basic PDF document using Prawn
 [source,ruby]
@@ -56,13 +57,14 @@ end
 ----
 
 It's that easy.
-And it's just the beginning.
+And that's just the beginning.
+Skip ahead to <<Getting started>> to start putting it use.
 
-Simply put, *Prawn is the killer library for PDF generation* we've needed to close this critical gap in Asciidoctor.
+*Prawn is the killer library for PDF generation* we've needed to close this critical gap in Asciidoctor.
 It absolutely takes the pain out of creating printable documents.
 Picking up from there, {project-name} takes the pain out of creating printable documents _from AsciiDoc_.
 
-== Notable Features
+== Notable features
 
 * Direct AsciiDoc to PDF conversion
 * Configuration-driven style and layout
@@ -74,15 +76,15 @@ Picking up from there, {project-name} takes the pain out of creating printable d
 * Orphan section titles avoided
 * Table border settings honored
 
-=== Missing Features
+=== Missing features
 
-See {uri-worklog}[WORKLOG].
+See <<WORKLOG.adoc#,WORKLOG>>.
 
 == Prerequisites
 
 All that's needed is Ruby 1.9.3 or better (2.1.2 recommended) and a few RubyGems, which we explain how to install in the next section.
 
-To check you have Ruby available, use the +ruby+ command to query the version installed:
+To check you have Ruby available, use the `ruby` command to query the version installed:
 
  $ ruby --version
 
@@ -92,7 +94,7 @@ If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with
 
 We like RVM because it keeps the dependencies required by various projects isolated.
 
-== Getting Started
+== Getting started
 
 The {project-name} project is published in pre-release on RubyGems.org.
 You can either install the pre-release version using the following command:
@@ -104,7 +106,7 @@ To be safe, go ahead and install both gems:
 
  $ gem install coderay pygments.rb
 
-Assuming all the required gems install properly, verify you can run the +asciidoctor-pdf+ script:
+Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:
 
  $ asciidoctor-pdf -v
 
@@ -122,7 +124,7 @@ You can retrieve the {project-name} project in one of two ways:
 
 ==== Option 1: Fetch using git clone
 
-If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to +git clone+ command:
+If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to `git clone` command:
 
  $ git clone https://github.com/asciidoctor/asciidoctor-pdf
 
@@ -135,34 +137,42 @@ Next, change to the project directory:
 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.
 
-TIP: Instead of working out of the {project-handle} directory, you can simply add the absolute path of the [path]_bin_ directory to your +PATH+ environment variable.
+TIP: Instead of working out of the {project-handle} directory, you can simply add the absolute path of the [path]_bin_ directory to your `PATH` environment variable.
 
 We'll leverage the project configuration to install the necessary dependencies.
 
-=== Install the Dependencies
+=== Install the dependencies
 
 The dependencies needed to use {project-name} are defined in the [file]_Gemfile_ at the root of the project.
 We can use Bundler to install the dependencies for us.
 
-To check you have Bundler available, use the +bundle+ command to query the version installed:
+To check you have Bundler available, use the `bundle` command to query the version installed:
 
  $ bundle --version
 
-If it's not installed, use the +gem+ command to install it.
+If it's not installed, use the `gem` command to install it.
 
  $ gem install bundler
 
-Then use the +bundle+ command to install the project dependencies:
+Then use the `bundle` command to install the project dependencies:
 
  $ bundle
 
-Assuming all the required gems install properly, verify you can run the +asciidoctor-pdf+ script using Ruby:
+NOTE: You need to call `bundle` from the project directory so that it can find the [file]_Gemfile_.
+
+Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:
 
  $ ruby ./bin/asciidoctor-pdf -v
 
 If you see the version of Asciidoctor PDF printed, you're ready to use {project-name}!
 
-Let's grab an AsciiDoc document to distill.
+If you get an error message--and you're not using a Ruby manager like RVM--you may need to invoke the script through `bundle exec`:
+
+ $ bundle exec ./bin/asciidoctor-pdf -v
+
+If this works, be sure to use `bundle exec` whenever invoking the `./bin/asciidoctor-pdf` script.
+
+Next, let's grab an AsciiDoc document to distill.
 
 === Example AsciiDoc document
 
@@ -204,7 +214,7 @@ It's time to convert the AsciiDoc document directly to PDF.
 
 === Convert AsciiDoc to PDF
 
-Converting to PDF is a simple as running the +./bin/asciidoctor-pdf+ script using Ruby and passing our AsciiDoc document as the first argument.
+Converting to PDF is a simple as running the `./bin/asciidoctor-pdf` script using Ruby and passing our AsciiDoc document as the first argument.
 
  $ ruby ./bin/asciidoctor-pdf example.adoc
 
@@ -225,19 +235,21 @@ 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>>.
 
-See the files [file]_default-theme.yml_ and [file]_asciidoctor-theme.yml_ found in the [file]_data/themes_ directory for examples.
+You can use the built-in theme files, [file]_default-theme.yml_ and [file]_asciidoctor-theme.yml_, found in the [file]_data/themes_ directory, as examples.
 
-Specify the path to an alternate theme file with the `pdf-style` attribute. For example to use the built-in _asciidoctor_ theme:
+Specify the path to an alternate theme file with the `pdf-style` attribute.
+For example to use the built-in _asciidoctor_ theme:
 
  $ ./bin/asciidoctor-pdf -a pdf-style=asciidoctor examples/example.adoc
  
 To refer to a theme at another location you can use the `pdf-stylesdir` attribute to specify the location of themes.
 If the `pdf-style` value does not end in `.yml`, then the file name is calculated as `{pdf-style}-theme.yml` located in the `pdf-stylesdir` directory (which defaults to the built-in `data/themes` directory).
 
-== Optional Scripts
+== 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.
+{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.
 
 Here's an example usage:
@@ -246,14 +258,14 @@ Here's an example usage:
 
 The command will generate the file [file]_example-optimized.pdf_ in the current directory.
 
-WARNING: The +optimize-pdf+ script currently requires a Bash shell (Linux, OSX, etc).
+WARNING: The `optimize-pdf` script currently requires a Bash shell (Linux, OSX, etc).
 We plan to rewrite the script in Ruby so it works across platforms (see https://github.com/asciidoctor/asciidoctor-pdf/issues/1[issue #1])
 
-IMPORTANT: The +optimize-pdf+ script relies on Ghostscript >= 9.10.
+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 `.pdfmarks` 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 Asciidoctor PDF always creates this file in addition to the PDF.
 
@@ -263,7 +275,12 @@ In the spirit of free software, _everyone_ is encouraged to help improve this pr
 
 To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
 
-Feel free to use the {uri-project-issues}[issue tracker] or http://discuss.asciidoctor.org[Asciidoctor mailing list] to provide feedback or suggestions in other ways.
+Feel free to use the {uri-project-issues}[issue tracker] or {uri-project-list}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.
+
+[[resources,Links]]
+== Resources
+
+* https://groups.google.com/forum/#!msg/prawn-ruby/MbMsCx862iY/6ImCsvLGfVcJ[Discussion about image quality in PDFs]
 
 == Authors
 
@@ -274,5 +291,8 @@ Feel free to use the {uri-project-issues}[issue tracker] or http://discuss.ascii
 Copyright (C) 2014 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 {uri-license}[LICENSE] file.
-Refer to the {uri-notice}[NOTICE] file for information about third-party Open Source software in use.
+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.
+
+// FIXME Asciidoctor should be using outfilesuffix defined in header
+:outfilesuffix: {original-outfilesuffix}

data/bin/asciidoctor-pdf

@@ -5,8 +5,9 @@ require 'asciidoctor/cli'
 
 options = Asciidoctor::Cli::Options.new backend: 'pdf', header_footer: true
 # FIXME This is a really bizarre API. Please make me simpler.
-if (options.parse! ARGV) == 0
-  exit 0
+result = options.parse! ARGV
+if Integer === result
+  exit result
 else
   invoker = Asciidoctor::Cli::Invoker.new options
   GC.start

data/data/themes/default-theme.yml

@@ -5,34 +5,36 @@ font:
       bold: notoserif-bold-latin.ttf
       italic: notoserif-italic-latin.ttf
       bold_italic: notoserif-bolditalic-latin.ttf
-    # NOTE currently, callout numbers don't work with LiberationMono
-    #LiberationMono:
-    #  normal: liberationmono-regular-latin.ttf
-    #  bold: liberationmono-bold-latin.ttf
-    #  italic: liberationmono-italic-latin.ttf
-    #  bold_italic: liberationmono-bolditalic-latin.ttf
     Mplus1mn:
       normal: mplus1mn-regular-ascii-conums.ttf
       bold: mplus1mn-bold-ascii.ttf
       italic: mplus1mn-italic-ascii.ttf
       bold_italic: mplus1mn-bolditalic-ascii.ttf
-    #Mplus1pMultilingual:
-    #  normal: mplus1p-regular-multilingual.ttf
-    #FontAwesome:
-    #  normal: fontawesome-regular.ttf
-  # FIXME using fallbacks breaks use of custom font styles (fixed in Prawn 1.2.1!)
-  #fallbacks:
-  #  - Mplus1pMultilingual
-brand:
-  primary_color: 428bca
+    Mplus1pMultilingual:
+      normal: mplus1p-regular-multilingual.ttf
+      bold: mplus1p-regular-multilingual.ttf
+      italic: mplus1p-regular-multilingual.ttf
+      bold_italic: mplus1p-regular-multilingual.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 <=
+    - Mplus1pMultilingual
 page:
   background_color: ffffff
   layout: portrait
-  # multiply inches by 72 to get pt values
-  margin: [0.5 * 72, 0.67 * 72, 0.67 * 72, 0.67 * 72]
+  # 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
 base:
+  # color as hex string (leading # is optional)
   font_color: 333333
+  # color as RGB array
+  #font_color: [51, 51, 51]
+  # color as CMYK array (approximated)
+  #font_color: [0, 0, 0, 0.92]
+  #font_color: [0, 0, 0, 92%]
   font_family: NotoSerif
   # choose one of these font_size/line_height_length combinations
   #font_size: 14
@@ -60,24 +62,43 @@ base:
 # correct line height for NotoSerif metrics
 vertical_rhythm: $base_line_height_length
 horizontal_rhythm: $base_line_height_length
-link_font_color: $brand_primary_color
+link:
+  font_color: 428bca
+# literal is currently used for inline monospaced in prose and table cells
+literal:
+  font_color: b12146
+  font_family: Mplus1mn
 heading:
+  #font_color: 181818
   font_color: $base_font_color
   font_family: $base_font_family
-  # h1 is used for document title
-  font_size_h1: floor($base_font_size * 2.6)
-  # h2 is used for chapter title
-  font_size_h2: floor($base_font_size * 2.15)
-  font_size_h3: round($base_font_size * 1.7)
-  font_size_h4: $base_font_size_large
-  font_size_h5: $base_font_size
-  font_size_h6: $base_font_size_small
+  # h1 is used for part titles
+  h1_font_size: floor($base_font_size * 2.6)
+  # h2 is used for chapter titles
+  h2_font_size: floor($base_font_size * 2.15)
+  h3_font_size: round($base_font_size * 1.7)
+  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 NotoSerif metrics
   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 
@@ -86,6 +107,12 @@ block:
   #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?)
+caption:
+  font_style: italic
+  align: left
+  # FIXME perhaps set line_height instead of / in addition to margins?
+  margin_inside: $vertical_rhythm * 0.25
+  margin_outside: 0
 code:
   font_color: $base_font_color
   #font_family: LiberationMono
@@ -95,7 +122,7 @@ code:
   # LiberationMono carries extra gap below line
   #padding: [10, 10, 7.5, 10]
   #line_height: 1.45
-  font_family: Mplus1mn
+  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
@@ -104,11 +131,6 @@ code:
   border_color: cccccc
   border_radius: $base_border_radius
   border_width: 0.75
-# literal is currently used for inline monospaced in prose and table cells
-literal:
-  #font_color: c7254e
-  font_color: b12146
-  font_family: $code_font_family
 blockquote:
   font_color: $base_font_color
   font_size: $base_font_size_large
@@ -123,7 +145,7 @@ sidebar:
   background_color: eeeeee
   title_font_color: $heading_font_color
   title_font_family: $heading_font_family
-  title_font_size: $heading_font_size_h4
+  title_font_size: $heading_h4_font_size
   title_font_style: $heading_font_style
   title_align: center
 example:
@@ -134,16 +156,11 @@ example:
 admonition:
   border_color: $base_border_color
   border_width: $base_border_width
-caption:
-  font_style: italic
-  align: left
-  # FIXME perhaps set line_height instead of / in addition to margins?
-  margin_inside: $vertical_rhythm * 0.25
-  margin_outside: 0
 conum:
   font_family: Mplus1mn
   font_color: $literal_font_color
-  font_size: $code_font_size
+  font_size: $base_font_size
+  line_height: 4 / 3
 image:
   align_default: left
   scaled_width_default: 0.5
@@ -168,15 +185,50 @@ description_list:
   term_font_style: italic
   description_indent: $horizontal_rhythm * 1.25
 outline_list:
-  indent: $horizontal_rhythm * 1.25
+  indent: $horizontal_rhythm * 1.5
+  # NOTE item_spacing applies to list items that do not have complex content
+  item_spacing: $vertical_rhythm / 2
 table:
-  background_color: transparent
-  background_color_alt: f9f9f9
+  background_color: ffffff
+  #head_background_color: <hex value>
+  #head_font_color: $base_font_color
+  even_row_background_color: f9f9f9
+  #odd_row_background_color: <hex value>
+  foot_background_color: f0f0f0
   border_color: dddddd
   border_width: $base_border_width
   # HACK accounting for line-height
   cell_padding: [3, 3, 6, 3]
+toc:
+  indent: $horizontal_rhythm
+  dot_leader_color: dddddd
+  #dot_leader_content: ". "
+  line_height: 1.4
+# NOTE In addition to footer, header is also supported
 footer:
   font_size: $base_font_size_small
   font_color: $base_font_color
+  # NOTE if background_color is set, background and border will span width of page
   border_color: dddddd
+  border_width: 0.25
+  height: $base_line_height_length * 2.5
+  padding: [$base_line_height_length / 2, 1, 0, 1]
+  valign: top
+  #image_valign: <alignment> or <number>
+  # additional attributes for content:
+  # * {page-count}
+  # * {page-number}
+  # * {document-title}
+  # * {document-subtitle}
+  # * {chapter-title}
+  # * {section-title}
+  # * {section-or-chapter-title}
+  recto_content:
+    #right: '{section-or-chapter-title} | {page-number}'
+    #right: '{document-title} | {page-number}'
+    right: '{page-number}'
+    #center: '{page-number}'
+  verso_content:
+    #left: '{page-number} | {chapter-title}'
+    left: '{page-number}'
+    #center: '{page-number}'