[m-rev.] for review: Overhaul of the Syntax chapter of the reference manual

[Mark Brown]

On Fri, Sep 2, 2022 at 5:32 PM Peter Wang <novalazy at gmail.com> wrote:
...
>
> In the sections that follow, I think it would be nice to present each
> feature, syntax then a discussion of semantics or whatever is relevant,
> e.g.
>
>     Conjunctions
>     ============
>
>     A conjunction goal is written:
>
>         Goal1, Goal2
>
>     The declarative semantics of a conjunction is ...
>
>     Operationally, a conjunction is executed first by executing Goal1,
>     and if that succeeds, executing Goal2.

I looked at this a bit more, as the Goals section indexes things by
syntax, whereas the State variables section uses something more like
the above style. These were my conclusions:

- "Goals" is better as it is, since I imagine the user's who most want
to look up the reference quickly would be those who are reading code
they didn't write, and see some syntax they don't recognize. E.g. if
they see ( A -> B ; C ) and don't know it is an if-then-else. This way
they can easily find it and find out what it means.

- "State variables" is also better as it is, since it's the semantics
of the goals that justifies why the transformation works the way it
does. It's easier to understand that way.

So I guess it's a case-by-case thing.

A related question is whether a transformation function is better
factored out at the end. For the section on DCGs I think so and I have
made the change, but I can revert this if people don't want it. I just
found the transform function easier to understand when it was
collected together. (The corresponding function for State variables is
better left piecewise, though, since there is a fair bit of prose that
goes with each clause.)

Cheers,
Mark

>
> I realise that's far beyond what you were intending to change.
>
> Peter