Overhaul Massif's manual, and a few minor related things.

git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10706 a5019735-40e9-0310-863c-91ae7b9d1cf9

Author: njn

cachegrind/docs/cg-manual.xml

@@ -441,8 +441,7 @@ configuration, or failing that, via defaults).</para>
             <option>%p</option> and <option>%q</option> format specifiers
             can be used to embed the process ID and/or the contents of an
             environment variable in the name, as is the case for the core
-            option <option>--log-file</option>.  See <link
-            linkend="manual-core.basicopts">here</link> for details.
+            option <option><xref linkend="opt.log-file"/></option>.
       </para>
     </listitem>
   </varlistentry>

callgrind/docs/cl-manual.xml

@@ -534,8 +534,7 @@ These options influence the name and format of the profile data files.
             <option>%p</option> and <option>%q</option> format specifiers
             can be used to embed the process ID and/or the contents of an
             environment variable in the name, as is the case for the core
-            option <option>--log-file</option>.  See <link
-            linkend="manual-core.basicopts">here</link> for details.
+            option <option><xref linkend="opt.log-file"/></option>.
             When multiple dumps are made, the file name
             is modified further; see below.</para> 
     </listitem>

massif/docs/ms-manual.xml

@@ -61,7 +61,7 @@ is unlikely to affect the heap memory usage.</para>
 <para>Then, to gather heap profiling information about the program
 <computeroutput>prog</computeroutput>, type:</para>
 <screen><![CDATA[
-% valgrind --tool=massif prog
+valgrind --tool=massif prog
 ]]></screen>
 
 <para>The program will execute (slowly).  Upon completion, no summary
@@ -74,7 +74,7 @@ data is written to a file.  By default, this file is called
 the ms_print script.  If the output file's name is
 <filename>massif.out.12345</filename>, type:</para>
 <screen><![CDATA[
-% ms_print massif.out.12345]]></screen>
+ms_print massif.out.12345]]></screen>
 
 <para>ms_print will produce (a) a graph showing the memory consumption over
 the program's execution, and (b) detailed information about the responsible
@@ -257,7 +257,7 @@ deallocate heap memory, Massif will not record a peak snapshot.</para>
 
 <para>Some more details about the peak:  the peak is determined by looking
 at every allocation, i.e. it is <emphasis>not</emphasis> just the peak among
-the regular snapshots.  However, recording the true peak is expensive, and
+the regular snapshots.  However, recording the true peak can be expensive, and
 so by default Massif records a peak whose size is within 1% of the size of
 the true peak.  See the description of the
 <option>--peak-inaccuracy</option> option below for more
@@ -350,12 +350,11 @@ a small amount of information is recorded for each one:</para>
   <option>--heap-admin</option> option.</para>
 
   <para>Second, allocators often round up the number of bytes asked for to a
-  larger number.  By default, if N bytes are asked for, Massif rounds N up
-  to the nearest multiple of 8 that is equal to or greater than N.  This is
-  typical behaviour for allocators, and is required to ensure that elements
-  within the block are suitably aligned.  The rounding size can be changed
-  with the <option>--alignment</option> option, although it
-  cannot be less than 8, and must be a power of two.</para></listitem>
+  larger number, usually 8 or 16.  This is required to ensure that elements
+  within the block are suitably aligned.  If N bytes are asked for, Massif
+  rounds N up to the nearest multiple of the value specified by the
+  <option><xref linkend="opt.alignment"/></option> option.
+  </para></listitem>
 
   <listitem><para>The size of the stack(s).  By default, stack profiling is
   off as it slows Massif down greatly.  Therefore, the stack column is zero
@@ -377,7 +376,7 @@ indicates all heap allocation functions such as <function>malloc</function>
 and C++ <function>new</function>.  All heap allocations go through these
 functions, and so all 9,000 useful bytes (which is 99.21% of all allocated
 bytes) go through them.  But how were <function>malloc</function> and new
-called?  At this point, every allocation so far has been due to line 21
+called?  At this point, every allocation so far has been due to line 20
 inside <function>main</function>, hence the second line in the tree.  The
 <option>-></option> indicates that main (line 20) called
 <function>malloc</function>.</para>
@@ -407,9 +406,9 @@ inside <function>main</function>, hence the second line in the tree.  The
 ]]></screen>
 
 <para>The first four snapshots are similar to the previous ones.  But then
-the global allocation peak is reached, and a detailed snapshot is taken.
-Its allocation tree shows that 20,000B of useful heap memory has been
-allocated, and the lines and arrows indicate that this is from three
+the global allocation peak is reached, and a detailed snapshot (number 14)
+is taken.  Its allocation tree shows that 20,000B of useful heap memory has
+been allocated, and the lines and arrows indicate that this is from three
 different code locations: line 20, which is responsible for 10,000B
 (49.74%);  line 5, which is responsible for 8,000B (39.79%); and line 10,
 which is responsible for 2,000B (9.95%).</para>
@@ -529,16 +528,16 @@ file, which will almost certainly make it unreadable by ms_print.</para>
 
   <varlistentry id="opt.heap-admin" xreflabel="--heap-admin">
     <term>
-      <option><![CDATA[--heap-admin=<number> [default: 8] ]]></option>
+      <option><![CDATA[--heap-admin=<size> [default: 8] ]]></option>
     </term>
     <listitem>
       <para>If heap profiling is enabled, gives the number of administrative
       bytes per block to use.  This should be an estimate of the average,
       since it may vary.  For example, the allocator used by
       glibc on Linux requires somewhere between 4 to
-      15 bytes per block, depending on various factors.  It also requires
-      admin space for freed blocks, although Massif does not account
-      for this.</para>
+      15 bytes per block, depending on various factors.  That allocator also
+      requires admin space for freed blocks, but Massif cannot
+      account for this.</para>
     </listitem>
   </varlistentry>
 
@@ -550,9 +549,9 @@ file, which will almost certainly make it unreadable by ms_print.</para>
       <para>Specifies whether stack profiling should be done.  This option
       slows Massif down greatly, and so is off by default.  Note that Massif
       assumes that the main stack has size zero at start-up.  This is not
-      true, but measuring the actual stack size is not easy, and it reflects
-      the size of the part of the main stack that a user program actually
-      has control over.</para>
+      true, but doing otherwise accurately is difficult.  Furthermore,
+      starting at zero better indicates the size of the part of the main
+      stack that a user program actually has control over.</para>
     </listitem>
   </varlistentry>
 
@@ -580,11 +579,11 @@ file, which will almost certainly make it unreadable by ms_print.</para>
       This option can be specified multiple times on the command line, to
       name multiple functions.</para>
 
-      <para>Note that overloaded C++ names must be written in full.  Single
-      quotes may be necessary to prevent the shell from breaking them up.
-      For example:
+      <para>Note that C++ names are demangled.  Note also that overloaded
+      C++ names must be written in full.  Single quotes may be necessary to
+      prevent the shell from breaking them up.  For example:
 <screen><![CDATA[
---alloc-fn='operator new(unsigned, std::nothrow_t const&amp;)'
+--alloc-fn='operator new(unsigned, std::nothrow_t const&)'
 ]]></screen>
       </para>
       </listitem>
@@ -597,7 +596,7 @@ file, which will almost certainly make it unreadable by ms_print.</para>
     <listitem>
       <para>Any direct heap allocation (i.e. a call to
       <function>malloc</function>, <function>new</function>, etc, or a call
-      to a function name in a <option>--alloc-fn</option>
+      to a function named by an <option>--alloc-fn</option>
       option) that occurs in a function specified by this option will be
       ignored.  This is mostly useful for testing purposes.  This option can
       be specified multiple times on the command line, to name multiple
@@ -611,8 +610,8 @@ file, which will almost certainly make it unreadable by ms_print.</para>
       <function>realloc</function>.
       </para>
 
-      <para>Note that overloaded C++ names must be written in full, as for
-      <option>--alloc-fn</option> above.
+      <para>The rules for writing C++ function names are the same as
+      for <option>--alloc-fn</option> above.
       </para>
       </listitem>
   </varlistentry>
@@ -623,9 +622,9 @@ file, which will almost certainly make it unreadable by ms_print.</para>
     </term>
     <listitem>
       <para>The significance threshold for heap allocations, as a
-      percentage.  Allocation tree entries that account for less than this
-      will be aggregated.  Note that this should be specified in tandem with
-      ms_print's option of the same name.</para>
+      percentage of total memory size.  Allocation tree entries that account
+      for less than this will be aggregated.  Note that this should be
+      specified in tandem with ms_print's option of the same name.</para>
     </listitem>
   </varlistentry>
 
@@ -647,7 +646,7 @@ file, which will almost certainly make it unreadable by ms_print.</para>
 
   <varlistentry id="opt.time-unit" xreflabel="--time-unit">
     <term>
-      <option><![CDATA[--time-unit=i|ms|B [default: i] ]]></option>
+      <option><![CDATA[--time-unit=<i|ms|B> [default: i] ]]></option>
     </term>
     <listitem>
       <para>The time unit used for the profiling.  There are three
@@ -692,21 +691,11 @@ file, which will almost certainly make it unreadable by ms_print.</para>
       <option>%p</option> and <option>%q</option> format specifiers can be
       used to embed the process ID and/or the contents of an environment
       variable in the name, as is the case for the core option
-      <option>--log-file</option>.  See <xref
-      linkend="manual-core.basicopts"/> for details.
+      <option><xref linkend="opt.log-file"/></option>.
       </para>
     </listitem>
   </varlistentry>
 
-  <varlistentry id="opt.alignment" xreflabel="--alignment">
-    <term>
-      <option><![CDATA[--alignment=<n> [default: 1.0] ]]></option>
-    </term>
-    <listitem>
-      <para>The minimum alignment (and thus size) of heap blocks.</para>
-    </listitem>
-  </varlistentry>
-
 </variablelist>
 <!-- end of xi:include in the manpage -->
 
@@ -731,7 +720,7 @@ file, which will almost certainly make it unreadable by ms_print.</para>
 
   <varlistentry>
     <term>
-      <option><![CDATA[-v --version ]]></option>
+      <option><![CDATA[--version ]]></option>
     </term>
     <listitem>
       <para>Show the version number.</para>
@@ -750,7 +739,7 @@ file, which will almost certainly make it unreadable by ms_print.</para>
 
   <varlistentry>
     <term>
-      <option><![CDATA[--x=<n> [default: 72]]]></option>
+      <option><![CDATA[--x=<4..1000> [default: 72]]]></option>
     </term>
     <listitem>
       <para>Width of the graph, in columns.</para>
@@ -759,7 +748,7 @@ file, which will almost certainly make it unreadable by ms_print.</para>
 
   <varlistentry>
     <term>
-      <option><![CDATA[--y=<n> [default: 20] ]]></option>
+      <option><![CDATA[--y=<4..1000> [default: 20] ]]></option>
     </term>
     <listitem>
       <para>Height of the graph, in rows.</para>
@@ -775,9 +764,9 @@ file, which will almost certainly make it unreadable by ms_print.</para>
 <para>Massif's file format is plain text (i.e. not binary) and deliberately
 easy to read for both humans and machines.  Nonetheless, the exact format
 is not described here.  This is because the format is currently very
-Massif-specific.  We plan to make the format more general, and thus suitable
-for possible use with other tools.  Once this has been done, the format will
-be documented here.</para>
+Massif-specific.  In the future we hope to make the format more general, and
+thus suitable for possible use with other tools.  Once this has been done,
+the format will be documented here.</para>
 
 </sect1>
 

massif/ms_main.c

@@ -49,7 +49,7 @@
 //   identified?  [hmm, could make getting the name of alloc-fns more
 //   difficult] [could dump full names to file, truncate in ms_print]
 // - make --show-below-main=no work
-// - Options like --alloc-fn='operator new(unsigned, std::nothrow_t const&)'
+// - Options like --alloc-fn='operator new(unsigned, std::nothrow_t const&)'
 //   don't work in a .valgrindrc file or in $VALGRIND_OPTS. 
 //   m_commandline.c:add_args_from_string() needs to respect single quotes.
 // - With --stack=yes, want to add a stack trace for detailed snapshots so
@@ -446,7 +446,7 @@ static void ms_print_usage(void)
 {
    VG_(printf)(
 "    --heap=no|yes             profile heap blocks [yes]\n"
-"    --heap-admin=<number>     average admin bytes per heap block;\n"
+"    --heap-admin=<size>       average admin bytes per heap block;\n"
 "                               ignored if --heap=no [8]\n"
 "    --stacks=no|yes           profile stack(s) [no]\n"
 "    --depth=<number>          depth of contexts [30]\n"

massif/ms_print.in

@@ -66,10 +66,10 @@ usage: ms_print [options] <file>
 
   options for the user, with defaults in [ ], are:
     -h --help             show this message
-    -v --version          show version
+    --version             show version
     --threshold=<n.n>     significance threshold, in percent [$threshold]
-    --x=<n>               graph width, in columns; min=4, max=1000 [72]
-    --y=<n>               graph height, in rows;   min=4, max=1000 [20]
+    --x=<4..1000>         graph width, in columns [72]
+    --y=<4..1000>         graph height, in rows [20]
 
   ms_print is Copyright (C) 2007-2007 Nicholas Nethercote.
   and licensed under the GNU General Public License, version 2.
@@ -107,7 +107,7 @@ sub process_cmd_line()
         if ($arg =~ /^-/) {
 
             # --version
-            if ($arg =~ /^-v$|^--version$/) {
+            if ($arg =~ /^--version$/) {
                 die("ms_print-$version\n");
 
             # --threshold=X (tolerates a trailing '%')