Feature request: Plain text console output

[acabal]

Please provide the following details if possible or relevant:

• [] the version of Ace impacted by the issue (as returned by the ace -v command). 1.0.0

Feature request: I'd like to add Ace checking to our build process at Standard Ebooks, to alert producers to accessibility issues in their productions before they submit them for review. Our build process runs on the command line, and can be instructed to run epubcheck after building to ensure the final epub is valid. It would be very helpful to be able to add ace to that step, but right now the console output of ace is verbose by default (a lot of info notices even when everything is OK) and the JSON output is tough for humans to read.

I'd like to suggest that ace be silent by default (the rule of silence), and instead of outputting JSON to the console, output a list of plain text errors/warnings a la epubcheck. Info notices and debug info could still be an option with --verbose, and JSON output could still be an option with a flag too. Then we could very easily integrate it into our build process, since the ace tool would then better follow the rules of Unix.

(It may also be worth it to consider mirroring epubcheck's output style as closely as possible, since conceivably both ace and epubcheck could be used simultaneously by ebook developers, and having the output in similar styles would go a long way towards ease-of-understanding.)

Thanks for all your hard work!

[rdeltour]

Thanks for the feedback! 😄

You can make Ace silent with the --silent option. I believe that having Ace output the various processing stages by default is helpful, especially for people who may not be very comfortable with the command line. That said, we may envision short-lived status messages.

As for outputting more human-friendly messages, yes that’s something we would like to do in a future version. Making that the default option, and JSON optional, would certainly make sense!

[acabal]

I would argue that it makes more sense to have either a --silent option, or a --verbose option, but not really both. Having not-quite-verbosity but not-quite-silence by default means that scripting gets harder, and yet not enough detail is given to obviate the need for --verbose when something unexpected happens during a human run. (And as mentioned earlier, defaulting to silence on success is more "Unix-y".)

[rdeltour]

A lot of CLI tools offer both a "quiet" and "verbose" mode, and I think a reasonable amount of feedback, especially for a process that may be long-running, is a fair compromise for user-friendliness.

Also, the "rule of silence" is far from being followed consistently and unanimously (outside the Unix community at least). Being "unix-y" isn’t a strong goal for Ace.

I’m not saying we’re rejecting the idea, just that we need to ponder what’s best for Ace’s target audience 😉

Btw, If an error happens unexpectedly, it will be logged in any case. The verbose mode provides more info that is mostly useful for debugging purpose.

[acabal]

Also, the "rule of silence" is far from being followed consistently and unanimously

Indeed, and if I could, I'd open Github issues for those CLI tools too, because they're also a pain to use and script. Git itself is an egregious, inexcusable offender... but just cuz some other popular tools do it, doesn't mean we can't seize the chance to have our own CLIs set a better example :)

especially for a process that may be long-running

Actually Ace is pretty fast! If I run it on our longest ebook, Chekhov's Short Fiction (2.3MB and over 800,000 words) it only takes 21 seconds. Likewise Don Quixote takes 18 seconds and it clocks in at ~425,000 words including 982 endnotes. Nice work :)

[danielweck]

Hello @acabal , we've "met" remotely before, in the context of Readium and https://standardebooks.org . I am an Ace developer / contributor as well, and I am particularly interested in making sure that the "engine" used to run the accessibility checks in the Ace App (ace-gui project) delivers comparable performance to the default "engine" used in the Ace CLI. By "engine" I mean the Chromium framework that actually loads HTML documents from EPUB publications, in order to launch the Axe tests (etc.). There is a default Puppeteer-based "Axe runner", and an Electron-based one (used in the Ace App).

So, more to the point - I checked the EPUBs you linked to in the comment above, and here are my results:

./compareAxeRunners.sh miguel-de-cervantes-saavedra_don-quixote.epub3 =>

PuppeteerAxeRunner ...
>>> ACE PERF: 19 seconds + 429164260 nanoseconds
ElectronAxeRunner ...
>>> ACE PERF: 19 seconds + 543085130 nanoseconds

./compareAxeRunners.sh anton-chekhov_short-fiction.epub3 =>

PuppeteerAxeRunner ...
>>> ACE PERF: 18 seconds + 934438775 nanoseconds
ElectronAxeRunner ...
>>> ACE PERF: 19 seconds + 309668557 nanoseconds

I am quite happy with that :)