Skip to content

Commit 4f1a496

Browse files
JayPanozJayPanoz
committed
Update docs
Re #59
1 parent bca2c29 commit 4f1a496

18 files changed

+30
-24
lines changed

‎contributing.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ The following guidelines are aimed at existing or newly-created stylesheets for
5454
- Attribute selectors, like `input[type="text"]` should always wrap the attribute's value in double quotes.
5555
- Don’t use classes, style elements.
5656
- Only use `!important` when a style must be applied at any cost necessary.
57-
- Try using prefixed-properties which are necessary, including `-epub-properties` (check the [EPUB 3.1 spec](http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-css-prefixed) for a complete list).
57+
- Try using prefixed-properties which are necessary, including `-epub-properties` (check the [EPUB 3.2 spec](https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-css-prefixed) for a complete list).
5858

5959
### Stylesheet Header
6060

‎css/ReadMe.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Quickstart
22

3-
Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provides:
3+
Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provides styles for reflowable text:
44

55
- a CSS normalize for EPUB contents;
66
- paged and scrolled views;
@@ -10,6 +10,8 @@ Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provi
1010
- user settings;
1111
- media overlays and user highlights.
1212

13+
**Note:** Readium CSS stylesheets were not designed and should not be used for fixed-layout EPUB, nor other file formats like FB2, PRC, Mobi, TEI, etc.
14+
1315
## Important info
1416

1517
**TL;DR: use the stylesheets in the `css/dist` folder if you don’t need to customize Readium CSS.** All the flags and variables can then be taken at face value in the docs.

‎docs/CSS02-quickstart.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[Implementers’ doc]
44

5-
Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provides:
5+
Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provides styles for reflowable text:
66

77
- a CSS normalize for EPUB contents;
88
- paged and scrolled views;
@@ -12,6 +12,8 @@ Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provi
1212
- user settings;
1313
- media overlays and user highlights.
1414

15+
**Note:** Readium CSS stylesheets were not designed and should not be used for fixed-layout EPUB, nor other file formats like FB2, PRC, Mobi, TEI, etc.
16+
1517
## Important info
1618

1719
**TL;DR: use the stylesheets in the `css/dist` folder if you don’t need to customize Readium CSS.** All the flags and variables can then be taken at face value in the docs.

‎docs/CSS05-reflow_requirements.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
[Implementers’ doc] [Authors’ doc]
44

5-
Source: [EPUB Content Documents 3.1](http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-css)
5+
Source: [EPUB Content Documents 3.2](https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-css)
66

77
There’s a few criteria Reading Systems must meet in order to be conformant:
88

99
- it must support the official definition of CSS as described in the [W3C CSS Snapshot](https://www.w3.org/TR/CSS/);
10-
- it must support all `-epub-` prefixed properties ([list](http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-css-prefixed)).
10+
- it must support all `-epub-` prefixed properties ([list](https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-css-prefixed)).
1111

1212
In addition:
1313

‎docs/CSS20-spec_impact.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Here is a list of all the specs and proposals which are likely to impact Readium
66

77
The [W3C CSSWG-Drafts repo](https://github.com/w3c/csswg-drafts/issues) is a good way to keep up.
88

9-
Readium CSS’ fundamental approach has been reviewed and should be future proof, but you’ll have to keep the following in mind since EPUB 3.1 is now using CSS snapshots – those specs and proposals are very likely to be listed in future snapshots.
9+
Readium CSS’ fundamental approach has been reviewed and should be future proof, but you’ll have to keep the following in mind since EPUB 3.2 is now using CSS snapshots – those specs and proposals are very likely to be listed in future snapshots.
1010

1111
## Media Queries Level 5
1212

‎docs/CSS21-epub_compat.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -541,8 +541,8 @@ Docs: [CSS Text Module Level 4](https://www.w3.org/TR/css-text-4/#hyphenation)
541541

542542
## EPUB properties
543543

544-
Some authors might have used `-epub-` prefixed properties only, thinking they were enough since those CSS properties were standardized. Authors are now strongly encouraged to use unprefixed properties in EPUB 3.1.
544+
Some authors might have used `-epub-` prefixed properties only, thinking they were enough since those CSS properties were standardized. Authors are now strongly encouraged to use unprefixed properties in EPUB 3.2.
545545

546-
In the meantime, implementers may want to polyfill at least some of those properties, especially those related to vertical writing, as practical issues may arise due to the lack of file updates on the authoring side. [A mapping is available](http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-css-prefixed) in the EPUB 3.1 spec if needed.
546+
In the meantime, implementers may want to polyfill at least some of those properties, especially those related to vertical writing, as practical issues may arise due to the lack of file updates on the authoring side. [A mapping is available](https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-css-prefixed) in the EPUB 3.2 spec if needed.
547547

548548
A [PostCSS Plugin](https://github.com/JayPanoz/postcss-epub-interceptor) has been specifically created to unprefix those properties and change their value whenever needed – PostCSS can indeed be browerified. Implementers’ best option is running this process once and for all before distribution or file opening.

‎docs/CSS23-fxl_requirements.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[Implementers’ doc] [Authors’ doc]
44

5-
Source: [EPUB Content Documents 3.1](http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-fixed-layouts)
5+
Source: [EPUB Content Documents 3.2](https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-fixed-layouts)
66

77
There’s a few criteria Reading Systems must meet in order to be conformant:
88

@@ -40,6 +40,6 @@ The coordinate system defined by the `viewbox` is mapped to the viewport, keepin
4040

4141
## Notes
4242

43-
The `rendition:spread portrait` and `rendition:viewport` [are deprecated in EPUB 3.1](http://www.idpf.org/epub/31/spec/epub-packages.html#app-obs-deprecated).
43+
The `rendition:spread portrait` and `rendition:viewport` [are deprecated in EPUB 3.2](https://w3c.github.io/publ-epub-revision/epub32/spec/epub-packages.html#sec-package-metadata-fxl).
4444

4545
Consequently, the `rendition:spread-portrait` spine override is deprecated as well.

‎docs/ReadiumCSS_docs.epub

153 Bytes
Binary file not shown.

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-002.xhtml

+3-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616
<p>[Implementers’ doc]</p>
1717

18-
<p>Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provides:</p>
18+
<p>Readium CSS is a set of reference stylesheets for EPUB Reading Systems. It provides styles for reflowable text:</p>
1919

2020
<ul>
2121
<li>a CSS normalize for EPUB contents;</li>
@@ -33,6 +33,8 @@
3333
<li>media overlays and user highlights.</li>
3434
</ul>
3535

36+
<p><strong>Note:</strong> Readium CSS stylesheets were not designed and should not be used for fixed-layout EPUB, nor other file formats like FB2, PRC, Mobi, TEI, etc.</p>
37+
3638
<section id="important-info" class="level2">
3739
<h2 id="sigil_toc_id_163">Important info</h2>
3840

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-005.xhtml

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,14 @@
1515

1616
<p>[Implementers’ doc] [Authors’ doc]</p>
1717

18-
<p>Source: <a href="http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-css">EPUB Content Documents 3.1</a></p>
18+
<p>Source: <a href="https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-css">EPUB Content Documents 3.2</a></p>
1919

2020
<p>There’s a few criteria Reading Systems must meet in order to be conformant:</p>
2121

2222
<ul>
2323
<li>it must support the official definition of CSS as described in the <a href="https://www.w3.org/TR/CSS/">W3C CSS Snapshot</a>;</li>
2424

25-
<li>it must support all <code>-epub-</code> prefixed properties (<a href="http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-css-prefixed">list</a>).</li>
25+
<li>it must support all <code>-epub-</code> prefixed properties (<a href="https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-css-prefixed">list</a>).</li>
2626
</ul>
2727

2828
<p>In addition:</p>

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-010.xhtml

+1-1
Original file line numberDiff line numberDiff line change
@@ -780,7 +780,7 @@
780780
</section>
781781

782782
<section id="recommended-fonts-for-accessibility" class="level2">
783-
<h2 id="sigil_toc_id_131">Recommended fonts for Accessibility</h2>
783+
<h2 id="sigil_toc_id_168">Recommended fonts for Accessibility</h2>
784784

785785
<p>ReadiumCSS is shipping with 2 a11y-related fonts to be found in the <code>dist/fonts</code> folder:</p>
786786

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-020.xhtml

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919

2020
<p>The <a href="https://github.com/w3c/csswg-drafts/issues">W3C CSSWG-Drafts repo</a> is a good way to keep up.</p>
2121

22-
<p>Readium CSS’ fundamental approach has been reviewed and should be future proof, but you’ll have to keep the following in mind since EPUB 3.1 is now using CSS snapshots – those specs and proposals are very likely to be listed in future snapshots.</p>
22+
<p>Readium CSS’ fundamental approach has been reviewed and should be future proof, but you’ll have to keep the following in mind since EPUB 3.2 is now using CSS snapshots – those specs and proposals are very likely to be listed in future snapshots.</p>
2323

2424
<section id="media-queries-level-5" class="level2">
2525
<h2 id="sigil_toc_id_103">Media Queries Level 5</h2>

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-021.xhtml

+2-2
Original file line numberDiff line numberDiff line change
@@ -579,9 +579,9 @@
579579
<section id="epub-properties" class="level2">
580580
<h2 id="sigil_toc_id_137">EPUB properties</h2>
581581

582-
<p>Some authors might have used <code>-epub-</code> prefixed properties only, thinking they were enough since those CSS properties were standardized. Authors are now strongly encouraged to use unprefixed properties in EPUB 3.1.</p>
582+
<p>Some authors might have used <code>-epub-</code> prefixed properties only, thinking they were enough since those CSS properties were standardized. Authors are now strongly encouraged to use unprefixed properties in EPUB 3.2.</p>
583583

584-
<p>In the meantime, implementers may want to polyfill at least some of those properties, especially those related to vertical writing, as practical issues may arise due to the lack of file updates on the authoring side. <a href="http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-css-prefixed">A mapping is available</a> in the EPUB 3.1 spec if needed.</p>
584+
<p>In the meantime, implementers may want to polyfill at least some of those properties, especially those related to vertical writing, as practical issues may arise due to the lack of file updates on the authoring side. <a href="https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-css-prefixed">A mapping is available</a> in the EPUB 3.2 spec if needed.</p>
585585

586586
<p>A <a href="https://github.com/JayPanoz/postcss-epub-interceptor">PostCSS Plugin</a> has been specifically created to unprefix those properties and change their value whenever needed – PostCSS can indeed be browerified. Implementers’ best option is running this process once and for all before distribution or file opening.</p>
587587
</section>

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-022.xhtml

+1-1
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ require("postcss-alter-property-value")({
142142
<li>remove static representations which can’t be interpolated and are <code>undefined</code> (<code>remove</code> task).</li>
143143
</ol>
144144

145-
<p>We recommend managing user settings via JavaScript in this case, especially as you can test support for CSS variables, as described in the <a href="../docs/CSS07-variables.md">CSS Variables primer</a>.</p>
145+
<p>We recommend managing user settings via JavaScript in this case, especially as you can test support for CSS variables, as described in the <a href="../Text/Section-007.xhtml">CSS Variables primer</a>.</p>
146146
</section>
147147
</section>
148148

‎docs/ReadiumCSS_docs/OEBPS/Text/Section-023.xhtml

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616
<p>[Implementers’ doc] [Authors’ doc]</p>
1717

18-
<p>Source: <a href="http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-fixed-layouts">EPUB Content Documents 3.1</a></p>
18+
<p>Source: <a href="https://w3c.github.io/publ-epub-revision/epub32/spec/epub-contentdocs.html#sec-fixed-layouts">EPUB Content Documents 3.2</a></p>
1919

2020
<p>There’s a few criteria Reading Systems must meet in order to be conformant:</p>
2121

@@ -72,7 +72,7 @@
7272
<section id="notes-3" class="level2">
7373
<h2 id="sigil_toc_id_62">Notes</h2>
7474

75-
<p>The <code>rendition:spread portrait</code> and <code>rendition:viewport</code> <a href="http://www.idpf.org/epub/31/spec/epub-packages.html#app-obs-deprecated">are deprecated in EPUB 3.1</a>.</p>
75+
<p>The <code>rendition:spread portrait</code> and <code>rendition:viewport</code> <a href="https://w3c.github.io/publ-epub-revision/epub32/spec/epub-packages.html#sec-package-metadata-fxl">are deprecated in EPUB 3.2</a>.</p>
7676

7777
<p>Consequently, the <code>rendition:spread-portrait</code> spine override is deprecated as well.</p>
7878
</section>

‎docs/ReadiumCSS_docs/OEBPS/Text/nav.xhtml

+1-1
Original file line numberDiff line numberDiff line change
@@ -290,7 +290,7 @@
290290
<a href="../Text/Section-010.xhtml#sigil_toc_id_119">Recommended Typefaces</a>
291291
</li>
292292
<li>
293-
<a href="../Text/Section-010.xhtml#sigil_toc_id_131">Recommended fonts for Accessibility</a>
293+
<a href="../Text/Section-010.xhtml#sigil_toc_id_168">Recommended fonts for Accessibility</a>
294294
</li>
295295
<li>
296296
<a href="../Text/Section-010.xhtml#sigil_toc_id_131">Recommended fonts for CJK</a>

‎docs/ReadiumCSS_docs/OEBPS/content.opf

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<dc:language>en</dc:language>
99
<dc:identifier id="epub-id-1">urn:uuid:91cab77e-946f-4814-9e61-8494a5d5cb0f</dc:identifier>
1010
<meta name="cover" content="cover_jpg"/>
11-
<meta property="dcterms:modified">2018-05-14T13:03:18Z</meta>
11+
<meta property="dcterms:modified">2019-02-20T15:08:53Z</meta>
1212
<meta content="0.9.5" name="Sigil version"/>
1313
</metadata>
1414
<manifest>

‎docs/ReadiumCSS_docs/OEBPS/toc.ncx

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="utf-8" ?>
22
<ncx version="2005-1" xmlns="http://www.daisy.org/z3986/2005/ncx/">
33
<head>
4-
<meta content="91cab77e-946f-4814-9e61-8494a5d5cb0f" name="dtb:uid"/>
4+
<meta content="urn:uuid:91cab77e-946f-4814-9e61-8494a5d5cb0f" name="dtb:uid"/>
55
<meta content="2" name="dtb:depth"/>
66
<meta content="0" name="dtb:totalPageCount"/>
77
<meta content="0" name="dtb:maxPageNumber"/>
@@ -529,7 +529,7 @@
529529
<navLabel>
530530
<text>Recommended fonts for Accessibility</text>
531531
</navLabel>
532-
<content src="Text/Section-010.xhtml#sigil_toc_id_131"/>
532+
<content src="Text/Section-010.xhtml#sigil_toc_id_168"/>
533533
</navPoint>
534534
<navPoint id="navPoint88">
535535
<navLabel>

0 commit comments

Comments
 (0)