report epub validations errors to users
Context
ePubs are validated against https://github.com/w3c/epubcheck but when there are errors, the message that users see doesn't help them fix the errors in their book. Currently users see a modal with:
Error: Something went wrong while creating your file!"
For example, if a link in the content is invalid, users will get this message.
Proposal
- Validate URLs when they are added in Wax -- wax/wax-prosemirror#106 (this solves this error example only)
- Expose errors reported by
epubcheck
(These may need to be made user user-friendly) - Point users to where the issue is in their content so they can fix it.
Example epub errors from terminal
server_1 | ########## WS HEARTBEAT END ##########
epubchecker_1 | info: sending back the report
epubchecker_1 | info: cleaning up temp path /home/node/epub-checker/temp/d549880df1c0.epub
epubchecker_1 | info: ::ffff:172.31.0.14 - - [19/Dec/2023:13:39:25 +0000] "POST /api/epubchecker/link HTTP/1.1" 200 380 "-" "axios/1.6.2"
epubchecker_1 |
server_1 | Error: Referenced resource "OEBPS/Text/coko.foundation" could not be found in the EPUB. - {
server_1 | error: [GraphQLError: Error: Referenced resource "OEBPS/Text/coko.foundation" could not be found in the EPUB. - ] {
server_1 | locations: [ [Object] ],
server_1 | path: [ 'exportBook' ],
server_1 | extensions: { code: 'INTERNAL_SERVER_ERROR', exception: [Object] }
server_1 | }
server_1 | }
server_1 | ::ffff:172.31.0.1 - - [19/Dec/2023:13:39:25 +0000] "POST /graphql HTTP/1.1" 200 200 "http://localhost:4000/" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/119.0"
Or you can try importing this file Creative_commons.docx. This file has a lot of broken links because I converted it PDF to .docx. The error in the terminal in this case is as below:
epubchecker_1 | info: sending back the report
epubchecker_1 | info: cleaning up temp path /home/node/epub-checker/temp/d10eddf0370d.epub
epubchecker_1 | info: ::ffff:172.31.0.14 - - [19/Dec/2023:13:42:30 +0000] "POST /api/epubchecker/link HTTP/1.1" 200 2926 "-" "axios/1.6.2"
epubchecker_1 |
server_1 | Error: "http://.coursera.org/learn/copyright-for-education" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.eff.org/files/filenode/three-step_test_fnl.pdf" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.legalaffairs.org/issues/March-April-2004/story_lessig_marapr04.msp" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.wikimedia.org/wiki/File:Berne_Convention.png" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.wikimedia.org/wiki/File:World_copyright_terms.svg" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.youtube.com/watch?v=NUGP-oW4_ZE" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http:////www.youtube.com/" is not a valid URL (Unexpected slash or backslash) - {
server_1 | error: [GraphQLError: Error: "http://.coursera.org/learn/copyright-for-education" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.eff.org/files/filenode/three-step_test_fnl.pdf" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.legalaffairs.org/issues/March-April-2004/story_lessig_marapr04.msp" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.wikimedia.org/wiki/File:Berne_Convention.png" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.wikimedia.org/wiki/File:World_copyright_terms.svg" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http://.youtube.com/watch?v=NUGP-oW4_ZE" is not a valid URL (Invalid host: A non-final domain name label (or the whole domain name) is empty.) - "http:////www.youtube.com/" is not a valid URL (Unexpected slash or backslash) - ] {
server_1 | locations: [ [Object] ],
server_1 | path: [ 'exportBook' ],
server_1 | extensions: { code: 'INTERNAL_SERVER_ERROR', exception: [Object] }
server_1 | }
server_1 | }
server_1 | ::ffff:172.31.0.1 - - [19/Dec/2023:13:42:30 +0000] "POST /graphql HTTP/1.1" 200 1178 "http://localhost:4000/" "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/119.0"
Design
An error modal with the following:
[Title] File not created
The ePub file couldn't be created because there are errors. These are likely due to issues in the content of your book. To resolve these errors, refer to the information below, go back to your book to fix them, and then download the ePub again.
{include list of errors}
If you still can't download the ePub, please contact your admin.
Implementation (if applicable)
- Check here where the outcome of the
epubchecker
call is handled. - On the client side (ketty), a new modal should be designed and implemented, which will be capable of displaying all the issues returned from the call to the
epubchecker
microservice. - The source code of the microservice which is responsible for the validity check is here and that microservice is using this under its hood.