Update binding-specification section in manual

[dschrempf]

The manual section on binding specifications has diverged from the implementation. In particular, we now distinguish between ctypes and hstypes. hstypes are not mentioned in the manual yet, and I don't feel comfortable enough to add this myself in the course of #1324.

Maybe @TravisCardwell can help?

[TravisCardwell]

There is a lot of work on binding specifications that needs to be done. Progress slowed way down when we started refactoring to use Frontend passes, and that refactoring is still ongoing. Once the ID refactoring is done, we need to move a lot of implementation from the Backend to the Frontend, now that anything that may cause an error must be in the Frontend. The Frontend must determine everything about what needs to be generated, and the Backend will just be used to generate the Haskell code. Work has been done to add binding specification syntax because we wanted to include such breaking changes before release, but implementation of many features must be done after the Frontend refactoring has stabilized.

Why is this? Binding specifications are a higher-level feature of hs-bindgen, which builds on top of many parts of the project.

For external binding specifications, it is pretty clear what information is needed. The challenge is that we use the same format for prescriptive binding specifications. We must therefore decide on the semantics for prescriptive specification, where users should only be required to specify things that they care about. We are still designing/questioning those semantics, as recent as yesterday.

My TODOs for implementation include writing tests and updating the manual. I do not think we should update the manual until the features are actually implemented, as the design is quite unstable.

In the WIP binding specifications section of the manual, there is indeed one example that needs hstypes: the generated binding specification. This example uses squashing, and I just fixed the binding specification generation for this yesterday! I added an update in that PR (#1404).

The rest of the binding specifications are external binding specifications, and hstypes specifications do not need to be specified unless there is a reason to do so.

[dschrempf]

Thanks. I will leave the section alone, and this ticket open.