[Plugin] Access-Aide - help improve epub accessibility

[KevinH]

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

[KevinH]

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

[thiago.eec]

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'.

[KevinH]

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!

Originally Posted by thiago.eec

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'.

[KevinH]

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

[KevinH]

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.

[thiago.eec]

Originally Posted by KevinH

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?

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

Originally Posted by KevinH

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.

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

Originally Posted by KevinH

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.

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:

EPUB 3 uses XHTML5 for content documents, so a doctype isn't required. Adding the HTML5 doctype isn't harmful, either.

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.

[thiago.eec]

Originally Posted by KevinH

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

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

Originally Posted by KevinH

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.

Thanks!

[KevinH]

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:

<title>
</title>

instead of

<title></title>

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

Originally Posted by thiago.eec

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



Thanks!

[KevinH]

As for DOCTYPE in epub3.

The spec for html5 clearly states:

Definition and Usage
All HTML documents must start with a <!DOCTYPE> declaration.

The declaration is not an HTML tag. It is an "information" to the browser about what document type to expect.

In HTML 5, the declaration is simple:

<!DOCTYPE html>

And the latest epub 3.2 spec states:

The XHTML profile defined by this specification inherits all definitions of semantics, structure and processing behaviors from [HTML] unless otherwise specified.

And a search reveals no other mention of doctype.

The epub 3.2 spec further states:

For all document constructs used that are defined by [HTML], it MUST conform to the conformance criteria defined for those constructs in that specification, unless explicitly overridden in HTML Deviations and Constraints.

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.

[KevinH]

Just in case there is something confusing the simple quickparser that is built-in, try running Mend on all your xhtml first so that both the doctype and any other issues are cleaned up by gumbo before trying the plugin.

Also to see any changes due to any tool or plugin, just use Sigil's Checkpoint tool first and then generate a diff against it using the Checkpoint comparison.

[KevinH]

Ah! I bet your title tags are self-closed? This can freak out some browsers that try to interpret that page as html and not xhtml. As a result, Sigil's gumbo parser will always serialize that to an open and close pair to make it valid in both html and xhtml.

The simple quickparser the plugin uses can handle those just fine but since Mend normally serializes them away, I never updated the Access-Aide to look for that case.

If that is the case, as a workaround, running Mend in Sigil before launching Access_Aide should prevent that issue.

Long term I have added code to Access-Aide to my local repo to now look for and handle self-closing title tags appropriately.

I have also added code to strip whitespace from any existing title text to determine if something is there or not (to have it ignore whitespace alone in a title tag).

As for force replacing, I will think about that but I am really not sure that it is a good idea to strip titles without review. So if you want that feature use Sigil find and replace to remove any existing titles you do not want before running Access-Aide.

If none of the possibilities I have mentioned are the culprit, then I really need a test case to see what is going on.

[thiago.eec]

Ok, I rest my case on the DOCTYPE thing. It was just a silly doubt, anyway.

Thanks for taking the time to look into this, and for the quick fix.

About the title tag:
- Not using self-closed tags
- There is no space or line break. Just like this: <title></title>

Attached is a scrambled version of a test case book. But I must say this didn't work with any of the books I tested. I even mended html files, before running the plugin (so, the DOCTYPE wouldn't be a problem).

My system:
Windows 10 x64. Sigil 1.4.3. Acces-aide 0.5.1.

[KevinH]

Okay, just tried your test case and Access-Aide properly filled in the empty title in each xhtml document.

So what version of Sigil are you using? What version of Access-Aide, I ran my tests both with current master and Sigil-1.43 release using both Access-Aide 0.5.1 and Access-Ade from my local repo.

[KevinH]

Just tried and it worked with Sigil-1.3.0 as well.

Could you by chance have a too old version of Access-Aide?

Originally Posted by KevinH

Okay, just tried your test case and Access-Aide properly filled in the empty title in each xhtml document.

So what version of Sigil are you using? What version of Access-Aide, I ran my tests both with current master and Sigil-1.43 release using both Access-Aide 0.5.1 and Access-Ade from my local repo.