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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 91cb53f52e412fd931bb3682852b067925666959
-  data.tar.gz: d0cd8e53ce01660fc2083acc816c817114c17ba1
+  metadata.gz: 2b2c65350b1794de68fc1396284903bb5e15efde
+  data.tar.gz: 29a3cfea5ef7f61d77e241518d1b26440c1f58cc
 SHA512:
-  metadata.gz: e1daccf26ee2383765fb921a184173b27331132579fd24775a353ac5f7fe639529d1155d6e0c5c38f31ff7ed52289c17ea19b9a11f39e51654dfa36685c7d570
-  data.tar.gz: a60d21046bb9653dc6a9c64e4f6720c4805732deb00d5c59ed8933d4369bb78f0a2b5e79194fd8b6e465a5deb9cfba35abb92e9735fd21f7169c9d1402a78562
+  metadata.gz: a6e7506596f8d5446e9275a00f916648f336c69543d372680a4d11d77065676de4dd7721b429d49e585386639ff3d9c7eaaca776040a0afc4f1e107e1d6e98eb
+  data.tar.gz: 173008d8b6d048722150da22616202c118f2d46929cc67f1b4ea097e0dd8b02b8fe7f13f0a6d1a933709844ad736af1eabbc1dc49c28f1315e1fea3e4e9e137c

data/NOTICE.adoc

@@ -19,7 +19,7 @@ See the License for the specific language governing permissions and limitations
 == Third-party licensed work
 
 M+ OUTLINE FONTS (M+ TESTFLIGHT 058)::
-  The M+ OUTLINE FONTS are used for section titles, literal text and code annotation numbers and bundled in the EPUB3 archive.
+  The M+ OUTLINE FONTS are used for literal text, annotation numbers and fallback characters and are bundled in the PDF file.
   These fonts are free software and are designed and maintained by Coji Morishita.
   Unlimited permission is granted to use, copy, and distribute them, with or without modification, either commercially or noncommercially.
   THESE FONTS ARE PROVIDED "AS IS" WITHOUT WARRANTY.
@@ -28,7 +28,7 @@ M+ OUTLINE FONTS (M+ TESTFLIGHT 058)::
 
 Noto Serif Font (v2014-01-30)::
   Noto is font family developed by the Google Internationalization Team that aims to support all the world's languages.
-  The Noto Serif font is used for body copy and bundled in the EPUB3 archive.
+  The Noto Serif font is used for headings and body copy and is bundled in the PDF file.
   The Noto fonts are licensed under the Apache 2.0 License.
   You may obtain a copy of the license at:
 

data/README.adoc

@@ -1,11 +1,14 @@
-= Asciidoctor PDF: A _native_ PDF converter for AsciiDoc
+= Asciidoctor PDF: A native PDF converter for AsciiDoc
 Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
 // Settings:
 :compat-mode!:
 :experimental:
 :idprefix:
 :idseparator: -
+:icons: font
+:pagenums:
 ifdef::env-github[:relfileprefix: /blob/master]
+ifdef::env-browser[:toc: preamble]
 //:pdf-page-size: [8.25in, 11.69in]
 //:pdf-page-size: A4
 // Aliases:
@@ -20,6 +23,7 @@ ifdef::env-github[:relfileprefix: /blob/master]
 :uri-rvm: http://rvm.io
 :uri-asciidoctor: http://asciidoctor.org
 
+// FIXME See last line; Asciidoctor should only be using outfilesuffix defined in header
 :original-outfilesuffix: {outfilesuffix}
 :outfilesuffix: .adoc
 
@@ -28,15 +32,15 @@ _No more middleman._ +
 _No more DocBook toolchain._ +
 It's AsciiDoc straight to PDF!
 
-[caption='Status']
+[caption=Status]
 CAUTION: {project-name} is currently _alpha_ software.
-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.
+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
 
-{uri-project}[{project-name}] is made possible by an amazing Ruby Gem named Prawn.
-And 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.
@@ -51,30 +55,37 @@ Here's an example that demonstrates how to use Prawn to create a basic PDF docum
 ----
 require 'prawn'
 
-Prawn::Document.generate 'example.pdf' do
+Prawn::Document.generate 'output.pdf' do
   text 'Hello, PDF creation!'
 end
 ----
 
 It's that easy.
 And that's just the beginning.
-Skip ahead to <<Getting started>> to start putting it use.
+Skip ahead to <<getting-started,Getting started>> to start putting it use.
 
-*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_.
+Picking up from there, {project-name} takes the pain out of creating PDF documents _from AsciiDoc_.
 
-== Notable features
+== Features
+
+=== Notable features
 
 * Direct AsciiDoc to PDF conversion
-* Configuration-driven style and layout
+* <<docs/theming-guide.adoc#,Configuration-driven style and layout>>
 * 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
-* Page breaks avoided in block content
+* Page numbering
+* Customizable running content (header and footer)
+* “Keep together” blocks (i.e., page breaks avoided in certain block content)
 * Orphan section titles avoided
 * Table border settings honored
+* Font-based icons (currently admonition blocks only)
+* Custom fonts
 
 === Missing features
 
@@ -82,200 +93,188 @@ 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.
+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.
 
-To check you have Ruby available, use the `ruby` command to query the version installed:
+[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:
 
- $ ruby --version
+  $ gem install prawn --version 1.3.0
 
-If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with Asciidoctor and {project-name}:
+You can then proceed with installation of Asciidoctor PDF.
+====
 
- $ rvm use 2.1@asciidoctor-pdf --create
+To check you have Ruby available, use the `ruby` command to query the version installed:
 
-We like RVM because it keeps the dependencies required by various projects isolated.
+ $ ruby --version
 
 == 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:
+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
+
+{project-name} is published in pre-release on RubyGems.org.
+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.
-To be safe, go ahead and install both gems:
+If you want to syntax highlight source listings, you'll also want to install CodeRay (or Pygments).
 
- $ gem install coderay pygments.rb
+ $ gem install coderay
 
 Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:
 
  $ asciidoctor-pdf -v
 
-If you see the version of Asciidoctor PDF printed, you're ready to use {project-name}!
-
-Skip ahead to the <<example-asciidoc-document>> section to start putting {project-name} to use.
-Alternatively, you can follow the steps below to install the project from source.
-
-=== Retrieve the source code
-
-You can retrieve the {project-name} project in one of two ways:
-
-. Clone the git repository
-. Download a zip archive of the repository
-
-==== Option 1: Fetch using git clone
+If you see the version of {project-name} printed, you're ready to use {project-name}.
 
-If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to `git clone` command:
+Let's grab an AsciiDoc document to distill and start putting {project-name} to use!
 
- $ git clone https://github.com/asciidoctor/asciidoctor-pdf
+=== An example AsciiDoc document
 
-Next, change to the project directory:
+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.
 
- $ cd asciidoctor-pdf
+ifeval::[{safe-mode-level} >= 20]
+See <<examples/basic-example.adoc#,basic-example.adoc>>.
+endif::[]
+ifeval::[{safe-mode-level} < 20]
+.basic-example.adoc
+[source,asciidoc]
+....
+include::examples/basic-example.adoc[]
+....
+endif::[]
 
-==== Option 2: Download the archive
+It's time to convert the AsciiDoc document directly to PDF.
 
-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.
+=== Convert AsciiDoc to PDF
 
-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.
+IMPORTANT: You'll need to the `coderay` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `coderay`.
 
-We'll leverage the project configuration to install the necessary dependencies.
+Converting to PDF is a simple as running the `asciidoctor-pdf` script using Ruby and passing our AsciiDoc document as the first argument.
 
-=== Install the dependencies
+ $ asciidoctor-pdf basic-example.adoc
 
-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.
+This command is just a shorthand way of running:
 
-To check you have Bundler available, use the `bundle` command to query the version installed:
+ $ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc
 
- $ bundle --version
+When the script completes, you should see the file [file]_basic-example.pdf_ in the same directory.
+Open the [file]_basic-example.pdf_ file with a PDF viewer to see the result.
 
-If it's not installed, use the `gem` command to install it.
+.Example PDF document rendered in a PDF viewer
+image::examples/example-pdf-screenshot.png[Screenshot of PDF document,width=800,scaledwidth=100%]
 
- $ gem install bundler
+You're also encouraged to try converting this <<README#,README>> as well as the documents in the examples directory to see more of what {project-name} can do.
 
-Then use the `bundle` command to install the project dependencies:
+The pain of the DocBook toolchain should be melting away about now.
 
- $ bundle
+== Themes
 
-NOTE: You need to call `bundle` from the project directory so that it can find the [file]_Gemfile_.
+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.
 
-Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:
+== Optional scripts
 
- $ ruby ./bin/asciidoctor-pdf -v
+{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.
 
-If you see the version of Asciidoctor PDF printed, you're ready to use {project-name}!
+Here's an example usage:
 
-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`:
+ $ ./bin/optimize-pdf basic-example.pdf
 
- $ bundle exec ./bin/asciidoctor-pdf -v
+The command will generate the file [file]_example-optimized.pdf_ in the current directory.
 
-If this works, be sure to use `bundle exec` whenever invoking the `./bin/asciidoctor-pdf` script.
+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])
 
-Next, let's grab an AsciiDoc document to distill.
+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.
 
-=== Example AsciiDoc 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 {project-name} always creates this file in addition to the PDF.
 
-If you don't already have an AsciiDoc document, you can use the [file]_example.adoc_ file found in the examples directory of this project.
+== Contributing
 
-.example.adoc
-[source,asciidoc]
-....
-= Document Title
-Doc Writer <doc@example.com>
-:doctype: book
-:source-highlighter: coderay
-:listing-caption: Listing
+In the spirit of free software, _everyone_ is encouraged to help improve this project.
 
-A simple http://asciidoc.org[AsciiDoc] document.
+To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
 
-== Introduction
+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.
 
-A paragraph followed by a simple list with square bullets.
+== Development
 
-[square]
-* item 1
-* item 2
+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.
 
-Here's how you say "`Hello, World!`" in Prawn:
+=== Retrieve the source code
 
-.Create a basic PDF document using Prawn
-[source,ruby]
-----
-require 'prawn'
+You can retrieve the source of {project-name} in one of two ways:
 
-Prawn::Document.generate 'example.pdf' do
-  text 'Hello, World!'
-end
-----
-....
+. Clone the git repository
+. Download a zip archive of the repository
 
-It's time to convert the AsciiDoc document directly to PDF.
+==== Option 1: Fetch using git clone
 
-=== Convert AsciiDoc to PDF
+If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to `git clone` command:
 
-Converting to PDF is a simple as running the `./bin/asciidoctor-pdf` script using Ruby and passing our AsciiDoc document as the first argument.
+ $ git clone https://github.com/asciidoctor/asciidoctor-pdf
 
- $ ruby ./bin/asciidoctor-pdf example.adoc
+Next, change to the project directory:
 
-When the script completes, you should see the file [file]_example.pdf_ in the same directory.
+ $ cd asciidoctor-pdf
 
-IMPORTANT: You'll need to the `coderay` gem installed to run this example since it uses the `source-highlighter` attribute with the value of `coderay`.
+==== Option 2: Download the archive
 
-Open the [file]_example.pdf_ file with a PDF viewer to see the result.
+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.
 
-.Example PDF document rendered in a PDF viewer
-image::examples/example-pdf-screenshot.png[Screenshot of PDF document,width=800,scaledwidth=100%]
+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.
 
-You're also encouraged to try converting this link:README.adoc[README] as well as the documents in the examples directory to see more of what {project-name} can do.
-Another good example is the https://github.com/cdi-spec/cdi/tree/master/spec[CDI Specification].
+We'll leverage the project configuration to install the necessary dependencies.
 
-The pain of the DocBook toolchain should be melting away about now.
+=== Install dependencies
 
-== Themes
+If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:
 
-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>>.
+ $ rvm use 2.2@asciidoctor-pdf --create
 
-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.
+We like RVM because it keeps the dependencies required by various projects isolated.
 
-Specify the path to an alternate theme file with the `pdf-style` attribute.
-For example to use the built-in _asciidoctor_ theme:
+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.
 
- $ ./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).
+To check you have Bundler available, use the `bundle` command to query the version installed:
 
-== Optional scripts
+ $ bundle --version
 
-{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.
+If it's not installed, use the `gem` command to install it.
 
-Here's an example usage:
+ $ gem install bundler
 
- $ ./bin/optimize-pdf example.pdf
+Then use the `bundle` command to install the project dependencies:
 
-The command will generate the file [file]_example-optimized.pdf_ in the current directory.
+ $ bundle
 
-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])
+NOTE: You need to call `bundle` from the project directory so that it can find the [file]_Gemfile_.
 
-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.
+Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:
 
-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.
+ $ ruby ./bin/asciidoctor-pdf -v
 
-== Contributing
+or
 
-In the spirit of free software, _everyone_ is encouraged to help improve this project.
+ $ bundle exec ./bin/asciidoctor-pdf -v
 
-To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
+If you see the version of {project-name} printed, you're ready to use {project-name}!
 
-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.
+CAUTION: 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`:
+For best results, be sure to always use `bundle exec` whenever invoking the `./bin/asciidoctor-pdf` script in development mode.
 
 [[resources,Links]]
 == Resources

data/Rakefile

@@ -8,13 +8,14 @@ default_tasks = []
 begin
   require 'bundler/gem_tasks'
 
+  # Enhance the release task to create an explicit commit for the release
+  #Rake::Task[:release].enhance [:commit_release]
+
+  # NOTE you don't need to push after updating version and committing locally
   task :commit_release do
     Bundler::GemHelper.new.send :guard_clean
     sh %(git commit --allow-empty -a -m 'Release #{Asciidoctor::Pdf::VERSION}')
   end
-
-  # Enhance the release task to create an explicit commit for the release
-  Rake::Task[:release].enhance [:commit_release]
 rescue LoadError
 end
 
@@ -22,7 +23,7 @@ begin
   require 'rdoc/task'
   Rake::RDocTask.new do |t|
     t.rdoc_dir = 'rdoc'
-    t.title = %(Asciidoctor EPUB3 #{Asciidoctor::Pdf::VERSION})
+    t.title = %(Asciidoctor PDF #{Asciidoctor::Pdf::VERSION})
     t.main = %(README.adoc)
     t.rdoc_files.include 'README.adoc', 'LICENSE.adoc', 'NOTICE.adoc', 'lib/**/*.rb', 'bin/**/*'
   end

data/bin/asciidoctor-pdf

@@ -4,9 +4,22 @@ require_relative '../lib/asciidoctor-pdf'
 require 'asciidoctor/cli'
 
 options = Asciidoctor::Cli::Options.new backend: 'pdf', header_footer: true
+
+# FIXME provide an API in Asciidoctor for sub-components to print version information
+unless ARGV != ['-v'] && (ARGV & ['-V', '--version']).empty?
+  $stdout.write %(Asciidoctor PDF #{Asciidoctor::Pdf::VERSION} using )
+  # NOTE the print_version method was added in Asciidoctor 1.5.2
+  if options.respond_to? :print_version
+    options.print_version
+  else
+    puts %(Asciidoctor #{::Asciidoctor::VERSION} [http://asciidoctor.org])
+  end
+  exit 0
+end
+
 # FIXME This is a really bizarre API. Please make me simpler.
-result = options.parse! ARGV
-if Integer === result
+case (result = options.parse! ARGV)
+when Integer
   exit result
 else
   invoker = Asciidoctor::Cli::Invoker.new options