backport fix for #2455 add extended converter use case to place colop…

…hon before TOC

docs/modules/extend/examples/pdf-converter-colophon-placement.rb

@@ -0,0 +1,20 @@
+class AsciidoctorPDFExtensions < (Asciidoctor::Converter.for 'pdf')
+  register_for 'pdf'
+
+  def ink_toc doc, num_levels, toc_page_number, start_cursor, num_front_matter_pages = 0
+    colophon = (doc.instance_variable_get :@colophon) || (doc.sections.find {|sect| sect.sectname == 'colophon' })
+    return super unless colophon
+    go_to_page toc_page_number unless (page_number == toc_page_number) || scratch?
+    if scratch?
+      (doc.instance_variable_set :@colophon, colophon).parent.blocks.delete colophon
+    else
+      # if doctype=book and media=prepress, use blank page before table of contents
+      go_to_page page_number.pred if @ppbook
+      convert_section colophon
+      go_to_page page_number.next
+    end
+    offset = @ppbook ? 0 : 1
+    toc_page_numbers = super doc, num_levels, (toc_page_number + offset), start_cursor, num_front_matter_pages
+    scratch? ? ((toc_page_numbers.begin - offset)..toc_page_numbers.end) : toc_page_numbers
+  end
+end

docs/modules/extend/pages/use-cases.adoc

@@ -146,6 +146,21 @@ For example:
 :chapter-toclevels: 2
 ----
 
+== Colophon before TOC
+
+Some publishers prefer the colophon to precede the table of contents.
+When converting to a prepress book, publishers may also prefer the colophon to be placed on the recto page that follows the title page.
+You can achieve both of these customizations by overriding the built-in `ink_toc` method and rendering the colophon before the TOC is rendered (i.e., inked).
+
+.Extended converter that modifies the placement of the colophon
+[,ruby]
+----
+include::example$pdf-converter-colophon-placement.rb[]
+----
+
+It's important to note that this converter, as written, assumes the colophon fits on a single page.
+More effort would be needed to accomodate a multi-page colophon.
+
 == License page
 
 Let's say you want to insert a license page into your documents, but you don't want to have to put a block macro for it in the document source.