Document/docs/styles.txt - zetacomponents - Git at Google

 ====================
 PDF style directives
 ====================

 The PDF rendering of the document component supports a list of style
 directives to customize the output. Most style directives are equivalent to
 the CSS directives used for HTML and XML, but there are some additional
 directives and not all CSS directives are supported.

 The selectors, which can be used are documented in the tutorial__. Currently
 all values are required to be escaped inside quotes ("). The full grammar
 looks like::

     File       ::= Directive+
     Directive  ::= Address '{' Formatting* '}'
     Formatting ::= Name ':' '"' Value '"' ';'
     Name       ::= [A-Za-z-]+
     Value      ::= [^"]+

     Address     ::= Element ( Rule )*
     Rule        ::= '>'? Element
     Element     ::= ElementName ( '.' ClassName | '#' ElementId )

     ClassName   ::= [A-Za-z_-]+
     ElementName ::= XMLName | '*'
     ElementId   ::= XMLName

     XMLName references to http://www.w3.org/TR/REC-xml/#NT-Name

 __ /docs/tutorials/Document#styling-the-pdf

 .. contents:: Table of Contents
    :depth: 2

 All values, given as "measure" accept different units, but always default to
 millimeters (mm). Possible units are:

 - "mm", Millimeters, the default measure, if none is specified
 - "pt", Points, 72 points per inch
 - "px", Pixel, depends on the set resolution, by default also 72 points per
   inch
 - "in", Inch

 The unit "Points" is most common for font sizes, while millimeters or inches
 will probably more useful for page margins and paddings. You are free to
 choose any of them and can even combine different units in one tuple, like::

     para {
         // Top margin: 12 mm; Right margin: .1 inch; Bottom margin: 10 points,
         // Left margin: 1 pixel
         margin: "12 .1in 10pt 1px";
     }

 Font style
 ==========

 font-size: <measure>
 --------------------

 Defines the font size of the text. Most common unit is points, so it can be
 used like::

     para {
         font-size: "12pt";
     }

 font-family: <name>
 -------------------

 Defines the font used to render the text. Currently only the default PDF fonts
 are supported, which are:

 - ``serif``
 - ``sans-serif``
 - ``monospace``
 - ``Symbol``
 - ``ZapfDingbats``

 The option can be used like::

     para {
         font-family: "sans-serif";
     }

 font-weight: <weight>
 ---------------------

 The font weight defines whether a font is printed bold or normal. Unlike CSS
 for now only two possible values are supported: ``bold`` and ``normal``.
 Some drivers might support additional values, though. Usage::

     emphasis {
         font-weight: "bold";
     }

 font-style: <style>
 -------------------

 The font style property defines the style of the printed text. The possible
 values are ``normal`` and ``italic``. Usage::

     emphasis {
         font-style: "italic";
     }

 Text style
 ==========

 text-align: <align>
 -------------------

 The text alignment defines the alignment of text inside a text block. The
 supported values are:

 - ``left``
 - ``right``
 - ``center``
 - ``justified``

 It can be used like::

     para {
         text-align: "justified";
     }

 If you are using justified text alignment you should also configure a
 meaningful hyphenator__.

 __ /docs/tutorials/Document#hyphenating

 line-height: <float>
 --------------------

 The line height configures the space between two lines in the rendered output.
 A line height of 1.4 is generally considered most readable. You can configure
 a different line height, like::

     para {
         line-height: "1.2";
     }

 Text rendering
 ==============

 text-columns: <int>
 -------------------

 Number of text columns printed on one page. Obviously not available in common
 CSS. Usage::

     article {
         text-columns: "2";
     }

 text-column-spacing: <measure>
 ------------------------------

 Spacing between text columns, defined as a common measure. Usage::

     article {
         text-column-spacing: "10mm";
     }

 orphans: <int>
 --------------

 Orphans__ are the dangling lines at the end of a page. This settings
 configures how many dangling lines are considered orphans and therefore moved
 to the next page. Set to 0 for no line moving. Usage::

     article {
         orphans: "3";
     }

 __ http://en.wikipedia.org/wiki/Widows_and_orphans

 widows: <int>
 -------------

 Widows__ are the dangling lines at the beginning of a page from a paragraph of
 the page before. This setting configures how many lines a page should at least
 contain, so that the lines are not considered widows any more and no
 additional lines are required to be shifted from the page before. Usage::

     article {
         widows: "3";
     }

 __ http://en.wikipedia.org/wiki/Widows_and_orphans

 Page style
 ==========

 page-size: <size>
 -----------------

 Defines the size of pages. Uses a number of common page size identifiers as
 valid values for size definitions, which are: A0, A1, A2, A3, A4, A5, A6, A7,
 A8, A9, A10, B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, C0, C1, C2, C3, C4,
 C5, C6, C7, C8, C9, C10, RA0, RA1, RA2, RA3, RA4, SRA0, SRA1, SRA2, SRA3,
 SRA4, LETTER, LEGAL, EXECUTIVE, FOLIO. This setting applies only to the
 virtual ``page`` element, like::

     page {
         page-size: "A4";
     }

 page-orientation: <orientation>
 -------------------------------

 Defines the orientation of a page. There are only two valid values for this
 setting: ``landscape`` and ``portrait``. This setting applies only to the
 virtual ``page`` element, like::

     page {
         page-orientation: "portrait";
     }

 Block level styles
 ==================

 There are some style options, which apply to all block level elements, like
 paragraphs, titles, pages, images, etc.

 margin: <measure> [<measure> [<measure> [<measure> ]]]
 ------------------------------------------------------

 Margin defines the outer space of some element. Like in CSS the number of
 values defines the meaning of the values. The meanings are:

 1 value
     Used for top, right, bottom and left margin.
 2 values
     First value is used for top and bottom margin, second is used for left and
     right margin.
 3 values
     First value is used for top margin, second is used for left and right
     margin, the third is used for bottom margin.
 4 values
     First value defines the top, second the right, third the bottom, and
     fourth the left margin.

 Different units may be combined, like::

     para {
         // Top margin: 12 mm; Right margin: .1 inch; Bottom margin: 10 points,
         // Left margin: 1 pixel
         margin: "12 .1in 10pt 1px";
     }

 padding: <measure> [<measure> [<measure> [<measure> ]]]
 -------------------------------------------------------

 Padding defines additional inner space inside of the borders of an element.
 The values are defined just like for margins. Usage::

     para {
         padding: "12 1px";
     }
	====================
	PDF style directives
	====================

	The PDF rendering of the document component supports a list of style
	directives to customize the output. Most style directives are equivalent to
	the CSS directives used for HTML and XML, but there are some additional
	directives and not all CSS directives are supported.

	The selectors, which can be used are documented in the tutorial__. Currently
	all values are required to be escaped inside quotes ("). The full grammar
	looks like::

	File ::= Directive+
	Directive ::= Address '{' Formatting* '}'
	Formatting ::= Name ':' '"' Value '"' ';'
	Name ::= [A-Za-z-]+
	Value ::= [^"]+

	Address ::= Element ( Rule )*
	Rule ::= '>'? Element
	Element ::= ElementName ( '.' ClassName \| '#' ElementId )

	ClassName ::= [A-Za-z_-]+
	ElementName ::= XMLName \| '*'
	ElementId ::= XMLName

	XMLName references to http://www.w3.org/TR/REC-xml/#NT-Name

	__ /docs/tutorials/Document#styling-the-pdf

	.. contents:: Table of Contents
	:depth: 2

	All values, given as "measure" accept different units, but always default to
	millimeters (mm). Possible units are:

	- "mm", Millimeters, the default measure, if none is specified
	- "pt", Points, 72 points per inch
	- "px", Pixel, depends on the set resolution, by default also 72 points per
	inch
	- "in", Inch

	The unit "Points" is most common for font sizes, while millimeters or inches
	will probably more useful for page margins and paddings. You are free to
	choose any of them and can even combine different units in one tuple, like::

	para {
	// Top margin: 12 mm; Right margin: .1 inch; Bottom margin: 10 points,
	// Left margin: 1 pixel
	margin: "12 .1in 10pt 1px";
	}

	Font style
	==========

	font-size: <measure>
	--------------------

	Defines the font size of the text. Most common unit is points, so it can be
	used like::

	para {
	font-size: "12pt";
	}

	font-family: <name>
	-------------------

	Defines the font used to render the text. Currently only the default PDF fonts
	are supported, which are:

	- ``serif``
	- ``sans-serif``
	- ``monospace``
	- ``Symbol``
	- ``ZapfDingbats``

	The option can be used like::

	para {
	font-family: "sans-serif";
	}

	font-weight: <weight>
	---------------------

	The font weight defines whether a font is printed bold or normal. Unlike CSS
	for now only two possible values are supported: ``bold`` and ``normal``.
	Some drivers might support additional values, though. Usage::

	emphasis {
	font-weight: "bold";
	}

	font-style: <style>
	-------------------

	The font style property defines the style of the printed text. The possible
	values are ``normal`` and ``italic``. Usage::

	emphasis {
	font-style: "italic";
	}

	Text style
	==========

	text-align: <align>
	-------------------

	The text alignment defines the alignment of text inside a text block. The
	supported values are:

	- ``left``
	- ``right``
	- ``center``
	- ``justified``

	It can be used like::

	para {
	text-align: "justified";
	}

	If you are using justified text alignment you should also configure a
	meaningful hyphenator__.

	__ /docs/tutorials/Document#hyphenating

	line-height: <float>
	--------------------

	The line height configures the space between two lines in the rendered output.
	A line height of 1.4 is generally considered most readable. You can configure
	a different line height, like::

	para {
	line-height: "1.2";
	}

	Text rendering
	==============

	text-columns: <int>
	-------------------

	Number of text columns printed on one page. Obviously not available in common
	CSS. Usage::

	article {
	text-columns: "2";
	}

	text-column-spacing: <measure>
	------------------------------

	Spacing between text columns, defined as a common measure. Usage::

	article {
	text-column-spacing: "10mm";
	}

	orphans: <int>
	--------------

	Orphans__ are the dangling lines at the end of a page. This settings
	configures how many dangling lines are considered orphans and therefore moved
	to the next page. Set to 0 for no line moving. Usage::

	article {
	orphans: "3";
	}

	__ http://en.wikipedia.org/wiki/Widows_and_orphans

	widows: <int>
	-------------

	Widows__ are the dangling lines at the beginning of a page from a paragraph of
	the page before. This setting configures how many lines a page should at least
	contain, so that the lines are not considered widows any more and no
	additional lines are required to be shifted from the page before. Usage::

	article {
	widows: "3";
	}

	__ http://en.wikipedia.org/wiki/Widows_and_orphans

	Page style
	==========

	page-size: <size>
	-----------------

	Defines the size of pages. Uses a number of common page size identifiers as
	valid values for size definitions, which are: A0, A1, A2, A3, A4, A5, A6, A7,
	A8, A9, A10, B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, C0, C1, C2, C3, C4,
	C5, C6, C7, C8, C9, C10, RA0, RA1, RA2, RA3, RA4, SRA0, SRA1, SRA2, SRA3,
	SRA4, LETTER, LEGAL, EXECUTIVE, FOLIO. This setting applies only to the
	virtual ``page`` element, like::

	page {
	page-size: "A4";
	}

	page-orientation: <orientation>
	-------------------------------

	Defines the orientation of a page. There are only two valid values for this
	setting: ``landscape`` and ``portrait``. This setting applies only to the
	virtual ``page`` element, like::

	page {
	page-orientation: "portrait";
	}

	Block level styles
	==================

	There are some style options, which apply to all block level elements, like
	paragraphs, titles, pages, images, etc.

	margin: <measure> [<measure> [<measure> [<measure> ]]]
	------------------------------------------------------

	Margin defines the outer space of some element. Like in CSS the number of
	values defines the meaning of the values. The meanings are:

	1 value
	Used for top, right, bottom and left margin.
	2 values
	First value is used for top and bottom margin, second is used for left and
	right margin.
	3 values
	First value is used for top margin, second is used for left and right
	margin, the third is used for bottom margin.
	4 values
	First value defines the top, second the right, third the bottom, and
	fourth the left margin.

	Different units may be combined, like::

	para {
	// Top margin: 12 mm; Right margin: .1 inch; Bottom margin: 10 points,
	// Left margin: 1 pixel
	margin: "12 .1in 10pt 1px";
	}

	padding: <measure> [<measure> [<measure> [<measure> ]]]
	-------------------------------------------------------

	Padding defines additional inner space inside of the borders of an element.
	The values are defined just like for margins. Usage::

	para {
	padding: "12 1px";
	}