Improve documentation.

Better xternal sorting example.
Improved compilation and installation instructions.
Tweaks to the intro.
Misc tweaks and links inserted.

doc/Doxyfile.in

@@ -447,7 +447,7 @@ INPUT += @tpie_SOURCE_DIR@/doc/index.dox
 
 # Getting started
 INPUT += @tpie_SOURCE_DIR@/doc/basicconcepts.dox
-INPUT += @tpie_SOURCE_DIR@/doc/install.dox
+INPUT += @tpie_SOURCE_DIR@/doc/setup.dox
 INPUT += @tpie_SOURCE_DIR@/doc/repository.dox
 INPUT += @tpie_SOURCE_DIR@/doc/files.dox
 

doc/code/code.cpp

@@ -60,10 +60,8 @@ void progress() {
 }
 
 namespace _h {
-void sort() {
 #include "sorting_external.inl"
 }
-}
 
 namespace _i {
 #include "sorting_internal.inl"

doc/code/sorting_external.inl

@@ -1,3 +1,22 @@
-tpie::file_stream<int> mystream;
-mystream.open("data.tpie");
-tpie::sort(mystream, mystream);
+#include <tpie/tpie.h> // for tpie::tpie_init
+#include <tpie/sort.h> // for tpie::sort
+
+int main() {
+	tpie::tpie_init();
+
+	//create a stream with 1000 ints
+	tpie::file_stream<int> mystream;
+
+	for (int i = 0; i < 1000; ++i) {
+	    mystream.write(i);
+	}
+
+	//sort the stream using the "<" operator
+	tpie::sort(mystream,mystream);
+
+	tpie::tpie_finish();
+
+	return 0;
+}
+
+

doc/index.dox

@@ -8,11 +8,14 @@ algorithm and data structures on very large sets of data. The
 algorithms and data structures that form the core of TPIE all provide
 efficient worst-case space, time and disk usage guarantees.
 
+TPIE works great on both Windows and Linux systems and have been
+used successfully in several commercial products.
+
 \subsection sec_help Getting started
 
 This documentation contain a few sections that help you start out with tpie:
 
-  - \ref install
+  - \ref setup
   - \ref basicconcepts of I/O algorithms
   - \ref repository
   - \ref files
@@ -26,17 +29,22 @@ href="http://madalgo.au.dk/tpie">tpie homepage</a>.
 
 \subsection sec_usage Usage
 
+Before diving into the reference part of this documentation, you may
+find the following introductionary examples helpful. If you need help
+setting up a makefile for compiling these test programs, checkout the
+file \c example/CMakeLists.txt in the reposityr.
+
   - \ref file_stream
-  - \ref sorting_internal (contains complete example)
+  - \ref sorting_internal 
   - \ref sorting_external
-  - \ref priority_queue (contains complete example)
-  - \ref memory
-  - \ref progress
-  - \ref fractiondb
+  - \ref priority_queue 
+  - \ref memory (example snippets)
+  - \ref progress (example snippets)
+  - \ref fractiondb (example snippets)
 
 \subsection sec_history History
 
-Originally, TPIE was known as the Transparent Parallel I/O
+TPIE was orginally known as the Transparent Parallel I/O
 Environment, it was started by researchers from the <a
 href="http://www.cs.duke.edu">Computer Science Department</a> at <a
 href="http://www.duke.edu/">Duke University</a> in 1994. TPIE is

doc/repository.dox

@@ -13,6 +13,7 @@ The \c cpp0xtest/ directory contains code that might not compile on all modern
 compilers. CMake uses this to determine if the system compiler supports
 variadic templates and rvalues.
 
-The \c example/ directory contains a simple example of how to use TPIE in your
-application.
+The \c example/ directory contains a simple example of how to use TPIE
+in your application, this includes a small CMakeLists.txt example.
+
 */

doc/setup.dox

@@ -0,0 +1,88 @@
+/**
+\page setup Compiling and installing TPIE
+
+
+You will need <a href="http://git-scm.org">Git</a>, <a
+href="http://cmake.org">CMake</a>, <a
+href="http://boost.org">Boost</a> and a C++ compiler in order to use
+TPIE on any system. Once these dependencies have been installed, you
+should be able to use the steps in this section to compile and install
+TPIE.
+
+\section sec_setup_linux Linux/MacOS
+
+First, clone the <a href="https://github.com/thomasmoelhave/tpie">git repository</a> and
+checkout the branch or tag you wish to compile:
+
+\verbatim
+git clone git://github.com/thomasmoelhave/tpie.git
+cd tpie
+git checkout master
+\endverbatim
+
+Now, create a build directory and run CMake followed by make:
+
+\verbatim
+mkdir build
+cd build
+cmake -D CMAKE_BUILD_TYPE:STRING=Release ..
+make
+\endverbatim
+
+This will generate the static library \c libtpie.a in the \c build/tpie folder.
+The unit test executables are placed in the \c test/unit folder and are prefixed
+with the token \c ut-.
+To run the unit tests, use <a href="http://www.cmake.org/cmake/help/ctest-2-8-docs.html">CTest</a>:
+
+\verbatim
+ctest
+\endverbatim
+
+\subsection sec_setup_install Installation
+
+TPIE can be used right from the build directory, or installed into a separate directory. The two most popular ways of doing this are:
+
+\subsubsection sec_setup_install_direct Direct Installation
+
+You can install tpie in \c /usr/local/ by simply invoking:
+
+\verbatim
+make install
+\endverbatim
+
+Change the \c CMAKE_INSTALL_PREFIX CMake variable to change the prefix
+directory.
+
+\subsubsection sec_setup_install_cpack CPack Installation
+
+You can use <a href="http://www.cmake.org/cmake/help/cpack-2-8-docs.html">CPack</a> to build various binary packages that can be used to
+install TPIE on your computer, or on other computers:
+
+\verbatim
+cpack
+# On .deb-based Linux distros:
+sudo dpkg -i tpie-1.0.0-Linux.deb
+# On other Linux distros:
+cd /usr/local
+sudo tar xvf path/to/tpie/build/tpie-1.0.0-Linux.tar.gz
+\endverbatim
+
+To link your application with TPIE, may manually specify the linker flags
+<tt>-ltpie -lboost_system -lboost_filesystem -lboost_date_time
+-lboost_thread</tt>, or you may use the example \c CMakeLists.txt from the
+\c tpie/example/ directory to find the TPIE installation using CMake.
+
+\section sec_setupwin Windows
+
+Clone the <a href="https://github.com/thomasmoelhave/tpie">git
+repository</a> at <tt>git://github.com/thomasmoelhave/tpie.git</tt>,
+perhaps using <a
+href="http://code.google.com/p/tortoisegit/">TortoiseGit</a> or <a
+href="http://code.google.com/p/gitextensions/">Git Extensions</a>, and
+set up the build environment using CMake, perhaps using the CMake
+GUI. TPIE is known to work with the Microsoft Visual Studio 2008 and
+2010 compilers. Be sure to select a 64-bit build when your platform
+supports it.
+
+
+ */

doc/sorting_external.dox.in

@@ -1,22 +1,30 @@
 /**
 \page sorting_external External sorting
 
-External memory sorting is implemented in \ref sort.h. The current interface is
-defined in the \c tpie namespace, but legacy definitions exist in the
-\c tpie::ami namespace.
+The recommended way to sort large data set (which will typically be
+stored in a \ref tpie::file_stream in TPIE) is to use one of the \ref
+tpie::sort functions defined in \ref sort.h.
 
-Currently, the sorting algorithm relies on data existing in a TPIE stream on
-disk. Once this is the case, and you have opened a file_stream for reading and
-writing to this file, sorting using the less-than operator with no progress
-reporting is a simple as calling \ref tpie::sort (mystream, mystream). This
-kind of in-stream sorting requires enough external memory space for a temporary
-stream of the same size as the input.
+When you have a \ref tpie::file_stream over some type \c T (opened for
+reading and writing), you can order the elements of this stream
+according to the order defined by the \c < operator (i.e. using \c
+T::operator< or \c operator<(T,T) ) simply invoke \ref tpie::sort
+(mystream, mystream). When the input and output stream is the same,
+the temporary space usage of \ref tpie::sort is the same as the space
+used by the input stream.
 
-If you wish to store the result in a new stream, the function call is
-\ref tpie::sort (instream, outstream); this requires three times the space
-occupied by instream in total.
+If you wish to store the result in a stream different from the input
+stream, supply this stream as the second argument to \r tpie::sort,
+this requires extra space equivalent to twice the space used by the
+input stream.
 
 \code
 @DOCCODE_SORTING_EXTERNAL@
 \endcode
+
+The current interface is
+defined in the \c tpie namespace, but legacy definitions exist in the
+\c tpie::ami namespace.
+
+
 */