Getting Started with Ace Core

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.

Note that this page refers to our command line tool, we also have an Ace by DAISY App which is a much more user friendly desktop version.

This guide is intended to help new users get started with Ace the command line tool. We highly recommend working through this document to get started. Additional documentation for advanced users can be found on the Ace support website.

Basics

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 Prompt or Start->Run->cmd.exe
  • On Mac: Applications->Utilities->Terminal

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, /Users/username/Documents/my-book.epub)
  • On Windows: c:\Users\username\Documents\my-book.epub.

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.

Getting started

Installation

Note: internet connectivity is required for both installation steps

Install Node.JS

Ace relies on an open source Javascript framework called Node, which is freely available to download. You must install Node first before installing Ace. Node installation requires administrator privileges.

  • 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
  • Type $ npm install -g @daisy/ace to 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:

export PATH=~/.npm-global/bin:$PATH

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

Usage

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 ~/Documents/moby-dick-report directory:

  • 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

Open 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. alt, aria-describedby)

Go to Ace’s documentation for more details about the reports produced by Ace.

Video Guide to Getting Started

Feedback

What to do if something goes wrong:

Check the troubleshooting page to see if your problem is described there; if not, please submit an issue on Github.

You are also welcome to contact us.