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

[Julien Fischer]

Hi Mark,

(I realise Peter has also responded to this thread, I'm running a bit
behind on my mails.)

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.

> 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.

>>> 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 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.

Cheers,
Julien.