Epub Accessibility - Changes for Sigil?

[KevinH]

Okay, I have searched for code examples that are recommended for Accessibility.

Please look at this list, and make any corrections or changes you want. Please suggest some additional examples that help make things clearer.

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


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" aria-labelledby="#fns tart">
    <h1 id="fnstart">Footnotes</h1>
    \1
</section


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


Cover Section
-------------
<section epub:type="cover" aria-label="Cover">
    <img src="HREF_TO_COVER_IMAGE_HERE" 
         alt="DESCRIPTION_OF_COVER_HERE" 
         epub:type="cover-image" role="doc-cover" />
</section


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

<span id="page5" epub:type="pagebreak" role = "doc-pagebreak" aria-label="Page 5" />


Footnote
----------
<p>SOME_TEXT_HERE<a href="#fn1" id="fnref1" epub:type="noteref" role="doc-noteref">[1]</a></p>

<aside id="fn1" epub:type="footnote" role="doc-footnote">
    <p>1. TEXT_OF_FOOTNOTE_HERE <a href="#fnref1" epub:type="backlink" role="doc-backlink">[return]</a></p>
</aside>


Endnote within Endnotes Section 
------------------------------------

<p>SOME_TEXT_HERE<a href="HREF_TO_ENDNOTES#en3" id="enref3" epub:type="noteref" role="doc-noteref">[3]</a></p>
 
<section epub:type="endnotes" rol="doc-endnotes">
  <ol>
    <li>ENDNOTE_1_HERE</li>
    <li>ENDNOTE_2_HERE</l1>
    <li id="en3" epub:type="endnote"><p>3. ENDNOTE_3_TEXT_HERE <a href="HREF_FOR_RETURN#enref3" epub:type="backlink" role="doc-backlink">return</a></p></li>
...
  </ol>
</section>


Sidebar
-------
<aside aria-label="About the Author">
    <p>SIDEBAR_TEXT_HERE</p>
</aside>

All feedback welcome!

[BeckyEbook]

I built Sigil and it looks encouraging.

Still missing is the disabling of the "Role" menu for the EPUB2 file, if you're considering it, because there's no precedent.
In my private version I use this way to disable the Tools > Epub3 Tools menu when I edit an EPUB2 file.

The easiest way to do this is by adding a paremeter for SetStateActionsCodeView:

Call:

QString epubversion = m_Book->GetConstOPF()->GetEpubVersion();
SetStateActionsCodeView(epubversion);

Function:

void MainWindow::SetStateActionsCodeView(QString epubversion)
{
    ...
    ui.actionInsertRole->setEnabled(epubversion == "2.0" ? false : true);
    ...
    ui.menuEPUB3Tools->setEnabled(epubversion == "2.0" ? false : true);
    ...

This idea only comes from the fact that [quote]:
"As XHTML 1.0 was released before ARIA 1.0, EPUB 2 does not support the use of ARIA attributes. Inclusion of the attributes will result in validation errors."

[KevinH]

Okay, I adopted your disable Insert Role approach, and fixed omitted doc-pullquote pieces.

I pushed this to master on my personal repo.

[Doitsu]

Originally Posted by KevinH

Okay, I adopted your disable Insert Role approach, and fixed omitted doc-pullquote pieces.

I pushed this to master on my personal repo.

Since my Linux machine broke down and I don't have a Windows build environment could you maybe build some macOS and Windows beta versions?

[KevinH]

Yes, happy to but they would be for MacOS. To easily build for other platforms I would have to push these changes to Sigil master and use the CI build and deploy. And I did not feel good about that yet, as it takes a significant new translation effort across the twenty or so languages due to all the descriptions (40 or so). Not something for a Sigil 2.5.3 release.

I can try to build it on my Windows VM on my Linux box, when I return early next week from my travels. Or maybe BeckyEbook or DNSB would be able to privately PM you a link to one of their builds.

[KevinH]

@Doitsu (and any other interested parties),

Just in case you have access to a Mac:

I made a quick Sigil.app-Beta-1 build from my kevinhendricks repo and posted them to my personal BuildSigilOnMac repo on github:

https://github.com/kevinhendricks/Bu...nMac/releases/

See:

Sigil.app-Beta-1-Mac-x86_64.tar.xz
Sigil.app-Beta-1-Mac-arm64.tar.xz

[DNSB]

For any interested Windows users, I've attached a link to the build I did from KevinH's Sigil repository. As usual no guarantees that this will do anything but consume drive space.

Sigil-2.5.2-Windows-x64-Setup.exe

[KevinH]

Originally Posted by DNSB

For any interested Windows users, I've attached a link to the build I did from KevinH's Sigil repository. As usual no guarantees that this will do anything but consume drive space.

Sigil-2.5.2-Windows-x64-Setup.exe

Thank you!

[KevinH]

Any more thoughts on this? Given the current Insert Role dialog (that is disabled under epub2) and is current tag sensitive, do we need a dedicated clips tool just to insert section tags?

Should we just change the default clips.ini file to include an empty section so that new users can find it?

Frankly most of the current example clips are pretty worthless in modern Sigil. Maybe we should redo completely the Example clips.

Thoughts Anyone?

[KevinH]

In fact, I think that at least one of the Examples for a style selector in Clips is wrong.

One style says "Highlight Anchor ids" and if appiled as an attribute selector on anchors seems to do nothing:

a[id class!="sigil_indexc_marker] { color: blue; }

I think what should be there according to modern CSS guides is the following:

a[id]:not([class="sigil_index_marker"]){ color:blue; }

The bottom one at least does what you think and works. The actual clip one seems to be broken.

Maybe we really should recreate the Clips Examples as they seem to be in bad shape.

[KevinH]

What are people using as valuable clips?

If anyone has a few good ones to share, that would help.
My own thinking is:

1. p
2. h1
3. h2
4. h3
5. span
6. div
7. class=""
8. hr
9. br
10. section (empty)
11. table 3x2
12. section (chapter)
13. a with href
14. reference to a footnote
15. aside footnote and id for backlink
16. aria-label=""
17. aria-labelledby=""
18. Sigil Split Marker


And maybe a clip that includes a smart quotes in matching open and close pairs

Please add any additional Example clips you think others would find useful. And we can maybe come up with a much better set of Example clips than what is there now.

[philja]

Originally Posted by KevinH

@Doitsu (and any other interested parties),

Just in case you have access to a Mac:

I made a quick Sigil.app-Beta-1 build from my kevinhendricks repo and posted them to my personal BuildSigilOnMac repo on github:

https://github.com/kevinhendricks/Bu...nMac/releases/

See:

Sigil.app-Beta-1-Mac-x86_64.tar.xz
Sigil.app-Beta-1-Mac-arm64.tar.xz

I used your Mac-arm64 beta build to have a go at the new Role insertion dropdown menu.

Mostly useful provided you have a fair knowledge of what semantics you require but I did have a problem with footnotes.

I was using one of my books which have 1 to 6 footnotes at the end of each chapter. The footnotes are separated from the chapter text by a short (width 25%) <hr /> element. The only choice at the <hr /> level is page-break which is definitely what I don't want.

Beneath the <hr/> element is a <p> for each footnote. The only 'role' choice at this level is 'biblioentry' which is not what I need because the footnotes are all to internal references and not external.

The only way I found to apply a footnotes role is to wrap the <hr/> and all the <p>'s in a <div> tag. Then I was offered the epub:type footnotes as a choice.

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.

The footnote anchor in the chapter body text and the backlink were easy to use.

[KevinH]

Interesting. Given the examples I posted above, did you try wrapping the footnotes themselves in a section tag immediately after the hr?

See:

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

This was taken from one of the aria to epub type guides as a good example of how to do it.

Using a section tag will allow it to be included in an auto generated chapter outline by the accessibility reader allowing users to quickly find that section, or more likely skip over its contents (if they chose to already follow the footnote links themselves).

[philja]

Originally Posted by KevinH

Interesting. Given the examples I posted above, did you try wrapping the footnotes themselves in a section tag immediately after the hr?

See:

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

This was taken from one of the aria to epub type guides as a good example of how to do it.

Using a section tag will allow it to be included in an auto generated chapter outline by the accessibility reader allowing users to quickly find that section, or more likely skip over its contents (if they chose to already follow the footnote links themselves).

No, quite honestly, the use of a section tag didn't occur to me at the footnote point. The whole of each chapter is wrapped in a section tag and I didn't think of using another one there.

I think I'll stick with <aside>'s since that seems to be what interests Amazon in the footnotes department.

[KevinH]

Section tags can be nested and Chapters and other sections can have more than one section either nested or in series.

Using an aside is recommended for footnotes but I thought by adding the hr you were trying to visually create a separator to effectively create a section of footnotes.

Thanks for feeding back your thoughts!