From 3f50b955324bd4b42f88a421f0203bc46a3ccf64 Mon Sep 17 00:00:00 2001
From: Dominic Steinitz <dominic@steinitz.org>
Date: Sat, 16 May 2015 13:53:14 +0100
Subject: Fix the documentation for haddock itself.

Change notation and add support for inline math.

Allow newlines in display math.

Add a command line option for the mathjax url (you might want to use a
locally installed version).

Rebase tests because of extra url and version change.

Respond to (some of the) comments.

Fix warnings in InterfaceFile.hs
---
 .../src/Documentation/Haddock/Parser.hs            | 24 ++++++++++++++--------
 haddock-library/src/Documentation/Haddock/Types.hs |  1 +
 .../test/Documentation/Haddock/ParserSpec.hs       |  4 ++++
 3 files changed, 20 insertions(+), 9 deletions(-)

(limited to 'haddock-library')

diff --git a/haddock-library/src/Documentation/Haddock/Parser.hs b/haddock-library/src/Documentation/Haddock/Parser.hs
index 919ea37f..123f5612 100644
--- a/haddock-library/src/Documentation/Haddock/Parser.hs
+++ b/haddock-library/src/Documentation/Haddock/Parser.hs
@@ -74,6 +74,7 @@ overIdentifier f d = g d
     g (DocHyperlink x) = DocHyperlink x
     g (DocPic x) = DocPic x
     g (DocMathInline x) = DocMathInline x
+    g (DocMathDisplay x) = DocMathDisplay x
     g (DocAName x) = DocAName x
     g (DocProperty x) = DocProperty x
     g (DocExamples x) = DocExamples x
@@ -114,7 +115,8 @@ parseStringBS = snd . parse p
   where
     p :: Parser (DocH mod Identifier)
     p = docConcat <$> many (monospace <|> anchor <|> identifier <|> moduleName
-                            <|> picture <|> mathDisplay <|> markdownImage
+                            <|> picture <|> mathDisplay <|> mathInline
+                            <|> markdownImage
                             <|> hyperlink <|> bold
                             <|> emphasis <|> encodedChar <|> string'
                             <|> skipSpecialChar)
@@ -226,17 +228,21 @@ picture :: Parser (DocH mod a)
 picture = DocPic . makeLabeled Picture . decodeUtf8
           <$> disallowNewline ("<<" *> takeUntil ">>")
 
--- FIXME: I have just copied the code for `picture` but it is not
--- clear why we should disallow a newline (if that is what
--- `disallowNewline` does)
+-- | Inline math parser, surrounded by \\( and \\).
+--
+-- >>> parseString "\\(\\int_{-\\infty}^{\\infty} e^{-x^2/2} = \\sqrt{2\\pi}\\)"
+-- DocMathInline "\\int_{-\\infty}^{\\infty} e^{-x^2/2} = \\sqrt{2\\pi}"
+mathInline :: Parser (DocH mod a)
+mathInline = DocMathInline . decodeUtf8
+             <$> disallowNewline  ("\\(" *> takeUntil "\\)")
 
--- | Inline math parser, surrounded by \$\$ and \$\$.
+-- | Display math parser, surrounded by \\[ and \\].
 --
--- >>> parseString "$$\int_{-infty}^{infty} e^{-x^2/2} = \sqrt{2\pi}$$"
--- DocMathInline (DocString "\int_{-infty}^{infty} e^{-x^2/2} = \sqrt{2\pi}")
+-- >>> parseString "\\[\\int_{-\\infty}^{\\infty} e^{-x^2/2} = \\sqrt{2\\pi}\\]"
+-- DocMathDisplay "\\int_{-\\infty}^{\\infty} e^{-x^2/2} = \\sqrt{2\\pi}"
 mathDisplay :: Parser (DocH mod a)
-mathDisplay = DocMathInline . decodeUtf8
-              <$> disallowNewline  ("$$" *> takeUntil "$$")
+mathDisplay = DocMathDisplay . decodeUtf8
+              <$> ("\\[" *> takeUntil "\\]")
 
 markdownImage :: Parser (DocH mod a)
 markdownImage = fromHyperlink <$> ("!" *> linkParser)
diff --git a/haddock-library/src/Documentation/Haddock/Types.hs b/haddock-library/src/Documentation/Haddock/Types.hs
index 2b1e7f26..4d5bb68a 100644
--- a/haddock-library/src/Documentation/Haddock/Types.hs
+++ b/haddock-library/src/Documentation/Haddock/Types.hs
@@ -72,6 +72,7 @@ data DocH mod id
   | DocHyperlink Hyperlink
   | DocPic Picture
   | DocMathInline String
+  | DocMathDisplay String
   | DocAName String
   | DocProperty String
   | DocExamples [Example]
diff --git a/haddock-library/test/Documentation/Haddock/ParserSpec.hs b/haddock-library/test/Documentation/Haddock/ParserSpec.hs
index 2ef414fb..1169eb49 100644
--- a/haddock-library/test/Documentation/Haddock/ParserSpec.hs
+++ b/haddock-library/test/Documentation/Haddock/ParserSpec.hs
@@ -208,6 +208,10 @@ spec = do
       it "supports title for deprecated picture syntax" $ do
         "<<b a z>>" `shouldParseTo` image "b" "a z"
 
+    context "when parsing display math" $ do
+
+      it "accepts markdown syntax for display math containing newlines" $ do
+         "\\[\\pi\n\\pi\\]" `shouldParseTo` DocMathDisplay "\\pi\n\\pi"
 
     context "when parsing anchors" $ do
       it "parses a single word anchor" $ do
-- 
cgit v1.2.3