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

[Mark Brown]

Hi Julien,

On Sun, Sep 11, 2022 at 11:37 PM Julien Fischer <jfischer at opturion.com> wrote:
>
>
> Hi Mark,
>
> On Wed, 7 Sep 2022, Mark Brown wrote:
>
> > Attached is another diff - it's the full diff as the relative diff is
> > no shorter. Also attached is the html that results from
> > --split=chapter.
>
> I think that mostly achieves what you wanted.  (The Next and Previous
> links look a little weird -- I couldn't find a way to omit them.)

There's a --no-headers option that seems to do the trick.

> > +A variable is an uppercase letter or underscore
> > +followed by zero or more letters, underscores, and digits.
> > +A variable token consisting of single underscore is treated specially:
> > +each instance of @samp{_} denotes a distinct variable.
> > +(In addition, variables starting with an underscore
> > +are presumed to be ``don't-care'' variables;
> > +the compiler will issue a warning
> > +if a variable that does not start with an underscore occurs only once,
> > +or if a variable starting with an underscore
> > +occurs more than once in the same scope.)
>
> I suggest just making the parenthetical bit into a separate (un-parenthesized)
> paragraph.
>
> Also, I suggest giving some examples of valid and invalid variable names.
>
> (Another issue here is that in the context of Unicode, "letter" and digits
> are broader than what Mercury actually supports in variable names.)

That applies in quite a number of other places, too. I've added a
proviso to the Character set section to cover all of them, which
seemed the right place for that. (The preceding two points are done.)

>
> > + at subheading Operational semantics
> > +
> > +The declarative semantics doesn't tell us
>
> s/doesn't/does not/
>
> > +whether our program will terminate, for example,
> > +or what its computational complexity is.
> > +For that we need the operational semantics,
> > +which tells us how the program will be executed.
> > +
> > +Execution in Mercury starts with a @dfn{goal}.
> > +This is a proposition that may contain some variables,
> > +and the aim of execution is to find a substitution
> > +for which the proposition is true.
>
> Make that into two sentences.

I've added the second line to the first sentence, which seems to read nicely.

> Parenthetical Prology things can go in the transition guide.

Most of them were actually already there :-)

I've deleted/moved them as appropriate.

The remaining points are fixed as suggested. Thanks for the review!

Mark

>
> Julien.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: reldiff
Type: application/octet-stream
Size: 16261 bytes
Desc: not available
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20220912/be215bf4/attachment-0001.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: mercury_ref.tar.gz
Type: application/gzip
Size: 163091 bytes
Desc: not available
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20220912/be215bf4/attachment-0001.gz>