diff: changes to options documentation

Fergus Henderson fjh at cs.mu.OZ.AU
Sat Jan 24 04:07:49 AEDT 1998
Previous message: diff: bug fix for `incr_hp_msg' name clash
Next message: diff: delete obsolete mode number priority hack
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Estimated hours taken: 0.5

compiler/options.m:
	Fix a couple of places where the help messages didn't line up
	or didn't fit in 80 columns.
	Change some old comments that referred to the `mc' script
	to instead talk about the `mmc' script (`mc' was renamed).

compiler/options.m:
doc/user_guide.texi:
	Move the documentation of the termination analysis options
	from the "overall optimization options" section to a new
	"termination analysis options" section.
	(Termination analysis might have some effect on optimization,
	but that is not it's primary purpose, so it doesn't belong
	in the optimization options section at all.)
	In the User Guide, add a pointer to the section on
	termination analysis in the Language Reference Manual.

cvs diff  compiler/options.m doc/user_guide.texi
Index: compiler/options.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.219
diff -u -r1.219 options.m
--- options.m	1998/01/23 12:11:56	1.219
+++ options.m	1998/01/23 16:36:01
@@ -128,10 +128,10 @@
 		;	bytes_per_word
 		;	conf_low_tag_bits
 				% The undocumented conf_low_tag_bits option
-				% is used by the `mc' script to pass the
+				% is used by the `mmc' script to pass the
 				% default value for num_tag_bits
 				% assuming --tags low.
-				% The reason that `mc' doesn't just
+				% The reason that `mmc' doesn't just
 				% pass a default value for --num-tag-bits
 				% is that we want to be able to give an
 				% error message if the user specifies
@@ -365,7 +365,7 @@
 		% Compilation model options (ones that affect binary
 		% compatibility).
 	grade			-	string_special,
-					% the `mc' script will pass the
+					% the `mmc' script will pass the
 					% default grade determined
 					% at configuration time
 	gcc_non_local_gotos	-	bool(yes),
@@ -393,7 +393,7 @@
 					% A good default for the current
 					% generation of architectures.
 	conf_low_tag_bits	-	int(2),
-					% the `mc' script will override the
+					% the `mmc' script will override the
 					% above default with a value determined
 					% at configuration time
 	args			-	string("compact"),
@@ -411,28 +411,28 @@
 	reclaim_heap_on_semidet_failure	-	bool(yes),
 	reclaim_heap_on_nondet_failure	-	bool(yes),
 	have_delay_slot		-	bool(no),
-					% the `mc' script may override the
+					% the `mmc' script may override the
 					% above default if configure says
 					% the machine has branch delay slots
 	num_real_r_regs		-	int(5),
 	num_real_f_regs		-	int(0),
 	num_real_r_temps	-	int(5),
 	num_real_f_temps	-	int(0),
-					% the `mc' script will override the
+					% the `mmc' script will override the
 					% above defaults with values determined
 					% at configuration time
 	cc			-	string("gcc"),
-					% the `mc' script will override the
+					% the `mmc' script will override the
 					% above default with a value determined
 					% at configuration time
 	cflags			-	accumulating([]),
 	cflags_for_regs		-	string(""),
 	cflags_for_gotos	-	string(""),
-					% the `mc' script will override the
+					% the `mmc' script will override the
 					% above two defaults with values
 					% determined at configuration time
 	c_include_directory	-	string(""),
-					% the `mc' script will override the
+					% the `mmc' script will override the
 					% above default with a value determined
 					% at configuration time
 	aditi			-	bool(no),
@@ -1112,6 +1112,7 @@
 	options_help_output,
 	options_help_aux_output,
 	options_help_semantics,
+	options_help_termination,
 	options_help_compilation_model,
 	options_help_code_generation,
 	options_help_optimization,
@@ -1323,6 +1324,44 @@
 	io__write_string("\t\tPerform at most <n> passes of mode inference (default: 30).\n").
 
 
+:- pred options_help_termination(io__state::di, io__state::uo) is det.
+
+options_help_termination -->
+	io__write_string("\nTermination Analysis Options:\n"),
+	io__write_string("\t--enable-term, --enable-termination\n"),
+	io__write_string("\t\tAnalyse each predicate to discover if it terminates.\n"),
+	io__write_string("\t--chk-term, --check-term, --check-termination\n"),
+	io__write_string("\t\tEnable termination analysis, and emit warnings for some\n"),
+	io__write_string("\t\tpredicates or functions that cannot be proved to terminate.  In\n"),
+	io__write_string("\t\tmany cases where the compiler is unable to prove termination\n"),
+	io__write_string("\t\tthe problem is either a lack of information about the\n"),
+	io__write_string("\t\ttermination properties of other predicates, or because language\n"),
+	io__write_string("\t\tconstructs (such as higher order calls) were used which could\n"),
+	io__write_string("\t\tnot be analysed.  In these cases the compiler does not emit a\n"),
+	io__write_string("\t\twarning of non-termination, as it is likely to be spurious.\n"),
+	io__write_string("\t--verb-chk-term, --verb-check-term, --verbose-check-termination\n"),
+	io__write_string("\t\tEnable termination analysis, and emit warnings for all\n"),
+	io__write_string("\t\tpredicates or functions that cannot be proved to terminate.\n"),
+	io__write_string("\t--term-single-arg <n>, --termination-single-argument-analysis <n>\n"),
+	io__write_string("\t\tWhen performing termination analysis, try analyzing\n"),
+	io__write_string("\t\trecursion on single arguments in strongly connected\n"),
+	io__write_string("\t\tcomponents of the call graph that have up to <n> procedures.\n"),
+	io__write_string("\t\tSetting this limit to zero disables single argument analysis.\n"),
+	io__write_string("\t--termination-norm {simple, total, num-data-elems}\n"),
+	io__write_string("\t\tThe norm defines how termination analysis measures the size\n"),
+	io__write_string("\t\tof a memory cell. The `simple' norm says that size is always\n"),
+	io__write_string("\t\tone.  The `total' norm says that it is the number of words\n"),
+	io__write_string("\t\tin the cell.  The `num-data-elems' norm says that it is the\n"),
+	io__write_string("\t\tnumber of words in the cell that contain something other\n"),
+	io__write_string("\t\tthan pointers to cells of the same type.\n"),
+	io__write_string("\t--term-err-limit <n>, --termination-error-limit <n>\n"),
+	io__write_string("\t\tPrint at most <n> reasons for any single termination error\n"),
+	io__write_string("\t\t(default: 3).\n"),
+	io__write_string("\t--term-path-limit <n>, --termination-path-limit <n>\n"),
+	io__write_string("\t\tPerform termination analysis only on predicates\n"),
+	io__write_string("\t\twith at most <n> paths (default: 256).\n").
+
+
 :- pred options_help_compilation_model(io__state::di, io__state::uo) is det.
 
 options_help_compilation_model -->
@@ -1371,13 +1410,13 @@
 	io__write_string("\t\tEnable use of a trail.\n"),
 	io__write_string("\t\tThis is necessary for interfacing with constraint solvers,\n"),
 	io__write_string("\t\tor for backtrackable destructive update.\n"),
-	io__write_string("\t-p, --profiling, --time-profiling\t\t"),
-	io__write_string("\t(grade modifier: `.prof')\n"),
+	io__write_string("\t-p, --profiling, --time-profiling\n"),
+	io__write_string("\t\t\t\t\t(grade modifier: `.prof')\n"),
 	io__write_string("\t\tEnable time and call profiling.  Insert profiling hooks in the\n"),
 	io__write_string("\t\tgenerated code, and also output some profiling\n"),
 	io__write_string("\t\tinformation (the static call graph) to the file\n"),
 	io__write_string("\t\t`<module>.prof'.\n"),
-	io__write_string("\t--memory-profiling\t\t"),
+	io__write_string("\t--memory-profiling\t"),
 	io__write_string("\t(grade modifier: `.memprof')\n"),
 	io__write_string("\t\tEnable memory and call profiling.\n"),
 /*****************
@@ -1428,13 +1467,13 @@
 	io__write_string("\t\tUse <n> tag bits.\n"),
 
 		% The --conf-low-tag-bits option is reserved for use
-		% by the `mc' script; it is deliberately not documented.
+		% by the `mmc' script; it is deliberately not documented.
 
 		% The --bits-per-word option is intended for use
-		% by the `mc' script; it is deliberately not documented.
+		% by the `mmc' script; it is deliberately not documented.
 
 		% The --bytes-per-word option is intended for use
-		% by the `mc' script; it is deliberately not documented.
+		% by the `mmc' script; it is deliberately not documented.
 
 	io__write_string("\t--branch-delay-slot\t"),
 	io__write_string("\t(This option is not for general use.)\n"),
@@ -1544,38 +1583,6 @@
 	io__write_string("\t--transitive-intermodule-optimization\n"),
 	io__write_string("\t\tImport the transitive intermodule optimization data.\n"),
 	io__write_string("\t\tThis data is imported from `<module>.trans_opt' files.\n"),
-	io__write_string("\t--enable-term, --enable-termination\n"),
-	io__write_string("\t\tAnalyse each predicate to discover if it terminates.\n"),
-	io__write_string("\t--chk-term, --check-term, --check-termination\n"),
-	io__write_string("\t\tEnable termination analysis, and emit warnings for some\n"),
-	io__write_string("\t\tpredicates or functions that cannot be proved to terminate.  In\n"),
-	io__write_string("\t\tmany cases where the compiler is unable to prove termination\n"),
-	io__write_string("\t\tthe problem is either a lack of information about the\n"),
-	io__write_string("\t\ttermination properties of other predicates, or because language\n"),
-	io__write_string("\t\tconstructs (such as higher order calls) were used which could\n"),
-	io__write_string("\t\tnot be analysed.  In these cases the compiler does not emit a\n"),
-	io__write_string("\t\twarning of non-termination, as it is likely to be spurious.\n"),
-	io__write_string("\t--verb-chk-term, --verb-check-term, --verbose-check-termination\n"),
-	io__write_string("\t\tEnable termination analysis, and emit warnings for all\n"),
-	io__write_string("\t\tpredicates or functions that cannot be proved to terminate.\n"),
-	io__write_string("\t--term-single-arg <n>, --termination-single-argument-analysis <n>\n"),
-	io__write_string("\t\tWhen performing termination analysis, try analyzing\n"),
-	io__write_string("\t\trecursion on single arguments in strongly connected\n"),
-	io__write_string("\t\tcomponents of the call graph that have up to <n> procedures.\n"),
-	io__write_string("\t\tSetting this limit to zero disables single argument analysis.\n"),
-	io__write_string("\t--termination-norm {simple, total, num-data-elems}\n"),
-	io__write_string("\t\tThe norm defines how termination analysis measures the size\n"),
-	io__write_string("\t\tof a memory cell. The `simple' norm says that size is always one.\n"),
-	io__write_string("\t\tThe `total' norm says that it is the number of words in the cell.\n"),
-	io__write_string("\t\tThe `num-data-elems' norm says that it is the number of words in\n"),
-	io__write_string("\t\tthe cell that contain something other than pointers to cells of\n"),
-	io__write_string("\t\tthe same type.\n"),
-	io__write_string("\t--term-err-limit <n>, --termination-error-limit <n>\n"),
-	io__write_string("\t\tPrint at most <n> reasons for any single termination error\n"),
-	io__write_string("\t\t(default: 3).\n"),
-	io__write_string("\t--term-path-limit <n>, --termination-path-limit <n>\n"),
-	io__write_string("\t\tPerform termination analysis only on predicates\n"),
-	io__write_string("\t\twith at most <n> paths (default: 256).\n"),
 	io__write_string("\t--split-c-files\n"),
 	io__write_string("\t\tGenerate each C function in its own C file,\n"),
 	io__write_string("\t\tso that the linker will optimize away unused code.\n"),
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.113
diff -u -r1.113 user_guide.texi
--- user_guide.texi	1998/01/06 23:51:17	1.113
+++ user_guide.texi	1998/01/23 16:43:57
@@ -1371,6 +1371,7 @@
 * Output options::
 * Auxiliary output options::
 * Language semantics options::
+* Termination analysis options::
 * Compilation model options::
 * Code generation options::
 * Optimization options::
@@ -1755,6 +1756,71 @@
 Perform at most @var{n} passes of mode inference (default: 30).
 @end table
 
+ at node Termination analysis options
+ at section Termination analysis options
+
+For detailed explanations, see the ``Termination analysis'' section
+in Mercury Language Reference Manual.  (It is listed under
+``Implementation dependent pragmas'' in the ``Pragmas'' chapter.)
+
+ at table @code
+ at item --enable-term
+ at itemx --enable-termination
+Enable termination analysis.  Termination analysis analyses each mode of
+each predicate to see whether it terminates.  @samp{pragma terminates},
+ at samp{pragma does_not_terminate} and @samp{pragma check_termination}
+pragmas have no effect unless termination analysis is enabled.  When
+using termination, @samp{--intermodule-optimization} should be enabled,
+as it greatly improves the accuracy of the analysis.
+
+ at sp 1
+ at item --chk-term
+ at itemx --check-term
+ at itemx --check-termination
+Enable termination analysis, and emit warnings for some predicates or
+functions that cannot be proved to terminate.  In many cases in which the
+compiler is unable to prove termination, the problem is either a lack of
+information about the termination properties of other predicates, or the
+fact that the program used language constructs (such as higher order
+calls) which cannot be analysed.  In these cases the compiler does
+not emit a warning of non-termination, as it is likely to be spurious.
+
+ at sp 1
+ at item --verb-chk-term
+ at itemx --verb-check-term
+ at itemx --verbose-check-termination
+Enable termination analysis, and emit warnings for all predicates or
+functions that cannot be proved to terminate.
+
+ at sp 1
+ at item --term-single-arg @var{limit}
+ at itemx --termination-single-argument-analysis @var{limit}
+When performing termination analysis, try analyzing
+recursion on single arguments in strongly connected
+components of the call graph that have up to @var{limit} procedures.
+Setting this limit to zero disables single argument analysis.
+
+ at sp 1
+ at item --termination-norm @var{norm}
+The norm defines how termination analysis measures the size
+of a memory cell. The @samp{simple} norm says that size is always one.
+The @samp{total} norm says that it is the number of words in the cell.
+The @samp{num-data-elems} norm says that it is the number of words in
+the cell that contain something other than pointers to cells of
+the same type.
+
+ at sp 1
+ at item --term-err-limit @var{limit}
+ at itemx --termination-error-limit @var{limit}
+Print at most @var{n} reasons for any single termination error.
+
+ at sp 1
+ at item --term-path-limit @var{limit}
+ at itemx --termination-path-limit @var{limit}
+Perform termination analysis only on predicates with at most @var{n} paths.
+
+ at end table
+
 @node Compilation model options
 @section Compilation model options
 
@@ -2127,62 +2193,6 @@
 files may depend on other @file{@var{module}.trans_opt} files.
 @file{@var{module}.opt} files may only depend on the
 @file{@var{module}.m} file.
-
- at sp 1
- at item --enable-term
- at itemx --enable-termination
-Enable termination analysis.  Termination analysis analyses each mode of
-each predicate to see whether it terminates.  @samp{pragma terminates},
- at samp{pragma does_not_terminate} and @samp{pragma check_termination}
-pragmas have no effect unless termination analysis is enabled.  When
-using termination, @samp{--intermodule-optimization} should be enabled,
-as it greatly improves the accuracy of the analysis.
-
- at sp 1
- at item --chk-term
- at itemx --check-term
- at itemx --check-termination
-Enable termination analysis, and emit warnings for some predicates or
-functions that cannot be proved to terminate.  In many cases in which the
-compiler is unable to prove termination, the problem is either a lack of
-information about the termination properties of other predicates, or the
-fact that the program used language constructs (such as higher order
-calls) which cannot be analysed.  In these cases the compiler does
-not emit a warning of non-termination, as it is likely to be spurious.
-
- at sp 1
- at item --verb-chk-term
- at itemx --verb-check-term
- at itemx --verbose-check-termination
-Enable termination analysis, and emit warnings for all predicates or
-functions that cannot be proved to terminate.
-
- at sp 1
- at item --term-single-arg @var{limit}
- at itemx --termination-single-argument-analysis @var{limit}
-When performing termination analysis, try analyzing
-recursion on single arguments in strongly connected
-components of the call graph that have up to @var{limit} procedures.
-Setting this limit to zero disables single argument analysis.
-
- at sp 1
- at item --termination-norm @var{norm}
-The norm defines how termination analysis measures the size
-of a memory cell. The @samp{simple} norm says that size is always one.
-The @samp{total} norm says that it is the number of words in the cell.
-The @samp{num-data-elems} norm says that it is the number of words in
-the cell that contain something other than pointers to cells of
-the same type.
-
- at sp 1
- at item --term-err-limit @var{limit}
- at itemx --termination-error-limit @var{limit}
-Print at most @var{n} reasons for any single termination error.
-
- at sp 1
- at item --term-path-limit @var{limit}
- at itemx --termination-path-limit @var{limit}
-Perform termination analysis only on predicates with at most @var{n} paths.
 
 @sp 1
 @item --split-c-files
-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.
Previous message: diff: bug fix for `incr_hp_msg' name clash
Next message: diff: delete obsolete mode number priority hack
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the developers mailing list