friendsofepub / blitz Goto Github PK

I don't like much the way asterisms are displayed in night mode (with a white border). I'd rather have them take the text color through a property like stroke: currentColor. I was able to achieve that by inlining (a simplified version of) your asterism.svg, but I am not sure how well that is supported by ereaders (I have limited testing possibilities). Any recommendations about that? Are there any other ways to achieve what I am asking for? For instance, how about using a simple <p>* * *</p> and hiding/removing <hr/>?

KF8 doesn’t support position: relative, which we use for hr.asterism: after. As a result, we’ve got extra margin-bottom on Kindle. position: absolute is supported but not on every Kindle device.

Tried to implement progressive enhancements (branch https://github.com/FriendsOfEpub/Blitz/tree/progressive-enhancements) and to my surprise, it seems LESS’ support for feature queries (@supports) is a little bit “raw around the edges.”

To sum up:

1. bubbling works OK but for some reason LESS won’t compile strings for @supports: unlike @media (cf. http://lesscss.org/3.x/#escaping), you get the variable name (cf. https://github.com/FriendsOfEpub/Blitz/blob/progressive-enhancements/Blitz_framework/LESS/core/features.less) in the output CSS…
2. as a result, feature queries have been tightly coupled to mixins (cf. https://github.com/FriendsOfEpub/Blitz/blob/progressive-enhancements/Blitz_framework/LESS/reference/mixins.less#L75), which may sound like a good idea at first since “hey, you don’t even have to manage feature queries, it’s automagic!”…
3. except in real case scenarios, it means you can’t override values if you need to, like say margins if you’re using flexbox to align vertically and shit—was screwed like 2 minutes after starting a template to check the DX.
4. @supports all over the place, obviously, since one mixin = one feature query so you can’t gather declarations which could be gathered within the same feature query.
5. when using arguments in the nested feature query (mixin), you get an error.
   ¯\(ツ)/¯

And man, some feature queries are just plain fucking awful—OTF, I'm looking at you. I have spent like 2 hours designing them, it’s not humanly possible to type them by hand every time you need them.

Of course there is like nothing about that. Checked and only found @supports bubbling is supposed to work since 2.5…

Any idea how to get around this temporarily?

I found out a problem in ADE with the code for portrait image styling when using ePub3 instead of ePub2. From what I understood, softwares either use vh or %. ADE with ePub2 uses % but vh with ePub3, but it doesn’t support @supports....! So this results in images not being displayed correctly in ADE when using ePub3. The solution is to use vh straight away, without apply it through @supports, but then it won’t be displayed correctly in the softwares not supporting vh.

The ADE display problem is something that can’t be ignored for my company, so I did a LOT of tests and came up with a code that seems to perfectly solve the problem, AND also makes us able to make an image full page, ratio preserved, beautifully centered in the page. I tested my code on ADE on Windows 10, iBooks on iPad, and on Android, Bluefire, Google Books and Gitden Reader.

I would love if you guys can test it and see if really it is as good as I’m thinking, and if so, for it to be implemented in the Blitz framework maybe?

Full page images (the height="98%" is for Bluefire, else it creates a blank page before the image):

  <div>
    <svg style="height: 100vh; width: 100vh" xmlns="http://www.w3.org/2000/svg" height="98%" preserveAspectRatio="xMidYMid meet" version="1.1" width="100%" xmlns:xlink="http://www.w3.org/1999/xlink"><image height="100%" width="100%" xlink:href="../Images/C1.jpg"/></svg>
  </div>

Image with caption:

  <div>
    <svg style="height: 70vh; width: 100vh" xmlns="http://www.w3.org/2000/svg" height="70%" preserveAspectRatio="xMidYMid meet" version="1.1" width="100%" xmlns:xlink="http://www.w3.org/1999/xlink"><image height="100%" width="100%" xlink:href="../Images/C1.jpg"/></svg>
  </div>

The CSS framework can probably be distributed on npm – the template should I guess be ignored?

That should ease the compilation for people using node as well.

Maybe I’ll take this opportunity to build proper tests as well (the debug file is lacking) but no guarantee.

It is a typographic tradition from print books that there should be no paragraph ident after a section heading or content break. This looks attractive and is just as meaningful in ebooks. I propose it be added (at least as an option) to Blitz (and, perhaps, be added to ebook tricks). The basic CSS is as follows:

h1 + p,
h2 + p,
h3 + p,
h4 + p,
h5 + p,
h6 + p,
hr + p {
    text-indent: 0;
}

I'm not sure how to handle cases where there is content between a <h1> and first <p> tag, such as an epigram.

Amazon has chosen to rasterize SVG for KFX, which impacts the background-image for hr.asterism.

Quality is not great at larger font-sizes, which defeats the purpose of using SVG. In addition, the background-color is slightly off.

Must do some checks first but enlarging the viewport in the SVG file may solve this issue… (see related script)

So I definitely claim responsibility for this mishap/screwup, although it shouldn’t have consequences in production.

Issue is I’ve never found this outdated CSS Text Level 3 spec before, which makes it clear hyphenate-limit-before and hyphenate-limit-after are for the minimum amount of characters in a hyphenated word before the hyphenation character.

I assumed that because the properties’ name was so close to hyphenate-limit-lines, it was meant for the minimum number of successive non-hyphenated lines before hyphenation can happen.

Fix: hyphenate-limit-before and hyphenate-limit-after should be remapped to hyphenate-limit-chars (cf. CSS Text Module Level 4) and the -webkit- ones should be moved to division (chars).

Impact: Low. We’re only applying the -webkit- prefixed one, the hyphens-division mixin takes care of the new syntax. The defaults are kinda wrong though.

This is quite some important part that is still missing in the framework so I just init’d i18n, starting from what has been done in ReadiumCSS in this branch: https://github.com/FriendsOfEpub/Blitz/blob/i18n/Blitz_framework/LESS/reference/i18n.less

That said, I’m way out of my comfort zone in the sense ReadiumCSS is relying on platform fonts while eReaders may not have some of those for instance, etc. And I’m probably not aware of typography and layout practices in some languages.

So any help will be appreciated.

Summary

Progressive enhancements have been implemented in branch progressive-enhancements.

It’s important we get this right since we’re building the foundation of Blitz Next (cf. #10).

This move is bold since they’ve been implemented in the core of the LESS framework:

1. features.less has been implemented in core (feature queries in the form of rulesets passed in a mixin);
2. enhancements.less has been implemented in reference (more about that later);
3. mixins have been added to mixins.less;
4. some styles are now using enhancements (which are definitely EPUB 3 utilities).

⚠️ ⚠️⚠️

However, I will release all of this as a plugin first so that it doesn’t disrupt usage and you can get familiar with it.

⚠️⚠️⚠️

The core implementation shouldn't disrupt usage (double-checked) but it makes a huge change, especially as feature queries are a must, which is why enhancements.less has been implemented in reference and not utils so that it doesn’t get output by default.

Details

Feature queries (features.less)

You’re likely to encounter a steep learning curve if you're not familiar with passing rulesets in a mixin because that’s definitely a new layer of abstraction I could not bypass—due to preprocessors’ limitations regarding @supports.

Syntax is the same as the query:

• @supports feature becomes .supports-feature;
• @supports not feature becomes .supports-not-feature.

To sum up, this is how you use them

.small-caps {
  /* solid styles for less-capable Reading Systems */

  .supports-true-sc({
    .true-sc;
  });
}

or, if you want to gather several declarations in the same feature query…

.supports-true-sc({
  h1, h2, h3,
  .small-caps {
    .true-sc;
  }
});

Yeah, I know, this is a PITA (cf. #11).

What differentiates those mixins from others is the javascriptesque ({ … }) only. It’s really hard to tell the difference at first sight.

Now, enhancements absolutely need this or else you’ll have issues all over the place in Reading Systems using Adobe’s ePub2 RMSDK.

Mixins (mixins.less from line 75)

There’s a bunch of new mixins you might want to use for initial-letter, reflowable images with a caption, etc.

To make things clearer, defaults have been set for some arguments—and yep, you do have to pass some arguments as strings so I’m not sure at all it’s worth it.

EPUB 3 Utilities (enhancements.less)

They’ve been designed as a reference so that they are not output in the CSS. The assumption is that if they were output by default, people could maybe use them without feature queries (@supports).

You’ve got mixins for flexbox, vertical-align—which relies on flexbox—, objects sizing and open type features.

Mixins’ names match features’ names whenever possible.

Usage

Get used to this syntax although it’s a pita…

h1 {
  .align-left;
  .italic;

  .supports-ss01({
    .override-italic;
    .ss01;
  });
}

The feature query will bubble up even if it’s nested so no worries.

You can also use several queries, like

h1 {
  .align-left;
  .italic;

  .supports-not-ss01({
    .override-italic;
    font-family: "embedded alternative font", serif;
  });

  .supports-SS01({
    .override-italic;
    .ss01;
  });
}

Both queries will bubble up as expected.

Let’s take a more complex example.

/*section*/
.copyrights {
  margin-top: 20%;
}

.copyrights p {
  .fs-xs;
  .align-center;
}

.supports-flex({
  .copyrights {
    margin: 0;
    .valign-bottom;
  }

  .copyrights p {
    .align-left;
    .no-break-inside;
  }
});

If you want to gather declarations in the same feature query, especially as performance may suffer if there are too many feature queries in your CSS, then you have to nest declarations in the mixin.

Roadmap

1. Master branch gets the plugin
2. I won’t push a release so fork the repo if you want to review the plugin
3. We’ll be collecting early feedback via this issue/mail + I’ll be reviewing this myself since templates are next on the todo list
4. Once we’re confident this is the best way to implement progressive enhancements, it will be re-implemented in the core of the LESS framework with a new release (version 1.2).

I’m expecting this process to take more or less one month and a half—a month if there’s no feedback, possibly two months otherwise.

Hi - would you add a license to Blitz (gpl, mit, unlicense, apache, etc)?

Thanks for your awesome work!

We should provide users with presets e.g. “novel”, “essay”, “report”, “cookbook”, etc. in addition to the customizable blitz.less. It would probably help people who’d like to use the framework but feel uncomfortable customizing it.

Moreover, we could provide preset stylesheets – instead of a default in which you must get rid of things you don’t use – for people not willing to use a preprocessor at all.

The style

nav[epub|type~="toc"] ol {
  list-style: none !important;
}

is not enough to suppress the number of the list at kindle and Calibre viewer. (see screenshots)

Calibre Viewer

Kindle Previewer

I have to give the ol element a class that numbers are suppressed at kindle

<ol class="toc-list">

For calibre viewer is an extra rule with the id of the nav element enough.

The additional css rule to blitz is in my stylesheet now:

nav#id ol, ol.toc-list{
  list-style: none !important;
}

The rule

nav[epub|type~="landmarks"],
nav[epub|type~="page-list"] {
  display: none;
}

is not enough to hide the landmarks (i think it's with page-list the same but i have no) at kindle (see screenshot)

I have to add the following rule

nav#landmarks {
  display: none;
}

I noticed

This reset seems unexpected to me. Is there a technical reason for this?

Not looking forward to this one tbh.

Related component: https://github.com/FriendsOfEpub/Blitz/blob/8eeb854b0efe6248b3b7578d9094d9ea622a7297/Blitz_framework/LESS/utils/break.less

So we have at least 5 levels of fuckedness here:

1. page-break-* support is kind of a cheat code for iBooks and iOS apps using the pagination API and most other apps actually require column breaks;
2. so already there is the issue of using -webkit-column-break-* for those apps, as it broke page-break-* at one point in some apps – I can’t remember which ones, but can recall spending quite a few hours on that bug;
3. then page-break-* is superseded by break-*, with aliasing to page for after and before;
4. so break-*: always will save the day? LOLOLOLOLOL nope because nobody supports always in columns;
5. you must therefore use break-*: column for columned-pagination but we’re back to 2.

Kill me with the fury of a thousands CSS implementations.

We need docs. Pretty badly.

Should be ready @ v1.

Please tag the latest release.

According to the project page, 1.4.1 is the latest release, but there's no tag for 1.4.1-- the latest tag is 1.4.0.

1.4.1

Fixed padding-left for lists (switched to relative ems) so that markers can’t be cropped

cf. https://github.com/jakubpawlowicz/clean-css-cli#optimization-levels

Those could probably be fine-tuned via npm scripts.

It would probably be a good idea to refactor those scripts too given the length of the argument expected. Or switch to clean-css + node scripts if the config becomes way too complex…

Nook is not specifically supported at the moment but it’s a “popular” platform in North America.

Unfortunately, we don’t have easy access to Nook in Europe so inputs from north american eBook producers is a must.

[edit] won't cripple the framework to get around their “yolo overrides” though.

My understanding is that webkit automatically maps lang and xml:lang attributes to the -webkit-locale CSS property → https://bugs.webkit.org/show_bug.cgi?id=67586">bug

It seems it is not directly related to hyphens but the font fallback and the text-transform property.

It could still be useful for spans of text in another language, especially if no xml:lang is provided in the xhtml but it should, in any case, be removed from hyphens and put into overrides (like -webkit-text-fill-color).

Just to file this here properly. I recently ran into cases where Kindle Previewer as well as sideloaded mobi on Kindle Android was having issues displaying figures. Some images inside figures would not be displayed and some figcaption elements would become "blank", i.e., text became invisible but dictionary lookups would still work.

Since this appeared to happen only near pagination breaks I tried resetting

to auto which seems to have resolved the problem.

I plan to add aria roles at some point, in addition to epub:types.

That shouldn’t be too much work at first sight.

Should be fine in RMSDK as long as the MQ is not empty, and there’s so little to Kindle that it wouldn’t add that much to the base anyway.

Re https://github.com/FriendsOfEpub/Blitz/blob/master/Blitz_framework/LESS/plugins/blitz-kindle.less

TL;DR: dev tools are lacking, debugging CSS and JS is a nightmare, we could provide blitz’ users with barebones tools in JS.

It’s possible (and actually quite easy) to plug the console, which is already there, into the DOM via JavaScript so, we basically can implement lightweight dev tools inside the EPUB file with a tiny script.

In other words, console.log() can be written in the EPUB file. By extension, it’s also possible to get computed styles, print the DOM and shit.

It has little impact on performance and would be designed as a plugin (reflowable/fixed-layout, parameters, API, etc.).

Also, we could theoretically save logs for later retrieving using localStorage and, why not, export them (mail?).

What we could provide (functions/API):

• DOM tree;
• RS default styles;
• element’s styles;
• transparent access to console which works with console.log, etc. (JS debugging);
• real viewport;
• offset and shit.

Another lead is https://kenneth.io/blog/2014/12/28/taking-chrome-devtools-outside-the-browser/ but I believe those two things are not exclusive: on the one hand, we could provide lightweight tools (JS) and, on the other hand, more powerful tools (chrome) if needed.

I was recently in a situation where I had to add .normal to a <blockquote> which led me to add a "inverted" copy of

when using .normal or .italics.

I was wondering if you're interested in that or if it's too much of an edgecase.

I’ve been very uncomfortable having this plugin since the very beginning because it’s unreliable AF in the ebook context, and it’s not output in CSS anyway – it’s just sitting there, with very few practical uses – only mobi7 and kf8 are in use.

Re https://github.com/FriendsOfEpub/Blitz/blob/master/Blitz_framework/LESS/plugins/blitz-mq.less

Here's the CSS for <td>

td {
  empty-cells: show;
  border-bottom: ((@border-width / @body-font-size) + 0em) @border-style @border-color; /* Current color = color of text (inverted in night mode) */
  @computed-padding: (((@body-font-size * @body-line-height) - (@border-width * 2)) / @body-font-size);
  padding: (@base-margin / 2) 10px ((@computed-padding / 2) + 0em) 0;
  text-align: left;
}

Most of it is computed, but the padding-right value is fixed at 10px. Why is this?

For example, take a look at this screenshot from Kindle Previewer of a two-column table. It's extremely cramped, and it's hard to tell where one column begins and another column ends.

It looks like Kindle Previewer 3 sometimes fails to convert EPUB using Blitz’ CSS to Kindle Format X, and will fallback to KF8.

It’s really difficult to find why at first sight though, as the debug file is OK (but not necessarily exposing all styles to the KP3 script parsing the DOM).

As one of the core (and the main) maintainer of Blitz, I’ve decided to let it go after an umpteenth event in the ebook community tonight, and sunset every project in the FriendsOfEpub workspace (the Blitz framework, the companion apps, Blitz Tasks, Blitz Checklist, etc.).

This decision is irrevocable – and tbh, long overdue.

I still have to lay out a plan accommodating current users, because I want to make sure those repos don’t disappear overnight. But this effectively means that all active developments are stopped tonight, current issues won’t be fixed, and all projects will eventually be archived later this year.

This will however happen over the span of a few months. So there is still an opportunity for someone to contact me and take over maintenance and benevolent ************, be it for the whole Blitz project or individual repos. I promise to help make the transition as seamless as possible, to the best of my ability.

This PSA should also be first and foremost an opportunity to thank (again) people who stepped in in 2019. So I encourage everyone to go read the state of Blitz for last year.

It’s been an honor serving so many users, and thanks for all the fish!

🙏

One of our client has just reported to me that numbers in ordered lists on iBooks on iPhone were cropped. To solve the problem, I had to remove the reset and parameters of

:

ol,
margin: 0;
padding: 0;

ol {
margin: 1.5em 0;
padding-left: 5%;
}

I’m not sure if the problem could come from my client’s phone/iBooks not being updated or something, or if it is a genuine problem of Blitz. I would be happy to get an answer about it though :-) Thanks!

See http://www.gridlover.net/try and http://type-scale.com.

The idea is to make the “preprocessor part” transparent to people who don’t want to learn another language.

I have a question. How can right padding of td be calculated if there is no table width specified? The width of the table is not known before it is actually rendered.
padding: 0.75em 2% 0.6875em 0;

Not something complex by any means cf. backstopJS but very boring/long in the sense you must make the test files for basically everything in the CSS – e.g. ReadiumCSS tests.

Your work is incredible — Thank you. I am on the board of the OWASP Foundation which writes best practices for software security. I was trying to have a project off the ground to be able to publish these books in epub/ebook + physical form. I would very much would like to reach out to you for help — we are an OSS foundation so we have a mutual interest in leveraging open source tools to publish open source content :-)

Here is our page: https://github.com/OWASP/OWASP-Books/ Right now I use a mix of Pandoc & Make — — most of our community writes in MarkDown.

Please reach out when you have a chance!

• Put everything list in lists.less
• Create less files for def lists, pre + code, etc.

The idea is that there’s quite a lot of stuff in typo.less which won't be used for every book so it would be easier to import them if needed.

In passing, seeing your note for AccessibilityAPI, I’m wondering whether we should just keep ARIA and remove all others, along with AccessibilityControl given this issue in epub-revision.

Totally agreed!

I know this sounds like “avoiding misuse by obfuscation” but I’m wondering how many people will check the doc first instead, especially as in most cases, they should be removed as they don’t apply.

Maybe it would be better to keep only the essential and comment all that is optional?

Originally posted by @garconvacher in #31 (comment)

I'm interested in adding better support for the Japanese language (and any other languages with similar characteristics).

Japanese can be written horizontally or vertically. I'm interested in adding horizontal support because that's closer to English, which Blitz already supports.

But, one major difference between Japanese and English is that paragraphs are not indented. Instead, a blank line is used between paragraphs.

So, I'd like to find a way to:

1. Eliminate paragraph indents and use an empty line between paragraphs.
2. Ensure a consistent top/bottom margin between elements.

For example:

• Paragraph
• One blank line
• Paragraph
• One blank line
• List item
• One blank line
• List item
• One blank line
• Table
• One blank line
• Paragraph
• One blank line
• Heading
• One blank line
• Paragraph

And so on.

I don't know too much about LESS but would it be possible to add something like a variable to toggle "paragraphs with indents and standard Blitz margins" or "no indents for paragraphs; use a blank line instead and ensure that a blank line is consistently used as a bottom margin between elements"?

In typo.less, a line height of 1.2 is specified four times.

For example:

h2, .h2 {
  .rhythm(2, 2, 1);
  .rhythm(3, 0, 1);

  @media @kf8 {
    line-height: 1.2;     /* Minimum value Kindle supports */
  }

Why is this being done?

There is a body-line-height variable that is easy to change, but these values are unrelated to the value of that variable.

Japanese documents tend to have a line-height of 1.75, so I'm thinking that these line-heights should probably be increased as well-- either by adding a variable or by computing them to be based on the body-line-height. But maybe I am misunderstanding why this is being set here, so please let me know.

This is a non formal announcement of Blitz’ next stage.

It’s been quite a while no commit/pull request has been made to blitz and this is kinda normal since I’ve spent a lot of time doing research of development for the next milestone of the framework (CSS + JS).

The super important priority right now is implementing progressive enhancements into the CSS library. And this is what the “blitz next” project is all about.

Goal

Blitz next aims at bringing responsiveness to eBooks without media queries.

Media queries and JS are fucked, for various reasons, so responsiveness implies faking element queries with some modern CSS—mainly, calc().

References

A lot of people actually proved inventive so we’ve got a good basis to build upon.

• Responsive CSS Patterns without Media Queries
• Look, no media queries
• The Fab Four technique

Where we are right now

There’s a lot of potential, but we must deal with a few incompatibilities (pagination + some user settings).

I’ve been able to:

• create a dynamic type scale based on the size of the page/viewport, which won't scale proportionally when you increase/decrease font-size (compat issue: iBooks);
• scale a portrait image based on the font-size of its caption (no compat issue to date);
• float images so that they don’t block the flow (think of a full-page image that doesn’t block the following paragraphs);
• turn floating images into full-width images on small screens (compat issue: iBooks’ pagination in which a few images are cut off);
• have a caption display on the side of the image on large screens;
• create a responsive grid with flexbox (compat issue: pagination);
• align elements vertically (no issue to date);
• etc.

Examples

Dynamic type scale

h1 {
  font-size: calc(1em + 2.25vmin);
}
h2 {
  font-size: calc(1em + 1.5vmin);
}
h3 {
  font-size: calc(1em + 0.75vmin);
}

Portrait image scaling based on caption’s font-size

img {
  width: auto;
  max-width: 100%;  
  min-height: 300px;
  height: calc(98vh - 5em);
  max-height: 95%;
  object-fit: contain;
}

Float to block

figure {
  min-width: 40%;
  width: calc((30em - 100%) * 1000);
  max-width: 100%;
}

Responsive grid

.grid {
  display: flex;
  flex-wrap: wrap;
  flex: 1 1 15em;
}
.grid li {
  page-break-inside: avoid;
  break-inside: avoid;
}

Vertical align

parent {
  min-height: 95vh;
  display: flex;
  flex-direction: column;
  justify-content: {value};
}

Where we’re heading

I’m being honest, this project might fail. We’re nearly there but have to find solutions to the current incompatibilities.

So I’ll share a sample in Blitz Labs ASAP so that volunteers can take a look at it. In the meantime, you can discuss features you’d like to see provided or share common problems you’re encountering in eprdctn.

So I’m kinda thinking about modifying the reset and declaring list-style: none for every nav ol, and not just TOC.

Per spec, we have this:

In the context of this specification, the default display style of list items within nav elements MUST be equivalent to the list-style: none property [CSSSnapshot]. Reading Systems MUST NOT show list item numbering on these lists when presenting the Navigation Document outside of the spine, regardless of their support for CSS. Authors MAY specify alternative list styling using CSS for rendering of the document in the spine. source

And I guess, albeit opinionated, this is the default most people would also use if their navigation document is visible in the EPUB file. Obviously would be overridable.

A kindle workaround is already doing that in develop so that would remove !important and make it global – and not scoped to Kindle.