update usage pdf

3 files changed, 50 insertions, 135 deletions

diff --git a/doc/a_simple_example.c b/doc/a_simple_example.c
index fb7d774..2153a70 100644
--- a/doc/a_simple_example.c
+++ b/doc/a_simple_example.c
@@ -1,52 +1,45 @@
+/* keep this include at the very top of the file */
 #include "simple-test.h"
+
+/* any global variables, functions, other inclusions, etc.
+ * should be declared here */
 #include "header_with_stuff_to_be_tested.h"
 
 BEGIN_TEST
 
-/* a simple test using only stack mem */
-TEST("description of the first test")
+/* the string is a description of the test being run */
+TEST("check add()'s return value")
 {
-  int var1=2;
-  int var2=4;
-  
-  /* add is a function included from our hypothetical
-   * header_with_stuff_to_be_tested */
-  EXPECT_INT("error message shown on failing",
-		  var1+var2, add(var1, var2));
+	int var1=2;
+	int var2=4;
+
+	/* add is a function included from our hypothetical
+	 * header_with_stuff_to_be_tested */
+	EXPECT_INT(var1+var2, add(var1, var2));
 }
 
-/* this test uses heap memory, so things get a bit
- * more complicated */
-TEST("this is the second test")
+TEST("compare two arrays of strings")
 {
-  /* first, ensure all your pointers which will
-   * point to heap mem are declared */
-  char *heap_string=NULL;
-  
-  /* next, declare a list of statements to be
-   * called to clean up memory once the test
-   * is completed */
-  CLEANUP(
-      if(heap_string != NULL)
-        free(heap_string);
-        );
-        
-  /* then, define the body of the test */
-  
-  /* STATE can be used to report (with pretty
-   * formatting) the current state within the
-   * test, which may be useful in the case of
-   * a segfault */
-  STATE("grabbing heap string");
-  
-  heap_string=get_heap_string_value();
-  
-  EXPECT_STR("i suck at grabbing pointers!",
-		  "expected value", heap_string);
-  
-  /* finally, call RETURN(); to run the
-   * cleanup code and continue */
-  RETURN();
+	int i;
+	char array1[][10] = {
+		"str1",
+		"str2",
+		"str3",
+	};
+	char array2[][10] = {
+		"str1",
+		"str2",
+		/* matching will fail here */
+		"different",
+	};
+
+	for(i = 0; i < sizeof(array1) / sizeof(char[10]); i++) {
+		/* ECHO can be used to print (with pretty
+		 * formatting) the current state within the
+		 * test */
+		ECHO("checking strs at i == %i", i);
+		EXPECT_STR_EQ(array1[i], array2[i]);
+	}
 }
 
 END_TEST
diff --git a/doc/usage.pdf b/doc/usage.pdf
index fb6f9c7..0ffcd3c 100644
--- a/doc/usage.pdf
+++ b/doc/usage.pdf
diff --git a/doc/usage.tex b/doc/usage.tex
index 6494ee5..f8cde5d 100644
--- a/doc/usage.tex
+++ b/doc/usage.tex
@@ -8,13 +8,7 @@
 \usepackage[usenames,x11names,table]{xcolor}
 
 \usepackage{listings}
-\usepackage{enumitem}
-\usepackage{graphicx}
 \usepackage{framed}
-\usepackage{calc}
-\usepackage{ifthenx}
-\usepackage{tabularx}
-\usepackage{soul}
 
 %%% -------------------------------------------------------
 %%% universal formatting
@@ -50,18 +44,6 @@
 	}
 }
 
-\newcommand{\myhl}[1]{
-	{
-		\color{Snow1}
-		\sethlcolor{Red1}
-		\hl{#1}
-	}
-}
-
-\newcommand{\mymacrow}[2]{
-	\footnotesize\textcolor{DarkOrchid3}{\textbf{#1}}: & \small #2 \\[8pt]
-}
-
 \newcommand{\mytermrow}[2]{
 	\tt\bf\small #1 & \tt\small #2 \\
 }
@@ -102,16 +84,15 @@
 	\hrule
 	\pagebreak
 
-	If both tests above succeed, the output will look like this:\\
+	If the second test was ommited, the ouput would look like this:\\
 
 	\hrule
 	\vspace{8pt}
 
 	% successful output
+	{\tt\bf\small a\_simple\_example.c}\\
 	\begin{tabular*}{\textwidth}{r@{\ \tt\bf :: }l}
-		\mytermrow{1}{\color{Yellow4}description of the first test}
-		\mytermrow{2}{\color{Yellow4}this is the second test}
-		\mytermrow{ }{\color{DodgerBlue2}grabbing heap string...}
+		\mytermrow{1}{\color{Yellow4}check add()'s return value}
 		\mytermrow{ }{\color{SpringGreen4}success!}
 	\end{tabular*}
 
@@ -119,89 +100,30 @@
 	\hrule
 	\vspace{20pt}
 
-	If the first test fails, it will look something like this:\\
+	If the second test was included, it would look like this:\\
+
 	\hrule
 	\vspace{8pt}
 
 	% failed output
+	{\tt\bf\small a\_simple\_example.c}\\
 	\begin{tabular*}{\textwidth}{r@{\ \tt\bf :: }l}
-		\mytermrow{1}{\color{Yellow4}description of the first test}
-		\mytermrow{ }{\color{Red1}FAIL: error message shown on failing}
-		\mytermrow{ }{\textcolor{SpringGreen4}{\textbf{\ \ expected:}}6}
-		\mytermrow{ }{\textcolor{Red1}{\textbf{\ \ \ \ actual:}}0}
+		\mytermrow{1}{\color{Yellow4}check add()'s return value}
+		\mytermrow{2}{\color{Yellow4}compare two arrays of strings}
+		\mytermrow{ }{\color{DodgerBlue2}checking strs at i == 0...}
+		\mytermrow{ }{\color{DodgerBlue2}checking strs at i == 1...}
+		\mytermrow{ }{\color{DodgerBlue2}checking strs at i == 2...}
+		\mytermrow{ }{\textbf{a\_simple\_example.c:40: \textcolor{Red1}{fail:}} strings unequal}
+		\mytermrow{ }{\ \ \textbf{array1[i]} == `str3'}
+		\mytermrow{ }{\ \ \textbf{array2[i]} == `different'}
 	\end{tabular*}
 	
 	\vspace{8pt}
 	\hrule
+	\vspace{20pt}
 
-	\pagebreak
-
-	\myheading{defined macros}
-	\begin{tabularx}{\textwidth}{r@{\ }X}
-		\mymacrow{BEGIN\_TEST}{
-			must appear before all tests and 
-			after all global variable declarations
-		}
-		\mymacrow{END\_TEST}{
-			must appear at the end of your test
-			program
-		}
-		\mymacrow{CLEANUP(statements)}{
-			this defines a list of statements to run
-			when the test exits, either successfully or
-			on a failure. it isn't necessary for a test
-			to run, but, if it does appear, it must be
-			after the declaration of all variables to
-			which it makes reference.
-		}
-		\mymacrow{RETURN()}{
-			place at the end of a test which uses
-			CLEANUP to ensure it is called before the
-			test exits. i couldn't find any way around
-			this without using more than just one
-			header file, so i hope it isn't too annoying.
-		}
-		\mymacrow{STATE(description)}{
-			show a prettily-formatted description of the
-			program's state during a test. takes printf-style
-			arguments.
-		}
-		\mymacrow{EXPECT\_ZERO(summary, arg)}{
-			fail if \texttt{arg} does not resolve to 0
-		}
-		\mymacrow{EXPECT\_ONE(summary, arg)}{
-			fail if \texttt{arg} does not resolve to 1
-		}
-		\mymacrow{EXPECT\_GREATER\_THAN\_ZERO(summary, arg)}{
-			fail if \texttt{arg} does not resolve to a value
-			greater than 0. this will be replaced with more
-			generic integer comparisons soon.
-		}
-		\mymacrow{EXPECT\_INT(summary, arg1, arg2)}{
-			fail if \texttt{arg2} does not match the
-			expected integer value \texttt{arg1}
-		}
-		\mymacrow{EXPECT\_EQUAL\_INT(summary, arg1, arg2)}{
-			fail if \texttt{arg1} and \texttt{arg2} are
-			not equal
-		}
-		\mymacrow{EXPECT\_UNEQUAL\_INT(summary, arg1, arg2)}{
-			fail if \texttt{arg1} and \texttt{arg2} are
-			equal
-		}
-		\mymacrow{EXPECT\_STR(summary, arg1, arg2)}{
-			fail if string \texttt{arg2} does not match the
-			expected string value \texttt{arg1}
-		}
-		\mymacrow{EXPECT\_EQUAL\_STR(summary, arg1, arg2)}{
-			fail if \texttt{arg1} and \texttt{arg2} are
-			not equivalent strings
-		}
-		\mymacrow{EXPECT\_UNEQUAL\_STR(summary, arg1, arg2)}{
-			fail if \texttt{arg1} and \texttt{arg2} are
-			equivalent strings
-		}
-	\end{tabularx}
+	For detailed descriptions of all available tests, see the included man page
+	or README.md .
 
 \end{document}