Earmark and EarmarkParser need better documentation about the split.

[RobertDober]

I propose to put something like the following quite on top of the README, input from @martosaur @https://github.com/dominicletz and of course @amit-chaudhari1 is most welcome

EarmarkParser vs. Earmark

Historically EarmarkParser was extracted out from Earmark because ex_doc did only use the AST when it became available during the evolution of Earmark.

For some time Earmark used EarmarkParser before generating the HTML.

Now however, especially as I have found a new maintainer in the person of @amit-chaudhari1 and both projects are free to implement the kind of markdown and featureset best suited for them, the two projects are independent.

We are aware that this might be confusing for some time but here are some basic rules that should help.

What to install

1. If you use ex_doc you use EarmarkParser as a dependency, now and only now you can work with Earmark as a dependency without risking a conflict.

2. If you want to transform Markdown into an AST you have two options, depending on the feature set you want to use. In case you use Earmark all is clear. If you need EarmarkParser you might have conflicts with ex_doc However there is a simple fix for this provided by José Valim himself, here is how to create your docs without ex_doc as a dependency https://github.com/RobertDober/earmark_parser/blob/5228fce46509ff1bc0c727eeeef8b2d20774ecc1/mix.exs#L33 and https://github.com/RobertDober/earmark_parser/blob/5228fce46509ff1bc0c727eeeef8b2d20774ecc1/mix.exs#L65-L83

3. If you want HTML Earmark is your only option.

How to report bugs

A very simple rule

If you have Bugs which are raised in ex_doc report to ex_doc or EarmarkParser, communication between us is great 👼
If you have EarmarkParserin your deps report to EarmarkParser
If you have Earmark in your deps report to Earmark

But I have both

Then report according to your feeling, nobody will be mad with you, we will route the issue between the two projects w/o any hussle. Again great communication 😉

[martosaur]

Thanks, this helps a lot! Do you have a vision on how changes to parsers should or should not be ported between them? A good example is RobertDober/earmark_parser#142 which would be a great fit for Earmark package I think.

[RobertDober]

Thanks, this helps a lot! Do you have a vision on how changes to parsers should or should not be ported between them? A good example is RobertDober/earmark_parser#142 which would be a great fit for Earmark package I think.

Concerning the example, I agree with you, ... #502
I guess it might be a good idea to cross reference or link the issues between the two repos. #501 is a good example where the same has to be done in both projects. There are two things that surprise me

• I thought the parser was stable, (I still think there will not be many things to backport, but there are some as it seems)
• The human aspect for collobaration and understanding of the two projects might be more complex (but that is something I will never fully understand with my brain, fortunately people explain it well to me so far 👍 )