DEVEL.md

A few development tips.

Benchmark parse to HTML rendering

time cmark --unsafe /file/to/md > /dev/null
time $(b0 --path -- bench --unsafe /file/to/md) > /dev/null

Expectation tests

To add a new test, add an .md test in test/expect, run the tests and add the new generated files to the repo.

b0 -- test_expect

Specification tests

To run the specification test use:

b0 -- test_spec             # All examples
b0 -- test_spec 1-10 34 56  # Specific examples

To test the CommonMark renderer on the specification tests use:

b0 -- trip_spec             # All examples
b0 -- trip_spec 1-10 32 56  # Specific examples
b0 -- trip_spec --show-diff # Show correct render diffs (if applicable)

Given a source a correct render yields the same HTML and it round trips if the source is byte-for-byte equivalent. Using --show-diff on an example that does not round trip shows the reason and the diff.

The tests are also run on parses without layout preservation to check they are correct.

Pathological tests

The pathological tests of cmark have been ported to test/pathological.ml. You can run them on any executable that reads CommonMark on standard input and writes HTML rendering on standard output.

b0 -- pathological -- cmark
b0 -u cmarkit -- pathological -- $(b0 --path -- cmarkit html)
b0 -- pathological --help
b0 -- pathological -d /tmp/ #   Dump tests and expectations

Specification update

If there's a specification version update. The commonmark_version variable must be updated in both in B0.ml and in src/cmarkit.ml. A s/old_version/new_version/g should be performed on .mli files.

The repository has the CommonMark specification test file in test/spec.json.

To update it invoke:

b0 -- update_spec_tests

Unicode data update

The library contains Unicode data generated in the file src/cmarkit_data_uchar.ml

To update it invoke:

opem install uucp
b0 -- update_unicode_data