Sort definitions in SCSS files to make them pass validators

[LPT-BlubbY]

I came across asciidoctor-epub3 some time ago and use it for my own projects. Back then I already noticed that the CSS files placed into the resulting *.epub file were causing many warnings and errors in validators.

So, after using it for some years now, I finally got the time to fix all the issues. I verified my changes with the hardware I have at hand here (read: Calibre 7.6.0 and my dusty Kobo GloHD with firmware version 3.19.5761 from December 2015). Both readers don't show any differences in the tests I did, but I can't cover all devices out there, of course.

There have been no changes in the semantics, just changes in the order of the individual CSS definitions.

I would kindly ask to review my changes and get them integrated at some point, but I also noticed that the files follow a more visual approach in the order they define the individual styles: from top to bottom. Header and chapter definitions come first in the files, then the stuff which goes into the content area (tables, paragraphs, images, ...) and finally there are definitions for footers. So I would also understand if my changes are not considered an improvement and keeping the current order being favored.

[slonopotamus]

Hi, my main question here is: what validator you use (and how) and whether we can integrate it into asciidoctor-epub3 testsuite to make sure CSS stays valid in the future. We already use EPUBCheck, but it doesn't report any issues in current CSS.

[LPT-BlubbY]

Hi, thanks for the info and quick response.

I used the validator integrated into Calibre (its "eBook Editor"). From the menu it can run checks on the whole book and came up with a total of 70+ issues. It's interesting that EPUBCheck didn't report anything, although I have to admit that I didn't use that tool in the past.

Nevertheless, I just gave it a try, installed it and fired it against a book. My workflow for this test was this:

1. Extract the *.epub file on disk (having it built with the old asciidoctor CSS files, of course)
2. Edit the styles/epub3.css file
3. Compress everything to a ZIP archive again and renamed it to *.epub
4. Start EPUBCheck with parameter -w which should bring up warnings, errors and fatals

My first impressions are that this tool does many checks regarding the overall structure and the metadata inside, including the package OPF. So it straight pointed out that in my test workflow here I accidentally compressed the mimetype file as well which is a no-no for EPUB... So that was all reported well. However, for some reason it looks like it doesn't do a full compliance check on the CSS files.

I tried the following:

• I changed an arbitrary margin definitions in that epub3.css file from 10 pixels to a non-existing unit. In my case I called it "glue", so this particular part now read: margin-top: 100glue;. That unit doesn't exist in CSS, yet EPUBCheck didn't say anything about it, not even a warning.
• Next I tried to add a non-existing attribute into the CSS: Instead of margin-top, I wrote LeckoMio: 100glue;. Again, no word from EPUBCheck (although AFAIK there is no CSS keyword which starts with an uppercase letter)
• Finally, I broke CSS by adding the same keyword without a unit and without the colon, so it just read: LeckoMio;. Interestingly, this time EPUBCheck responded with a fail.

Worth noting that all 3 cases were detected fine by Calibre's eBook Editor and produced red error messages there.

Maybe you can give that a try on your end as well to see if you can reproduce my results? I used EPUBCheck version 4.2.6, but maybe I missed some parameters.

My command line is: epubcheck -w /path/to/the/file.epub

[slonopotamus]

I used the validator integrated into Calibre (its "eBook Editor"). From the menu it can run checks on the whole book and came up with a total of 70+ issues.

Ah, that's the bit I was missing, thanks.

WRT EPUBCheck: asciidoctor-epub3 has builtin support for that. You install epubcheck-ruby gem, make sure java is available on PATH and simply pass -a ebook-validate argument to asciidoctor-epub3. It is true that EPUBCheck does not have a strong CSS validation.

[LPT-BlubbY]

Talking about automation for testing:
I just did a search on this matter, but it looks like the Calibre editor has no option to perform these checks from command line. Also, I guess, it would require some UI in order to start. So that's not an option. However, maybe the foundation of the Calibre applications is something which could be integrated into asciidoctor-epub3 as well (like some sort of CSS LINT library).