[css-page] Add page-orientation descriptor. Fixes #4491.

css-page-3/Overview.bs

@@ -1862,6 +1862,86 @@ Media Queries</h4>
 	In the example above, "A4" sheets are given a "3cm" page margin, and "letter"
 	sheets are given a "1in" page margin.
 
+<h4 id="page-orientation-prop">
+Rotating The Printed Page: the 'page-orientation' property</h4>
+
+	<pre class=descdef>
+	Name: page-orientation
+	For: @page
+	Value: upright | rotate-left | rotate-right
+	Initial: upright
+	Computed Value: as specified
+	</pre>
+
+	High-quality printing implementations
+	can handle pages of varying sizes and orientations,
+	so an author can choose the size of a page
+	according to what's best for that page's content.
+	For example,
+	they might use ''size: letter portrait;'' for most pages in a document,
+	but switch to ''size: letter landscape;''
+	to lay out a wide information table.
+
+	However, handling content flowing across pages of differing widths
+	is a relatively complex task,
+	and is not yet solved in many popular printing implementations
+	(notably, web browsers).
+	The ''page-orientation'' descriptor is intended to help such implementations,
+	allowing them to lay out pages in a single consistent size,
+	but change the orientation post-layout
+	in the output medium
+	(such as PDF),
+	so that pages which want to be displayed in a different orientation
+	can do so.
+
+	Its values are defined as:
+
+	<dl dfn-type=value dfn-for=page-orientation>
+		: <dfn>upright</dfn>
+		:: No special orientation is applied;
+			the page is laid out and formatted as normal.
+
+		: <dfn>rotate-left</dfn>
+		:: After the page has been laid out,
+			if the output medium supports rotation,
+			this value indicates that the page must be displayed
+			rotated a quarter turn to the left
+			(counter-clockwise)
+			of how it was laid out.
+
+		: <dfn>rotate-right</dfn>
+		:: Same as ''rotate-left'',
+			except the page must be displayed
+			rotated a quarter turn to the right
+			(clockwise)
+			of how it was laid out.
+	</dl>
+
+	Note: Margin boxes and other positional things
+	have no special interaction with this property;
+	they'll be laid out as normal in the unrotated page,
+	then rotated along with everything else.
+
+	<div class=note>
+		This property is intended as a stop-gap
+		for less-capable implementations,
+		allowing them to still print documents
+		with a mix of portrait and landscape orientations
+		before they have the ability
+		to flow content across differently-size pages.
+		It requires some awkward contortions to use,
+		such as specifying that a wide table containing only English
+		actually has a vertical 'writing-mode'
+		so it'll lay out "sideways",
+		but be rotated back to upright for readability
+		in the printed output.
+
+		There should be no need to use this property
+		in high-quality printing implementations;
+		instead, use '@page/size' to control ''portrait'' vs ''landscape'' orientation of a page.
+	</div>
+
+
 <h3 id="marks">
 Crop and Registration Marks: the 'marks' property</h3>