asciidoctor-pdf 1.5.0.beta.1 → 1.5.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (134) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +277 -2
  3. data/LICENSE.adoc +1 -1
  4. data/NOTICE.adoc +1 -1
  5. data/README.adoc +486 -292
  6. data/asciidoctor-pdf.gemspec +12 -11
  7. data/bin/asciidoctor-pdf +2 -6
  8. data/bin/asciidoctor-pdf-optimize +20 -0
  9. data/data/fonts/ABOUT-mplus1mn-subset +26 -0
  10. data/data/fonts/ABOUT-mplus1p-subset +26 -0
  11. data/data/fonts/ABOUT-notoemoji-subset +3 -0
  12. data/data/fonts/ABOUT-notoserif-subset +26 -0
  13. data/data/fonts/{LICENSE-mplus-testflight-58 → LICENSE-mplus} +2 -2
  14. data/data/fonts/{LICENSE-noto-2015-06-05 → LICENSE-notoserif} +0 -0
  15. data/data/fonts/mplus1mn-bold-ascii.ttf +0 -0
  16. data/data/fonts/mplus1mn-bold-subset.ttf +0 -0
  17. data/data/fonts/mplus1mn-bold_italic-ascii.ttf +0 -0
  18. data/data/fonts/mplus1mn-bold_italic-subset.ttf +0 -0
  19. data/data/fonts/mplus1mn-italic-ascii.ttf +0 -0
  20. data/data/fonts/mplus1mn-italic-subset.ttf +0 -0
  21. data/data/fonts/mplus1mn-regular-ascii-conums.ttf +0 -0
  22. data/data/fonts/mplus1mn-regular-subset.ttf +0 -0
  23. data/data/fonts/mplus1p-regular-fallback.ttf +0 -0
  24. data/data/fonts/notoemoji-subset.ttf +0 -0
  25. data/data/fonts/notoserif-bold-subset.ttf +0 -0
  26. data/data/fonts/notoserif-bold_italic-subset.ttf +0 -0
  27. data/data/fonts/notoserif-italic-subset.ttf +0 -0
  28. data/data/fonts/notoserif-regular-subset.ttf +0 -0
  29. data/data/themes/base-theme.yml +22 -4
  30. data/data/themes/default-theme.yml +59 -29
  31. data/data/themes/default-with-fallback-font-theme.yml +4 -17
  32. data/docs/theming-guide.adoc +1647 -167
  33. data/lib/asciidoctor/pdf/converter.rb +4489 -0
  34. data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/abstract_block.rb +2 -0
  35. data/lib/asciidoctor/pdf/ext/asciidoctor/abstract_node.rb +7 -0
  36. data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/document.rb +2 -0
  37. data/lib/asciidoctor/pdf/ext/asciidoctor/image.rb +35 -0
  38. data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/list.rb +4 -2
  39. data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/list_item.rb +3 -1
  40. data/lib/asciidoctor/pdf/ext/asciidoctor/logging_shim.rb +33 -0
  41. data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/section.rb +9 -6
  42. data/lib/asciidoctor/pdf/ext/asciidoctor.rb +11 -0
  43. data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/array.rb +6 -0
  44. data/lib/asciidoctor/pdf/ext/core/file.rb +9 -0
  45. data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/hash.rb +2 -0
  46. data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/numeric.rb +5 -3
  47. data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/object.rb +3 -1
  48. data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/quantifiable_stdout.rb +9 -1
  49. data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/regexp.rb +2 -0
  50. data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/string.rb +9 -13
  51. data/lib/asciidoctor/pdf/ext/core.rb +10 -0
  52. data/lib/asciidoctor/pdf/ext/pdf-core/page.rb +54 -0
  53. data/lib/asciidoctor/pdf/ext/pdf-core/pdf_object.rb +8 -0
  54. data/lib/asciidoctor/pdf/ext/pdf-core.rb +4 -0
  55. data/lib/asciidoctor/pdf/ext/prawn/coderay_encoder.rb +117 -0
  56. data/lib/asciidoctor/pdf/ext/prawn/extensions.rb +922 -0
  57. data/lib/{asciidoctor-pdf/prawn_ext → asciidoctor/pdf/ext/prawn}/font/afm.rb +14 -10
  58. data/lib/asciidoctor/pdf/ext/prawn/font_metric_cache.rb +9 -0
  59. data/lib/asciidoctor/pdf/ext/prawn/formatted_text/box.rb +66 -0
  60. data/lib/{asciidoctor-pdf/prawn_ext → asciidoctor/pdf/ext/prawn}/formatted_text/fragment.rb +16 -12
  61. data/lib/asciidoctor/pdf/ext/prawn/images.rb +54 -0
  62. data/lib/asciidoctor/pdf/ext/prawn-svg/interface.rb +14 -0
  63. data/lib/{asciidoctor-pdf/prawn-svg_ext.rb → asciidoctor/pdf/ext/prawn-svg.rb} +3 -1
  64. data/lib/asciidoctor/pdf/ext/prawn-table/cell/asciidoc.rb +76 -0
  65. data/lib/{asciidoctor-pdf/prawn-table_ext → asciidoctor/pdf/ext/prawn-table}/cell/text.rb +6 -3
  66. data/lib/{asciidoctor-pdf/prawn-table_ext → asciidoctor/pdf/ext/prawn-table}/cell.rb +10 -10
  67. data/lib/asciidoctor/pdf/ext/prawn-table.rb +6 -0
  68. data/lib/{asciidoctor-pdf/prawn-templates_ext.rb → asciidoctor/pdf/ext/prawn-templates.rb} +2 -0
  69. data/lib/asciidoctor/pdf/ext/prawn.rb +9 -0
  70. data/lib/asciidoctor/pdf/ext/pygments.rb +34 -0
  71. data/lib/asciidoctor/pdf/ext/rouge/formatters/prawn.rb +208 -0
  72. data/lib/{asciidoctor-pdf/rouge_ext → asciidoctor/pdf/ext/rouge}/themes/asciidoctor_pdf_default.rb +2 -0
  73. data/lib/asciidoctor/pdf/ext/rouge.rb +5 -0
  74. data/lib/asciidoctor/pdf/ext.rb +9 -0
  75. data/lib/asciidoctor/pdf/formatted_text/formatter.rb +43 -0
  76. data/lib/asciidoctor/pdf/formatted_text/fragment_position_renderer.rb +14 -0
  77. data/lib/asciidoctor/pdf/formatted_text/inline_destination_marker.rb +21 -0
  78. data/lib/asciidoctor/pdf/formatted_text/inline_image_arranger.rb +134 -0
  79. data/lib/asciidoctor/pdf/formatted_text/inline_image_renderer.rb +51 -0
  80. data/lib/asciidoctor/pdf/formatted_text/inline_text_aligner.rb +22 -0
  81. data/lib/{asciidoctor-pdf → asciidoctor/pdf}/formatted_text/parser.rb +31 -7
  82. data/lib/{asciidoctor-pdf → asciidoctor/pdf}/formatted_text/parser.treetop +3 -4
  83. data/lib/asciidoctor/pdf/formatted_text/source_wrap.rb +43 -0
  84. data/lib/asciidoctor/pdf/formatted_text/text_background_and_border_renderer.rb +55 -0
  85. data/lib/asciidoctor/pdf/formatted_text/transform.rb +394 -0
  86. data/lib/{asciidoctor-pdf → asciidoctor/pdf}/formatted_text.rb +4 -0
  87. data/lib/asciidoctor/pdf/index_catalog.rb +133 -0
  88. data/lib/asciidoctor/pdf/measurements.rb +62 -0
  89. data/lib/asciidoctor/pdf/optimizer.rb +44 -0
  90. data/lib/asciidoctor/pdf/pdfmark.rb +41 -0
  91. data/lib/asciidoctor/pdf/roman_numeral.rb +128 -0
  92. data/lib/asciidoctor/pdf/sanitizer.rb +45 -0
  93. data/lib/asciidoctor/pdf/text_transformer.rb +116 -0
  94. data/lib/asciidoctor/pdf/theme_loader.rb +305 -0
  95. data/lib/asciidoctor/pdf/version.rb +8 -1
  96. data/lib/asciidoctor/pdf.rb +15 -1
  97. data/lib/asciidoctor-pdf/converter.rb +2 -3824
  98. data/lib/asciidoctor-pdf/version.rb +3 -6
  99. data/lib/asciidoctor-pdf.rb +3 -4
  100. metadata +130 -85
  101. data/lib/asciidoctor-pdf/asciidoctor_ext/image.rb +0 -24
  102. data/lib/asciidoctor-pdf/asciidoctor_ext/logging_shim.rb +0 -25
  103. data/lib/asciidoctor-pdf/asciidoctor_ext.rb +0 -8
  104. data/lib/asciidoctor-pdf/core_ext/ostruct.rb +0 -8
  105. data/lib/asciidoctor-pdf/core_ext.rb +0 -6
  106. data/lib/asciidoctor-pdf/formatted_text/formatter.rb +0 -40
  107. data/lib/asciidoctor-pdf/formatted_text/inline_destination_marker.rb +0 -21
  108. data/lib/asciidoctor-pdf/formatted_text/inline_image_arranger.rb +0 -160
  109. data/lib/asciidoctor-pdf/formatted_text/inline_image_renderer.rb +0 -46
  110. data/lib/asciidoctor-pdf/formatted_text/inline_text_aligner.rb +0 -20
  111. data/lib/asciidoctor-pdf/formatted_text/text_background_and_border_renderer.rb +0 -45
  112. data/lib/asciidoctor-pdf/formatted_text/transform.rb +0 -294
  113. data/lib/asciidoctor-pdf/implicit_header_processor.rb +0 -63
  114. data/lib/asciidoctor-pdf/index_catalog.rb +0 -127
  115. data/lib/asciidoctor-pdf/measurements.rb +0 -58
  116. data/lib/asciidoctor-pdf/pdf-core_ext/page.rb +0 -25
  117. data/lib/asciidoctor-pdf/pdf-core_ext/pdf_object.rb +0 -6
  118. data/lib/asciidoctor-pdf/pdf-core_ext.rb +0 -2
  119. data/lib/asciidoctor-pdf/pdfmark.rb +0 -33
  120. data/lib/asciidoctor-pdf/prawn-svg_ext/interface.rb +0 -10
  121. data/lib/asciidoctor-pdf/prawn-table_ext/cell/asciidoc.rb +0 -69
  122. data/lib/asciidoctor-pdf/prawn-table_ext.rb +0 -4
  123. data/lib/asciidoctor-pdf/prawn_ext/coderay_encoder.rb +0 -115
  124. data/lib/asciidoctor-pdf/prawn_ext/extensions.rb +0 -904
  125. data/lib/asciidoctor-pdf/prawn_ext/images.rb +0 -51
  126. data/lib/asciidoctor-pdf/prawn_ext.rb +0 -5
  127. data/lib/asciidoctor-pdf/roman_numeral.rb +0 -126
  128. data/lib/asciidoctor-pdf/rouge_ext/formatters/prawn.rb +0 -175
  129. data/lib/asciidoctor-pdf/rouge_ext/themes/bw.rb +0 -38
  130. data/lib/asciidoctor-pdf/rouge_ext.rb +0 -4
  131. data/lib/asciidoctor-pdf/sanitizer.rb +0 -101
  132. data/lib/asciidoctor-pdf/temporary_path.rb +0 -13
  133. data/lib/asciidoctor-pdf/theme_loader.rb +0 -280
  134. data/lib/asciidoctor-pdf/ttfunk_ext.rb +0 -8
data/README.adoc CHANGED
@@ -1,6 +1,6 @@
1
1
  = Asciidoctor PDF: A native PDF converter for AsciiDoc
2
2
  Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
3
- v1.5.0.beta.1, 2019-07-08
3
+ v1.5.0, 2020-02-11
4
4
  // Settings:
5
5
  :experimental:
6
6
  :idprefix:
@@ -12,7 +12,6 @@ ifdef::env-github,env-browser[]
12
12
  endif::[]
13
13
  ifdef::env-github[]
14
14
  :status:
15
- :outfilesuffix: .adoc
16
15
  :!toc-title:
17
16
  :caution-caption: :fire:
18
17
  :important-caption: :exclamation:
@@ -24,98 +23,92 @@ endif::[]
24
23
  :project-name: Asciidoctor PDF
25
24
  :project-handle: asciidoctor-pdf
26
25
  // Variables:
27
- :release-version: 1.5.0.beta.1
26
+ :release-version: 1.5.0
28
27
  // URIs:
29
- :uri-asciidoctor: http://asciidoctor.org
30
- :uri-gem: http://rubygems.org/gems/asciidoctor-pdf
31
- :uri-project: https://github.com/asciidoctor/asciidoctor-pdf
32
- :uri-project-repo: {uri-project}
33
- :uri-project-issues: {uri-project-repo}/issues
34
- :uri-project-list: http://discuss.asciidoctor.org
35
- :uri-prawn: http://prawnpdf.org
36
- :uri-prawn-gmagick: https://github.com/packetmonkey/prawn-gmagick
37
- :uri-prawn-svg: https://github.com/mogest/prawn-svg
38
- :uri-asciidoctor-mathematical: https://github.com/asciidoctor/asciidoctor-mathematical
39
- :uri-rvm: http://rvm.io
40
- :uri-graphicsmagick: http://www.graphicsmagick.org
28
+ :url-asciidoctor: http://asciidoctor.org
29
+ :url-gem: http://rubygems.org/gems/asciidoctor-pdf
30
+ :url-project: https://github.com/asciidoctor/asciidoctor-pdf
31
+ :url-project-repo: {url-project}
32
+ :url-project-issues: {url-project-repo}/issues
33
+ :url-project-list: http://discuss.asciidoctor.org
34
+ :url-prawn: http://prawnpdf.org
35
+ :url-prawn-gmagick: https://github.com/packetmonkey/prawn-gmagick
36
+ :url-prawn-svg: https://github.com/mogest/prawn-svg
37
+ :url-asciidoctor-mathematical: https://github.com/asciidoctor/asciidoctor-mathematical
38
+ :url-rvm: http://rvm.io
39
+ :url-graphicsmagick: http://www.graphicsmagick.org
41
40
 
42
41
  ifdef::status[]
43
42
  image:https://img.shields.io/travis/asciidoctor/asciidoctor-pdf/master.svg[Build Status (Travis CI),link=https://travis-ci.org/asciidoctor/asciidoctor-pdf]
44
- image:https://ci.appveyor.com/api/projects/status/524bhoms3j2dp1o3/branch/master?svg=true[Build Status (AppVeyor),link=https://ci.appveyor.com/project/asciidoctor/asciidoctor-pdf]
45
- image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={uri-gem}]
43
+ image:https://github.com/asciidoctor/asciidoctor-pdf/workflows/CI/badge.svg[Build Status (GitHub Actions),link=https://github.com/asciidoctor/asciidoctor-pdf/actions?query=workflow%3ACI]
44
+ image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={url-gem}]
46
45
  image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright]
47
46
  endif::[]
48
47
 
49
- ifdef::env-site[]
50
48
  Asciidoctor PDF is a native PDF converter for AsciiDoc.
51
- It bypasses the requirement to generate an interim format such as DocBook, Apache FO, or LaTeX.
52
- Instead, you can use it to convert directly from AsciiDoc to PDF.
49
+ It bypasses the requirement to generate an intermediary format such as DocBook, Apache FO, or LaTeX.
50
+ Instead, you can use this extension to convert your documents directly from AsciiDoc to PDF.
53
51
  Its aim is to take the pain out of creating PDF documents from AsciiDoc.
54
- endif::[]
55
- ifndef::env-site[]
56
- _Lo and behold_, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! +
57
- _No more middleman._ +
58
- _No more DocBook toolchain._ +
59
- It's AsciiDoc straight to PDF!
60
-
61
- [caption=Status]
62
- CAUTION: {project-name} is currently _alpha_ software.
63
- While the converter handles most AsciiDoc content, there's still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented.
64
- See the milestone v1.5.0 in the {uri-project-issues}[issue tracker] for details.
65
52
 
66
53
  toc::[]
67
54
 
68
- == Prawn, the Majestic PDF Generator
69
-
70
- {uri-project}[{project-name}] is made possible by an amazing Ruby gem named Prawn.
71
- And what a gem it is!
72
-
73
- {uri-prawn}[Prawn] is a nimble PDF writer for Ruby.
74
- 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 accommodate special circumstances.
75
-
76
- 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.
77
- In addition, it brings a fluent API and aggressive code re-use to the printable document space.
78
-
79
- Here's an example that demonstrates how to use Prawn to create a basic PDF document.
80
-
81
- .Create a basic PDF document using Prawn
82
- [source,ruby]
83
- ----
84
- require 'prawn'
55
+ == Overview
85
56
 
86
- Prawn::Document.generate 'output.pdf' do
87
- text 'Hello, PDF creation!'
88
- end
89
- ----
57
+ {project-name} is an Asciidoctor extension that converts an AsciiDoc document directly to a PDF document.
58
+ The style and layout of the PDF is controlled by a dedicated theme file.
59
+ To the degree possible, this converter supports all the features of AsciiDoc that are supported by the built-in converters.
60
+ However, there are <<known-limitations,certain limits>> imposed by the PDF format and the PDF library this extension uses.
90
61
 
91
- It's that easy.
92
- And that's just the beginning.
93
- Skip ahead to <<getting-started,Getting started>> to start putting it use.
62
+ Under the covers, {project-name} uses the Prawn gem and its extensions (e.g., prawn-svg and prawn-table) to generate the PDF document.
63
+ {url-prawn}[Prawn] is a general purpose PDF generator for Ruby that features high-level APIs for common needs like setting up the page and inserting images and low-level APIs for positioning and rendering text and graphics.
94
64
 
95
- Prawn is the _killer library_ for PDF generation we've needed to close this critical gap in Asciidoctor.
96
- It absolutely takes the pain out of creating printable documents.
97
- Picking up from there, {project-name} takes the pain out of creating PDF documents _from AsciiDoc_.
98
- endif::[]
65
+ Prawn takes the pain out of creating (basic) PDF documents.
66
+ Likewise, {project-name} takes the pain out of creating PDF documents _directly from AsciiDoc_.
67
+ Skip ahead to <<getting-started,Getting started>> to start putting {project-name} use.
68
+ But don't miss the <<Highlights>> to get a preview of what's possible.
99
69
 
100
70
  == Highlights
101
71
 
102
72
  * Direct AsciiDoc to PDF conversion
103
- * <<docs/theming-guide#,Configuration-driven theme (style and layout)>>
104
- * SVG support
73
+ * <<docs/theming-guide.adoc#,Configuration-driven theme (style and layout)>>
74
+ * Custom (TTF) fonts
75
+ * Full SVG support (thanks to https://github.com/mogest/prawn-svg[prawn-svg])
105
76
  * PDF document outline (i.e., bookmarks)
77
+ * Title page
106
78
  * Table of contents page(s)
107
- * Document metadata (title, authors, subject, keywords, etc)
79
+ * Document metadata (title, authors, subject, keywords, etc.)
80
+ * Configurable page size (e.g., A4, Letter, Legal, etc)
108
81
  * Internal cross reference links
109
- * Syntax highlighting with Rouge, Pygments, or CodeRay
82
+ * Syntax highlighting with Rouge (preferred), Pygments, or CodeRay
83
+ * Cover pages
84
+ * Page background color or page background image with named scaling
110
85
  * Page numbering
86
+ * Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
111
87
  * Customizable running content (header and footer)
112
88
  * “Keep together” blocks (i.e., page breaks avoided in certain block content)
113
89
  * Orphaned section titles avoided
114
90
  * Autofit verbatim blocks (as permitted by base_font_size_min setting)
115
91
  * Table border settings honored
116
92
  * Font-based icons
117
- * Custom (TTF) fonts
118
- * Double-sided printing mode (margins alternate on recto and verso pages)
93
+ * Auto-generated index
94
+ * Automatic hyphenation (when enabled)
95
+ * Permissive line breaking for CJK languages
96
+ * Compression / optimization of output file
97
+
98
+ == Known Limitations
99
+
100
+ * Footnotes are always rendered as endnotes (at end of chapter for books; at end of document for all other doctypes)
101
+ * Table cells that exceed height of a single page will be truncated (see https://github.com/prawnpdf/prawn-table/issues/41[prawn-table#41])
102
+ * Columns cannot be assigned a 0% width (or a width less than the width of a single character); in the same vein, a column cannot be set to autowidth if width of all other columns meets or exceeds 100%; the result is that the converter with throw a Prawn::Errors::CannotFit error
103
+ * An inline image in a table cell will not force the column wider if the width of the image exceeds the width of the column; either reduce the image width using `pdfwidth` or increase the width of the column using `cols`; another solution is to convert the cell to an AsciiDoc table cell (see https://github.com/asciidoctor/asciidoctor-pdf/issues/830)
104
+ * Must use development version of prawn-table for autowidth to work on table head row
105
+ * Must use development version of prawn for error to include font name when requested font style is missing
106
+ * Must use Ruby >= 2.4 for natural cross references to work with non-ASCII titles
107
+ * AsciiDoc table cell leaves padding below last block (due to lack of margin collapsing)
108
+ * Prawn does not support double-wide box drawing glyphs correctly, so box drawings aren't aligned properly in verbatim blocks (see https://github.com/prawnpdf/prawn/issues/1002[prawn#1002]
109
+ * Orphan / widow support is limited; a page break can occur between a section title and its section content, a table caption and the caption, etc.; use a manual page break to avoid
110
+ * If a no-break hyphen is surrounded by formatted text on both sides (or is formatted individually), it will not prevent a line break
111
+ * Images cannot float
119
112
 
120
113
  == Prerequisites
121
114
 
@@ -148,11 +141,43 @@ ifndef::env-site[You can also <<development,run the code from source>> if you wa
148
141
 
149
142
  === Install the Published Gem
150
143
 
151
- {project-name} is published as a pre-release on RubyGems.org.
152
- First, make sure you have satisfied the <<Prerequisites,prerequisites>>.
153
- Then, you can install the published gem using the following command:
144
+ To install {project-name}, first make sure you have satisfied the <<Prerequisites,prerequisites>>.
145
+ Then, install the gem from RubyGems.org using the following command:
146
+
147
+ $ gem install asciidoctor-pdf
148
+
149
+ ==== Installation Troubleshooting
154
150
 
155
- $ gem install asciidoctor-pdf --pre
151
+ If you get a permission error while installing the gem, such as the one below, it's likely you're attempting to install the gem directly into your system.
152
+ Installing gems for tech writing directly into your system is not recommended.
153
+
154
+ .Permission error when attempting to install as a system gem
155
+ ....
156
+ ERROR: While executing gem ... (Gem::FilePermissionError)
157
+ You don't have write permissions for the /Library/Ruby/Gems/2.x.x directory.
158
+ ....
159
+
160
+ A better practice (and one that will ensure your sanity) is to ignore any version of Ruby installed on your system and use {url-rvm}[RVM] to manage the Ruby installation instead.
161
+ The benefit of this approach is that a) Ruby is guaranteed to be set up correctly, b) installing gems will in no way interfere with the operation of your system, and c) any bin scripts provided by the installed gems will be available on your PATH.
162
+ All files are managed in user space (aka your home or user directory).
163
+ If something gets messed up, you can simply remove the [.path]_$HOME/.rvm_ folder and start over.
164
+
165
+ To learn how to install RVM, follow the https://asciidoctor.org/docs/install-asciidoctor-macos/#rvm-procedure-recommended[RVM installation procedure] covered in the Asciidoctor documentation.
166
+ Once you have installed RVM and used it to install Ruby, make sure to activate the Ruby managed by RVM using `rvm use default` or a specific Ruby version like `rvm use 2.6`.
167
+ (You'll need to do this each time you open a new terminal).
168
+
169
+ After installing the gem, you can see where it was installed using the following command:
170
+
171
+ $ gem which asciidoctor-pdf
172
+
173
+ To see where the bin script is located, use this command:
174
+
175
+ $ command -v asciidoctor-pdf
176
+
177
+ Both paths should be underneath the [.path]_$HOME/.rvm_ directory.
178
+ If not, check your RVM setup.
179
+
180
+ ==== Install a Syntax Highlighter (optional)
156
181
 
157
182
  If you want to syntax highlight source listings, you'll also want to install Rouge, Pygments, or CodeRay.
158
183
  Choose one (or more) of the following:
@@ -173,6 +198,38 @@ You then activate syntax highlighting for a given document by adding the `source
173
198
  :source-highlighter: rouge
174
199
  ----
175
200
 
201
+ ==== Upgrade Prawn and Extensions (optional)
202
+
203
+ {project-name} uses Prawn to handle the PDF generation, which has a different release cycle.
204
+ At times, there may are development features in Prawn and its extensions you need to use which haven't yet been released.
205
+ No problem.
206
+ You can still gain access to these features by installing the unreleased gems directly from GitHub.
207
+
208
+ To get started, first create a [.path]_Gemfile_ in the root of your project.
209
+ In that file, declare the gem soruce, the {project-handle} gem, and the prawn gem and/or one of its extension gems.
210
+ In this example, we'll install both the prawn and prawn-table gems from GitHub.
211
+
212
+ .Gemfile
213
+ [source,ruby]
214
+ ----
215
+ source 'https://rubygems.org'
216
+
217
+ gem 'asciidoctor-pdf'
218
+ gem 'prawn', github: 'prawnpdf/prawn'
219
+ gem 'prawn-table', github: 'prawnpdf/prawn-table'
220
+ ----
221
+
222
+ You can then install the gems into your project using the `bundle` command:
223
+
224
+ $ bundle config set --local path .bundle/gems && bundle
225
+
226
+ Since you're using Bundler to manage the gems, you'll need to prefix all commands with `bundle exec`.
227
+ For example:
228
+
229
+ $ bundle exec asciidoctor-pdf -v
230
+
231
+ Thus, to any command present in the following sections, be sure to include this prefix.
232
+
176
233
  === Run the Application
177
234
 
178
235
  Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script:
@@ -185,10 +242,10 @@ Let's grab an AsciiDoc document to distill and start putting {project-name} to u
185
242
 
186
243
  === An Example AsciiDoc Document
187
244
 
188
- If you don't already have an AsciiDoc document, you can use the <<examples/basic-example#,basic-example.adoc>> file found in the examples directory of this project.
245
+ If you don't already have an AsciiDoc document, you can use the <<examples/basic-example.adoc#,basic-example.adoc>> file found in the examples directory of this project.
189
246
 
190
247
  ifeval::[{safe-mode-level} >= 20]
191
- See <<examples/basic-example#,basic-example.adoc>>.
248
+ See <<examples/basic-example.adoc#,basic-example.adoc>>.
192
249
  endif::[]
193
250
  ifeval::[{safe-mode-level} < 20]
194
251
  .basic-example.adoc
@@ -222,7 +279,7 @@ Open the [.path]_basic-example.pdf_ file with a PDF viewer to see the result.
222
279
  image::examples/example-pdf-screenshot.png[Screenshot of PDF document,width=850,467,scaledwidth=100%]
223
280
 
224
281
  ifndef::env-site[]
225
- 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.
282
+ You're also encouraged to try converting this <<README.adoc#,README>> as well as the documents in the examples directory to see more of what {project-name} can do.
226
283
  endif::[]
227
284
 
228
285
  The pain of the DocBook toolchain should be melting away about now.
@@ -230,7 +287,7 @@ The pain of the DocBook toolchain should be melting away about now.
230
287
  == Themes
231
288
 
232
289
  The layout and styling of the PDF is driven by a YAML configuration file.
233
- To learn how the theming system works and how to create and apply custom themes, refer to the <<docs/theming-guide#,Asciidoctor PDF Theme Guide>>.
290
+ 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>>.
234
291
  You can use the built-in theme files, which you can find in the [.path]_data/themes_ directory, as examples.
235
292
 
236
293
  If you've enabled a source highlighter, you can control the style (aka theme) it applies to source blocks using the `coderay-style`, `pygments-style`, and `rouge-style` attributes, respectively.
@@ -239,29 +296,91 @@ For example, to configure Rouge to use the built-in monokai theme, run Asciidoct
239
296
  $ asciidoctor-pdf -a rouge-style=monokai basic-example.adoc
240
297
 
241
298
  It's possible to develop your own theme for Rouge.
242
- Refer to the <<docs/theming-guide#,Asciidoctor PDF Theme Guide>> for details.
299
+ Refer to the <<docs/theming-guide.adoc#,Asciidoctor PDF Theme Guide>> for details.
243
300
 
244
- === Support for Non-Latin Languages
301
+ == Support for Non-Latin Languages
245
302
 
246
303
  Asciidoctor can process the full range of characters in the UTF-8 character set.
247
- That means you can write your document in any language, save the file with UTF-8 encoding, and expect Asciidoctor to convert the text properly.
248
- However, you may notice that certain characters for certain languages, such as Chinese, are missing in the PDF.
249
- Read on to find out why and how to address it.
304
+ That means you can write your document in any language, save the file with UTF-8 encoding (_that's important!_), and expect Asciidoctor to convert the text properly.
305
+ But you still need a font that provides the glyphs for those characters.
306
+
307
+ When converting a document with Asciidoctor PDF, you may notice that some of the glyphs for certain languages, such as Chinese, are missing from the PDF.
308
+ PDF is a "`bring your own font`" kind of system.
309
+ In other words, the font you provide must provide glyphs for all the characters used.
310
+ There's no one font that supports all the world's languages (though some, like Noto Serif, certainly come close).
311
+ Even if there were such a font, bundling that font with the main gem would make it enormous.
312
+ It would also severely limit the style choices in the default theme, which targets Latin-based languages.
313
+ Therefore, we're taking the strategy of creating separate dedicated theme gems that target each language family, such as CJK.
314
+ Read on to find out how to use these themes.
250
315
 
251
- If you're writing in a non-Latin language, you need to use a dedicated theme that provides the necessary fonts.
252
- For example, to produce a PDF from a document written in a CJK language such as Chinese, you need to use a CJK theme.
316
+ Asciidoctor PDF provides a built-in theme that provides a broad range of characters in the CJK charsets, so you can start with that theme:
317
+
318
+ $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-fallback-font document.adoc
319
+
320
+ Notice the `-a scripts=cjk` option.
321
+ That's important.
322
+ It tells the converter to insert break opportunities between CJK characters so that the line wraps properly when mixing English and a CJK language like Japanese.
323
+
324
+ If the built-in theme with the fallback font doesn't go far enough, you'll need to use a theme that is optimized for CJK text.
253
325
  You can get such a theme by installing the `asciidoctor-pdf-cjk-kai_gen_gothic` gem.
254
- See the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project for detailed instructions.
326
+ The https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project provides themes optimized for CJK languages based on the kai_gen_gothic font.
327
+ See the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project README for detailed setup instructions.
255
328
 
256
- Using a dedicated theme is necessary because PDF is a "`bring your own font`" kind of system.
257
- In other words, the font you provide must provide glyphs for all the characters.
258
- There's no one font that supports all the worlds languages (though some, like Noto Serif, certainly come close).
259
- Even if there were such a font, bundling that font with the main gem would make the package enormous.
260
- It would also severely limit the style choices in the default theme, which targets Latin-based languages.
329
+ Once you have that gem installed (and the fonts), you need to tell Asciidoctor PDF to use one of the themes.
330
+ If you're converting a document that is primarily written in Japanese, you'd run Asciidoctor PDF as follows:
261
331
 
262
- Therefore, we're taking the strategy of creating separate dedicated theme gems that target each language family, such as CJK.
263
- The base theme for CJK languages is provided by the https://github.com/chloerei/asciidoctor-pdf-cjk[asciidoctor-pdf-cjk] project and a concrete implementation provided by the https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic[asciidoctor-pdf-cjk-kai_gen_gothic] project that's based on the kai_gen_gothic font.
264
- Of course, you're free to follow this model and create your own theme gem that uses fonts of your choice.
332
+ asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-theme=KaiGenGothicJP document.adoc
333
+
334
+ You also have to option of creating your own theme gem that uses fonts of your choice.
335
+ For example, if you want to use the `asciidoctor-pdf-cjk-kai_gen_gothic` gem to fetch fonts, but then use them in your own theme, here's how you'd do it.
336
+
337
+ . Install the `asciidoctor-pdf-cjk-kai_gen_gothic` gem:
338
+
339
+ $ gem install asciidoctor-pdf-cjk-kai_gen_gothic
340
+
341
+ . Download / install the fonts:
342
+
343
+ $ asciidoctor-pdf-cjk-kai_gen_gothic-install
344
+
345
+ . Create a theme that extends the default theme:
346
+ +
347
+ [source,yml]
348
+ ----
349
+ extends: default
350
+ font:
351
+ catalog:
352
+ KaiGen Gothic JP:
353
+ normal: KaiGenGothicJP-Regular.ttf
354
+ bold: KaiGenGothicJP-Bold.ttf
355
+ italic: KaiGenGothicJP-Regular-Italic.ttf
356
+ bold_italic: KaiGenGothicJP-Bold-Italic.ttf
357
+ M+ 1mn:
358
+ normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
359
+ bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
360
+ italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
361
+ bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf
362
+ fallbacks:
363
+ - KaiGen Gothic JP
364
+ base:
365
+ font-family: KaiGen Gothic JP
366
+ heading:
367
+ font-family: $base-font-family
368
+ abstract:
369
+ title:
370
+ font-family: $heading-font-family
371
+ sidebar:
372
+ title:
373
+ font-family: $heading-font-family
374
+ ----
375
+
376
+ . Load your theme when running Asciidoctor PDF:
377
+
378
+ $ asciidoctor-pdf -a scripts=cjk -a pdf-theme=./jp-theme.yml -a pdf-fontsdir=`ruby -r asciidoctor-pdf-cjk-kai_gen_gothic -e "print File.expand_path '../fonts', (Gem.datadir 'asciidoctor-pdf-cjk-kai_gen_gothic')"` document.adoc
379
+
380
+ The `-a pdf-fontsdir` option is important to tell Asciidoctor PDF where to find your custom fonts.
381
+
382
+ Rather than using the installer from the `asciidoctor-pdf-cjk-kai_gen_gothic` gem, you can download fonts whatever way you choose.
383
+ When using your own fonts, be sure to consult the <<docs/theming-guide.adoc#preparing-a-custom-font,Preparing a Custom Font>> section of the theming guide to find recommended modifications.
265
384
 
266
385
  == Font-Based Icons
267
386
 
@@ -329,17 +448,22 @@ To find a complete list of available icons, consult the https://github.com/jesse
329
448
 
330
449
  == Image Paths
331
450
 
332
- Relative images paths are resolved relative to the value of the `imagesdir` attribute at the time the converter is run.
451
+ Images are resolved at the time the converter runs.
452
+ That means they need to be located where the converter can find them.
453
+
454
+ Relative images paths in the document are resolved relative to the value of the `imagesdir` attribute.
333
455
  This is effectively the same as how the built-in HTML converter works when the `data-uri` attribute is set.
334
456
  The `imagesdir` is blank by default, which means relative images paths are resolved relative to the input document.
457
+ 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).
458
+ The `imagesdir` attribute is not used when resolving an image path in the theme file.
335
459
  Absolute image paths are used as is.
336
460
 
337
461
  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.
338
462
 
339
- 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.
463
+ 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.
340
464
 
341
- 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.
342
- However, note that a width and height must be specified on the linked image or else the SVG library will fail to process it.
465
+ If you use a linked image in an SVG, the width and height of that image must be specified.
466
+ Otherwise, the SVG library will fail to process it.
343
467
 
344
468
  === Asciidoctor Diagram Integration
345
469
 
@@ -358,7 +482,7 @@ Keep in mind that this strategy may introduce other side effects you'll have to
358
482
  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.
359
483
  There are five ways to specify the width of an image, listed here in order of precedence:
360
484
 
361
- [cols="1s,3d"]
485
+ [cols="1s,3"]
362
486
  |===
363
487
  |Attribute{nbsp}Name | Description
364
488
 
@@ -379,13 +503,14 @@ _Only applies to block images._
379
503
 
380
504
  |width
381
505
  |The unitless display width of the image (assumed to be pixels), typically matching the intrinsic width of the image.
506
+ If the value ends in % (not recommended), it's assumed to be the percentage of the available content area width.
382
507
  If the width exceeds the content area width, the image is scaled down to the content area width.
383
508
 
384
509
  |_unspecified_
385
510
  |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.
386
511
  |===
387
512
 
388
- The image is always sized according to the explicit or intrinsic width and its height is scaled proportionally.
513
+ The image is always sized according to the explicit or intrinsic width, then its height is scaled proportionally.
389
514
  The height of the image is ignored by the PDF converter unless the height of the image exceeds the content height of the page.
390
515
  In this case, the image is scaled down to fit on a single page.
391
516
 
@@ -393,10 +518,7 @@ If you want a block image to align to the boundaries of the page (not the conten
393
518
  This is most useful when using vw units because you can make the image cover the entire width of the page.
394
519
 
395
520
  Images in running content and page background images also support the `fit` attribute (when specified using the image macro).
396
- 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.
397
- 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.
398
-
399
- 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`).
521
+ See <<Background Image Sizing>> for details.
400
522
 
401
523
  === Using the pdfwidth Attribute
402
524
 
@@ -436,15 +558,88 @@ Inline images can be sized in much the same way as block images (using the pdfwi
436
558
  * The image will be scaled down, if necessary, to fit the width and height of the content area.
437
559
  * Inline images do not currently support a default width controlled from the theme.
438
560
 
561
+ To confine the inline image to the height of the line while preserving the aspect ratio, use the attribute `fit=line`.
562
+
439
563
  If the resolved height of the image is less than or equal to 1.5 times the line height, the image won't disrupt the line height and is centered vertically in the line.
440
564
  This is done to maximize the use of available space.
441
565
  Once the resolved height exceeds this amount, the height of the line is increased (by increasing the font size of the invisible placeholder text) to accommodate the image.
442
566
  In this case, the surrounding text will be aligned to the bottom of the image.
443
567
  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).
444
568
 
569
+ === Background Image Sizing
570
+
571
+ In addition to the width-related attributes previously covered, cover and background images can be sized relative to the page using the `fit` attribute of the image macro.
572
+ The `fit` attribute works similarly to the `object-fit` property in CSS.
573
+ It's value must be specified as a single keyword, chosen from the table below.
574
+ The starting size of the image is determined by the explicit width, if specified, or the implicit width.
575
+ The height is always derived from the width while respecting the implicit aspect ratio of the image.
576
+ The available space for a background image (i.e., the canvas) is the page.
577
+ If the `fit` attribute is not specified, it defaults to `contain` (i.e., the image is automatically scaled to fit the bounds of the page).
578
+
579
+ [cols="1s,3"]
580
+ |===
581
+ | Value | Purpose
582
+
583
+ | contain
584
+ | The image is scaled up or down while retaining its aspect ratio to fit within the available space. (default)
585
+
586
+ | cover
587
+ | 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.
588
+
589
+ | scale-down
590
+ | The image is scaled down while retaining its aspect ratio to fit within the available space.
591
+ If the image already fits, it is not scaled.
592
+
593
+ | fill
594
+ | The image is scaled to fit the available space even if it means modifying the aspect ratio of the image.
595
+ Does not apply to SVG images.
596
+
597
+ | none
598
+ | The image is not scaled.
599
+ |===
600
+
601
+ The `fit` attribute is often combined with the `position` attribute, covered next, to control the placement of the image on the canvas.
602
+
603
+ == Background Image Positioning
604
+
605
+ In addition to scaling, background images for cover pages, content pages, and the title page support positioning via the `position` attribute.
606
+ The `position` attribute accepts a syntax similar to the `background-position` property in CSS, except only the keyword positions are supported.
607
+ The position consists of two values, the vertical position and the horizontal position (e.g., `top center`).
608
+ If only one value is specified (e.g., `top`), the other value is assumed to be `center`.
609
+ If the `position` attribute is not specified, the value is assumed to be `center center` (i.e., the image is centered on the page).
610
+
611
+ The following table provides a list of the vertical and horizontal positioning keywords that are supported.
612
+ You can use any combination of these keywords to position the image.
613
+
614
+ |===
615
+ | Vertical Positions | Horizontal Positions
616
+
617
+ | top +
618
+ center +
619
+ bottom
620
+
621
+ | left +
622
+ center +
623
+ right
624
+ |===
625
+
626
+ Here's an example of how to place a background image at the top center of every page:
627
+
628
+ ----
629
+ :page-background-image: image:bg.png[fit=none,pdfwidth=50%,position=top]
630
+ ----
631
+
632
+ Here's how to move it to the bottom right:
633
+
634
+ ----
635
+ :page-background-image: image:bg.png[fit=none,pdfwidth=50%,position=bottom right]
636
+ ----
637
+
638
+ If an image dimension matches the height or width of the page, the positioning keyword for that axis has no effect.
639
+
445
640
  == Fonts in SVG Images
446
641
 
447
- Asciidoctor PDF uses {uri-prawn-svg}[prawn-svg] to embed SVGs in the PDF document, including SVGs generated by Asciidoctor Diagram.
642
+ Asciidoctor PDF uses {url-prawn-svg}[prawn-svg] to embed SVGs in the PDF document, including SVGs generated by Asciidoctor Diagram.
448
643
 
449
644
  Actually, it's not accurate to say that prawn-svg embeds the SVG.
450
645
  Rather, prawn-svg is an SVG _renderer_.
@@ -455,7 +650,7 @@ The result becomes indistinguishable from other PDF objects.
455
650
  What that means for text is that any font family used for text in the SVG _must_ be registered in the Asciidoctor PDF theme file (and thus with Prawn).
456
651
  Otherwise, Prawn will fallback to using the closest matching built-in (afm) font from PDF (e.g., sans-serif becomes Helvetica).
457
652
  Recall that afm fonts only support basic Latin.
458
- As we like to say, PDF is <<docs/theming-guide#built-in-afm-fonts,bring your own font>>.
653
+ As we like to say, PDF is <<docs/theming-guide.adoc#built-in-afm-fonts,bring your own font>>.
459
654
 
460
655
  If you're using Asciidoctor Diagram to generate SVGs to embed in the PDF, you likely need to specify the default font the diagramming tool uses.
461
656
  Let's assume you are making a plantuml diagram.
@@ -485,20 +680,149 @@ If you're using fonts in your SVG, and you want those fonts to be preserved, tho
485
680
 
486
681
  In order to embed an image into a PDF, Asciidoctor PDF must understand how to read it.
487
682
  To perform this work, Asciidoctor delegates to the underlying libraries.
488
- {uri-prawn}[Prawn] provides support for reading JPG and PNG images.
489
- {uri-prawn-svg}[prawn-svg] brings support for SVG images.
683
+ {url-prawn}[Prawn] provides support for reading JPG and PNG images.
684
+ {url-prawn-svg}[prawn-svg] brings support for SVG images.
490
685
  Without any additional libraries, those are the only supported image file formats.
491
686
 
492
- 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.
493
- prawn-gmagick is an extension for Prawn based on {uri-graphicsmagick}[GraphicsMagick] that adds support for all the image formats recognized by that library.
687
+ 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 {url-prawn-gmagick}[prawn-gmagick] (>= 0.0.9) Ruby gem.
688
+ prawn-gmagick is an extension for Prawn based on {url-graphicsmagick}[GraphicsMagick] that adds support for all the image formats recognized by that library.
494
689
  prawn-gmagick has the added benefit of significantly reducing the time it takes to generate a PDF containing a lot of images.
495
690
 
496
691
  The prawn-gmagick gem uses native extensions to compile against GraphicsMagick.
497
692
  This system prerequisite limits installation to Linux and OSX.
498
- Please refer to the {uri-prawn-gmagick}[README for prawn-gmagick] to learn how to install it.
693
+ Please refer to the {url-prawn-gmagick}[README for prawn-gmagick] to learn how to install it.
694
+
695
+ Once this gem is installed, Asciidoctor automatically loads it, then delegates to it to handle all image embedding.
696
+ In addition to support for additional image file formats, this gem also speeds up image processing considerably.
697
+ We highly recommend using this gem if you're able to install it.
698
+
699
+ == Importing PDF Pages
700
+
701
+ In addition to using a PDF page for the front or back cover, you can also insert a PDF page at an arbitrary location.
702
+ 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.
703
+ One such example is an insert such as an advertisement or visual interlude.
704
+
705
+ To import the first page from a PDF file, use the block image macro with the PDF filename as the image target.
706
+
707
+ [source,asciidoc]
708
+ ----
709
+ image::custom-page.pdf[]
710
+ ----
711
+
712
+ 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).
713
+ Therefore, there's no need to put a manual page break (i.e., `<<<`) around the image macro.
714
+
715
+ By default, this macro will import the first page of the PDF.
716
+ To import a different page, specify it as a 1-based index using the `page` attribute.
717
+
718
+ [source,asciidoc]
719
+ ----
720
+ image::custom-pages.pdf[page=2]
721
+ ----
722
+
723
+ You can import multiple pages either using multiple image macros or using the `pages` attribute.
724
+ The `pages` attribute accepts individual page numbers or page number ranges (two page numbers separated by `..`).
725
+ The values can be separated either by commas or semi-colons.
726
+ (The syntax is similar to the syntax uses for the `lines` attribute of the AsciiDoc include directive).
727
+
728
+ [source,asciidoc]
729
+ ----
730
+ image::custom-pages.pdf[pages=3;1..2]
731
+ ----
732
+
733
+ Pages are imported in the order listed.
734
+
735
+ 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].
736
+
737
+ CAUTION: An image macro used to imports PDF pages should never be nested inside a delimited block or table cell.
738
+ It should be a direct descendant of the document or a section.
739
+ That's because what it imports are entire pages.
740
+ If it's used inside a delimited block or table cell, the behavior is unspecified.
741
+
742
+ == Crafting Interdocument Xrefs
743
+
744
+ This converter produces a single PDF file, which means content from multiple source documents get colocated into the same output file.
745
+ That means references between documents must necessarily become internal references.
746
+ These interdocument cross references (i.e., xrefs) will only successfully make that transition if you structure your document in accordance with the rules.
747
+
748
+ Those rules are as follows:
749
+
750
+ . The path segment of the interdocument xref must match the project-relative path of the included document
751
+ . The reference must include the ID of the target element
752
+
753
+ For instance, if your primary document contains the following include:
754
+
755
+ [source,asciidoc]
756
+ ----
757
+ \include::chapters/chapter-1.adoc[]
758
+ ----
759
+
760
+ Then an interdocument xref to an anchor in that chapter must be expressed as:
499
761
 
500
- Once this gem is installed, Asciidoctor automatically switches over to it to handle embedding of all images.
501
- 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.
762
+ [source,asciidoc]
763
+ ----
764
+ <<chapters/chapter-1.adoc#_anchor_name,Destination in Chapter 1>>
765
+ ----
766
+
767
+ This rule holds regardless of which document the xref is located in.
768
+
769
+ To resolve the interdocument xref, the converter first checks if the target matches the `docname` attribute.
770
+ It then looks to see if the target matches one of the included files.
771
+ (In both cases, it ignores the file extension).
772
+ If Asciidoctor cannot resolve the target of an interdocument xref, it simply makes a link (like the HTML converter).
773
+
774
+ Let's consider a complete example.
775
+ Assume you are converting the following book document at the root of the project:
776
+
777
+ [source,asciidoc]
778
+ ----
779
+ = Book Title
780
+ :doctype: book
781
+
782
+ \include::chapters/chapter-1.adoc[]
783
+
784
+ \include::chapters/chapter-2.adoc[]
785
+ ----
786
+
787
+ Where the contents of chapter 1 is as follows:
788
+
789
+ [source,asciidoc]
790
+ ----
791
+ == Chapter 1
792
+
793
+ We cover a little bit here.
794
+ The rest you can find in <<chapters/chapter-2.adoc#_chapter_2,Chapter 2>>.
795
+ ----
796
+
797
+ And the contents of chapter 2 is as follows:
798
+
799
+ [source,asciidoc]
800
+ ----
801
+ == Chapter 2
802
+
803
+ Prepare to be educated.
804
+ This chapter has it all!
805
+
806
+ To begin, jump to <<chapters/chapter-2/first-steps.adoc#_first_steps,first steps>>.
807
+
808
+ <<<
809
+
810
+ \include::chapter-2/first-steps.adoc[]
811
+ ----
812
+
813
+ And, finally, the contents of the nested include is as follows:
814
+
815
+ [source,asciidoc]
816
+ ----
817
+ === First Steps
818
+
819
+ Let's start small.
820
+ ----
821
+
822
+ You'll find when you run this example that all the interdocument xrefs become internal references in the PDF.
823
+
824
+ The reason both the path and anchor are required (even when linking to the top of a chapter) is so the interdocument xref works independent of the converter.
825
+ In other words, it encodes the complete information about the reference so the converter can sort out where the target is in all circumstances.
502
826
 
503
827
  == STEM Support
504
828
 
@@ -519,13 +843,13 @@ That prototype can be found in the https://github.com/asciidoctor/asciidoctor-ex
519
843
 
520
844
  === Asciidoctor Mathematical
521
845
 
522
- {uri-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros (currently only latexmath).
846
+ {url-asciidoctor-mathematical}[Asciidoctor Mathematical] is an extension for Asciidoctor that provides alternate processing of STEM blocks and inline macros (currently only latexmath).
523
847
  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.
524
848
  Conversion then proceeds as normal.
525
849
 
526
850
  Asciidoctor Mathematical is a Ruby gem that uses native extensions.
527
851
  It has a few system prerequisites which limit installation to Linux and OSX.
528
- Please refer to the {uri-asciidoctor-mathematical}#installation[installation section] in the Asciidoctor Mathematical README to learn how to install it.
852
+ Please refer to the {url-asciidoctor-mathematical}#installation[installation section] in the Asciidoctor Mathematical README to learn how to install it.
529
853
 
530
854
  Once Asciidoctor Mathematical is installed, you just need to enable it when invoking Asciidoctor PDF using the `-r` flag:
531
855
 
@@ -545,7 +869,7 @@ You control this setting using the `mathematical-format` AsciiDoc attribute:
545
869
 
546
870
  $ asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg sample.adoc
547
871
 
548
- Refer to the {uri-asciidoctor-mathematical}#readme[README] for Asciidoctor Mathematical to learn about additional settings and options.
872
+ Refer to the {url-asciidoctor-mathematical}#readme[README] for Asciidoctor Mathematical to learn about additional settings and options.
549
873
 
550
874
  == Skipping Passthrough Content
551
875
 
@@ -590,10 +914,11 @@ Therefore, the long lines are forced to wrap.
590
914
  Wrapped lines can make the verbatim blocks hard to read or even cause confusion.
591
915
 
592
916
  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.
593
- When the `autofit` option is enabled, Asciidoctor PDF will decrease the font size until the longest line fits without wrapping.
917
+ 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.
594
918
 
595
- CAUTION: The font size will not be decreased beyond the value of the `base_font_size_min` key specified in the PDF theme.
919
+ CAUTION: The converter will not shrink the font size beyond the value of the `base_font_size_min` key specified in the PDF theme.
596
920
  If that threshold is reached, lines may still wrap.
921
+ To allow `autofit` to handle all cases, set `base_font_size_min` to `0` in your theme.
597
922
 
598
923
  Here's an example of the autofit option enabled on a source block:
599
924
 
@@ -619,6 +944,30 @@ If you want to enable the autofit option globally, set the `autofit-option` docu
619
944
  :autofit-option:
620
945
  ----
621
946
 
947
+ == Autowidth Tables
948
+
949
+ Asciidoctor PDF does support autowidth tables.
950
+ However, the behavior differs from HTML when the content forces the table to the page boundary.
951
+ The behavior, which is handled by the prawn-table library, is explained in this section.
952
+
953
+ If the natural width of all columns (based on the width of the cell content) is less than the width of the page, it behaves as you'd expect.
954
+ Each column is assigned the width it needs to prevent the content from wrapping.
955
+
956
+ However, when the natural width of all columns exceeds the width of the page, the behavior may not be what you expect.
957
+ What prawn-table does is compute how to arrange the table on an infinite canvas, where each column can have a width no greater than the width of the page.
958
+ Then, it reduces the width of the table by reducing the width of each column proportionally.
959
+ As a result, columns which reported the width necessary to render without wrapping now no longer do.
960
+
961
+ The reason this compression is not performed like in HTML is because prawn-table has no awareness of words.
962
+ Thus, it doesn't know how to redistribute with width intelligently.
963
+
964
+ To protected against truncation or insufficient width errors, prawn-table wraps text by character.
965
+ That's why the last character in the cell can end up getting wrapped.
966
+ (There's a small amount of tolerance built in to prawn-table to address some edge cases, but it's not sufficient to handle all of them).
967
+
968
+ For the reason just explained, you should be extremely careful with relying on autowidth tables in Asciidoctor PDF, especially when the natural content of the cells forces the table to page boundary.
969
+ Let experience be your guide.
970
+
622
971
  == Printing Page Ranges
623
972
 
624
973
  The print dialog doesn't understand the page numbers labels (which appear in the running content).
@@ -678,27 +1027,35 @@ However, you could use an extension, such as a TreeProcessor, to automatically m
678
1027
 
679
1028
  == Optimizing the Generated PDF
680
1029
 
681
- === optimize-pdf
1030
+ By default, Asciidoctor PDF does not optimize the output document or even compress the streams.
1031
+ The simplest way to reduce the size of the file is to enable stream compression (using the FlateDecode method).
1032
+ You can enable this feature by setting the `compress` attribute on the document:
682
1033
 
683
- {project-name} also provides a shell script that uses GhostScript (`gs`) to optimize and compress the generated PDF (with minimal impact on quality).
684
- You must have Ghostscript installed to use it.
1034
+ $ asciidoctor-pdf -a compress document.adoc
685
1035
 
686
- Here's an example usage:
1036
+ For more thorough optimzation, you can use either the built-in `asciidoctor-pdf-optimize` script or hexapdf.
1037
+ Read on to learn how.
687
1038
 
688
- $ ./bin/optimize-pdf basic-example.pdf
1039
+ === asciidoctor-pdf-optimize
689
1040
 
690
- The command will generate the file [.path]_basic-example-optimized.pdf_ in the same directory.
1041
+ {project-name} also provides a bin script that uses GhostScript to optimize and compress the generated PDF (with minimal impact on quality).
1042
+ You must have Ghostscript (command: `gs`) and the `rghost` gem installed to use it.
691
1043
 
692
- WARNING: The `optimize-pdf` script currently requires a Bash shell (Linux, OSX, etc).
693
- We plan to rewrite the script in Ruby so it works across platforms (see https://github.com/asciidoctor/asciidoctor-pdf/issues/1[issue #1])
1044
+ Here's an example usage:
1045
+
1046
+ $ asciidoctor-pdf-optimize basic-example.pdf
1047
+
1048
+ The command will overwrite the PDF file with an optimized version.
694
1049
 
695
1050
  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.
696
1051
  This file is necessary to preserve the document metadata since Ghostscript will otherwise drop it.
697
1052
  That's why {project-name} always creates this file in addition to the PDF.
698
1053
 
699
- IMPORTANT: The `optimize-pdf` script relies on Ghostscript >= 9.10.
700
- Otherwise, it may actually make the PDF larger.
701
- You should probably only consider using it if the file size of the original PDF is > 5MB.
1054
+ IMPORTANT: The `asciidoctor-pdf-optimize` is not guaranteed to reduce the size of the PDF file.
1055
+ It may actually make the PDF larger.
1056
+ You should probably only consider using it if the file size of the original PDF is several megabytes.
1057
+ You can also try reducing the quality of the output file using the `--quality` flag (e.g., `--quality screen`).
1058
+ The `--quality` flag accepts the following keywords: `default` (default), `screen`, `ebook`, `printer`, and `prepress`.
702
1059
 
703
1060
  === hexapdf
704
1061
 
@@ -729,171 +1086,8 @@ hexapdf also allows you to add password protection to your PDF, if that's someth
729
1086
  ifndef::env-site[]
730
1087
  == Contributing
731
1088
 
732
- In the spirit of free software, _everyone_ is encouraged to help improve this project.
733
-
734
- To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
735
- *All pull requests must include a) tests that verify the code change and b) an entry in the CHANGELOG.adoc file to document what changed.*
736
- If a pull request is missing tests or a CHANGELOG entry, *it will not be merged*.
737
-
738
- 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.
739
-
740
- == Development
741
-
742
- To help develop {project-name}, or to simply use the development version, you need to get the source from GitHub.
743
- Follow the instructions below to learn how to clone the source and run it from your local copy.
744
-
745
- === Retrieve the Source Code
746
-
747
- You can retrieve the source of {project-name} in one of two ways:
748
-
749
- . Clone the git repository
750
- . Download a zip archive of the repository
751
-
752
- ==== Option 1: Fetch Using Git
753
-
754
- If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to the `git clone` command:
755
-
756
- $ git clone https://github.com/asciidoctor/asciidoctor-pdf
757
-
758
- Next, change to the project directory:
759
-
760
- $ cd asciidoctor-pdf
761
-
762
- ==== Option 2: Download the Archive
763
-
764
- 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.
765
- Once the download finishes, extract the archive, open a console and change to that directory.
766
-
767
- 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.
768
-
769
- We'll leverage the project configuration to install the necessary dependencies.
770
-
771
- === Install Dependencies
772
-
773
- If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:
774
-
775
- $ rvm use 2.5@asciidoctor-pdf --create
776
-
777
- We like RVM because it keeps the dependencies required by various projects isolated.
778
-
779
- The dependencies needed to use {project-name} are defined in the [.path]_Gemfile_ at the root of the project.
780
- We can use Bundler to install the dependencies for us.
781
-
782
- To check you have Bundler available, use the `bundle` command to query the installed version:
783
-
784
- $ bundle --version
785
-
786
- If it's not installed, use the `gem` command to install it.
787
-
788
- $ gem install bundler
789
-
790
- Then use the `bundle` command to install the project dependencies:
791
-
792
- $ bundle
793
-
794
- NOTE: You need to call `bundle` from the project directory so that it can find the [.path]_Gemfile_.
795
-
796
- === Run the Tests
797
-
798
- Tests are written using RSpec.
799
- To run the tests, simply invoke rspec via bundler.
800
-
801
- $ bundle exec rspec
802
-
803
- To disable the visual integration tests, pass the `` option:
804
-
805
- $ bundle exec rspec -t ~integration
806
-
807
- 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:
808
-
809
- $ DEBUG=true bundle exec rspec -t integration
810
-
811
- If you want to see the name of each test as it is run, add the `-fd` option:
812
-
813
- $ bundle exec rspec -fd
814
-
815
- You can also use the provided Rake task (note the name difference):
816
-
817
- $ bundle exec rake spec
818
-
819
- Running tests using `rspec` directly gives you the advantage of being able to specify additional options.
820
-
821
- To run a single test, you can filter by the name of the test.
822
- For example, to run all tests that pertain to failures, use:
823
-
824
- $ bundle exec rspec -e fail
825
-
826
- To run all tests that have `wip` in the name, use:
827
-
828
- $ bundle exec rspec -e wip
829
-
830
- You can also run all tests in a given file by passing the file's path to rspec:
831
-
832
- $ bundle exec rspec spec/toc_spec.rb
833
-
834
- For a full list of options that rspec provides, run `rspec -h`.
835
-
836
- === Run the Application (optional)
837
-
838
- Like with Bundler, you have to run the application from the project directory.
839
- Assuming all the required gems install properly, verify you can run the `asciidoctor-pdf` script using Ruby:
840
-
841
- $ bundle exec asciidoctor-pdf -v
842
-
843
- If you see the version of {project-name} printed, you're ready to use {project-name}!
844
-
845
- You can use the application to convert a document as follows:
846
-
847
- $ bundle exec asciidoctor-pdf /path/to/sample.adoc
848
-
849
- === Install the Application (optional)
850
-
851
- If you want to install the application globally so you can run it anywhere, use the following `rake` task:
852
-
853
- $ bundle exec rake install
854
-
855
- This task will package the gem and install it into your system gems.
856
-
857
- If you want to install the gem using a separate command, first use the following `rake` task to build it:
858
-
859
- $ rm -rf pkg
860
- bundle exec rake build
861
-
862
- This task packages the application as a gem and writes it to the [.path]_pkg_ directory.
863
- A message will be printed to the console telling you the exact filename.
864
- You can now use the `gem install` command to install it.
865
-
866
- $ gem install pkg/*.gem
867
-
868
- You'll want to pay attention to which Ruby installation you are installing the gem into.
869
- If successful, the `asciidoctor-pdf` executable will be available on your PATH.
870
-
871
- endif::[]
872
-
873
- === Test a Pull Request
874
-
875
- To test a pull request (PR), you first need to fetch the branch that contains the change and switch to it.
876
- The steps below are covered in detail in the https://help.github.com/articles/checking-out-pull-requests-locally[GitHub help].
877
-
878
- Let's assume you want to test PR 955.
879
- Here's how you fetch and switch to it:
880
-
881
- $ git fetch origin pull/955/head:pr-955-review
882
- git checkout pr-955-review
883
-
884
- IMPORTANT: Make sure you replace the number with the number of the PR you want to test.
885
-
886
- In case any dependencies have changed, you should run the `bundle` command again:
887
-
888
- $ bundle
889
-
890
- Now you can run the application as modified by the PR:
891
-
892
- $ bundle exec asciidoctor-pdf /path/to/sample.adoc
893
-
894
- To switch back to master, just type:
895
-
896
- $ git checkout master
1089
+ See the <<CONTRIBUTING.adoc#,contributing guide>>.
1090
+ To help develop {project-name}, or to simply use the development version, refer to the <<CONTRIBUTING-CODE.adoc#,developing and contributing code guide>>.
897
1091
 
898
1092
  [[resources,Links]]
899
1093
  == Resources
@@ -906,8 +1100,8 @@ To switch back to master, just type:
906
1100
 
907
1101
  == Copyright
908
1102
 
909
- Copyright (C) 2014-2019 OpenDevise Inc. and the Asciidoctor Project.
1103
+ Copyright (C) 2014-2020 OpenDevise Inc. and the Asciidoctor Project.
910
1104
  Free use of this software is granted under the terms of the MIT License.
911
1105
 
912
- For the full text of the license, see the <<LICENSE#,LICENSE>> file.
913
- Refer to the <<NOTICE#,NOTICE>> file for information about third-party Open Source software in use.
1106
+ For the full text of the license, see the <<LICENSE.adoc#,LICENSE>> file.
1107
+ Refer to the <<NOTICE.adoc#,NOTICE>> file for information about third-party Open Source software in use.