changeset 22772:b186b3ef4b54

color: reorganise and sectionify the help text

The color docstring was getting long. This splits it up into
bite-sized sections and rearranges the order of the paragraphs a
little to match these sections.

--- a/hgext/color.py	Mon Oct 06 08:16:40 2014 -0400
+++ b/hgext/color.py	Mon Oct 06 08:18:03 2014 -0400
@@ -13,12 +13,25 @@
 other commands have analogous colors. It is possible to customize
 these colors.
 
+Effects
+-------
+
 Other effects in addition to color, like bold and underlined text, are
 also available. By default, the terminfo database is used to find the
 terminal codes used to change color and effect.  If terminfo is not
 available, then effects are rendered with the ECMA-48 SGR control
 function (aka ANSI escape codes).
 
+The available effects in terminfo mode are 'blink', 'bold', 'dim',
+'inverse', 'invisible', 'italic', 'standout', and 'underline'; in
+ECMA-48 mode, the options are 'bold', 'inverse', 'italic', and
+'underline'.  How each is rendered depends on the terminal emulator.
+Some may not be available for a given terminal type, and will be
+silently ignored.
+
+Labels
+------
+
 Text receives color effects depending on the labels that it has. Many
 default Mercurial commands emit labelled text. You can also define
 your own labels in templates using the label function, see :hg:`help
@@ -90,20 +103,8 @@
 
   histedit.remaining = red bold
 
-The available effects in terminfo mode are 'blink', 'bold', 'dim',
-'inverse', 'invisible', 'italic', 'standout', and 'underline'; in
-ECMA-48 mode, the options are 'bold', 'inverse', 'italic', and
-'underline'.  How each is rendered depends on the terminal emulator.
-Some may not be available for a given terminal type, and will be
-silently ignored.
-
-Note that on some systems, terminfo mode may cause problems when using
-color with the pager extension and less -R. less with the -R option
-will only display ECMA-48 color codes, and terminfo mode may sometimes
-emit codes that less doesn't understand. You can work around this by
-either using ansi mode (or auto mode), or by using less -r (which will
-pass through all terminal control codes, not just color control
-codes).
+Custom colors
+-------------
 
 Because there are only eight standard colors, this module allows you
 to define color names for other color slots which might be available
@@ -119,6 +120,9 @@
 defined colors may then be used as any of the pre-defined eight,
 including appending '_background' to set the background to that color.
 
+Modes
+-----
+
 By default, the color extension will use ANSI mode (or win32 mode on
 Windows) if it detects a terminal. To override auto mode (to enable
 terminfo mode, for example), set the following configuration option::
@@ -128,6 +132,14 @@
 
 Any value other than 'ansi', 'win32', 'terminfo', or 'auto' will
 disable color.
+
+Note that on some systems, terminfo mode may cause problems when using
+color with the pager extension and less -R. less with the -R option
+will only display ECMA-48 color codes, and terminfo mode may sometimes
+emit codes that less doesn't understand. You can work around this by
+either using ansi mode (or auto mode), or by using less -r (which will
+pass through all terminal control codes, not just color control
+codes).
 '''
 
 import os