Feedback requested re. demarcating standard CSS blocks

[Alex Cabal]

While updating the corpus for the new responsive drama CSS, an issue
I've thought about in the past came up again.

We have thousands of CSS files which are mostly composed of
copy-and-paste standard "blocks" of CSS, like blocks for poetry, blocks
for drama, etc.

However right now we don't have a way to demarcate those blocks within
the CSS file itself.

This makes it difficult to update standard CSS, because if some was
removed (for example because of an unused selector) or if some was
reordered for some reason, how can we find the exact block we're looking
to update?

Having demarcated blocks would also unlock the ability to add some lint
improvements, like for example checking if a block conforms to the
current standard regardless of unused selectors, or understanding
whether a later CSS rule overrides something in a standard block, or is
a locally-specific duplicate selector that should be merged together.

Does anyone have any ideas on how we might demarcate such blocks? For
example, something like:

/* se:css start verse-1.8.5 */
...verse css...
/* se:css end */

This is just a raw brainstorm.

Any ideas, thoughts, opinions, proposals?

[Robin Whittleton]

Given that we’re loading from a file system and not over the network, can’t we have versioned sub files and use @import to pull them in?

-Robin

> On 4 Feb 2026, at 21:22, 'Alex Cabal' via Standard Ebooks <standar...@googlegroups.com> wrote:
>
> While updating the corpus for the new responsive drama CSS, an issue I've thought about in the past came up again.

> --
> You received this message because you are subscribed to the Google Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to standardebook...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/standardebooks/957d454c-1ed5-4c6a-b25f-050257a18431%40standardebooks.org.

[Alex Cabal]

That's one option but I don't know if ADE supports imports... I would assume no but it's worth testing. Although we could just inline the imports for the compatible build.

[Vince]

I have on my list of things that need a round tuit to suggest a simplified version of this. Some of the CSS blocks in the manual have comments around, some of them don’t. I always put them around the standard blocks in my own productions, and thought it would be helpful to do so for all of them in the manual (and thus all productions) as well.

However, doing so doesn’t guarantee that what’s in between the comments is “standard.” I run across CSS in reviews all the time where the standard CSS has been copied and then adjusted to do something different, e.g. lines added/changed in the standard “centered dedication” CSS to change the style to small/all caps, etc., rather than making those changes in a different section of local.css. IOW, the blocks may have started copy-and-paste, but they might not have ended up that way.

I don’t know much about @import, but Robin’s idea might be the best way; put each of the “standard” CSSs in a separate file, update the manual to have people add “@import epigraph.css”, and then inline them (if necessary) in the compatibility build. That forces everyone to leave the standard CSS alone, and make any needed changes to the local.css proper.

Alternatively, we could make each of them their own file, and change the instructions to just add them to the top of whatever file they’re needed in. So instead of just core.css and local.css on each file, the dedication file might also have dedication.css, etc. More fussy, obviously; I’m not suggesting it as much as just pointing out it’s another option.

[Alex Cabal]

The more I think about it the more I like @import. I can't test just
this minute but if @import works out of the box in iBooks then we could
do that as the default for the "advanced" epub. Then it's literally a
string replace to compile it down to compatible etc. builds.

We could create two new tools:

- se add-css to import from a predefined list of blocks,

- se normalize-css to "normalize" these blocks/files which would 1)
update each file to the newest versions and 2) then remove unused
selectors based on what's in the ebook.

That sounds pretty good to me provided it works in iBooks (which is at
least unofficially the best "advanced" renderer, so that if it doesn't
work there then it probably won't work anywhere else)

On 2/4/26 6:13 PM, Vince wrote:
> I have on my list of things that need a round tuit to suggest a
> simplified version of this. Some of the CSS blocks in the manual have
> comments around, some of them don’t. I always put them around the
> standard blocks in my own productions, and thought it would be helpful
> to do so for all of them in the manual (and thus all productions) as well.
>
> However, doing so doesn’t guarantee that what’s in between the comments
> is “standard.” I run across CSS in reviews all the time where the
> standard CSS has been copied and then adjusted to do something
> different, e.g. lines added/changed in the standard “centered
> dedication” CSS to change the style to small/all caps, etc., rather than
> making those changes in a different section of local.css. IOW, the

> blocks may have /started/ copy-and-paste, but they might not have ended

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com

> <mailto:standardebook...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/7FAF5AA6-0C55-4CEC-B807-C1120EECF792%40letterboxes.org
> <https://groups.google.com/d/msgid/standardebooks/7FAF5AA6-0C55-4CEC-
> B807-C1120EECF792%40letterboxes.org?utm_medium=email&utm_source=footer>.

[Vince]

Note this gets tricky for things like letters, where we have “standard” CSS but we only use the part needed for the letters in this production. Unlike dedications, epigraphs, drama, we don’t copy-and-paste ALL of the letter CSS, just whatever portion is needed. So maybe we don’t change how letters are handled, even though as a whole it’s “standard” CSS.

[Alex Cabal]

Letters might probably benefit from a basic commonly used subset, like
footer, postscript, remove indent from line after salutation, etc. Or
might be best to just not do letters at all since they vary so widely.

On 2/4/26 6:19 PM, Vince wrote:
> Note this gets tricky for things like letters, where we have “standard”
> CSS but we only use the part needed for the letters in this production.
> Unlike dedications, epigraphs, drama, we don’t copy-and-paste ALL of the
> letter CSS, just whatever portion is needed. So maybe we don’t change
> how letters are handled, even though as a whole it’s “standard” CSS.
>
>> On Feb 4, 2026, at 6:13 PM, Vince <vr_se...@letterboxes.org> wrote:
>>
>> I have on my list of things that need a round tuit to suggest a
>> simplified version of this. Some of the CSS blocks in the manual have
>> comments around, some of them don’t. I always put them around the
>> standard blocks in my own productions, and thought it would be helpful
>> to do so for all of them in the manual (and thus all productions) as well.
>>
>> However, doing so doesn’t guarantee that what’s in between the
>> comments is “standard.” I run across CSS in reviews all the time where
>> the standard CSS has been copied and then adjusted to do something
>> different, e.g. lines added/changed in the standard “centered
>> dedication” CSS to change the style to small/all caps, etc., rather
>> than making those changes in a different section of local.css. IOW,

>> the blocks may have/started/ copy-and-paste, but they might not have

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/9A0E3E37-2FFF-4781-8E56-6A7860D1FEE6%40letterboxes.org
> <https://groups.google.com/d/msgid/
> standardebooks/9A0E3E37-2FFF-4781-8E56-6A7860D1FEE6%40letterboxes.org?
> utm_medium=email&utm_source=footer>.

[Vince]

Honestly we probably should move footnote and signature out of letters—they are not letter-specific, and are (validly) used in many places other than letters, e.g. prefaces, forewords, dedications, etc.

[Robin Whittleton]

@import was in the CSS1 spec from 1996 so I’d be surprised if Books at least didn’t support it. I’ll have a poke later.

-Robin

> On 5 Feb 2026, at 01:38, Vince <vr_se...@letterboxes.org> wrote:
>
> Honestly we probably should move footnote and signature out of letters—they are not letter-specific, and are (validly) used in many places other than letters, e.g. prefaces, forewords, dedications, etc.

> --
> You received this message because you are subscribed to the Google Groups "Standard Ebooks" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to standardebook...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/standardebooks/CA068A27-21AB-4A63-A6B5-23DF8308712A%40letterboxes.org.

[Vince]

It does work. But it took me a while to figure out the right combination. Everything but the last paragraph was written before I got it working.

Safari is supposed to have supported it since 1.x, so it shouldn’t be a problem. But it’s not working for me, so I must be doing something wrong. I tried it first in Books, but I’ve since just opened the file in Safari and have been testing it there.

I created an epigraph.css file in the css directory that contains the epigraph CSS that formerly existed in local.css. I then added a line to the very top (line 1) of local.css that says

@import “epigraph.css”;

I then opened the standalone epigraph.xhtml file in Safari.

It doesn’t work—the standalone epigraph is not formatted correctly, and it is formatted correctly when the epigraph css is embedded in local.css as usual.

I’ve tried the above, `”../css/epigraph.css”`, `url(“epigraph.css”);`, `url(“../css/epigraph.css”);`, `”css/epigraph.css”` and the url version of that. None of them worked.

None of the documentation I could find indicated what relative path the file is loaded from; I assume that since both local.css and epigraph.css are in the same directory, then there’s no need for anything other than the filename, but I tried the others just in case.

I removed all the comments in epigraph.css in case that was an issue; still didn’t work.

I’m sure it’s something intuitively obvious to the most casual observer…

… and of course, it was. I thought I tried this earlier, but I must have had something else wrong at the same time. It only works if epigraph.css also has the appropriate @namespace rule in it. IOW, it doesn’t appear to be work as if the imported file is copied into the local.css file; if that was true, then the @namespace in local.css should be sufficient for both. But without the @namespace in epigraph.css, it doesn’t work, and with it, it does. (I’m guessing epigraph.css should also have the @charset, but it works without it, probably because there are no non-ascii characters in the file right now.) The initial `@import “epigraph.css”` was sufficient, so the starting directory would appear to be the directory where the importing file is.

[Vince]

Firefox Mac behaves the same way, as does calibre’s CSS processor. So that would appear to be the way it’s implemented; any imported file needs whatever @namespace defined in it that the imported file’s CSS uses, regardless of whether it’s already in the importing CSS file.

[Robin Whittleton]

Yep, exactly. @imports need to go before @namespace, and @namespace declarations are specific to a CSS file. Any @imports also specifically need to go after @charset according to the spec.

I’ve built a test book using an @import and can confirm that it works natively in Apple Books, Kobo kepub and Kobo epub (ADE). We might not need to do any postprocessing on this? Well, outside of Kindle, but I don’t have one available to test.

-Robin

-- 
You received this message because you are subscribed to the Google Groups "Standard Ebooks" group.
To unsubscribe from this group and stop receiving emails from it, send an email to standardebook...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/standardebooks/08F2F368-5609-45C0-A252-A8F5D131BB5E%40letterboxes.org.

[Hendrik Kaiber]

I tested in my Kindle PW (11th gen.) and it doesn't seem to work.

I picked The Mysteries of Udolpho and moved both the epigraph and poetry css to their own file, and it works in Firefox, but doesn't in the kindle. I made sure to put both the charset and namespace declarations in the new css files, and it didn't matter. I also put the @import at the top of the local.css file, below the @charset and before the @namespace declarations. So this simple solution might need to be tweaked for the kindle versions. 

—Hendrik

[Robin Whittleton]

I also just checked in Thorium and as expected it works fine there. So I think we can say that we’d just need the Kindle build to be concatenated.

-Robin

To view this discussion visit https://groups.google.com/d/msgid/standardebooks/60a92374-1ec9-4afe-b936-376d6d38be16n%40googlegroups.com.

[Asher Smith]

I'm not sure I like the idea mentioned above of having the blocks be a little more granular (letter-header, letter-body, and letter-footer rather than just letter) because I'm worried that it's easy to miss things. For example, I have a standard drama css block file that I add to all my productions, and then I just remove everything lint tells me isn't being used at the end of the production, and that includes the following blocks:

• core drama
• together dialogue
• editorial stage directions
• stage direction abbreviations
• dramatis personae

I almost never need to actually use editorial stage directions, but I prefer to be reminded that it exists.

[Vince]

I don’t think the spec means it has to come after @charset and/or @layer, just that those are the only ones it can go after. And, as expected, it works either way, i.e. with @import in the first line, or with it after @charset. I personally would prefer it/them first; that way they don’t get lost between the @charset and @namespace rules.

[Vince]

Right, and now you would just include one or more @imports. As I said above, I don’t think letters work for importing anyway; there’s too much variability.

How lint will handle @imports is a whole nuther question; will it ignore any “unused” CSS that are in an import? Will it figure out we don’t need anything in an @import, i.e. we have a stray @import we don’t need? And so on. Lots of implementation details to be figured out.

Anyway, ultimately I expect the decisions, as now, will be what’s best for the books, not what’s easiest for us. :)

[Alex Cabal]

On a semi-related note, we can *probably* get rid of @charset now, that
was a leftover from over a decade ago, for completeness; today browsers
assume utf-8 when no charset is declared and I doubt there's a single
non-ascii character in any local.css file of ours anyway. But we can do
that as a separate thing.

On 2/5/26 9:54 AM, Vince wrote:
> I don’t think the spec means it /has/ to come after @charset and/or
> @layer, just that those are the only ones it /can/ go after. And, as

> expected, it works either way, i.e. with @import in the first line, or
> with it after @charset. I personally would prefer it/them first; that
> way they don’t get lost between the @charset and @namespace rules.
>
>> On Feb 5, 2026, at 1:25 AM, Robin Whittleton <ro...@reala.net> wrote:
>>
>> Yep, exactly. @imports need to go before @namespace, and @namespace
>> declarations are specific to a CSS file. Any @imports also
>> specifically need to go after @charset according to the spec.
>>
>> I’ve built a test book using an @import and can confirm that it works
>> natively in Apple Books, Kobo kepub and Kobo epub (ADE). We might not
>> need to do any postprocessing on this? Well, outside of Kindle, but I
>> don’t have one available to test.
>

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com

> <mailto:standardebook...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/59EEC24A-7C48-497C-8B9E-15B6C5B7B054%40letterboxes.org
> <https://groups.google.com/d/msgid/
> standardebooks/59EEC24A-7C48-497C-8B9E-15B6C5B7B054%40letterboxes.org?
> utm_medium=email&utm_source=footer>.

[Alex Cabal]

Updating lint shouldn't be too hard because it's easy to extract the
filename from the @import string, so we'd just process any imports just
like we would local.css.

On 2/5/26 10:00 AM, Vince wrote:
> Right, and now you would just include one or more @imports. As I said
> above, I don’t think letters work for importing anyway; there’s too much
> variability.
>
> How lint will handle @imports is a whole nuther question; will it ignore
> any “unused” CSS that are in an import? Will it figure out we don’t

> need /anything/ in an @import, i.e. we have a stray @import we don’t

> need? And so on. Lots of implementation details to be figured out.
>
> Anyway, ultimately I expect the decisions, as now, will be what’s best
> for the books, not what’s easiest for us. :)
>
>> On Feb 5, 2026, at 7:18 AM, Asher Smith
>> <forlackofa...@gmail.com> wrote:
>>
>> I'm not sure I like the idea mentioned above of having the blocks be a
>> little more granular (letter-header, letter-body, and letter-footer
>> rather than just letter) because I'm worried that it's easy to miss
>> things. For example, I have a standard drama css block file that I add
>> to all my productions, and then I just remove everything lint tells me
>> isn't being used at the end of the production, and that includes the
>> following blocks:
>>

>> * core drama
>> * together dialogue
>> * editorial stage directions
>> * stage direction abbreviations
>> * dramatis personae

>>
>> I almost never need to actually use editorial stage directions, but I
>> prefer to be reminded that it exists.
>

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com

> <mailto:standardebook...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/51914D4A-074C-48C8-9A11-3ADDE9BF4DF3%40letterboxes.org
> <https://groups.google.com/d/msgid/
> standardebooks/51914D4A-074C-48C8-9A11-3ADDE9BF4DF3%40letterboxes.org?
> utm_medium=email&utm_source=footer>.

[Vince]

Would we though? That’s one of the questions—will we leave all the @import files as is, or will we remove CSS from them that aren’t being used in a particular production, like we do for local? And if we do, doesn’t that defeat the purpose of @imports—now the @import file doesn’t look the same across the corpus, and can’t be unconditionally replaced.

Regardless of that decision, the unused selector check, just to pick an example, is determined by loading up local.css and then processing every other file. Are we going to load local.css and all the @imports at once, then process all the text files? Then how will lint identify that we didn’t use any of a particular file? And, if we don’t care about unused CSS in imports (assuming the opposite decision from above), then how will we differentiate unused selectors in local.css from unused selectors in the @imports?

And, as asked elsewhere in the thread, how granular will we get about the @imports? Will all of drama, including all of the optional things and dramatis personae, be in one @import, or will we split it into multiple (and if so, how many)? Same for epigraph—will each of the three sections (all, section header, full-page) be its own @import, or will it just be one? And for images (include full-page?), and so on.

I’m not looking for answers to all of the above, just pointing out that there are a lot of decisions to be made on how it’s going to work, and the sum of those decisions will determine how easy/difficult the implementation is going to be. Lint might turn out to be “not too hard,” but seems too early to tell.

[Alex Cabal]

On 2/5/26 2:10 PM, Vince wrote:
> Would we though? That’s one of the questions—will we leave all the
> @import files as is, or will we remove CSS from them that aren’t being
> used in a particular production, like we do for local? And if we do,
> doesn’t that defeat the purpose of @imports—now the @import file doesn’t
> look the same across the corpus, and can’t be unconditionally replaced.

This is what the theoretical se normalize-css tool would be for. It
would first copy complete template imports into your dir if they exist.
Then it would remove unused selectors from them. The outcome is the
same: the latest template CSS but without unused selectors.

> Regardless of that decision, the unused selector check, just to pick an
> example, is determined by loading up local.css and then processing every

> other file. Are we going to load local.css /and/ all the @imports at
> once, /then/ process all the text files? Then how will lint identify
> that we didn’t use /any/ of a particular file? And, if we /don’t/ care

> about unused CSS in imports (assuming the opposite decision from above),
> then how will we differentiate unused selectors in local.css from unused
> selectors in the @imports?

These are implementation details. Anything can be accomplished. I don't
think this will be too difficult to sort out.

[B Keith]

We could think about it another way entirely…?

Just add all the code blocks to the standard css file. Then build a tool that removes unused css blocks upon build. I know Sigil has something similar — I have started to use this methodology in my own projects because its is easier to cut then organize the additions.

Just a thought.

Bruce

_________

Gaudeamus igitur iuvenes dum sumus

--
You received this message because you are subscribed to the Google Groups "Standard Ebooks" group.

To unsubscribe from this group and stop receiving emails from it, send an email to standardebook...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/standardebooks/68650bb9-ea89-4c15-b803-d0f112ecc4e9%40standardebooks.org.

[Alex Cabal]

That is an interesting approach and could be a lot simpler to implement.
We would still need some kind of `se normalize-css`tool but the rest of
the implementation would be much simpler... Does anyone else have any
opinions?

On 2/9/26 11:39 AM, B Keith wrote:
> We could think about it another way entirely…?
>

> Just add /all/ the code blocks to the standard css file. Then build a

> <mailto:standardebook...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/E30FAE4F-D6B2-40DC-A422-17D9D94C88D0%40gmail.com
> <https://groups.google.com/d/msgid/standardebooks/E30FAE4F-D6B2-40DC-
> A422-17D9D94C88D0%40gmail.com?utm_medium=email&utm_source=footer>.

[Vince]

If we did that (and it’s essentially the way I’ve worked for years; I have a local.css that contains all of our standard CSS that gets pulled in by `create-draft`), maybe we just leave it untouched and create a new custom.css (or whatever name) to hold truly custom CSS for the project. That way we ensure that the standard CSS is “clean” (i.e. not rearranged, added to, attributes changed, etc., making it trivial to normalize).

So core.css remains always the same, local.css contains all of our “standard” CSS, remains off-limits to manual changes as core.css is, but `se normalize` will remove unused CSS, and custom.css contains any CSS specific to the production.

In addition to making it easier for producers, this would also help reviewers—they wouldn’t need to concern themselves with anything but custom.css, and it would generally have very little if any CSS in it.

[Vince]

Or maybe call them standard.css and local.css.