[m-rev.] for review: document trace count tools

[Ian MacLarty]

On Wed, Sep 13, 2006 at 10:55:00PM +1000, Julien Fischer wrote:
> 
> On Wed, 13 Sep 2006, Ian MacLarty wrote:
> 
> >Here's the new diff:
> >
> >Index: doc/user_guide.texi
> >===================================================================
> >RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
> >retrieving revision 1.489
> >diff -u -r1.489 user_guide.texi
> >--- doc/user_guide.texi	4 Sep 2006 01:47:34 -0000	1.489
> >+++ doc/user_guide.texi	13 Sep 2006 08:08:12 -0000
> >@@ -1193,6 +1193,7 @@
> >* I/O tabling::
> >* Debugger commands::
> >* Declarative debugging::
> >+* Trace counts::
> >@end menu
> >
> >@node Quick overview
> >@@ -3706,10 +3707,10 @@
> >This can be done by compiling the program with deep tracing enabled
> >(either by compiling in a .debug or .decldebug grade
> >or with the @samp{--trace deep} or @samp{--trace rep} compiler options)
> >-and then running the program
> >-with the MERCURY_OPTIONS environment variable set to @samp{--trace-count}.
> >-This will generate a file called @samp{.mercury_trace_counts}
> >-which contains a summary of the program's execution.
> >+and then running the program under mtc.
> >+This will generate a file with the prefix
> >+ at samp{.mercury_trace_counts} and a unique suffix,
> >+that contains a summary of the program's execution
> >This summary is called a slice.
> >Copy the generated slice to a new file for each test case,
> >to end up with some passing slices,
> 
> Is this last step necessary now that each of the trace count files has 
> a unique suffix?
> 

Not necessary, but it's useful otherwise it's hard to remember which
slices are for passing runs and which are for failing runs.

> >+
> >+The mslice tool is invoked using a command of the form:
> >+ at example
> >+mslice [-s sortspec] [-l N] [-m module] file
> >+ at end example
> >+ at sp 1
> >+where @samp{file} may be a generated trace counts file, or a file 
> >containing
> 
> Is it a "trace counts" file or "trace count" file?
> 

I've changed to "trace count file" throughout.

I've adopted your other changes and also documented the -f mtc option.

The changes are now committed (at your request).

Here's the interdiff:

diff -u doc/user_guide.texi doc/user_guide.texi
--- doc/user_guide.texi	13 Sep 2006 08:08:12 -0000
+++ doc/user_guide.texi	14 Sep 2006 00:46:58 -0000
@@ -4703,12 +4703,14 @@
 @node Trace counts
 @section Trace counts
 
-A program with debugging enabled can be run in a special mode that causes it
-to dump out a summary of its execution,
-called a @emph{trace count} or @emph{slice}.
+A program with debugging enabled may be run in a special mode that causes it
+to write out a summary of its execution to a file.
+This summary is called a @emph{trace count} or @emph{slice}.
 A slice is a record of how many times each @emph{label} in the program was
 executed for a particular run.
-A label is a point in the source code where a debugger event can be triggered.
+A label is a point in the source code where a debugger event,
+such as CALL or EXIT,
+can be triggered.
 
 Slices are useful for determining what parts of a failing program are being run
 and possibly causing the failure.
@@ -4734,16 +4736,24 @@
 arguments after the program name.
 @sp 1
 For example:
+ at sp 1
 @example
 mtc ./myprog arg1 arg2
 @end example
 @sp 1
-The program will run as usual, except that when it terminates it will dump
-a summary of the run to a file with the prefix @samp{.mercury_trace_counts}
+The program will run as usual, except that when it terminates it will write
+a summary of the run to a file.
+ at sp 1
+ at samp{mtc} accepts an @samp{-f} or @samp{--output-file} option.
+The argument to this option is the filename to use for the generated
+trace count file.
+If this option is not given then the trace count will be written to a
+file with the prefix @samp{.mercury_trace_counts}
 and a unique suffix.
-The generated slice can then be analysed with the @samp{mslice}
-and @samp{mdice} tools
-and can also be used to help direct a declarative debugging search
+ at sp 1
+The generated slice can then be analysed by the @samp{mslice}
+and @samp{mdice} tools.
+It can also be used to help direct a declarative debugging search
 (see @ref{Search Modes}).
 
 @node mslice
@@ -4762,19 +4772,20 @@
 pred mrg.msort_n/4-0 <?;>      mrg.m:35     12 (1)
 @end example
 @sp 1
-Each row corresponds to a label in the program and the meanings of the columns
-are as follows:
+Each row corresponds to a label in the program.
+The meanings of the columns are as follows:
 @itemize @bullet
 @item @samp{Procedure}:
 This column displays the procedure that the label relates to.
 @item @samp{Path/Port}:
 For labels that generate interface events this column displays          
 the event port and for labels that generate internal events it          
-displays the goal path.            
+displays the goal path. (See @ref{Tracing of Mercury programs} for an
+explanation of interface and internal events.)
 @item @samp{File:Line}:
 This column displays the context of the label.
 @item @samp{Count}:
-This column displays how many times the particular label was executed.
+This column displays how many times the label was executed.
 The number in parentheses for each label row says in how many runs the label
 was executed.
 The number in parentheses in the heading row (after the word "Count")
@@ -4788,7 +4799,7 @@
 mslice [-s sortspec] [-l N] [-m module] file
 @end example
 @sp 1
-where @samp{file} may be a generated trace counts file, or a file containing
+where @samp{file} may be a generated trace count file, or a file containing
 a list of generated trace count file names.
 @sp 1
 The @samp{-s} or @samp{--sort} option specifies how the output should be
@@ -4840,15 +4851,16 @@
 but never during the passing test runs,
 so this would be a good place to start looking for a bug.
 @sp 1
-Each row corresponds to a label in the program and the meanings of the
-columns are as follows:
+Each row corresponds to a label in the program. 
+The meanings of the columns are as follows:
 @itemize @bullet
 @item @samp{Procedure}:
 This column displays the procedure the label relates to.
 @item @samp{Path/Port}:
 For labels that generate interface events this column displays          
 the event port and for labels that generate internal events it          
-displays the goal path.
+displays the goal path. (See @ref{Tracing of Mercury programs} for an
+explanation of interface and internal events.)
 @item @samp{File:Line}:
 This column displays the context of the label.
 @item @samp{Pass (total passing test runs)}:
@@ -4863,7 +4875,7 @@
 test run(s).
 @item @samp{Suspicion}:
 This columns displays a number between 0 and 1 which gives an indication of how
-likely a particular goal is to be buggy. 
+likely a particular goal is to contain a bug. 
 The suspicion is calculated as Suspicion = F / (P + F) where F is the number of
 times the goal was executed in failing runs and P is the number of times
 the goal was executed in passing runs.
@@ -4874,10 +4886,10 @@
 @example
 mdice [-s sortspec] [-l N] [-m module] passfile failfile
 @end example
- at samp{passfile} is either a generated trace counts file for a passing run,
+ at samp{passfile} is either a generated trace count file for a passing run,
 or a file containing a list of generated trace count filenames for passing
 runs.
- at samp{failfile} is either a generated trace counts file for a failing run,
+ at samp{failfile} is either a generated trace count file for a failing run,
 or a file containing a list of generated trace count filenames for failing
 runs.
 @sp 1
@@ -4904,16 +4916,16 @@
 displayed.
 @sp 1
 The @samp{-m} or @samp{--module} option limits the output to the given module
-and its submodules, if any.
+and any submodules.
 
 @sp 1
 
 @node mtc_union
 @subsection mtc_union
 
-The @samp{mtc_union} tool can be used to combine several trace counts files
-into one trace counts file.
-This is useful when you have many trace counts files you wish to analyse with
+The @samp{mtc_union} tool can be used to combine several trace count files
+into one trace count file.
+This is useful when you have many trace count files you wish to analyse with
 @samp{mslice} or @samp{mdice}.
 It avoids the overhead of reading all the files
 each time @samp{mslice} or @samp{mdice} is invoked.
@@ -4924,11 +4936,11 @@
 mtc_union [-v] -o output_file file1 file2 ...
 @end example
 @sp 1
- at samp{file1}, @samp{file2}, etc. are the trace counts files that should be
+ at samp{file1}, @samp{file2}, etc. are the trace count files that should be
 combined.
-The new trace counts file will be written to @samp{output_file}.
-If the @samp{-v} or @samp{--verbose} option is present then a progress
-message will be displayed as files are merged.
+The new trace count file will be written to @samp{output_file}.
+If the @samp{-v} or @samp{--verbose} option is specified then a progress
+message will be displayed as the files are merged.
 
 @c ----------------------------------------------------------------------------
 
--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------