[m-rev.] diff: declarative debugger documentation

[Fergus Henderson]

Estimated hours taken: 2
Branches: main

Fix some inconsistent documentation of the declarative debugging
options and grades.  This finishes off Zoltan's earlier change
to expunge all mention of the `--decl-debug' option and `.decldebug'
grade component from the user documentation, and adds mention of
`--trace rep' in some places where previously it was missing.

doc/user_guide.texi:
	- Fix a typo in some XXX comments: s/usefull/usefully/
	- Comment out all remaining occurrences of `.decldebug'

compiler/options.m:
	- Mention (again) that all options should be documented,
	  and describe in detail how/where it should be done.
	- Add a pointer to the documentation for the
	  stack_trace, require_tracing, and decl_debug options
	  in runtime/mercury_conf_param.h.
	- Update the explanation of why `--trace decl' isn't included
	  in the help message; the previous explanation was no longer true.
	- Include `--trace rep' in the help message,
	  since it is documented in the user guide.
	- Don't include `--decl-debug' in the help message,
	  since its documentation is commented out in the user guide.

Workspace: /home/ceres/fjh/ws-ceres2/mercury
Index: compiler/options.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.388
diff -u -d -r1.388 options.m
--- compiler/options.m	19 Sep 2002 13:58:59 -0000	1.388
+++ compiler/options.m	10 Oct 2002 13:35:44 -0000
@@ -52,6 +52,20 @@
 	% Quote an argument to a shell command.
 :- func quote_arg(string) = string.
 
+	% NOTE: ALL OPTIONS SHOULD BE DOCUMENTED!
+	%
+	% Officially supported options should be documented both in the
+	% help message output by options_help/2, and also in the
+	% "invocation" chapter of doc/user_guide.texi.
+	%
+	% Options which are not officially supported (e.g. those used
+	% internally by the Mercury implementation, those which are not
+	% sufficiently useful to be worth mentioning in the User Guide,
+	% or options for experimental features that are not yet stable
+	% enough to be officially supported should still be documented.
+	% The documentation can go either next to the option definition
+	% here, or as commented-out code in the appropriate subroutine
+	% of options_help/2.
 :- type option	
 	% Warning options
 		--->	inhibit_warnings
@@ -173,6 +187,12 @@
 		% Compilation model options for optional features:
 
 		%   (a) Debugging
+		%	For documentation of the stack_trace, require_tracing,
+		%	and decl_debug options, see the documentation for
+		%	MR_STACK_TRACE, MR_REQUIRE_TRACING, and MR_DECL_DEBUG
+		%	in runtime/mercury_conf_param.h.
+		%	The debug option just means both stack_trace and
+		%	require_tracing.
 		;	debug
 		;	stack_trace
 		;	require_tracing
@@ -2407,9 +2427,10 @@
 		"\twhen using Mmake. This is recommended when building a",
 		"\tlibrary for installation.",
 
-% declarative debugging is not documented yet, since it is still experimental
+% "--trace decl" is not documented, because it is for backwards
+% compatibility only.  It is now equivalent to `--trace rep'.
 %		"--trace {minimum, shallow, deep, decl, rep, default}",
-		"--trace {minimum, shallow, deep, default}",
+		"--trace {minimum, shallow, deep, rep, default}",
 		"\tGenerate code that includes the specified level", 
 		"\tof execution tracing.",
 		"\tSee the Debugging chapter of the Mercury User's Guide",
@@ -2667,13 +2688,17 @@
 		"\tSee the Debugging chapter of the Mercury User's Guide",
 		"\tfor details.",
 		"\tThis option is not yet supported for the `--high-level-code'",
-		"\tback-ends.",
-		"--decl-debug\t\t\t\t(grade modifier: `.decldebug')",
-		"\tEnable declarative debugging.",
-		"\tSee the Debugging chapter of the Mercury User's Guide",
-		"\tfor details.",
-		"\tThis option is not yet supported for the `--high-level-code'",
 		"\tback-ends."
+% The --decl-debug option is not documented because the .decldebug grade
+% is not installed by default, and because the .decldebug grade is not
+% usefully different from the .debug grade.
+%		"--decl-debug\t\t\t\t(grade modifier: `.decldebug')",
+%		"\tEnable full support for declarative debugging.",
+%		"\tThis ensures that .",
+%		"\tSee the Debugging chapter of the Mercury User's Guide",
+%		"\tfor details.",
+%		"\tThis option is not yet supported for the `--high-level-code'",
+%		"\tback-ends."
 	]),
 	io__write_string("      Profiling\n"),
 	write_tabbed_lines([
@@ -2911,7 +2936,7 @@
 %		"\tBox no-tag types.  This option is disabled by default."
 
 	]),
-	io__write_string("\n      Developer Optional features\n"),
+	io__write_string("\n      Developer optional features\n"),
 	write_tabbed_lines([
 		"--use-minimal-model",
 		"(This option is not for general use.)",
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.330
diff -u -d -r1.330 user_guide.texi
--- doc/user_guide.texi	10 Oct 2002 07:40:13 -0000	1.330
+++ doc/user_guide.texi	10 Oct 2002 13:30:32 -0000
@@ -1175,12 +1175,12 @@
 To use the debugger, you must
 first compile your program with debugging enabled.
 You can do this by using
- at c XXX .decldebug isn't usefull different from .debug
+ at c XXX .decldebug isn't usefully different from .debug
 @c one of the @samp{--debug} and @samp{--decl-debug} options
 the @samp{--debug} option
 when invoking @samp{mmc},
 or by including @samp{GRADEFLAGS = --debug}
- at c XXX .decldebug isn't usefull different from .debug
+ at c XXX .decldebug isn't usefully different from .debug
 @c or @samp{GRADEFLAGS = --decl-debug}
 in your @file{Mmakefile}.
 
@@ -1611,7 +1611,7 @@
 The simpler way is to compile a program in a debugging grade,
 which you can do directly by specifying a grade
 that includes the word ``debug'' (e.g.@: @samp{asm_fast.gc.debug}),
- at c XXX .decldebug isn't usefull different from .debug
+ at c XXX .decldebug isn't usefully different from .debug
 @c or indirectly by specifying one of the @samp{--debug} or @samp{--decl-debug}
 @c grade options to the compiler, linker, and other tools
 or indirectly by specifying the @samp{--debug}
@@ -4323,7 +4323,7 @@
 @findex --trace-level @var{level}
 Generate code that includes the specified level of execution tracing.
 The @var{level} should be one of
- at samp{none}, @samp{shallow}, @samp{deep}, and @samp{default}.
+ at samp{none}, @samp{shallow}, @samp{deep}, @samp{rep} and @samp{default}.
 See @ref{Debugging}.
 
 @item --trace-optimized
@@ -4703,7 +4703,8 @@
 @cindex .agc (grade modifier)
 @cindex .rt (grade modifier)
 @cindex .debug (grade modifier)
- at cindex .decldebug (grade modifier)
+ at c XXX .decldebug isn't usefully different from .debug
+ at c @cindex .decldebug (grade modifier)
 @cindex .par (grade modifier)
 @cindex prof (grade modifier)
 @cindex memprof (grade modifier)
@@ -4713,7 +4714,8 @@
 @cindex agc (grade modifier)
 @cindex rt (grade modifier)
 @cindex debug (grade modifier)
- at cindex decldebug (grade modifier)
+ at c XXX .decldebug isn't usefully different from .debug
+ at c @cindex decldebug (grade modifier)
 @cindex par (grade modifier)
 @table @asis
 @item What target language to use, and (for C) what combination of GNU C extensions to use:
@@ -4737,7 +4739,9 @@
 @samp{rt} (the default is no reserved tag)
 
 @item What debugging features to enable:
- at samp{debug} and @samp{decldebug} (the default is no debugging features).
+ at c XXX .decldebug isn't usefully different from .debug
+ at c @samp{debug} and @samp{decldebug} (the default is no debugging features).
+ at samp{debug} (the default is no debugging features).
 
 @item Whether to use a thread-safe version of the runtime environment:
 @samp{par} (the default is a non-thread-safe environment).
@@ -4846,7 +4850,7 @@
 @item @samp{.debug}
 @code{--debug}.
 
- at c XXX .decldebug isn't usefull different from .debug
+ at c XXX .decldebug isn't usefully different from .debug
 @c @item @samp{.decldebug}
 @c @code{--decl-debug}.
 
@@ -4977,7 +4981,7 @@
 that allow the program to be debugged with @samp{mdb} (see @ref{Debugging}).
 This option is not yet supported for the @samp{--high-level-code} back-ends.
 
- at c XXX .decldebug isn't usefull different from .debug
+ at c XXX .decldebug isn't usefully different from .debug
 @c @sp 1
 @c @item @code{--decl-debug} (grades: any grade containing @samp{.decldebug})
 @c @findex --decl-debug

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