From f4bd057f69b3d72da73bf20e31fca7a2bfedbf3a Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Fri, 10 Jun 2022 15:07:33 -0600 Subject: resolves #327 arrange body of article or manpage doctype into multiple columns if page-columns key is set in theme (PR #2232) --- .../extend/examples/pdf-converter-columns.rb | 18 ------------ docs/modules/extend/pages/use-cases.adoc | 34 ++++++++-------------- docs/modules/theme/pages/page.adoc | 23 +++++++++++++++ 3 files changed, 35 insertions(+), 40 deletions(-) delete mode 100644 docs/modules/extend/examples/pdf-converter-columns.rb (limited to 'docs/modules') diff --git a/docs/modules/extend/examples/pdf-converter-columns.rb b/docs/modules/extend/examples/pdf-converter-columns.rb deleted file mode 100644 index b6231bcc..00000000 --- a/docs/modules/extend/examples/pdf-converter-columns.rb +++ /dev/null @@ -1,18 +0,0 @@ -class PDFConverterColumns < (Asciidoctor::Converter.for 'pdf') - register_for 'pdf' - - def traverse node - if node.context == :document && - (columns = ColumnBox === bounds ? 1 : theme.base_columns || 1) > 1 - column_box [bounds.left, cursor], - columns: columns, - width: bounds.width, - reflow_margins: true, - spacer: theme.base_column_gap do - super - end - else - super - end - end -end diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc index 014a29ff..9daa9f2f 100644 --- a/docs/modules/extend/pages/use-cases.adoc +++ b/docs/modules/extend/pages/use-cases.adoc @@ -270,34 +270,24 @@ image: == Multiple columns -Asciidoctor PDF does not yet provide multi-column support, where the body of the article is arranged into multiple columns. -However, the converter does provide the foundation for supporting a multi-column layout. -We can tap into that foundation using an extended converter. +Starting with Asciidoctor PDF 2.1, this converter provides built-in support for multiple columns. +This feature is available when the doctype is article or manpage, but not book. +The columns get applied to the body of the document, which excludes the document title and TOC, if present. -The trick is to intercept the `traverse` method and enclose the call in a column box using the `column_box` method. -The `traverse` method is called to render the body, accepting the document as the sole argument. -Since this method is also called for other blocks, we'll need to filter out those calls by looking for the `:document` context. +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: -.Extended converter that arranges the body into columns [,ruby] ---- -include::example$pdf-converter-columns.rb[] +column_box [bounds.left, cursor], columns: 2, width: bounds.width, reflow_margins: true do + ink_prose 'left column' + bounds.move_past_bottom + ink_prose 'right column' +end ---- -WARNING: You may encounter some quirks when using this extended converter. -It's not yet a perfect solution. -For example, it does not handle the index section correctly. -You may have to play around with the code to get the desired result. - -You can configure the number of columns and the gap between the columns in the theme file as follows: - -[,yaml] ----- -extends: default -base: - columns: 2 - column-gap: 12 ----- +If you want a multi-column layout for a specific chapter or section, you can override the `traverse` method, look for the section you want to arrange, and wrap the call to `super` in a `column_box` enclosure. == Theme table using custom role diff --git a/docs/modules/theme/pages/page.adoc b/docs/modules/theme/pages/page.adoc index 64df40f7..97c5852c 100644 --- a/docs/modules/theme/pages/page.adoc +++ b/docs/modules/theme/pages/page.adoc @@ -39,6 +39,21 @@ page: recto: image:page-bg-recto.png[] verso: image:page-bg-verso.png[] +|columns +|Integer + +(default: _not set_) +|[source] +page: + columns: 2 + +|column_gap +|xref:measurement-units.adoc[Measurement] + +(default: _$base-font-size_) +|[source] +page: + columns: 2 + columns_gap: 12 + |xref:images.adoc#foreground[foreground-image] |xref:images.adoc#specify[image macro] {vbar} xref:images.adoc#specify[path] + (default: _not set_) @@ -111,6 +126,14 @@ If no cover is specified, the recto margin is not applied to the title page. To apply the recto margin to the title page, but not include a cover, assign the value `~` to the `front-cover-image` and `back-cover-image` attributes. See xref:cover.adoc[] for information about the `cover` category keys. +[#columns] +=== Columns + +The columns are only applied to the body of a document with the article or manpage doctype. +The body of the document begins after the document title and TOC, if present. + +If the columns are set on the index section using the `index-columns` key, they will be ignored when `page-columns` is set. + [#numbering] == page-numbering -- cgit v1.2.3