resolves #327 arrange body of article or manpage doctype into multiple columns if page-columns key is set in theme (PR #2232)

3 files changed, 35 insertions, 40 deletions

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