diff options
Diffstat (limited to 'docs/modules')
| -rw-r--r-- | docs/modules/ROOT/pages/asciidoc-attributes.adoc | 2 | ||||
| -rw-r--r-- | docs/modules/ROOT/pages/background-images.adoc | 1 | ||||
| -rw-r--r-- | docs/modules/ROOT/pages/breakable-and-unbreakable.adoc | 3 | ||||
| -rw-r--r-- | docs/modules/ROOT/pages/features.adoc | 4 | ||||
| -rw-r--r-- | docs/modules/ROOT/pages/whats-new.adoc | 35 | ||||
| -rw-r--r-- | docs/modules/extend/pages/index.adoc | 2 | ||||
| -rw-r--r-- | docs/modules/extend/pages/use-cases.adoc | 9 | ||||
| -rw-r--r-- | docs/modules/theme/pages/add-running-content.adoc | 2 | ||||
| -rw-r--r-- | docs/modules/theme/pages/heading.adoc | 2 | ||||
| -rw-r--r-- | docs/modules/theme/pages/page-numbers.adoc | 2 | ||||
| -rw-r--r-- | docs/modules/theme/pages/page.adoc | 2 | ||||
| -rw-r--r-- | docs/modules/theme/pages/text.adoc | 2 |
12 files changed, 39 insertions, 27 deletions
diff --git a/docs/modules/ROOT/pages/asciidoc-attributes.adoc b/docs/modules/ROOT/pages/asciidoc-attributes.adoc index 3e2b3824..2fe1a44a 100644 --- a/docs/modules/ROOT/pages/asciidoc-attributes.adoc +++ b/docs/modules/ROOT/pages/asciidoc-attributes.adoc @@ -101,7 +101,7 @@ If an attribute matches a key in the theme file, the document attribute takes pr |`pdf-page-margin-rotated` |xref:theme:measurement-units.adoc[Measurement] {vbar} xref:theme:measurement-units.adoc[Measurement[top,right,bottom,left\]] |Yes -|`:pdf-page-margin: [0.5in, 0.25in]` +|`:pdf-page-margin-rotated: [0.5in, 0.25in]` |`pdf-page-mode` |`outline` {vbar} `none` {vbar} `thumbs` {vbar} `fullscreen` {vbar} `fullscreen outline` {vbar} `fullscreen none` {vbar} `fullscreen thumbs` (default: `outline`) diff --git a/docs/modules/ROOT/pages/background-images.adoc b/docs/modules/ROOT/pages/background-images.adoc index 9d45b071..4c368f40 100644 --- a/docs/modules/ROOT/pages/background-images.adoc +++ b/docs/modules/ROOT/pages/background-images.adoc @@ -133,6 +133,7 @@ If a background image is assigned to the recto pages (right-hand, odd-numbered p If a background image isn't specified for a side, the converter will use the default page background image (`page-background-image`), if specified. To turn off the background image for a side, assign the value `none`. +[#page-layout] == Per page layout You can configure any background image to be selected per page layout by including the _escaped_ `+{page-layout}+` attribute reference in the image path. diff --git a/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc b/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc index 5cb8b0a3..1253fd35 100644 --- a/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc +++ b/docs/modules/ROOT/pages/breakable-and-unbreakable.adoc @@ -54,7 +54,8 @@ The `breakable` option can be applied to a table to ensure the anchor and title ---- <.> Assign the `breakable` option to a table, using the shorthand percent symbol (`%`) for the `option` attribute name, to indicate that the table's title and anchor should be kept with the table. -=== Section or Discrete Heading +[#section-or-discrete-heading] +=== Section or discrete heading The `breakable` option can be applied to a section to ensure the section title is kept with the first child block if that block gets advanced to the following page. diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc index 8b088a76..17cdde85 100644 --- a/docs/modules/ROOT/pages/features.adoc +++ b/docs/modules/ROOT/pages/features.adoc @@ -35,7 +35,7 @@ == Known limitations * Copying text from a PDF in a way that preserves the original line wrapping is not reliable, particularly in code blocks. -To achieve proper rendering, non-visible characters may either be interpretted, inserted, or dropped. +To achieve proper rendering, non-visible characters may either be interpreted, inserted, or dropped. This is primarily a limitation of the PDF format, in which text is broken into fragments and positioned at absolute coordinates on the canvas. * Footnotes are always displayed as endnotes (at the bottom of the last page of a chapter for books; at the bottom of the last page of the document for all other doctypes). *Footnotes cannot be displayed at the current bottom of the page because the PDF generator does not support content reflows* (see {url-project-issues}/85#issuecomment-577412975[#85^] for reasoning). @@ -56,7 +56,7 @@ This matches the behavior of HTML. * If a no-break hyphen is surrounded by formatted text on both sides (or is formatted individually), it will not prevent a line break. * The `float` attribute on an image (i.e., an image float) is only supported for block images, not inline images. The converter will clear the float at the next non-paragraph or when the paragraph content clears the bottom of the image. -See xref:extend:use-cases.adoc#wrap-code-blocks-around-an-image-float[Wrap code blocks around an image float] to learn how to wrap non-paragraph blocks around an image float. +See xref:extend:use-cases.adoc#wrap-code-blocks-around-image[Wrap code blocks around an image float] to learn how to wrap non-paragraph blocks around an image float. * Multiple columns are not supported in the book doctype. * You cannot use inline HTML (like a link or emphasized text) in a source block that also uses syntax highlighting. These two technologies don't mix in the PDF generation process due to how the syntax highlighters work. diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc index 168d0481..153cb19a 100644 --- a/docs/modules/ROOT/pages/whats-new.adoc +++ b/docs/modules/ROOT/pages/whats-new.adoc @@ -12,28 +12,37 @@ The releases are ordered from newest to oldest. = Asciidoctor PDF {page-component-version}.0 -_**Release date:** 2022.07.00 | *Release notes:* {url-project-repo}/releases/tag/v2.2.0[v{page-component-version}.0^] | *Issue label:* {url-milestone-2-2-0}[{page-component-version}.0^]_ +_**Release date:** 2022.07.22 | *Release notes:* {url-project-repo}/releases/tag/v2.2.0[v{page-component-version}.0^] | *Issue label:* {url-milestone-2-2-0}[{page-component-version}.0^]_ -Asciidoctor PDF {page-component-version} introduces several enhancements. +Asciidoctor PDF {page-component-version}.0 introduces several enhancements. For a complete list of changes, see the {url-project-repo}/blob/main/CHANGELOG.adoc[CHANGELOG^]. == Enhancements -* Allow page background image to be specified per layout using `+{page-layout}+` attribute reference in path. -* Allow page margin for rotated page to be configured independently using `page-margin-rotated` theme key or `pdf-page-margin-rotated` document attribute. -* Allow orphan detection to be enabled for all section titles and discrete headings by setting `heading-min-height-after` to `auto` in the theme. -* Set `docimagesdir` attribute when attribute substitutions are applied to a value from the theme. -* Start page numbering and running content on empty verso page before first chapter of prepress book if `start-at` value is `0`. -* Don't force page break after TOC with automatic placement in article if `title-page` attribute is set and value of `toc-break-after` theme key is `auto`. +* Allow a xref:background-images.adoc#page-layout[page background image to be specified per layout] using the `+{page-layout}+` attribute reference in the target path. +* Allow the page margins for rotated pages to be configured independently using the xref:theme:page.adoc#rotated-margin[page-margin-rotated theme key] or xref:asciidoc-attributes.adoc[pdf-page-margin-rotated document attribute]. +* Allow xref:breakable-and-unbreakable.adoc#section-or-discrete-heading[orphan detection to be enabled for all section titles and discrete headings] by setting xref:theme:heading.adoc#min-height-after[heading-min-height-after] to `auto` in the theme. +* Set the xref:theme:images.adoc#specify[docimagesdir attribute] when attribute substitutions are applied to a value from the theme. +* Start xref:theme:page-numbers.adoc[page numbering] and xref:theme:add-running-content.adoc#page[running content] on empty verso page before first chapter of prepress book if `start-at` value is `0`. +* Don't force a page break after a TOC with automatic placement in an article if the `title-page` attribute is set and the xref:theme:toc.adoc[value of toc-break-after theme key is auto]. * Add `--theme` option to CLI as shorthand for `-a pdf-theme`. -* Add `--sourcemap` option to CLI to enable `:sourcemap` option on processor. -* Broaden support for relative font sizes in theme to more than just inline elements; document support for relative font sizes. +* Add `--sourcemap` option to CLI to enable `:sourcemap` option. +* Broaden support for xref:theme:text.adoc#font-size[relative font sizes in the theme] to more than just inline elements. +* Allow the theme to control the font properties of ordered list markers using the xref:theme:list.adoc#olist-marker[olist-marker category]. +* Allow the theme to control the xref:theme:list.adoc#ulist-marker[font style of unordered list markers] per marker or all markers. == Bug fixes -* Always set `imagesdir` attribute to value of `themesdir` when resolving images from theme. +* Always set the `imagesdir` attribute to the value of `themesdir` when resolving images from theme. +* Allow the `top` keys in the `title-page` theme category to accept a fixed value (e.g., `1in`). +* Prevent orphan detection for headings (section title or discrete heading) from modifying the document state. + +== Compliance + +* Configure table borders to be compatible with prawn-table > 0.2.2. +* Don't coerce a font size < 1 to a relative font size; relative font size should be specified in units. == Previous releases -* See xref:2.1@whats-new.adoc[What's New in Asciidoctor PDF 2.1] to learn about the improvements added in Asciidoctor 2.1. -* Refer to xref:2.0@whats-new.adoc[What's New in Asciidoctor PDF 2.0] to learn about all the new features, improvements, and fixes introduced in 2.0. +* See xref:2.1@whats-new.adoc[What's New in Asciidoctor PDF 2.1] to learn about the improvements added in Asciidoctor PDF 2.1. +* Refer to xref:2.0@whats-new.adoc[What's New in Asciidoctor PDF 2.0] to learn about the new features, improvements, and fixes introduced in 2.0. diff --git a/docs/modules/extend/pages/index.adoc b/docs/modules/extend/pages/index.adoc index cdf09ec7..72ae7b4a 100644 --- a/docs/modules/extend/pages/index.adoc +++ b/docs/modules/extend/pages/index.adoc @@ -15,7 +15,7 @@ Once you feel comfortable with Prawn, you're ready to extend the converter. == Going beyond theming -While creating the PDF document, there are thousands of small decisions the converter must make about how to instruct Prawn to layout the content elements on the page (so-called "`hackable typesetting`"). +While creating the PDF document, there are thousands of small decisions the converter must make about how to instruct Prawn to lay out the content elements on the page (so-called "`hackable typesetting`"). But once these elements are written, they can't be moved or styled (as is the case with HTML and CSS). To help influence those decisions--and thus prevent the converter from becoming too opinionated, a theming system was introduced. diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc index 21bbb76a..a8c86fa6 100644 --- a/docs/modules/extend/pages/use-cases.adoc +++ b/docs/modules/extend/pages/use-cases.adoc @@ -128,7 +128,7 @@ For example: == License page -Let's so you want to insert a license page into your documents, but you don't want to have to put a block macro for it in the document source. +Let's say you want to insert a license page into your documents, but you don't want to have to put a block macro for it in the document source. You can use an extended converter to add new pages to the body of the document. Let's consider the case of reading the license text from a file and inserting it into the first page of the body. @@ -146,7 +146,7 @@ You may want to take this a bit further and allow the location of the license fi == Paragraph numbering -To help with content auditing or coorelation, you may want to add a number in front of each paragraph. +To help with content auditing or correlation, you may want to add a number in front of each paragraph. You can do this first by assigning a number to each paragraph in the document in the `init_pdf` method. Then, you can add this number in the left margin at the start of each paragraph by overriding the `convert_paragraph` method. @@ -214,7 +214,7 @@ Once this limit is reached, the converter will not call `get_entries_for_toc` fo == Narrow TOC Let's say you want to make the content on the TOC page(s) really narrow. -You can do so by overridding the `ink_toc` method and squeezing the margins by applying extra indentation. +You can do so by overriding the `ink_toc` method and squeezing the margins by applying extra indentation. .Extended converter with narrow TOC [,ruby] @@ -270,6 +270,7 @@ You're free to customize where the label is placed. The float method allows you to move the cursor around in absolute space without impacting the flow of the content. The extent gives you the information about the location of the code block. +[#wrap-code-blocks-around-image] == Wrap code blocks around an image float Asciidoctor PDF provides basic support for image floats. @@ -361,7 +362,7 @@ The columns get applied to the body of the document, which excludes the document The Asciidoctor PDF converter also provides the framework for making multi-column layouts in an extended converter. This framework is accessible via the helper method `column_box`. -To make a muti-column layout, you put statements that ink content inside a code block and pass it to the `column_box` method as follows: +To make a multi-column layout, you put statements that ink content inside a code block and pass it to the `column_box` method as follows: [,ruby] ---- diff --git a/docs/modules/theme/pages/add-running-content.adoc b/docs/modules/theme/pages/add-running-content.adoc index 6b5b37e5..c0da188b 100644 --- a/docs/modules/theme/pages/add-running-content.adoc +++ b/docs/modules/theme/pages/add-running-content.adoc @@ -45,7 +45,7 @@ The `toc` value only applies if the TOC is in the default location (before the f If the value is `toc`, and the toc macro is used to position the TOC, the `start-at` behavior is the same as if the TOC is not enabled. The `toc` value is only recognized if the title page is implicitly or explicitly enabled. [[page]]Integer:: The running content starts on the page that matches the number assigned to `start-at` (i.e., 1 is the first body page, 2 is the second body page). -For a prepress book (doctype=book and media=prepress), the running content starts on the empty verso page before the body if the value is 0. +For a prepress book (`doctype=book` and `media=prepress`), the running content starts on the empty verso page before the body if the value is `0`. When an integer is assigned to `start-at`, the title page doesn't need to be enabled. TIP: To turn off the running content on TOC pages inserted by the toc macro, set the `noheader` or `nofooter` options on the macro (e.g., `toc::[opts=nofooter]`). diff --git a/docs/modules/theme/pages/heading.adoc b/docs/modules/theme/pages/heading.adoc index 9c45f912..307760ab 100644 --- a/docs/modules/theme/pages/heading.adoc +++ b/docs/modules/theme/pages/heading.adoc @@ -68,7 +68,7 @@ heading: heading: margin-top: 6 -|min-height-after +|[[min-height-after]]min-height-after |xref:measurement-units.adoc[Measurement] {vbar} auto + (default: `20`) |[source] diff --git a/docs/modules/theme/pages/page-numbers.adoc b/docs/modules/theme/pages/page-numbers.adoc index 64239505..072387b9 100644 --- a/docs/modules/theme/pages/page-numbers.adoc +++ b/docs/modules/theme/pages/page-numbers.adoc @@ -52,7 +52,7 @@ The `toc` value only applies if the TOC is in the default location (before the f If the value is `toc`, and the toc macro is used to position the TOC, the `start-at` behavior is the same as if the TOC is not enabled. The `toc` value is only recognized if the title page is implicitly or explicitly enabled. Integer:: The page numbering starts at the specified page of the body (i.e., 1 is the first body page, 2 is the second body page). -For a prepress book (doctype=book and media=prepress), the page numbering starts on the empty verso page before the body if the value is 0. +For a prepress book (`doctype=book` and `media=prepress`), the page numbering starts on the empty verso page before the body if the value is `0`. An integer value is recognized by all doctypes and the title page doesn't need to be enabled. Let's start the integer page number on the title page of a document. diff --git a/docs/modules/theme/pages/page.adoc b/docs/modules/theme/pages/page.adoc index fa963e79..b94871a6 100644 --- a/docs/modules/theme/pages/page.adoc +++ b/docs/modules/theme/pages/page.adoc @@ -132,7 +132,7 @@ If the initial page layout is portrait, then the rotated margin applies to lands The `margin` key applies to the initial page layout. The rotated margin does not honor <<prepress-margins>>. -Rather, it's the same margin regardless of whether the page side is recto or verso.. +Rather, it's the same margin regardless of whether the page side is recto or verso. [#prepress-margins] === Inner and outer margins diff --git a/docs/modules/theme/pages/text.adoc b/docs/modules/theme/pages/text.adoc index 45c0a964..4dfec693 100644 --- a/docs/modules/theme/pages/text.adoc +++ b/docs/modules/theme/pages/text.adoc @@ -1,5 +1,5 @@ = Text Styles -:description: The theming language provides keys for aligning, decorating, styling, and transforming text. +:description: The theming language provides keys for aligning, decorating, sizing, styling, and transforming text. [#text-align] == Text alignment |