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

[Mark Brown]

On Sat, Sep 3, 2022 at 8:38 PM Julien Fischer <jfischer at opturion.com> wrote:
>
>
> Hi Mark,
>
> (I realise Peter has also responded to this thread, I'm running a bit
> behind on my mails.)

No worries. Note that there's some additional response to you in with
my response to Peter.

>
> On Thu, 1 Sep 2022, Mark Brown wrote:
>
> > On Thu, Sep 1, 2022 at 12:36 AM Julien Fischer <jfischer at opturion.com> wrote:
> >>
> >>
> >> Hi Mark,
> >>
> >> On Wed, 31 Aug 2022, Mark Brown wrote:
> >>
> >>> This makes some significant changes to the Syntax chapter. The
> >>> motivation for these changes comes largely from what questions were
> >>> needing to be asked by programmers with a non-Prolog background who
> >>> were learning Mercury, and what things they were confused about.
> >>>
> >>> The texinfo is for review by Peter, but I've also attached a tarball
> >>> of the split html for anyone else to look through (and pdf and info,
> >>> in case anyone cares).
> >>
> >> Here are some initial comments regarding your proposed changes to the
> >> structure of the reference manual.
> >>
> >>> commit 923a62ae30a236ba11b61020c3636e6909e67925
> >>> Author: Mark Brown <mark at mercurylang.org>
> >>> Date:   Tue Aug 30 07:53:25 2022 +1000
> >>>
> >>>     Overhaul of the Syntax chapter of the reference manual
> >>>
> >>>     There are three main aims for this change:
> >>>
> >>>     1. Don't rely so much on users having knowledge of Prolog (ideally we
> >>>     wouldn't require it at all, but this change probably doesn't fully achieve
> >>>     that).
> >>
> >> Ideally, the reference manual would contain one reference to Prolog. That
> >> reference would point interested readers to the Prolog transition guide.
> >
> > Agreed - that would make it very clear that it isn't required.
> >
> > We still refer to things like SLDNF resolution, though, which in
> > practice means needing to know about Prolog.
>
> It's possible to describe SLDNF resolution within the context of logic
> programming generally, without specific reference to Prolog.
>
> The one reference we do have to SLDNF resolution in the Mercury
> reference manual is not really very useful anyway, since it just chucks
> it out there and assumes you know what it is.

I think we're in agreement here - like, I imagine the number of people
who know about SLDNF but not about Prolog is approximately zero. I'm
just saying that I wasn't aiming to describe SLDNF resolution or
anything like that in this change.

>
> > So I can't say that I was aiming to remove dependencies entirely.
>
> Based on a quick look at the references to Prolog, I think nearly all of
> them could be omitted or shifted into the Prolog transition guide.

Fwiw, I don't mind the references, so long as they are written so as
to not give the impression that readers are supposed to know Prolog.

>
> >>> Present the information more linearly, i.e., without requiring so many
> >>> forward references.
> >>>
> >>>     2. Make important information less likely to be overlooked. As it stands,
> >>>     we give a lot of semantics in the Syntax chapter where users wouldn't
> >>>     expect to find it (they're more likely to just skim over such a chapter).
> >>
> >> I agree with this; I don't agree with how you've decided to address it (see
> >> below).
> >>
> >>>     We also currently break the chapter up into small sections, some of which
> >>>     have little information. This works well in the PDF version, but in split
> >>>     html and info versions where navigation is required it is a pain.
> >>
> >> One reason for having those small sections is that they appear in the
> >> table of contents. In the existing version, it's _really_ obvious where
> >> to look, to give an example, for the list of characters that are
> >> considered whitespace.
> >>
> >> Building the HTML version of the reference manual with --split=chapter
> >> would appear to address your concerns for the HTML version.  (The Info
> >> format and the tools for viewing it that I am familiar seem to have a
> >> rather fixed view about how documents are presented.)
> >>
> >>> People tend to forget information each time they navigate, and are likely to
> >>> find themselves going back and forth between nodes.
> >>
> >> Which suggests that splitting at nodes (which is the texinfo default) is
> >> not the right thing to do for this document.
> >
> > Agreed. And I didn't know about splitting by chapter - I will check it out.
> >
> > For the whitespace and other early subsections, I wasn't aiming for
> > "really obvious" (Lexical syntax/structure is sufficiently obvious,
> > imho) but more "not dry and dull". I think it is keeping with the
> > style of the rest of the manual to present the information like an
> > article, rather than in an overly structured way. I also think the way
> > the table splits up the text is more aesthetically pleasing, but I
> > won't argue that point any further ;-)
>
> Hmmm, you must be new to this list ;-)
>
> >> ...
> >>
> >>>     Changes to document structure
> >>>     -----------------------------
> >>>
> >>>     Sections and subsections of the Syntax chapter have been merged, to provide
> >>>     a more reasonable amount of information at each node.
> >>
> >>
> >>>     The Syntax chapter
> >>>     as a whole has been split into two chapters, Syntax and Semantics (the
> >>>     existing Semantics chapter is renamed Formal Semantics). The new structure
> >>>     is as follows:
> >>
> >> I think "Semantics" is a problematic name: there's a load of syntax
> >> stuff in there as well. Rather than "Semantics" I suggest simply calling
> >> it "Goals and Expressions".
> >
> > Well, there's some pretty significant things other than goals and
> > expressions, and most of the remaining chapters provide syntax along
> > with the semantics. If you want a more accurate name then it could be
> > "Clause semantics" for example. If you just want to suggest that it's
> > not _all_ of the language semantics it could be called "Basic
> > semantics" or something like that.
>
> I think we can address this by not using the chapter names "Syntax" and
> "Basic Semantics" (and such similar names).  The material you are
> dividing between those two chapters is the syntax and (where required)
> semantics of the basic language constructs.  Let's just have a chapter
> named something like "Basic constructs" or "Basic elements".  (The whole
> issue of the "Syntax" chapter also including semantics then becomes a
> non-issue.)
>
>
> >>       3. Terms
> >
> > This is better placed under something entitled "Syntax", in my view,
> > otherwise it just sounds like a glossary.
>
> I was struggling to find a place to put Terms.
>
> > One of the reasons why I wanted to make a clear distinction between
> > syntax and semantics, at least early on,
>
> I don't see how you can make such a separation for things like goals,
> without describing them twice (once for syntax, once for semantics).
> (And goals are pretty fundamental part of the language.)

The separation is so we only have to describe the term equivalence
relation once. This is something we already do in the existing manual,
we just make the point in a subtle way. E.g., in the syntax overview
we say that everything in a module is an item and an item is a term
followed by a period, and in the term syntax we say that operator
notation can be used. In the rest of the manual we assume that the
reader will therefore know when to use parentheses. I want to make it
more obvious, as it's something that new users I spoke to had missed.

Regarding calling it syntax, we currently start the Data-terms section
with, "Syntactically, a data-term is just a term." So I think we are
already making the distinction between syntax and semantics. I don't
think we should change that, I just think we should make the
implications of it clearer.

In this context "semantics" means a mapping from syntax to some
semantic domain. E.g., for the declarative semantics of goals the
semantic domain is predicate calculus formulas, and the Goals section
contains one big mapping from terms to formulas, which maps comma to
conjunction, semicolon to disjunction, etc (with some extra stuff like
implicit quantification covered shortly after).

In other contexts a different mapping applies, e.g. in type
declarations, terms map to abstract types, equivalence types, etc.

The only place I didn't think there was a clear separation was with
state variables, which could be considered syntactic but which are
hard to justify without knowing the semantics of clauses. That's the
main reason I think they ought to have their own chapter, after the
chapter that covers the semantics of clauses.

>
> ...
>
> >> The position of this seems fairly arbitrary; given its tone and content I feel
> >> it would be better placed in an extended version of the introduction to the
> >> entire document or in a separate chapter just after the introduction.
> >
> > Yes, I guess you could say it is arbitrary. The question is whether it
> > accurately characterizes our claims to be a declarative programming
> > language.
> >
> > We use the terms "declarative semantics" and "operational semantics"
> > throughout the remainder of the manual so we need to explain what
> > we're talking about, and the formal semantics is pretty steep for
> > anyone who doesn't already know Prolog. Would anyone else know what
> > the completion of the clauses is? One thing I can say for certain is
> > that there are very good programmers out there who don't know what
> > unification is.
>
> I think your question is really: how much logic programming theory can a
> reader of the reference manual be assumed to know? If the answer is
> none, then we're going to end up with the better part of a text book
> somewhere in the manual.

No, we won't. I'm dividing readers into two classes here: those who
want rigorous definitions and those who don't. I think the existing
semantics chapter is fine for the former, but doesn't cater to the
latter - they still need to know what we mean by declarative and
operational semantics. But it can be informal and incomplete, and
that's what I'm aiming for.

Cheers,
Mark

>
> Cheers,
> Julien.
>