Revert "Fix images and alt tags, fix #621, fix #622"

1 files changed, 44 insertions, 38 deletions

diff --git a/style_guide.rst b/style_guide.rst
index c5258b9db..030dcfc1f 100644
--- a/style_guide.rst
+++ b/style_guide.rst
@@ -6,22 +6,22 @@ Nextcloud manuals style guide
 
 See the `Documentation README <https://github.com/nextcloud/documentation/blob/master/README.rst>`_ for information on setting up your documentation build environment
 
-See `reStructuredText Primer <http://sphinx-doc.org/rest.html>`_ for a complete
+See `reStructuredText Primer <http://sphinx-doc.org/rest.html>`_ for a complete 
 Sphinx/RST markup reference.
 
-This is the official style guide for the Nextcloud Administration and User
-manuals. Please follow these conventions for consistency, and easier
+This is the official style guide for the Nextcloud Administration and User 
+manuals. Please follow these conventions for consistency, and easier 
 proofreading and copyediting.
 
-When you are writing your text, make it as literal and specific as possible. Put
-yourself in the place of the person who is using Nextcloud and looking for
-instructions on performing a task. Don't make them guess, but spell
-out every step in order, and tell exactly what buttons to click or what form
-fields to fill out. Give complete information; for example, when configuring a
-timeout value be sure to say if it is in seconds or some other value. Say
-``config.php`` rather than "the configuration file". When you are describing
-features of a GUI administration form use the exact literal names of buttons,
-form fields, and menus. Specify if menus are dropdown, right-click,
+When you are writing your text, make it as literal and specific as possible. Put 
+yourself in the place of the person who is using Nextcloud and looking for 
+instructions on performing a task. Don't make them guess, but spell 
+out every step in order, and tell exactly what buttons to click or what form 
+fields to fill out. Give complete information; for example, when configuring a 
+timeout value be sure to say if it is in seconds or some other value. Say 
+``config.php`` rather than "the configuration file". When you are describing 
+features of a GUI administration form use the exact literal names of buttons, 
+form fields, and menus. Specify if menus are dropdown, right-click, 
 left-click, or mouseover.
 
 Page filenames
@@ -32,8 +32,8 @@ Use lowercase filenames with underscores, for example file_name_config.rst.
 Page titles and headings
 ------------------------
 
-There are many ways to markup headings and subheadings. This is the official
-Nextcloud way. Use sentence case. Three levels is enough; if you find that you want more,
+There are many ways to markup headings and subheadings. This is the official 
+Nextcloud way. Use sentence case. Three levels is enough; if you find that you want more, 
 then re-think the organization of your text::
 
  ==============
@@ -45,7 +45,7 @@ then re-think the organization of your text::
 
  Subhead, h3
  ^^^^^^^^^^^
-
+ 
 This is how they render:
 
 ==============
@@ -61,9 +61,9 @@ Subhead, h3
 Labels and code
 ---------------
 
-Elements in a GUI configuration form are in bold, and should be described as
-literally as possible, so that your description matches what your reader sees
-on the screen. For example, on the User listing page describe the various
+Elements in a GUI configuration form are in bold, and should be described as 
+literally as possible, so that your description matches what your reader sees 
+on the screen. For example, on the User listing page describe the various 
 elements like these examples::
 
  **Username** field
@@ -72,9 +72,9 @@ elements like these examples::
  **Create** button
  **Full Name** field
  **Quota** dropdown menu
-
+ 
 This is how they render:
-
+ 
 **Username** field
 
 **Password** field
@@ -87,21 +87,23 @@ This is how they render:
 
 **Quota** dropdown menu
 
-.. image:: users-config.png
-   :alt:
-
+.. figure:: users-config.png
+   :alt: User listings and administration page.
+   
+   *Figure 1: The Nextcloud user listing and administration page.*
+   
 Use double-backticks for inline code and command examples::
-
+  
   ``sudo -u www-data php occ files:scan --help``
   ``maintenance:install``
-
+  
 This is how they render:
 
 ``sudo -u www-data php occ files:scan --help``
 
 ``maintenance:install``
 
-When you are giving hyperlinks as examples, use double-backticks rather than
+When you are giving hyperlinks as examples, use double-backticks rather than 
 creating a live hyperlink::
 
  ``https://example.com``
@@ -111,22 +113,26 @@ Images
 
 Use lowercase with hyphens for image names, for example image-name.png.
 
-Images should be in .png format. Keep your screenshots focused on the items you
-are describing. When you need an image of something large like a configuration
-form on the Nextcloud admin page, narrow your Web browser to fold the fields
-into a smaller space, because a long skinny graphic is not very readable. Think
+Images should be in .png format. Keep your screenshots focused on the items you 
+are describing. When you need an image of something large like a configuration 
+form on the Nextcloud admin page, narrow your Web browser to fold the fields 
+into a smaller space, because a long skinny graphic is not very readable. Think 
 square.
 
-The text should be readable and accessible without the need of the images.
-This is why we use the image element instead of figure, with a present but empty
-alt tag because it would duplicate info when read out by a screen reader::
+Both images and figures must have brief and descriptive alt tags and all 
+figures must have captions with figure numbers. Sphinx RST markup does not 
+have a tag for figure numbers, so you must 
+use the caption element. You may use simple numbering like "Figure 1, Figure 2", 
+or add a caption. Captions must follow a blank line and be italicized, like this example::
 
-  .. image:: images/users-config.png
-   :alt:
+  .. figure:: images/users-config.png
+     :alt: User listings and administration page.
+     
+     *Figure 1: The Nextcloud user listing and administration page.*
 
-Images must go into a sub-directory of the directory containing your manual
-page. Currently the manuals have both a single master images directory, and
-image directories local to each chapter. A single master images directory is
+Images must go into a sub-directory of the directory containing your manual 
+page. Currently the manuals have both a single master images directory, and 
+image directories local to each chapter. A single master images directory is 
 difficult to maintain and inevitably becomes cluttered with obsolete images. Eventually
 the single master directories will be gone.