Rearranging main page and now use * as FILE_PATTERNS (for includes without extensions).

Author: bingmann

Doxyfile

@@ -688,7 +688,7 @@ INPUT_ENCODING         = UTF-8
 # *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py
 # *.f90 *.f *.for *.vhd *.vhdl
 
-FILE_PATTERNS          =
+FILE_PATTERNS          = *
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
 # should be searched for input files as well. Possible values are YES and NO.
@@ -716,7 +716,7 @@ EXCLUDE_SYMLINKS       = NO
 # against the file with absolute path, so to exclude all test directories
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = *.png *.pdf *.eps *.svg *.bib *.xml *.css
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

doc/common.dox

@@ -1,3 +1,4 @@
+// -*- mode: c++; mode: visual-line; mode: flyspell; fill-column: 100000 -*-
 /***************************************************************************
  *  doc/common.dox
  *
@@ -12,10 +13,7 @@
 
 /*! \page common Common Utilities and Helpers found in STXXL
 
-A lots of basic utility classes and helper functions have accumulated in
-STXXL. Try are usually fundamental enough to be also used in an application
-program.  Before implementing a common software utility, please check the list
-below; it might already exist in STXXL:
+A lots of basic utility classes and helper functions have accumulated in STXXL. Try are usually fundamental enough to be also used in an application program.  Before implementing a common software utility, please check the list below; it might already exist in STXXL:
 
 - \subpage common_random "random number generators"
 - \subpage common_timer "timestamp and timer function"
@@ -47,35 +45,25 @@ TODO-df
 
 /*! \page common_simple_vector A Non-growing, Non-initializing Simpler Vector
 
-For applications where a std::vector is overkill, or one wishes to allocate an
-uninitialied POD array, the stxxl::simple_vector is a good method.
+For applications where a std::vector is overkill, or one wishes to allocate an uninitialied POD array, the stxxl::simple_vector is a good method.
 
 */
 
 /*! \page common_counting_ptr Reference Counted (Shared) Objects
 
-Some objects in STXXL are reference counted. This is usually done for large
-objects, which should not be copied deeply in assignments. Instead, a reference
-counting pointer is used, which holds a handle while the pointer exists and
-deletes the object once all pointers go out of scope. Examples are matrices and
-sorted_runs.
+Some objects in STXXL are reference counted. This is usually done for large objects, which should not be copied deeply in assignments. Instead, a reference counting pointer is used, which holds a handle while the pointer exists and deletes the object once all pointers go out of scope. Examples are matrices and sorted_runs.
 
-The method used is called stxxl::counting_ptr or intrusive reference counting.
-This is similar, but not identical to boost or TR1's shared_ptr.
+The method used is called stxxl::counting_ptr or intrusive reference counting.  This is similar, but not identical to boost or TR1's shared_ptr.
 
-The stxxl::counting_ptr is accompanied by stxxl::counted_object, which contains
-the actual reference counter (a single integer). A reference counted object
-must derive from stxxl::counted_object:
+The stxxl::counting_ptr is accompanied by stxxl::counted_object, which contains the actual reference counter (a single integer). A reference counted object must derive from stxxl::counted_object:
 
 \code
 struct something : public stxxl::counted_object
 {
 };
 \endcode
 
-Code that now wishes to use pointers referencing this object, will typedef an
-stxxl::counting_ptr, which is used to increment and decrement the included
-reference counter automatically.
+Code that now wishes to use pointers referencing this object, will typedef an stxxl::counting_ptr, which is used to increment and decrement the included reference counter automatically.
 
 \code
 typedef stxxl::counting_ptr<something> something_ptr
@@ -91,25 +79,19 @@ typedef stxxl::counting_ptr<something> something_ptr
 }
 \endcode
 
-The stxxl::counting_ptr can generally be used like a usual pointer or
-shared_ptr (see the docs for more).
+The stxxl::counting_ptr can generally be used like a usual pointer or shared_ptr (see the docs for more).
 
-There is also stxxl::const_counting_ptr to return const objects (note that a
-const stxxl::counting_ptr will only render the pointer const, not the enclosed
-object).
+There is also stxxl::const_counting_ptr to return const objects (note that a const stxxl::counting_ptr will only render the pointer const, not the enclosed object).
 
 */
 
 /*! \page common_thread_sync Synchronization Primitives for Multi-Threading
 
-To support multi-threading, some parts of STXXL use synchronization primitives
-to ensure correct results. The primitives are based either on pthreads or on
-Boost classes.
+To support multi-threading, some parts of STXXL use synchronization primitives to ensure correct results. The primitives are based either on pthreads or on Boost classes.
 
 \section mutex Mutexes
 
-For simple mutual exclusion contexts, stxxl::mutex objects should be used
-together with scoped locks:
+For simple mutual exclusion contexts, stxxl::mutex objects should be used together with scoped locks:
 
 \code
 class Something
@@ -137,8 +119,7 @@ stxxl::onoff_switch is a two state semaphore thing?
 
 /*! \page common_logging Logging Macros STXXL_MSG
 
-All STXXL components should output log or trace messages using the following
-macros. There are two basic methods for logging using ostream syntax:
+All STXXL components should output log or trace messages using the following macros. There are two basic methods for logging using ostream syntax:
 
 \code
 // for plain messages
@@ -159,8 +140,7 @@ STXXL_VERBOSE2("text " << var)
 STXXL_VERBOSE3("text " << var)
 \endcode
 
-A method used by some submodule authors to create their own levels of verbosity
-is to make their own debugging macros:
+A method used by some submodule authors to create their own levels of verbosity is to make their own debugging macros:
 
 \code
 #define STXXL_VERBOSE_VECTOR(msg) STXXL_VERBOSE1("vector[" << static_cast<const void *>(this) << "]::" << msg)
@@ -170,8 +150,7 @@ is to make their own debugging macros:
 
 /*! \page common_assert Macros for Checking Assertions
 
-There are quite a bunch of macros for testing assertions. You must be careful
-to pick the right one depending on when and what you want to assert on.
+There are quite a bunch of macros for testing assertions. You must be careful to pick the right one depending on when and what you want to assert on.
 
 \section static Compile-time Assertions: STXXL_STATIC_ASSERT
 
@@ -184,10 +163,7 @@ STXXL_STATIC_ASSERT(sizeof(item) == 4 * sizeof(int));
 
 \section unittest Assertions in Unit Tests: STXXL_CHECK
 
-Assertions in unit tests must use the following macros to ensure that the
-condition is also checked in release builds (where a plain \c "assert()" is
-void). These \c CHECK function should NOT be used to test return values, since
-we try to throw exceptions instead of aborting the program.
+Assertions in unit tests must use the following macros to ensure that the condition is also checked in release builds (where a plain \c "assert()" is void). These \c CHECK function should NOT be used to test return values, since we try to throw exceptions instead of aborting the program.
 
 \code
 // test a condition
@@ -196,19 +172,13 @@ STXXL_CHECK( 2+2 == 4 );
 STXXL_CHECK2( 2+2 == 4, "We cannot count!");
 \endcode
 
-Sometimes one also wants to check that a specific expression \b throws an
-exception. This checking can be done automatically using a <tt>try { } catch
-{}</tt> by using STXXL_CHECK_THROW.
+Sometimes one also wants to check that a specific expression \b throws an exception. This checking can be done automatically using a <tt>try { } catch {}</tt> by using STXXL_CHECK_THROW.
 
 \section plain Plain Assertions: assert
 
-For the usual assertions, that should be removed in production code for
-performance, we use the standard \c "assert()" function.
+For the usual assertions, that should be removed in production code for performance, we use the standard \c "assert()" function.
 
-However, there is also \c STXXL_ASSERT(), which can be used as a replacement
-for \c assert(), when compiler warnings about unused variables or typedefs
-occur. The issue is that assert() completely removes the code, whereas
-STXXL_ASSERT() keeps the code encloses it inside \c if(0).
+However, there is also \c STXXL_ASSERT(), which can be used as a replacement for \c assert(), when compiler warnings about unused variables or typedefs occur. The issue is that assert() completely removes the code, whereas STXXL_ASSERT() keeps the code encloses it inside \c if(0).
 
 TODO: STXXL_THROW
 
@@ -236,14 +206,11 @@ See the file common/uint_types.h
 
 \section namespaces __STXXL_BEGIN_NAMESPACE
 
-A long, long time ago, not all compilers supported C++ namespaces, thus STXXL
-uses the macros __STXXL_BEGIN_NAMESPACE and __STXXL_END_NAMESPACE, which open
-and close the \c "namespace stxxl".
+A long, long time ago, not all compilers supported C++ namespaces, thus STXXL uses the macros __STXXL_BEGIN_NAMESPACE and __STXXL_END_NAMESPACE, which open and close the \c "namespace stxxl".
 
 \section unused STXXL_UNUSED
 
-STXXL_UNUSED is not actually a macro. It is a remedy against "unused variable"
-warnings, for whatever reason. Usage:
+STXXL_UNUSED is not actually a macro. It is a remedy against "unused variable" warnings, for whatever reason. Usage:
 
 \code
 void function(int x)
@@ -254,9 +221,7 @@ void function(int x)
 
 \section likely LIKELY and UNLIKEY
 
-Some compilers have facilities to specify whether a condition is likely or
-unlikely to be true. This may have consequences on how to layout the assembler
-code better.
+Some compilers have facilities to specify whether a condition is likely or unlikely to be true. This may have consequences on how to layout the assembler code better.
 
 \code
 if (LIKELY(x > 1)) { ... }
@@ -265,8 +230,6 @@ if (UNLIKELY(x > 8)) { ... }
 
 \section deprecated Deprecated Functions
 
-Some compilers can warn the user about deprecated function by tagging them in
-the source. In STXXL we use the macro _STXXL_DEPRECATED(...) to enclose
-deprecated functions.
+Some compilers can warn the user about deprecated function by tagging them in the source. In STXXL we use the macro _STXXL_DEPRECATED(...) to enclose deprecated functions.
 
 */

doc/design.dox

@@ -126,13 +126,11 @@ The documentation of \subpage design_stl "The STL-User Layer" is on a separate s
 
 # The Algorithm Pipelining Layer
 
-The \subpage design_pipeline "Streaming layer" provides efficient support for
-external memory algorithms with mostly \b sequential I/O pattern, i.e. scan,
-sort, merge, etc. A user algorithm, implemented using this module can save many
-I/Os. The win is due to an efficient interface, that couples the input and the
-output of the algorithms-components (scans, sorts, etc.). The output from an
-algorithm is directly fed into another algorithm as the input, without the need
-to store it on the disk.
+The \subpage design_pipeline "Streaming layer" provides efficient support for external memory algorithms with mostly \b sequential I/O pattern, i.e. scan, sort, merge, etc. A user algorithm, implemented using this module can save many I/Os. The win is due to an efficient interface, that couples the input and the output of the algorithms-components (scans, sorts, etc.). The output from an algorithm is directly fed into another algorithm as the input, without the need to store it on the disk.
+
+# Common Helpers and Utilities
+
+Beyond the layered library, STXXL contains many small helpers commonly used in C++ like random numbers or shared pointers. See \subpage common "the common library" for short descriptions.
 
 */
 

doc/faq.dox

@@ -1,4 +1,20 @@
-/*! \page FAQ FAQ - Frequently Asked Questions
+// -*- mode: c++; mode: visual-line; mode: flyspell; fill-column: 100000 -*-
+/***************************************************************************
+ *  doc/faq.dox
+ *
+ *  Frequently asked and answered questions
+ *
+ *  Part of the STXXL. See http://stxxl.sourceforge.net
+ *
+ *  Copyright (C) 2007 Andreas Beckmann <[email protected]>
+ *  Copyright (C) 2013 Timo Bingmann <[email protected]>
+ *
+ *  Distributed under the Boost Software License, Version 1.0.
+ *  (See accompanying file LICENSE_1_0.txt or copy at
+ *  http://www.boost.org/LICENSE_1_0.txt)
+ **************************************************************************/
+
+/** \page faq FAQ - Frequently Asked Questions
 
 \section FAQ-latest Latest version of this FAQ
 The most recent version of this FAQ can always be found

doc/install.dox

@@ -149,4 +149,6 @@ where you execute the program (in our case this would be /project/build/src). A
 [TODO] use syscall_unlink INSTEAD !!! touch /tmp/stxxl to create a file, the Stxxl is allowed to use as disk space \endverbatim
 Please see [TODO] for further available options.
 
+\author Timo Bingmann
+
 */

doc/introduction.dox

@@ -1,5 +1,5 @@
 /***************************************************************************
- *  doc/intro-design.dox
+ *  doc/introduction.dox
  *
  *  Most of this is from the old TeX tutorial and papers.
  *
@@ -13,7 +13,7 @@
  *  http://www.boost.org/LICENSE_1_0.txt)
  **************************************************************************/
 
-/*! \page introduction Introduction and Design
+/*! \page introduction Introduction to External Memory
 
 There exist many applications that have to process data sets which can not fit
 into the main memory of a computer, but fit into external memory (e.g. hard

doc/mainpage.dox

@@ -13,7 +13,7 @@
  *  http://www.boost.org/LICENSE_1_0.txt)
  **************************************************************************/
 
-/*! \mainpage Welcome to STXXL
+/** \mainpage Welcome to STXXL
 
 The core of STXXL is an implementation of the C++ standard template library STL for <b>external memory</b> (out-of-core) computations, i.e., STXXL implements containers and algorithms that can process huge volumes of data that only fit on disks. While the compatibility to the STL supports ease of use and compatibility with existing applications, another design priority is high performance. Here is a selection of STXXL performance features:
 
@@ -24,23 +24,19 @@ The core of STXXL is an implementation of the C++ standard template library STL
 - algorithm pipelining
 - utilization of multiple processor cores for internal computation
 
-See the \subpage introduction "introduction and design" page for a longer mission statement.
+See the \subpage introduction "introduction to external memory" for a longer description and our vision.
 
-\section getting_started Getting Started
+# Getting Started: Building and Tutorial
 
 This section will help you if you are using the STXXL for the first time.
 
-\subpage install_unix
+First you must compile the library. Pick one of the following instructions, depending on your host system:
 
-\link install-windows Compiling and Installing the STXXL on Microsoft Windows \endlink
+- \subpage install_unix
 
-\link install-macos Compiling Installing the STXXL on Mac OS \endlink
+- \link install-windows Compiling and Installing the STXXL on Microsoft Windows \endlink
 
-\subpage design "Design of STXXL concepts, containers and algorithms"
-
-\section usage_functionality Usage and Functionality
-
-This section provides simple and detailed documented examples on STXXL's datastructures.
+Once compiled, you can read the following simple tutorial on how to use STXXL containers and algorithms:
 
 \link external_vector External Memory Vector \endlink
 
@@ -54,26 +50,23 @@ This section provides simple and detailed documented examples on STXXL's datastr
 
 \link external_stack External Memory Stack \endlink
 
-\section installation Instructions on installation, usage, configuration
-
-- \link installation_linux_gcc Installation, usage, configuration (Linux/Unix &ndash; g++/icpc/clang++) \endlink
-- \link installation_msvc Installation, usage, configuration (Windows &ndash; Microsoft Visual C++) \endlink
+# Design and More Information
 
-- \link install-svn Installing from subversion \endlink
+We have collected much documentation about the design of STXXL. Even more information is available as academic research papers, technical reports and theses.
 
+- \subpage design "Design of STXXL concepts, containers and algorithms"
 
-\section questions Questions
+# Questions
 
 - Questions concerning use and development of the STXXL library should be posted to the <b><a href="http://sourceforge.net/projects/stxxl/forums">FORUMS</a></b>. Please search the forum before posting, your question may have been answered before.
 
-\section bugreports Bug Reports
+# Bug Reports and FAQ
 
-- Bugs should be reported in the <b><a href="https://stxxl.ae.cs.uni-frankfurt.de/bugs/">Bugzilla Bug Tracker</a></b>
-
-- \link FAQ FAQ - Frequently Asked Questions \endlink
+- \subpage faq "FAQ - Frequently Asked Questions"
 
+- Bugs should be reported in the <b><a href="https://stxxl.ae.cs.uni-frankfurt.de/bugs/">Bugzilla Bug Tracker</a></b>
 
-\section license License
+# License
 
 \c STXXL is distributed under the Boost Software License, Version 1.0.<br> You can find a copy of the license in the accompanying file \c LICENSE_1_0.txt or online at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>.