[commit: haddock] T6018-injective-type-families, adamse-D1033, ghc-head, master, metainfo, wip/10268, wip/10313, wip/D538, wip/D538-1, wip/D538-2, wip/D538-3, wip/D538-4, wip/D538-5, wip/D538-6, wip/D548-master, wip/D548-master-2, wip/T10483, wip/T9840, wip/api-annot-tweaks-7.10, wip/api-annots-ghc-7.10-3, wip/orf-reboot: Allow an optional colon after the closing bracket of definition lists (122fe6e)

git at git.haskell.org git at git.haskell.org
Wed Jul 8 08:32:32 UTC 2015 

Repository : ssh://git@git.haskell.org/haddock

On branches: T6018-injective-type-families,adamse-D1033,ghc-head,master,metainfo,wip/10268,wip/10313,wip/D538,wip/D538-1,wip/D538-2,wip/D538-3,wip/D538-4,wip/D538-5,wip/D538-6,wip/D548-master,wip/D548-master-2,wip/T10483,wip/T9840,wip/api-annot-tweaks-7.10,wip/api-annots-ghc-7.10-3,wip/orf-reboot
Link       : http://git.haskell.org/haddock.git/commitdiff/122fe6edaeae55e77d606e6d57aa1904bbfb55c4

>---------------------------------------------------------------

commit 122fe6edaeae55e77d606e6d57aa1904bbfb55c4
Author: Simon Hengel <sol at typeful.net>
Date:   Sun Nov 2 12:19:38 2014 +0800

    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.


>---------------------------------------------------------------

122fe6edaeae55e77d606e6d57aa1904bbfb55c4
 CHANGES                                            |  4 +++
 doc/haddock.xml                                    | 13 +++----
 .../src/Documentation/Haddock/Parser.hs            |  2 +-
 .../test/Documentation/Haddock/ParserSpec.hs       | 42 ++++++++++++++--------
 4 files changed, 36 insertions(+), 25 deletions(-)

diff --git a/CHANGES b/CHANGES
index 4bfe492..352a739 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 ee77ede..618e19f 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 at .
+--   [@foo@]: The description of @foo at .
 --
---   [@bar@] The description of @bar at .
+--   [@bar@]: The description of @bar at .
 </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
-        “definition term” 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
+        “definition term” 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 ff03c7b..9901089 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 4373234..a228a95 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"]

More information about the ghc-commits mailing list