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

[Peter Wang]

On Sat, 03 Sep 2022 17:20:22 +1000 Mark Brown <mark at mercurylang.org> wrote:
> On Fri, Sep 2, 2022 at 5:32 PM Peter Wang <novalazy at gmail.com> wrote:
...
> 
> So here's another structure, also for the sake of discussion:
> 
> 2. Syntax
>   2.1 Character set
>   2.2 Whitespace
>   2.3 Comments
>   2.4 Line number directives
>   2.5 Variables
>   2.6 Names
>   2.7 Literals
>   2.8 Punctuation
>   2.9 Operators
>   2.10 Terms
>   2.11 Items
> 
> The literals section could also be split.
> 

That looks fine to me. I'd want to move Line number directives later,
after Operators.

> > I'm thinking, instead, we should present a grammar that goes down to the
> > level of terms, without describing yet what each piece of syntax is for.
> > People who read that kind of thing can get an overview of how a Mercury
> > module is structured, other people can skip over it.
> 
> That sounds better than what I have. So I'll just keep the very top
> bit of grammar, say that declarations are covered in relevant chapters
> (without giving forward references), and quickly show the four clause
> types.
> 
> One question about terminology, though. Sometimes I want to use 'head"
> to mean the part of a clause to the left of the ':-' (for example when
> saying that the body implies the head, and sometimes I want to exclude
> the '= Res' for function clauses (for example, when saying that the
> principal functor determines which function is being defined). For
> which of these can I use the term "head", and what should I call the
> other one?
> 
> Fwiw, I think it's more useful to use "head" in the first sense.

Yes, and I think we should avoid using it for the other sense
in the reference manual.

parse_item.m binds the function-name-and-arguments term to a variable
called "FuncHeadTerm", so maybe we should use a term "function head"
to mean the "[clause] head" excluding the "= Res" bit.
Or, just call it the "name-and-args" term if it doesn't come up very
often.

Peter