Allow an optional colon after the closing bracket of definition lists

This is to disambiguate them from markdown links and will be require
with a future release.

4 files changed, 36 insertions, 25 deletions

diff --git a/CHANGES b/CHANGES
index 4bfe492c..352a739b 100644
--- a/CHANGES
+++ b/CHANGES
@@ -4,6 +4,10 @@ Changes in version 2.15.1
 
  * Add support for markdown links and images
 
+ * Allow an optional colon after the closing bracket of definition lists.
+   This is to disambiguate them from markdown links and will be require with a
+   future release.
+
 Changes in version 2.15.0
 
  * Always read in prologue files as UTF8 (#286 and Cabal #1721)
diff --git a/doc/haddock.xml b/doc/haddock.xml
index ee77ede9..618e19f2 100644
--- a/doc/haddock.xml
+++ b/doc/haddock.xml
@@ -2038,9 +2038,9 @@ This belongs to the list above!
 <programlisting>
 -- | This is a definition list:
 --
---   [@foo@] The description of @foo@.
+--   [@foo@]: The description of @foo@.
 --
---   [@bar@] The description of @bar@.
+--   [@bar@]: The description of @bar@.
 </programlisting>
 
         <para>To produce output something like this:</para>
@@ -2061,13 +2061,8 @@ This belongs to the list above!
         </variablelist>
 
         <para>Each paragraph should be preceded by the
-        &ldquo;definition term&rdquo; enclosed in square brackets.
-        The square bracket characters have no special meaning outside
-        the beginning of a definition paragraph.  That is, if a
-        paragraph begins with a <literal>[</literal> character, then
-        it is assumed to be a definition paragraph, and the next
-        <literal>]</literal> character found will close the definition
-        term.  Other markup operators may be used freely within the
+        &ldquo;definition term&rdquo; enclosed in square brackets and followed by a colon.
+        Other markup operators may be used freely within the
         definition term. You can escape <literal>]</literal> with a backslash as usual.</para>
 
       <para>Same rules about nesting and no newline separation as for bulleted and numbered lists apply.
diff --git a/haddock-library/src/Documentation/Haddock/Parser.hs b/haddock-library/src/Documentation/Haddock/Parser.hs
index ff03c7bb..99010897 100644
--- a/haddock-library/src/Documentation/Haddock/Parser.hs
+++ b/haddock-library/src/Documentation/Haddock/Parser.hs
@@ -294,7 +294,7 @@ definitionList :: Parser (DocH mod Identifier)
 definitionList = DocDefList <$> p
   where
     p = do
-      label <- "[" *> (parseStringBS <$> takeWhile1 (`notElem` "]\n")) <* "]"
+      label <- "[" *> (parseStringBS <$> takeWhile1 (`notElem` "]\n")) <* ("]" <* optional ":")
       c <- takeLine
       (cs, items) <- more p
       let contents = parseString . dropNLs . unlines $ c : cs
diff --git a/haddock-library/test/Documentation/Haddock/ParserSpec.hs b/haddock-library/test/Documentation/Haddock/ParserSpec.hs
index 4373234c..a228a956 100644
--- a/haddock-library/test/Documentation/Haddock/ParserSpec.hs
+++ b/haddock-library/test/Documentation/Haddock/ParserSpec.hs
@@ -646,7 +646,7 @@ spec = do
 
 
       it "can nest definition lists" $ do
-        "[a] foo\n\n    [b] bar\n\n        [c] baz\n        qux" `shouldParseTo`
+        "[a]: foo\n\n    [b]: bar\n\n        [c]: baz\n        qux" `shouldParseTo`
           DocDefList [ ("a", "foo"
                              <> DocDefList [ ("b", "bar"
                                                    <> DocDefList [("c", "baz\nqux")])
@@ -661,7 +661,7 @@ spec = do
           <> DocOrderedList [ DocParagraph "baz" ]
 
       it "definition lists can come back to top level with a different list" $ do
-        "[foo] foov\n\n    [bar] barv\n\n1. baz" `shouldParseTo`
+        "[foo]: foov\n\n    [bar]: barv\n\n1. baz" `shouldParseTo`
           DocDefList [ ("foo", "foov"
                                <> DocDefList [ ("bar", "barv") ])
                      ]
@@ -809,9 +809,9 @@ spec = do
     context "when parsing definition lists" $ do
       it "parses a simple list" $ do
         unlines [
-            " [foo] one"
-          , " [bar] two"
-          , " [baz] three"
+            " [foo]: one"
+          , " [bar]: two"
+          , " [baz]: three"
           ]
         `shouldParseTo` DocDefList [
             ("foo", "one")
@@ -821,9 +821,9 @@ spec = do
 
       it "ignores empty lines between list items" $ do
         unlines [
-            "[foo] one"
+            "[foo]: one"
           , ""
-          , "[bar] two"
+          , "[bar]: two"
           ]
         `shouldParseTo` DocDefList [
             ("foo", "one")
@@ -831,13 +831,13 @@ spec = do
           ]
 
       it "accepts an empty list item" $ do
-        "[foo]" `shouldParseTo` DocDefList [("foo", DocEmpty)]
+        "[foo]:" `shouldParseTo` DocDefList [("foo", DocEmpty)]
 
       it "accepts multi-line list items" $ do
         unlines [
-            "[foo] point one"
+            "[foo]: point one"
           , "  more one"
-          , "[bar] point two"
+          , "[bar]: point two"
           , "more two"
           ]
         `shouldParseTo` DocDefList [
@@ -846,21 +846,33 @@ spec = do
           ]
 
       it "accepts markup in list items" $ do
-        "[foo] /foo/" `shouldParseTo` DocDefList [("foo", DocEmphasis "foo")]
+        "[foo]: /foo/" `shouldParseTo` DocDefList [("foo", DocEmphasis "foo")]
 
       it "accepts markup for the label" $ do
-        "[/foo/] bar" `shouldParseTo` DocDefList [(DocEmphasis "foo", "bar")]
+        "[/foo/]: bar" `shouldParseTo` DocDefList [(DocEmphasis "foo", "bar")]
 
       it "requires empty lines between list and other paragraphs" $ do
         unlines [
             "foo"
           , ""
-          , "[foo] bar"
+          , "[foo]: bar"
           , ""
           , "baz"
           ]
         `shouldParseTo` DocParagraph "foo" <> DocDefList [("foo", "bar")] <> DocParagraph "baz"
 
+      it "dose not require the colon (deprecated - this will be removed in a future release)" $ do
+        unlines [
+            " [foo] one"
+          , " [bar] two"
+          , " [baz] three"
+          ]
+        `shouldParseTo` DocDefList [
+            ("foo", "one")
+          , ("bar", "two")
+          , ("baz", "three")
+          ]
+
     context "when parsing consecutive paragraphs" $ do
       it "will not capture irrelevant consecutive lists" $ do
         unlines [ "   * bullet"
@@ -873,9 +885,9 @@ spec = do
                 , " "
                 , "   2. different bullet"
                 , "   "
-                , "   [cat] kitten"
+                , "   [cat]: kitten"
                 , "   "
-                , "   [pineapple] fruit"
+                , "   [pineapple]: fruit"
                 ] `shouldParseTo`
           DocUnorderedList [ DocParagraph "bullet"
                            , DocParagraph "different bullet"]