link_to.rb in nanoc3-3.0.4

- old
+ new

@@ -11,11 +11,13 @@
 
     require 'nanoc3/helpers/html_escape'
     include Nanoc3::Helpers::HTMLEscape
 
     # Creates a HTML link to the given path or item representation, and with
-    # the given text.
+    # the given text. All attributes of the `a` element, including the `href`
+    # attribute, will be HTML-escaped; the contents of the `a` element, which
+    # can contain markup, will not be HTML-escaped.
     #
     # +path_or_rep+:: the URL or path (a String) that should be linked to, or
     #                 the item representation that should be linked to.
     #
     # +text+:: the visible link text.
@@ -47,11 +49,12 @@
       "<a #{attributes}href=\"#{h path}\">#{text}</a>"
     end
 
     # Creates a HTML link using link_to, except when the linked item is the
     # current one. In this case, a span element with class "active" and with
-    # the given text will be returned.
+    # the given text will be returned. The HTML-escaping rules for `link_to`
+    # apply here as well.
     #
     # Examples:
     #
     #   link_to_unless_current('Blog', '/blog/')
     #   # => '<a href="/blog/">Blog</a>'
@@ -69,10 +72,10 @@
         link_to(text, path_or_rep, attributes)
       end
     end
 
     # Returns the relative path from the current item to the given path or
-    # item representation.
+    # item representation. The returned path will not be HTML-escaped.
     #
     # +path_or_rep+:: the URL or path (a String) to where the relative should
     #                 point, or the item representation to which the relative
     #                 should point.
     #