Consistent alt and titles in SVGs

_docs/advanced/html-transformations.md

@@ -12,7 +12,7 @@ The template already includes some transformations:
 - For accessibility purposes, the `epubAriaSidenotes` transformation gives all elements with the class `sidenote` the ARIA attribute `role="note"`.
 - We use transformations in PDF to generate QR codes from `include qr-code` tags.
 
-Transformations are currently supported for epub and EPUB outputs only.
+Transformations are currently supported for epub and PDF outputs only.
 
 To add a transformation for epub output, add a file containing a single function file to `_tools/gulp/transformations/epub`. You would do the same for PDF by adding a function file to `_tools/gulp/transformations/pdf`.
 

_docs/editing/figures.md

@@ -32,13 +32,14 @@ In the tag for each figure, we can define the following information:
 * a reference (e.g. 'Figure 1.2', which will appear in front of the caption)
 * a link (clicking the image opens this link; without it, by default clicking the image opens the image file)
 * a caption (appears below the image)
-* a title (can be used to title descriptive text)
+* a slide-caption (appears below the image in slidelines)
+* a title (serves as the title attribute that becomes a mouseover tooltip, and an SVG's accessibility title)
 * alt text (a description of the image, e.g. for screen readers)
 * a source (appears below the figure)
 * the height of the image in lines
 * a [class](classes.html) (for styling the layout of a given figure).
 
-The template uses that information differently depending on the output format. For instance, on the web and in the epub, the alt text is the text that screen-readers will read aloud to visually impaired users who can't see an image; and we don't need to display it in print.
+The template uses that information differently depending on the output format. For instance, on the web and in the epub, the alt text is the text that screen-readers will read aloud to visually impaired users who can't see an image; and we don't need to display it in print. The `title` is important for accessibility when your image is an SVG.
 
 A caption and alt text are similar, but not the same. A caption usually provides information about the figure, while alt text describes its appearance for someone who can't see the image.
 
@@ -72,23 +73,24 @@ caption='Blake's illustration for "The Tyger".'
 caption="Blake's illustration for “The Tyger”."
 ```
 
-### Multiple images and alt text
+### Multiple images and titles and alt text
 
 You can have multiple images in the same figure. Include each image's filename in a comma-separated list.
 
-Each image needs its own alt text. To do this, include each image's alt text in order, separated by `|`.
+Each image needs its own alt text, and can have its own title. To do this for alt text, include each image's alt text in order, separated by `|`. Do the same for `title` if each image has a different title.
 
 {% raw %}
 ```
 {% include figure
    images="mydog.jpg, yourdog.jpg"
    caption="Our dogs."
-   alt-text="A chocolate-coloured labrador | A grey husky."
+   alt-text="A chocolate-coloured labrador. | A grey husky."
+   title="Labrador | Husky"
 %}
 ```
 {% endraw %}
 
-Each image matches each piece of alt text in order. If you include multiple images in a figure, make sure you provide separate alt text for each image. If you don't, some images will have no alt text.
+Each image matches each piece of alt text (or title) in order. If you include multiple images in a figure, make sure you provide separate alt text for each image. If you don't, some images will have no alt text. Titles are less important for accessibility, and are therefore optional.
 
 ### Rotating figures
 

_docs/editing/images.md

@@ -10,24 +10,10 @@ order: 3
 * toc
 {:toc}
 
+{% comment %} Don't process Liquid tags in these docs. {% endcomment %}
 {% raw %}
 
-## Adding images in markdown
-
-You can use standard markdown to embed images:
-
-~~~
-![A description of the image](../{{ site.image-set }}/filename.svg)
-~~~
-
-Let's break that down:
-
-* the exclamation mark and square and round brackets make up the basic markdown image syntax: `![Description](filename)`. The description is especially important for screen-readers used by the visually impaired.
-* `../` means 'go up, out of the `text` folder'
-* `{{ site.image-set }}/` means 'go into the folder containing our preferred set of images' (as defined in `_config.yml`). The default image-set folder is `images`.
-* finally, the image file name.
-
-### Responsive images
+### The `include image` tag
 
 To add an image, you can use standard [kramdown syntax](https://kramdown.gettalong.org/quickref.html#links-and-images), as described above, but then you'll be missing a key feature of this template: your user's browser won't fetch the size of image best suited to their device.
 
@@ -45,22 +31,10 @@ If necessary, you can add `class`, `id` and/or `alt` attributes to the image, to
 {% include image file="foobar.jpg" class="example" alt="An example image." id="anyuniqueid" %}
 ```
 
-(You can also use `src="foobar.jpg"` instead of `file="foobar.jpg"`, if you're used to standard HTML `img` syntax, which uses `src`.)
-
-### Images in translations
-
-If you are creating a [translation](translations.html) in a subdirectory of `text`, and your images are in the parent book folder, you need to change the path to the images slightly. You have three options:
-
-1. From version 0.10 of the template, you can use `{{ images }} metadata tag, which will always create the correct path to your images. At the top of your markdown file, add `{% include metadata %}`, so that you can use metadata variables in that file.
-1. In older versions of the template: use the `{{ path-to-book-directory }}` metadata tag. At the top of your markdown file, add `{% include metadata %}`, so that you can use metadata variables in that file. Then instead of any `../`s, you use the tag: `{{ path-to-book-directory }}{{ site.image-set }}/filename.jpg`.
+For accessibility, it's important to always include a description of the image as `alt` text, unless the image is purely decorative.
 
-   Even if you're not in a translation folder, it's good practice to always use the `{{ path-to-book-directory }}` tag for maximum portability, if you don't mind having the `{% include metadata %}` tag at the top of your files. Ultimately this image include will look like this: `![A description of the image]({{ path-to-book-directory }}{{ site.image-set }}/filename.jpg)`
+You can also use `src="foobar.jpg"` instead of `file="foobar.jpg"`, if you're used to standard HTML `img` syntax, which uses `src`.
 
-1. In very old versions of the template: add another `../` for each directory level. So if your translation text is in `book/fr`, anf your images are in the `book` folder, you need to come up two levels before going into `book/images`. So your path is `../../{{ site.image-set }}/filename.jpg`.
-
-   Ultimately, your image include will be `![A description of the image](../../{{ site.image-set }}/filename.jpg)`.
-
-{% endraw %}
 
 ## Image size
 
@@ -70,91 +44,148 @@ In PDF output, you can use a class to specify the exact height of the image in l
 {% include image file="foobar.jpg" class="height-15" %}
 ```
 
-> CSS tip: [If you're having trouble with SVGs having space around them](https://stackoverflow.com/questions/24626908/how-to-get-rid-of-extra-space-below-svg-in-div-element), in your CSS make sure you set the height of the `img` element. SVGs are inline elements by default, and will add white space around them.
+CSS tip: [If you're having trouble with SVGs having space around them](https://stackoverflow.com/questions/24626908/how-to-get-rid-of-extra-space-below-svg-in-div-element), in your CSS make sure you set the height of the `img` element. SVGs are inline elements by default, and will add white space around them.
+{:.box}
+
+
+## Standard markdown image syntax
+
+You can also use standard markdown to embed images:
+
+~~~
+![A description of the image](../{{ site.image-set }}/filename.svg)
+~~~
+
+Let's break that down:
+
+* the exclamation mark and square and round brackets make up the basic markdown image syntax: `![Description](filename)`. The description is especially important for screen-readers used by the visually impaired.
+* `../` means 'go up, out of the `text` folder'
+* `{{ site.image-set }}/` means 'go into the folder containing our preferred set of images' (as defined in `_config.yml`). The default image-set folder is `images`.
+* finally, the image file name.
+
+However, it is usually simpler and you'll get better HTML if you use the `include image` tag described above. For example, you don't need to worry about the paths to images in translations.
+
+### Images in translations
+
+If you are using standasrd markdown iamge syntax, and you are creating a [translation](translations.html), and your images are in the parent language's folder, you need to change the path to the images slightly. You have three options:
+
+1. From version 0.10 of the template, you can use `{{ images }} metadata tag, which will always create the correct path to your images. At the top of your markdown file, add `{% include metadata %}`, so that you can use metadata variables in that file.
+1. In older versions of the template: use the `{{ path-to-book-directory }}` metadata tag. At the top of your markdown file, add `{% include metadata %}`, so that you can use metadata variables in that file. Then instead of any `../`s, you use the tag: `{{ path-to-book-directory }}{{ site.image-set }}/filename.jpg`.
+
+   Even if you're not in a translation folder, it's good practice to always use the `{{ path-to-book-directory }}` tag for maximum portability, if you don't mind having the `{% include metadata %}` tag at the top of your files. Ultimately this image include will look like this: `![A description of the image]({{ path-to-book-directory }}{{ site.image-set }}/filename.jpg)`
+
+1. In very old versions of the template: add another `../` for each directory level. So if your translation text is in `book/fr`, and your images are in the `book` folder, you need to come up two levels before going into `book/images`. So your path is `../../{{ site.image-set }}/filename.jpg`.
+
+   Ultimately, your image include will be `![A description of the image](../../{{ site.image-set }}/filename.jpg)`.
+
 
 ## Images over a double-page-spread
 
 There is no easy way to put images over a double-page spread, but there is a way to hack it.
 
-Of course, images across a DPS are not an ebook or web issue (if an ereader or browser shows 'pages' as a DPS, we have no control over it anyway). They are only a print issue. The problem is that PrinceXML does not provide a mechanism for placing images (or any element) across a spread. 
+Of course, images across a DPS are not an ebook or web issue (if an ereader or browser shows 'pages' as a DPS, we have no control over it anyway). They are only a print issue. The problem is that PrinceXML does not provide a mechanism for placing images (or any element) across a spread.
 
 In short, what we do is:
 
-1. Place the image twice, each in a `div` (as HTML) or `blockquote` (possible with markdown) element.
-2. Using PrinceXML's `next` modifier for floats, we float the div or blockquote elements on the first and second pages of the DPS respectively.
-3. Inside each div or blockquote, we position the image so that, on the left, only the left half of the image shows; and on the right, only the right half of the image shows.
+1. Place the image twice, each in a `div` HTML element.
+2. Using PrinceXML's `next` modifier for floats, we float the `div` elements on the first and second pages of the DPS respectively.
+3. Inside each `div`, we position the image so that, on the left, only the left half of the image shows; and on the right, only the right half of the image shows.
 
 This all depends on placing your image reference in a way that the first blockquote–image falls on a left-hand page.
 
 Here's a step-by-step guide using example code:
 
 1. The image itself must be in the right aspect ratio. This method cannot (yet) resize or crop your image for you with CSS. In this example here, the image must be 270×120 (landscape), including an allowance for 5mm bleed.
-2. In the markdown text file, place the image twice, each inside a blockquote, and tag the first instance `{:.dps-left}` and the second `{:.dps-right}`.
-   
+2. In the markdown text file, place the image twice, each inside a `div`, and tag the first instance `{:.dps-left}` and the second `{:.dps-right}`.
+
    ``` markdown
-   > ![1](images/lion.tif)
-   {:.dps-left}
-
-   > ![1](images/lion.tif)
-   {:.dps-right}
+   <div class="dps-left">
+      {% include image file="lion.tif" %}
+   </div>
+
+   <div class="dps-right">
+      {% include image file="lion.tif" %}
+   </div>
    ```
 
 3. Hide the second instance of the image in any web, app or epub CSS:
-   
+
    ``` css
    /* Hide second instance of images intended for DPS in print */
-   .dps-right { 
+   .dps-right {
      display: none;
    }
    ```
 
 4. In print CSS, use this. Follow the comments to modify sizes to suit your page size and layout:
-   
+
    ``` css
    /* DPS images */
-
-   blockquote.dps-left {
-   float: top;
-   margin: -20mm 0 10mm -5mm; /* Here you're aiming to start the image in the page bleed top left */
-   width: 135mm; /* Page width plus one side's bleed, e.g. 130mm wide plus 5mm bleed */
-   height: 120mm; /* Exact height of the image */
-   text-align: left;
+
+   .dps-left {
+      float: top;
+      text-align: left;
+
+      /* Start the image in the page bleed top left */
+      margin: -20mm 0 10mm -5mm;
+
+      /* Page width plus one side's bleed, e.g. 130mm wide plus 5mm bleed */
+      width: 135mm;
+
+      /* Exact height of the image */
+      height: 120mm;
    }
-   blockquote.dps-right {
-   float: top next;
-   margin: -20mm 0 10mm -5mm; /* Here you're aiming to place the image in the page bleed top right */
-   width: 135mm; /* Page width plus one side's bleed, e.g. 130mm wide plus 5mm bleed */
-   height: 120mm; /* Exact height of the image */
-   text-align: right;
+   .dps-right {
+      float: top next;
+      text-align: right;
+
+      /* Place the image in the page bleed top right */
+      margin: -20mm 0 10mm -5mm;
+
+      /* Page width plus one side's bleed, e.g. 130mm wide plus 5mm bleed */
+      width: 135mm;
+
+      /* Exact height of the image */
+      height: 120mm;
    }
-   blockquote.dps-left p img {
-   width: 270mm; /* This must be exactly double the width above */
-   max-height: 120mm; /* This must be the same as the height above */
-   position: absolute;
-   left: -5mm;
+   .dps-left img {
+      position: absolute;
+      left: -5mm;
+
+      /* Must be exactly double the width above */
+      width: 270mm;
+
+      /* Must be the same as the height above */
+      max-height: 120mm;
    }
-   blockquote.dps-right p img {
-   width: 270mm; /* Ditto */
-   max-height: 120mm; /* Ditto */
-   position: absolute;
-   right: -5mm;
+   .dps-right img {
+      position: absolute;
+      right: -5mm;
+
+      /* Ditto */
+      width: 270mm;
+
+      /* Ditto */
+      max-height: 120mm;
    }
    ```
 
 That's all based on these page settings. Yours may differ, affecting your margins, heights and widths accordingly:
 
 ``` css
 @page {
-    size: 130mm 200mm;
-    margin-top: 15mm;
-    margin-bottom: 20mm;
-    margin-outside: 0;
-    margin-inside: 0;
-    prince-bleed: 5mm;
-    prince-trim: 5mm;
+   size: 130mm 200mm;
+   margin-top: 15mm;
+   margin-bottom: 20mm;
+   margin-outside: 0;
+   margin-inside: 0;
+   prince-bleed: 5mm;
+   prince-trim: 5mm;
 }
 ```
 
 We've done very little testing with this so far, so your results may vary.
 
-There is another example [here](https://github.com/electricbookworks/electric-book/issues/164).
+There is another example [in the template's issues on GitHub](https://github.com/electricbookworks/electric-book/issues/164).
+
+{% endraw %}