<commit_before>= Asciidoctor PDF Features
:navtitle: Features

== Highlights

* Direct AsciiDoc to PDF conversion
* Composable, xref:theme:index.adoc[configuration-driven theming system] that resembles basic CSS
* Themable AsciiDoc blocks (e.g., example, admonition, sidebar, etc.)
* Custom fonts (TTF and limited OTF support)
* Full SVG support
* Front and back cover pages
* Title page
* Document metadata (title, authors, subject, keywords, etc.)
* xref:pdf-outline.adoc[PDF document outline]
* xref:toc.adoc[Table of contents with page numbers]
* Configurable page size (e.g., A4, Letter, Legal, etc.) and layout (portrait or landscape)
* Internal cross reference links
* Syntax highlighting with Rouge (preferred), Pygments, or CodeRay
* Page background color or xref:background-images.adoc[page background image] with configurable scaling
* xref:page-numbers.adoc[Page numbering]
* Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
* xref:theme:add-running-content.adoc[Customizable header and footer running content]
* Section body indent
* xref:breakable-and-unbreakable.adoc[Unbreakable blocks]
* Orphaned section titles avoided (basic support)
* Autofit verbatim blocks (as permitted by `base_font_size_min` setting)
* Table border settings
* xref:icons.adoc[Font-based and image icons]
* Auto-generated index
* Automatic hyphenation (when enabled)
* Permissive line breaking for CJK languages
* Compression / optimization of output file

[#limitations]
== 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 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).
* Table cells that exceed the height of a single page are truncated with a warning (see https://github.com/prawnpdf/prawn-table/issues/41[prawn-table#41^]).
* A rowspan in a table that exceeds the height of a single page will be orphaned and the remaining columns will be truncated (see {url-project-issues}/403#issuecomment-1133840210[#403^]).
* A column can't be assigned a `width` of `0%` or a `width` less than the width of a single character.
The converter will skip the table and emit a warning if such a case occurs.
* A column can't be set to `autowidth` if the width of all the other columns in the table meets or exceeds 100%.
The converter will skip the table and emit a warning if such a case occurs.
* An inline image in a table cell will shrink to fit (rather than force the column wider) if the width of the image exceeds the width of the column; you can increase the width of the column using `cols` or convert the cell to an AsciiDoc table cell and, preferably, use a block image (see {url-project-issues}/830[#830^]).
* An inline image with a percentage `width` value in an `autowidth` table cell is resized relative to its intrinsic width.
The space reserved for the image matches its intrinsic width.
This matches the behavior of HTML.
* 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^]).
* Orphan and widow support is limited to delimited blocks, block images, and admonitions; therefore, a page break may occur between a section title and its first block of content
 ** to avoid an orphaned section title, you can add the xref:breakable-and-unbreakable.adoc[breakable option] to the section
 ** to avoid an orphaned caption on a table, add the xref:breakable-and-unbreakable.adoc[breakable option] to the table
* 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-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.
* Verse blocks do not use a fixed-width font by default, but you can control this setting xref:theme:verse.adoc[using the theme].
* Cannot use remote inline image in the doctitle or a section title with an automatic ID<commit_msg>add limitation that custom subs that add additional formatting cannot be used on source block<commit_after>= Asciidoctor PDF Features
:navtitle: Features

== Highlights

* Direct AsciiDoc to PDF conversion
* Composable, xref:theme:index.adoc[configuration-driven theming system] that resembles basic CSS
* Themable AsciiDoc blocks (e.g., example, admonition, sidebar, etc.)
* Custom fonts (TTF and limited OTF support)
* Full SVG support
* Front and back cover pages
* Title page
* Document metadata (title, authors, subject, keywords, etc.)
* xref:pdf-outline.adoc[PDF document outline]
* xref:toc.adoc[Table of contents with page numbers]
* Configurable page size (e.g., A4, Letter, Legal, etc.) and layout (portrait or landscape)
* Internal cross reference links
* Syntax highlighting with Rouge (preferred), Pygments, or CodeRay
* Page background color or xref:background-images.adoc[page background image] with configurable scaling
* xref:page-numbers.adoc[Page numbering]
* Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
* xref:theme:add-running-content.adoc[Customizable header and footer running content]
* Section body indent
* xref:breakable-and-unbreakable.adoc[Unbreakable blocks]
* Orphaned section titles avoided (basic support)
* Autofit verbatim blocks (as permitted by `base_font_size_min` setting)
* Table border settings
* xref:icons.adoc[Font-based and image icons]
* Auto-generated index
* Automatic hyphenation (when enabled)
* Permissive line breaking for CJK languages
* Compression / optimization of output file

[#limitations]
== 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 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).
* Table cells that exceed the height of a single page are truncated with a warning (see https://github.com/prawnpdf/prawn-table/issues/41[prawn-table#41^]).
* A rowspan in a table that exceeds the height of a single page will be orphaned and the remaining columns will be truncated (see {url-project-issues}/403#issuecomment-1133840210[#403^]).
* A column can't be assigned a `width` of `0%` or a `width` less than the width of a single character.
The converter will skip the table and emit a warning if such a case occurs.
* A column can't be set to `autowidth` if the width of all the other columns in the table meets or exceeds 100%.
The converter will skip the table and emit a warning if such a case occurs.
* An inline image in a table cell will shrink to fit (rather than force the column wider) if the width of the image exceeds the width of the column; you can increase the width of the column using `cols` or convert the cell to an AsciiDoc table cell and, preferably, use a block image (see {url-project-issues}/830[#830^]).
* An inline image with a percentage `width` value in an `autowidth` table cell is resized relative to its intrinsic width.
The space reserved for the image matches its intrinsic width.
This matches the behavior of HTML.
* 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^]).
* Orphan and widow support is limited to delimited blocks, block images, and admonitions; therefore, a page break may occur between a section title and its first block of content
 ** to avoid an orphaned section title, you can add the xref:breakable-and-unbreakable.adoc[breakable option] to the section
 ** to avoid an orphaned caption on a table, add the xref:breakable-and-unbreakable.adoc[breakable option] to the table
* 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-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.
* Verse blocks do not use a fixed-width font by default, but you can control this setting xref:theme:verse.adoc[using the theme].
* Cannot use remote inline image in the doctitle or a section title with an automatic ID
* Cannot use custom subs that add additional formatting on a source block when source-highlighter is set (e.g., `subs=+quotes`)
{'fraction_non_alphanumeric': 0.06455576559546314, 'fraction_numerical': 0.009829867674858222, 'mean_word_length': 4.894707520891365, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1770673', 'n_tokens_mistral': 2895, 'n_tokens_neox': 2703, 'n_words': 1489}