[m-rev.] for review: update backends page on website

[Julien Fischer]

Hi Zoltan,

On Wed, 19 Jan 2022, Zoltan Somogyi wrote:

> On Wed, 19 Jan 2022 16:42:59 +1100 (AEDT), "Zoltan Somogyi" <zoltan.somogyi at runbox.com> wrote:
>>> Do you need me to update the live site as well?
>>
>> No, thanks.
>
> The attached diff, which I can commit now or after review,
> further improves (at least in my view) the backends section.
> For review by Julien.
>
> I do have some further concerns I have not acted upon.
>
> The C# and Java backends say that there is support for
> Mercury level debugging, but the .ssdebug grade component,
> as far as I remember, is not actually publically documented,
> which makes these claims look hollow.

I think those descriptions were written before we un-publicly
documented the .ssdebug grades.

> I am not sure why we lay so much (relative) emphasis
> on good interfacing with the target language. Shouldn't this be
> a given?

It should, but it doesn't hurt to emphasise it since it's something
prospective users of Mercury may well be interested in.

> Does anyone have a list of the parts of the standard library
> that do not work in Java and/or C# grades?

They are listed in REAMDE.{Java,CSharp} and/or described in the
library documentation itself.  (I am intending to update both those
READMEs soon, so I will take a closer look then.)

> Why is it important to specify the first release that supported
> these backends? These were more than a decade ago.

Those descriptions were added to accompany the first release
supporting the backends.  (I don't think this page has been updated
since then.)  We should remove them, since the C# and Java backends
*are* supported in any release of Mercury that will get past the
configure step these days.

> Why does this file use </p>? I thought paragraphs did NOT
> have to be explicitly terminated.

They don't, but some HTML linters emit spurious warnings about
such things.

> Note that my laptop does not have PHP installed,
> so I haven't been able to test the aesthetics of the result.

I'll take a look after you commit and make any adjustments required.

> diff --git a/about/include/backends.inc b/about/include/backends.inc
> index f23995f..0b1cf5b 100644
> --- a/about/include/backends.inc
> +++ b/about/include/backends.inc
> @@ -1,81 +1,114 @@
>  <h2>About Mercury<span class="submenutitle">/ back-ends </span></h2>
>  <p>
> -The Mercury implementation compiles to a wide variety of target languages on a
> -wide variety of platforms.
> +The Mercury implementation compiles Mercury code to C, C# or Java,
> +and works on a wide variety of platforms.
>  </p>
>
>  <div class="backend-container">
>  <div class="backend-item">
> -  <h3>Low level C.</h3>
> +  <h3>Low level C backend.</h3>
>    <p>
> -  Our original back-end.
> -  This one compiles Mercury source to low-level C code.
> -  It works by converting Mercury source into code for an abstract machine, and
> -  then converting the abstract machine instructions into C code with macros for
> -  the abstract machine registers and instructions.
> -  We use C's conditional compilation (<code>#ifdef</code>) to define these
> -  macros as either standard ANSI/ISO C code, or as GNU C code that makes uses of
> -  GNU C extensions such as global register variables, computed gotos, and inline
> -  assembler.
> +  The backend that compiles Mercury code low-level C code
> +  is our original back-end.

Can we settle on one of "backend" or "back-end".  This page is now using
both.

> +  It works by converting Mercury source code
> +  into code for an abstract machine specifically designed Mercury.
> +  This abstract machine manages its own set of abstract machine registers
> +  and its own stacks (one stack for deterministic code,
> +  and another for non deterministic code), and its own heap.
> +  It has no if-then-else or loop constructs,
> +  using only conditional and unconditional branches.
> +  Each instruction of this abstract machine is translated to C code
> +  that relies heavily on macros,
> +  We use C's conditional compilation (<code>#ifdef</code>)
> +  to define these macros as either standard ANSI/ISO C code,
> +  or as GNU C code that uses some GNU C extensions:
> +  global register variables;
> +  the ability to take the address of a label, and later jump to that label; and
> +  using inline assembler to make function-local labels globally visible,
> +  allowing code in one function to jump to into the middle of another function.
> +  (Recent versions of gcc do not support this last capability.)

That last bit is not entirely true, recent versions of GCC on specific
platforms do not support it; on other platforms it's fine.
In any case, it's probably not worth mentioning on this page; the
configure script should select a safe set of GNC C extensions and for
most users that should be the end of the matter.

>    </p>
>    <p>
> -  For more information on the low-level C back-end, see the
> -  <a href="<?php echo $root?>/documentation/papers.html">papers</a>
> -  section of the web site, in particular the papers titled "The
> -  execution algorithm of Mercury: an efficient purely declarative
> -  logic programming language", "Code generation for Mercury",
> -  and "Compiling logic programs to C using GNU C as a portable
> -  assembler".
> +  For more information on the low-level C back-end, see the papers
> +  <ul>
> +  <li>
> +  <a href="<?php echo $root?>/documentation/papers.html#jlp">
> +  The execution algorithm of Mercury: an efficient purely declarative
> +  logic programming language</a>,
> +  <li>
> +  <a href="<?php echo $root?>/documentation/papers.html#code_gen_mit">
> +  Code generation for Mercury</a>, and
> +  <li>
> +  <a href="<?php echo $root?>/documentation/papers.html#mercury_to_c">
> +  Compiling logic programs to C using GNU C as a portable assembler</a>.
> +  </ul>
>    </p>
>  </div>
>
>  <div class="backend-item">
> -  <h3>Java.</h3>
> +  <h3>Java backend.</h3>
>    <p>
>    This back-end compiles Mercury to Java.
>    </p>
>    <p>
> -  The compiler support is complete, it includes good support for interfacing
> -  with Java (see the language reference manual for details), and the standard
> -  library is fairly reasonable.
> -  There is support for Mercury-level debugging, but there is not yet support
> -  for Mercury-level profiling.
> +  The compiler now includes good support for interfacing with Java
> +  (see section 15.10.3 of the language reference manual for details),
> +  There is support for Mercury-level debugging,
> +  but there is not yet support for Mercury-level profiling.
> +  A few backend-specific parts of the Mercury standard library
> +  do not yet have implementations for this backend,
> +  but this affects only a tiny minority
> +  of the standard library's functionality.
>    </p>
>    <p>
> -  For a guide to installing and using the Java grade, refer to README.Java and
> -  the User's Guide. You will need Mercury release 10.04 or later.
> +  For a guide to installing and using the Java grade,
> +  refer to README.Java, and section 6.4 of the User's Guide.
> +  </p>
> +  <p>
> +  You will need Mercury release 10.04 or later.
>    </p>

As mentioned above: delete that paragraph.

>  </div>
>
>  <div class="backend-item">
> -  <h3>C#.</h3>
> +  <h3>C# backend.</h3>
>    <p>
>    This back-end compiles Mercury to C#.
>    </p>
>    <p>
> -  The compiler support is complete, it includes good support for interfacing
> -  with C# (see the language reference manual for details), and the standard
> -  library is fairly reasonable.
> -  There is support for Mercury-level debugging, but there is not yet support
> -  for Mercury-level profiling.
> +  The compiler now includes good support for interfacing with C#
> +  (see section 15.10.2 of the language reference manual for details),
> +  There is support for Mercury-level debugging,
> +  but there is not yet support for Mercury-level profiling.
> +  A few backend-specific parts of the Mercury standard library
> +  do not yet have implementations for this backend,
> +  but this affects only a tiny minority
> +  of the standard library's functionality.
> +  </p>
> +  <p>
> +  For a guide to installing and using the C# grade,
> +  refer to README.CSharp, and section 6.5 of the User's Guide.
>    </p>
>    <p>
> -  For a guide to installing and using the C# grade, refer to README.CSharp and
> -  the User's Guide. You will need Mercury release 11.01 or later.
> +  You will need Mercury release 11.01 or later.
>    </p>

Ditto.

>  </div>
>  </div>

You can go ahead and commit after addressing my review comments and I
will take another look at it.

Julien.