Fixes #1600. Adds documentation and caveats about image formats system within rich text

docs/advanced_topics/customisation/page_editing_interface.rst

@@ -35,6 +35,8 @@ As standard, Wagtail organises panels into three tabs: 'Content', 'Promote' and
         ])
 
 
+.. _rich-text:
+
 Rich Text (HTML)
 ~~~~~~~~~~~~~~~~
 
@@ -74,6 +76,8 @@ To inject JavaScript into the Wagtail page editor, see the :ref:`insert_editor_j
 
 For information on developing custom ``hallo.js`` plugins, see the project's page: https://github.com/bergie/hallo
 
+.. _rich_text_image_formats:
+
 Image Formats in the Rich Text Editor
 -------------------------------------
 
@@ -98,7 +102,10 @@ To begin, import the the ``Format`` class, ``register_image_format`` function, a
   The label used in the chooser form when inserting the image into the :class:`~wagtail.wagtailcore.fields.RichTextField`.
 
 ``classnames``
-  The string to assign to the ``class`` attribute of the generated ``<img>`` tag.
+  The string to assign to the ``class`` attribute of the generated ``<img>`` tag. 
+
+  .. note::
+    Any class names you provide must have CSS rules matching them written separately, as part of the front end CSS code. Specifying a ``classnames`` value of ``left`` will only ensure that class is output in the generated markup, it won't cause the image to align itself left.
 
 ``filter_spec``
   The string specification to create the image rendition. For more, see the :ref:`image_tag`.

docs/topics/images/using_in_templates.rst

@@ -170,3 +170,30 @@ You can also use the ``attrs`` property as a shorthand to output the attributes
 .. code-block:: django
 
     <img {{ tmp_photo.attrs }} class="my-custom-class" />
+
+
+Images embedded in rich text
+----------------------------
+
+The information above relates to images defined via image-specific fields in your model, but images can also be embedded arbitrarily in Rich Text fields by the editor (see :ref:`rich-text`).
+
+Images embedded in Rich Text fields can't be controlled by the template developer as easily. There are no image objects to work with, so the ``{% image %}`` template tag can't be used. Instead editors can choose from one of a number of image "Formats" at the point of inserting images into their text.
+
+Wagtail comes with three pre-defined image formats, but more can be defined in Python by the developer. These formats are:
+
+.. glossary::
+
+    ``Full width``
+        Creates an image tag using the filter ``width-800`` and given the CSS class ``full-width``
+
+    ``Left-aligned``
+        Creates an image tag with the filter ``width-500`` and given the CSS class ``left``
+
+    ``Right-aligned``
+        Creates an image tag with the filter ``width-500`` and given the CSS class ``right``
+
+.. Note::
+
+    The CSS classes added to images do **not** come with any accompanying stylesheets, or inline styles. e.g the ``left`` class will do nothing, by default. The developer is expected to add these classes to their front end CSS files, to define what exactly ``left``, ``right`` or ``full-width`` means *to them*.
+
+For more information about image formats, including creating your own, see :ref:`rich_text_image_formats`