[PATCH 2 of 2] color: reorganise and sectionify the help text

[Jordi Gutiérrez Hermoso]

# HG changeset patch
# User Jordi Gutiérrez Hermoso <jordigh at octave.org>
# Date 1412597883 14400
#      Mon Oct 06 08:18:03 2014 -0400
# Node ID f882960cd0e66920874d5d163b9fe583ca0ed6bb
# Parent  d81f747d2c71ee3f81956f6d2872002719b2bb53
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.

diff --git a/hgext/color.py b/hgext/color.py
--- a/hgext/color.py
+++ b/hgext/color.py
@@ -13,12 +13,25 @@ in red, while the status command shows m
 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 @@ effects may be overridden from your conf
 
   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 @@ that have brighter colors defined in the
 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 @@ terminfo mode, for example), set the fol
 
 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