manual: work on display attribute, text encoding and text layout

--HG--
branch : feature-sphinx

5 files changed, 313 insertions, 181 deletions

diff --git a/docs/manual/displayattributes.rst b/docs/manual/displayattributes.rst
index 77f6fc7..1e11f55 100644
--- a/docs/manual/displayattributes.rst
+++ b/docs/manual/displayattributes.rst
@@ -1,55 +1,224 @@
 .. _display-attributes:
 
 **********************
-  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
+.. currentmodule:: urwid
+
+Urwid supports a number of common display attributes in monochrome, 16-color,
+88-color and 256-color modes.
+
+You are encouraged to provide support for as many of these modes as you like, while
+allowing your interface to degrade gracefully by  providing command line arguments
+or other interfaces to switch modes.
+
+When setting up a palette with :class:`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.
+:meth:`screen.set_terminal_properties() <raw_display.Screen.set_terminal_properties>`,
+where ``screen`` is your screen instance or :attr:`MainLoop.screen`.
 
-`register_palette reference <http://excess.org/urwid/reference.html#Screen-register_palette>`_
+.. seealso::
+   :meth:`register_palette() reference <BaseScreen.register_palette>`,
 
-`set_terminal_properties reference <http://excess.org/urwid/reference.html#Screen-set_terminal_properties>`_
+Using Display Attributes
+========================
 
-See also: RecommendedPalette.
+Once you have defined a palette you may use the its display attribute names
+anywhere that expects a display attribute.  When no display attribute is defined
+``None`` is used as a default display attribute.
 
-16 Standard Foreground Colors
-=============================
+``None`` will typically be rendered with the terminal's default foreground and
+background colors.
+
+You can also specify an exact foreground and background using an
+:class:`AttrSpec` instance instead of a display attribute name.
+Using :class:`AttrSpec` instances in your code may be trickier than using your
+screen's palette because you must know which mode (number of colors) the screen is in.
+
+.. _text-markup:
+
+Text Markup
+-----------
+
+A :class:`Text` widget can specify which display attributes each part of the
+text will use with the format defined in :class:`Text class reference <Text>`.
+Some examples:
+
+::
+
+    Text(u"a simple string with default attribute")
+
+The string and space around will use the ``None`` default display attribute
+which usually appears in the terminal's default foreground and background.
+
+::
+
+    Text(('attr1', u"a string in display 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 display attribute.
+
+::
+
+    Text([u"a simple string ", ('attr1', u"ending with attr1")])
+
+The first three words have the default display attribute and the last three words have
+display attribute ``'attr1'``.
+
+::
+
+    Text([('attr1', u"start in attr1 "), ('attr2', u"end in attr2")])
+
+The first three words have display attribute ``'attr1'`` and the last three words have
+display attribute ``'attr2'``.
+
+::
+
+    Text(('attr1', [u"nesting example ", ('attr2', u"inside"), u" 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'``.
+
+
+Assigning Display Attributes with AttrMap
+-----------------------------------------
+
+If you want a whole widget to be assigned a display attribute, or if you want to change
+one or more display attributes to other display attributes, you can wrap your widget
+in an :class:`AttrMap` widget.  :class:`Text` widgets have no way to specify
+a display attribute for the whitespace around the text caused by alignment and wrapping
+so :class:`AttrMap` may be used. Some examples:
 
-'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'
+::
+
+    AttrMap(Text(u"hello"), 'attr1')
+
+The whole :class:`Text` widget will have display attribute ``'attr1'`` including
+whitespace around the ``"hello"`` text.
+
+::
+
+    AttrMap(Text(('attr1', u"hello")), 'attr2')
+
+The ``u"hello"`` text will appear with display attribute ``'attr1'`` and all surrounding
+whitespace will appear with display attribute ``'attr2'``.
+
+::
+
+    AttrMap(Text([('attr1', u"hello"), u" world"]), {'attr1': 'attr2'})
+
+The :class:`AttrMap` widget will apply display attribute ``'attr2'`` to all parts of
+the :class:`Text` widget that are using ``'attr1'``.  The result is the ``"hello"``
+text appearing with display attribute ``'attr2'`` and all other text and whitespace
+appearing in the default display attribute.
+
+
+:class:`AttrMap` can also change display attributes differently when they are in focus.
+This can be used to "highlight" one or more widgets to make your interface more
+user friendly.  To use this feature set the ``focus_map`` parameter when creating the
+:class:`AttrMap` widget.
+
+
+Foreground and Background Settings
+==================================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 23 15 10 10 15
+
+   * - Supported by Terminal
+     - xterm / gnome-term
+     - rxvt
+     - linux console
+     - others
+   * - :ref:`16 standard foreground colors <16-standard-foreground>`
+     - YES
+     - YES
+     - YES
+     - very widely supported
+   * - :ref:`8 standard background colors <8-standard-background>`
+     - YES
+     - YES
+     - YES
+     - very widely supported
+   * - :ref:`default foreground/background <default-foreground-background>`
+     - YES
+     - YES
+     - YES
+     - widely supported
+   * - :ref:`bold, underline, standout <bold-underline-standout>`
+     - YES
+     - YES
+     - standout
+     - widely supported
+   * - :ref:`"bright" background colors <bright-background>`
+     - YES
+     - urxvt
+     -
+     - some support
+   * - :ref:`256-color foreground/background <256-foreground-background>`
+     - YES
+     -
+     -
+     - some support
+   * - :ref:`88-color foreground/background <88-foreground-background>`
+     - w/palette setting
+     - urxvt
+     -
+     - limited support
+   * - :ref:`RGB palette setting <rgb-palette-setting>`
+     - YES
+     -
+     -
+     - limited support
+
+
+.. _16-standard-foreground:
+
+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:
 
 8 Standard Background Colors
-============================
+----------------------------
 
-'black', 'dark red', 'dark green', 'brown', 'dark blue', 'dark magenta', 'dark
-cyan', 'light gray'
+* ``'black'``
+* ``'dark red'``
+* ``'dark green'``
+* ``'brown'``
+* ``'dark blue'``
+* ``'dark magenta'``
+* ``'dark cyan'``
+* ``'light gray'``
 
-Default Foreground/Background
-=============================
+.. _default-foreground-background:
+
+Default Foreground and Background
+---------------------------------
+
+* ``'default'`` (or simply ``''``)
 
 ``'default'`` may be specified as a foreground or background to use a
 terminal's default color. For terminals with transparent backgrounds
@@ -58,8 +227,14 @@ 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:
+
 Bold, Underline, Standout
-=========================
+-------------------------
+
+* ``'bold'``
+* ``'underline'``
+* ``'standout'``
 
 These settings may be tagged on to foreground colors using commas, eg: ``'light
 gray,underline,bold'``
@@ -70,70 +245,85 @@ 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.
+:meth:`BaseScreen.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.
 
-Standout is usually displayed as the foreground and background colors reversed.
+.. _bright-background:
 
 "Bright" Background Colors
-==========================
+--------------------------
+
+.. warning::
+   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'``.
 
-'dark gray', 'light red', 'light green', 'yellow', 'light blue', 'light
-magenta', 'light cyan', 'white'
+* ``'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
-===============================
+.. _256-foreground-background:
+
+256-Color Foreground and Background Colors
+------------------------------------------
 
-In 256-color mode you have the 16 basic colors, a 6x6x6 color cube and a gray
+In 256-color mode you have the 16 basic colors, a 6 * 6 * 6 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.
+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'.
+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'`` (black from color cube) , ``'g3'``, ``'g7'``, ...
+``'g100'`` (white from color cube).
 
-See also the palette_test.py example program
+.. seealso::
+   The ``palette_test.py`` example program
 
-.. todo: add link
 
-88-Color Foreground/Background
-==============================
+.. _88-foreground-background:
 
-In 88-color mode you have the 16 basic colors, a 4x4x4 color cube and a gray
+88-Color Foreground and Background Colors
+-----------------------------------------
+
+In 88-color mode you have the 16 basic colors, a 4 * 4 * 4 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.
+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'`` (black from color cube), ``'g19'``, ``'g35'``, ...
+``'g100'`` (white from color cube).
 
-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'.
+.. seealso::
+   The ``palette_test.py`` example program
 
-See also the palette_test.py example program
 
-.. todo: add link
+.. _rgb-palette-setting:
 
 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
+values with :meth:`raw_display.Screen.modify_terminal_palette`.
+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>`_
+:meth:`raw_display.Screen.reset_default_terminal_palette` is used to
+reset the palette in the ``palette_test.py`` example program when switching modes.
 
-`reset_default_terminal_palette reference <http://excess.org/urwid/reference.html#Screen-reset_default_terminal_palette>`_
diff --git a/docs/manual/index.rst b/docs/manual/index.rst
index 9308945..756ca52 100644
--- a/docs/manual/index.rst
+++ b/docs/manual/index.rst
@@ -5,7 +5,7 @@
 ################
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    overview
    mainloop
@@ -15,7 +15,6 @@
    textlayout
    textencodings
    displayattributes
-   textattributes
    listboxcontents
    canvascache
    eventloops
diff --git a/docs/manual/textattributes.rst b/docs/manual/textattributes.rst
deleted file mode 100644
index 53918e6..0000000
--- a/docs/manual/textattributes.rst
+++ /dev/null
@@ -1,59 +0,0 @@
-.. _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 ef5ca15..6c6ca45 100644
--- a/docs/manual/textencodings.rst
+++ b/docs/manual/textencodings.rst
@@ -3,9 +3,11 @@
 .. _text-encodings:
 
 ******************
-  Text Encodings  
+  Text Encodings
 ******************
 
+.. currentmodule:: urwid
+
 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.
@@ -23,11 +25,11 @@ 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_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.
+user will see mojibake 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
diff --git a/docs/manual/textlayout.rst b/docs/manual/textlayout.rst
index ff66a35..5fa86af 100644
--- a/docs/manual/textlayout.rst
+++ b/docs/manual/textlayout.rst
@@ -1,35 +1,35 @@
 .. _text-layout:
 
 ***************
-  Text Layout  
+  Text Layout
 ***************
 
+.. currentmodule:: urwid
+
 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
+layout. The :class:`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")
+    Text("Showing some different alignment modes", align=...)
 
-    align=LEFT (default)
+    align='left' (default)
     +----------------+   +------------------------+
     |Showing some    |   |Showing some different  |
     |different       |   |alignment modes         |
     |alignment modes |   +------------------------+
     +----------------+
 
-    align=CENTER
+    align='center'
     +----------------+   +------------------------+
     |  Showing some  |   | Showing some different |
     |   different    |   |    alignment modes     |
     |alignment modes |   +------------------------+
     +----------------+
 
-    align=RIGHT
+    align='right'
     +----------------+   +------------------------+
     |    Showing some|   |  Showing some different|
     |       different|   |         alignment modes|
@@ -38,9 +38,9 @@ characters, at any location, or clip text that is off the edge.
 
 ::
 
-    Text("Showing some different wrapping modes\nnewline")
+    Text("Showing some different wrapping modes\nnewline", wrap=...)
 
-    wrap=SPACE (default)
+    wrap='space' (default)
     +----------------+   +------------------------+
     |Showing some    |   |Showing some different  |
     |different       |   |wrapping modes          |
@@ -48,7 +48,7 @@ characters, at any location, or clip text that is off the edge.
     |newline         |   +------------------------+
     +----------------+
 
-    wrap=ANY
+    wrap='any'
     +----------------+   +------------------------+
     |Showing some dif|   |Showing some different w|
     |ferent wrapping |   |rapping modes           |
@@ -56,7 +56,7 @@ characters, at any location, or clip text that is off the edge.
     |newline         |   +------------------------+
     +----------------+
 
-    wrap=CLIP
+    wrap='clip'
     +----------------+   +------------------------+
     |Showing some dif|   |Showing some different w|
     |newline         |   |newline                 |
@@ -65,16 +65,36 @@ characters, at any location, or clip text that is off the edge.
 If this is good enough for your application feel free to skip the rest of this
 section.
 
+.. seealso::
+   :class:`Text widget reference <Text>`
+
+
+Custom Text Layouts
+===================
+
+The :class:`StandardTextLayout` is set as the class variable
+:attr:`Text.layout`. Individual :class:`Text`
+widgets may use a different layout class, or you can change the default by
+setting the :attr:`Text.layout` class variable itself.
+
+A custom text layout class should extend the
+:class:`TextLayout` base class and return text layout
+structures from its ``layout()`` method.
+
+.. seealso::
+   :class:`TextLayout reference <TextLayout>`
+
+
 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---10---15---20---25---30---35---40---45--
 
-    +0----5----0----5--+   right_aligned_text_layout = [
-    0     This is how a|     [(5, 0), (13, 0, 13)],
+    0----5---10---15---+   right_aligned_text_layout = [
+    |     This is how a|     [(5, 0), (13, 0, 13)],
     |    string of text|     [(4, 13), (14, 14, 28)],
     |might be displayed|     [(18, 29, 47)]
     +------------------+   ]
@@ -82,10 +102,10 @@ Text Layout Structures
 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`
+Text layout structures are used both for rendering :class:`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.
+:class:`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.
@@ -97,7 +117,7 @@ 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.
+Tuple A displays a segment of text from the :class:`Text` widget.
 Column width is explicitly specified because some characters within the text
 may be zero width or double width.
 
@@ -106,30 +126,10 @@ 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
+:class:`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).
+.. seealso::
+   :class:`TextLayout reference <TextLayout>`,
+   :class:`StandardTextLayout reference <StandardTextLayout>`
 
-`TextLayout reference <http://excess.org/urwid/reference.html#TextLayout>`_