Document the use of `org-list-demote-modify-bullet'.

* doc/org.texi (Plain lists): Document
`org-list-demote-modify-bullet'.

* lisp/org-list.el (org-list-demote-modify-bullet): Improve docstring
by showing an example.

This change was triggered by a request by Livin Stephen Sharma.

2 files changed, 28 insertions, 1 deletions

diff --git a/doc/org.texi b/doc/org.texi
index ad8f74c..37255fc 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -1273,6 +1273,11 @@ properly (@pxref{Exporting}).  Since indentation is what governs the
 structure of these lists, many structural constructs like @code{#+BEGIN_...}
 blocks can be indented to signal that they should be part of a list item.
 
+@vindex org-list-demote-modify-bullet
+If you find that using a different bullet for a sub-list (than that used for
+the current list-level) improves readability, customize the variable
+@code{org-list-demote-modify-bullet}.
+
 The following commands act on items when the cursor is in the first line
 of an item (the line with the bullet or number).
 
diff --git a/lisp/org-list.el b/lisp/org-list.el
index 417061f..938391d 100644
--- a/lisp/org-list.el
+++ b/lisp/org-list.el
@@ -86,7 +86,29 @@ heading will be exposed in a children' view."
 (defcustom org-list-demote-modify-bullet nil
   "Default bullet type installed when demoting an item.
 This is an association list, for each bullet type, this alist will point
-to the bullet that should be used when this item is demoted."
+to the bullet that should be used when this item is demoted.
+For example,
+
+ (setq org-list-demote-modify-bullet
+       '((\"+\" . \"-\") (\"-\" . \"+\") (\"*\" . \"+\")))
+
+will make
+
+  + Movies
+    + Silence of the Lambs
+    + My Cousin Vinny
+  + Books
+    + The Hunt for Red October
+    + The Road to Omaha
+
+into
+
+  + Movies
+    - Silence of the Lambs
+    - My Cousin Vinny
+  + Books
+    - The Hunt for Red October
+    - The Road to Omaha"
   :group 'org-plain-lists
   :type '(repeat
 	  (cons