added Usage item

2 files changed, 75 insertions, 9 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
index e8f9c3cb..160597bf 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml
@@ -45,7 +45,7 @@ probe	<replaceable>[event]</replaceable>,
 	exit()
 }
 </programlisting>		
-	<para>The <replaceable>exit()</replaceable> condition is optional, but it is recommended since it safely terminates the session once the script successfully traps the required information.</para>	
+	<para>The <replaceable>exit()</replaceable> condition is optional; this condition safely terminates the session once the script successfully traps the required information the first time.</para>	
 	
 <important>
 	<title>Important</title>
@@ -68,7 +68,7 @@ probe	<replaceable>[event]</replaceable>,
 <varlistentry>
 	<term>kernel.function("<replaceable>[function]</replaceable>")</term>
 	<listitem>
-		<para>The entry to the kernel function <replaceable>function</replaceable>. For example, <command>kernel.function("sys_open")</command> refers to the "event" that the kernel function <command>sys_open</command> is used. To specify the <emphasis>return</emphasis> of the kernel function <command>sys_open</command>, append the <command>return</command> string to the event statement; i.e. <command>kernel.function("sys_open").return</command>.</para>
+		<para>The entry to the kernel function <replaceable>function</replaceable>. For example, <command>kernel.function("sys_open")</command> refers to the "event" that occurs when the kernel function <command>sys_open</command> is called by any thread in the system. To specify the <emphasis>return</emphasis> of the kernel function <command>sys_open</command>, append the <command>return</command> string to the event statement; i.e. <command>kernel.function("sys_open").return</command>.</para>
 		
 		<para>When defining functions, you can use asterisk (<command>*</command>) for wildcards. You can also trace the entry/exit of a function in a kernel source file. Consider the following example:</para>
 <example id="wildcards"><title>Wildcards and Kernel Source Files in an Event</title>
@@ -142,7 +142,7 @@ probe kernel.function("*@net/socket.c").return { }
 
 
 <varlistentry>
-	<term>timer.ms()</term>
+	<term>timer events</term>
 	<listitem>
 		<para>An event that specifies a handler to be executed "after X number of milliseconds". For example:</para>
 		
@@ -156,7 +156,23 @@ probe timer.ms(4000)
 </example>
 
 <para>
-	<xref linkend="timer"/> is an example of a probe that allows you to terminate the script after 4000 milliseconds (or 4 seconds). When used in conjunction with another probe that traps a large quantity of data, a probe using <command>timer.ms()</command> allows you to limit the information your script is collecting (and printing out).
+	<xref linkend="timer"/> is an example of a probe that allows you to terminate the script after 4000 milliseconds. Note that you can also use the following timer events:
+</para>
+	
+<itemizedlist>
+<listitem><para><command>timer.s(<replaceable>[seconds]</replaceable>)</command></para></listitem>
+
+<listitem><para><command>timer.us(<replaceable>[microseconds]</replaceable>)</command></para></listitem>
+
+<listitem><para><command>timer.ns(<replaceable>[nanoseconds]</replaceable>)</command></para></listitem>
+
+<listitem><para><command>timer.hz(<replaceable>[hertz]</replaceable>)</command></para></listitem>
+
+<listitem><para><command>timer.jiffies(<replaceable>[jiffies]</replaceable>)</command></para></listitem>
+
+</itemizedlist>
+<para>
+	When used in conjunction with another probe that traps a large quantity of data, timer events allow you to limit the information your script is collecting (and printing out).
 </para>	
 		
 	</listitem>	
@@ -215,11 +231,10 @@ probe begin
 <formalpara id="printf">
 	<title>printf ( ) Statements</title>
 <para>
-	The <command>printf ()</command> statement is one of the simplest handler tools for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format:
+	The <command>printf ()</command> statement is one of the simplest functions for printing data. <command>printf ()</command> can also be used to trap data using a wide variety of SystemTap handler functions using the following format:
 </para>
 
 </formalpara>
-<remark>is "handler tool" appropriate?</remark>
 
 
 <programlisting>
@@ -234,6 +249,11 @@ printf ("<replaceable>[format string]</replaceable>\n", <replaceable>[argument]<
 	You can use the variables <command>%s</command> (for strings) and <command>%d</command> (for numbers) in format strings, depending on your list of arguments. Format strings can have multiple variables, each matching a corresponding argument; multiple arguments are delimited by a comma (<command>,</command>) and space.
 </para>
 
+<note>
+	<title>Note</title>
+	<para>Semantically, the SystemTap <command>printf</command> function is very similar to its C language counterpart. The aforementioned syntax and format for SystemTap's <command>printf</command> function is identical to that of the C-style <command>printf</command>.</para>
+</note>	
+
 <para>
 	To illustrate this, consider the following probe example:
 </para>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
index da6d4d4c..38f8d018 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
@@ -108,14 +108,60 @@ uname -r
 	<section id="using-usage">
 		<title>Usage</title>
 		<remark>
-			basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter)
+			- basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter)
 		</remark>
 		
 		<remark>
-			running systemtap scripts
+			- running systemtap scripts
 		</remark>
+<!--		
+		<remark>- Tapsets: short intro on usage</remark>
+		-->
+		<para>
+			SystemTap scripts are run through the command <command>stap</command>. <command>stap</command> can run SystemTap scripts from standard input or from file. Below is a list of common options available to you: 
+		</para>
 		
-		<remark>Tapsets: short intro on usage</remark>
+<variablelist>
+
+<varlistentry>
+	<term>-v</term>
+	<listitem>
+		<para>Makes the output of the SystemTap session more verbose. You can repeat this option to (for example, <command>stap -vvv script.stp</command>); provide more details on the script's execution. This option is particularly useful if you encounter any errors in running the script.</para>
+		
+		<para>For more information about common SystemTap script errors, refer to <xref linkend="errors"/>.</para>
+	</listitem>	
+</varlistentry>	
+	
+<varlistentry>
+	<term>-I <replaceable>[directory]</replaceable></term>
+	<listitem>
+		<para>Check the script against additional tapsets found in  <command><replaceable>[directory]</replaceable></command>. This is useful if you have additional tapsets that are not included in <filename>/usr/share/systemtap/tapset/</filename>; for more information about tapsets, refer to <xref linkend="understanding-tapsets"/>.</para>
+	</listitem>	
+</varlistentry>	
+
+<varlistentry>
+	<term>-o <replaceable>[filename]</replaceable></term>
+	<listitem>
+		<para>Sends the standard output to file (<replaceable>[filename]</replaceable>).</para>
+	</listitem>	
+</varlistentry>	
+
+<!--	
+<varlistentry>
+	<term></term>
+	<listitem>
+		<para></para>
+	</listitem>	
+</varlistentry>	
+			-->
+</varlistentry>
+
+<remark>any other useful options worth noting here for beginners?</remark>
+
+<para>For more information about <command>stap</command>, refer to <command>man stap</command>.</para>
+
+<para>To run SystemTap instrumentation (i.e. the kernel module built from SystemTap scripts during a cross-instrumentation), use <command>staprun</command> instead. For more information about <command>staprun</command> and cross-instrumentation, refer to <xref linkend="cross-compiling"/>.</para>
+
 	</section>
 
 </chapter>