From 4c03f53b8ab3b3a691cd3a190362ae873db49dc0 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Sat, 21 May 2022 15:33:18 -0600 Subject: [PATCH] document the expected return value for convert handler methods [no ci] --- docs/modules/extend/pages/create-converter.adoc | 3 +++ docs/modules/extend/pages/use-cases.adoc | 5 ++++- lib/asciidoctor/pdf/converter.rb | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/modules/extend/pages/create-converter.adoc b/docs/modules/extend/pages/create-converter.adoc index edd2e7700..ed81247e8 100644 --- a/docs/modules/extend/pages/create-converter.adoc +++ b/docs/modules/extend/pages/create-converter.adoc @@ -24,6 +24,9 @@ Let's start by overriding the thematic break (i.e., horizontal rule) to make it include::example$pdf-converter-custom-thematic-break.rb[tag=convert_thematic_break] ---- +The return value of a convert handler for a block node is ignored. +The return value of a convert handler for an inline node must be a string, which may contain the HTML-like markup that this convert supports. + To find all the available methods to override, see the {url-api-docs}[API docs^]. Now that you've made a change to the converter, let's xref:use-converter.adoc[learn how to activate it]. diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc index b89f32fcb..456dac58e 100644 --- a/docs/modules/extend/pages/use-cases.adoc +++ b/docs/modules/extend/pages/use-cases.adoc @@ -23,6 +23,9 @@ That means we can make use of graphics fill and stroke methods provided by Ascii include::example$pdf-converter-custom-thematic-break.rb[tags=**] ---- +The return value of the convert handler method for a block node is ignored, which is why there's no clear return value in this override. +If this were a convert handler method for an inline node, a return value would be required, which becomes the text to render. + == Custom title page Every title page is as unique as the work itself. @@ -247,7 +250,7 @@ However, if it encounters a non-paragraph, the converter will clear the float an As a companion to this basics support, the converter provides a framework for broadening support for float wrapping. We can take advantage of this framework in an extended converter. -By extending the converter and overriding the `supports_float_wrapping?` as well as the handler for the block you want to enlist (e.g., `convert_code`), you can arrange additional content into the empty space adjacent to the floated image. +By extending the converter and overriding the `supports_float_wrapping?` as well as the convert handler for the block you want to enlist (e.g., `convert_code`), you can arrange additional content into the empty space adjacent to the floated image. In the following example, code (listing and literal) blocks are included in the float wrapping. .Extended converter that additionally wraps code blocks around an image float diff --git a/lib/asciidoctor/pdf/converter.rb b/lib/asciidoctor/pdf/converter.rb index 2a2f6b9d0..a8f964331 100644 --- a/lib/asciidoctor/pdf/converter.rb +++ b/lib/asciidoctor/pdf/converter.rb @@ -152,7 +152,7 @@ def convert node, name = nil, _opts = {} # TODO: delegate to convert_method_missing log :warn, %(missing convert handler for #{name} node in #{@backend} backend) end - # NOTE: inline nodes generate pseudo-HTML strings; the remainder write directly to PDF object + # NOTE: inline node handlers generate HTML-like strings; all other handlers write directly to the PDF object ::Asciidoctor::Inline === node ? result : self end