Getting Started Beta Testing Ace, by DAISY
Ace, the Accessibility Checker for EPUB, is a tool developed by the DAISY Consortium to assist with the evaluation of the accessibility of EPUB publications. Its automated accessibility checks assist in the evaluation of conformance to the EPUB Accessibility specification.
It is important to keep in mind that a limited portion of accessibility checks can be automated. Therefore, Ace is not a complete accessibility conformance evaluation tool; instead, it is an aid for a broader, human driven evaluation process.
This document is intended to help new users get started with Ace.
Important note about Beta testing
This tool is remains in development and is not currently ready for everyone to use. We are actively seeking technical experts from the publishing industry to assist by offering feedback on this beta release, to refine the Ace tool ready for a mainstream release later this year. If you are not a technical publishing expert, please join the Inclusive Publishing Newsletter for news about subsequent releases and other industry news.
Ace is a command line tool, which means that you’ll run it by typing commands into a terminal window (also called a “shell” or “command prompt”). Here’s how to open a terminal window:
- On Windows:
Windows System->Command Promptor
- On Mac:
Depending on which style of terminal window you use, the actual prompt might look like a dollar sign (
$) or a greater-than sign (
>), perhaps preceded by something (e.g.
c:\>). The convention used here is
$ followed by what you should type (i.e. you don’t type the dollar sign, that’s just to indicate that we’re using the command prompt).
Another thing you should understand before using Ace is how to type the path to a file. E.g. if I have a file named
my-book.epub in my
Documents directory, its path would be:
- On Mac:
~/Documents/my-book.epub(or, in expanded form,
- On Windows:
You may use relative or absolute paths.
Ace will require that you enter the path to your EPUB file and also the path where you would like Ace’s report stored.
We highly recommend working through this document to get started, but additional documentation for advanced users can be found on the Ace Github pages.
- The report
Note: internet connectivity is required for both installation steps
- Go to Node.JS
- Download version 6 or higher
- Double-click to install and follow the instructions.
Install or update Ace
- After installing Node, open a terminal window
$ npm install -g @daisy/aceto install Ace, or update to the latest version
If everything went smoothly, you should now be able to run the
ace command in your terminal window. Try typing
$ ace --help
Ace should display usage information and then exit.
Checking an EPUB
You can check an EPUB by running the
ace command followed by the path to the EPUB document. For example:
$ ace ~/Documents/moby-dick.epub
The above command will run the automated accessibility tests on the EPUB document and output the results in the terminal window.
Storing the results
You can specify the directory for Ace to store its output with the
--outdir option. For example:
$ ace --outdir ~/Documents/moby-dick-report ~/Documents/moby-dick.epub
Note that if you do not specify a directory with
--outdir, no reports get saved. You would only see output in the terminal window.
If the specified directory does not exist, it will be created. In this example, two versions of the results report will be found under the
report.html: A human-readable version of the report, in HTML format.
report.json: A machine-readable version of the report, in JSON format
report.html in your web browser to see the results. The report contains several sections, described below.
The report contains a table listing the violations found in the EPUB. The table columns are:
Impact: the severity of the violation
Rule: identifier for the rule that was violated
Location: where in the book the violation occurred
Details: suggestions on how to fix the problem, as well as a link to the relevant topic page in our online knowledge base.
There is a set of drop-down filters at the top of the table where you can refine by Impact, File, and Rule.
The outlines are intended to assist with manual checking. They represent extracted views of different aspects of the EPUB. The outlines are:
- Table of contents, taken from the EPUB navigation document
- Headings, including indications of missing heading levels (i.e. going from
- HTML, which represents heading content and sectioning content
Accessibility metadata summary
This section lists both present accessibility metadata, summarized in a table, as well as a list of what’s missing or empty.
This table contains each image in the EPUB and information about it. The table columns are:
Image: the image itself
alt attribute: the contents of the
aria-describedby: the contents of the element referenced by the
Associated figcaption: the
figcaptionfor this image
Location: location in the EPUB of this image
What to do if something goes wrong:
In the first instance check the Ace issue tracker on Github to see if you have encountered a known issue which we’re working on. If the issue is not currently documented please raise it as a new issue on Github.
We also welcome your broader comments about the tool at any time during the beta testing process. Please use the Ace feedback form.
Additional documentation can be found on the Ace Github pages.