Zed_char: clarify doc-comm

[kandu]

This PR is based on the discussion in issue #15. The max sectioning level allowed in odoc is 5, so I take this opportunity to fix it.

[kandu]

If there is no objection, I'll merge this PR and release zed 2.0.1 in 24 hours. cc @Drup

[Drup]

I now understand what you are trying to do, but your API is, imho, simply badly designed, which explains the number of questions.

You expect the user to create locally malformed datatype (using unsafe_*) to handle user input, so that they can be passed on to later actions. A better answer is to say: You can only form Zed_char from actual graphemes. zchar mostly comes from "getting" into a zstring. If you want to add individual uchars to Zed's string/ropes/edit, use the appropriate function from there (such as Zed_string.add_uchar).

This way, you have something that is coherent, and doesn't require users to have locally malformed datastructures. This does require a few changes in the rest of the API to make sure that everything needed is possible, in particular this (but I'm sure there are others).

[kandu]

As I've said in issue 2 of lambda-term

I'm skillful at writing bugs.

It's no doubt that I'll design bad API. But fortunately, you point out the problems and let me learn a lot from your suggestions.

As we are going to release zed 3.0. Would you mind taking some time to improve the API and implementation, release them in the upcoming 3.0 version, so we can leave bad things in bad place(2.0) and keep going properly.

And meanwhile I'll learn how to design and implement things exquisitely from the new release, so I will collaborate with the community in a better way.

Thanks again @Drup

[kandu]

Zed is an editing engine, when we talk about user input and later actions, what we are really talking about is the assembled working editing system(input -- zed -- rendering).

We also provide room for custom preprocessing, e.g. key bindings in lambda-term, arrow key processing, user custom keycode remap etc. which is deemed to be raw.

And when talking about an editing system. User input is not the only source of inputing. There are macro, pasting, auto completion etc. which is deemed to be cooked.

Zed_char is there not only for zed itself. It's a common container for exchanging data among (raw input) -> (preprocessing) -> (zed itself) -> (rendering)

You are right. The api of zed 2(and lambda-term 2) is rough and badly designed. Ideally we can make the boundary between these phases clean and make the zed_char type represent only for graphemes, at the same time, the api will still keep clean and elegant. I hope that we can achieve the goal when zed 3.0 is released.