Change Xml.add_link() method

We should support two different parameters, the HTML "href" value, which refers to the link target, and independently the text that is visible to the user.

Also document that `Xml.add_paragraph()` isa context manager.

Author: JorjMcKie

docs/xml-class.rst

@@ -103,17 +103,20 @@ There is no need to ever directly construct an :ref:`Xml` object: after creating
        :arg width: if provided, either an absolute (int) value, or a percentage string like "30%". A percentage value refers to the width of the specified ``where`` rectangle in :meth:`Story.place`. If this value is provided and ``height`` is omitted, the image will be included keeping its aspect ratio.
        :arg height: if provided, either an absolute (int) value, or a percentage string like "30%". A percentage value refers to the height of the specified ``where`` rectangle in :meth:`Story.place`. If this value is provided and ``width`` is omitted, the image's aspect ratio will be honored.
 
-    .. method:: add_link(link)
+    .. method:: add_link(href=None, text=None)
 
-       Add an :htmlTag:`a` tag.
+       Add an :htmlTag:`a` tag - inline element, treated like text.
+
+       :arg str href: the URL target.
+       :arg str text: the text to display. If omitted, the ``href`` text is shown instead.
 
     .. method:: add_number_list
 
        Add an :htmlTag:`ol` tag, context manager.
 
     .. method:: add_paragraph
 
-       Add a :htmlTag:`p` tag.
+       Add a :htmlTag:`p` tag, context manager.
 
     .. method:: add_span
 

fitz/fitz.i

@@ -13122,10 +13122,16 @@ struct Xml
             self.append_child(child)
             return child
 
-        def add_link(self, text=None):
+        def add_link(self, href=None, text=None):
             """Add a hyperlink ("a" tag)"""
             child = self.create_element("a")
-            if type(text) is str:
+            if not isinstance(href, str):
+                href = text
+            if not isinstance(text, str):
+                text = href
+            if href:
+                child.set_attribute("href", href)
+            if text:
                child.append_child(self.create_text_node(text)) 
             prev = self.span_bottom()
             if prev == None: