[m-rev.] for review: updates for non-C grades in user's guide

[Zoltan Somogyi]

2020-06-21 16:51 GMT+10:00 Julien Fischer<jfischer at opturion.com>:
> This was request by Zoltan last month.

Thank you.

> diff --git a/README.Java b/README.Java
> index 49647cb..d8c547d 100644
> --- a/README.Java
> +++ b/README.Java
> @@ -44,7 +44,7 @@ Now you can run hello
> 
>  Note that hello is a simple shell script that invokes the program using the
>  Java interpreter.  The actual class files are stored in the Mercury
> -subdirectory in `classs'.  These class files will be packaged up into Java
> +subdirectory in `classs'.  These class files will be packaged up into a Java
>  archive (JAR) named `hello.jar'.

I think that `classs' needs to be followed by (a) a confirmation that the triple s
is not a typo, and (b) an explanation of the naming scheme that adds the third s.\

> @@ -234,8 +234,10 @@ by the Mercury compiler. The non-standard extensions are necessary
>  to avoid conflicts with system header files.
>  @file{.java}, @file{.class} and @file{.jar} files are Java source code,
>  Java bytecode and Java archives respectively.
> - at file{.cs} files are C# source code.
> - at c XXX mention .dll and .exe?
> + at c when we support shared libraries on Windows .dll will also be used for them.
> + at file{.cs} files are C# source code, @file{.dll} files are library
> +assemblies and, when compiling to C#, @file{.exe} files are process
> +assemblies.
>  @file{.erl} and @file{.beam} files are Erlang source code and
>  bytecode (object) files respectively.

It may be a good idea to put the descriptions of the file kinds specific
to each target language in separate paragraphs.

>  @file{.beams} directories are collections of @file{.beam} files which
> @@ -247,12 +249,11 @@ act like a library archive.
>  @chapter Using the Mercury compiler
>  @cindex Microsoft Management Console
> 
> -Following a long Unix tradition,
> -the Mercury compiler is called @samp{mmc}
> +The Mercury compiler is called @samp{mmc}
>  (for ``Melbourne Mercury Compiler'').
>  @pindex mmc
>  Some of its options (e.g.@: @samp{-c}, @samp{-o}, and @samp{-I})
> -have a similar meaning to that in other Unix compilers.
> +have a similar meaning to that in other compilers.
> 
>  (Note that on Microsoft Windows systems the name @samp{mmc} is also used by the
>  executable for the Microsoft Management Console.

I would add a comma after "systems".

Do we explain anywhere what users need to do if "mmc" resolves to the Windows
management console for them? If not, we should.

> @@ -277,27 +278,65 @@ This argument processing is done recursively.
>  The contents of the @samp{@@file} is split into arguments
>  one per line in the file.
> 
> -To compile a program which consists of just a single source file,
> -use the command
> +To compile a program that consists of a single source file, use the command
> 
>  @example
>  mmc @var{filename}.m
>  @end example
> 
> -Unlike traditional Unix compilers, however,
> - at samp{mmc} will put the executable into a file called @file{@var{filename}},
> -not @file{a.out}.
> +Note that compiling a single source file as above only works when targeting C;
> +if you are generating C#, Java or Erlang you must use the @samp{--make} option.
> +For programs that consist of more than one source file, you can use + at samp{--make} option to @samp{mmc}, or Mmake (@pxref{Using Mmake}).
> +Note that Mmake only works when targeting C; if you are generating C#, Java or
> +Erlang you must use the @samp{--make} option.

All of the above is likely to be confusing. In my experience, if you what you write
follows the schema "Do action A. But if condition C holds, then do action B instead",
then people will do A as soon as they have read the first sentence, even if
condition C holds. (I got this is a lot in lab classes). I have learned to put the
conditions up front.

If you don't want to take a stab at such a rewriting, I will do it after you commit.

> +The use of @samp{mmc --make} is recommended.

> +When targeting C on systems that do not require an executable file extension,
> + at samp{mmc} will put the executable into a file called @file{@var{filename}}; on
> +systems that use the @file{.exe} executable file extension (e.g. Windows) the
> +executable will be put into a file called @file{@var{filename}.exe}.

I would reword the second half as

on systems (such as WIndows) that use .exe as the file extension for executables,
mmc will put the executable into a file called filename.exe.

> +When targeting C#, @samp{mmc} will generate a process assembly called
> + at file{@var{filename}.exe}.
> +On non-Windows systems, @samp{mmc} will also generate a shell script called
> + at file{@var{filename}} that invokes the CLI execution environment
> +on the process assembly.
> +On Windows, the process assembly can be run directly and nothing further
> +is required.

Nothing further than *what* is required?

I would reword as

On Windows, this process assembly can be run directly (hence the .exe suffix).
On non-Windows systems, which cannot run process assemblies directly,
mmc will also generate a shell script called filename that invokes the CLI
execution environment on the process assembly.

> +(See the file @file{README.CSharp} included in the Mercury distribution for
> +further details.)

I would reverse the pointer; i.e. I would move the discussion of Mono and .NET
from README.CSharp to here.

> +When targeting Java, @samp{mmc} will package up all of the class files for the
> +executable into a Java archive (JAR) named @file{@var{filename}.jar}.
> +It will also generate a shell script called @file{@var{filename}} that invokes
> +the program using the Java interpreter.
> +If you are using the Windows command line interpreter, @samp{cmd.exe},

Is cmd.exe usually described as an interpreter?

>  then
> + at samp{mmc} will generate a batch file called @file{@var{filename}.bat} that
> +invokes the program using the Java interpreter instead.

Instead of what?

> +(See the file @file{README.Java} included in the Mercury distribution for
> +further details.)

I would do the same shuffle here.

> +When targeting Erlang, @samp{mmc} will place all of the object files for
> +the executable into the subdirectory @file{Mercury/beams}.
> +It will also generate a shell script named @file{@var{filename}} that starts
> +the Erlang runtime system and runs the program.
> +If you are using the Windows command line interpreter, @samp{cmd.exe}, then
> + at samp{mmc} will generate a batch file called @file{@var{filename}.bat} that
> +starts the Erlang runtime system and runs the program instead.

Again, instead of what?

> +(See the file @file{README.Erlang} included in the Mercury distribution for
> +further details.)

And here.

>  @noindent
> -If you use Mmake or @samp{mmc --make}, then you don't need to understand the
> +If you use Mmake or @samp{mmc --make}, then you do not need to understand the
>  details
>  of how the Mercury implementation goes about building programs.
>  Thus you may wish to skip the rest of this chapter.
> @@ -388,9 +427,9 @@ the name of the C file of every module in the program.
>  The order of the arguments is not important.
>  The @samp{mgnuc} command is the Mercury GNU C compiler;
>  it is a shell script that invokes the GNU C compiler @samp{gcc}
> - at c (or some other C compiler if GNU C is not available)
>  with the options appropriate for compiling
>  the C programs generated by Mercury.
> +Despite the name, it can be used with C compilers other than GNU C.

I would reword the line above the deleted comment as

it is a shell script that invokes the configured C compiler

and then replace the line you added with

(In the early days of the Mercury project, the configured C compiler
was almost always gcc, which is why the name of the script is what it is,
but the script itself will work with clang or MSVC as well.)

> @@ -1041,6 +1081,8 @@ library should be created: @samp{shared} or @samp{static}. The
>  @samp{--lib-linkage} option can be specified multiple times.
>  In our example, the files @samp{libmypackage.a} and @samp{libmypackage.so}
>  should appear in the current directory.
> +(On macOS @samp{libmypackage.dylib} will appear instead of
> + at samp{libmypackage.so}.)

Again, I would put the condition (which in this case is the OS) up front.

> @@ -1348,31 +1390,23 @@ EXTRA_LIBRARIES-foo = mylib4foo
>  @cindex jar files
>  @cindex Java libraries
> 
> -Libraries are handled a little differently for the Java grade.  Instead of
> -compiling object code into a static or shared library, the class files are
> -added to a jar (Java ARchive) file
> -whose name has the form @file{@var{library-name}.jar}.
> -
> -To create or install a Java library, simply specify that you want to use the
> -java grade, either by setting @samp{GRADE=java} in your Mmakefile, or by
> -including @samp{--java} or @samp{--grade java} in your @samp{GRADEFLAGS}, then
> -follow the instructions as above.
> +To create or install a library in the Java grade, specify that you want to
> +use the Java grade and use @samp{mmc --make}.
> +Mmake does @emph{not} support Java targets.
> 
> -Java libraries are installed to the directory
> - at file{@var{prefix}/lib/mercury/lib/java}.  To include them in a program, in
> -addition to the instructions above, you will need to include the installed jar
> -file in your @samp{CLASSPATH}, which you can set using
> - at samp{--java-classpath @var{jarfile}} in @samp{MCFLAGS}.
> +Libraries are compiled to class files that are added to a Java archive (JAR)
> +file whose name has the form @file{@var{library-name}.jar}.

This chunk of the diff deletes some information it does not replace.
Is this intentional, and if so, why?

Other than the above, the diff is fine.

Zoltan.