Documentation clarification.

Definition list terms starting with a hyphen need escaping.
Report by Pierre Ossman.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk/docutils@8850 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 26 insertions, 13 deletions

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 9ad40c57a..7d18dda03 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -330,6 +330,8 @@ than the marker.  For example, field lists may have very long markers
         body on the same line as the marker.
 
 
+.. _escape:
+
 Escaping Mechanism
 ==================
 
@@ -784,14 +786,24 @@ Doctree elements: definition_list_, definition_list_item_, term_,
 classifier_, definition_.
 
 Each definition list item contains a term, optional classifiers, and a
-definition.  A term is a simple one-line word or phrase.  Optional
-classifiers may follow the term on the same line, each after an inline
-" : " (space, colon, space).  A definition is a block indented
-relative to the term, and may contain multiple paragraphs and other
-body elements.  There may be no blank line between a term line and a
-definition block (this distinguishes definition lists from `block
-quotes`_).  Blank lines are required before the first and after the
-last definition list item, but are optional in-between.  For example::
+definition.
+
+* A `term` is a simple one-line word or phrase.  Escape_ a leading hyphen
+  to prevent recognition as an `option list`_ item.
+
+* Optional `classifiers` may follow the term on the same line, each after
+  an inline " : " (space, colon, space).  Inline markup is parsed in the
+  term line before the classifier delimiters are recognized.  A delimiter
+  will only be recognized if it appears outside of any inline markup.
+
+* A `definition` is a block indented relative to the term, and may
+  contain multiple paragraphs and other body elements.  There may be no
+  blank line between a term line and a definition block (this
+  distinguishes definition lists from `block quotes`_). Blank lines are
+  required before the first and after the last definition list item, but
+  are optional in-between.
+
+Example::
 
     term 1
         Definition 1.
@@ -807,9 +819,8 @@ last definition list item, but are optional in-between.  For example::
     term 4 : classifier one : classifier two
         Definition 4.
 
-Inline markup is parsed in the term line before the classifier
-delimiter (" : ") is recognized.  The delimiter will only be
-recognized if it appears outside of any inline markup.
+    \-term 5
+        Without escaping, this would be an option list item.
 
 A definition list may be used in various ways, including:
 
@@ -1001,6 +1012,7 @@ The RCS keyword processing only kicks in when the field list is in
 bibliographic context (first non-comment construct in the document,
 after a document title if there is one).
 
+.. _option list:
 
 Option Lists
 ------------
@@ -1078,8 +1090,9 @@ Multiple option "synonyms" may be listed, sharing a single
 description.  They must be separated by comma-space.
 
 There must be at least two spaces between the option(s) and the
-description.  The description may contain multiple body elements.  The
-first line after the option marker determines the indentation of the
+description (which can also start on the next line).  The description
+may contain multiple body elements.
+The first line after the option marker determines the indentation of the
 description.  As with other types of lists, blank lines are required
 before the first option list item and after the last, but are optional
 between option entries.