diff options
| -rw-r--r-- | CHANGES | 2 | ||||
| -rw-r--r-- | doc/haddock.xml | 19 | ||||
| -rw-r--r-- | haddock-library/src/Documentation/Haddock/Parser.hs | 12 | ||||
| -rw-r--r-- | haddock-library/test/Documentation/Haddock/ParserSpec.hs | 24 |
4 files changed, 34 insertions, 23 deletions
@@ -2,6 +2,8 @@ Changes in version 2.15.1 * Experimental collapsible header support (#335) + * Add support for markdown links and images + 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 1fece5b3..ee77ede9 100644 --- a/doc/haddock.xml +++ b/doc/haddock.xml @@ -2118,17 +2118,20 @@ This belongs to the list above! <section> <title>Images</title> + <para> + Haddock supports Markdown syntax for inline images. This resembles + the syntax for links, but starts with an exclamation mark. An + example looks like this: + </para> - <para>An image can be included in a documentation comment by - surrounding it in double angle brackets: - <literal><<...>></literal>. If the output format supports - it, the image will be rendered inside the documentation.</para> - - <para>Title text can be included using an optional label:</para> <programlisting> -<<pathtoimage.png title>> + </programlisting> - + <para> + If the output format supports it, the image will be rendered inside + the documentation. The image description is used as relpacement text + and/or image title. + </para> </section> <section> diff --git a/haddock-library/src/Documentation/Haddock/Parser.hs b/haddock-library/src/Documentation/Haddock/Parser.hs index f1fd5dda..ff03c7bb 100644 --- a/haddock-library/src/Documentation/Haddock/Parser.hs +++ b/haddock-library/src/Documentation/Haddock/Parser.hs @@ -102,7 +102,7 @@ parseStringBS = parse p where p :: Parser (DocH mod Identifier) p = docConcat <$> many (monospace <|> anchor <|> identifier <|> moduleName - <|> picture <|> hyperlink <|> bold + <|> picture <|> markdownImage <|> hyperlink <|> bold <|> emphasis <|> encodedChar <|> string' <|> skipSpecialChar) @@ -209,6 +209,11 @@ picture :: Parser (DocH mod a) picture = DocPic . makeLabeled Picture . decodeUtf8 <$> disallowNewline ("<<" *> takeUntil ">>") +markdownImage :: Parser (DocH mod a) +markdownImage = fromHyperlink <$> ("!" *> linkParser) + where + fromHyperlink (Hyperlink url label) = DocPic (Picture url label) + -- | Paragraph parser, called by 'parseParas'. paragraph :: Parser (DocH mod Identifier) paragraph = examples <|> skipSpace *> ( @@ -467,7 +472,10 @@ hyperlink = DocHyperlink . makeLabeled Hyperlink . decodeUtf8 <|> markdownLink markdownLink :: Parser (DocH mod a) -markdownLink = DocHyperlink <$> (flip Hyperlink <$> label <*> (whitespace *> url)) +markdownLink = DocHyperlink <$> linkParser + +linkParser :: Parser Hyperlink +linkParser = flip Hyperlink <$> label <*> (whitespace *> url) where label :: Parser (Maybe String) label = Just . strip . decode <$> ("[" *> takeUntil "]") diff --git a/haddock-library/test/Documentation/Haddock/ParserSpec.hs b/haddock-library/test/Documentation/Haddock/ParserSpec.hs index 6d152ee2..4373234c 100644 --- a/haddock-library/test/Documentation/Haddock/ParserSpec.hs +++ b/haddock-library/test/Documentation/Haddock/ParserSpec.hs @@ -183,24 +183,22 @@ spec = do "foo https://example.com/example bar" `shouldParseTo` "foo " <> hyperlink "https://example.com/example" Nothing <> " bar" - context "when parsing pictures" $ do - let picture :: String -> Maybe String -> Doc String - picture uri = DocPic . Picture uri + context "when parsing images" $ do + let image :: String -> Maybe String -> Doc String + image uri = DocPic . Picture uri - it "parses a simple picture" $ do - "<<baz>>" `shouldParseTo` picture "baz" Nothing + it "accepts markdown syntax for images" $ do + "" `shouldParseTo` image "url" "label" - it "parses a picture with a title" $ do - "<<b a z>>" `shouldParseTo` picture "b" (Just "a z") + it "accepts Unicode" $ do + "" `shouldParseTo` image "url" "灼眼のシャナ" - it "parses a picture with unicode" $ do - "<<灼眼のシャナ>>" `shouldParseTo` picture "灼眼のシャナ" Nothing + it "supports deprecated picture syntax" $ do + "<<baz>>" `shouldParseTo` image "baz" Nothing - it "allows for escaping of the closing tags" $ do - "<<ba\\>>z>>" `shouldParseTo` picture "ba>>z" Nothing + it "supports title for deprecated picture syntax" $ do + "<<b a z>>" `shouldParseTo` image "b" "a z" - it "doesn't allow for multi-line picture tags" $ do - "<<ba\nz aar>>" `shouldParseTo` "<<ba\nz aar>>" context "when parsing anchors" $ do it "parses a single word anchor" $ do |