Incorporated Keith's latest feedback, switched XXX to @todo...

--HG--
branch : mjc
rename : docs/src/overview.dox => docs/src/introduction.dox
rename : include/wiredtiger.h => include/wiredtiger_ext.h

docs/src/basic-api.dox

@@ -1,62 +1,81 @@
 /* vim: set filetype=c.doxygen : */
 
-/*! \page basic_api Getting Started with the API
+/*! @page basic_api Getting Started with the API
 
-\dontinclude ex_access.c
+WiredTiger applications will generally use the following classes to access and manage data:
 
-All applications that use WiredTiger will be structured roughly as follows.  The code below is taken from the complete example program \ex_ref{ex_access.c}.
+ - a WT_CONNECTION represents a connection to a database.  Most applications
+ will only open one connection to a database for each process.  The first
+ process to open a connection to a database will access the database in its
+ own address space.  Subsequent connections (if allowed) will communicate
+ with the first process over a socket connection to perform their
+ operations.
 
-\section basic_connection Connecting to a database
+ - a WT_SESSION represents a context in which database operations are
+ performed.  Sessions are opened on a specified connection, and applications
+ must open a single session for each thread accessing the database.
+
+ - a WT_CURSOR represents a cursor over a collection of data.  Cursors are
+ opened in the context of a session (which may have an associated
+ transaction), and can query and update records.  In the common case, a
+ cursor is used to access records in a table.  However, cursors can be used
+ on subsets of tables (such as a single column or a projection of multiple
+ columns), as an interface to statistics, configuration data or
+ application-specific data sources.
+
+Handles and operations are configured using strings, which keeps the set of methods in the API relatively small and makes the interface very similar regardless of the programming language used in the application.  WiredTiger supports the C, C++, Java and Python programming languages (among others).
+
+@dontinclude ex_access.c
+
+All applications that use WiredTiger will be structured roughly as follows.  The code below is taken from the complete example program @ex_ref{ex_access.c}.
+
+@section basic_connection Connecting to a database
 
 To access a database, first open a connection with the following code:
-\skip main
-\until wiredtiger_open
+@skip main
+@until Note
 
-Here the configuration string \c "create" is passed to ::wiredtiger_open to indicate that the database should be created if it does not exist when the program starts running.
+Here the configuration string @c "create" is passed to ::wiredtiger_open to indicate that the database should be created if it does not already exist.
 
-\section basic_session Opening a Session
+Next we open a session handle for the single thread accessing the database.
 
-Next we open a session handle for the single thread accessing the database:
+The code block above also shows simple error handling with wiredtiger_strerror (a function that returns a string describing an error code passed as its argument).  More complex error handling can be configured by passing an implementation of WT_ERROR_HANDLER to wiredtiger_open or WT_CONNECTION::open_session.
 
-\until Note
-
-The code block above also shows simple error handling with ::wiredtiger_strerror.  The default behavior for more detailed errors is to write them to \c stderr.  That can be overridden by passing an implementation of WT_ERROR_HANDLER to ::wiredtiger_open or WT_CONNECTION::open_session.
-
-\section basic_create_table Creating a Table
+@section basic_create_table Creating a Table
 
 If the database was created by the ::wiredtiger_open call above, it will be empty.  We now create a table that we can use to store data:
 
-\until ;
+@until ;
 
-This call creates a table called \c "access", configured to use strings for its key and value columns.  We go into more details about what is possible later in the section on \ref schema.
+This call creates a table called @c "access", configured to use strings for its key and value columns.  We go into more details about what is possible later in the section on @ref schema.
 
-\section basic_cursors Accessing Data With Cursors
+@section basic_cursors Accessing Data With Cursors
 
 Now that we're sure we have a table, we open a cursor to perform some operations on it:
 
-\until insert
+@until insert
 
-Here, the string \c "table:access" specifies that we are opening the cursor on the table named \c "access" that we created above.
+Here, the string @c "table:access" specifies that we are opening the cursor on the table named @c "access" that we created above.
 
-The WT_CURSOR::set_key and WT_CURSOR::set_value calls marshal the application's data into the cursor.  The WT_CURSOR::insert call then creates a record containing that data and inserts it into the table.
+The WT_CURSOR::set_key and WT_CURSOR::set_value calls put the application's data into the cursor.  The WT_CURSOR::insert call creates a record containing that data and inserts it into the table.
 
 Now we iterate through all of the records in the table, printing them out as we go:
 
-\until }
+@until }
 
 Note that the key and value parts of the records are returned as C strings because the table was created that way (even if it was created by a previous run of the example).  No extracting or converting of needs to be done in the application.
 
-If we weren't using the cursor for the call to WT_CURSOR::insert above, this loop would simplify to:
+Because the cursor was positioned in the table after the WT_CURSOR::insert call, we had to re-position it using the WT_CURSOR::first call; if we weren't using the cursor for the call to WT_CURSOR::insert above, this loop would simplify to:
 
-\code
+@code
 	while ((ret = cursor->next(cursor)) == 0) {
 		...
 	}
-\endcode
+@endcode
 
-\section basic_close Closing Handles
+@section basic_close Closing Handles
 
 Lastly, we close the connection, which implicitly closes the cursor and session handles:
 
-\skipline close
+@skipline close
  */