[m-rev.] for review: document `il' and `hl' grades, etc.

Fergus Henderson fjh at cs.mu.OZ.AU
Mon Nov 4 14:41:53 AEDT 2002
Previous message: [m-rev.] for review: environment variable documentation
Next message: [m-rev.] for review: document `il' and `hl' grades, etc.
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Estimated hours taken: 1.5
Branches: main

Update the documentation to reflect recent changes in what is/is not
supported.

compiler/options.m:
doc/user_guide.texi:
	Document the `--high-level-data' option.
	Document the `il' and `hl' grades.
	Delete documentation of the `ilc' grade.
	Avoid using "Microsoft" for things which are no longer
	Microsoft-specific.
	Various other minor wording changes.

Workspace: /home/ceres/fjh/mercury
Index: compiler/options.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.390
diff -u -d -r1.390 options.m
--- compiler/options.m	22 Oct 2002 04:35:54 -0000	1.390
+++ compiler/options.m	26 Oct 2002 15:02:37 -0000
@@ -2626,14 +2626,15 @@
 		"-s <grade>, --grade <grade>",
 		"\tSelect the compilation model. The <grade> should be one of",
 		"\tthe base grades `none', `reg', `jump', `asm_jump', `fast', ",
-		"\t`asm_fast', `hlc', `ilc', or `java',",
-% These grades (hl, hl_nest, and hlc_nest) are not yet documented, because
+		"\t`asm_fast', `hl', `hlc', `il', or `java',",
+% The hl, hl_nest, and hlc_nest are not yet documented, because
 % the --high-level-data option is not yet supported for C,
 % and the --gcc-nested-functions option is not yet documented.
-%		"\t`hl', `hl_nest', `hlc_nest'",
+% The ilc grade is not documented because it is not useful;
+% it has been superceded by the il grade.
 		"\tor one of those with one or more of the grade modifiers",
-		"\t`.gc', `.mps', `.prof', `.memprof', `.tr', `.rt', `.debug', `.par'",
-		"\tand/or `.pic_reg' appended.",
+		"\t`.gc', `.mps', `.prof', `.memprof', `.tr', `.rt', `.debug',",
+		"\t`.par' and/or `.pic_reg' appended.",
 		"\tDepending on your particular installation, only a subset",
 		"\tof these possible grades will have been installed.",
 		"\tAttempting to use a grade which has not been installed",
@@ -2643,13 +2644,14 @@
 	io__write_string("\n    Target selection compilation model options:\n"),
 	write_tabbed_lines([
 		"--target c\t\t\t(grades: none, reg, jump, fast,",
-		"\t\t\t\t\tasm_jump, asm_fast, hlc)",
+		"\t\t\t\t\tasm_jump, asm_fast, hl, hlc)",
 		"--target asm\t\t\t(grades: hlc)",
-		"--target il\t\t\t(grades: ilc)",
+		"--target il\t\t\t(grades: il)",
 		"--target java\t\t\t(grades: java)",
 		"\tSpecify the target language: C, assembler, IL or Java.",
-		"\tThe default is C.",
-		"\t""IL"" is the Microsoft.NET Intermediate Language.",
+		"\tThe default is C.  ""IL"" (also known as ""CIL"" or ""MSIL"")",
+		"\tis the Intermediate Language for the .NET Common Language",
+		"\tRuntime.",
 		"\tTargets other than C imply `--high-level-code' (see below).",
 		"\tAs an exception to the usual rule for options in this section,",
 		"\twhere different option settings normally correspond to different",
@@ -2750,8 +2752,9 @@
 		"\t\t\t\t`.mps' grades use `--gc mps',",
 		"\t\t\t\tother grades use `--gc none'.)",
 		"\tSpecify which method of garbage collection to use",
-		"\t(default: boehm).  `accurate' GC is not yet implemented.",
-		"\t`conservative' or `boehm' is Hans Boehm et al's conservative collector.",
+		"\t(default: boehm).  `accurate' GC is not yet supported.",
+		"\t`conservative' or `boehm' is Hans Boehm et al's conservative",
+		"\tcollector.",
 		"\t`mps' is a different conservative collector, based on",
 		"\tRavenbrook Limited's MPS (Memory Pool System) kit.",
 		"\tThis option is ignored for the IL and Java back-ends,",
@@ -2795,24 +2798,26 @@
 
 	io__write_string("\n    MLDS back-end compilation model options:\n"),
 	write_tabbed_lines([
-% These grades (hl, hl_nest, and hlc_nest) are not yet documented, because
-% the --high-level-data option is not yet implemented,
-% and the --gcc-nested-functions option is not yet documented.
-%		"-H, --high-level-code\t\t\t(grades: hl, hlc, hl_nest, hlc_nest)",
-		"-H, --high-level-code\t\t\t(grades: hlc, ilc, java)",
+% These grades (hl_nest, and hlc_nest) are not yet documented,
+% because the --gcc-nested-functions option is not yet documented.
+%		"-H, --high-level-code\t\t\t(grades: hl_nest, hlc_nest)",
+% The ilc grade is not documented because it is not useful;
+% it has been superceded by the il grade.
+		"-H, --high-level-code\t\t\t(grades: hl, hlc, il, java)",
 		"\tUse an alternative back-end that generates high-level code",
 		"\trather than the very low-level code that is generated by our",
-		"\toriginal back-end."
-% The --high-level-data option is not yet documented,
+		"\toriginal back-end.",
+% The hl_nest grade is not yet documented,
+% because the --gcc-nested-functions option is not yet documented.
 % because it is not yet supported
-%		"--high-level-data\t\t\t(grades: hl, hl_nest)",
-%		"\tUse an alternative higher-level data representation.",
-% The --high-level option is not yet documented,
-% because --high-level-data is not yet supported
-%		"--high-level\t\t\t(grades: hl, hl_nest)",
-%		"\tAn abbreviation for `--high-level-code --high-level-data'.",
+%		"--high-level-data\t\t\t(grades: hl, hl_nest, il, java)",
+		"--high-level-data\t\t\t(grades: hl, il, java)",
+		"\tUse an alternative higher-level data representation.",
+%		"--high-level\t\t\t(grades: hl, hl_nest, il, java)",
+		"--high-level\t\t\t(grades: hl, il, java)",
+		"\tAn abbreviation for `--high-level-code --high-level-data'."
 % The --gcc-nested-functions option is not yet documented,
-% because it has not been thoroughly tested, and it is
+% because it doesn't pass our test suite, and it is
 % probably not very useful.
 %		"--gcc-nested-functions\t\t(grades: hl_nest, hlc_nest)",
 %		"\tSpecify whether or not to use GNU C's nested functions extension.",
@@ -2874,30 +2879,30 @@
 %		"\tGenerate IL code that assumes that the CLI verifier",
 %		"\tsupports tail calls with byref arguments."
 %
-% The --il-funcptr-types option is not documented because currently there
-% are no IL implementations for which it is useful.
+% The --il-funcptr-types option is not documented because it is not yet
+% implemented.
 %		"--il-funcptr-types",
 %		"\tGenerate IL code that assumes that the IL assembler",
 %		"\tsupports function pointer types."
 %		"\tThe ECMA CLI specification allows function pointer types,"
-%		"\tbut the current (Beta 2) Microsoft CLR implementation"
-%		"\tdoes not support them."
+%		"\tbut some CLR implementations, e.g. the old Beta 2 version of"
+%		"\tthe Microsoft CLR implementation, do not support them."
 	]),
 
 	io__write_string("\n    Developer compilation model options:\n"),
 	io__write_string("\n      Data representation\n"),
 	write_tabbed_lines([
-		"--tags {none, low, high}\t(This option is not for general use.)",
+		"--tags {none, low, high}      (This option is not for general use.)",
 		"\tSpecify whether to use the low bits or the high bits of ",
 		"\teach word as tag bits (default: low).",
 	% 	"\t\t`--tags none' implies `--num-tag-bits 0'.",
-		"--num-tag-bits <n>\t\t(This option is not for general use.)",
+		"--num-tag-bits <n>            (This option is not for general use.)",
 		"\tUse <n> tag bits.",
-		"--num-reserved-addresses <n>\t(This option is not for general use.)",
+		"--num-reserved-addresses <n>  (This option is not for general use.)",
 		"\tTreat the integer values from 0 up to <n> - 1 as reserved",
 		"\taddresses that can be used to represent nullary constructors",
 		"\t(constants) of discriminated union types.",
-		"--num-reserved-objects <n>\t(This option is not for general use.)",
+		"--num-reserved-objects <n>    (This option is not for general use.)",
 		"\tAllocate up to <n> global objects per type,",
 		"\tfor representing nullary constructors",
 		"\t(constants) of discriminated union types.",
@@ -3062,18 +3067,18 @@
 
 	io__write_string("\n    Code generation target options:\n"),
 	write_tabbed_lines([
-		"--branch-delay-slot\t\t(This option is not for general use.)",
+		"--branch-delay-slot    \t(This option is not for general use.)",
 		"\tAssume that branch instructions have a delay slot.",
-		"--num-real-r-regs <n>\t\t(This option is not for general use.)",
+		"--num-real-r-regs <n>  \t(This option is not for general use.)",
 		"\tAssume registers r1 up to r<n> are real general purpose",
 		"\tregisters.",
-		"--num-real-f-regs <n>\t\t(This option is not for general use.)",
+		"--num-real-f-regs <n>  \t(This option is not for general use.)",
 		"\tAssume registers f1 up to f<n> are real floating point",
 		"\tregisters.",
-		"--num-real-r-temps <n>\t\t(This option is not for general use.)",
+		"--num-real-r-temps <n> \t(This option is not for general use.)",
 		"\tAssume that <n> non-float temporaries will fit into",
 		"\treal machine registers.",
-		"--num-real-f-temps <n>\t\t(This option is not for general use.)",
+		"--num-real-f-temps <n> \t(This option is not for general use.)",
 		"\tAssume that <n> float temporaries will fit into",
 		"\treal machine registers."
 	]).
@@ -3473,9 +3478,9 @@
 		% options are are reserved for use by the `mmc' script;
 		% they are deliberately not documented.
 
-		"--javac",
-		"--java-compiler",
-		"\tSpecify which Java compiler to use.  The default is javac.",
+		"--javac <javac>",
+		"--java-compiler <javac>",
+		"\tSpecify which Java compiler to use.  The default is `javac'.",
 		
 		"--java-flags <options>, --java-flag <option>",
 		"\tSpecify options to be passed to the Java compiler.",
@@ -3490,7 +3495,7 @@
 		"\tBy default this is `.class'.",
 
 		"--il-assembler <ilasm>",
-		"\tThe Microsoft IL Assembler.",
+		"\tSpecify the name of the .NET IL Assembler command.",
 		"--ilasm-flags <options>, --ilasm-flag <options>",
 		"\tSpecify options to be passed to the IL assembler.",
 		"\t`--ilasm-flag' should be used for single words which need",
@@ -3503,7 +3508,7 @@
 		"\tto be quoted when passed to the shell.",
 
 		"--csharp-compiler <csc>",
-		"\tSpecify the name of the Microsoft C# Compiler.",
+		"\tSpecify the name of the C# Compiler.  The default is `csc'.",
 		"--csharp-flags <options>, --csharp-flag <option>",
 		"\tSpecify options to be passed to the C# compiler.",
 		"\t`--csharp-flag' should be used for single words which need",
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.333
diff -u -d -r1.333 user_guide.texi
--- doc/user_guide.texi	26 Oct 2002 14:15:33 -0000	1.333
+++ doc/user_guide.texi	26 Oct 2002 14:47:17 -0000
@@ -234,7 +234,7 @@
 @file{.s} files and @file{.pic_s} files are assembly language.
 @file{.java} and @file{.class} files are Java source code
 and Java bytecode respectively.
- at file{.il} files are Microsoft Intermediate Language (MSIL) files
+ at file{.il} files are Intermediate Language (IL) files
 for the .NET Common Language Runtime.
 @c XXX mention .dll and .exe?
 
@@ -543,7 +543,7 @@
 Compiles @var{main-module} to Java bytecode files (@file{*.class}).
 
 @item @var{main-module}.ils
-Compiles @var{main-module} to MSIL files (@file{*.il})
+Compiles @var{main-module} to IL files (@file{*.il})
 for the .NET Common Language Runtime.
 
 @c XXX mention .dlls and .exe targets?
@@ -4803,8 +4803,9 @@
 @cindex asm_jump (compilation grade)
 @cindex fast (compilation grade)
 @cindex asm_fast (compilation grade)
+ at cindex hl (compilation grade)
 @cindex hlc (compilation grade)
- at cindex ilc (compilation grade)
+ at cindex il (compilation grade)
 @cindex java (compilation grade)
 @cindex .prof (grade modifier)
 @cindex .memprof (grade modifier)
@@ -4830,9 +4831,9 @@
 @c @cindex decldebug (grade modifier)
 @cindex par (grade modifier)
 @table @asis
- at item What target language to use, and (for C) what combination of GNU C extensions to use:
+ at item What target language to use, what data representation to use, and (for C) what combination of GNU C extensions to use:
 @samp{none}, @samp{reg}, @samp{jump}, @samp{asm_jump},
- at samp{fast}, @samp{asm_fast}, @samp{hlc}, @samp{ilc} and @samp{java}
+ at samp{fast}, @samp{asm_fast}, @samp{hl}, @samp{hlc}, @samp{il} and @samp{java}
 (the default is system dependent).
 
 @item What garbage collection strategy to use:
@@ -4914,11 +4915,14 @@
 @item @samp{hlc}
 @code{--target c --high-level-code}.
 
- at item @samp{ilc}
- at code{--target il --high-level-code}.
+ at item @samp{hl}
+ at code{--target c --high-level-code --high-level-data}.
+
+ at item @samp{il}
+ at code{--target il --high-level-code --high-level-data}.
 
 @item @samp{java}
- at code{--target java --high-level-code}.
+ at code{--target java --high-level-code --high-level-data}.
 
 @item @samp{.gc}
 @code{--gc boehm}.
@@ -4975,13 +4979,14 @@
 @cindex Target options
 
 @table @asis
- at item @code{--target c} (grades: none, reg, jump, fast, asm_jump, asm_fast, hlc)
+ at item @code{--target c} (grades: none, reg, jump, fast, asm_jump, asm_fast, hl, hlc)
 @item @code{--target asm} (grades: hlc)
- at itemx @code{--il}, @code{--target il} (grades: ilc)
+ at itemx @code{--il}, @code{--target il} (grades: il)
 @itemx @code{--java}, @code{--target java} (grades: java)
 Specify the target language used for compilation: C, assembler, IL or Java.
 C means ANSI/ISO C, optionally with GNU C extensions (see below).
-IL means the Microsoft .NET Intermediate Language.
+IL means the Intermediate Language of the .NET Common Language Runtime.
+(IL is sometimes also known as "CIL" or "MSIL".)
 Targets other than C imply @samp{--high-level-code}.
 
 @sp 1
@@ -5071,13 +5076,18 @@
 @cindex MLDS back-end compilation model options
 
 @table @asis
- at item @code{-H}, @code{--high-level-code} (grades: hlc, ilc, java)
+ at item @code{-H}, @code{--high-level-code} (grades: hl, hlc, il, java)
 @findex -H
 @findex --high-level-code
 Use an alternative back-end that generates high-level code
 rather than the very low-level code that is generated by our
 original back-end.
 
+ at item @code{--high-level-data} (grades: hl, il, java)
+ at findex --high-level-data
+Use an alternative, higher-level data representation that uses structs
+or classes, rather than treating all objects as arrays.
+
 @end table
 
 @node Optional features compilation model options
@@ -6815,13 +6825,13 @@
 This is the second preferred foreign language for IL code generation.
 
 @item @samp{IL}
-IL (or CIL) is the intermediate language of the .NET Common Language
-Runtime.
+IL is the intermediate language of the .NET Common Language
+Runtime (sometimes also known as CIL or MSIL).
 Only available on backends that compile to IL.
 This is the preferred foreign language for IL code generation.
 
 @item @samp{Managed C++}
-Managed Extensions for C++ is a language based on C++ that
+Microsoft Managed Extensions for C++ is a language based on C++ that
 provide support for writing .NET components, by adding extra
 keywords and syntax.
 Only available on backends that compile to IL.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------
Previous message: [m-rev.] for review: environment variable documentation
Next message: [m-rev.] for review: document `il' and `hl' grades, etc.
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the reviews mailing list