Fix issue #865

CHANGES.md

@@ -1,7 +1,11 @@
 # Unreleased
 
+### Added
 - Support for OxCaml unboxed named types (@art-w, #1407)
 
+### Fixed
+- Allow to break link into multiline (@Tim-ats-d, #1439)
+
 # 3.2.1
 
 ### Fixed

src/parser/syntax.ml

@@ -1,3 +1,4 @@
+
 (* This module is a recursive descent parser for the ocamldoc syntax. The parser
    consumes a token stream of type [Token.t Stream.t], provided by the lexer,
    and produces a comment AST of the type defined in [Parser_.Ast].
@@ -167,6 +168,30 @@ type token_that_always_begins_an_inline_element =
   | `Begin_link_with_replacement_text of string
   | `Math_span of string ]
 
+let escape_link link =
+  let link = String.trim link in
+  let buf = Buffer.create (String.length link) in
+  let last_state =
+    String.fold_left
+         (fun acc chr ->
+           match (acc, chr) with
+           | `Char, '\\' -> `Backslash
+           | `Char, _ ->
+               Buffer.add_char buf chr;
+               `Char
+           | (`Backslash | `Escaping), (' ' | '\t' | '\n') -> `Escaping
+           | (`Backslash | `Escaping), _ ->
+               Buffer.add_char buf chr;
+               `Char)
+         `Char link
+  in
+  let () =
+    match last_state with
+    | `Backslash -> Buffer.add_char buf '\\'
+    | `Escaping | `Char -> ()
+  in
+  Buffer.contents buf
+
 (* Check that the token constructors above actually are all in [Token.t]. *)
 let _check_subset : token_that_always_begins_an_inline_element -> Token.t =
  fun t -> (t :> Token.t)
@@ -269,7 +294,7 @@ let rec inline_element :
   | `Simple_link u ->
       junk input;
 
-      let u = String.trim u in
+      let u = escape_link u |> String.trim in
 
       if u = "" then
         Parse_error.should_not_be_empty
@@ -281,7 +306,7 @@ let rec inline_element :
   | `Begin_link_with_replacement_text u as parent_markup ->
       junk input;
 
-      let u = String.trim u in
+      let u = escape_link u |> String.trim in
 
       if u = "" then
         Parse_error.should_not_be_empty

test/model/semantics/test.ml

@@ -690,6 +690,14 @@ let%expect_test _ =
         {|
         {"value":[{"`Heading":[{"heading_level":"`Subsection","heading_label_explicit":"false"},{"`Label":[{"`Page":["None","f.ml"]},""]},[{"`Link":["foo",[]]}]]}],"warnings":[]} |}]
 
+    let multilines_link_in_markup =
+      test {|{{:https://github.com/ocaml/\
+   odoc/\
+issues/\
+                865\  }this issue}|};
+      [%expect
+        {| {"value":[{"`Paragraph":[{"`Link":["https://github.com/ocaml/odoc/issues/865\\",[{"`Word":"this"},"`Space",{"`Word":"issue"}]]}]}],"warnings":["File \"f.ml.mld\":\nPages (.mld files) should start with a heading."]} |}]
+
     let reference_in_markup =
       test "{2 {!foo}}";
       [%expect