Expanding documentation on PfB CSS properties 'widows' and 'orphans'.

yeslogic · Sep 17, 2024 · 2a93259 · 2a93259
1 parent 33806e5
commit 2a93259
Show file tree

Hide file tree

Showing 2 changed files with 58 additions and 27 deletions.
diff --git a/docs/prince-for-books.md b/docs/prince-for-books.md
@@ -57,6 +57,37 @@ Pagination flexibility is used to achieve the following page-breaking goals:
 * Avoiding a short gap at the end of a page resulting from satisfying the rules defined by above properties without the `-prince-prefer` keyword;
 * Avoiding hyphenating at the end of a page or column.
 
+The properties `widows` and `orphans` additionally take a second, optional, comma-separated value expressed with the additional keyword `-prince-prefer`. This is useful in case the _preference_, expressed with the additional keyword, is a bigger amount than the hard _requirement_ expressed in the first value.
+
+CSS
+
+```css
+    p {
+      widows: 2, -prince-prefer 3;
+    }
+```
+
+The first value is a requirement strong enough that lines can be push from the previous page if necessary, while the second value with the `-prince-prefer` keyword is merely a preference that tries to be achieved, if possible, by only using the pagination flexibility that has been granted.
+
+Another feature in Prince for Books are the so-called "fractional widows": the [`widows`](css-props.md#prop-widows) property is allowed a value expressed as percentage, followed by the keyword `-prince-full`.
+
+CSS
+
+```css
+    p {
+      widows: 50% -prince-full;
+    }
+```
+This indicates that one widow line is accepted, as long as the line width is at least the given percentage value of the available page width, to avoid the worst case of having a widow line that is only one or two words long.
+
+CSS
+
+```css
+    p {
+      widows: 50% -prince-full, -prince-prefer 70% -prince-full;
+    }
+```
+
 
 Line breaking
 -------------
@@ -233,15 +264,3 @@ The value `change` means to make the paragraph either a line longer or shorter,
 A simple integer value is the least convenient value to use (since choosing the desired number requires counting the existing number of lines, and since this property is most commonly used on long paragraphs). Its value lies in the fact that the result is not subject to variation in "the number of lines that the paragraph would otherwise have had", as can occur if this paragraph spans a page end, and a subsequent styling change causes some earlier content to changes in size, affecting what is the last line before the break, and if this in turn affects line-breaking decisions made to avoid having a hyphenation at the end of a page.
 
 Alternatives to adjusting a paragraph length include adding extra space around a heading, an image or at the start of a chapter.
-
-#### Fractional Widows
-
-Another feature in Prince for Books are the "fractional widows": the [`widows`](css-props.md#prop-widows) property is allowed a value expressed as percentage, followed by the keyword `-prince-full`.
-
-```
-    p {
-      widows: 50% -prince-full;
-    }
-```
-This indicates that one widow line is accepted, as long as the line width is at least the given percentage value of the available page width, to avoid the worst case of having a widow line that is only one or two words long.
-
diff --git a/website/properties/properties.xml b/website/properties/properties.xml
@@ -4098,10 +4098,16 @@
 	determines the minimum number of lines that must be left at the bottom
 	of the first page or column.
 	</p>
-
     <p class="note">
     The initial value has been changed from <code>2</code> to <code>1</code>.
     </p>
+    <p>
+    In Prince for Books the property can take a second, optional, comma-separated
+    value expressed with the additional keyword <i>-prince-prefer</i>. It is
+    useful in case the <em>preference</em>, expressed with the additional
+    keyword, is a bigger amount than the hard <em>requirement</em> expressed
+    in the first value.
+    </p>
     </comments>
     <spec><a href="https://www.w3.org/TR/CSS2/page.html#break-inside">CSS 2.1</a></spec>
     <spec><a href="https://www.w3.org/TR/css-break-3/#widows-orphans">CSS Fragmentation Module Level 3</a></spec>
@@ -8180,28 +8186,26 @@ blockquote { margin: 1rem; -prince-resize-options: -1rem; }
 	the page or column at the end of the paragraph.
 	</p>
 
-    <p>
-    The percentage value only applies to <a href="/doc/prince-for-books/">Prince for Books</a>, and indicates
-    that one widow line is accepted, as long as the line width is at least the
-    given percentage value of the available page width, to avoid the worst case
-    of having a widow line that is only one or two words long.  It is followed
-    by the keyword <code>-prince-full</code>.  For more details
-    see <a href="/doc/prince-for-books/#fractional-widows">Fractional Widows</a>.
-    </p>
-
     <p class="note">
     The initial value has been changed from <code>2</code> to <code>1</code>.
     </p>
 
     <p>
-    For an amount not preceded by <code>-prince-prefer</code>,
-    lines will be brought forward from the previous page or column
-    if necessary to ensure the given number of lines are together.
+    The following additional features only apply to Prince for Books.
     </p>
 
     <p>
-    Values involving <code>-prince-prefer</code> are only accepted by
-    <a href="/doc/prince-for-books/">Prince for Books</a>.
+    Prince for Books also supports a percentage value followed by the keyword
+    <code>-prince-full</code>, which indicates that one widow line is accepted,
+    as long as the line width is at least the given percentage value of the
+    available page width, to avoid the worst case of having a widow line that
+    is only one or two words long.  For more details see
+    <a href="/doc/prince-for-books/#fractional-widows">Fractional Widows</a>.
+    </p>
+
+    <p>
+    In Prince for Books a value can be preceded by the keyword <code>-prince-prefer</code>,
+    which turns the requirement into a <em>preference</em>.
     An amount preceded by <code>-prince-prefer</code>
     is a request that Prince for Books will try to satisfy,
     but not at the cost of introducing an obvious gap at the end of the
@@ -8212,6 +8216,14 @@ blockquote { margin: 1rem; -prince-resize-options: -1rem; }
     or
     <code><property name="prince-resize-options"/></code>.
     </p>
+
+    <p>
+    The property additionally can take a second, optional, comma-separated
+    value expressed with the additional keyword <i>-prince-prefer</i>. It is
+    useful in case the <em>preference</em>, expressed with the additional
+    keyword, is a bigger amount than the hard <em>requirement</em> expressed
+    in the first value.
+    </p>
     </comments>
     <spec><a href="https://www.w3.org/TR/CSS2/page.html#break-inside">CSS 2.1</a></spec>
     <spec><a href="https://www.w3.org/TR/css-break-3/#widows-orphans">CSS Fragmentation Module Level 3</a></spec>