Bump OMD to 2.0.0~alpha1

[patricoferris]

This issue is to upgrade the OCaml scripts which use Omd to the latest version of Omd. This issue is not necessarily very straight forward, but would expose someone to a lot of OCaml code, compiler errors and working in harmony with the type checker.

The main change is in the omd abstract syntax tree (AST) -- for example in scripts/code.ml we have:

match Omd.of_string ("<pre>" ^ p ^ "</pre>") with
    | [ Omd.Html_block(_,_,o) ] -> o
    | _ -> assert false

But the AST has changed, and Omd.of_string now returns a doc type (https://github.com/ocaml/omd/blob/master/src/omd.mli#L66) so this pattern-matching with the latest Omd returns an error.

Error: This pattern matches values of type Omd.block_desc
       but a pattern was expected which matches values of type Omd.block

So we need to convert instances like this to the new AST. For most cases this isn't too bad because the new AST simply wraps most things in a block type which has a block_desc and some attributes. The fix for this line becomes:

match Omd.of_string ("<pre>" ^ p ^ "</pre>") with
    | Omd.[{ bl_desc = Html_block o; _ }] -> o
    | _ -> assert false

To start developing a solution be sure to update your version of omd i.e. opam install omd.2.0.0~alpha1.

[CarolVilarino]

Hi @patricoferris I haven't taken any issues yet to solve, do you think this would be a good start? 😃

[patricoferris]

HI @CarolVilarino I'm not sure this is a good first issue -- there's quite a lot of OCaml code to change and this repository doesn't have the dune build system which makes it even more challenging to update. I think you have commented on some other issues so hopefully you have another one?

[Srinithyee]

@patricoferris can I try working on this?

[patricoferris]

Hi @Srinithyee I've done a little extra digging on this issue, so let me explain some things and then you can see if you still want to work on it.

The latest omd binary doesn't have the same level of functionality as the old one. In particular, it cannot generate table of contents like we do now (i.e. omd -otoc...), so until that functionality is brought back we cannot upgrade to omd.2.0.0~alpha1 without rewriting that ourselves, but there are plans to add it back in perhaps (see ocaml-community/omd#232).

However, we can still work the the omd library (the parts I was describing above). We can convert to the new AST and make sure that the scripts compile and then leave that as a draft PR ready to be merged if/when the omd binary gets the support we need.

In summary, the work done on this won't be merged probably any time soon but it is still a contribution I believe you can write about in your Outreachy app :)) Let me know what you think, thanks.

[patricoferris]

Just seen you are working on ocaml/ocaml.org#1492 -- it's best that you focus on that one I think. If anyone else wants to work on this given the above let me know :))

[gs0510]

@Goodiec Since you were asking for a more challenging issue, you can take this one! :)

[Srinithyee]

Just seen you are working on #1492 -- it's best that you focus on that one I think. If anyone else wants to work on this given the above let me know :))

@patricoferris Yes, I'd like to work on #1492. Thanks a lot for your clarification on this issue though :))

[Goodiec]

@Goodiec Since you were asking for a more challenging issue, you can take this one! :)

OK @gs0510, I'll attempt this. Thank you.

[jyotibalodhi]

@Goodiec Are you still working on this issue?
@gs0510 @patricoferris, If @Goodiec confirms she is not working on this Issue, Can I take this up?

[Goodiec]

@Goodiec Are you still working on this issue?
@gs0510 @patricoferris, If @Goodiec confirms she is not working on this Issue, Can I take this up?

Hi @jyotibalodhi, yes I am.

[gs0510]

@Goodiec have you been able to make any progress? Do you need any help? Thanks!