Edit text sections on associative arrays. Also tweak example two space indent.

2 files changed, 84 insertions, 86 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
index 8fe46721..789bf607 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
@@ -263,7 +263,7 @@ delta = gettimeofday_s() - foo[tid()]
 <replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>] ++
 </screen>
 
-<para>Again, you can also use a handler function for your <command><replaceable>index_expression</replaceable></command>. For example, if you wanted to tally how many times a specific process performed a read to the virtual file system (using the event <command>kernel.function("vfs_read")</command>), you can use the following probe:</para>
+<para>Again, you can also use a handler function for your <command><replaceable>index_expression</replaceable></command>. For example, if you wanted to tally how many times a specific process performed a read to the virtual file system (using the event <command>vfs.read</command>), you can use the following probe:</para>
 
 <!-- next 3 indexterms for tallying virtual file system reads (VFS reads) -->
 
@@ -299,9 +299,9 @@ delta = gettimeofday_s() - foo[tid()]
 <example id="simplesimplevfsread">
 	<title>vfsreads.stp</title>
 <programlisting>
-probe kernel.function("vfs_read") 
+probe vfs.read
 {
-	reads[execname()] ++
+  reads[execname()] ++
 }
 </programlisting>
 </example>
@@ -430,12 +430,12 @@ probe kernel.function("vfs_read")
 global reads
 probe vfs.read
 { 
-	reads[execname()] ++
+  reads[execname()] ++
 }
 probe timer.s(3)
 {
-	foreach (count in reads)
-		printf("%s : %d \n", count, reads[count])
+  foreach (count in reads)
+    printf("%s : %d \n", count, reads[count])
 }
 </programlisting>
 </example>
@@ -500,8 +500,8 @@ probe timer.s(3)
 <screen>
 probe timer.s(3)
 {
-	foreach (count in reads- limit 10)
-		printf("%s : %d \n", count, reads[count])
+  foreach (count in reads- limit 10)
+    printf("%s : %d \n", count, reads[count])
 }
 </screen>
 
@@ -591,13 +591,13 @@ probe timer.s(3)
 global reads
 probe vfs.read
 { 
-	reads[execname()] ++
+  reads[execname()] ++
 }
 probe timer.s(3)
 {
-	foreach (count in reads)
-		printf("%s : %d \n", count, reads[count])
-	delete reads	
+  foreach (count in reads)
+    printf("%s : %d \n", count, reads[count])
+  delete reads	
 }
 </programlisting>
 </example>
@@ -608,20 +608,20 @@ probe timer.s(3)
 global reads
 probe vfs.read
 {
-	reads[execname()] ++
-
+  reads[execname()] ++
 }
-probe timer.s(2)
+
+probe timer.s(3)
 {
-	printf("=======\n")
-	foreach (count in reads+) 
-		printf("%s : %d \n", count, reads[count])
-	delete reads
+  printf("=======\n")
+  foreach (count in reads+) 
+    printf("%s : %d \n", count, reads[count])
+  delete reads
 }
 </programlisting>
 </example>-->
 
-<para>In <xref linkend="simplevfsreadprintnotcumulative"/>, the second probe prints the number of VFS reads each process made <emphasis>within the probed 2-second period only</emphasis>. The <command>delete reads</command> statement clears the <command>reads</command> array within the probe.</para>
+<para>In <xref linkend="simplevfsreadprintnotcumulative"/>, the second probe prints the number of VFS reads each process made <emphasis>within the probed 3-second period only</emphasis>. The <command>delete reads</command> statement clears the <command>reads</command> array within the probe.</para>
 
 <note>
 	<title>Note</title>
@@ -651,34 +651,34 @@ probe timer.s(2)
 <secondary>clearing arrays/array elements</secondary>
 <tertiary>array operations</tertiary>
 </indexterm>	
-	<para>You can have multiple array operations within the same probe. Using the examples from <xref linkend="arrayops-foreach"/> and <xref linkend="arrayops-deleting"/> , you can track the number of VFS reads each process makes per 2-second period <emphasis>and</emphasis> tally the cumulative VFS reads of those same processes. Consider the following example:</para>
+	<para>You can have multiple array operations within the same probe. Using the examples from <xref linkend="arrayops-foreach"/> and <xref linkend="arrayops-deleting"/> , you can track the number of VFS reads each process makes per 3-second period <emphasis>and</emphasis> tally the cumulative VFS reads of those same processes. Consider the following example:</para>
 	
 <screen>
 global reads, totalreads
 
-probe kernel.function("vfs_read")
+probe vfs.read
 {
-	reads[execname()] ++
-	totalreads[execname()] ++
+  reads[execname()] ++
+  totalreads[execname()] ++
 }
 
-probe timer.s(2)
+probe timer.s(3)
 {
-	printf("=======\n")
-	foreach (count in reads+) 
-		printf("%s : %d \n", count, reads[count])
-	delete reads
-
+  printf("=======\n")
+  foreach (count in reads+) 
+    printf("%s : %d \n", count, reads[count])
+  delete reads
 }
+
 probe end
 {
-	printf("TOTALS\n")
-	foreach (total in totalreads+)
-		printf("%s : %d \n", total, totalreads[total])
+  printf("TOTALS\n")
+  foreach (total in totalreads+)
+    printf("%s : %d \n", total, totalreads[total])
 }
 </screen>
 
-<para>In this example, the arrays <command>reads</command> and <command>totalreads</command> track the same information, and are printed out in a similar fashion. The only difference here is that <command>reads</command> is cleared every 2-second period, whereas <command>totalreads</command> keeps growing.</para> 
+<para>In this example, the arrays <command>reads</command> and <command>totalreads</command> track the same information, and are printed out in a similar fashion. The only difference here is that <command>reads</command> is cleared every 3-second period, whereas <command>totalreads</command> keeps growing.</para> 
 </note>
 </section>	
 <section id="arrayops-conditionals">
@@ -711,39 +711,38 @@ probe end
 global reads
 probe vfs.read
 {
-    reads[execname()] ++
+  reads[execname()] ++
 }
 
-probe timer.s(2)
+probe timer.s(3)
 {
-    printf("=======\n")
-    foreach (count in reads-)
-        if (reads[count] >= 1024)
-            printf("%s : %dkB \n", count, reads[count]/1024)
-        else
-            printf("%s : %dB \n", count, reads[count])
+  printf("=======\n")
+  foreach (count in reads-)
+    if (reads[count] >= 1024)
+      printf("%s : %dkB \n", count, reads[count]/1024)
+    else
+      printf("%s : %dB \n", count, reads[count])
 }
 </programlisting>
 </example>	
 
-<para>Every two seconds, <xref linkend="simplevfsreadprintif"/> prints out a list of all processes, along with how many times each process performed a VFS read. If the associated value of a process name is equal or greater than 1024, the <command>if</command> statement in the script converts and prints it out in <command>kB</command>.</para>  
+<para>Every three seconds, <xref linkend="simplevfsreadprintif"/> prints out a list of all processes, along with how many times each process performed a VFS read. If the associated value of a process name is equal or greater than 1024, the <command>if</command> statement in the script converts and prints it out in <command>kB</command>.</para>  
 <!--	<title>vfsreads-stop-on-stapio.stp</title>
 <programlisting>
 global reads
 probe kernel.function("vfs_read")
 {
-	reads[execname()] ++
+  reads[execname()] ++
 }
 
-probe timer.s(2)
+probe timer.s(3)
 {
-	printf("=======\n")
-	foreach (count in reads+) 
-		printf("%s : %d \n", count, reads[count])
-	if(reads["stapio"] >= 20)
-	{
-		exit()
-	}
+  printf("=======\n")
+  foreach (count in reads+) 
+    printf("%s : %d \n", count, reads[count])
+  if(reads["stapio"] >= 20) {
+    exit()
+  }
 }
 </programlisting>
 </example>
@@ -789,7 +788,7 @@ probe timer.s(2)
 </formalpara>
 
 <screen>
-if([<replaceable>index_expression</replaceable>] in <replaceable>array_name</replaceable>
+if([<replaceable>index_expression</replaceable>] in <replaceable>array_name</replaceable>)
 </screen>
 
 <para>To illustrate this, consider the following example:</para>
@@ -801,19 +800,18 @@ global reads
 
 probe vfs.read
 {
-	reads[execname()] ++
+  reads[execname()] ++
 }
 
-probe timer.s(2)
+probe timer.s(3)
 {
-	printf("=======\n")
-	foreach (count in reads+) 
-		printf("%s : %d \n", count, reads[count])
-	if(["stapio"] in reads)
-	{
-		printf("stapio read detected, exiting\n")
-		exit()
-	}
+  printf("=======\n")
+  foreach (count in reads+) 
+    printf("%s : %d \n", count, reads[count])
+  if(["stapio"] in reads) {
+    printf("stapio read detected, exiting\n")
+    exit()
+  }
 }
 </programlisting>		
 </example>
@@ -882,7 +880,7 @@ probe timer.s(2)
 global reads	
 probe vfs.read
 {
-reads[execname()] &lt;&lt;&lt; count
+  reads[execname()] &lt;&lt;&lt; count
 }
 </programlisting>
 </example>
@@ -1158,16 +1156,16 @@ reads[execname()] &lt;&lt;&lt; count
 <example id="multiplearrayindices">
 	<title>Multiple Array Indexes</title>
 <programlisting>
-global reads

-probe vfs.read

-{

-reads[execname(),pid()] &lt;&lt;&lt; 1

-}

-probe timer.s(3)

-{

-foreach([var1,var2] in reads)

-	printf("%s (%d) : %d \n", var1, var2, @count(reads[var1,var2]))

-}	
+global reads
+probe vfs.read
+{
+  reads[execname(),pid()] &lt;&lt;&lt; 1
+}
+probe timer.s(3)
+{
+  foreach([var1,var2] in reads)

+    printf("%s (%d) : %d \n", var1, var2, @count(reads[var1,var2]))
+}
 </programlisting>
 </example>
 
@@ -1188,4 +1186,4 @@ foreach([var1,var2] in reads)
 
 </section>
 
-</section>
\ No newline at end of file
+</section>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml
index 04e34de3..63c3df04 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml
@@ -14,7 +14,7 @@
 <secondary>introduction</secondary>
 </indexterm>	
 
-<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it.</para>
+<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a collection of values. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it.</para>
 
 <!--<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it. Illustrating this visually would be similar to creating a two-column table: the first column would have the unique key, while the second column would have each key's associated value. Each unique key and its associated value is referred to as a <emphasis>key pair</emphasis>.</para>-->
 
@@ -98,7 +98,7 @@
 <tertiary>arrays</tertiary>
 </indexterm>
 
-<para>Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they are declared as <command>global</command> variables in the SystemTap script. The syntax for manipulating arrays (i.e. accessing elements in an associative array) is similar to that of <command>awk</command>, and is as follows:</para>
+<para>Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they are declared as <command>global</command> variables in the SystemTap script. The syntax for accessing an element in an associative array is similar to that of <command>awk</command>, and is as follows:</para>
 <!-- next 3 indexterms for syntax -->
 <indexterm>
 <primary>arrays</primary>
@@ -126,10 +126,10 @@
 
 
 <screen>
-<replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>] <replaceable>operation</replaceable>
+<replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>]
 </screen>
 
-<para>Here, the <command><replaceable>array_name</replaceable></command> is any arbitrary name the array uses. The <command><replaceable>index_expression</replaceable></command> is used to refer to a specific unique key (or set of unique keys) in the array, and the <command><replaceable>operation</replaceable></command> defines what to do with the <command><replaceable>index_expression</replaceable></command>. To illustrate, let us try to build an array named <command>foo</command> that specifies the ages of three people (i.e. the unique keys): <command>tom</command>, <command>dick</command>, and <command>harry</command>. To assign them the ages (i.e. associated values) of 23, 24, and 25 respectively, we'd use the following array statements:</para> 
+<para>Here, the <command><replaceable>array_name</replaceable></command> is any arbitrary name the array uses. The <command><replaceable>index_expression</replaceable></command> is used to refer to a specific unique key in the array. To illustrate, let us try to build an array named <command>foo</command> that specifies the ages of three people (i.e. the unique keys): <command>tom</command>, <command>dick</command>, and <command>harry</command>. To assign them the ages (i.e. associated values) of 23, 24, and 25 respectively, we'd use the following array statements:</para> 
 
 <!-- next 2 indexterms for example -->
 
@@ -158,13 +158,13 @@ foo["dick"] = 24
 foo["harry"] = 25
 </screen>
 </example>
-<!--
-<para>You can specify up to 5 index expressons in an array statement, each one delimited by a comma (<command>,</command>). This is useful if you wish to perform the same operation to a set of key pairs. For example, to increase the associated value of all the key pairs defined by <xref linkend="arraysimplestexample"/>, you can use the following statement:</para>
+
+<para>You can specify up to 5 index expressons in an array statement, each one delimited by a comma (<command>,</command>). This is useful if you wish to have a key that contains multiple pieces of information. The following line from <xref linkend="scriptdisktop"/> uses 5 elements for the key: process ID, executable name, user ID, parent ID, and string "W". It associates the value of <command>devname</command> with that key.</para>
 
 <screen>
-foo["tom","dick","harry"] ++
+device[pid(),execname(),uid(),ppid(),"W"] = devname
 </screen>
--->
+
 <important>
 	<title>Important</title>
 	<para>All associate arrays must be declared as <command>global</command>, regardless of whether the associate array is used in one or multiple probes. </para>
@@ -220,13 +220,13 @@ probe begin {	foo[4,"hello"] ++ }
 
 <para>You can also use a handler function in as the <command><replaceable>unique_key</replaceable></command>. Doing so creates an associate array that uses the values returned by the handler function as the unique keys. The first time that a probe using this array returns a string value, that value is set as a unique key with an initial value of 0. The next time that the probe returns the same string value, it increments the associated value of the unique key by 1.</para>
 
-<para>For example, let's say you need to tally how many times each process performs a read to the virtual file system (VFS). To do this, probe the kernel function <command>vfs_read</command>, use the handler <command>execname()</command> to identify which processes performed the VFS read, and tally the reads of each process using the associative array named <command>reads</command>, as in</para>
+<para>For example, let's say you need to tally how many times each process performs a read to the virtual file system (VFS). To do this, probe the VFS read opeartion, use the handler <command>execname()</command> to identify which processes performed the VFS read, and tally the reads of each process using the associative array named <command>reads</command>, as in</para>
 
 <formalpara id="aaexamplesimplevfsreads">
 	<title>tallying-in-arrays.stp</title>
 <para>
 <programlisting>
-probe kernel.function("vfs_read")
+probe vfs.read
 { reads[execname()] += $count }
 </programlisting>
 </para>
@@ -234,4 +234,4 @@ probe kernel.function("vfs_read")
 
 <para>In <xref linkend="aaexamplesimplevfsreads"/>, the first time that the probe returns the process name <command>gnome-terminal</command> (i.e. the first time <command>gnome-terminal</command> performs a VFS read), that process name is set as a unique key. The next time that the probe returns the process name <command>gnome-terminal</command>, SystemTap increments the associated value of <command>gnome-terminal</command> by 1. SystemTap performs this operation for <emphasis>all</emphasis> process names as the probe returns them.</para>
 -->
-</section>
\ No newline at end of file
+</section>