Cut a new release

[nojb]

I think we should cut a new release. This will allow users to migrate to the 2.0 version and we will get more bug reports, etc.

What needs to be done before:

1. complete some of the printers (text, markdown)
2. document, cleanup the exposed API

I will try to do this in the next couple of weeks. Please post here if you can think of anything else that needs to be done before a release.

[samoht]

Ping. Would be indeed very nice to have a new release (especially with the dune port).

[nojb]

Ping. Would be indeed very nice to have a new release (especially with the dune port).

Hello @samoht! Apologies for the long delay in getting back on this, I've been submerged by other things.

This is what needs to be done before a release:

Clean up the public AST type

Currently the public AST type is parametrized by a type variable that does not serve any purpose (it is an implementation artifact).

• Remove this variable from the public API.
• Get rid of the submodules in Ast corresponding to each constructor of the AST type, replace them by inline records or just plain records.

Adjust the HTML "printer" interface?

Currently the HTML printer (html.ml) is a record of functions that write on Buffer.ts. It can be extended by open recursion.

• I would like to use the same printer type for all backends, and
• I would like to change the signature so that we are not tied to Buffer.t's. Maybe print on Format.formatter?

I resisted doing this second point because any whitespace change in the printer output will break the testsuite which compares the generated HTML bytewise. But this is too fragile anyway and should be replaced by a comparison of the "parsed" HTML.

Add comments to the public interface

• The meaning of each AST constructor and their arguments, and to the functions exposed in omd.mli should all be documented.
• The "tag" system should be documented as being experimental and that it could go away in a future release.

Complete implementation of non-HTML backends

• Complete the "Text" backend (text.ml)
• Fix the FIXMEs in the "Markdown" backend (markdown.ml)

Other points to work on (not required for release)

• Rewrite the inline parser (in parser.ml): the current parser goes through some hoops to try not to allocate too much but I don't think it is worth it, and it is very hard to read and modify. A simpler combinator parser may be enough and be much simpler to work on.

• Decide what to do with the "tag" system; this was added in Added implementation of inline tags and tag blocks #191 but is highly non-standard (I am not aware of any other Markdown implementation that has something like this). We should decide if we keep it, if the syntax needs to be adjusted or if we want to replace it by something more standard.

• In general I think that if we are going to be adding non-standard extensions anyway, we may as well follow the lead of pandoc (or some other already established implementation), instead of coming up with our own (incompatible) extensions.

That's it I think. Help welcome !

cc @clecat
cc @deveah who expressed interest in collaborating.

[deveah]

Hello! I'm going to try to clean up the public AST type.

[shonfeder]

I should be able to help out here a bit. I'll start with

Fix the FIXMEs in the "Markdown" backend (markdown.ml)

since that should be provide clear guidance. Please let me know if you'd like me to focus on something else.

[nojb]

Hi @shonfeder, and thanks for the offer! Sure, that would be a good first step.

A bit of context: the project is basically "stalled" after a big rewrite because of not enough manpower (I am too busy to dedicate any serious time to it at the moment, and no-one else is available either).

If you have time available to work on it, it would really useful to help push towards the next release. I will gladly provide guidance of what needs to be done. Let me know (either here or by mail) if you want more information or if you want to discuss any other aspect of the project.

[shonfeder]

Thanks for the context and the offer! If it turns out I can keep the time freed up to help here in a substantial way, I'll definitely take you up on the latter :)

[clecat]

Hello !
I would be glad to help if hands are needed.
About the tags, I added them as a way to add personalized behaviours into the printers, but as you mentioned, this is not at all a common behaviour and might not be a good idea to keep.

And sorry for the late reply, I did not see this issue at the time

[nojb]

Thanks @clecat ! Any and all help is warmly welcomed :) I wrote some points in the issue description. Feel free to take up a point that you like, and do not hesitate to ask me if you have any questions/suggestions/etc.

[nojb]

Did the first two points in #201

[nojb]

Also reworked the testsuite #204 , and added an intermediate representation for HTML #128 which made the printing sort of trivial (both for HTML and plain text), so got rid of the printer data structure.

[shonfeder]

Hi! Just circling around here to see if I could be of help. It looks like you've made a lot of progress over the week! In particular, the stuff under "Complete implementation of non-HTML backends" seems completed (items checked and the referenced files don't exist any more) :) It's not clear to me where more help would be useful to make it possible to cut the release. Is there any other particular help I can offer over the weekend?

Thanks!

[nojb]

Hi @shonfeder,

Yes, sorry about that :) I had a rare opportunity to work on Omd this weekend and so I ran with it and tried to get as much as possible done in the available time.

I don't see any self-contained small issue to work on right now for the 2.0 release, but we will have for sure after the release. Right now I am trying to whip everything into shape to get the release out the door as soon as possible so we can get more testing and more feedback, which will help us prioritize new features, etc.

[shonfeder]

No worries at all! Very glad to see the progress, and even better it happens without my efforts :D -- thank you!

Sounds good to me. Feel free to tag me if I can be useful!

[aantron]

What is the status of the release at this point?

[nojb]

What is the status of the release at this point?

https://discuss.ocaml.org/t/markdown-library-omd-seeking-mantainer/7420

[aantron]

(For readers here, I replied in the Discuss thread — thanks @nojb).

[tatchi]

Hey, what's the current status of this issue ? And more generally, what are the remaining blockers for a 2.0 release?

As far as I know, we still need to implement a function that can print back the AST to a string. This will require us to address the issue at #223.

Is there anything else that we need to consider?