Markdown reader: revised definition list syntax (closes #1429).

* This change brings pandoc's definition list syntax into alignment
  with that used in PHP markdown extra and multimarkdown (with the
  exception that pandoc is more flexible about the definition markers,
  allowing tildes as well as colons).

* Lazily wrapped definitions are now allowed; blank space is required
  between list items; and the space before definition is used to
  determine whether it is a paragraph or a "plain" element.

* For backwards compatibility, a new extension,
  `compact_definition_lists`, has been added that restores the behavior
  of pandoc 1.12.x, allowing tight definition lists with no blank space
  between items, and disallowing lazy wrapping.

1 files changed, 55 insertions, 13 deletions

diff --git a/README b/README
index 991c2756d..82f3f6615 100644
--- a/README
+++ b/README
@@ -1437,8 +1437,8 @@ If default list markers are desired, use `#.`:
 
 **Extension: `definition_lists`**
 
-Pandoc supports definition lists, using a syntax inspired by
-[PHP Markdown Extra] and [reStructuredText]:[^3]
+Pandoc supports definition lists, using the syntax of
+[PHP Markdown Extra] with some extensions.[^3]
 
     Term 1
 
@@ -1455,25 +1455,41 @@ Pandoc supports definition lists, using a syntax inspired by
 Each term must fit on one line, which may optionally be followed by
 a blank line, and must be followed by one or more definitions.
 A definition begins with a colon or tilde, which may be indented one
-or two spaces. The body of the definition (including the first line,
-aside from the colon or tilde) should be indented four spaces. A term may have
-multiple definitions, and each definition may consist of one or more block
-elements (paragraph, code block, list, etc.), each indented four spaces or one
-tab stop.
-
-If you leave space after the definition (as in the example above),
-the blocks of the definitions will be considered paragraphs. In some
+or two spaces.
+
+A term may have multiple definitions, and each definition may consist of one or
+more block elements (paragraph, code block, list, etc.), each indented four
+spaces or one tab stop.  The body of the definition (including the first line,
+aside from the colon or tilde) should be indented four spaces. However,
+as with other markdown lists, you can "lazily" omit indentation except
+at the beginning of a paragraph or other block element:
+
+    Term 1
+
+    :   Definition
+    with lazy continuation.
+
+        Second paragraph of the definition.
+
+If you leave space before the definition (as in the example above),
+the text of the definition will be treated as a paragraph.  In some
 output formats, this will mean greater spacing between term/definition
-pairs. For a compact definition list, do not leave space between the
-definition and the next term:
+pairs. For a more compact definition list, omit the space before the
+definition:
 
     Term 1
       ~ Definition 1
+
     Term 2
       ~ Definition 2a
       ~ Definition 2b
 
-[^3]:  I have also been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html).
+Note that space between items in a definition list is required.
+(A variant that loosens this requirement, but disallows "lazy"
+hard wrapping, can be activated with `compact_definition_lists`: see
+[Non-pandoc extensions](#non-pandoc-extensions), below.)
+
+[^3]:  I have been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html).
 
 [PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/
 
@@ -2629,6 +2645,32 @@ these, so they are presently just ignored.
 Parses multimarkdown style header identifiers (in square brackets,
 after the header but before any trailing `#`s in an ATX header).
 
+**Extension: `compact_definition_lists`**\
+Activates the definition list syntax of pandoc 1.12.x and earlier.
+This syntax differs from the one described [above](#definition-lists)
+in several respects:
+
+  - No blank line is required between consecutive items of the
+    definition list.
+  - To get a "tight" or "compact" list, omit space between consecutive
+    items; the space between a term and its definition does not affect
+    anything.
+  - Lazy wrapping of paragraphs is not allowed:  the entire definition must
+    be indented four spaces.[^6]
+
+[^6]:  To see why laziness is incompatible with relaxing the requirement
+    of a blank line between items, consider the following example:
+
+        bar
+        :    definition
+        foo
+        :    definition
+
+    Is this a single list item with two definitions of "bar," the first of
+    which is lazily wrapped, or two list items?  To remove the ambiguity
+    we must either disallow lazy wrapping or require a blank line between
+    list items.
+
 Markdown variants
 -----------------