resolves #1597 add example of extended converter that adds change bars to paragraphs (PR #2186)

2 files changed, 33 insertions, 0 deletions

diff --git a/docs/modules/extend/examples/pdf-converter-change-bars.rb b/docs/modules/extend/examples/pdf-converter-change-bars.rb
new file mode 100644
index 00000000..887a395d
--- /dev/null
+++ b/docs/modules/extend/examples/pdf-converter-change-bars.rb
@@ -0,0 +1,15 @@
+class PDFConverterChangeBars < (Asciidoctor::Converter.for 'pdf')
+  register_for 'pdf'
+
+  def convert_paragraph node
+    start_cursor = cursor
+    super
+    if node.role? 'changed'
+      float do
+        bounding_box [bounds.left - 4, start_cursor], width: 2, height: (start_cursor - cursor) do
+          fill_bounds 'FF0000'
+        end
+      end
+    end
+  end
+end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index bd98aafa..5efd7f48 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -152,6 +152,24 @@ Then, you can add this number in the left margin at the start of each paragraph
 include::example$pdf-converter-numbered-paragraphs.rb[]
 ----
 
+== Change bars
+
+If you have a preprocessor that adds change metadata to the content, you can use an extended converter to draw change bars to add a visual indicator in the rendered output.
+
+.Extended converter with change bars
+[,ruby]
+----
+include::example$pdf-converter-change-bars.rb[]
+----
+
+This converter will look for paragraphs like this one:
+
+[,asciidoc]
+----
+[.changed]
+This line has been changed.
+----
+
 == Avoid break after heading
 
 This functionality is already provided by the converter if you set the `breakable` option on section title or discrete heading.