Page 1 of 1

Reviewing your First Ace Report

Posted: Thu Nov 29, 2018 1:51 pm
by Danny
Revised December 26, 2018
Greetings testers,

I chose the title for this post very carefully, because it's only meant for beginners, like myself, to Ace. I have only reviewed four reports, and the experienced Farrah would likely cringe at my humble attempts at breaking down this powerful tool. Nevertheless, I want to share with you what I've learned so far, partly so you can correct me where I've strayed from the path, and partly on the off chance that this may help someone else.

There are four tabs on an Html Ace report. You'll find these near the top of the document, below the book title and the date the report was generated. Each tab shows different information, and it's important to peruse each tab to get a full picture of the book's layout.

There are two headings under the Violations tab. If you jump down to the "All Violations" heading, you can use the boxes below it to filter the results.

Let's say the report you're reviewing has 36 color violations. Okay, we get it. The foreground and background colors are too close together. But once we've noted the colors need improvement, we can quote a single example and move on. You can do that by pulling down the Rule box, and moving to the next item in the list after Colors.

The next tab is Metadata. In an ePub, Metadata tags are what tell your player the full title, author, and publisher of the book you're reading. All that great stuff that's spoken when you press the "Where am I" key comes from Metadata. But Metadata is also used internally by your player to quickly identify accessibility features. When these tags aren't properly coded, your player may not be able to take advantage of the latest and greatest navigation and presentation features.

For those reasons, a quick check of the book's data is always a good idea. You'll find a complete list of these tags in the list headed by "All Metadata". Directly below, a heading of "Accessibility Metadata" gives a summary of what data was - or was not - included.

The next tab, Outlines, gives us a quick breakdown of the sections in the book, and how well laid out they are. If this section is empty, it is likely that your book contains no headings at all.

The "TOC Outline" heading spits out the table of contents imbedded in the ePub. This is the data your player will attempt to interpret when building its own list of navigation points. If this data is missing, out of order or improperly headed, internal navigation is likely to be impacted. Unless you're using Edge. Edge is a beast, it can detect coding so jumbled and mixed up it's hard for a human to follow it.

It is worth noting that Ace only extracts the TOC from version 3 ePub navigation files. Thus, there may be nothing wrong with your book's TOC, even though this section may be blank when reporting on an ePub2 title.

"Headings Outline" is the next heading you'll come across, and may well be the most useful bit of data in the whole report. This area lists all the headings in the book, from start to finish. Icons denote each heading level, captioned "Bullet" for a level 1 heading, "White bullet" for H2, and "Black square" for h3. This section is useful for finding gaps in the hierarchical structure, or pointing out headings that are purely decorative in nature (both Daisy errors).

"HTML Outline" is the last heading on the Outlines tab. This section follows the structure of each XHTML file in the book. Unfortunately, the report doesn't indicate the name or title of the XHTML document it's reporting on, so it can be difficult to follow. In addition, the text "Untitled Body" seems to indicate no headings in a given document.

The final tab is called simply Images. Yes, this does list all the images referenced in the text, complete with the Xhtml document where the reference came from. But it also attempts to list ARIA roles and figure captions, so you can get a really good idea of how much sense any given image is going to make.

Let's look through the columns in this last table really quickly.

Image: the name of the image. Nice to have if you're referencing it as an example of something done right ... or wrong. The graphic is also referenced in this column, so you can try running OCR on it to see if it contains text. Note that this column contains a graphical link to the image itself. There is only so much space for the filename in the table, but if you click on the image, it opens up in a separate window so you can copy the full filename. This window also works particularly well to OCR the given image.

alt attribute: the Alt parameter of the <Img tag, only used by adaptive technology. This should only be blank for a decorative image, otherwise it should contain a description of the visual content. It should not repeat any data in the figure caption, and ideally would contain more than the title of the image. There is debate on how long Alt tags should be, and concern that some devices cannot adiquately move through this text.

aria-describedbycontent: Not likely to come across in today's ePub books (thank you Ka Li!) This is used for associating different controls such as buttons, checkboxes, forms, etc with descriptions that provide greater detail as to what the control does.

Associated figcaption: the caption of the image, displayed to everyone. If this field is populated, it is (hopefully) a good bet that the image is correctly wrapped in a <Figure> container. Otherwise, assistive tech will not be able to skip figure captions, making it likely that they will break up the reading of the main narrative.

Location: the Xhtml file that references this image. Very helpful if you want to crack open the code and take a closer look.

Role: the Aria role referenced in this <Img tag. This is great to have, because if the Alt tag is empty but the Role is Decoration, we know it's a decorative image - and that the playback device should, too.

Okay, I made a few assumptions in the above. I hope I'm at least close on some of them, but please take this post with a grain of salt, everyone! I'd love to know what else you find - all replies here are welcome. Let's continue to all contribute as a team to give this guide more accuracy and heft.

Re: Reviewing your First Ace Report

Posted: Wed Dec 05, 2018 10:03 am
by Danny
*December 5 Discoveries

The newest version of NodeJs and Ace seem to have trouble generating reports for books that reference the same image repeatedly. After the book has been analysed and just before the report is generated, Ace errors out with Filecopy EBUSY: Resource busy or locked. The app then closes without producing a report. The workaround is to re-run Ace with exactly the same command, only add a -f switch to the list of arguments. This forces Ace to override files - giving it permission to keep replacing the image over and over.

I recently encountered an empty list of headings under the Outlines tab of an Ace report. When I looked into the book's coding, I was startled to discover the reason - the book had absolutely no headings. So, if you come upon an empty list, it means none of those elements were detected.

Re: Reviewing your First Ace Report

Posted: Wed Dec 05, 2018 4:26 pm
Hi Danny,
Thanks for the fix for the locked error. I had that happen with a few books.

My guess is that we'll probably not see aria-describedbycontent: used a lot currently since a lot of publishers have not fully embraced epub as it's own unique format that does not have to be confined to the limitations of a print book which is how most publishers still see epub; a digital replica of a print book. I think aria-describedbycontent is used for associating different controls such as buttons, checkboxes, forms, etc with descriptions that provide greater detail as to what the control does.