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.
- checksums.yaml +4 -4
- data/CHANGELOG.adoc +277 -2
- data/LICENSE.adoc +1 -1
- data/NOTICE.adoc +1 -1
- data/README.adoc +486 -292
- data/asciidoctor-pdf.gemspec +12 -11
- data/bin/asciidoctor-pdf +2 -6
- data/bin/asciidoctor-pdf-optimize +20 -0
- data/data/fonts/ABOUT-mplus1mn-subset +26 -0
- data/data/fonts/ABOUT-mplus1p-subset +26 -0
- data/data/fonts/ABOUT-notoemoji-subset +3 -0
- data/data/fonts/ABOUT-notoserif-subset +26 -0
- data/data/fonts/{LICENSE-mplus-testflight-58 → LICENSE-mplus} +2 -2
- data/data/fonts/{LICENSE-noto-2015-06-05 → LICENSE-notoserif} +0 -0
- data/data/fonts/mplus1mn-bold-ascii.ttf +0 -0
- data/data/fonts/mplus1mn-bold-subset.ttf +0 -0
- data/data/fonts/mplus1mn-bold_italic-ascii.ttf +0 -0
- data/data/fonts/mplus1mn-bold_italic-subset.ttf +0 -0
- data/data/fonts/mplus1mn-italic-ascii.ttf +0 -0
- data/data/fonts/mplus1mn-italic-subset.ttf +0 -0
- data/data/fonts/mplus1mn-regular-ascii-conums.ttf +0 -0
- data/data/fonts/mplus1mn-regular-subset.ttf +0 -0
- data/data/fonts/mplus1p-regular-fallback.ttf +0 -0
- data/data/fonts/notoemoji-subset.ttf +0 -0
- data/data/fonts/notoserif-bold-subset.ttf +0 -0
- data/data/fonts/notoserif-bold_italic-subset.ttf +0 -0
- data/data/fonts/notoserif-italic-subset.ttf +0 -0
- data/data/fonts/notoserif-regular-subset.ttf +0 -0
- data/data/themes/base-theme.yml +22 -4
- data/data/themes/default-theme.yml +59 -29
- data/data/themes/default-with-fallback-font-theme.yml +4 -17
- data/docs/theming-guide.adoc +1647 -167
- data/lib/asciidoctor/pdf/converter.rb +4489 -0
- data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/abstract_block.rb +2 -0
- data/lib/asciidoctor/pdf/ext/asciidoctor/abstract_node.rb +7 -0
- data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/document.rb +2 -0
- data/lib/asciidoctor/pdf/ext/asciidoctor/image.rb +35 -0
- data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/list.rb +4 -2
- data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/list_item.rb +3 -1
- data/lib/asciidoctor/pdf/ext/asciidoctor/logging_shim.rb +33 -0
- data/lib/{asciidoctor-pdf/asciidoctor_ext → asciidoctor/pdf/ext/asciidoctor}/section.rb +9 -6
- data/lib/asciidoctor/pdf/ext/asciidoctor.rb +11 -0
- data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/array.rb +6 -0
- data/lib/asciidoctor/pdf/ext/core/file.rb +9 -0
- data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/hash.rb +2 -0
- data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/numeric.rb +5 -3
- data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/object.rb +3 -1
- data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/quantifiable_stdout.rb +9 -1
- data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/regexp.rb +2 -0
- data/lib/{asciidoctor-pdf/core_ext → asciidoctor/pdf/ext/core}/string.rb +9 -13
- data/lib/asciidoctor/pdf/ext/core.rb +10 -0
- data/lib/asciidoctor/pdf/ext/pdf-core/page.rb +54 -0
- data/lib/asciidoctor/pdf/ext/pdf-core/pdf_object.rb +8 -0
- data/lib/asciidoctor/pdf/ext/pdf-core.rb +4 -0
- data/lib/asciidoctor/pdf/ext/prawn/coderay_encoder.rb +117 -0
- data/lib/asciidoctor/pdf/ext/prawn/extensions.rb +922 -0
- data/lib/{asciidoctor-pdf/prawn_ext → asciidoctor/pdf/ext/prawn}/font/afm.rb +14 -10
- data/lib/asciidoctor/pdf/ext/prawn/font_metric_cache.rb +9 -0
- data/lib/asciidoctor/pdf/ext/prawn/formatted_text/box.rb +66 -0
- data/lib/{asciidoctor-pdf/prawn_ext → asciidoctor/pdf/ext/prawn}/formatted_text/fragment.rb +16 -12
- data/lib/asciidoctor/pdf/ext/prawn/images.rb +54 -0
- data/lib/asciidoctor/pdf/ext/prawn-svg/interface.rb +14 -0
- data/lib/{asciidoctor-pdf/prawn-svg_ext.rb → asciidoctor/pdf/ext/prawn-svg.rb} +3 -1
- data/lib/asciidoctor/pdf/ext/prawn-table/cell/asciidoc.rb +76 -0
- data/lib/{asciidoctor-pdf/prawn-table_ext → asciidoctor/pdf/ext/prawn-table}/cell/text.rb +6 -3
- data/lib/{asciidoctor-pdf/prawn-table_ext → asciidoctor/pdf/ext/prawn-table}/cell.rb +10 -10
- data/lib/asciidoctor/pdf/ext/prawn-table.rb +6 -0
- data/lib/{asciidoctor-pdf/prawn-templates_ext.rb → asciidoctor/pdf/ext/prawn-templates.rb} +2 -0
- data/lib/asciidoctor/pdf/ext/prawn.rb +9 -0
- data/lib/asciidoctor/pdf/ext/pygments.rb +34 -0
- data/lib/asciidoctor/pdf/ext/rouge/formatters/prawn.rb +208 -0
- data/lib/{asciidoctor-pdf/rouge_ext → asciidoctor/pdf/ext/rouge}/themes/asciidoctor_pdf_default.rb +2 -0
- data/lib/asciidoctor/pdf/ext/rouge.rb +5 -0
- data/lib/asciidoctor/pdf/ext.rb +9 -0
- data/lib/asciidoctor/pdf/formatted_text/formatter.rb +43 -0
- data/lib/asciidoctor/pdf/formatted_text/fragment_position_renderer.rb +14 -0
- data/lib/asciidoctor/pdf/formatted_text/inline_destination_marker.rb +21 -0
- data/lib/asciidoctor/pdf/formatted_text/inline_image_arranger.rb +134 -0
- data/lib/asciidoctor/pdf/formatted_text/inline_image_renderer.rb +51 -0
- data/lib/asciidoctor/pdf/formatted_text/inline_text_aligner.rb +22 -0
- data/lib/{asciidoctor-pdf → asciidoctor/pdf}/formatted_text/parser.rb +31 -7
- data/lib/{asciidoctor-pdf → asciidoctor/pdf}/formatted_text/parser.treetop +3 -4
- data/lib/asciidoctor/pdf/formatted_text/source_wrap.rb +43 -0
- data/lib/asciidoctor/pdf/formatted_text/text_background_and_border_renderer.rb +55 -0
- data/lib/asciidoctor/pdf/formatted_text/transform.rb +394 -0
- data/lib/{asciidoctor-pdf → asciidoctor/pdf}/formatted_text.rb +4 -0
- data/lib/asciidoctor/pdf/index_catalog.rb +133 -0
- data/lib/asciidoctor/pdf/measurements.rb +62 -0
- data/lib/asciidoctor/pdf/optimizer.rb +44 -0
- data/lib/asciidoctor/pdf/pdfmark.rb +41 -0
- data/lib/asciidoctor/pdf/roman_numeral.rb +128 -0
- data/lib/asciidoctor/pdf/sanitizer.rb +45 -0
- data/lib/asciidoctor/pdf/text_transformer.rb +116 -0
- data/lib/asciidoctor/pdf/theme_loader.rb +305 -0
- data/lib/asciidoctor/pdf/version.rb +8 -1
- data/lib/asciidoctor/pdf.rb +15 -1
- data/lib/asciidoctor-pdf/converter.rb +2 -3824
- data/lib/asciidoctor-pdf/version.rb +3 -6
- data/lib/asciidoctor-pdf.rb +3 -4
- metadata +130 -85
- data/lib/asciidoctor-pdf/asciidoctor_ext/image.rb +0 -24
- data/lib/asciidoctor-pdf/asciidoctor_ext/logging_shim.rb +0 -25
- data/lib/asciidoctor-pdf/asciidoctor_ext.rb +0 -8
- data/lib/asciidoctor-pdf/core_ext/ostruct.rb +0 -8
- data/lib/asciidoctor-pdf/core_ext.rb +0 -6
- data/lib/asciidoctor-pdf/formatted_text/formatter.rb +0 -40
- data/lib/asciidoctor-pdf/formatted_text/inline_destination_marker.rb +0 -21
- data/lib/asciidoctor-pdf/formatted_text/inline_image_arranger.rb +0 -160
- data/lib/asciidoctor-pdf/formatted_text/inline_image_renderer.rb +0 -46
- data/lib/asciidoctor-pdf/formatted_text/inline_text_aligner.rb +0 -20
- data/lib/asciidoctor-pdf/formatted_text/text_background_and_border_renderer.rb +0 -45
- data/lib/asciidoctor-pdf/formatted_text/transform.rb +0 -294
- data/lib/asciidoctor-pdf/implicit_header_processor.rb +0 -63
- data/lib/asciidoctor-pdf/index_catalog.rb +0 -127
- data/lib/asciidoctor-pdf/measurements.rb +0 -58
- data/lib/asciidoctor-pdf/pdf-core_ext/page.rb +0 -25
- data/lib/asciidoctor-pdf/pdf-core_ext/pdf_object.rb +0 -6
- data/lib/asciidoctor-pdf/pdf-core_ext.rb +0 -2
- data/lib/asciidoctor-pdf/pdfmark.rb +0 -33
- data/lib/asciidoctor-pdf/prawn-svg_ext/interface.rb +0 -10
- data/lib/asciidoctor-pdf/prawn-table_ext/cell/asciidoc.rb +0 -69
- data/lib/asciidoctor-pdf/prawn-table_ext.rb +0 -4
- data/lib/asciidoctor-pdf/prawn_ext/coderay_encoder.rb +0 -115
- data/lib/asciidoctor-pdf/prawn_ext/extensions.rb +0 -904
- data/lib/asciidoctor-pdf/prawn_ext/images.rb +0 -51
- data/lib/asciidoctor-pdf/prawn_ext.rb +0 -5
- data/lib/asciidoctor-pdf/roman_numeral.rb +0 -126
- data/lib/asciidoctor-pdf/rouge_ext/formatters/prawn.rb +0 -175
- data/lib/asciidoctor-pdf/rouge_ext/themes/bw.rb +0 -38
- data/lib/asciidoctor-pdf/rouge_ext.rb +0 -4
- data/lib/asciidoctor-pdf/sanitizer.rb +0 -101
- data/lib/asciidoctor-pdf/temporary_path.rb +0 -13
- data/lib/asciidoctor-pdf/theme_loader.rb +0 -280
- 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
|
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
|
26
|
+
:release-version: 1.5.0
|
28
27
|
// URIs:
|
29
|
-
:
|
30
|
-
:
|
31
|
-
:
|
32
|
-
:
|
33
|
-
:
|
34
|
-
:
|
35
|
-
:
|
36
|
-
:
|
37
|
-
:
|
38
|
-
:
|
39
|
-
:
|
40
|
-
:
|
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://
|
45
|
-
image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={
|
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
|
52
|
-
Instead, you can use
|
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
|
-
==
|
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
|
-
|
87
|
-
|
88
|
-
|
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
|
-
|
92
|
-
|
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
|
96
|
-
|
97
|
-
|
98
|
-
|
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
|
-
*
|
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
|
-
*
|
118
|
-
*
|
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}
|
152
|
-
|
153
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
249
|
-
|
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
|
-
|
252
|
-
|
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
|
-
|
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
|
-
|
257
|
-
|
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
|
-
|
263
|
-
|
264
|
-
|
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
|
-
|
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
|
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
|
342
|
-
|
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,
|
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
|
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
|
-
|
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 {
|
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
|
-
{
|
489
|
-
{
|
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 {
|
493
|
-
prawn-gmagick is an extension for Prawn based on {
|
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 {
|
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
|
-
|
501
|
-
|
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
|
-
{
|
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 {
|
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 {
|
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
|
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
|
-
|
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
|
-
|
684
|
-
You must have Ghostscript installed to use it.
|
1034
|
+
$ asciidoctor-pdf -a compress document.adoc
|
685
1035
|
|
686
|
-
|
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
|
-
|
1039
|
+
=== asciidoctor-pdf-optimize
|
689
1040
|
|
690
|
-
|
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
|
-
|
693
|
-
|
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 `
|
700
|
-
|
701
|
-
You should probably only consider using it if the file size of the original PDF is
|
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
|
-
|
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-
|
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.
|