Normalize whitespaces in codespans

[gpetiot]

To summarize:

• A newline followed by any whitespaces should be considered to be one space character by odoc-parser and ocamlformat.
  Consecutive whitespaces not after a newline are conserved as they are.
• Trim whitespaces at the beginning and end of code spans. Not related to the issue but as we making whitespaces a bit less significant, this is worth mentioning.

[dbuenzli]

Implementing the proposition of https://github.com/tarides/tooling-tasks/issues/49

Please avoid referencing non-public propositions in a public project.

• A newline followed by any whitespaces should be considered to be one space character by odoc-parser and ocamlformat.

That's quite an odd convention. If you want to change the current behaviour (not sure what it is) I think you should rather ignore all whitespace (and make sure you can introduce one with an escape).

[jonludlam]

How will this affect mdx?

[dbuenzli]

That's quite an odd convention.

Sorry I misunderstood, I thought it was for code blocks. What you propose is fine with me (and FWIW indirectly what CommonMark does).

[dbuenzli]

• Trim whitespaces at the beginning and end of code spans. Not related to the issue but as we making whitespaces a bit less significant, this is worth mentioning.

Also I don't think this should be done.

[gpetiot]

How will this affect mdx?

There won't be any impact, mdx doesn't process code spans, only the code blocks

[panglesd]

For the records, here is the issue this PR is solving.

Citing @Julow (private conversation):

[In the context of ocamlformat] Code spans can be large and might need to break. For example, we might want to format the first into the second:, and having the following two versions identical would allow for better formatting:

(** [very_long_word b] *)

(** [very_long_word
     b] *)

In the second case, Odoc's AST contains "very_long_word\n b". When using the html backend, both comments render the same as the whitespaces are normalized by the browser.

My suggestions:

• A newline followed by any whitespaces should be considered to be one space character by odoc-parser and ocamlformat.
  Consecutive whitespaces not after a newline are conserved as they are.
• Trim whitespaces at the beginning and end of code spans. Not related to the issue but as we making whitespaces a bit less significant, this is worth mentioning.
• Backward compatibility is not a concern. Most already written don't have this problem. The newline is not visible when using the html backend.

See also this PR for the discussion on the ocamlformat side.

[dbuenzli]

As I said I don't think initial and trailing whitespace should be suppressed. 1) There may be legitimate reasons to have some 2) It needlessly deviates from other lightweight markup languages like CommonMark.

[panglesd]

Maybe this PR could be split in two:

• The modification solving the original issue: considering newlines followed by blanks as a single space, and
• the initial and final whitespace trimming

so one modification is not blocking the other?

I think having the syntax for inline elements play nice with the "80 char rule" is good to have, so I would be in favor of the first change. I haven't though about the second change, but as a first impression I would be in favor of having the same behavior as CommonMark.

[gpetiot]

• the initial and final whitespace trimming

I removed these changes and cleaned up the PR.

[panglesd]

Maybe a small mention of that in the docs could be good! Odoc's language is underspecified but let's slowly improve that...

[panglesd]

Promoted tests and updated docs, and then it's mergeable!

[panglesd]

This PR is ready to be merged. I'll let a few days before merging to let anyone who dislike the change speak up.

[jonludlam]

Looks good to me. In it goes!