Epub Accessibility - Changes for Sigil?

[Doitsu]

Originally Posted by philja

All worked much better when I wrapped the footnote <p>'s in an <aside> tag which I suppose I ought to have done first of all. I've now added <aside> to my clips.

FYI: in Apple Books, it makes a difference if you wrap end-of-chapter footnotes in <div> or <aside> tags. Both will be rendered as pop-up footnotes, but footnotes in <aside> tags will be hidden. For more information, see the Apple Books Asset Guide

Originally Posted by Apple Books Asset Guide

Because the <aside> element has an epub:type of footnote, the text is hidden in the main body of the book. The text will only be seen by the reader in the context of the popup. [...]

Note: When adding pop-up footnotes in EPUB 3 books, you can replace the <aside> element with a <div> or <p> element. Use the <aside> element when you want to hide the footnote; use a <div> or <p> element when you want the footnote to appear in the normal reading view. If you use <div> or <p> and a user clicks the footnote link, the content appears in a popup, but the footnote is also visible as part of the text on the page.

[KevinH]

Unfortunately, Apple's Books.app is the only one that does that. I guess you want to be sure not to create an entire endnotes or footnotes section using a list of aside tags if you actually want them to be seen on Books.app.

Strange really.

[KevinH]

I have been trying to build a better set of allowable tags for the Insert Roles. The Aria docs provide a list of allowed tags includes lots of tags that may take on "any" role but are ludicrous to use for footnotes, endnotes, and sections, etc.

The specs technically allow a kbd tag to have the role of doc-footnote which makes no sense.

Their list of tags that accept any role, is just too long and too silly for words.

I am testing out various "saner" mappings in my github repo.

[KevinH]

Should we actually even include section and aside in the Examples clips bar as they do not work on epub2?

Perhaps instead of an aria specific clips bar or adding to our Example clips (things only good on epub3), we should add a second epub3 only Insert menu item, called "Insert Aria Code Snippets" that contains an expanded list of code templates from the "Examples" post a few back.

If we make a new class for it we can use normal translations for all the template fill in placeholders so that they make sense in all languages.

I think I am leaning that way but ...

Thoughts on that?

[DNSB]

With that menu only showing when editing an ePub3? Sounds good to me.

[KevinH]

Originally Posted by DNSB

With that menu only showing when editing an ePub3? Sounds good to me.

Yes, disabled (greyed out) otherwise.

[philja]

Originally Posted by KevinH

Yes, disabled (greyed out) otherwise.

Sounds good.

And maybe grey out the existing 'Epub3 Tools' when working on an epub2 book?

[KevinH]

You should not use the same approach to grey out the epub3 Tools menu as it is not tied at all to CodeView. Those tools should be available at all times on epub3.

In addition, all of that menu and its contents are protected against being run on epub2 (will warn you and not do anything) and they have been there from Sigil 0.9x betas and are required tools for epub3 users to get a working epub, not optional like the Accessibility Insert Roles ...

So no change there. That menu will stay enabled I think.

[KevinH]

Hi All, after staring at many examples and looking for commonality, here is the set of Accessibility Code Templates I am thinking of including in Sigil under a new epub3 enabled/disabled Insert menu item:

PLACEHOLDER_TEXT (These placeholders would be translated)
----------------
CHAPTER_TITLE_HERE
TEXT_OF_FOOTNOTE_HERE
TEXT_OF_ENDNOTE_HERE
HREF_TO_ENDNOTE
HREF_RETURN_FROM_ENDNOTE
LABEL_FOR_SIDEBAR
LABEL_FOR_TIP
_N_ /* number of footnote, endnote, page, etc */

Here are the Aria Code Templates I was thinking about:

Section
-------
<section>
    \1
</section>


Aside
-----
<aside>
    \1
</aside>


Chapter Section
---------------
<section role="doc-chapter" epub:type="chapter" aria-labelledby="heading1">
    <h1 id="heading1">CHAPTER_TITLE_HERE</h1>
    \1
</section


Footnotes Section
-------------------------
<section role="doc-footnotes" epub:type="footnotes">
    \1
</section


Footnote Reference
------------------
<a id="ref_fn_N_" href="#fn_N_" epub:type="noteref" role="doc-noteref">[_N_]</a>


Footnote Backlink
-----------------
<a href="ref_fn_N_" epub:type="backlink" role="doc-backlink">[_N_]</a>


Footnote With BackLink (aside)
------------------------------
<aside id="fn_N_" epub:type="footnote" role="doc-footnote">
    <p>
        <a href="#ref_fn_N_" epub:type="backlink" role="doc-backlink">[_N_]</a>
        TEXT_OF_FOOTNOTE_HERE
    </p> 
</aside>


Footnote With BackLink (div)
-----------------------------
<div id="fn_N_" epub:type="footnote" role="doc-footnote">
    <p>
        <a href="#ref_fn_N_" epub:type="backlink" role="doc-backlink">[_N_]</a>
        TEXT_OF_FOOTNOTE_HERE
    </p> 
</div>


EndNote Reference
------------------
<a id="ref_en_N_" href="HREF_TO_ENDNOTES#en_N_" epub:type="noteref" role="doc-noteref">[_N_]</a>


EndNote BackLink
----------------
<a href="HREF_FOR_RETURN_FROM_ENDNOTE#en_N_" epub:type="backlink" role-"doc-backlink">[_N_]</a>


EndNotes Section
----------------
<section epub:type="endnotes" rol="doc-endnotes">
  <ol>
  </ol>
</section>


Endnote with BackLink (li)
--------------------------
    <li id="en_N_" epub:type="endnote">
        <p>
            <a href="HREF_FOR_RETURN_FROM_ENDNOTE#en_N_" epub:type="backlink" role-"doc-backlink">[_N_]</a>    
            TEXT_OF_ENDNOTE_HERE
       </p>
    </li>
 

Tip
---
<aside role="doc-tip" epub:type="tip" aria-label="LABEL_FOR_TIP">
    \1
<aside>


PageBreak hr
------------
<hr epub:type="pagebreak" role = "doc-pagebreak" />


Page List PageBreak (span)
--------------------------
<span id="page_N_" epub:type="pagebreak" role = "doc-pagebreak" aria-label="Page _N_" />

Any thoughts and feedback before I start coding this all up would be welcome.

None of these templates would be user editable, but of course a user could easily create their own editable clip to use in place of any other these.

Thanks for you thoughts and feedback. Hopefully we are getting closer to the end.

[KevinH]

Okay for those interested, I have added an Insert Aria Clips menu item and all of the support code around it and pushed the whole thing to master on my personal github site.

It is all very rough for now. Still Proof of Concept but if you build your own please pull from my repo:

https://github.com/kevinhendricks/Sigil

And fire up an empty epub3 and play around with those Aria clips templates.

If people like this approach, then I will work on a way to save and read that set of clips from an ini or xml file so that more advanced users can modify these clip templates to match their own needs. Right now they are all hardcoded in Misc/AriaClips.cpp and .h.

Please give it a try and let me know what you think of this idea/approach.

If people are generally happy, I will move this into Sigil master and make a broader CI set of betas for additional people to play with.

Thanks!

[KevinH]

Originally Posted by KevinH

You should not use the same approach to grey out the epub3 Tools menu as it is not tied at all to CodeView. Those tools should be available at all times on epub3.

In addition, all of that menu and its contents are protected against being run on epub2 (will warn you and not do anything) and they have been there from Sigil 0.9x betas and are required tools for epub3 users to get a working epub, not optional like the Accessibility Insert Roles ...

So no change there. That menu will stay enabled I think.

But we could disable its submenu contents.

I have taken a shot at disabling all the epub3 Tools submenu items (greyed out) on epub2 just like BeckyEbook but did not tie it to CodeView. Instead it happens in UpdateUiWithCurrentFile which is called after every epub load and when creating empty epubs.

I have pushed this to master on my repo.

[KevinH]

And I have pulled everything into Sigil master to create a Beta when things calm down a bit more.