<commit_before>= Asciidoctor PDF Features
:navtitle: Features

== Highlights

* Direct AsciiDoc to PDF conversion
* xref:theme:index.adoc[Configuration-driven theme]
* Custom fonts (TTF or OTF)
* Full SVG support (thanks to {url-prawn-svg}[prawn-svg^])
* PDF document outline (i.e., bookmarks)
* Title page
* Table of contents page(s)
* Document metadata (title, authors, subject, keywords, etc.)
* Configurable page size (e.g., A4, Letter, Legal, etc.)
* Internal cross reference links
* Syntax highlighting with Rouge (preferred), Pygments, or CodeRay
* Cover pages
* Page background color or page background image with named scaling
* Page numbering
* Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
* Customizable running content (header and footer)
* “Keep together” blocks (i.e., page breaks avoided in certain block content):
** Explicitly delimited blocks other than open blocks
** Open blocks with the "unbreakable" option `[%unbreakable]`
* Orphaned section titles avoided
* Autofit verbatim blocks (as permitted by `base_font_size_min` setting)
* Table border settings honored
* Font-based icons
* Auto-generated index
* Automatic hyphenation (when enabled)
* Permissive line breaking for CJK languages
* Compression / optimization of output file

[#limitations]
== Known limitations

* Footnotes are always displayed as endnotes (at the end of chapter for books; at the end of document for all other doctypes).
*Footnotes cannot be displayed at the 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 (see https://github.com/prawnpdf/prawn-table/issues/41[prawn-table#41^]).
* A column can't be assigned a `width` of `0%` or a `width` less than the width of a single character.
The converter will throw the error `Prawn::Errors::CannotFit` if such a case occurs.
* A column can't be set to `autowidth` if the width of all the other columns in the table meet or exceed 100%.
The converter will throw the error `Prawn::Errors::CannotFit` if such a case occurs.
* 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`, 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^]).
* Must use development version of prawn for error to include font name when requested font style is missing.
* AsciiDoc table cell leaves padding below last block (due to lack of margin collapsing).
* 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 / 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.
* If a no-break hyphen is surrounded by formatted text on both sides (or is formatted individually), it will not prevent a line break.
* Images cannot float.
* You cannot use inline HTML (like a link or emphasized text) in a source block that also uses syntax highlighting.
These two technologies just don't combine 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 using the theme.
* 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.<commit_msg>resolves #2042 update features and limitations to reflect current state of converter (PR #2066)<commit_after>= Asciidoctor PDF Features
:navtitle: Features

== Highlights

* Direct AsciiDoc to PDF conversion
* Composable, xref:theme:index.adoc[configuration-driven theming system] (resembling basic CSS)
* Themable AsciiDoc blocks (e.g., example, admonition, sidebar, etc.)
* Custom fonts (TTF and limited OTF support)
* Full SVG support (thanks to {url-prawn-svg}[prawn-svg^])
* PDF document outline
* Title page
* Table of contents with page numbers
* Document metadata (title, authors, subject, keywords, etc.)
* 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
* Front and back cover pages
* Page background color or page background image with configurable scaling
* Page numbering
* Double-sided (aka prepress) printing mode (i.e., margins alternate on recto and verso pages)
* Customizable running content (header and footer)
* Section body indent
* Unbreakable blocks
* Orphaned section titles avoided (basic support)
* Autofit verbatim blocks (as permitted by `base_font_size_min` setting)
* Table border settings
* Font-based icons
* Auto-generated index
* Automatic hyphenation (when enabled)
* Permissive line breaking for CJK languages
* Compression / optimization of output file

[#limitations]
== Known limitations

* 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 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 meet or exceed 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 / widow support is limited; for example, a page break may occur between a section title the first block of content
 ** to avoid an orphaned section title, you can extend the converter and override the arrange_section method
 ** to avoid an orphaned caption on a table, add the `%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.
* Images cannot float.
* Only a single column is supported (except for the index section).
* 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 using the theme.
{'fraction_non_alphanumeric': 0.06760744066709429, 'fraction_numerical': 0.010262989095574085, 'mean_word_length': 4.766272189349112, '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': '1065805', 'n_tokens_mistral': 2115, 'n_tokens_neox': 1999, 'n_words': 1127}