Merge pull request #199 from willmcgugan/markup-color

color parsing

docs/source/markup.rst

@@ -38,16 +38,13 @@ If your terminal software supports hyperlinks, you will be able to click the wor
 Escaping
 ~~~~~~~~
 
-Occasionally you may want to print something that Rich would interpret as markup. You can *escape* square brackets by doubling them up. Here's an example::
+Occasionally you may want to print something that Rich would interpret as markup. You can *escape* a tab by preceding it with backslash. Here's an example::
 
     >>> from rich import print
-    >>> print("foo[[bar]]")
+    >>> print("foo\[bar]")
     foo[bar]
 
-The function :func:`~rich.markup.escape` will handle escape of text for you.
-
-.. warning::
-    Be careful when using f-strings with console markup. You will need to escape any variables if they could contain square brackets.
+The function :func:`~rich.markup.escape` will handle escaping of text for you.
 
 Rendering Markup
 ----------------

docs/source/style.rst

@@ -16,9 +16,9 @@ To specify a foreground color use one of the 256 :ref:`appendix-colors`. For exa
 
     console.print("Hello", style="magenta")
 
-You may also use the color's number (an integer between 0 and 255). The following will give the equivalent output::
+You may also use the color's number (an integer between 0 and 255) with the syntax `"color(<number>)"`. The following will give the equivalent output::
 
-    console.print("Hello", style="5")
+    console.print("Hello", style="color(5)")
 
 Alteratively you can use a CSS-like syntax to specify a color with a "#" followed by three pairs of hex characters, or in RGB form with three decimal integers. The following two lines both print "Hello" in the same color (purple)::
 
@@ -116,6 +116,10 @@ You can also use these custom styles via markup. For example::
 
     console.print("[warning]The pod bay doors are locked[/warning]")
 
+
+.. note::
+    style names must be lower case, start with a letter, and only contain letters or the characters ``"."``, ``"-"``, ``"_"``.
+
 If you prefer you can write your styles in an external config file rather than in Python. Here's an example of the format::
 
     [styles]

docs/source/text.rst

@@ -27,3 +27,24 @@ Since building Text instances from parts is a common requirement, Rich offers :m
     console.print(text)
 
 You can apply a style to given words in the text with :meth:`~rich.text.Text.highlight_words` or for ultimate control call :meth:`~rich.text.Text.highlight_regex` to highlight text matching a *regular expression*. 
+
+
+Text attributes
+~~~~~~~~~~~~~~~
+
+The Text class has a number of parameters you can set on the constructor to modify how the text is display.
+
+- ``justify`` should be "left", "center", "right", or "full", and will override default justify behaviour if set.
+- ``overflow`` should be "fold", "crop", or "ellipsis" and will override default overflow if set.
+- ``no_wrap`` prevents wrapping if the text is longer then the available width.
+- ``tab_size`` Sets the number of characters in a tab.
+
+A Text instance may be used in place of a plain string virtually everywhere in the Rich API, which gives you a lot of control in how text is displays within other Rich renderables. For instance, the following right aligns text within a :class:`rich.panel.Panel`::
+
+    from rich import print
+    from rich.panel import Panel
+    from rich.text import Text
+    panel = Panel(Text("Hello", justify="right"))
+    print(panel)
+
+