Merge PR #1172

4 files changed, 30 insertions, 78 deletions

diff --git a/lib/asciidoctor/converter.rb b/lib/asciidoctor/converter.rb
index 39aee4c8..678ae29b 100644
--- a/lib/asciidoctor/converter.rb
+++ b/lib/asciidoctor/converter.rb
@@ -160,9 +160,9 @@ module Asciidoctor
     end
 =end
 
-    # Public: Converts an {AbstractNode} using the specified transform. If a
-    # transform is not specified, implementations typically derive one from the
-    # {AbstractNode#node_name} property.
+    # Public: Converts an {AbstractNode} using the specified transform along
+    # with additional options. If a transform is not specified, implementations
+    # typically derive one from the {AbstractNode#node_name} property.
     #
     # Implementations are free to decide how to carry out the conversion. In
     # the case of the built-in converters, the tranform value is used to
@@ -174,29 +174,16 @@ module Asciidoctor
     #             should be applied to this node. If a transform is not specified,
     #             the transform is typically derived from the value of the
     #             node's node_name property. (optional, default: nil)
+    # opts      - An optional Hash of options that provide additional hints about
+    #             how to convert the node. (optional, default: {})
     #
     # Returns the [String] result
-    def convert node, transform = nil
+    def convert node, transform = nil, opts = {}
       raise ::NotImplementedError
     end
 
-    # Public: Converts an {AbstractNode} using the specified transform along
-    # with additional options. Delegates to {#convert} without options by default.
-    # Used by the template-based converter to delegate to the converter for outline.
-    # (see https://github.com/asciidoctor/asciidoctor-backends/blob/master/slim/html5/block_toc.html.slim#L11)
-    #
-    # node      - The concrete instance of AbstractNode to convert
-    # transform - An optional String transform that hints at which transformation
-    #             should be applied to this node. If a transform is not specified,
-    #             the transform is typically derived from the value of the
-    #             node's node_name property. (optional, default: nil)
-    # opts      - An optional Hash of options that provide additional hints about
-    #             how to convert the node.
-    #
-    # Returns the [String] result
-    def convert_with_options node, transform = nil, opts = {}
-      convert node, transform
-    end
+    # Alias for backward compatibility.
+    alias :convert_with_options :convert
   end
 
   # A module that can be used to mix the {#write} method into a {Converter}
diff --git a/lib/asciidoctor/converter/base.rb b/lib/asciidoctor/converter/base.rb
index 9c3dcb9d..e74d81d8 100644
--- a/lib/asciidoctor/converter/base.rb
+++ b/lib/asciidoctor/converter/base.rb
@@ -16,25 +16,21 @@ module Asciidoctor
     def initialize backend, opts = {}
     end
 
-    # Public: Converts the specified {AbstractNode} using the specified transform.
+    # Public: Converts the specified {AbstractNode} using the specified
+    # transform and optionally additional options (when not empty).
     #
-    # See {Converter#convert} for more details.
+    # CAUTION: Method that handles the specified transform *may not* accept the
+    # second argument with additional options, in which case an {ArgumentError}
+    # is raised if the given +opts+ Hash is not nil. The additional options are
+    # used in template-based backends to access convert helper methods such as
+    # outline.
     #
-    # Returns the [String] result of conversion
-    def convert node, transform = nil
-      transform ||= node.node_name
-      send transform, node
-    end
-
-    # Public: Converts the specified {AbstractNode} using the specified transform 
-    # with additional options.
-    #
-    # See {Converter#convert_with_options} for more details.
+    # See {Converter#convert} for more details.
     #
     # Returns the [String] result of conversion
-    def convert_with_options node, transform = nil, opts = {}
+    def convert node, transform = nil, opts = {}
       transform ||= node.node_name
-      send transform, node, opts
+      opts.empty? ? (send transform, node) : (send transform, node, opts)
     end
 
     alias :handles? :respond_to?
diff --git a/lib/asciidoctor/converter/composite.rb b/lib/asciidoctor/converter/composite.rb
index 09fdf4f9..a04e2166 100644
--- a/lib/asciidoctor/converter/composite.rb
+++ b/lib/asciidoctor/converter/composite.rb
@@ -16,35 +16,23 @@ module Asciidoctor
     end
 
     # Public: Delegates to the first converter that identifies itself as the
-    # handler for the given transform.
-    #
-    # node      - the AbstractNode to convert
-    # transform - the optional String transform, or the name of the node if no
-    #             transform is specified. (default: nil)
-    #
-    # Returns the String result returned from the delegate's convert method
-    def convert node, transform = nil
-      transform ||= node.node_name
-      # QUESTION is there a way we can control whether to use convert or send?
-      (converter_for transform).convert node, transform
-    end
-
-    # Public: Delegates to the first converter that identifies itself as the
     # handler for the given transform. The optional Hash is passed as the last
     # option to the delegate's convert method.
     #
     # node      - the AbstractNode to convert
     # transform - the optional String transform, or the name of the node if no
     #             transform is specified. (default: nil)
-    # opts      - a optional Hash that is passed to the delegate's convert method. (default: {})
+    # opts      - an optional Hash that is passed to the delegate's convert method. (default: {})
     #
     # Returns the String result returned from the delegate's convert method
-    def convert_with_options node, transform = nil, opts = {}
+    def convert node, transform = nil, opts = {}
       transform ||= node.node_name
-      # QUESTION should we check arity, or perhaps do a rescue ::ArgumentError?
-      (converter_for transform).convert_with_options node, transform, opts
+      (converter_for transform).convert node, transform, opts
     end
 
+    # Alias for backward compatibility.
+    alias :convert_with_options :convert
+
     # Public: Retrieve the converter for the specified transform.
     #
     # Returns the matching [Converter] object
diff --git a/lib/asciidoctor/converter/template.rb b/lib/asciidoctor/converter/template.rb
index 97ea1cfb..f54bffc7 100644
--- a/lib/asciidoctor/converter/template.rb
+++ b/lib/asciidoctor/converter/template.rb
@@ -166,9 +166,11 @@ module Asciidoctor
     # template_name - the String name of the template to use, or the value of
     #                 the node_name property on the node if a template name is
     #                 not specified. (optional, default: nil)
+    # opts          - an optional Hash that is passed as local variables to the
+    #                 template. (optional, default: {})
     #
     # Returns the [String] result from rendering the template
-    def convert node, template_name = nil
+    def convert node, template_name = nil, opts = {}
       template_name ||= node.node_name
       unless (template = @templates[template_name])
         raise %(Could not find a custom template to handle transform: #{template_name})
@@ -180,33 +182,12 @@ module Asciidoctor
         node.extend ::Slim::Helpers
       end
 
+      # NOTE opts become locals in the template
       if template_name == 'document'
-        (template.render node).strip
+        (template.render node, opts).strip
       else
-        (template.render node).chomp
-      end
-    end
-
-    # Public: Convert an {AbstractNode} using the named template with the
-    # additional options provided.
-    #
-    # Looks for a template that matches the value of the
-    # {AbstractNode#node_name} property if a template name is not specified.
-    #
-    # node          - the AbstractNode to convert
-    # template_name - the String name of the template to use, or the value of
-    #                 the node_name property on the node if a template name is
-    #                 not specified. (optional, default: nil)
-    # opts          - an optional Hash that is passed as local variables to the
-    #                 template. (optional, default: {})
-    #
-    # Returns the [String] result from rendering the template
-    def convert_with_options node, template_name = nil, opts = {}
-      template_name ||= node.node_name
-      unless (template = @templates[template_name])
-        raise %(Could not find a custom template to handle transform: #{template_name})
+        (template.render node, opts).chomp
       end
-      (template.render node, opts).chomp
     end
 
     # Public: Checks whether there is a Tilt template registered with the specified name.