Support the :nth() page selector.

docs/features.rst

@@ -301,70 +301,89 @@ CSS Generated Content for Paged Media Module
 
 The `CSS Generated Content for Paged Media Module`_ (GCPM) is a working draft
 defining "new properties and values, so that authors may bring new techniques
-(running headers and footers, footnotes, leaders, bookmarks) to paged media".
+(running headers and footers, footnotes, page selection) to paged media".
 
-Three features from this module have been implemented in WeasyPrint.
+`Page selectors`_ are also supported by WeasyPrint. You can select pages
+according to their position in the document:
 
-.. _bookmarks:
+.. code-block:: css
 
-The first feature is `PDF bookmarks`_.  Using the experimental_
-``bookmark-level`` and ``bookmark-level`` properties, you can add
-bookmarks that will be available in your PDF reader.
+    @page :nth(3) { background: red } /* Third page */
+    @page :nth(2n+1) { background: green } /* Odd pages */
 
-Bookmarks have already been added in the WeasyPrint's `user agent stylesheet`_,
-so your generated documents will automatically have bookmarks on headers (from
-``<h1>`` to ``<h6>``). But for example, if you have only one top-level ``<h1>``
-and do not wish to include it in the bookmarks, add this in your stylesheet:
+The other features of GCPM are **not** implemented:
 
-.. code-block:: css
+- running elements (``running()`` and ``element()``);
+- footnotes (``float: footnote``, ``footnote-display``, ``footnote`` counter,
+  ``::footnote-call``, ``::footnote-marker``, ``@footnote`` rule,
+  ``footnote-policy``);
+- page groups (``:nth(X of pagename)`` pseudo-class).
 
-    h1 { bookmark-level: none }
+.. _CSS Generated Content for Paged Media Module: http://www.w3.org/TR/css-gcpm-3/
+.. _Page selectors: https://www.w3.org/TR/css-gcpm-3/#document-page-selectors
 
-The second feature is `Named strings`_. You can define strings related to the
-first or last element of a type present on a page, and display these strings in
-page borders. This feature is really useful to add the title of the current
-chapter at the top of the pages of a book for example.
 
-The named strings can embed static strings, counters, cross-references, tag contents 
-and tag attributes.
+CSS Generated Content Module Level 3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `CSS Generated Content Module Level 3`_ is a working draft helping "authors
+[who] sometimes want user agents to render content that does not come from the
+document tree. One familiar example of this is numbered headings
+[…]. Similarly, authors may want the user agent to insert the word "Figure"
+before the caption of a figure […], or replacing elements with images or other
+multimedia content."
+
+`Named strings`_ are supported by WeasyPrint. You can define strings related to
+the first or last element of a type present on a page, and display these
+strings in page borders. This feature is really useful to add the title of the
+current chapter at the top of the pages of a book for example.
+
+The named strings can embed static strings, counters, cross-references, tag
+contents and tag attributes.
 
 .. code-block:: css
 
-    @top-center { content: string(chapter); }
+    @top-center { content: string(chapter) }
     h2 { string-set: chapter "Current chapter: " content() }
 
-
-The third feature is internal `Cross-references`_,
-which makes it possible to retrieve counter or content values from 
-targets (anchors or ids) in the current document:
+`Cross-references`_ retrieve counter or content values from targets (anchors or
+identifiers) in the current document:
 
 .. code-block:: css
 
-    a::after { 
-      content: ", on page " target-counter(attr(href), page);
-    }
-    a::after { 
-      content: ", see " target-text(attr(href)); 
-    }
-
-In particular, ``target-counter()`` and ``target-text()`` are useful when 
-it comes to tables of contents,
-see `an example <https://github.com/Kozea/WeasyPrint/pull/652#issuecomment-403276559>`_.
-
-The other features of GCPM are **not** implemented:
+    a::after { content: ", on page " target-counter(attr(href), page) }
+    a::after { content: ", see " target-text(attr(href)) }
 
-- running elements (``running()`` and ``element()``);
-- footnotes (``float: footnote``, ``footnote-display``, ``footnote`` counter,
-  ``::footnote-call``, ``::footnote-marker``, ``@footnote`` rule,
-  ``footnote-policy``);
-- page selectors and page groups (``:nth()`` pseudo-class);
+In particular, ``target-counter()`` and ``target-text()`` are useful when it
+comes to tables of contents (see `an example
+<https://github.com/Kozea/WeasyPrint/pull/652#issuecomment-403276559>`_).
+
+.. _bookmarks:
+
+You can also control `PDF bookmarks`_ with WeasyPrint. Using the experimental_
+``bookmark-level`` and ``bookmark-level`` properties, you can add bookmarks
+that will be available in your PDF reader.
+
+Bookmarks have already been added in the WeasyPrint's `user agent stylesheet`_,
+so your generated documents will automatically have bookmarks on headers (from
+``<h1>`` to ``<h6>``). But for example, if you have only one top-level ``<h1>``
+and do not wish to include it in the bookmarks, add this in your stylesheet:
+
+.. code-block:: css
+
+    h1 { bookmark-level: none }
+
+The other features of this module are **not** implemented:
+
+- quotes (``content: *-quote``);
 - leaders (``content: leader()``);
 - bookmark states (``bookmark-state``).
 
-.. _CSS Generated Content for Paged Media Module: http://www.w3.org/TR/css-gcpm-3/
-.. _PDF bookmarks: http://www.w3.org/TR/css-gcpm-3/#bookmarks
-.. _Named strings: http://www.w3.org/TR/css-gcpm-3/#named-strings
-.. _Cross-references: https://www.w3.org/TR/css-gcpm-3/#cross-references
+.. _CSS Generated Content Module Level 3: http://www.w3.org/TR/css-content-3/
+.. _Quotes: https://www.w3.org/TR/css-content-3/#quotes
+.. _Named strings: https://www.w3.org/TR/css-content-3/#named-strings
+.. _Cross-references: https://www.w3.org/TR/css-content-3/#cross-references
+.. _PDF bookmarks: https://www.w3.org/TR/css-content-3/#bookmark-generation
 .. _experimental: http://www.w3.org/TR/css-2010/#experimental
 .. _user agent stylesheet: https://github.com/Kozea/WeasyPrint/blob/master/weasyprint/css/html5_ua.css