manual: remove dos endlines

--HG--
branch : feature-sphinx

13 files changed, 1102 insertions, 1102 deletions

diff --git a/docs/manual/canvascache.rst b/docs/manual/canvascache.rst
index 4304d31..5856874 100644
--- a/docs/manual/canvascache.rst
+++ b/docs/manual/canvascache.rst
@@ -1,58 +1,58 @@
-.. _canvas-cache:

-

-****************

-  Canvas Cache  

-****************

-

-In an Urwid application each time the screen is redrawn typically only part of

-the screen actually needs to be updated. A canvas cache is used to store

-visible, unchanged canvases so that not all of the visible widgets need to be

-rendered for each update.

-

-The :class:`~urwid.widget.Widget` base class uses some metaclass magic to

-capture the canvas objects returned when :meth:`render` is called and return

-them the next time :meth:`render` is called again with the same parameters. The

-:meth:`_invalidate` method is provided as a way to remove cached widgets so

-that changes to the widget are visible the next time the screen is redrawn.

-

-Similar metaclass magic is used for flow widgets' :meth:`rows` method. If a

-canvas for that widget with the same parameters is cached then the rows of that

-canvas are returned instead of calling the widget's actual :meth:`rows` method.

-

-Composite Canvases

-==================

-

-When container and decoration widgets are rendered, they collect the canvases

-returned by their children and arrange them into a composite canvas. Composite

-canvases may are nested to form a tree with the topmost widget's :meth:`render`

-method returning the root of the tree. That canvas is sent to the display

-module to be rendered on the screen.

-

-Composite canvases reference the content and layout from their children,

-reducing the number of copies required to build them. When a canvas is removed

-from the cache by a call to :meth:`_invalidate` all the direct parents of that

-canvas are removed from the cache as well, forcing those widgets to be re-drawn

-on the next screen update. This cascade-removal happens only once per update

-(the canvas is then no longer in the cache) so batched changes to visible

-widgets may be made efficiently. This is important when a user's input gets

-ahead of the screen updating -- Urwid handles all the pending input first then

-updates the screen with the final result, instead of falling further and

-further behind.

-

-Cache Lifetime

-==============

-

-The canvases "stored" in the canvas cache are actually weak references to the

-canvases. The canvases must have a real reference somewhere for the cache to

-function properly. Urwid's display modules store the currently displayed

-topmost canvas for this reason. All canvases that are visible on the screen

-will remain in the cache, and others will be garbage collected.

-

-Future Work

-===========

-

-A updating method that invalidates regions of the display without redrawing

-parent widgets would be more efficient for the common case of a single change

-on the screen that does not affect the screen layout. Send an email to the

-mailing list if you're interested in helping with this or other display

-optimizations.

+.. _canvas-cache:
+
+****************
+  Canvas Cache  
+****************
+
+In an Urwid application each time the screen is redrawn typically only part of
+the screen actually needs to be updated. A canvas cache is used to store
+visible, unchanged canvases so that not all of the visible widgets need to be
+rendered for each update.
+
+The :class:`~urwid.widget.Widget` base class uses some metaclass magic to
+capture the canvas objects returned when :meth:`render` is called and return
+them the next time :meth:`render` is called again with the same parameters. The
+:meth:`_invalidate` method is provided as a way to remove cached widgets so
+that changes to the widget are visible the next time the screen is redrawn.
+
+Similar metaclass magic is used for flow widgets' :meth:`rows` method. If a
+canvas for that widget with the same parameters is cached then the rows of that
+canvas are returned instead of calling the widget's actual :meth:`rows` method.
+
+Composite Canvases
+==================
+
+When container and decoration widgets are rendered, they collect the canvases
+returned by their children and arrange them into a composite canvas. Composite
+canvases may are nested to form a tree with the topmost widget's :meth:`render`
+method returning the root of the tree. That canvas is sent to the display
+module to be rendered on the screen.
+
+Composite canvases reference the content and layout from their children,
+reducing the number of copies required to build them. When a canvas is removed
+from the cache by a call to :meth:`_invalidate` all the direct parents of that
+canvas are removed from the cache as well, forcing those widgets to be re-drawn
+on the next screen update. This cascade-removal happens only once per update
+(the canvas is then no longer in the cache) so batched changes to visible
+widgets may be made efficiently. This is important when a user's input gets
+ahead of the screen updating -- Urwid handles all the pending input first then
+updates the screen with the final result, instead of falling further and
+further behind.
+
+Cache Lifetime
+==============
+
+The canvases "stored" in the canvas cache are actually weak references to the
+canvases. The canvases must have a real reference somewhere for the cache to
+function properly. Urwid's display modules store the currently displayed
+topmost canvas for this reason. All canvases that are visible on the screen
+will remain in the cache, and others will be garbage collected.
+
+Future Work
+===========
+
+A updating method that invalidates regions of the display without redrawing
+parent widgets would be more efficient for the common case of a single change
+on the screen that does not affect the screen layout. Send an email to the
+mailing list if you're interested in helping with this or other display
+optimizations.
diff --git a/docs/manual/displayattributes.rst b/docs/manual/displayattributes.rst
index 3076639..77f6fc7 100644
--- a/docs/manual/displayattributes.rst
+++ b/docs/manual/displayattributes.rst
@@ -1,139 +1,139 @@
-.. _display-attributes:

-

-**********************

-  Display Attributes  

-**********************

-

-Urwid supports a number of common display attributes.

-

-=============================== ================= ===== ============= =====================

-Attribute Support by Terminal   xterm, gnome-term rxvt  linux console others

-=============================== ================= ===== ============= =====================

-16 standard foreground colors   YES               YES   YES           very widely supported

-8 standard background colors    YES               YES   YES           very widely supported

-default foreground/background   YES               YES   YES           widely supported

-bold, underline, standout       YES               YES   standout      widely supported

-"bright" background colors      YES               urxvt               some support

-256-color foreground/background YES                                   some support

-88-color foreground/background  w/palette setting urxvt               limited support

-RGB palette setting             YES                                   limited support

-=============================== ================= ===== ============= =====================

-

-You are encouraged to provide support for as many of these as you like, while

-allowing your interface to degrade gracefully by using display modules' palette

-modes and providing command line arguments or other interfaces to switch modes.

-

-When setting up a palette with :class:`~urwid.main_loop.MainLoop` (or directly

-on your screen instance), you may specify attributes for 16-color, monochrome

-and high color modes. You can then switch between these modes with

-:meth:`screen.set_terminal_properties`, where :attr:`screen` is a

-:class:`~urwid.main_loop.MainLoop` attribute or your own screen instance.

-

-`register_palette reference <http://excess.org/urwid/reference.html#Screen-register_palette>`_

-

-`set_terminal_properties reference <http://excess.org/urwid/reference.html#Screen-set_terminal_properties>`_

-

-See also: RecommendedPalette.

-

-16 Standard Foreground Colors

-=============================

-

-'black', 'dark red', 'dark green', 'brown', 'dark blue', 'dark magenta', 'dark

-cyan', 'light gray', 'dark gray', 'light red', 'light green', 'yellow', 'light

-blue', 'light magenta', 'light cyan', 'white'

-

-8 Standard Background Colors

-============================

-

-'black', 'dark red', 'dark green', 'brown', 'dark blue', 'dark magenta', 'dark

-cyan', 'light gray'

-

-Default Foreground/Background

-=============================

-

-``'default'`` may be specified as a foreground or background to use a

-terminal's default color. For terminals with transparent backgrounds

-``'default'`` is the only way to show the transparent background. There is no

-way to tell what the default colors are, so it is best to use default

-foregrounds and backgrounds together (not with other colors) to ensure good

-contrast.

-

-Bold, Underline, Standout

-=========================

-

-These settings may be tagged on to foreground colors using commas, eg: ``'light

-gray,underline,bold'``

-

-For monochrome mode combinations of these are the only values that may be used.

-

-Many terminals will turn foreground colors into their bright versions when you

-use bold, eg: ``'dark blue,bold'`` might look the same as ``'light blue'``.

-Some terminals also will display bright colors in a bold font even if you don't

-specify bold. To inhibit this you can try setting ``bright_is_bold=False`` with

-:func:`set_terminal_properties`, but it is not always supported.

-

-`set_terminal_properties reference <http://excess.org/urwid/reference.html#Screen-set_terminal_properties>`_

-

-Standout is usually displayed as the foreground and background colors reversed.

-

-"Bright" Background Colors

-==========================

-

-'dark gray', 'light red', 'light green', 'yellow', 'light blue', 'light

-magenta', 'light cyan', 'white'

-

-Terminal support for bright background colors is spotty, and they generally

-should be avoided. If you are in a high-color mode you might have better luck

-using the high-color versions 'h8', 'h9', 'h10', ..., 'h15'.

-

-.. _high-colors:

-

-256-Color Foreground/Background

-===============================

-

-In 256-color mode you have the 16 basic colors, a 6x6x6 color cube and a gray

-scale with 24 entries (white and black not included).

-

-The color cube is weighted towards the brighter colors, with RGB points at 0,

-0x5f, 0x87, 0xaf, 0xd7 and 0xff. The hex characters '0', '6', '8', 'a', 'd' and

-'f' are used as short-forms for these values.

-

-High colors may be specified by their index 'h0', ..., 'h255' or with the

-shortcuts for the color cube `'#000'`, `'#006'`, `'#008'`, ..., `'#fff'` or

-gray scale entries 'g0', 'g3', 'g7', ... 'g100'.

-

-See also the palette_test.py example program

-

-.. todo: add link

-

-88-Color Foreground/Background

-==============================

-

-In 88-color mode you have the 16 basic colors, a 4x4x4 color cube and a gray

-scale with 8 entries (white and black not included).

-

-The color cube is weighted towards the brighter colors, with RGB points at 0,

-0x8b, 0xcd, and 0xff. The hex characters '0', '8', 'c' and 'f' are used as

-short-forms for these values.

-

-High colors may be specified by their index 'h0', ..., 'h87' or with the

-shortcuts for the color cube `'#000'`, `'#008'`, `'#00c'`, ..., `'#fff'` or

-gray scale entries 'g0', 'g19', 'g35', ... 'g100'.

-

-See also the palette_test.py example program

-

-.. todo: add link

-

-RGB Palette Setting

-===================

-

-A few terminals have the ability to customize the terminal palette's RGB

-values. There is no automatic way to tell if this is supported by a user's

-terminal, so this feature shouldn't be relied on.

-

-It is used (via the reset_default_terminal_palette method) in the

-palette_test.py example program when switching modes.

-

-`modify_terminal_palette reference <http://excess.org/urwid/reference.html#Screen-modify_terminal_palette>`_

-

-`reset_default_terminal_palette reference <http://excess.org/urwid/reference.html#Screen-reset_default_terminal_palette>`_

+.. _display-attributes:
+
+**********************
+  Display Attributes  
+**********************
+
+Urwid supports a number of common display attributes.
+
+=============================== ================= ===== ============= =====================
+Attribute Support by Terminal   xterm, gnome-term rxvt  linux console others
+=============================== ================= ===== ============= =====================
+16 standard foreground colors   YES               YES   YES           very widely supported
+8 standard background colors    YES               YES   YES           very widely supported
+default foreground/background   YES               YES   YES           widely supported
+bold, underline, standout       YES               YES   standout      widely supported
+"bright" background colors      YES               urxvt               some support
+256-color foreground/background YES                                   some support
+88-color foreground/background  w/palette setting urxvt               limited support
+RGB palette setting             YES                                   limited support
+=============================== ================= ===== ============= =====================
+
+You are encouraged to provide support for as many of these as you like, while
+allowing your interface to degrade gracefully by using display modules' palette
+modes and providing command line arguments or other interfaces to switch modes.
+
+When setting up a palette with :class:`~urwid.main_loop.MainLoop` (or directly
+on your screen instance), you may specify attributes for 16-color, monochrome
+and high color modes. You can then switch between these modes with
+:meth:`screen.set_terminal_properties`, where :attr:`screen` is a
+:class:`~urwid.main_loop.MainLoop` attribute or your own screen instance.
+
+`register_palette reference <http://excess.org/urwid/reference.html#Screen-register_palette>`_
+
+`set_terminal_properties reference <http://excess.org/urwid/reference.html#Screen-set_terminal_properties>`_
+
+See also: RecommendedPalette.
+
+16 Standard Foreground Colors
+=============================
+
+'black', 'dark red', 'dark green', 'brown', 'dark blue', 'dark magenta', 'dark
+cyan', 'light gray', 'dark gray', 'light red', 'light green', 'yellow', 'light
+blue', 'light magenta', 'light cyan', 'white'
+
+8 Standard Background Colors
+============================
+
+'black', 'dark red', 'dark green', 'brown', 'dark blue', 'dark magenta', 'dark
+cyan', 'light gray'
+
+Default Foreground/Background
+=============================
+
+``'default'`` may be specified as a foreground or background to use a
+terminal's default color. For terminals with transparent backgrounds
+``'default'`` is the only way to show the transparent background. There is no
+way to tell what the default colors are, so it is best to use default
+foregrounds and backgrounds together (not with other colors) to ensure good
+contrast.
+
+Bold, Underline, Standout
+=========================
+
+These settings may be tagged on to foreground colors using commas, eg: ``'light
+gray,underline,bold'``
+
+For monochrome mode combinations of these are the only values that may be used.
+
+Many terminals will turn foreground colors into their bright versions when you
+use bold, eg: ``'dark blue,bold'`` might look the same as ``'light blue'``.
+Some terminals also will display bright colors in a bold font even if you don't
+specify bold. To inhibit this you can try setting ``bright_is_bold=False`` with
+:func:`set_terminal_properties`, but it is not always supported.
+
+`set_terminal_properties reference <http://excess.org/urwid/reference.html#Screen-set_terminal_properties>`_
+
+Standout is usually displayed as the foreground and background colors reversed.
+
+"Bright" Background Colors
+==========================
+
+'dark gray', 'light red', 'light green', 'yellow', 'light blue', 'light
+magenta', 'light cyan', 'white'
+
+Terminal support for bright background colors is spotty, and they generally
+should be avoided. If you are in a high-color mode you might have better luck
+using the high-color versions 'h8', 'h9', 'h10', ..., 'h15'.
+
+.. _high-colors:
+
+256-Color Foreground/Background
+===============================
+
+In 256-color mode you have the 16 basic colors, a 6x6x6 color cube and a gray
+scale with 24 entries (white and black not included).
+
+The color cube is weighted towards the brighter colors, with RGB points at 0,
+0x5f, 0x87, 0xaf, 0xd7 and 0xff. The hex characters '0', '6', '8', 'a', 'd' and
+'f' are used as short-forms for these values.
+
+High colors may be specified by their index 'h0', ..., 'h255' or with the
+shortcuts for the color cube `'#000'`, `'#006'`, `'#008'`, ..., `'#fff'` or
+gray scale entries 'g0', 'g3', 'g7', ... 'g100'.
+
+See also the palette_test.py example program
+
+.. todo: add link
+
+88-Color Foreground/Background
+==============================
+
+In 88-color mode you have the 16 basic colors, a 4x4x4 color cube and a gray
+scale with 8 entries (white and black not included).
+
+The color cube is weighted towards the brighter colors, with RGB points at 0,
+0x8b, 0xcd, and 0xff. The hex characters '0', '8', 'c' and 'f' are used as
+short-forms for these values.
+
+High colors may be specified by their index 'h0', ..., 'h87' or with the
+shortcuts for the color cube `'#000'`, `'#008'`, `'#00c'`, ..., `'#fff'` or
+gray scale entries 'g0', 'g19', 'g35', ... 'g100'.
+
+See also the palette_test.py example program
+
+.. todo: add link
+
+RGB Palette Setting
+===================
+
+A few terminals have the ability to customize the terminal palette's RGB
+values. There is no automatic way to tell if this is supported by a user's
+terminal, so this feature shouldn't be relied on.
+
+It is used (via the reset_default_terminal_palette method) in the
+palette_test.py example program when switching modes.
+
+`modify_terminal_palette reference <http://excess.org/urwid/reference.html#Screen-modify_terminal_palette>`_
+
+`reset_default_terminal_palette reference <http://excess.org/urwid/reference.html#Screen-reset_default_terminal_palette>`_
diff --git a/docs/manual/displaymodules.rst b/docs/manual/displaymodules.rst
index 4b7051b..0215c14 100644
--- a/docs/manual/displaymodules.rst
+++ b/docs/manual/displaymodules.rst
@@ -1,143 +1,143 @@
-.. _display-modules:

-

-*************************

-  Urwid Display Modules  

-*************************

-

-Introduction

-============

-

-Urwid's display modules provide a layer of abstraction for drawing to the

-screen and reading user input. The display module you choose will depend on

-how you plan to use Urwid.

-

-.. image:: images/display_modules.png

-

-Typically you will select a display module by passing it to your

-:class:`~urwid.main_loop.MainLoop` constructor, eg:

-

-::

-

-    loop = MainLoop(widget, ..., screen=urwid.curses_display.Screen())

-

-If you don't specify a display module, the default main loop will use

-:class:`urwid.raw_display.Screen` by default

-

-::

-

-    # These are the same

-    loop = MainLoop(widget, ...)

-    loop = MainLoop(widget, ..., screen=urwid.raw_display.Screen())

-

-``raw_display`` and ``curses_display``

-======================================

-

-Urwid has two display modules for displaying to terminals or the console.

-

-The :mod:`urwid.raw_display` module is a pure-python display module with no

-external dependencies. It sends and interprets terminal escape sequences

-directly. This is the default display module used by

-:class:`~urwid.main_loop.MainLoop`.

-

-.. TODO: add a link to some ncurses resources?

-

-The :mod:`urwid.curses_display` module uses the curses or ncurses library

-provided by the operating system. The library does some optimization of screen

-updates and uses termcap to adjust to the user's terminal.

-

-The (n)curses library will disable colors if it detects a monochrome terminal,

-so a separate set of attributes should be given for monochrome mode when

-registering a palette with :mod:`urwid.curses_display`. High colors will not be

-used by the :mod:`urwid.curses_dislpay` module. See :ref:`setting-a-palette`

-below.

-

-This table summarizes the differences between the two modules:

-

-============================== =========== ==============

-..                             raw_display curses_display

-============================== =========== ==============

-optimized C code               no          YES

-compatible with any terminal   no          YES [1]_

-UTF-8 support                  YES         YES [2]_

-bright foreground without bold YES [3]_    no

-88- or 256-color support       YES         no

-mouse dragging support         YES         no

-external event loop support    YES         no

-============================== =========== ==============

-

-.. [1] if the termcap entry exists and TERM environment variable is set

-       correctly

-.. [2] if python is linked against the wide version of ncurses

-.. [3] when using xterm or gnome-terminal

-

-.. TODO: what to do with these references?

-

-.. :ref:`raw_display.Screen <raw_display.Screen>`

-

-..  :ref:`curses_display.Screen <curses_display.Screen>`

-

-AJAX-based Web Display Module ``web_display``

-=============================================

-

-The :mod:`urwid.web_display` module lets you run your application as a CGI

-script under Apache instead of running it in a terminal.

-

-This module is a proof of concept. There are security and responsiveness issues

-that need to be resolved before this module is recommended for production use.

-

-The tour.py_ and calc.py_ example programs demonstrate use of this module.

-

-.. _tour.py: http://excess.org/urwid/browser/tour.py

-.. _calc.py: http://excess.org/urwid/browser/calc.py

-

-.. TODO:

-

-`live demo of web_display module <http://live.excess.org/>`_

-

-`web_display.Screen reference <http://excess.org/urwid/reference.html#web_display.Screen>`_

-

-Screenshot Display Module ``html_fragment``

-===========================================

-

-Screenshots of Urwid interfaces can be rendered in plain HTML. The

-:mod:`html_fragment` display module lets you do this by simulating user input

-and capturing the screen as fragments of HTML each time :func:`draw_screen` is

-called.

-

-These fragments may be included in HTML documents. They will be rendered

-properly by any browser that uses a monospaced font for text that appears in

-``<pre>`` tags. HTML screenshots have text that is searchable and selectable in

-a web browser, and they will shrink and grow when a user changes their

-browser's text size.

-

-The `example screenshots`_ are generated with this display module.

-

-.. _`example screenshots`: http://excess.org/urwid/examples.html

-

-`html_fragment.Screen reference <http://excess.org/urwid/reference.html#html_fragment.Screen>`_

-

-

-.. _setting-a-palette:

-

-Setting a Palette

-=================

-

-The :class:`~urwid.main_loop.MainLoop` constructor takes a ``palette`` parameter that it passes

-to the :meth:`register_palette` method of your display module.

-

-A palette is a list of palette entry names, called "attributes" and foreground

-and background settings. Display modules may be run in monochrome, normal or

-high color modes and you can set different foregrounds and backgrounds for each

-mode as part of your palette. eg:

-

-::

-

-    loop = MainLoop(widget, palette=[

-        ('headings', 'white,underline', 'black', 'bold,underline'), # bold text in monochrome mode

-        ('body_text', 'dark cyan', 'light gray'),

-        ('buttons', 'yellow', 'dark green', 'standout'),

-        ('section_text', 'body_text'), # alias to body_text

-        ])

-

-The :ref:`display-attributes` section of this manual describes all the options

-available.

+.. _display-modules:
+
+*************************
+  Urwid Display Modules  
+*************************
+
+Introduction
+============
+
+Urwid's display modules provide a layer of abstraction for drawing to the
+screen and reading user input. The display module you choose will depend on
+how you plan to use Urwid.
+
+.. image:: images/display_modules.png
+
+Typically you will select a display module by passing it to your
+:class:`~urwid.main_loop.MainLoop` constructor, eg:
+
+::
+
+    loop = MainLoop(widget, ..., screen=urwid.curses_display.Screen())
+
+If you don't specify a display module, the default main loop will use
+:class:`urwid.raw_display.Screen` by default
+
+::
+
+    # These are the same
+    loop = MainLoop(widget, ...)
+    loop = MainLoop(widget, ..., screen=urwid.raw_display.Screen())
+
+``raw_display`` and ``curses_display``
+======================================
+
+Urwid has two display modules for displaying to terminals or the console.
+
+The :mod:`urwid.raw_display` module is a pure-python display module with no
+external dependencies. It sends and interprets terminal escape sequences
+directly. This is the default display module used by
+:class:`~urwid.main_loop.MainLoop`.
+
+.. TODO: add a link to some ncurses resources?
+
+The :mod:`urwid.curses_display` module uses the curses or ncurses library
+provided by the operating system. The library does some optimization of screen
+updates and uses termcap to adjust to the user's terminal.
+
+The (n)curses library will disable colors if it detects a monochrome terminal,
+so a separate set of attributes should be given for monochrome mode when
+registering a palette with :mod:`urwid.curses_display`. High colors will not be
+used by the :mod:`urwid.curses_dislpay` module. See :ref:`setting-a-palette`
+below.
+
+This table summarizes the differences between the two modules:
+
+============================== =========== ==============
+..                             raw_display curses_display
+============================== =========== ==============
+optimized C code               no          YES
+compatible with any terminal   no          YES [1]_
+UTF-8 support                  YES         YES [2]_
+bright foreground without bold YES [3]_    no
+88- or 256-color support       YES         no
+mouse dragging support         YES         no
+external event loop support    YES         no
+============================== =========== ==============
+
+.. [1] if the termcap entry exists and TERM environment variable is set
+       correctly
+.. [2] if python is linked against the wide version of ncurses
+.. [3] when using xterm or gnome-terminal
+
+.. TODO: what to do with these references?
+
+.. :ref:`raw_display.Screen <raw_display.Screen>`
+
+..  :ref:`curses_display.Screen <curses_display.Screen>`
+
+AJAX-based Web Display Module ``web_display``
+=============================================
+
+The :mod:`urwid.web_display` module lets you run your application as a CGI
+script under Apache instead of running it in a terminal.
+
+This module is a proof of concept. There are security and responsiveness issues
+that need to be resolved before this module is recommended for production use.
+
+The tour.py_ and calc.py_ example programs demonstrate use of this module.
+
+.. _tour.py: http://excess.org/urwid/browser/tour.py
+.. _calc.py: http://excess.org/urwid/browser/calc.py
+
+.. TODO:
+
+`live demo of web_display module <http://live.excess.org/>`_
+
+`web_display.Screen reference <http://excess.org/urwid/reference.html#web_display.Screen>`_
+
+Screenshot Display Module ``html_fragment``
+===========================================
+
+Screenshots of Urwid interfaces can be rendered in plain HTML. The
+:mod:`html_fragment` display module lets you do this by simulating user input
+and capturing the screen as fragments of HTML each time :func:`draw_screen` is
+called.
+
+These fragments may be included in HTML documents. They will be rendered
+properly by any browser that uses a monospaced font for text that appears in
+``<pre>`` tags. HTML screenshots have text that is searchable and selectable in
+a web browser, and they will shrink and grow when a user changes their
+browser's text size.
+
+The `example screenshots`_ are generated with this display module.
+
+.. _`example screenshots`: http://excess.org/urwid/examples.html
+
+`html_fragment.Screen reference <http://excess.org/urwid/reference.html#html_fragment.Screen>`_
+
+
+.. _setting-a-palette:
+
+Setting a Palette
+=================
+
+The :class:`~urwid.main_loop.MainLoop` constructor takes a ``palette`` parameter that it passes
+to the :meth:`register_palette` method of your display module.
+
+A palette is a list of palette entry names, called "attributes" and foreground
+and background settings. Display modules may be run in monochrome, normal or
+high color modes and you can set different foregrounds and backgrounds for each
+mode as part of your palette. eg:
+
+::
+
+    loop = MainLoop(widget, palette=[
+        ('headings', 'white,underline', 'black', 'bold,underline'), # bold text in monochrome mode
+        ('body_text', 'dark cyan', 'light gray'),
+        ('buttons', 'yellow', 'dark green', 'standout'),
+        ('section_text', 'body_text'), # alias to body_text
+        ])
+
+The :ref:`display-attributes` section of this manual describes all the options
+available.
diff --git a/docs/manual/eventloops.rst b/docs/manual/eventloops.rst
index f684c0f..ebbec2f 100644
--- a/docs/manual/eventloops.rst
+++ b/docs/manual/eventloops.rst
@@ -1,62 +1,62 @@
-.. _event-loops:

-

-***************

-  Event Loops  

-***************

-

-Urwid's event loop classes handle waiting for things for the

-:class:`~urwid.main_loop.MainLoop`. The different event loops allow you to

-integrate with Twisted_ or Glib_ libraries, or use a simple *select*-based

-loop. Event loop classes abstract the particulars of waiting for input and

-calling functions as a result of timeouts.

-

-You will typically only have a single event loop in your application, even if

-you have more than one :class:`~urwid.main_loop.MainLoop` running.

-

-You can add your own files to watch to your event loop, with the

-:meth:`watch_file` method. Using this interface gives you the special handling

-of :exc:`ExitMainLoop` and other exceptions when using Glib_ or Twisted_.

-

-.. _Twisted: http://twistedmatrix.com/trac/

-.. _Glib: http://developer.gnome.org/glib/stable/

-

-``SelectEventLoop``

-===================

-

-This event loop is based on ``select.select()``. This is the default event loop

-created if none is passed to :class:`~urwid.main_loop.MainLoop`.

-

-::

-

-    # same as urwid.MainLoop(widget, event_loop=urwid.SelectEventLoop())

-    loop = urwid.MainLoop(widget)

-

-`SelectEventLoop reference <http://excess.org/urwid/reference.html#SelectEventLoop>`_

-

-``TwistedEventLoop``

-====================

-

-This event loop uses Twisted's reactor. It has been set up to emulate

-:class:`~urwid.main_loop.SelectEventLoop`'s behaviour and will start the

-reactor and stop it on an error. This is not the standard way of using

-Twisted's reactor, so you may need to modify this behaviour for your

-application.

-

-::

-

-    loop = urwid.MainLoop(widget, event_loop=urwid.TwistedEventLoop())

-

-`TwistedEventLoop reference <http://excess.org/urwid/reference.html#TwistedEventLoop>`_

-

-``GLibEventLoop``

-=================

-

-This event loop uses GLib's event loop. This is useful if you are building an

-application that depends on DBus events, but don't want to base your

-application on Twisted.

-

-::

-

-    loop = urwid.MainLoop(widget, event_loop=urwid.GLibEventLoop())

-

-`GLibEventLoop reference <http://excess.org/urwid/reference.html#GLibEventLoop>`_

+.. _event-loops:
+
+***************
+  Event Loops  
+***************
+
+Urwid's event loop classes handle waiting for things for the
+:class:`~urwid.main_loop.MainLoop`. The different event loops allow you to
+integrate with Twisted_ or Glib_ libraries, or use a simple *select*-based
+loop. Event loop classes abstract the particulars of waiting for input and
+calling functions as a result of timeouts.
+
+You will typically only have a single event loop in your application, even if
+you have more than one :class:`~urwid.main_loop.MainLoop` running.
+
+You can add your own files to watch to your event loop, with the
+:meth:`watch_file` method. Using this interface gives you the special handling
+of :exc:`ExitMainLoop` and other exceptions when using Glib_ or Twisted_.
+
+.. _Twisted: http://twistedmatrix.com/trac/
+.. _Glib: http://developer.gnome.org/glib/stable/
+
+``SelectEventLoop``
+===================
+
+This event loop is based on ``select.select()``. This is the default event loop
+created if none is passed to :class:`~urwid.main_loop.MainLoop`.
+
+::
+
+    # same as urwid.MainLoop(widget, event_loop=urwid.SelectEventLoop())
+    loop = urwid.MainLoop(widget)
+
+`SelectEventLoop reference <http://excess.org/urwid/reference.html#SelectEventLoop>`_
+
+``TwistedEventLoop``
+====================
+
+This event loop uses Twisted's reactor. It has been set up to emulate
+:class:`~urwid.main_loop.SelectEventLoop`'s behaviour and will start the
+reactor and stop it on an error. This is not the standard way of using
+Twisted's reactor, so you may need to modify this behaviour for your
+application.
+
+::
+
+    loop = urwid.MainLoop(widget, event_loop=urwid.TwistedEventLoop())
+
+`TwistedEventLoop reference <http://excess.org/urwid/reference.html#TwistedEventLoop>`_
+
+``GLibEventLoop``
+=================
+
+This event loop uses GLib's event loop. This is useful if you are building an
+application that depends on DBus events, but don't want to base your
+application on Twisted.
+
+::
+
+    loop = urwid.MainLoop(widget, event_loop=urwid.GLibEventLoop())
+
+`GLibEventLoop reference <http://excess.org/urwid/reference.html#GLibEventLoop>`_
diff --git a/docs/manual/listboxcontents.rst b/docs/manual/listboxcontents.rst
index f69f4f8..d21e6ba 100644
--- a/docs/manual/listboxcontents.rst
+++ b/docs/manual/listboxcontents.rst
@@ -1,77 +1,77 @@
-.. _listbox-contents:

-

-********************

-  ListBox Contents

-********************

-

-The :class:`~urwid.listbox.ListBox` is a box widget that contains flow widgets.

-Its contents are displayed stacked vertically, and the

-:class:`~urwid.listbox.ListBox` allows the user to scroll through its content.

-One of the flow widgets displayed in the :class:`~urwid.listbox.ListBox` is its

-focus widget.

-

-List Walkers

-============

-

-The :class:`~urwid.listbox.ListBox` does not manage the widgets it displays

-directly, instead it passes that task to a class called a "list walker". List

-walkers keep track of the widget in focus and provide an opaque position object

-that the :class:`~urwid.listbox.ListBox` may use to iterate through widgets

-above and below the focus widget.

-

-A `SimpleListWalker <http://excess.org/urwid/reference.html#SimpleListWalker>`_

-is a list walker that behaves like a normal Python list. It may be used any

-time you will be displaying a moderate number of widgets.

-

-If you need to display a large number of widgets you should implement your own

-list walker that manages creating widgets as they are requested and destroying

-them later to avoid excessive memory use.

-

-List walkers may also be used to display tree or other structures within a

-:class:`~urwid.listbox.ListBox`. A number of the `example programs

-<http://excess.org/urwid/examples.html#>`_ demonstrate the use of custom list

-walker classes.

-

-`List walker interface definition

-<http://excess.org/urwid/reference.html#List_Walker_interface_definition>`_

-

-Focus & Scrolling Behavior

-==========================

-

-The :class:`~urwid.listbox.ListBox` passes all key presses it receives first to

-its focus widget. If its focus widget does not handle a keypress then the

-:class:`~urwid.listbox.ListBox` may handle the keypress by scrolling and/or

-selecting another widget to become its new focus widget.

-

-The :class:`~urwid.listbox.ListBox` tries to do *the most sensible thing* when

-scrolling and changing focus. When the widgets displayed are all

-:class:`~urwid.widget.Text` widgets or other unselectable widgets then the

-:class:`~urwid.listbox.ListBox` will behave like a web browser does when the

-user presses *UP*, *DOWN*, *PAGE UP* and *PAGE DOWN*: new text is immediately

-scrolled in from the top or bottom. The :class:`~urwid.listbox.ListBox` chooses

-one of the visible widgets as its focus widget when scrolling. When scrolling

-up the :class:`~urwid.listbox.ListBox` chooses the topmost widget as the focus,

-and when scrolling down the :class:`~urwid.listbox.ListBox` chooses the

-bottommost widget as the focus.

-

-The :class:`~urwid.listbox.ListBox` remembers the visible location of its focus

-widget as either an "offset" or an "inset". An offset is the number of rows

-between the top of the :class:`~urwid.listbox.ListBox` and the beginning of the

-focus widget. An offset of zero corresponds to a widget with its top aligned

-with the top of the :class:`~urwid.listbox.ListBox`. An inset is the fraction

-of rows of the focus widget that are "above" the top of the

-:class:`~urwid.listbox.ListBox` and not visible. The

-:class:`~urwid.listbox.ListBox` uses this method of remembering the focus

-widget location so that when the :class:`~urwid.listbox.ListBox` is resized the

-the text will remain roughly in the same position of the visible area.

-

-When there are selectable widgets visible in the

-:class:`~urwid.listbox.ListBox` the focus will move between the selectable

-widgets, skipping the unselectable widgets.  The

-:class:`~urwid.listbox.ListBox` will try to scroll all the rows of a selectable

-widget into view so that the user can see the new focus widget in its entirety.

-This behavior can be used to bring more than a single widget into view by using

-a :class:`~urwid.container.Pile` or other container widget to combine a

-selectable widget with other widgets that should be visible at the same time.

-

-`Tutorial chapters covering ListBox usage <http://excess.org/urwid/tutorial.html#frlb>`_

+.. _listbox-contents:
+
+********************
+  ListBox Contents
+********************
+
+The :class:`~urwid.listbox.ListBox` is a box widget that contains flow widgets.
+Its contents are displayed stacked vertically, and the
+:class:`~urwid.listbox.ListBox` allows the user to scroll through its content.
+One of the flow widgets displayed in the :class:`~urwid.listbox.ListBox` is its
+focus widget.
+
+List Walkers
+============
+
+The :class:`~urwid.listbox.ListBox` does not manage the widgets it displays
+directly, instead it passes that task to a class called a "list walker". List
+walkers keep track of the widget in focus and provide an opaque position object
+that the :class:`~urwid.listbox.ListBox` may use to iterate through widgets
+above and below the focus widget.
+
+A `SimpleListWalker <http://excess.org/urwid/reference.html#SimpleListWalker>`_
+is a list walker that behaves like a normal Python list. It may be used any
+time you will be displaying a moderate number of widgets.
+
+If you need to display a large number of widgets you should implement your own
+list walker that manages creating widgets as they are requested and destroying
+them later to avoid excessive memory use.
+
+List walkers may also be used to display tree or other structures within a
+:class:`~urwid.listbox.ListBox`. A number of the `example programs
+<http://excess.org/urwid/examples.html#>`_ demonstrate the use of custom list
+walker classes.
+
+`List walker interface definition
+<http://excess.org/urwid/reference.html#List_Walker_interface_definition>`_
+
+Focus & Scrolling Behavior
+==========================
+
+The :class:`~urwid.listbox.ListBox` passes all key presses it receives first to
+its focus widget. If its focus widget does not handle a keypress then the
+:class:`~urwid.listbox.ListBox` may handle the keypress by scrolling and/or
+selecting another widget to become its new focus widget.
+
+The :class:`~urwid.listbox.ListBox` tries to do *the most sensible thing* when
+scrolling and changing focus. When the widgets displayed are all
+:class:`~urwid.widget.Text` widgets or other unselectable widgets then the
+:class:`~urwid.listbox.ListBox` will behave like a web browser does when the
+user presses *UP*, *DOWN*, *PAGE UP* and *PAGE DOWN*: new text is immediately
+scrolled in from the top or bottom. The :class:`~urwid.listbox.ListBox` chooses
+one of the visible widgets as its focus widget when scrolling. When scrolling
+up the :class:`~urwid.listbox.ListBox` chooses the topmost widget as the focus,
+and when scrolling down the :class:`~urwid.listbox.ListBox` chooses the
+bottommost widget as the focus.
+
+The :class:`~urwid.listbox.ListBox` remembers the visible location of its focus
+widget as either an "offset" or an "inset". An offset is the number of rows
+between the top of the :class:`~urwid.listbox.ListBox` and the beginning of the
+focus widget. An offset of zero corresponds to a widget with its top aligned
+with the top of the :class:`~urwid.listbox.ListBox`. An inset is the fraction
+of rows of the focus widget that are "above" the top of the
+:class:`~urwid.listbox.ListBox` and not visible. The
+:class:`~urwid.listbox.ListBox` uses this method of remembering the focus
+widget location so that when the :class:`~urwid.listbox.ListBox` is resized the
+the text will remain roughly in the same position of the visible area.
+
+When there are selectable widgets visible in the
+:class:`~urwid.listbox.ListBox` the focus will move between the selectable
+widgets, skipping the unselectable widgets.  The
+:class:`~urwid.listbox.ListBox` will try to scroll all the rows of a selectable
+widget into view so that the user can see the new focus widget in its entirety.
+This behavior can be used to bring more than a single widget into view by using
+a :class:`~urwid.container.Pile` or other container widget to combine a
+selectable widget with other widgets that should be visible at the same time.
+
+`Tutorial chapters covering ListBox usage <http://excess.org/urwid/tutorial.html#frlb>`_
diff --git a/docs/manual/mainloop.rst b/docs/manual/mainloop.rst
index 4bb9dea..213bbeb 100644
--- a/docs/manual/mainloop.rst
+++ b/docs/manual/mainloop.rst
@@ -1,51 +1,51 @@
-.. _main-loop:

-

-*************

-  Main Loop

-*************

-

-The :class:`~urwid.main_loop.MainLoop` class ties together a :ref:`display

-module <display-modules>`, a set of widgets and an :ref:`event loop

-<event-loops>`. It handles passing input from the display module to the

-widgets, rendering the widgets and passing the rendered canvas to the display

-module to be drawn.

-

-You may filter the user's input before it is passed to the widgets with your

-own code by using :func:`input_filter() <urwid.main_loop.MainLoop>`, or have

-special code to handle input not handled by the widgets by using

-:func:`unhandled_input() <urwid.main_loop.MainLoop>`.

-

-You may set alarms to create timed events using

-:meth:`~urwid.main_loop.MainLoop.set_alarm_at` or

-:meth:`~urwid.main_loop.MainLoop.set_alarm_in`. These methods automatically add

-a call to :func:`~urwid.main_loop.MainLoop.draw_screen` after calling your

-callback. :meth:`~urwid.main_loop.MainLoop.remove_alarm` may be used to remove

-alarms.

-

-When the main loop is running, any code that raises an

-:exc:`~urwid.main_loop.ExitMainLoop` exception will cause the loop to

-exit cleanly. If any other exception reaches the main loop code, it will shut

-down the screen to avoid leaving the terminal in an unusual state then re-raise

-the exception for normal handling.

-

-Using :class:`~urwid.main_loop.MainLoop` is highly recommended, but if it does

-not fit the needs of your application you may choose to use your own code

-instead. There are no dependencies on :class:`~urwid.main_loop.MainLoop` in

-other parts of Urwid.

-

-Widgets Displayed

-=================

-

-The topmost widget displayed by :class:`~urwid.main_loop.MainLoop` must be

-passed as the first parameter to the constructor. If you want to change the

-topmost widget while running, you can assign a new widget to the

-:class:`~urwid.main_loop.MainLoop` object's

-:attr:`~urwid.main_loop.MainLoop.widget` attribute. This is useful for

-applications that have a number of different modes or views.

-

-The displayed widgets will be handling user input, so it is better to extend

-the widgets that are displayed with your application-specific input handling so

-that the application's behaviour changes when the widgets change. If all your

-custom input handling is done from :func:`unhandled_input()

-<urwid.main_loop.MainLoop>`, it will be difficult to extend as your application

-gets more complicated. 

+.. _main-loop:
+
+*************
+  Main Loop
+*************
+
+The :class:`~urwid.main_loop.MainLoop` class ties together a :ref:`display
+module <display-modules>`, a set of widgets and an :ref:`event loop
+<event-loops>`. It handles passing input from the display module to the
+widgets, rendering the widgets and passing the rendered canvas to the display
+module to be drawn.
+
+You may filter the user's input before it is passed to the widgets with your
+own code by using :func:`input_filter() <urwid.main_loop.MainLoop>`, or have
+special code to handle input not handled by the widgets by using
+:func:`unhandled_input() <urwid.main_loop.MainLoop>`.
+
+You may set alarms to create timed events using
+:meth:`~urwid.main_loop.MainLoop.set_alarm_at` or
+:meth:`~urwid.main_loop.MainLoop.set_alarm_in`. These methods automatically add
+a call to :func:`~urwid.main_loop.MainLoop.draw_screen` after calling your
+callback. :meth:`~urwid.main_loop.MainLoop.remove_alarm` may be used to remove
+alarms.
+
+When the main loop is running, any code that raises an
+:exc:`~urwid.main_loop.ExitMainLoop` exception will cause the loop to
+exit cleanly. If any other exception reaches the main loop code, it will shut
+down the screen to avoid leaving the terminal in an unusual state then re-raise
+the exception for normal handling.
+
+Using :class:`~urwid.main_loop.MainLoop` is highly recommended, but if it does
+not fit the needs of your application you may choose to use your own code
+instead. There are no dependencies on :class:`~urwid.main_loop.MainLoop` in
+other parts of Urwid.
+
+Widgets Displayed
+=================
+
+The topmost widget displayed by :class:`~urwid.main_loop.MainLoop` must be
+passed as the first parameter to the constructor. If you want to change the
+topmost widget while running, you can assign a new widget to the
+:class:`~urwid.main_loop.MainLoop` object's
+:attr:`~urwid.main_loop.MainLoop.widget` attribute. This is useful for
+applications that have a number of different modes or views.
+
+The displayed widgets will be handling user input, so it is better to extend
+the widgets that are displayed with your application-specific input handling so
+that the application's behaviour changes when the widgets change. If all your
+custom input handling is done from :func:`unhandled_input()
+<urwid.main_loop.MainLoop>`, it will be difficult to extend as your application
+gets more complicated. 
diff --git a/docs/manual/standardwidgets.rst b/docs/manual/standardwidgets.rst
index 86e25ea..3713b86 100644
--- a/docs/manual/standardwidgets.rst
+++ b/docs/manual/standardwidgets.rst
@@ -1,43 +1,43 @@
-.. _basic-grafic-widgets:

-

-********************

-  Standard widgets  

-********************

-

-Basic & Graphic Widgets

-=======================

-

-.. image:: images/urwid_widgets_1.png

-

-`Urwid Reference <http://excess.org/urwid/reference.html>`_

-

-Basic and graphic widgets are the content with which users interact. They may

-also be used as part of custom widgets you create.

-

-

-Decoration & Container Widgets

-==============================

-

-.. image:: images/urwid_widgets_2.png

-

-`Urwid Reference <http://excess.org/urwid/reference.html>`_

-

-.. TODO: add links here?

-

-Decoration widgets alter the appearance or position of a single other widget.

-The widget they wrap is available as the ``decoration_widget.original_widget``.

-If you might be using more than one decoration widget you may use

-``decoration_widget.base_widget`` to access the "most" original_widget

-(``decoration_widget.original_widget.original_widget...``).

-``widget.base_widget`` points to ``widget`` on all non-decoration widgets, so

-it is safe to use in any situation.

-

-Container widgets divide their available space between their child widgets.

-This is how widget layouts are defined. When handling selectable widgets

-container widgets also keep track of which of their child widgets is in focus.

-Container widgets may be nested, so the actual widget in focus may be many

-levels below the topmost widget.

-

-Different container widgets have different methods of accessing and updating

-their children, and the child in focus. These methods will be made more

-consistent in a future release.

+.. _basic-grafic-widgets:
+
+********************
+  Standard widgets  
+********************
+
+Basic & Graphic Widgets
+=======================
+
+.. image:: images/urwid_widgets_1.png
+
+`Urwid Reference <http://excess.org/urwid/reference.html>`_
+
+Basic and graphic widgets are the content with which users interact. They may
+also be used as part of custom widgets you create.
+
+
+Decoration & Container Widgets
+==============================
+
+.. image:: images/urwid_widgets_2.png
+
+`Urwid Reference <http://excess.org/urwid/reference.html>`_
+
+.. TODO: add links here?
+
+Decoration widgets alter the appearance or position of a single other widget.
+The widget they wrap is available as the ``decoration_widget.original_widget``.
+If you might be using more than one decoration widget you may use
+``decoration_widget.base_widget`` to access the "most" original_widget
+(``decoration_widget.original_widget.original_widget...``).
+``widget.base_widget`` points to ``widget`` on all non-decoration widgets, so
+it is safe to use in any situation.
+
+Container widgets divide their available space between their child widgets.
+This is how widget layouts are defined. When handling selectable widgets
+container widgets also keep track of which of their child widgets is in focus.
+Container widgets may be nested, so the actual widget in focus may be many
+levels below the topmost widget.
+
+Different container widgets have different methods of accessing and updating
+their children, and the child in focus. These methods will be made more
+consistent in a future release.
diff --git a/docs/manual/textattributes.rst b/docs/manual/textattributes.rst
index 899b681..53918e6 100644
--- a/docs/manual/textattributes.rst
+++ b/docs/manual/textattributes.rst
@@ -1,59 +1,59 @@
-.. _text-attributes:

-

-*******************

-  Text Attributes  

-*******************

-

-A :class:`~urwid.widget.Text` widget can take plain or unicode strings, but you

-can also specify which attributes to display each part of that text by using

-"text markup" format. Text markup made up of lists and tuples. Tuples contain

-an attribute and text markup to apply it to. Lists used to concatenate text

-markup.

-

-The normal text formatting rules apply and the attributes will follow the text

-when it is split or wrapped to the next line.

-

-`Text reference <http://excess.org/urwid/reference.html#Text>`_

-

-::

-

-    Text("a simple string with default attributes")

-

-The string and space around will appear in the default foreground and

-background.

-

-::

-

-    Text(('attr1', "a string in attribute attr1"))

-

-The string will appear with foreground and backgrounds specified in the display

-module's palette for ``'attr1'``, but the space around (before/after) the text

-will appear with the default foreground and background.

-

-If you want the whole :class:`~urwid.widget.Text` widget, including the space

-around the text, to appear as a single attribute you should put your widget

-inside an :class:`~urwid.decoration.AttrMap` widget.

-

-`AttrMap reference <http://excess.org/urwid/reference.html#AttrMap>`_

-

-::

-

-    Text(["a simple string ", ('attr1', "ending in attr1")])

-

-The first three words have the default attribute and the last three words have

-attribute ``'attr1'``.

-

-::

-

-    Text([('attr1', "start in attr1 "), ('attr2', "end in attr2")])

-

-The first three words have attribute ``'attr1'`` and the last three words have

-attribute ``'attr2'``.

-

-::

-

-    Text(('attr1', ["nesting example ", ('attr2', "inside"), " outside"]))

-

-When markup is nested only the innermost attribute applies. Here ``"inside"``

-has attribute ``'attr2'`` and all the rest of the text has attribute

-``'attr1'``.

+.. _text-attributes:
+
+*******************
+  Text Attributes  
+*******************
+
+A :class:`~urwid.widget.Text` widget can take plain or unicode strings, but you
+can also specify which attributes to display each part of that text by using
+"text markup" format. Text markup made up of lists and tuples. Tuples contain
+an attribute and text markup to apply it to. Lists used to concatenate text
+markup.
+
+The normal text formatting rules apply and the attributes will follow the text
+when it is split or wrapped to the next line.
+
+`Text reference <http://excess.org/urwid/reference.html#Text>`_
+
+::
+
+    Text("a simple string with default attributes")
+
+The string and space around will appear in the default foreground and
+background.
+
+::
+
+    Text(('attr1', "a string in attribute attr1"))
+
+The string will appear with foreground and backgrounds specified in the display
+module's palette for ``'attr1'``, but the space around (before/after) the text
+will appear with the default foreground and background.
+
+If you want the whole :class:`~urwid.widget.Text` widget, including the space
+around the text, to appear as a single attribute you should put your widget
+inside an :class:`~urwid.decoration.AttrMap` widget.
+
+`AttrMap reference <http://excess.org/urwid/reference.html#AttrMap>`_
+
+::
+
+    Text(["a simple string ", ('attr1', "ending in attr1")])
+
+The first three words have the default attribute and the last three words have
+attribute ``'attr1'``.
+
+::
+
+    Text([('attr1', "start in attr1 "), ('attr2', "end in attr2")])
+
+The first three words have attribute ``'attr1'`` and the last three words have
+attribute ``'attr2'``.
+
+::
+
+    Text(('attr1', ["nesting example ", ('attr2', "inside"), " outside"]))
+
+When markup is nested only the innermost attribute applies. Here ``"inside"``
+has attribute ``'attr2'`` and all the rest of the text has attribute
+``'attr1'``.
diff --git a/docs/manual/textencodings.rst b/docs/manual/textencodings.rst
index 94df721..ef5ca15 100644
--- a/docs/manual/textencodings.rst
+++ b/docs/manual/textencodings.rst
@@ -1,94 +1,94 @@
-.. vim: set fileencoding=utf-8:

-

-.. _text-encodings:

-

-******************

-  Text Encodings  

-******************

-

-Urwid has a single global setting for text encoding that is set on start-up

-based on the configured locale. You may change that setting with the

-:meth:`set_encoding` method. eg.

-

-::

-

-    urwid.set_encoding("UTF-8")

-

-There are two distinct modes of handling encodings with Urwid: Unicode or

-Pass-through. The mode corresponds to using Unicode strings or normal strings

-in your widgets.

-

-::

-

-    txt_a = urwid.Text(u"El Niño")

-    txt_b = urwid.Text("El Niño")

-

-``txt_a`` will be automatically encoded when it is displayed (Unicode mode).  

-

-``txt_b`` is **assumed** to be in the encoding the user is expecting and passed

-through as-is (Pass-through mode). If the encodings are different then the

-user will see garbage on their screen.

-

-The only time it makes sense to use pass-through mode is if you're handling an

-encoding that does not round-trip to Unicode properly, or if you're absolutely

-sure you know what you're doing.

-

-Unicode Support

-===============

-

-Urwid has a basic understanding of character widths so that the text layout

-code can properly wrap and display most text. There is currently no support for

-right-to-left text.

-

-You should be able to use any valid Unicode characters that are present in the

-global encoding setting in your widgets, with the addition of some common DEC

-graphic characters:

-

-::

-

-    \u00A3 (£), \u00B0 (°), \u00B1 (±), \u00B7 (·), \u03C0 (π),

-    \u2260 (≠), \u2264 (≤), \u2265 (≥), \u23ba (⎺), \u23bb (⎻),

-    \u23bc (⎼), \u23bd (⎽), \u2500 (─), \u2502 (│), \u250c (┌),

-    \u2510 (┐), \u2514 (└), \u2518 (┘), \u251c (├), \u2524 (┤),

-    \u252c (┬), \u2534 (┴), \u253c (┼), \u2592 (▒), \u25c6 (◆)

-

-If you use these characters with a non-UTF-8 encoding they will be sent using

-the alternate character set sequences supported by some terminals.

-

-Pass-through Support

-====================

-

-Supported encodings for pass-through mode:

-

-* UTF-8 (narrow and wide characters)

-* ISO-8859-*

-* EUC-JP (JISX 0208 only)

-* EUC-KR

-* EUC-CN (aka CN-GB)

-* EUC-TW (CNS 11643 plain 1 only)

-* GB2312

-* GBK

-* BIG5

-* UHC

-

-In pass-through mode Urwid must still calculate character widths. For UTF-8

-mode the widths are specified in the Unicode standard. For ISO-8859-* all

-bytes are assumed to be 1 column wide characters. For the remaining supported

-encodings any byte with the high-bit set is considered to be half of a 2-column

-wide character.

-

-The additional plains in EUC are not currently supported.

-

-Future Work

-===========

-

-Text encoding should be a per-screen (display module) setting, not a global

-setting. It should be possible to simultaneously support different encodings on

-different screens with Urwid. Making this work involves possibly changing the

-function signature of many widget methods, because encoding needs to be

-specified along with size and focus.

-

-Device-specific encodings should also be possible for Unicode mode. The LCD

-display module in development drives a device with a non-standard mapping of

-Unicode code points to 8-bit values, but it should still be possible to use a

-Unicode text to display the characters it supports.

+.. vim: set fileencoding=utf-8:
+
+.. _text-encodings:
+
+******************
+  Text Encodings  
+******************
+
+Urwid has a single global setting for text encoding that is set on start-up
+based on the configured locale. You may change that setting with the
+:meth:`set_encoding` method. eg.
+
+::
+
+    urwid.set_encoding("UTF-8")
+
+There are two distinct modes of handling encodings with Urwid: Unicode or
+Pass-through. The mode corresponds to using Unicode strings or normal strings
+in your widgets.
+
+::
+
+    txt_a = urwid.Text(u"El Niño")
+    txt_b = urwid.Text("El Niño")
+
+``txt_a`` will be automatically encoded when it is displayed (Unicode mode).  
+
+``txt_b`` is **assumed** to be in the encoding the user is expecting and passed
+through as-is (Pass-through mode). If the encodings are different then the
+user will see garbage on their screen.
+
+The only time it makes sense to use pass-through mode is if you're handling an
+encoding that does not round-trip to Unicode properly, or if you're absolutely
+sure you know what you're doing.
+
+Unicode Support
+===============
+
+Urwid has a basic understanding of character widths so that the text layout
+code can properly wrap and display most text. There is currently no support for
+right-to-left text.
+
+You should be able to use any valid Unicode characters that are present in the
+global encoding setting in your widgets, with the addition of some common DEC
+graphic characters:
+
+::
+
+    \u00A3 (£), \u00B0 (°), \u00B1 (±), \u00B7 (·), \u03C0 (π),
+    \u2260 (≠), \u2264 (≤), \u2265 (≥), \u23ba (⎺), \u23bb (⎻),
+    \u23bc (⎼), \u23bd (⎽), \u2500 (─), \u2502 (│), \u250c (┌),
+    \u2510 (┐), \u2514 (└), \u2518 (┘), \u251c (├), \u2524 (┤),
+    \u252c (┬), \u2534 (┴), \u253c (┼), \u2592 (▒), \u25c6 (◆)
+
+If you use these characters with a non-UTF-8 encoding they will be sent using
+the alternate character set sequences supported by some terminals.
+
+Pass-through Support
+====================
+
+Supported encodings for pass-through mode:
+
+* UTF-8 (narrow and wide characters)
+* ISO-8859-*
+* EUC-JP (JISX 0208 only)
+* EUC-KR
+* EUC-CN (aka CN-GB)
+* EUC-TW (CNS 11643 plain 1 only)
+* GB2312
+* GBK
+* BIG5
+* UHC
+
+In pass-through mode Urwid must still calculate character widths. For UTF-8
+mode the widths are specified in the Unicode standard. For ISO-8859-* all
+bytes are assumed to be 1 column wide characters. For the remaining supported
+encodings any byte with the high-bit set is considered to be half of a 2-column
+wide character.
+
+The additional plains in EUC are not currently supported.
+
+Future Work
+===========
+
+Text encoding should be a per-screen (display module) setting, not a global
+setting. It should be possible to simultaneously support different encodings on
+different screens with Urwid. Making this work involves possibly changing the
+function signature of many widget methods, because encoding needs to be
+specified along with size and focus.
+
+Device-specific encodings should also be possible for Unicode mode. The LCD
+display module in development drives a device with a non-standard mapping of
+Unicode code points to 8-bit values, but it should still be possible to use a
+Unicode text to display the characters it supports.
diff --git a/docs/manual/textlayout.rst b/docs/manual/textlayout.rst
index bbca25d..ff66a35 100644
--- a/docs/manual/textlayout.rst
+++ b/docs/manual/textlayout.rst
@@ -1,135 +1,135 @@
-.. _text-layout:

-

-***************

-  Text Layout  

-***************

-

-Mapping a text string to screen coordinates within a widget is called text

-layout. The :class:`~urwid.widget.Text` widget's default layout class supports

-aligning text to the left, center or right, and can wrap text on space

-characters, at any location, or clip text that is off the edge.

-

-`Text widget reference <http://excess.org/urwid/reference.html#Text>`_

-

-::

-

-    Text("Showing some different alignment modes")

-

-    align=LEFT (default)

-    +----------------+   +------------------------+

-    |Showing some    |   |Showing some different  |

-    |different       |   |alignment modes         |

-    |alignment modes |   +------------------------+

-    +----------------+

-

-    align=CENTER

-    +----------------+   +------------------------+

-    |  Showing some  |   | Showing some different |

-    |   different    |   |    alignment modes     |

-    |alignment modes |   +------------------------+

-    +----------------+

-

-    align=RIGHT

-    +----------------+   +------------------------+

-    |    Showing some|   |  Showing some different|

-    |       different|   |         alignment modes|

-    | alignment modes|   +------------------------+

-    +----------------+

-

-::

-

-    Text("Showing some different wrapping modes\nnewline")

-

-    wrap=SPACE (default)

-    +----------------+   +------------------------+

-    |Showing some    |   |Showing some different  |

-    |different       |   |wrapping modes          |

-    |wrapping modes  |   |newline                 |

-    |newline         |   +------------------------+

-    +----------------+

-

-    wrap=ANY

-    +----------------+   +------------------------+

-    |Showing some dif|   |Showing some different w|

-    |ferent wrapping |   |rapping modes           |

-    |modes           |   |newline                 |

-    |newline         |   +------------------------+

-    +----------------+

-

-    wrap=CLIP

-    +----------------+   +------------------------+

-    |Showing some dif|   |Showing some different w|

-    |newline         |   |newline                 |

-    +----------------+   +------------------------+

-

-If this is good enough for your application feel free to skip the rest of this

-section.

-

-Text Layout Structures

-======================

-

-::

-

-    "This is how a string of text might be displayed"

-    -0----5----0----5----0----5----0----5----0----5-

-

-    +0----5----0----5--+   right_aligned_text_layout = [

-    0     This is how a|     [(5, 0), (13, 0, 13)],

-    |    string of text|     [(4, 13), (14, 14, 28)],

-    |might be displayed|     [(18, 29, 47)]

-    +------------------+   ]

-

-The mapping from a text string to where that text will be displayed in the

-widget is expressed as a text layout structure.

-

-Text layout structures are used both for rendering :class:`~urwid.widget.Text`

-widgets and for mapping ``(x, y)`` positions within a widget back to the

-corresponding offsets in the text. The latter is used when moving the cursor in

-:class:`~urwid.widget.Edit` widgets up and down or by clicking with the mouse.

-

-A text layout structure is a list of one or more line layouts. Each line layout

-corresponds to a row of text in the widget, starting from its top.

-

-A line layout is a list zero or more of the following tuples, each expressing

-text to be displayed from left to right:

-

-A. ``(column width, starting text offset, ending text offset)``

-B. ``(column width of space characters to insert, text offset or None)``

-C. ``(column width, text offset, "new text to insert")``

-

-Tuple A displays a segment of text from the :class:`~urwid.widget.Text` widget.

-Column width is explicitly specified because some characters within the text

-may be zero width or double width.

-

-Tuple B inserts any number of space characters, and if those characters

-correspond to an offset within the text, that may be specified.

-

-Tuple C allows insertion of arbitrary text. This could be used for hyphenating

-split words or any other effect not covered by A or B. The

-:class:`~urwid.text_layout.StandardTextLayout` does not currently use this

-tuple in its line layouts.

-

-`TextLayout reference <http://excess.org/urwid/reference.html#TextLayout>`_

-

-.. TODO: move class definition in another file and substitute it with a section?

-

-.. class:: StandardTextLayout

-

-   This class implements Urwid's standard text layout, with *left*, *center*

-   and *right* align modes and *space*, *any* and *clip* wrap modes.

-

-`StandardTextLayout reference <http://excess.org/urwid/reference.html#StandardTextLayout>`_

-

-Custom Text Layouts

-===================

-

-The :class:`~urwid.text_layout.StandardTextLayout` is set as the class variable

-:attr:`~urwid.widget.Text.layout`. Individual :class:`~urwid.widget.Text`

-widgets may use a different layout class, or you can change the default by

-setting the :attr:`~urwid.widget.Text.layout` class variable itself.

-

-A custom text layout class should extend the

-:class:`~urwid.text_layout.TextLayout` base class and return text layout

-structures from its :meth:`layout` method (see above).

-

-`TextLayout reference <http://excess.org/urwid/reference.html#TextLayout>`_

+.. _text-layout:
+
+***************
+  Text Layout  
+***************
+
+Mapping a text string to screen coordinates within a widget is called text
+layout. The :class:`~urwid.widget.Text` widget's default layout class supports
+aligning text to the left, center or right, and can wrap text on space
+characters, at any location, or clip text that is off the edge.
+
+`Text widget reference <http://excess.org/urwid/reference.html#Text>`_
+
+::
+
+    Text("Showing some different alignment modes")
+
+    align=LEFT (default)
+    +----------------+   +------------------------+
+    |Showing some    |   |Showing some different  |
+    |different       |   |alignment modes         |
+    |alignment modes |   +------------------------+
+    +----------------+
+
+    align=CENTER
+    +----------------+   +------------------------+
+    |  Showing some  |   | Showing some different |
+    |   different    |   |    alignment modes     |
+    |alignment modes |   +------------------------+
+    +----------------+
+
+    align=RIGHT
+    +----------------+   +------------------------+
+    |    Showing some|   |  Showing some different|
+    |       different|   |         alignment modes|
+    | alignment modes|   +------------------------+
+    +----------------+
+
+::
+
+    Text("Showing some different wrapping modes\nnewline")
+
+    wrap=SPACE (default)
+    +----------------+   +------------------------+
+    |Showing some    |   |Showing some different  |
+    |different       |   |wrapping modes          |
+    |wrapping modes  |   |newline                 |
+    |newline         |   +------------------------+
+    +----------------+
+
+    wrap=ANY
+    +----------------+   +------------------------+
+    |Showing some dif|   |Showing some different w|
+    |ferent wrapping |   |rapping modes           |
+    |modes           |   |newline                 |
+    |newline         |   +------------------------+
+    +----------------+
+
+    wrap=CLIP
+    +----------------+   +------------------------+
+    |Showing some dif|   |Showing some different w|
+    |newline         |   |newline                 |
+    +----------------+   +------------------------+
+
+If this is good enough for your application feel free to skip the rest of this
+section.
+
+Text Layout Structures
+======================
+
+::
+
+    "This is how a string of text might be displayed"
+    -0----5----0----5----0----5----0----5----0----5-
+
+    +0----5----0----5--+   right_aligned_text_layout = [
+    0     This is how a|     [(5, 0), (13, 0, 13)],
+    |    string of text|     [(4, 13), (14, 14, 28)],
+    |might be displayed|     [(18, 29, 47)]
+    +------------------+   ]
+
+The mapping from a text string to where that text will be displayed in the
+widget is expressed as a text layout structure.
+
+Text layout structures are used both for rendering :class:`~urwid.widget.Text`
+widgets and for mapping ``(x, y)`` positions within a widget back to the
+corresponding offsets in the text. The latter is used when moving the cursor in
+:class:`~urwid.widget.Edit` widgets up and down or by clicking with the mouse.
+
+A text layout structure is a list of one or more line layouts. Each line layout
+corresponds to a row of text in the widget, starting from its top.
+
+A line layout is a list zero or more of the following tuples, each expressing
+text to be displayed from left to right:
+
+A. ``(column width, starting text offset, ending text offset)``
+B. ``(column width of space characters to insert, text offset or None)``
+C. ``(column width, text offset, "new text to insert")``
+
+Tuple A displays a segment of text from the :class:`~urwid.widget.Text` widget.
+Column width is explicitly specified because some characters within the text
+may be zero width or double width.
+
+Tuple B inserts any number of space characters, and if those characters
+correspond to an offset within the text, that may be specified.
+
+Tuple C allows insertion of arbitrary text. This could be used for hyphenating
+split words or any other effect not covered by A or B. The
+:class:`~urwid.text_layout.StandardTextLayout` does not currently use this
+tuple in its line layouts.
+
+`TextLayout reference <http://excess.org/urwid/reference.html#TextLayout>`_
+
+.. TODO: move class definition in another file and substitute it with a section?
+
+.. class:: StandardTextLayout
+
+   This class implements Urwid's standard text layout, with *left*, *center*
+   and *right* align modes and *space*, *any* and *clip* wrap modes.
+
+`StandardTextLayout reference <http://excess.org/urwid/reference.html#StandardTextLayout>`_
+
+Custom Text Layouts
+===================
+
+The :class:`~urwid.text_layout.StandardTextLayout` is set as the class variable
+:attr:`~urwid.widget.Text.layout`. Individual :class:`~urwid.widget.Text`
+widgets may use a different layout class, or you can change the default by
+setting the :attr:`~urwid.widget.Text.layout` class variable itself.
+
+A custom text layout class should extend the
+:class:`~urwid.text_layout.TextLayout` base class and return text layout
+structures from its :meth:`layout` method (see above).
+
+`TextLayout reference <http://excess.org/urwid/reference.html#TextLayout>`_
diff --git a/docs/manual/userinput.rst b/docs/manual/userinput.rst
index 17767be..eaf2cf0 100644
--- a/docs/manual/userinput.rst
+++ b/docs/manual/userinput.rst
@@ -1,114 +1,114 @@
-.. vim: set fileencoding=utf-8:

-

-.. _user-input:

-

-**************

-  User Input  

-**************

-

-All input from the user is parsed by a display module, and returned from either

-the :meth:`get_input` or :meth:`get_input_nonblocking` methods as a list.

-Window resize events are also included in the user input.

-

-The :class:`~urwid.main_loop.MainLoop` class will take this input and pass each

-item to the widget methods :meth:`keypress` or :meth:`mouse_event`. You may

-filter input (possibly removing or altering it) before it is passed to the

-widgets, or can catch unhandled input by passing functions into the

-:class:`~urwid.main_loop.MainLoop` constructor. If the window was resized

-:class:`~urwid.main_loop.MainLoop` will query the new display size and update

-the screen.

-

-There may be more than one keystroke or mouse event processed at a time, and

-each is sent as a separate item in the list.

-

-Keyboard Input

-==============

-

-Not all keystrokes are sent by a user's terminal to the program, and which keys

-are sent varies from terminal to terminal, but Urwid will report any keys that

-are sent.

-

-============= =================

-Key pressed   Input returned

-============= =================

-H             ``'h'``

-SHIFT+H       ``'H'``

-SPACE         ``' '``

-ENTER         ``'enter'``

-UP            ``'up'``

-PAGE DOWN     ``'page down'``

-F5            ``'f5'``

-SHIFT+F5      ``'shift f5'``

-CTRL+SHIFT+F5 ``'shift ctrl f5'``

-ALT+J         ``'meta j'``

-============= =================

-

-With Unicode :ref:`text encoding <text-encodings>` you will also receive

-Unicode strings for any non-ASCII characters:

-

-=========== ==============

-Key pressed Input returned

-=========== ==============

-é           ``u'é'``

-Ж           ``u'Ж'``

-カ          ``u'カ'``

-=========== ==============

-

-With non-Unicode :ref:`text encoding <text-encodings>` characters will be sent

-as-is in the original encoding.

-

-=========== =========================================

-Key pressed Input returned (each in its own encoding)

-=========== =========================================

-é           ``'é'``

-Ж           ``'Ж'``

-カ          ``'カ'`` (two bytes)

-=========== =========================================

-

-Urwid does not try to convert this text to Unicode to avoid losing any

-information. If you want the input converted to Unicode in all cases you may

-create an input filter to do so.

-

-Mouse Input

------------

-

-Mouse input is sent as a ``(event, button, x, y)`` tuple. *event* is a string

-describing the event. If the SHIFT, ALT or CTRL keys are held when a mouse

-event is sent then *event* may be prefixed by ``'shift '``, ``'meta '`` or

-``'ctrl'``. *button* is a number from 1 to 5. *x* and *y* are character

-coordinates starting at ``(0,0)`` at the top-left of the screen. 

-

-Support for the right-mouse button and use of modifier keys is poor in many

-terminals and some users don't have a middle mouse button, so these shouldn't

-be relied on.

-

-``'mouse press'`` Events

-========================

-

-A mouse button was pressed.

-

-=============== ======================

-`button` number Mouse button

-=============== ======================

-1               Left button

-2               Middle button

-3               Right button

-4               Scroll wheel up [#first]_

-5               Scroll wheel down [#first]_

-=============== ======================

-

-.. [#first] typically no corresponding release event is sent

-

-``'mouse release'`` Events

-==========================

-

-Mouse release events will often not have information about which button was

-released. In this case *button* will be set to 0.

-

-``'mouse drag'`` Events

-=======================

-

-In the rare event that your user is using a terminal that can send these events

-you can use them to track their mouse dragging from one character cell to the

-next across the screen. Be aware that you might see *x* and/or *y* coordinates

-one position off the screen if the user drags their mouse to the edge.

+.. vim: set fileencoding=utf-8:
+
+.. _user-input:
+
+**************
+  User Input  
+**************
+
+All input from the user is parsed by a display module, and returned from either
+the :meth:`get_input` or :meth:`get_input_nonblocking` methods as a list.
+Window resize events are also included in the user input.
+
+The :class:`~urwid.main_loop.MainLoop` class will take this input and pass each
+item to the widget methods :meth:`keypress` or :meth:`mouse_event`. You may
+filter input (possibly removing or altering it) before it is passed to the
+widgets, or can catch unhandled input by passing functions into the
+:class:`~urwid.main_loop.MainLoop` constructor. If the window was resized
+:class:`~urwid.main_loop.MainLoop` will query the new display size and update
+the screen.
+
+There may be more than one keystroke or mouse event processed at a time, and
+each is sent as a separate item in the list.
+
+Keyboard Input
+==============
+
+Not all keystrokes are sent by a user's terminal to the program, and which keys
+are sent varies from terminal to terminal, but Urwid will report any keys that
+are sent.
+
+============= =================
+Key pressed   Input returned
+============= =================
+H             ``'h'``
+SHIFT+H       ``'H'``
+SPACE         ``' '``
+ENTER         ``'enter'``
+UP            ``'up'``
+PAGE DOWN     ``'page down'``
+F5            ``'f5'``
+SHIFT+F5      ``'shift f5'``
+CTRL+SHIFT+F5 ``'shift ctrl f5'``
+ALT+J         ``'meta j'``
+============= =================
+
+With Unicode :ref:`text encoding <text-encodings>` you will also receive
+Unicode strings for any non-ASCII characters:
+
+=========== ==============
+Key pressed Input returned
+=========== ==============
+é           ``u'é'``
+Ж           ``u'Ж'``
+カ          ``u'カ'``
+=========== ==============
+
+With non-Unicode :ref:`text encoding <text-encodings>` characters will be sent
+as-is in the original encoding.
+
+=========== =========================================
+Key pressed Input returned (each in its own encoding)
+=========== =========================================
+é           ``'é'``
+Ж           ``'Ж'``
+カ          ``'カ'`` (two bytes)
+=========== =========================================
+
+Urwid does not try to convert this text to Unicode to avoid losing any
+information. If you want the input converted to Unicode in all cases you may
+create an input filter to do so.
+
+Mouse Input
+-----------
+
+Mouse input is sent as a ``(event, button, x, y)`` tuple. *event* is a string
+describing the event. If the SHIFT, ALT or CTRL keys are held when a mouse
+event is sent then *event* may be prefixed by ``'shift '``, ``'meta '`` or
+``'ctrl'``. *button* is a number from 1 to 5. *x* and *y* are character
+coordinates starting at ``(0,0)`` at the top-left of the screen. 
+
+Support for the right-mouse button and use of modifier keys is poor in many
+terminals and some users don't have a middle mouse button, so these shouldn't
+be relied on.
+
+``'mouse press'`` Events
+========================
+
+A mouse button was pressed.
+
+=============== ======================
+`button` number Mouse button
+=============== ======================
+1               Left button
+2               Middle button
+3               Right button
+4               Scroll wheel up [#first]_
+5               Scroll wheel down [#first]_
+=============== ======================
+
+.. [#first] typically no corresponding release event is sent
+
+``'mouse release'`` Events
+==========================
+
+Mouse release events will often not have information about which button was
+released. In this case *button* will be set to 0.
+
+``'mouse drag'`` Events
+=======================
+
+In the rare event that your user is using a terminal that can send these events
+you can use them to track their mouse dragging from one character cell to the
+next across the screen. Be aware that you might see *x* and/or *y* coordinates
+one position off the screen if the user drags their mouse to the edge.
diff --git a/docs/manual/widgetlayout.rst b/docs/manual/widgetlayout.rst
index 1be08c9..684a2f1 100644
--- a/docs/manual/widgetlayout.rst
+++ b/docs/manual/widgetlayout.rst
@@ -1,72 +1,72 @@
-.. _widget-layout:

-

-*****************

-  Widget Layout

-*****************

-

-Urwid uses widgets to divide up the available screen space. This makes it easy

-to create a fluid interface that moves and changes with the user's terminal and

-font size.

-

-.. image:: images/widget_layout.png

-

-The result of rendering a widget is a canvas suitable for displaying on the

-screen. When we render the topmost widget:

-

-1. The topmost widget *(a)* is rendered the full size of the screen

-2. *(a)* renders *(b)* any size up to the full size of the screen

-3. *(b)* renders *(c)*, *(d)* and *(e)* dividing its available screen columns

-   between them

-4. *(e)* renders *(f)* and *(g)* dividing its available screen rows between

-   them

-5. *(e)* combines the canvases from *(f)* and *(g)* and returns them

-6. *(b)* combines the canvases from *(c)*, *(d)* and *(e)* and returns them

-7. *(a)* possibly modifies the canvas from *(b)* and returns it

-

-Widgets *(a)*, *(b)* and *(e)* are called container widgets because they

-contain other widgets. Container widgets choose the size and position their

-contained widgets.

-

-Container widgets must also keep track of which one of their contained widgets

-is in focus. The focus is used when handling keyboard input. If in the above

-example *(b)* 's focus widget is *(e)* and *(e)* 's focus widget is

-*(f)* then keyboard input will be handled this way:

-

-1. The keypress is passed to the topmost widget *(a)*

-2. *(a)* passes the keypress to *(b)*

-3. *(b)* passes the keypress to *(e)*, its focus widget

-4. *(e)* passes the keypress to *(f)*, its focus widget

-5. *(f)* either handles the keypress or returns it

-6. *(e)* has an opportunity to handle the keypress if it was returned from

-   *(f)*

-7. *(b)* has an opportunity to handle the keypress if it was returned from

-   *(e)*

-8. *(a)* has an opportunity to handle the keypress if it was returned from

-   *(b)*

-

-Box, Flow and Fixed Widgets

-===========================

-

-The size of a widget is measured in screen columns and rows. Widgets that are

-given an exact number of screen columns and rows are called box widgets. The

-topmost widget is always a box widget.

-

-Much of the information displayed in a console user interface is text and the

-best way to display text is to have it flow from one screen row to the next.

-Widgets like this that require a variable number of screen rows are called flow

-widgets. Flow widgets are given a number of screen columns and can calculate

-how many screen rows they need.

-

-Occasionally it is also useful to have a widget that knows how many screen

-columns and rows it requires, regardless of the space available. This is

-called a fixed widget.

-

-It is an Urwid convention to use the variables :attr:`maxcol` and

-:attr:`maxrow` to store a widget's size. Box widgets require both of ``(maxcol,

-maxrow)`` to be specified.

-

-Flow widgets expect a single-element tuple ``(maxcol,)`` instead because they

-calculate their :attr:`maxrow` based on the :attr:`maxcol` value.

-

-Fixed widgets expect the value ``None`` to be passed in to functions that take

-a size because they know their :attr:`maxcol` and :attr:`maxrow` values.

+.. _widget-layout:
+
+*****************
+  Widget Layout
+*****************
+
+Urwid uses widgets to divide up the available screen space. This makes it easy
+to create a fluid interface that moves and changes with the user's terminal and
+font size.
+
+.. image:: images/widget_layout.png
+
+The result of rendering a widget is a canvas suitable for displaying on the
+screen. When we render the topmost widget:
+
+1. The topmost widget *(a)* is rendered the full size of the screen
+2. *(a)* renders *(b)* any size up to the full size of the screen
+3. *(b)* renders *(c)*, *(d)* and *(e)* dividing its available screen columns
+   between them
+4. *(e)* renders *(f)* and *(g)* dividing its available screen rows between
+   them
+5. *(e)* combines the canvases from *(f)* and *(g)* and returns them
+6. *(b)* combines the canvases from *(c)*, *(d)* and *(e)* and returns them
+7. *(a)* possibly modifies the canvas from *(b)* and returns it
+
+Widgets *(a)*, *(b)* and *(e)* are called container widgets because they
+contain other widgets. Container widgets choose the size and position their
+contained widgets.
+
+Container widgets must also keep track of which one of their contained widgets
+is in focus. The focus is used when handling keyboard input. If in the above
+example *(b)* 's focus widget is *(e)* and *(e)* 's focus widget is
+*(f)* then keyboard input will be handled this way:
+
+1. The keypress is passed to the topmost widget *(a)*
+2. *(a)* passes the keypress to *(b)*
+3. *(b)* passes the keypress to *(e)*, its focus widget
+4. *(e)* passes the keypress to *(f)*, its focus widget
+5. *(f)* either handles the keypress or returns it
+6. *(e)* has an opportunity to handle the keypress if it was returned from
+   *(f)*
+7. *(b)* has an opportunity to handle the keypress if it was returned from
+   *(e)*
+8. *(a)* has an opportunity to handle the keypress if it was returned from
+   *(b)*
+
+Box, Flow and Fixed Widgets
+===========================
+
+The size of a widget is measured in screen columns and rows. Widgets that are
+given an exact number of screen columns and rows are called box widgets. The
+topmost widget is always a box widget.
+
+Much of the information displayed in a console user interface is text and the
+best way to display text is to have it flow from one screen row to the next.
+Widgets like this that require a variable number of screen rows are called flow
+widgets. Flow widgets are given a number of screen columns and can calculate
+how many screen rows they need.
+
+Occasionally it is also useful to have a widget that knows how many screen
+columns and rows it requires, regardless of the space available. This is
+called a fixed widget.
+
+It is an Urwid convention to use the variables :attr:`maxcol` and
+:attr:`maxrow` to store a widget's size. Box widgets require both of ``(maxcol,
+maxrow)`` to be specified.
+
+Flow widgets expect a single-element tuple ``(maxcol,)`` instead because they
+calculate their :attr:`maxrow` based on the :attr:`maxcol` value.
+
+Fixed widgets expect the value ``None`` to be passed in to functions that take
+a size because they know their :attr:`maxcol` and :attr:`maxrow` values.
diff --git a/docs/manual/widgetmethods.rst b/docs/manual/widgetmethods.rst
index b7ade07..f40df72 100644
--- a/docs/manual/widgetmethods.rst
+++ b/docs/manual/widgetmethods.rst
@@ -1,55 +1,55 @@
-.. _widget-methods:

-

-******************

-  Widget Methods  

-******************

-

-Widgets in Urwid are easiest to create by extending other widgets. If you are

-making a new type of widget that can use other widgets to display its content,

-like a new type of button or control, then you should start by extending

-:class:`~urwid.widget.WidgetWrap` and passing the display widget to its

-constructor.

-

-This section describes the :class:`~urwid.widget.Widget` interface in detail

-and is useful if you're looking to modify the behavior of an existing widget,

-build a new widget class from scratch or just want a better understanding of

-the library.

-

-One design choice that stands out is that widgets in Urwid typically have no

-size. Widgets don't store the size they will be displayed at, and instead are

-passed that information when they need it.

-

-This choice has some advantages:

-

-* widgets may be reused in different locations

-* reused widgets only need to be rendered once per size displayed

-* widgets don't need to know their parents

-* less data to store and update

-* no worrying about widgets that haven't received their size yet

-* same widgets could be displayed at different sizes to different users

-  simultaneously

-

-It also has disadvantages:

-

-* difficult to determine a widget's size on screen

-* more parameters to parse

-* duplicated size calculations across methods

-

-For determining a widget's size on screen it is possible to look up the size(s)

-it was rendered at in the :class:`~urwid.canvas.CanvasCache`. There are plans

-to address some of the duplicated size handling code in the container widgets

-in a future Urwid release.

-

-The same holds true for a widget's focus state, so that too is passed in to

-functions that need it.

-

-The :class:`~urwid.widget.Widget` base class has some metaclass magic that

-creates a :attr:`__super` attribute for calling your superclass:

-:attr:`self.__super` is the same as the usual ``super(MyClassName, self)``.

-

-.. seealso::

-

-    class :class:`.Widget`

-        Widget base class reference

-

-

+.. _widget-methods:
+
+******************
+  Widget Methods  
+******************
+
+Widgets in Urwid are easiest to create by extending other widgets. If you are
+making a new type of widget that can use other widgets to display its content,
+like a new type of button or control, then you should start by extending
+:class:`~urwid.widget.WidgetWrap` and passing the display widget to its
+constructor.
+
+This section describes the :class:`~urwid.widget.Widget` interface in detail
+and is useful if you're looking to modify the behavior of an existing widget,
+build a new widget class from scratch or just want a better understanding of
+the library.
+
+One design choice that stands out is that widgets in Urwid typically have no
+size. Widgets don't store the size they will be displayed at, and instead are
+passed that information when they need it.
+
+This choice has some advantages:
+
+* widgets may be reused in different locations
+* reused widgets only need to be rendered once per size displayed
+* widgets don't need to know their parents
+* less data to store and update
+* no worrying about widgets that haven't received their size yet
+* same widgets could be displayed at different sizes to different users
+  simultaneously
+
+It also has disadvantages:
+
+* difficult to determine a widget's size on screen
+* more parameters to parse
+* duplicated size calculations across methods
+
+For determining a widget's size on screen it is possible to look up the size(s)
+it was rendered at in the :class:`~urwid.canvas.CanvasCache`. There are plans
+to address some of the duplicated size handling code in the container widgets
+in a future Urwid release.
+
+The same holds true for a widget's focus state, so that too is passed in to
+functions that need it.
+
+The :class:`~urwid.widget.Widget` base class has some metaclass magic that
+creates a :attr:`__super` attribute for calling your superclass:
+:attr:`self.__super` is the same as the usual ``super(MyClassName, self)``.
+
+.. seealso::
+
+    class :class:`.Widget`
+        Widget base class reference
+
+