[Plugin] Access-Aide - help improve epub accessibility
 

Updated: September 17, 2021
Current Version: "0.5.4"

See the Attached: Access-Aide_v054.zip

Official Guthub site: https://github.com/kevinhendricks/Access-Aide

Changes since the Previous Release
- version 0.5.4 - add schema::accessibilityHazard support
- version 0.5.3 - fix accessgui scaling for thin but wide images that truncate to 0 height
- version 0.5.2 - fix Windows mixed case path bug, extra whitespace bug in xmlheader, handle self-closing title tags when updating titles
- version 0.5.1 - fix typo in variable name bug path vs apath
- version 0.5.0 - update to work with new Sigil 1.0 plugin interface
- version 0.4.3 - sync accessgui.py to master, do not add epub:type to body tags
- version 0.4.2 - update rules to assign aria roles based on epub 3.2/3.02 spec
- version 0.4.0 - initial release

License/Copying: GNU LGPL Version 2 or Version 3, your choice. Any other license terms are only available directly from the author in writing.

Minimum Sigil Version: support for this plugin is provided for Sigil 0.9.0 and later using the Python 3.4 or later Python interpreter.


Goal
The goal of this program is to help improve the Accessibility of your epub to help meet ACE requirements. It strives to create an epub that meets the following criteria:


Before you run Access-Aide
Before running AccessAide you should make sure your epub has passed epubcheck and that you have properly added the appropriate semantic tags to mark your ebook files appropriately.


How it Works
This edit plugin will read/edit the content.opf to determine the primary language used, identify any nav or ncx and will add the appropriate metadata.
The ncx or nav is then parsed to collect titles for every xhtml file and in the case of the nav will also collect epub:type landmark information.

Then for each xhtml file, the plugin will:
1. add lang and xml:lang attributes to the html element
2. fill in any missing title tag that is a child of the head tag
3. will add empty alt attributes to any img tag where it is missing
4. collect a list of all image tags and their current alt text descriptions
5. add in appropriate epub:type semantic tags (for epub3 only)
6. map epub:type attributes to their appropriate aria role attribute

Then a graphical user interface is generated showing a thumbnail of every img tag image and its associated alt text description, so that the user can easily and quickly add improves textual descriptions for each image used


Limitations ...
1. In able to properly achieve the schema:accessModeSufficient: textual critieria, Access-Aide will abort when provided with epubs that use javascripts, audio resources, video resources, and mathml because Access-Aide simply can not tell if the proper textual descriptions are provided in these cases.

2. The schema:accessibilityHazard set to none indicates you are using only static images with no Video and no animated gifs. You need to verify that or manually edit this metadata value in your OPF.

3. svg image tags images are ignored as the "alt" attribute is not allowed on those tags. The proper way to handle svg: image tags is to provide the proper title and desc elements immediately after the svg start tag that contains the image element.

Access-Aide Plugin icon
This plugin includes a plugin icon that is in the public domain and provided by the The Accessible Icon Project that can be found at: https://accessibleicon.org for the express purpose for promoting accessibility.


Thanks to DiapDealer, Doitsu, and elibrarian with their help testing and debugging earlier versions of the this plugin and for elibrarian for for promoting the idea in the first place.

For access to fixes before the next release see my github repo for Access-Aide:
https://github.com/kevinhendricks/Access-Aide

Hi

Thank you for this nice plugin!

Display question

I tried it with an Epub3 produced by ODTImport which passes Epubcheck. ODTImport produces a Text/nav.xhtml which I like to place at the end of all files and to add a link with my stylesheet.
It looks like this :


Once I have added semantics, your plugin adds under this nav (in the same xhtml file) the new landmarks nav.



This one is displayed only with the Prince PDF and appears neither in Sigil or in Calibre editor preview. It appears though in Code View with the Calibre editor.

Also to the previous nav has been added the expression : role="doc-toc"

What did I miss to make it appear in Code view and display in preview?

Hi

I got a side help and -needed- explanation. It seems that the landmarks nav is not to be displayed in code view (hidden " ") and that Prince should in fact not display it.

So it was a misunderstanding of mine. The modified Epub3 with its new semantics attributes and the changes made with the Access-Aide plugin is just fine.

I learnt something. Thanks again for this plugin. :thumbsup:

The landmarks are to epub3 very much like the opf guide in epub2. Its entries are used to mark files as to their functional/structural role. They are a required part of a valid nav as the guide itself has been deprecated in epub3. The landmarks section of the nav is typically not displayed directly and is instead meant to be machine readable.

Both epub:type and aria role attributes are meant to be used by the ebook author/developer to add semantic information to aide structural navigation of the epub, and provide screen readers for use by readers with vision impairment or other accessibility issues more information to help better convey the epub.

Help installing the plugin
 

I am so excited about this plugin. But I can't get it to work. Can someone point me in the right direction? When I try to load it via "Manage Plugins", navigate to the folder containing it, etc., everything is greyed out and not chose-able.

I have a feeling I am missing something that is mean to be installed underneath Sigil, but I don't know what it is.

Any help would be greatly appreciated.

A Sigil plugin is a zip file. It should not be unzipped further. The install process will properly handle that.

Many people have download managers or browsers that unzip zip archives automatically when they are downloaded. These will mess up the downlad. Try using a brower like Firefox and right click on the link for the plugin and tell Firefox just to download it and not try to unpack it.

Thank you!

I'm doing a quick writeup of this plugin for epubsecrets.com, and have a couple of questions. Is this the right place to ask them?

Yes, this is the right place to ask questions about this plugin. There is some explanation of exactly what this plugin does in the first post of this thread.

Thanks! A few things I'm unclear on:

1. The readme says to make sure you have "properly added the appropriate semantic tags to mark your ebook files appropriately." Then in the list of things the plugin does, #5 says it will "add in appropriate epub:type semantic tags," and #6 says it will "map epub:type attributes to their appropriate aria role attribute."

What semantic tags should the author have added? Are they something besides the epub:type semantic tags specified in #5? My best guess is the author must manually code epub:type semantic tags before running the plugin, and that only #6 is actually performed by the plugin, not #5. Is this correct?

2. In #2, the plugin "fills in any missing title tag that is a child of the head tag." Is this the text it collects when "The ncx or nav is then parsed to collect titles for every xhtml file?" I was not able to get this to work; is there a precondition of some sort in the xhtml file?

I think that's it, at least for the moment. It's a useful plugin, and I'd like to make sure I represent it accurately in the article.

Thanks for this great plugin! I've just run it for the first time on a book I'm planning to upload to the MR library, and everything went smoothly.

The one thing I don't understand is how to add the description to svg images. I've read the explanation in the first post:

But I don't understand which proper title and desc elements and where exactly to insert them. I'm providing the code for my cover image:


Could someone please put "This is the image description" in the appropriate place(s) for me please?

Here is an example of using title and desc to help improve accessibility in svg as found on the web.

In your case you would add the title tag immediately after the opening svg tag (just before the start of the image tag), followed by the desc tag and then the image tag.

For number 5, Yes, the nav has a landmarks section. These user supplied landmarks semantic tags (epub:type) will be added to the proper body tag or id for each chapter if possible by the plugin

But, the user can and should use the epub3 semantics tool and manually add epub:type attributes to various tags in each part of the book. They should do this before runnng the plugin. The plugin itself will convert the epub:type to an aria role and add that in as well.

It will not replace existing title tag contents in head. So make sure you have the latest version of the plugin and that the current title tags are truly empty (no whitespace). The titles for each file are taken from the nav.

Great. Thanks.

Got it, thank you.

Thanks for the help. The article is live.

testing if thread has been closed, nope, posting works just fine. Use the New Reply button below.

Hi, I have a question which I would appreciate some help with. The plugin adds epub:type tags to each xhtml file, and using the Add Semantics tool in Sigil I've added the epub:type to the body tag successfully. However is there support for adding epub:type tags to heading tags, section tags, list tags, etc? Thanks!

Simply use search and replace in Sigil in CodeView (or saved searches or clips) to do what you want. Sigil supports both normal and regular expression searches.

Access-Aide version 0.4.2 Released
 

Access-Aide version 0.4.2 has now been released. See the first post in this thread for the link to Access-Aide_v042.zip

This version updates the rules for mapping epub:type attributes to aria roles given the epub 3.0.2 spec and changes in which tads aria role attributes may be added.

Thank Doitsu for the head's up and for testing with the latest rc versions of epubcheck.

KevinH

Access-Aide version 0.4.3 Released
 

Access-Aide version 0.4.3 has now been released. See the first post in this thread for the link to Access-Aide_v043.zip

This version updates the accessgui.py code to match master as a previous bug fix was inadvertently dropped.

In addition, given that epub:type attributes on the body tag have been "strongly discouraged", Access-Aide will no longer add epub:type information to any body tag.

KevinH

Using the latest version I've been trying to match aria roles to epub:types. I use the Add Semantics tool on my xhtml files and then run the plugin, but no changes have been happening to the code. I was hoping the matched role would appear on a <section> tag?

Thanks for your help!

What kind of epub:type attribute did you add to the section tag and what role attribute did you expect to be added?

Using Add Semantics I selected 'Chapter' for one of my chapters and ran the plugin, which had no effect on the code of that chapter.

I also added section tags wrapping around the content of the chapter, thinking the doc-role attribute might be added onto this, but nothing happened.

Currently I don't know how to add epub:types or role attributes to my ebook using the plugin and would appreciate any help.

AFAIK, selecting Add Semantics..., will update nav.xhtml and/or content.opf.

You'll need to manually add epub:type attributes in Code View mode to tags in .xhtml files. For example, if you add the following code to an epub3 book:

and run the plugin it'll add a role="doc-chapter" attribute:

Hi again, I've been using this plugin for a long time and love it. I was wondering if there is a certain way of coding the ebook, or a certain technique, that guarantees success when using the add semantics tool. Lately when I've been using the plugin on epub3s, some roles aren't added or in fact none at all after I've followed the steps. However when I double-check the nav, the landmarks list has grown with the semantics added from using the plugin, which makes me wonder why it's not working as I assume everything is in place.

I understand ebooks are coded differently and I would greatly appreciate any help in making mine more compatible with using this plugin.

AcessAide does not "add roles" on its own. It translates epub:type semantics into aria-roles and tries its best to add them where allowed.

Current versions of epubcheck has made this difficult by complaining that aria-roles should never be added to the body tag. This makes no sense at all but Access-Aide tries hard to not cause epubcheck to complain.

One way around these new rules is to manually add section tags to wrap the body contents and then apply epub:type semantics to the section tag. AccessAide will happily convert those to aria-roles equivalent and add them.

So this is really just epubcheck stupidity banning epub:type/aria roles on the body tag where they belong.

Thanks for your quick reply. I've already tried manually adding section tags with epub:type semantics on it, but the roles aren't adding when I run the plugin on some ebooks. However it works on others so I don't know what's the problem is with the ebooks where it's unsuccessful.

Hmm. section tags allow almost all epub:type and aria-roles. So if you have a single xhtml file that has section tags with epub:type attributes that does not get a corresponding role via AccessAide, I would like to see it. Feel free to scramble the text. If you could zip it up and post it here, I will incorporate it into an epub3 and see what is happening.

Thanks for your help. It seems that updating Sigil to the latest version has cured the problem in these ebooks. Thank you.

Announcing Access-Aide_v050
 

Hi All,

Access-Aide version 0.5.0 is now available from the first post in this thread and from my github site:

https://github.com/kevinhendricks/Access-Aide

Changes in this new version:

• update Access-Aide to work with the new Sigil 1.0 plugin interface
• adds ability to run on non-Sigil standard epub layouts
• should still work just fine with Sigil version before Sigil-0.9.991

Hope this helps,

KevinH

Updated to Access-Aide_v051 to fix a variable name typo bug.

Hi, KevinH.

Got some questions about the plugin:

1) I can't make it fill the empty titles. Tested it with epub2 (with NCX and Guide) and epub3 (NCX, Guide, NAV). Also, can't it have an option to override titles that does not match NAV/NCX information?

2) It seems that every time the plugin runs, it adds a space after '<?xml' for every file.

3) The plugin is complaining about the missing DOCTYPE. An xhtml file without a DOCTYPE is really invalid?

4) My books are mostly in Portuguese (BR), so the language is defined in the opf as 'pt-BR'. But when I run the plugin, it adds/changes the lang/xml:lang to 'pt', instead of 'pt-BR'.

A few questions/answers:

1. Perhaps I broke something in the last update? I will look into that. Forcing it to overwrite titles can be made an option for the future but wouldn't it be easier to use Find and Replace to empty all titles if that is what you want before running the plugin?

2. In the xml header? Hmm I have not noticed that but trimming can be added to remove any duplicate space. I will look into how it is being serialized.

3. Yes. Unlike Calibre which ignores that part of the spec, a doctype is required. Especially for epub2 as the doctype is what specifies that named entities are allowed and which ones. Calibre kind of punts on this by removing and all named entities so that it can live without a doctype. That does not meet the spec. Sigil fully supports both named entities so the doctype is not optional. epubcheck has an open issue to check and require this.

4. That must be a bug. It should get the language code directly from the opf metadata first dc:language tag. If it is set to pt-BR then that is what should be added to lang and xml:lang attributes in html tags if something is not already specified.

Thanks!

Does you nav in the toc use urls with fragment identifiers on the end even for top of file references by any chance?

I looked at the plugin code for your point 4. It seems to have the region code removed deliberately. I am not really sure why that was added to begin with. Either way this can easily be removed.

Yes, that could be done easily enough. But since the plugin is going to run anyway, it would be even easier.

Yes, in the xml header. The spaces are adding up for every run (I ran it multiple times just for testing).

Ok, so it is required for epub2, but not for epub3, right? I've seen Matt Garrish stating that it was not necessary for epub3:

Source


And just a suggestion: It would be nice to have summary of changes. There is no indication that the book was even modified, unless you look around.

I've tested it with and without fragment identifiers. None of them worked.

Thanks!

My titles are properly being filled in from the nav and from the ncx in my testcases.

So if it is not fragment identifiers being used in the ncx snd nav for top of file links, then there must be some other reason.

You you have left a single blank in the titles or have a return or other whitespace in it? That might happen if you use this form:

instead of

as the first technically has a whitespace text node child of the tag in the DOM while the second does not.

If that is not the case, then I am stumped.

Would you please copy your epub and strip it down to one or two chapters and run the Borkify Epub plugin and post it here so that I can figure out what is going on.

My local repo has the extra space in the xml header fixed as well as the stripping of region in the language code removed, so this is really the only issue remaining to track down.

Thanks,

Kevin

As for DOCTYPE in epub3.

The spec for html5 clearly states:

And the latest epub 3.2 spec states:

And a search reveals no other mention of doctype.

The epub 3.2 spec further states:

And in that deviations section there is no mention of doctype.

The only other part of the specs that mentions doctype is for pure xml (not xhtml) files do not need a doctype thus it is not used on the opf or other pure xml document.

The xhtml1.1 spec interestingly enough says a doctype is required. And all discussion on future epub specs talks about accepting pure html [whatwg standard or html5] as a content document format and that requires a doctype.

So since it is required based on the exact language of the spec according to my reading, is required in epub2, is required in html5 and required in the html whatwg living spec, and required for xhtml 1.1 and only not required for pure xml files like the opf, Sigil will enforce that.

It is not something we are going to change.