Rename images.inline to images.img_element

6 files changed, 25 insertions, 9 deletions

diff --git a/NEWS b/NEWS
index 2620560..e63eb86 100644
--- a/NEWS
+++ b/NEWS
@@ -9,6 +9,9 @@
 * The default ID prefix is now the empty string rather than a random number
   followed by a hyphen.
 
+* Rename mammoth.images.inline to mammoth.images.img_element to better reflect
+  its behaviour.
+
 # 0.3.31
 
 * Improve collapsing of similar non-fresh HTML elements.
diff --git a/README.md b/README.md
index c423581..1a4e1a6 100644
--- a/README.md
+++ b/README.md
@@ -177,7 +177,7 @@ def convert_image(image):
         "src": "data:{0};base64,{1}".format(image.content_type, encoded_src)
     }
 
-mammoth.convert_to_html(docx_file, convert_image=mammoth.images.inline(convert_image))
+mammoth.convert_to_html(docx_file, convert_image=mammoth.images.img_element(convert_image))
 ```
 
 #### Bold
@@ -312,8 +312,8 @@ Each message has the following properties:
 
 #### Image converters
 
-An inline image converter can be created by calling `mammoth.images.inline(func)`.
-This creates an inline `<img>` element for each image in the original docx.
+An image converter can be created by calling `mammoth.images.img_element(func)`.
+This creates an `<img>` element for each image in the original docx.
 `func` should be a function that has one argument `image`.
 This argument is the image element being converted,
 and has the following properties:
@@ -322,8 +322,10 @@ and has the following properties:
   
 * `content_type`: the content type of the image, such as `image/png`.
 
-`func` should return a `dict` with a `src` item,
-which will be used as the `src` attribute on the `<img>` element.
+`func` should return a `dict` of attributes for the `<img>` element.
+At a minimum, this should include the `src` attribute.
+If any alt text is found for the image,
+this will be automatically added to the element's attributes.
 
 For instance, the following replicates the default image conversion:
 
@@ -336,7 +338,7 @@ def convert_image(image):
         "src": "data:{0};base64,{1}".format(image.content_type, encoded_src)
     }
 
-mammoth.images.inline(convert_image)
+mammoth.images.img_element(convert_image)
 ```
 
 ## Writing style maps
diff --git a/mammoth/conversion.py b/mammoth/conversion.py
index 8fe6e4e..a2d1d0d 100644
--- a/mammoth/conversion.py
+++ b/mammoth/conversion.py
@@ -22,7 +22,7 @@ def convert_document_element_to_html(element,
         id_prefix = ""
     
     if convert_image is None:
-        convert_image = images.inline(_generate_image_attributes)
+        convert_image = images.img_element(_generate_image_attributes)
     
     messages = []
     converter = _DocumentConverter(
diff --git a/mammoth/images.py b/mammoth/images.py
index 3def424..4dc095a 100644
--- a/mammoth/images.py
+++ b/mammoth/images.py
@@ -1,7 +1,7 @@
 from . import html
 
 
-def inline(func):
+def img_element(func):
     def convert_image(image):
         attributes = func(image).copy()
         if image.alt_text:
@@ -10,3 +10,6 @@ def inline(func):
         return [html.self_closing_element("img", attributes)]
     
     return convert_image
+
+# Undocumented, but retained for backwards-compatibility with 0.3.x
+inline = img_element
diff --git a/scripts/mammoth b/scripts/mammoth
index 7d683ff..1194540 100644
--- a/scripts/mammoth
+++ b/scripts/mammoth
@@ -24,7 +24,7 @@ def main():
             convert_image = None
             output_path = args.output
         else:
-            convert_image = mammoth.images.inline(ImageWriter(args.output_dir))
+            convert_image = mammoth.images.img_element(ImageWriter(args.output_dir))
             output_filename = "{0}.html".format(os.path.basename(args.path).rpartition(".")[0])
             output_path = os.path.join(args.output_dir, output_filename)
         
diff --git a/tests/images_tests.py b/tests/images_tests.py
new file mode 100644
index 0000000..c3d1689
--- /dev/null
+++ b/tests/images_tests.py
@@ -0,0 +1,8 @@
+from nose.tools import istest
+
+import mammoth
+
+
+@istest
+def inline_is_available_as_alias_of_img_element():
+    assert mammoth.images.inline is mammoth.images.img_element