Fix issue #865

[Tim-ats-d]

First try to fix the issue #865. The patch is dead simple, I've only added a multilines_link_to_link which properly reformats multi lines link into normal ones.

As I'm not yet really familiar with the Odoc codebase, don't hesitate to tell where can I define the multilines_link_to_link function or if the test need to reside in its own file!

Cc @panglesd

[panglesd]

I left some comments. This also needs a change entry!

[panglesd]

This does not really correspond to what we expect (escaping newlines):

a
b\      <--- there are whitespace after the \
c\      <--- no newlines after the \

will be interpreted as abc. The biggest problem probably being that the trailing \ is removed (?)

[Tim-ats-d]

I've changed the behavior to be more fine-grained. Ending backslash should now be preserved in the extracted link.
Here are some examples:

{{:https://github.com/ocaml/\
   odoc/\
issues/\
                865\  }this issue}

=> https://github.com/ocaml/odoc/issues/865\

{{:https://github.com/ocaml/\
   odoc/issues/\

865

}this issue}

=> https://github.com/ocaml/odoc/issues/865

{{:https://github.com/ocaml/odoc/issues/\
865/   /\
ending worlds}this issue} 

=> https://github.com/ocaml/odoc/issues/865/ /ending worlds"

[panglesd]

(I've checked in the definition of a URI, whitespace and \ are not allowed in URI. Which does not mean they should be removed, it would be surprising as browsers handle their percent-encoding.)

One sentence should be added to the docs. Without it, it is difficult to say whether there is a bug in the implementation, or if it had the behaviour you wanted. My problem with the current implementation is that they cannot satisfyingly be expressed in English. ("When a backslash is followed by whitespace, remove both except at the end where if there is no whitespace the backslash is kept").

I suggest to make it either:

When a backslash is followed by whitespace, both are removed

which implies a small modification to your code

or:

Removes all backlashes and the space that follows them

which has a simpler implementation but is more invasive. I think I prefer the first one.

Could you add a sentence in the docs that says what is done to backslash and whitespace, and have the implementation correspond?

[panglesd]

The docs says:

When a backslash is followed by whitespace, both are removed.

but here, even without whitespace, the backslash is removed...

[panglesd]

Suggested change

	| (`Backslash | `Escaping), _ ->
	Buffer.add_char buf chr;
	`Char)
	| (`Backslash | `Escaping), _ ->
	if state = `Backslash then Buffer.add_char buf '\\';
	Buffer.add_char buf chr;
	`Char)

or a more elegant version if you have one.

Actually see https://github.com/ocaml/odoc/pull/1439/changes#r3623267227

[Tim-ats-d]

Should be fine now 😄

[panglesd]

Looks good to me! Thanks!