Getting Started with 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 guide is intended to help new users get started with Ace. We highly recommend working through this document to get started. Additional documentation for advanced users can be found on the Ace support website.
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.
- The HTML report
- Video Guide to Getting Started
Note: internet connectivity is required for both installation steps
- Go to Node.JS
- Download version 6.4.0 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.
Additional Troubleshooting Steps for Mac Users
Some Mac users may need to take the following additional steps if they encounter errors in the above installation steps:
1. Make a directory for global installations:
$ mkdir ~/.npm-global
2. Configure npm to use the new directory path:
$ npm config set prefix '~/.npm-global'
3a.) If you don’t already have one, Create and Open a ~/.profile file:
$ touch ~/.profile $ open -e !$
3b.) Or, if you already have a .profile, Open it:
$ Open -e ~/.profile
4. Add the following line, save and close the file:
5. On the command line, update the system variables for the file you just created:
$ source ~/.profile
6. Launch Ace:
$ npm install -g @daisy/ace
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
The HTML report
report.html in your web browser to see the results. The report contains several sections:
- Violations: Table of the automated tests that have failed, with suggestions for remedying the problems and links to the relevant section of the Accessible Publishing Knowledge Base
- Metadata: Table of all the publication’s metadata from its Package Document, and special mention of present or absent accessibility metadata
- Outlines: Extracted views of different aspects of the publication’s structure, presented side-by-side for quick comparison.
- Images: Table of all the images in the publication and the accessible properties for each (e.g.
Go to Ace’s documentation for more details about the reports produced by Ace.
Video Guide to Getting Started
What to do if something goes wrong:
You are also welcome to contact us.