Verbatim bugs

[dbuenzli]

odoc chokes on topkg's use of verbatims. @trefis thinks this is an octavius bug:

opam pin add topkg https://github.com/dbuenzli/topkg.git#1bcd6ca66f81c7306ec424aa5b8988c4a39edb94
odig odoc topkg
Error src/topkg.mli, line 747, col 44 to line 747, col 45: text expected
Error src/topkg.mli, line 1956, col 61 to line 1956, col 62: unmatched ']'

The corresponding lines are
https://github.com/dbuenzli/topkg/blob/1bcd6ca66f81c7306ec424aa5b8988c4a39edb94/src/topkg.mli#L747
https://github.com/dbuenzli/topkg/blob/1bcd6ca66f81c7306ec424aa5b8988c4a39edb94/src/topkg.mli#L1956

Note that this breaks a significant part of topkg's documentation as it drops all the remaining sections of the docs which in turns breaks many internal links to them.

Worked around by turning a few of these verbatims into code fences in dbuenzli/topkg@56c82f7

[dbuenzli]

Note that it would be quite nice to review #39 at the same time for the release.

[trefis]

OK, the problem is that in strings like this one:

{v
"--dev-pkg" "%{dev}%"    # for opam >= 2.0
"--dev-pkg" "%{pinned}%" #           < 2.0 v}

The verbatim block is terminated by the v} in "%{dev}%".

This could be improved by requiring some kind of blank just before the terminator (which, I think, is what ocamldoc does).
Until it is though, you can just escape the }, which ocamldoc will support as well. So "%{dev\}%".

[trefis]

Btw, the change to better handle blanks at the beginning/end of verbatim block is exactly the same as the one needed for preformatted code blocks. And will be fixed at the same time. But not before the release.

[dbuenzli]

(which, I think, is what ocamldoc does).

Yes ocamldoc has no issues with the above.

[aantron]

The commit linked above fixes this. There is a new test,

odoc/test/parser/test.ml

Line 366 in f973950

t "nested-closer-with-word" "{v {dev} v}";

which checks that a correct comment AST is produced:

odoc/test/parser/expect/verbatim/nested-closer-with-word.txt

Line 1 in f973950

((output (ok (((f.ml (1 0) (1 11)) (verbatim {dev}))))) (warnings ()))