====================
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";
    }