add foundation to support multi-column layout; add example to docs (PR #2190)

2 files changed, 43 insertions, 0 deletions

diff --git a/docs/modules/extend/examples/pdf-converter-columns.rb b/docs/modules/extend/examples/pdf-converter-columns.rb
new file mode 100644
index 00000000..97b3c91d
--- /dev/null
+++ b/docs/modules/extend/examples/pdf-converter-columns.rb
@@ -0,0 +1,10 @@
+class PDFConverterColumns < (Asciidoctor::Converter.for 'pdf')
+  register_for 'pdf'
+
+  def traverse node
+    return super unless node.context == :document && (columns = theme.base_columns)
+    column_box [0, cursor], columns: columns, width: bounds.width, reflow_margins: true, spacer: theme.base_column_gap do
+      super
+    end
+  end
+end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index 5efd7f48..b89f32fc 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -234,6 +234,7 @@ This converter works when a custom theme defines the `image-indent` key, as foll
 
 [,yaml]
 ----
+extends: default
 image:
   indent: [0.5in, 0]
 ----
@@ -259,10 +260,42 @@ You can configure the gap next to and below the image using the `image-float-gap
 
 [,yaml]
 ----
+extends: default
 image:
   float-gap: [12, 6]
 ----
 
+== 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.
+
+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.
+
+.Extended converter that arranges the body into columns
+[,ruby]
+----
+include::example$pdf-converter-columns.rb[]
+----
+
+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
+----
+
 == Access page number from inline macro
 
 Although not an extended converter, this use case uses information from the converter in much the same way.