From e06c1c255377e5245748f4c4003240815deae72f Mon Sep 17 00:00:00 2001 From: Steve Hart Date: Tue, 12 Apr 2022 07:29:46 -0400 Subject: Parse Markdown links at beginning of line within a paragraph (#1470) * Catch Markdown links at beginning of line within paragraph Per Issue #774, Markdown links were being parsed as ordinary text when they occurred at the beginning of a line other than the first line of the paragraph. This occurred because the parser was not interpreting a left square bracket as a special character that could delimit special markup. A space character was considered a special character, so, if a space occurred at the beginning of the new line, then the parser would interpret the space by itself and then continue parsing, thereby catching the Markdown link. '\n' was not treated as a special character, so the parser did not catch a Markdown link that may have followed. Note that this will allow for Markdown links that are not surrounded by spaces. For example, the following text includes a Markdown link that will be parsed: Hello, world[label](url) This is consistent with how the parser handles other types of markup. * Remove obsolete documentation hint Commit 6b9aeafddf20efc65d3725c16e3fc43a20aac343 should eliminate the need for the workaround suggested in the documentation. --- doc/markup.rst | 11 ------ .../src/Documentation/Haddock/Parser.hs | 2 +- .../test/Documentation/Haddock/ParserSpec.hs | 46 +++++++++++++--------- 3 files changed, 29 insertions(+), 30 deletions(-) diff --git a/doc/markup.rst b/doc/markup.rst index abfeb52a..73ec22fd 100644 --- a/doc/markup.rst +++ b/doc/markup.rst @@ -1126,17 +1126,6 @@ followed by the URL enclosed in regular parentheses, for example: :: The link text is used as a description for the URL if the output format supports it. - -Hint: There's a `known issue `_ -that any inline link at the beginning of a line within a multi-line comment -isn't rendered correctly: :: - - {-| Some multi-line comment that has a - [link](https://example.com) and a - [reference link]: https://example.com - -} - -Adding a space or a word in front of such a link can be used as a workaround. Images ~~~~~~ diff --git a/haddock-library/src/Documentation/Haddock/Parser.hs b/haddock-library/src/Documentation/Haddock/Parser.hs index fa15c275..c6d7e59b 100644 --- a/haddock-library/src/Documentation/Haddock/Parser.hs +++ b/haddock-library/src/Documentation/Haddock/Parser.hs @@ -173,7 +173,7 @@ encodedChar = "&#" *> c <* ";" -- Once we have checked for any of these and tried to parse the -- relevant markup, we can assume they are used as regular text. specialChar :: [Char] -specialChar = "_/<@\"&'`# " +specialChar = "_/<@\"&'`#[ " -- | Plain, regular parser for text. Called as one of the last parsers -- to ensure that we have already given a chance to more meaningful parsers diff --git a/haddock-library/test/Documentation/Haddock/ParserSpec.hs b/haddock-library/test/Documentation/Haddock/ParserSpec.hs index 5fa73ecd..9cf7c537 100644 --- a/haddock-library/test/Documentation/Haddock/ParserSpec.hs +++ b/haddock-library/test/Documentation/Haddock/ParserSpec.hs @@ -576,27 +576,37 @@ spec = do it "turns it into a code block" $ do "@foo@" `shouldParseTo` DocCodeBlock "foo" - context "when a paragraph starts with a markdown link" $ do - it "correctly parses it as a text paragraph (not a definition list)" $ do - "[label](url)" `shouldParseTo` - DocParagraph (hyperlink "url" "label") + context "when a paragraph contains a markdown link" $ do + it "correctly parses the link" $ do + "Blah [label](url)" `shouldParseTo` + DocParagraph ("Blah " <> hyperlink "url" "label") - it "can be followed by an other paragraph" $ do - "[label](url)\n\nfoobar" `shouldParseTo` - DocParagraph (hyperlink "url" "label") <> DocParagraph "foobar" - - context "when paragraph contains additional text" $ do - it "accepts more text after the link" $ do - "[label](url) foo bar baz" `shouldParseTo` - DocParagraph (hyperlink "url" "label" <> " foo bar baz") - - it "accepts a newline right after the markdown link" $ do - "[label](url)\nfoo bar baz" `shouldParseTo` - DocParagraph (hyperlink "url" "label" <> " foo bar baz") + context "when the paragraph starts with the markdown link" $ do + it "correctly parses it as a text paragraph (not a definition list)" $ do + "[label](url)" `shouldParseTo` + DocParagraph (hyperlink "url" "label") it "can be followed by an other paragraph" $ do - "[label](url)foo\n\nbar" `shouldParseTo` - DocParagraph (hyperlink "url" "label" <> "foo") <> DocParagraph "bar" + "[label](url)\n\nfoobar" `shouldParseTo` + DocParagraph (hyperlink "url" "label") <> DocParagraph "foobar" + + context "when paragraph contains additional text" $ do + it "accepts more text after the link" $ do + "[label](url) foo bar baz" `shouldParseTo` + DocParagraph (hyperlink "url" "label" <> " foo bar baz") + + it "accepts a newline right after the markdown link" $ do + "[label](url)\nfoo bar baz" `shouldParseTo` + DocParagraph (hyperlink "url" "label" <> " foo bar baz") + + it "can be followed by an other paragraph" $ do + "[label](url)foo\n\nbar" `shouldParseTo` + DocParagraph (hyperlink "url" "label" <> "foo") <> DocParagraph "bar" + + context "when the link starts on a new line not at the beginning of the paragraph" $ do + it "correctly parses the link" $ do + "Bla\n[label](url)" `shouldParseTo` + DocParagraph ("Bla\n" <> hyperlink "url" "label") context "when parsing birdtracks" $ do it "parses them as a code block" $ do -- cgit v1.2.3