add example of extended converter that inserts a license page

2 files changed, 35 insertions, 0 deletions

diff --git a/docs/modules/extend/examples/pdf-converter-license-page.rb b/docs/modules/extend/examples/pdf-converter-license-page.rb
new file mode 100644
index 00000000..0f1bb6a8
--- /dev/null
+++ b/docs/modules/extend/examples/pdf-converter-license-page.rb
@@ -0,0 +1,17 @@
+class PDFConverterLicensePage < (Asciidoctor::Converter.for 'pdf')
+  register_for 'pdf'
+
+  def traverse node
+    return super unless node.context == :document
+    start_new_page unless at_page_top?
+    theme_font :heading, level: 2 do
+      ink_heading 'License', level: 2
+    end
+    license_text = File.read 'LICENSE'
+    theme_font :code do
+      ink_prose license_text, normalize: false, align: :left, color: theme.base_font_color
+    end
+    start_new_page
+    super
+  end
+end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index 48f76fd8..bd98aafa 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -122,6 +122,24 @@ For example:
 :chapter-toclevels: 2
 ----
 
+== License page
+
+Let's so 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.
+You can use an extended converter to add new pages to the body of the document.
+
+Let's consider the case of reading the license text from a file and inserting it into the first page of the body.
+
+.Extended converter with license page
+[,ruby]
+----
+include::example$pdf-converter-license-page.rb[]
+----
+
+The method `start_new_page` will create a new page in the document.
+The `ink_prose` method provides a `normalize` option.
+When this option is false, it will preserve the newlines in the content, which is what we want in the case of license text.
+You may want to take this a bit further and allow the location of the license file to be configurable.
+
 == Paragraph numbering
 
 To help with content auditing or coorelation, you may want to add a number in front of each paragraph.