.. -*- mode: rst -*-

====================
Available formatters
====================

This page lists all builtin formatters.

Common options
==============

All formatters support these options:

`encoding`
    *New in Pygments 0.6.*

    If given, must be an encoding name (such as ``"utf-8"``). This will
    be used to convert the token strings (which are Unicode strings)
    to byte strings in the output (default: ``None``).
    It will also be written in an encoding declaration suitable for the
    document format if the `full` option is given (e.g. a ``meta
    content-type`` directive in HTML or an invocation of the `inputenc`
    package in LaTeX).

    If this is ``""`` or ``None``, Unicode strings will be written
    to the output file, which most file-like objects do not support.
    For example, `pygments.highlight()` will return a Unicode string if
    called with no `outfile` argument and a formatter that has `encoding`
    set to ``None`` because it uses a `StringIO.StringIO` object that
    supports Unicode arguments to `write()`. Using a regular file object
    wouldn't work.

`outencoding`
    *New in Pygments 0.7.*

    When using Pygments from the command line, any `encoding` option given is
    passed to the lexer and the formatter. This is sometimes not desirable,
    for example if you want to set the input encoding to ``"guess"``.
    Therefore, `outencoding` has been introduced which overrides `encoding`
    for the formatter if given.


The `HtmlFormatter` and `LatexFormatter` classes support these options:

`style`
    The style to use, can be a string or a Style subclass (default:
    ``'default'``).

`full`
    Tells the formatter to output a "full" document, i.e. a complete
    self-contained document (default: ``False``).

`title`
    If `full` is true, the title that should be used to caption the
    document (default: ``''``).

`linenos`
    If set to ``True``, output line numbers (default: ``False``).

`linenostart`
    The line number for the first line (default: ``1``).

`linenostep`
    If set to a number n > 1, only every nth line number is printed.


Formatter classes
=================

All these classes are importable from `pygments.formatters`.

[builtin_formatter_docs]