asciidoctor-pdf 1.5.0.beta.2 → 1.5.0.beta.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39073eb8a1bb2d5cac70b6909884e9c7e28813919295d5058c4471ea5805f103
-  data.tar.gz: e527403b220a3969d0398e9a6e3b4e3101fb9a55eafe9dacbe429b6abd8399ee
+  metadata.gz: a069bf48fbe99050934610c30657128be8730eb5efcfc05cb63501374e904fbd
+  data.tar.gz: b2975922d3e8da6f7da239285fab79d285ec1a57b3870af130aa248c01475445
 SHA512:
-  metadata.gz: 15142864ee5aa1ab97c6ec2c5c82793532528b10ebe093a3af8514c313c0c3f06b4a3aabc2c1d246546991332a6de7bd8772843373fd715a96b4d38d5f563228
-  data.tar.gz: 3c3d20aebe612eb3869fc5f38b8af536e5bb51ea95765cbe1c61515e36d03e0d62dbe97262629b581524a6d8783cb886c8bfc4832c6e5b4dab0dd3a4e4624a17
+  metadata.gz: 005bb7e4b493d6adae9b3fef48b94caeacea1a84e47ae5209c0562a5d9ba10131a71cba011b35f1f09de57850ccea7fe5456d1d59906f0a76d2a3a63e70f4c7f
+  data.tar.gz: ea0f6d4a02d5ef32e4fb467e8793e1b4da458391eca2f678d0dbc1e9a52c22987843b1ebf6260d41cb4ae27780f6cde686a2c64bda24817ac83e978a8050a83c

data/CHANGELOG.adoc

@@ -5,6 +5,47 @@
 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.3 (2019-08-30) - @mojavelinux
+
+* allow multiple font dirs to be specified using the pdf-fontsdir attribute (#80)
+* fill and stroke bounds of example across all pages (#362)
+* allow page background color and background image to be used simultaneously (#1186)
+* allow theme to specifiy initial zoom (#305)
+* strip surrounding whitespace from text in normal table cells
+* allow attribute references to be used in image paths in theme (#588)
+* resolve variables in font catalog in theme file
+* honor the cellbgcolor attribute defined in a table cell to set the cell background color (#234) (*mch*)
+* add the .notdef glyph to the bundled fonts (a box which is used as the default glyph if the font is missing a character) (#1194)
+* don't drop headings if base font family is not set in theme
+* don't crash if heading margins are not set in theme
+* don't rely on base_line_height_length theme key in converter (should be internal to theme)
+* set fallback value for base (root) font size
+* reduce min font size in base theme
+* allow theme to configure the minimum height required after a section title for it to stay on same page (#1210)
+* convert hyphen to underscore in theme key for admonition icon type (#1217)
+* always resolve images in running content relative to themesdir (instead of document) (#1183)
+* fix placement of toc in article when doctitle is not set (#1240)
+* honor text alignment role on abstract paragraph(s)
+* don't insert blank page at start of document if media=prepress and document does not have a cover (#1181)
+* insert blank page after cover if media=prepress (#1181)
+* add support for stretch role on table (as preferred alias for spread) (#1225)
+* include revremark on title page if specified (#1198)
+* allow theme to configure border around block image (#767)
+* align first block of list item with marker if primary text is blank (#1196)
+* apply correct margin to list item if primary text is blank (#1196)
+* allow page break before and after part and before chapter to be configured by theme (#74)
+* allow page number of PDF to import to be specified using `page` attribute on image macro (#1202)
+* use value of theme key heading-margin-page-top as top margin for heading if cursor is at top of page (#576)
+* resolve icon image relative to docdir instead of current working directory
+* allow theme to style mark element; add default styles to built-in themes (#1226)
+* if value of scripts attribute is cjk, break lines between any two CJK characters (except punctuation) (#1206)
+* add support for role to font-based icon (to change font color) (#349)
+* use fallback size for admonition icon
+* allow attribute reference in running content to be escaped using a backslash
+* allow theme to configure text background and border on a phrase with a custom role (#1223)
+* fix crash if source-highlighter attribute is defined outside the header (#1231)
+* fix crash when aligning line numbers of source highlighted with Pygments (#1233)
+
 == 1.5.0.beta.2 (2019-07-30) - @mojavelinux
 
 * only apply title page background image to the title page (#1144)

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.beta.2, 2019-07-30
+v1.5.0.beta.3, 2019-08-30
 // Settings:
 :experimental:
 :idprefix:
@@ -24,7 +24,7 @@ endif::[]
 :project-name: Asciidoctor PDF
 :project-handle: asciidoctor-pdf
 // Variables:
-:release-version: 1.5.0.beta.2
+:release-version: 1.5.0.beta.3
 // URIs:
 :uri-asciidoctor: http://asciidoctor.org
 :uri-gem: http://rubygems.org/gems/asciidoctor-pdf
@@ -58,11 +58,6 @@ _No more middleman._ +
 _No more DocBook toolchain._ +
 It's AsciiDoc straight to PDF!
 
-[caption=Status]
-CAUTION: {project-name} is currently _alpha_ software.
-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.
-
 toc::[]
 
 == Prawn, the Majestic PDF Generator
@@ -148,9 +143,11 @@ ifndef::env-site[You can also <<development,run the code from source>> if you wa
 
 === Install the Published Gem
 
-{project-name} is published as a pre-release on RubyGems.org.
-First, make sure you have satisfied the <<Prerequisites,prerequisites>>.
-Then, you can install the published gem using the following command:
+{project-name} is published to RubyGems.org as a pre-release.
+Since it's in pre-release, you have to specify the `--pre` flag when installing using the `gem` command.
+
+To install {project-name}, first make sure you have satisfied the <<Prerequisites,prerequisites>>.
+Then, install the gem from RubyGems.org using the following command:
 
  $ gem install asciidoctor-pdf --pre
 
@@ -329,17 +326,19 @@ To find a complete list of available icons, consult the https://github.com/jesse
 
 == Image Paths
 
-Relative images paths are resolved relative to the value of the `imagesdir` attribute at the time the converter is run.
+Relative images paths in the document are resolved relative to the value of the `imagesdir` attribute (at the time the converter runs).
 This is effectively the same as how the built-in HTML converter works when the `data-uri` attribute is set.
 The `imagesdir` is blank by default, which means relative images paths are resolved relative to the input document.
+Relative images paths in the theme are resolved relative to the value of the `pdf-themesdir` attribute (which defaults to the directory of the theme file).
+The `imagesdir` attribute is not used when resolving an image path in the theme file.
 Absolute image paths are used as is.
 
 If the image is an SVG, and the SVG includes a nested raster image (PNG or JPG) with a relative path, that path is resolved relative to the directory that contains the SVG.
 
-The converter will refuse to include an image if the target is a URI unless the `allow-uri-read` attribute is enabled via the CLI or API.
+The converter will refuse to embed an image if the target is a URI (including image references in an SVG) unless the `allow-uri-read` attribute is enabled via the CLI or API.
 
-If the image is an SVG and that SVG links to another image, the linked image will be resolved using the same rules as the original image.
-However, note that a width and height must be specified on the linked image or else the SVG library will fail to process it.
+If you use a linked image in an SVG, the width and height of that image must be specified.
+Otherwise, the SVG library will fail to process it.
 
 === Asciidoctor Diagram Integration
 
@@ -358,7 +357,7 @@ Keep in mind that this strategy may introduce other side effects you'll have to
 Since PDF is a fixed-width canvas, you almost always need to specify a width to get the image to fit properly on the page.
 There are five ways to specify the width of an image, listed here in order of precedence:
 
-[cols="1s,3d"]
+[cols="1s,3"]
 |===
 |Attribute{nbsp}Name | Description
 
@@ -385,7 +384,7 @@ If the width exceeds the content area width, the image is scaled down to the con
 |If you don't specify one of the aforementioned width settings, the intrinsic width of the image is used (the px value is multiplied by 75% to convert to pt, assuming canvas is 96 dpi) unless the width exceeds the content area width, in which case the image is scaled down to the content area width.
 |===
 
-The image is always sized according to the explicit or intrinsic width and its height is scaled proportionally.
+The image is always sized according to the explicit or intrinsic width, then its height is scaled proportionally.
 The height of the image is ignored by the PDF converter unless the height of the image exceeds the content height of the page.
 In this case, the image is scaled down to fit on a single page.
 
@@ -442,6 +441,72 @@ Once the resolved height exceeds this amount, the height of the line is increase
 In this case, the surrounding text will be aligned to the bottom of the image.
 If the image height exceeds the height of the page, the image will be scaled down to fit on a single page (this may cause the image to advance to the subsequent page).
 
+=== Background Image Sizing
+
+In addition to the width-related attributes previously covered, background images can be sized relative to the page using the `fit` attribute of the image macro.
+The `fit` attribute works similarly to the `object-fit` property in CSS.
+It's value must be specified as a single keyword, chosen from the table below.
+The starting size of the image is determined by the explicit width, if specified, or the implicit width.
+The height is always derived from with width, respecting the implicit aspect ratio of the image.
+The available space for a background image (i.e., the canvas) is the page.
+
+[cols="1s,3"]
+|===
+| Value | Purpose
+
+| contain
+| The image is scaled up or down while retaining its aspect ratio to fit within the available space.
+
+| cover
+| The image is scaled up or down while retaining its aspect ratio so the image completely covers the available space, even if it means the image must be clipped in one direction.
+
+| scale-down
+| The image is scaled down while retaining its aspect ratio to fit within the available space.
+If the image already fits, it is not scaled.
+
+| none
+| The image is not scaled.
+|===
+
+The `fit` attribute is often combined with the `position` attribute, covered next, to control the placement of the image on the canvas.
+
+== Background Image Positioning
+
+In addition to scaling, background images for cover pages, content pages, and the title page support positioning via the `position` attribute.
+The `position` attribute accepts a syntax similar to the `background-position` property in CSS, except only the keyword positions are supported.
+The position consists of two values, the vertical position and the horizontal position (e.g., `top center`).
+If only one value is specified (e.g., `top`), the other value is assumed to be `center`.
+If the `position` attribute is not specified, the value is assumed to be `center center` (i.e., the image is centered on the page).
+
+The following table provides a list of the vertical and horizontal positioning keywords that are supported.
+You can use any combination of these keywords to position the image.
+
+|===
+| Vertical Positions | Horizontal Positions
+
+| top +
+center +
+bottom
+
+| left +
+center +
+right
+|===
+
+Here's an example of how to place a background image at the top center of every page:
+
+----
+:page-background-image: image:bg.png[pdfwidth=50%,position=top]
+----
+
+Here's how to move it to the bottom right:
+
+----
+:page-background-image: image:bg.png[pdfwidth=50%,position=bottom right]
+----
+
+If an image dimension matches the height or width of the page, the positioning keyword for that axis has no effect.
+
 == Fonts in SVG Images
 
 Asciidoctor PDF uses {uri-prawn-svg}[prawn-svg] to embed SVGs in the PDF document, including SVGs generated by Asciidoctor Diagram.
@@ -500,6 +565,123 @@ Please refer to the {uri-prawn-gmagick}[README for prawn-gmagick] to learn how t
 Once this gem is installed, Asciidoctor automatically switches over to it to handle embedding of all images.
 In addition to support for more additional image file formats, this gem also speeds up image processing considerably, so we highly recommend using it if you can.
 
+== Importing PDF Pages
+
+In addition to using a PDF page for the front or back cover, you can also insert a PDF page at an arbitrary location.
+This technique is useful to include pages that have complex layouts and graphics prepared in a specialized design program (such as Inkscape), which would otherwise not be achievable using this converter.
+One such example is an insert such as an advertisement or visual interlude.
+
+To import the first page from a PDF file, use the block image macro with the PDF filename as the image target.
+
+[source,asciidoc]
+----
+image::custom-page.pdf[]
+----
+
+By default, this macro will import the first page of the PDF.
+To import a different page, specify it as a 1-based index using the `page` attribute.
+
+[source,asciidoc]
+----
+image::custom-page.pdf[page=2]
+----
+
+To import multiple pages, you'll need to use multiple image macros, each specifying the page number to import.
+
+CAUTION: An image macro that imports a PDF page should never be nested inside a delimited block or table.
+It should be a direct descendant of the document or a section.
+Otherwise, the behavior is unspecified.
+
+The converter will insert the page from the PDF as a dedicated page that matches the size and layout of the page being imported (no matter where the block image occurs).
+Therefore, there's no need to put a manual page break (i.e., `<<<`) around the image macro.
+
+To see a practical example of how to use this feature, refer to the blog post https://fromplantoprototype.com/blog/2019/08/07/importing-pdf-pages-in-asciidoctor-pdf/[Importing PDF Pages in asciidoctor-pdf].
+
+== Crafting Interdocument Xrefs
+
+This converter produces a single PDF file, which means content from multiple source documents get colocated into the same output file.
+That means references between documents must necessarily become internal references.
+These interdocument cross references (i.e., xrefs) will only successfully make that transition if you structure your document in accordance with the rules.
+
+Those rules are as follows:
+
+. The path segment of the interdocument xref must match the project-relative path of the included document
+. The reference must include the ID of the target element
+
+For instance, if your primary document contains the following include:
+
+[source,asciidoc]
+----
+\include::chapters/chapter-1.adoc[]
+----
+
+Then an interdocument xref to an anchor in that chapter must be expressed as:
+
+[source,asciidoc]
+----
+<<chapters/chapter-1.adoc#_anchor_name,Destination in Chapter 1>>
+----
+
+This rule holds regardless of which document the xref is located in.
+
+To resolve the interdocument xref, the converter first checks if the target matches the `docname` attribute.
+It then looks to see if the target matches one of the included files.
+(In both cases, it ignores the file extension).
+If Asciidoctor cannot resolve the target of an interdocument xref, it simply makes a link (like the HTML converter).
+
+Let's consider a complete example.
+Assume you are converting the following book document at the root of the project:
+
+[source,asciidoc]
+----
+= Book Title
+:doctype: book
+
+\include::chapters/chapter-1.adoc[]
+
+\include::chapters/chapter-2.adoc[]
+----
+
+Where the contents of chapter 1 is as follows:
+
+[source,asciidoc]
+----
+== Chapter 1
+
+We cover a little bit here.
+The rest you can find in <<chapters/chapter-2.adoc#_chapter_2,Chapter 2>>.
+----
+
+And the contents of chapter 2 is as follows:
+
+[source,asciidoc]
+----
+== Chapter 2
+
+Prepare to be educated.
+This chapter has it all!
+
+To begin, jump to <<chapters/chapter-2/first-steps.adoc#_first_steps,first steps>>.
+
+<<<
+
+\include::chapter-2/first-steps.adoc[]
+----
+
+And, finally, the contents of the nested include is as follows:
+
+[source,asciidoc]
+----
+=== First Steps
+
+Let's start small.
+----
+
+You'll find when you run this example that all the interdocument xrefs become internal references in the PDF.
+
+The reason both the path and anchor are required (even when liking to the top of a chapter) is so the interdocument xref works independent of the converter.
+In other words, it encodes the complete information about the reference so the converter can sort out where the target is in all circumstances.
+
 == STEM Support
 
 Unlike the built-in HTML converter, Asciidoctor PDF does not provide native support for STEM blocks and inline macros (i.e., asciimath and latexmath).
@@ -590,10 +772,11 @@ Therefore, the long lines are forced to wrap.
 Wrapped lines can make the verbatim blocks hard to read or even cause confusion.
 
 To help address this problem, Asciidoctor PDF provides the `autofit` option on all verbatim (i.e., literal, listing and source) blocks to attempt to fit the text within the available width.
-When the `autofit` option is enabled, Asciidoctor PDF will decrease the font size until the longest line fits without wrapping.
+When the `autofit` option is enabled, Asciidoctor PDF will decrease the font size (as much as it can) until the longest line fits without wrapping.
 
-CAUTION: The font size will not be decreased beyond the value of the `base_font_size_min` key specified in the PDF theme.
+CAUTION: The converter will not shrink the font size beyond the value of the `base_font_size_min` key specified in the PDF theme.
 If that threshold is reached, lines may still wrap.
+To allow `autofit` to handle all cases, set `base_font_size_min` to `0` in your theme.
 
 Here's an example of the autofit option enabled on a source block:
 
@@ -895,6 +1078,38 @@ To switch back to master, just type:
 
  $ git checkout master
 
+=== Generate Code Coverage Report
+
+To generate a code coverage report when running tests using simplecov, set the `COVERAGE` environment variable as follows when running the tests:
+
+ $ COVERAGE=true bundle exec rake spec
+
+You'll see a total coverage score as well as a link to the HTML report in the output.
+The HTML report helps you understand which lines and branches were missed, if any.
+
+Despite being fast, the downside of using simplecov is that it misses code branches.
+You can use deep-cover instead of simplecov to generate a more thorough report.
+To do so, set the `COVERAGE` environment variable to `deep` when running the tests:
+
+ $ COVERAGE=deep bundle exec rake spec
+
+You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
+The HTML report helps you understand which lines and branches were missed, if any.
+
+////
+As an alternative to deep cover's native HTML reporter, you can also use istanbul / nyc.
+First, you'll need to have the `nyc` command available on your system:
+
+ $ npm install -g nyc
+
+Next, in addition to the `COVERAGE` environment variable, also set the `DEEP_COVER_REPORTER` environment variable as follows when running the tests:
+
+ $ COVERAGE=deep DEEP_COVER_REPORTER=istanbul bundle exec rake spec
+
+You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
+The HTML report helps you understand which lines and branches were missed, if any.
+////
+
 [[resources,Links]]
 == Resources
 

data/asciidoctor-pdf.gemspec

@@ -48,9 +48,12 @@ 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 (verified in CI build using 2.0.0)
-  s.add_development_dependency 'rouge', '~> 3.6.0'
+  s.add_development_dependency 'deep-cover-core', '~> 0.7.0'
+  s.add_development_dependency 'simplecov', '~> 0.17.0'
   s.add_development_dependency 'rspec', '~> 3.8.0'
   s.add_development_dependency 'pdf-inspector', '~> 1.3.0'
+  # Asciidoctor PDF supports Rouge >= 2 (verified in CI build using 2.0.0)
+  s.add_development_dependency 'rouge', '~> 3.6.0'
+  s.add_development_dependency 'coderay', '~> 1.1.0'
   s.add_development_dependency 'chunky_png', '~> 1.3.0'
 end

data/data/fonts/ABOUT-mplus1mn-subset

@@ -7,6 +7,7 @@ The following changes were made using fontforge to produce mplus1mn-*-ascii.ttf
  ** Basic Latin (U+0020–U+007e)
  ** Enclosed Numbers (U+2460–U+2473, U+2776–U+277f, U+24eb–U+24f4) (M+ 1mn Regular only)
  ** Box Drawing Symbols (U+2500–U+257f)
+ ** .notdef glyph
 * Subsetted to include (subset variant):
  ** Non-visible Characters (U+00a0)
  ** Basic Latin (U+0020–U+007e)
@@ -17,6 +18,7 @@ The following changes were made using fontforge to produce mplus1mn-*-ascii.ttf
  ** Assorted Symbols (U+20ac)
  ** Enclosed Numbers (U+2460–U+2473, U+2776–U+277f, U+24eb–U+24f4) (mplus1mn-regular only)
  ** Box Drawing Symbols (U+2500–U+257f)
+ ** .notdef glyph
 * Added BOM (U+feff) and line feed (U+000a) characters (from blank)
 * Generated old-style kern table (neither Apple or OpenType) (required to make kerning work in Prawn) (flags: 0x90)
 * Removed Truetype instructions (information not used by Prawn) (flags: 0x08)

data/data/fonts/ABOUT-mplus1p-subset

@@ -17,6 +17,7 @@ The following changes were made using fontforge to produce mplus1p-regular-fallb
  ** General Punctuation (U+2000–U203a)
  ** Geometric Shapes (U+25a0–U25ff)
  ** Assorted Symbols (U+20ac, U+2122, U+21d0–U+21d5, U+2190–U+2195, U+2610–U+2611, U+2713)
+ ** .notdef glyph
 * Added BOM (U+feff), hair space (U+200a), zero-width space (U+200b) and line feed (U+000a) characters (from blank)
 * Manually added non-breaking hyphen (U+2011) from hyphen (U+002d)
 * Generated old-style kern table (neither Apple or OpenType) (required to make kerning work in Prawn) (flags: 0x90)

data/data/fonts/ABOUT-notoserif-subset

@@ -17,6 +17,7 @@ The following changes were made using fontforge to produce the notoserif-*-subse
  ** General Punctuation (U+2000–U203a)
  ** Geometric Shapes (U+25a0–U25ff)
  ** Assorted Symbols (U+20ac, U+2122, U+21d0, U+21d2, U+2190, U+2192)
+ ** .notdef glyph
 * Imported ballot boxes from Font Awesome (U+2610, U+2611) (Noto Serif Regular only)
 * Added line feed character (U+000a)
 * Generated old-style kern table (neither Apple or OpenType) (required to make kerning work in Prawn) (flags: 0x90)