asciidoctor-pdf 1.5.0.alpha.18 → 1.5.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fed971e3655c6b460cdf90ba7205802ad7060710287123a36df56b1e75dd8257
-  data.tar.gz: 888b1ef50e7e690bab7661ee0b10d35671376e85352389ccc8f1bf6b11798cfc
+  metadata.gz: 032a48f8d8cda0a29e3e7c3249cb2c74aaccc0f910adcb4607ef30733b70b948
+  data.tar.gz: 1e995ab8292dedab7deef06867f5da0ca41570be9abe88e6be81af999fe4965b
 SHA512:
-  metadata.gz: e29597fcbbb5c7cc2b822ad5844f0d656fc5890a1b6fb062511f9fb88a68204d5cde0f98b897b9f448c24897c53a9b221328a53ec8ef2f922f769d9f707153ed
-  data.tar.gz: a0275c1a8cee51ccbcf69102d47508f892784637ed0727a4c507c7d3f538b632aa2e87430e23146c7b93a295a95e4057f794f3b7693a1891517106f16c20b563
+  metadata.gz: 945a1f3e02ee7c08e7a08f5566dc9bf79aac394674f44665285cf40f7fbaf1bd16c2b2d491b37ad467a5e718c23fa311e245b46f4d46de3f1fe54badf83a69e9
+  data.tar.gz: e3d6c083f0b4ecf716a2264127f523f4a8febfa0a2915838c31f67a4d2cf5201b2178d15a5e6b057528bad4d7b5f685cbc69a8dcaa44538359d2a27532ab8a4c

data/CHANGELOG.adoc

@@ -5,6 +5,50 @@
 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.beta.1 (2019-07-08) - @mojavelinux
+
+* rename pdf-style and pdf-stylesdir attributes to pdf-theme and pdf-themesdir, respectively (while still honoring the old names for compatibility) (#1127)
+* don't load fallback font by default; move fallback font to default-with-fallback-font theme
+* apply cell padding to table cells in the head row (#1098)
+* allow the theme to control the padding of table cells in the head row using the table_head_cell_padding key (#1098)
+* fix position of table caption for reduced-width tables when caption align is center (#1138)
+* adjust width of table caption to match width of table unless table_caption_max_width is none in theme (#1138)
+* fix position of text in running header (#1087)
+* ignore start attribute on ordered list if marker is disabled
+* allow start value to be negative for ordered lists that use arabic or roman numbering (#498)
+* don't convert values in theme which are not color keys to a string (#1089)
+* apply page layout specified on page break even when break falls page boundary (#1091)
+* scale SVG background image to fit page in the same way raster image is scaled (#765)
+* allow page background size to be controlled using image macro attributes (#1117)
+* allow page background image position to be controlled using position attribute on image macro (#1124)
+* add support for fit=cover for cover page, page background, and running content images (#1136)
+* change default background image position to center (#1124)
+* allow cover image position to be controlled using position attribute on image macro (#1134)
+* change default cover image position to center (#1134)
+* set enable_file_requests_with_root and enable_web_requests options for all SVGs (#683)
+* automatically set pdf-stylesdir if pdf-style ends with .yml and pdf-stylesdir is not specified (#1126)
+* replace hyphens with underscores in top-level theme keys
+* allow hyphens to be used in variable references in theme (#1122)
+* allow theme to control background and border of inline code (literal) (#306)
+* allow theme to control background and border of inline button (#451)
+* resolve null color value in theme to nil (aka not set)
+* add support for cgi-style options on source language when syntax highlighting with Rouge (#1102)
+* apply custom theme to chronicles example to customize running content and demonstrate how to extend default theme
+* drop remapping of legacy running content keys in theme data
+* resize running content to fit page layout (#1036)
+* exclude border width from running content area (#1109)
+* support text-transform property in running content (#702)
+* make depth of section titles assigned to section-title attribute in running content configurable (#1141)
+* support width attribute on image in running content if no other dimension attribute is specified
+* apply correct scale-down logic to image in running content
+* allow image format to be specified using format attribute (cover page image, page background image, running content image) (#1132)
+* allow theme to set bottom border properties (color, style, and width) of table head row (#770)
+* allow column rule and spacing to be specified for running content when multiple columns are specified (#1093)
+* never load base theme when loading default theme; otherwise load base theme if extends isn't specified, but only if theme data hasn't been initialized
+* shorten text-alignment attribute to text-align
+* set PDF version to 1.4 by default (#302)
+* allow PDF version to be set using pdf-version document attribute (#302)
+
 == 1.5.0.alpha.18 (2019-06-01) - @mojavelinux
 
 * restore compatibility with Asciidoctor back to 1.5.3 and add verification to test matrix (#1038)
@@ -45,6 +89,7 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 * add support for nbsp named entity (i.e., `+ `); replace occurances of nbsp named entity with a single space in outline
 * upgrade to FontAwesome 5; introduce the fas, far, and fab icon sets, now preferred over fa; drop support for octicons (#891) (@jessedoyle)
 * place footnotes at end of chapters in books or end of document otherwise (#85) (@bcourtine)
+* fix rendering of footnotes directly adjacent to text in a normal table cell (#927)
 * place toc directly after document title when doctype is not book (#233) (@ogmios-voice)
 * add page layout control to page break (#490) (@resort-diaper)
 * allow additional style properties to be set per heading level (#176) (@billybooth)

data/NOTICE.adoc

@@ -1,7 +1,7 @@
 = Asciidoctor PDF
 OpenDevise Inc.; Asciidoctor Project
 
-Copyright (C) 2014-2016 OpenDevise Inc. and the Asciidoctor Project.
+Copyright (C) 2014-2019 OpenDevise Inc. and the Asciidoctor Project.
 
 Please visit the Asciidoctor project site for more information:
 
@@ -26,7 +26,7 @@ M+ OUTLINE FONTS (M+ TESTFLIGHT 058)::
 
   - http://mplus-fonts.sourceforge.jp/mplus-outline-fonts/index-en.html
 
-Noto Serif Font (v2014-01-30)::
+Noto Serif Font (v2015-06-05)::
   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 headings and body copy and is bundled in the PDF file.
   The Noto fonts are licensed under the Apache 2.0 License.
@@ -36,7 +36,7 @@ Noto Serif Font (v2014-01-30)::
 
   - https://code.google.com/p/noto/
 
-Font Awesome Icon Font (v4.0.3)::
+Font Awesome Icon Font (v5.4)::
   Font Awesome (@fontawesome), the iconic font designed for Bootstrap by David Gandy (@davegandy), is used for the admonition icons and other icons in author's content and bundled in the PDF file.
   Font Awesome is fully open source and GPL compatible.
   The font is licensed under the SIL Open Font 1.1 License (OFL).
@@ -46,14 +46,6 @@ Font Awesome Icon Font (v4.0.3)::
 
   - http://fontawesome.io
 
-Liberation Fonts (v2.00.1)::
-  The Liberation(tm) Fonts 2.00.1, which are used by default, are licensed under the SIL Open Font License, Version 1.1.
-  You may obtain a copy of the license at:
-
-  http://scripts.sil.org/OFL
-
-  - https://fedorahosted.org/liberation-fonts 
-
 RomanNumeral class::
   The RomanNumeral class, which is used for numbering of ordered lists, is borrowed from the roman-numerals RubyGem and modified for the purpose of this application.
   The original RomanNumerals class was written by Andrew Vos and is licensed under the MIT License.
@@ -74,3 +66,14 @@ Bootstrap (v3.0.3)::
   The default theme is inspired by Bootstrap 3.0.3.
 
   - http://getbootstrap.com
+
+spec/fixtures/cover.jpg::
+  Attribution: Dominicus Johannes Bergsma; License: Creative Commons Attribution-Share Alike 3.0 Unported
+  This file is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported license.
+
+  - https://commons.wikimedia.org/wiki/File:Dahlia_%27Bishop_of_Auckland.JPG
+
+spec/fixtures/tux.png::
+  Attribution: Larry Ewing, Simon Budig, Garrett LeSage; License: Creative Commons CC0 1.0 Universal Public Domain Dedication
+
+  - https://commons.wikimedia.org/wiki/File:Tux.svg

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.18, 2019-06-01
+v1.5.0.beta.1, 2019-07-08
 // Settings:
 :experimental:
 :idprefix:
@@ -24,7 +24,7 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.0.alpha.18
+:release-version: 1.5.0.beta.1
 // URIs:
 :uri-asciidoctor: http://asciidoctor.org
 :uri-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -100,7 +100,7 @@ endif::[]
 == Highlights
 
 * Direct AsciiDoc to PDF conversion
-* <<docs/theming-guide#,Configuration-driven style and layout>>
+* <<docs/theming-guide#,Configuration-driven theme (style and layout)>>
 * SVG support
 * PDF document outline (i.e., bookmarks)
 * Table of contents page(s)
@@ -392,12 +392,11 @@ In this case, the image is scaled down to fit on a single page.
 If you want a block image to align to the boundaries of the page (not the content margin), specify the `align-to-page` option (e.g., `opts="align-to-page"`).
 This is most useful when using vw units because you can make the image cover the entire width of the page.
 
-Images in running content also support the `fit` attribute.
+Images in running content and page background images also support the `fit` attribute (when specified using the image macro).
 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.
+If sizing information is not specified for a page background image, the image is automatically scaled to fit the bounds of the page (i.e., `fit=contain`).
 
 === Using the pdfwidth Attribute
 
@@ -490,7 +489,7 @@ To perform this work, Asciidoctor delegates to the underlying libraries.
 {uri-prawn-svg}[prawn-svg] brings support for SVG images.
 Without any additional libraries, those are the only supported image file formats.
 
-If you need support for additional image formats, such as GIF, TIFF, or interlaced PNG--and you don't want to convert those images to a supported format--you must install the {uri-prawn-gmagick}[prawn-gmagick] Ruby gem.
+If you need support for additional image formats, such as GIF, TIFF, or interlaced PNG--and you don't want to convert those images to a supported format--you must install the {uri-prawn-gmagick}[prawn-gmagick] (>= 0.0.9) Ruby gem.
 prawn-gmagick is an extension for Prawn based on {uri-graphicsmagick}[GraphicsMagick] that adds support for all the image formats recognized by that library.
 prawn-gmagick has the added benefit of significantly reducing the time it takes to generate a PDF containing a lot of images.
 
@@ -503,23 +502,25 @@ In addition to support for more additional image file formats, this gem also spe
 
 == STEM Support
 
-Unlike the built-in HTML converter, Asciidoctor PDF does not provide native support for STEM blocks and inline macros.
-That's because Asciidoctor core doesn't actually process STEM equations.
-In the HTML output, Asciidoctor relies on the JavaScript-based MathJax library to parse and render the equations in the browser.
-All the HTML converter does is wrap the equations so MathJax is able to find them.
+Unlike the built-in HTML converter, Asciidoctor PDF does not provide native support for STEM blocks and inline macros (i.e., asciimath and latexmath).
+That's because Asciidoctor core doesn't process the STEM content itself.
+It just passes it through to the converter.
+In the HTML output, Asciidoctor relies on the JavaScript-based MathJax library to parse and render the equations in the browser when the page is loaded.
+The HTML converter simply wraps the equations in special markup so MathJax can find them.
 
 In order to insert a rendered equation into the PDF, the toolchain has to parse the equations and convert them to a format the PDF writer (Prawn) can understand.
 That typically means converting to an image.
 
-The recommended solution is an extension named Asciidoctor Mathematical, which we'll cover here.
-Another solution still under development uses Mathoid to convert STEM equations to images.
-Mathoid is a library that invokes MathJax using a headless browser.
+The recommended solution is an extension named Asciidoctor Mathematical, which we'll cover in this document.
+
+Another solution, which is still under development, uses Mathoid to convert STEM equations to images.
+Mathoid is a library that invokes MathJax using a headless browser, so it supports both asciimath and latexmath equations.
 That prototype can be found in the https://github.com/asciidoctor/asciidoctor-extensions-lab#extension-catalog[Asciidoctor extensions lab].
 
 === Asciidoctor Mathematical
 
-{uri-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros.
-After the document has been parsed, the extension locates all the STEM blocks and inline macros, converts the equations to images using Mathematical, then replaces them with image nodes.
+{uri-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros (currently only latexmath).
+After the document has been parsed, the extension locates all the latexmath blocks and inline macros, converts the equations to images using Mathematical, then replaces them with image nodes.
 Conversion then proceeds as normal.
 
 Asciidoctor Mathematical is a Ruby gem that uses native extensions.
@@ -627,6 +628,20 @@ Therefore, to print a range of pages as they are labeled in the document, you ne
 For example, if you only want to print the first 5 pages labeled with a page number (e.g., 1-5), and there are 2 pages before the page labeled as page 1, you need to add 2 to both numbers in the range, giving you a physical page range of 3-7.
 That's the range you need to enter into the print dialog.
 
+== Title Page
+
+Unlike other converters, the PDF converter introduces a dedicated title page at the start of the document.
+The title page contains the doctitle, author, date, and revision info.
+If a front cover image is specified, the title page comes after the front cover.
+The title page can be styled using the theme and/or reserved page attributes.
+
+The title page is enabled if either of these conditions are met:
+
+* The document has the `book` doctype.
+* The `title-page` attribute is set (with an empty value) in the document header.
+
+When the title page is enabled, the table of contents (aka TOC) also gets is own page (or pages, if necessary).
+
 == Table of Contents
 
 The table of contents (TOC) is not included by default.
@@ -661,28 +676,56 @@ The only restriction is that no index terms may be defined below this section.
 NOTE: Although the catalog is generated automatically, you have to mark the index terms manually.
 However, you could use an extension, such as a TreeProcessor, to automatically mark index terms.
 
-== Optional Scripts
+== Optimizing the Generated PDF
+
+=== optimize-pdf
 
-{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 uses 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:
 
  $ ./bin/optimize-pdf basic-example.pdf
 
-The command will generate the file [.path]_example-optimized.pdf_ in the current directory.
+The command will generate the file [.path]_basic-example-optimized.pdf_ in the same directory.
 
 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.
-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 `.pdfmark` 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.
 
+IMPORTANT: The `optimize-pdf` script relies on Ghostscript >= 9.10.
+Otherwise, it may actually make the PDF larger.
+You should probably only consider using it if the file size of the original PDF is > 5MB.
+
+=== hexapdf
+
+Another option to optimize the PDF is https://hexapdf.gettalong.org/[hexapdf] (gem: hexapdf, command: hexapdf).
+Before introducing it, though, it's important to point out that its license is AGPL.
+If that's okay with you, read on to learn how to use it.
+
+First, install the hexapdf gem using the following command:
+
+ $ gem install hexapdf
+
+You can then use it to optimize your PDF as follows:
+
+ $ hexapdf optimize --compress-pages --force basic-example.pdf basic-example-optimized.pdf
+
+This command does not manipulate the images in any way.
+It merely compresses the objects in the PDF and prunes any unreachable references.
+But given how much waste Prawn leaves behind, this turns out to reduce the file size significantly.
+
+To see more options, run:
+
+ $ hexapdf help optimize
+
+For example, to make the source of the PDF a bit more readable, set the stream-related options to `preserve`.
+
+hexapdf also allows you to add password protection to your PDF, if that's something you're interested in doing.
+
 ifndef::env-site[]
 == Contributing
 
@@ -761,6 +804,10 @@ To disable the visual integration tests, pass the `` option:
 
  $ bundle exec rspec -t ~integration
 
+If a visual integration test fails, you can instruct the test suite to keep the files in the [.path]_spec/output_ directory by setting the `DEBUG` environment variable:
+
+ $ DEBUG=true bundle exec rspec -t integration
+
 If you want to see the name of each test as it is run, add the `-fd` option:
 
  $ bundle exec rspec -fd
@@ -774,11 +821,15 @@ Running tests using `rspec` directly gives you the advantage of being able to sp
 To run a single test, you can filter by the name of the test.
 For example, to run all tests that pertain to failures, use:
 
- $ bundle exec rspec -e fail -fd
+ $ bundle exec rspec -e fail
+
+To run all tests that have `wip` in the name, use:
+
+ $ bundle exec rspec -e wip
 
 You can also run all tests in a given file by passing the file's path to rspec:
 
- $ bundle exec rspec -fd spec/toc_spec.rb
+ $ bundle exec rspec spec/toc_spec.rb
 
 For a full list of options that rspec provides, run `rspec -h`.
 

data/asciidoctor-pdf.gemspec

@@ -48,6 +48,8 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'treetop', '~> 1.5.0'
 
   s.add_development_dependency 'rake', '~> 12.3.0'
+  # Asciidoctor PDF supports Rouge >= 2; Rouge 3.4.1 emits a superfluous warning in verbose mode
+  s.add_development_dependency 'rouge', '~> 3.4.0', '!= 3.4.1'
   s.add_development_dependency 'rspec', '~> 3.8.0'
   s.add_development_dependency 'pdf-inspector', '~> 1.3.0'
   s.add_development_dependency 'chunky_png', '~> 1.3.0'

data/data/themes/base-theme.yml

@@ -21,6 +21,9 @@ base_line_height: 1.15
 base_line_height_length: 13.8
 base_border_color: 'EEEEEE'
 base_border_width: 0.5
+button_content: '[%s]'
+button_font_family: Courier
+button_font_style: bold
 link_font_color: '0000EE'
 literal_font_family: Courier
 heading_font_style: bold
@@ -91,6 +94,7 @@ table_border_style: solid
 table_border_width: 0.5
 table_cell_padding: 2
 table_head_font_style: bold
+table_head_border_bottom_width: 1.25
 table_body_stripe_background_color: 'EEEEEE'
 thematic_break_border_color: 'EEEEEE'
 thematic_break_border_style: solid

data/data/themes/default-theme.yml

@@ -12,15 +12,6 @@ font:
       bold: mplus1mn-bold-ascii.ttf
       italic: mplus1mn-italic-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-fallback.ttf
-      bold: mplus1p-regular-fallback.ttf
-      italic: mplus1p-regular-fallback.ttf
-      bold_italic: mplus1p-regular-fallback.ttf
-  fallbacks:
-  - M+ 1p Fallback
 page:
   background_color: ffffff
   layout: portrait
@@ -67,13 +58,17 @@ vertical_rhythm: $base_line_height_length
 horizontal_rhythm: $base_line_height_length
 # QUESTION should vertical_spacing be block_spacing instead?
 vertical_spacing: $vertical_rhythm
+button:
+  content: "[\u2009%s\u2009]"
+  font_style: bold
 link:
   font_color: 428bca
 # literal is currently used for inline monospaced in prose and table cells
 literal:
   font_color: b12146
   font_family: M+ 1mn
-menu_caret_content: " <font size=\"1.15em\"><color rgb=\"b12146\">\u203a</color></font> "
+menu:
+  caret_content: " <font size=\"1.15em\"><color rgb=\"b12146\">\u203a</color></font> "
 heading:
   align: left
   #font_color: 181818
@@ -173,7 +168,7 @@ code:
   border_radius: $base_border_radius
   border_width: 0.75
 conum:
-  font_family: M+ 1mn
+  font_family: $literal_font_family
   font_color: $literal_font_color
   font_size: $base_font_size
   line_height: 4 / 3
@@ -219,15 +214,16 @@ outline_list:
   item_spacing: $vertical_rhythm / 2
 table:
   background_color: $page_background_color
-  #head_background_color: <hex value>
-  #head_font_color: $base_font_color
-  head_font_style: bold
-  #body_background_color: <hex value>
-  body_stripe_background_color: f9f9f9
-  foot_background_color: f0f0f0
   border_color: dddddd
   border_width: $base_border_width
   cell_padding: 3
+  head:
+    font_style: bold
+    border_bottom_width: $base_border_width * 2.5
+  body:
+    stripe_background_color: f9f9f9
+  foot:
+    background_color: f0f0f0
 toc:
   indent: $horizontal_rhythm
   line_height: 1.4
@@ -238,7 +234,10 @@ toc:
 footnotes:
   font_size: round($base_font_size * 0.75)
   item_spacing: $outline_list_item_spacing / 2
-# NOTE in addition to footer, header is also supported
+header:
+  font_size: $base_font_size_small
+  line_height: 1
+  vertical_align: middle
 footer:
   font_size: $base_font_size_small
   # NOTE if background_color is set, background and border will span width of page
@@ -248,27 +247,11 @@ footer:
   line_height: 1
   padding: [$base_line_height_length / 2, 1, 0, 1]
   vertical_align: top
-  #image_vertical_align: <alignment> or <number>
-  # additional attributes for content:
-  # * {page-count}
-  # * {page-number}
-  # * {document-title}
-  # * {document-subtitle}
-  # * {chapter-title}
-  # * {section-title}
-  # * {section-or-chapter-title}
   recto:
     #columns: "<50% =0% >50%"
     right:
       content: '{page-number}'
-      #content: '{section-or-chapter-title} | {page-number}'
-      #content: '{document-title} | {page-number}'
-    #center:
-    #  content: '{page-number}'
   verso:
     #columns: $footer_recto_columns
     left:
       content: $footer_recto_right_content
-      #content: '{page-number} | {chapter-title}'
-    #center:
-    #  content: '{page-number}'