fixed python scripts for wandbox link update and html doc generation
diff --git a/doc/html_generated/assertions.html b/doc/html_generated/assertions.html
new file mode 100644
index 0000000..e528820
--- /dev/null
+++ b/doc/html_generated/assertions.html
@@ -0,0 +1,99 @@
+<!DOCTYPE html>
+<html>
+<title>assertions</title>
+<xmp theme="united" style="display:none;">
+
+## Assertion macros
+
+Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (```_EQUALS```, ```_NOTEQUALS```, ```_GREATER_THAN``` etc).
+
+**doctest** is different (but it's like [**Catch**](https://github.com/philsquared/Catch) in this regard). Because it decomposes natural C-style conditional expressions most of these forms are reduced to one or two that you will use all the time. That said there are a rich set of auxiliary macros as well. We'll describe all of these here.
+
+Most of these macros come in two forms:
+
+## Natural Expressions
+
+The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails.
+
+The ```CHECK``` family are equivalent but execution continues in the same test case even if the assertion fails. This is useful if you have a series of essentially orthogonal assertions and it is useful to see all the results rather than stopping at the first failure.
+
+The ```WARN``` family will just print the error when the condition is not met - but will not fail the test case.
+
+* **REQUIRE(** _expression_ **)**
+* **CHECK(** _expression_ **)**
+* **WARN(** _expression_ **)**
+
+Evaluates the expression and records the result. If an exception is thrown it is caught, reported, and counted as a failure (unless it is a **WARN**). These are the macros you will use most of the time
+
+Examples:
+
+```
+CHECK(str == "string value");
+CHECK(thisReturnsTrue());
+REQUIRE(i == 42);
+```
+
+* **REQUIRE_FALSE(** _expression_ **)**
+* **CHECK_FALSE(** _expression_ **)**
+* **WARN_FALSE(** _expression_ **)**
+
+Evaluates the expression and records the _logical NOT_ of the result. If an exception is thrown it is caught, reported, and counted as a failure.
+(these forms exist as a workaround for the fact that ! prefixed expressions cannot be decomposed).
+
+Example:
+
+```
+REQUIRE_FALSE(thisReturnsFalse());
+```
+
+### Floating point comparisons
+
+When comparing floating point numbers - especially if at least one of them has been computed - great care must be taken to allow for rounding errors and inexact representations.
+
+**doctest** provides a way to perform tolerant comparisons of floating point values through use of a wrapper class called ```doctest::Approx```. ```doctest::Approx``` can be used on either side of a comparison expression. It overloads the comparisons operators to take a tolerance into account. Here's a simple example:
+
+```
+REQUIRE(performComputation() == doctest::Approx(2.1));
+```
+
+By default a small epsilon value is used that covers many simple cases of rounding errors. When this is insufficient the epsilon value (the amount within which a difference either way is ignored) can be specified by calling the ```epsilon()``` method on the ```doctest::Approx``` instance. e.g.:
+
+```
+REQUIRE(22/7 == doctest::Approx(3.141).epsilon(0.01));
+```
+
+When dealing with very large or very small numbers it can be useful to specify a scale, which can be achieved by calling the ```scale()``` method on the ```doctest::Approx``` instance.
+
+## Exceptions
+
+* **REQUIRE_THROWS(** _expression_ **)**
+* **CHECK_THROWS(** _expression_ **)**
+* **WARN_THROWS(** _expression_ **)**
+
+Expects that an exception (of any type) is be thrown during evaluation of the expression.
+
+* **REQUIRE_THROWS_AS(** _expression_, _exception type_ **)**
+* **CHECK_THROWS_AS(** _expression_, _exception type_ **)**
+* **WARN_THROWS_AS(** _expression_, _exception type_ **)**
+
+Expects that an exception of the _specified type_ is thrown during evaluation of the expression.
+
+* **REQUIRE_NOTHROW(** _expression_ **)**
+* **CHECK_NOTHROW(** _expression_ **)**
+* **WARN_NOTHROW(** _expression_ **)**
+
+Expects that no exception is thrown during evaluation of the expression.
+
+--------
+
+- Check out the [**example**](../../examples/assertion_macros/main.cpp) which shows many of these macros
+- Do not wrap assertion macros in ```try```/```catch``` - the REQUIRE macros throw exceptions to end the test case execution!
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/benchmarks.html b/doc/html_generated/benchmarks.html
new file mode 100644
index 0000000..621f958
--- /dev/null
+++ b/doc/html_generated/benchmarks.html
@@ -0,0 +1,99 @@
+<!DOCTYPE html>
+<html>
+<title>benchmarks</title>
+<xmp theme="united" style="display:none;">
+
+## Benchmarks
+
+This is a benchmark that is relevant only to single header and header only frameworks - like **doctest** and [**Catch**](https://github.com/philsquared/Catch).
+
+The benchmark is done with [**this**](../../scripts/bench/bench.py) script only under Windows (but can be adapted for Unix) using CMake.
+
+It should be noted that GCC performs much better under Unix.
+
+The script generates 501 source files and in 500 of them makes a function in the form of ```int f135() { return 135; }``` and in ```main.cpp``` it forward declares all the 500 such dummy functions and accumulates their result to return from the ```main()``` function. This is done to ensure that all source files are built and that the linker doesn't remove/optimize anything.
+
+- **baseline** - how much time the source files need for a single threaded build with ```msbuild```/```mingw32-make```
+- **+ implementation** - only in ```main.cpp``` the header is included with a ```#define``` before it so the test runner gets instantiated:
+
+ ```
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include "doctest.h"
+ ```
+- **+ header everywhere** - the framework header is also included in all the other source files
+- **+ a test everywhere** - in all the source files there is 1 test case with 1 assertions defined
+- **+ disabled** - **doctest** specific - only this framework can remove everything related to it from the binary
+
+## doctest
+
+| | baseline | + implementation | + header everywhere | + a test everywhere | + disabled |
+|--------------|----------|---------------------|------------------------------|---------------------|-------------------------|
+| MSVC Debug | 14.2 | 15.1 | 18.3 | 21.4 | 15.6 |
+| MSVC Release | 13.4 | 14.5 | 18.7 | 23.2 | 15.2 |
+| GCC Debug | 22.7 | 24.1 | 29.2 | 38 | 25 |
+| GCC Release | 22.9 | 25 | 30 | 45 | 25 |
+
+## Catch
+
+| | baseline | + implementation | + header everywhere | + a test everywhere | |
+|--------------|----------|---------------------|------------------------------|---------------------|-------------------------|
+| MSVC Debug | 14.2 | 17 | 242 | 249 | |
+| MSVC Release | 13.4 | 17.7 | 231 | 264 | |
+| GCC Debug | 22.7 | 36.7 | 178 | 189 | |
+| GCC Release | 22.9 | 31.5 | 163 | 193 | |
+
+## Conclusion
+
+So on a modern developer machine:
+
+### doctest
+
+- instantiating the test runner in one source file costs ~1 second ```implementation - baseline```
+- the inclusion of ```doctest.h``` in one source file costs below 9ms ```(header_everywhere - implementation) / 500```
+- the addition of a test costs below 10ms ```(a_test_everywhere - header_everywhere) / 500```
+ (below 18ms for MinGW-w64 but Linux GCC will be much faster)
+- using the library everywhere with tests - but everything disabled - costs less than 2 seconds ```disabled - baseline```
+
+### [Catch](https://github.com/philsquared/Catch)
+
+- instantiating the test runner in one source file costs ~4 second ```implementation - baseline```
+ (~12 seconds for MinGW-w64 but Linux GCC will be much faster)
+- the inclusion of ```catch.hpp``` in one source file costs around 430ms ```(header_everywhere - implementation) / 500```
+ (below 280ms for MinGW-w64 which is really odd)
+- the addition of a test costs between 20ms and 60ms ```(a_test_everywhere - header_everywhere) / 500```
+
+----------
+
+So if ```doctest.h``` costs 8ms and ```catch.hpp``` costs 430ms on MSVC - then **doctest** is >> **54** << times lighter!
+
+----------
+
+The results are in seconds and are in **no way** intended to bash [**Catch**](https://github.com/philsquared/Catch) - the **doctest** framework wouldn't exist without it.
+
+The reason **doctest** is so light on compile times is because it forward declares everything and doesn't drag any standard headers in the source files (except for the source file where the test runner gets instantiated). This was a design decision from day 1.
+
+## Details
+
+Compilers used:
+
+- Microsoft Visual Studio Community 2015 - Version 14.0.25123.00 Update 2
+- gcc 5.3.0 (x86_64-posix-seh-rev0, Built by MinGW-W64 project)
+
+Environment used - Windows 7 on an SSD, Intel i7 3770k, 16g RAM
+
+Date: 2016.05.22
+
+**doctest** version: 1.0.0
+
+[**Catch**](https://github.com/philsquared/Catch) version: 1.5.4
+
+Room temperature: 18°C
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/commandline.html b/doc/html_generated/commandline.html
new file mode 100644
index 0000000..7cf67c6
--- /dev/null
+++ b/doc/html_generated/commandline.html
@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html>
+<title>commandline</title>
+<xmp theme="united" style="display:none;">
+
+## Command line
+
+**doctest** works quite nicely without any command line options at all - but for more control there are a bunch that are available.
+
+**Query flags** - after the result is printed the program quits without executing any test cases (and if the framework is integrated into a client codebase which [**supplies it's own ```main()``` entry point**](main.html) - the program should check the result of ```doctest::Context::shouldExit()``` after calling ```doctest::Context::run()``` and should exit - this is left up to the user).
+
+**Int/String options** - they require a value after the ```=``` sign - without spaces! For example: ```--order-by=rand```.
+
+**Bool options** - they expect ```1```/```yes```/```on```/```true``` or ```0```/```no```/```off```/```false``` after the ```=``` sign - but they can also be used like flags and the ```=value``` part can be skipped - then ```true``` is assumed.
+
+**Filters** use wildcards for matching values - where ```*``` means "match any sequence" and ```?``` means "match any one character".
+To pass a pattern with an interval use ```""``` like this: ```--test-case="*no sound*,vaguely named test number ?"```.
+
+All the options can also be set with code if the user [**supplies the ```main()``` function**](main.html) so an option is always with some value.
+
+| Query Flags | Description |
+|:------------|-------------|
+| ```-?``` ```--help``` ```-h``` | Prints a help message listing all these flags/options |
+| ```-v``` ```--version``` | Prints the version of the **doctest** framework |
+| ```-c``` ```--count``` | Prints the number of test cases matching the current filters (see below) |
+| ```-ltc``` ```--list-test-cases``` | Lists all test cases by name which match the current filters (see below) |
+| ```-lts``` ```--list-test-suites``` | Lists all test suites by name which have at least one test case matching the current filters (see below) |
+| **Int/String Options** | <hr> |
+| ```-tc``` ```--test-case=<filters>``` | Filters test cases based on their name. By default all test cases match but if a value is given to this filter like ```--test-case=*math*,*sound*``` then only test cases who match atleast one of the patterns in the comma-separated list with wildcards will get executed/counted/listed |
+| ```-tce``` ```--test-case-exclude=<filters>``` | Same as the ```-test-case=<filters>``` option but if any of the patterns in the comma-separated list of values matches - then the test case is skipped |
+| ```-sf``` ```--source-file=<filters>``` | Same as ```--test-case=<filters>``` but filters based on the file in which test cases are written |
+| ```-sfe``` ```--source-file-exclude=<filters>``` | Same as ```--test-case-exclude=<filters>``` but filters based on the file in which test cases are written |
+| ```-ts``` ```--test-suite=<filters>``` | Same as ```--test-case=<filters>``` but filters based on the test suite in which test cases are in |
+| ```-tse``` ```--test-suite-exclude=<filters>``` | Same as ```--test-case-exclude=<filters>``` but filters based on the test suite in which test cases are in |
+| ```-ob``` ```--order-by=<string>``` | Test cases will be sorted before being executed either by **the file in which they are** / **the test suite they are in** / **their name** / **random**. The possible values of ```<string>``` are ```file```/```suite```/```name```/```rand```. The default is ```file``` |
+| ```-rs``` ```--rand-seed=<int>``` | The seed for random ordering |
+| ```-f``` ```--first=<int>``` | The **first** test case to execute which passes the current filters - for range-based execution - see [**the example**](../../examples/range_based_execution/) (the **run.py** script) |
+| ```-l``` ```--last=<int>``` | The **last** test case to execute which passes the current filters - for range-based execution - see [**the example**](../../examples/range_based_execution/) (the **run.py** script) |
+| ```-aa``` ```--abort-after=<int>``` | The testing framework will stop executing test cases/assertions after this many failed assertions. The default is 0 which means don't stop at all |
+| **Bool Options** | <hr> |
+| ```-s``` ```--success=<bool>``` | To include successful assertions in the output |
+| ```-cs``` ```--case-sensitive=<bool>``` | Filters being treated as case sensitive |
+| ```-e``` ```--exit=<bool>``` | Exits after the tests finish - this is meaningful only when the client has [**provided the ```main()``` entry point**](main.html) - the program should check ```doctest::Context::shouldExit()``` after calling ```doctest::Context::run()``` and should exit - this is left up to the user. The idea is to be able to execute just the tests in a client program and to not continue with it's execution |
+| ```-no``` ```--no-overrides=<bool>``` | Disables procedural overrides of options which are only possible if the client has [**provided the ```main()``` entry point**](main.html). This is useful if the program has some default options set (which override the command line) but you want to set an option differently from the command line without recompiling.|
+| ```-nt``` ```--no-throw=<bool>``` | Skips [**exceptions-related assertion**](assertions.html#exceptions) checks |
+| ```-ne``` ```--no-exitcode=<bool>``` | Always returns a successful exit code - even if a test case has failed |
+| ```-nr``` ```--no-run=<bool>``` | Skips all runtime **doctest** operations (except the test registering which happens before the program enters ```main()```). This is useful if the testing framework is integrated into a client codebase which has [**provided the ```main()``` entry point**](main.html) and the user wants to skip running the tests and just use the program |
+| ```-nc``` ```--no-colors=<bool>``` | Disables colors in the output |
+| ```-nb``` ```--no-breaks=<bool>``` | Disables breakpoints in debuggers when an assertion fails |
+| ```-npf``` ```--no-path-filenames=<bool>``` | Paths are removed from the output when a filename is printed - useful if you want the same output from the testing framework on different environments |
+| | |
+
+All the flags/options also come with a prefixed version (with ```-dt-``` at the front) - for example ```--version``` can be used also with ```--dt-version``` or ```-dt-v```.
+
+All the unprefixed versions listed here can be disabled with the [**```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**](configuration.html) define.
+
+This is done for easy interoperability with client command line option handling when the testing framework is integrated within a client codebase - all **doctest** related flags/options can be prefixed so there are no clashes and so that the user can exclude everything starting with ```-dt-``` from their option parsing.
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/configuration.html b/doc/html_generated/configuration.html
new file mode 100644
index 0000000..acc4432
--- /dev/null
+++ b/doc/html_generated/configuration.html
@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html>
+<title>configuration</title>
+<xmp theme="united" style="display:none;">
+
+## Configuration
+
+**doctest** is designed to "just work" as much as possible. It exposes a small set of defines for configuring how it is built.
+
+For most people the only configuration needed is telling **doctest** which source file should host all the implementation code:
+
+- **```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**
+
+ ```
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include "doctest.h"
+ ```
+
+ This should be done in only one source file! Otherwise there will be linker errors and slower build times.
+
+- **```DOCTEST_CONFIG_IMPLEMENT```** - if the client wants to [**supply the ```main()``` function**](main.html) (either to set an option with some value from the code or to integrate the framework into his existing project codebase) this define should be used.
+
+- **```DOCTEST_CONFIG_DISABLE```** - the next most important configuration option - when defined globally in the whole project before the inclusion of the framework header - everything testing - related is removed from the binary - including most of the framework implementation and every test case written anywhere! This is one of the most unique features of **doctest**.
+
+- **```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```** - this will remove all macros from **doctest** that don't have the **```DOCTEST_```** prefix - like **```CHECK```**, **```TEST_CASE```** and **```SUBCASE```**. Then only the full macro names will be available - **```DOCTEST_CHECK```**, **```DOCTEST_TEST_CASE```** and **```DOCTEST_SUBCASE```**. The user is free to make his own short versions of these macros - [**example**](../../examples/alternative_macros/)
+
+- **```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```** - this will disable the short versions of the [**command line**](commandline.html) options and only the versions with ```-dt-``` prefix will be parsed by **doctest** - this is possible for easy interoperability with client command line option handling when the testing framework is integrated within a client codebase - so there are no clashes and so that the user can exclude everything starting with ```-dt-``` from their option parsing. This configuration option is relevant only for the source file where the library is implemented
+
+- **```DOCTEST_CONFIG_COLORS_NONE```** - this will remove support for colors in the console output of the framework. This configuration option is relevant only for the source file where the library is implemented
+
+- **```DOCTEST_CONFIG_COLORS_WINDOWS```** - this will force the support for colors in the console output to use the Windows APIs and headers. This configuration option is relevant only for the source file where the library is implemented
+
+- **```DOCTEST_CONFIG_COLORS_ANSI```** - this will force the support for colors in the console output to use ANSI escape codes. This configuration option is relevant only for the source file where the library is implemented
+
+- **```DOCTEST_CONFIG_USE_IOSFWD```** - the library by default provides a forward declaration of ```std::ostream``` in order to support the ```operator<<``` [**stringification**](stringification.html) mechanism. This is forbidden by the standard (even though it works everywhere on all tested compilers). However if the user wishes to be 100% standards compliant - then this configuration option can be used to force the inclusion of ```<iosfwd>```. It should be defined everywhere before the framework header is included.
+
+- **```DOCTEST_CONFIG_WITH_LONG_LONG```** - by default the library includes support for stringifying ```long long``` only if the value of ```__cplusplus``` is at least ```201103L``` (C++11) or if the compiler is MSVC 2003 or newer. Many compilers that don't fully support C++11 have it as an extension but it errors for GCC/Clang when the ```-std=c++98``` option is used and this cannot be detected with the preprocessor in any way. Use this configuration option if your compiler supports ```long long``` but doesn't yet support the full C++11 standard. It should be defined everywhere before the framework header is included.
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/faq.html b/doc/html_generated/faq.html
new file mode 100644
index 0000000..b7bb6ab
--- /dev/null
+++ b/doc/html_generated/faq.html
@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html>
+<title>faq</title>
+<xmp theme="united" style="display:none;">
+
+## FAQ
+
+#TODO...
+
+- linker issues? Make sure you have instantiated the test runner in only one source file.
+
+- stringification issues - if operator<<(ostream for a type is visible only in one source file...
+
+- why no regex and only wildcards
+
+- tests are ran serially - no multi-threaded execution planned for now
+
+- mocking is not included because it is orthogonal to testing and a different third party library may be used for that (google mock)
+https://github.com/tpounds/mockitopp
+
+- linker errors for ```doctest::detail::...``` when using ```DOCTEST_CONFIG_DISABLE```
+ solution: don't use anything from detail
+
+- property based testing - what it is and how to use it with doctest
+
+- tests in headers... might end up in different test suites - and only 1 of them will get registered? or might have ifdef-ed parts that get compiled differently based on how/where the header is included...... so not a good practice to write tests in header files
+
+- how subcases work - http://pastebin.com/rwghFzK4 - or look in the repo
+
+- why c++98? because.
+
+- will the library support checking for memory leaks? no. use tools like valgrind or the sanitizers.
+
+- mixing different versions of the framework within the same executable?
+ - unfortunately what single header libraries like [stb](https://github.com/nothings/stb) are doing is not feasible with this library.
+ - it could be done if tests are written only in source files where the library has been implemented with the ```DOCTEST_CONFIG_IMPLEMENT``` macro but that is very limiting.
+
+- is the VC++6 support full?
+ - no
+ - the stringification with ```ostream& operator<<(ostream&, myType)``` is disabled
+ - comparing C strings will compare the pointers and not the actual strings
+ - VC6 subcases not working - set a bounty on this: http://stackoverflow.com/questions/36940730/preprocessor-problems-with-vc6
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/features.html b/doc/html_generated/features.html
new file mode 100644
index 0000000..d22e455
--- /dev/null
+++ b/doc/html_generated/features.html
@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html>
+<title>features</title>
+<xmp theme="united" style="display:none;">
+
+## Features and design goals
+
+**doctest** has been designed from the start to be as **light** and **unintrusive** as possible. These key features should be kept.
+
+## Unintrusive (transparent):
+
+- everything testing-related can be removed from the binary executable by defining the [**```DOCTEST_CONFIG_DISABLE```**](configuration.html) identifier
+- very small and easy to integrate - single header - less than 3k LOC in the implementation translation unit and less than 1.5k LOC everywhere else - **extremely** low footprint on compile times - see the [**benchmarks**](benchmarks.html)
+- doesn't drag any headers when included (except for in the translation unit where the library gets implemented)
+- everything is in the ```doctest``` namespace (and the implementation details are in a nested ```detail``` namespace)
+- all macros have prefixes - some by default have unprefixed versions as well but that is optional - see [**configuration**](configuration.html)
+- 0 warnings even with the most aggresive flags (on all tested compilers!!!)
+ - ```-Weverything -pedantic``` for **clang**
+ - ```-Wall -Wextra -pedantic``` and **>> over 50 <<** other warnings **not** covered by these flags for **GCC**!!! - see [**here**](../../scripts/common.cmake#L59)
+ - ```/W4``` for **MSVC** (```/Wall``` is too much there - even their own headers produce **thousands** of warnings with that option)
+- doesn't error on unrecognized [**command line**](commandline.html) options and supports prefixes for interop with client command line parsing
+- can set options [**procedurally**](main.html) and not deal with passing ```argc```/```argv``` from the command line
+- doesn't leave warnings disabled after itself
+
+## Extremely portable:
+
+- Standards compliant **C++98** code - should work with any **C++98** compiler
+- tested with **GCC**: **4.4**, **4.5**, **4.6**, **4.7**, **4.8**, **4.9**, **5.0**
+- tested with **Clang**: **3.4**, **3.5**, **3.6**, **3.7**, **3.8**
+- tested with **MSVC**: **2008**, **2010**, **2012**, **2013**, **2015** (and even **VC++6** - that **18 year old compiler** from 1998!)
+- per-commit tested on **travis** and **appveyor** CI services
+ - warnings as errors even on the most aggressive warning levels - see [**here**](../../scripts/common.cmake#L59)
+ - all tests have their output compared to reference output of a previous known good run
+ - all tests built and ran in **Debug**/**Release** and also in **32**/**64** bit modes
+ - all tests ran through **valgrind** under **Linux**/**OSX**
+ - all tests ran through **address** and **UB** sanitizers under **Linux**/**OSX**
+ - tests are ran in a total of **180** different configurations on UNIX (Linux + OSX) on **travis** CI
+ - tests are ran in a total of **18** different configurations on Windows on **appveyor** CI
+
+## Other features:
+
+- really easy to get started - it's just 1 header file - see the [**tutorial**](tutorial.html)
+- **very** light, unintrusive and portable - see the sections above - and also the [**benchmarks**](benchmarks.html)
+- offers a way to remove **everything** testing-related from the binary with the [**```DOCTEST_CONFIG_DISABLE```**](configuration.html) macro
+- tests are registered automatically - no need to add them to a collection manually
+- supports [**subcases**](testcases.html) for easy setup/teardown of tests (also supports the retro [**test fixtures**](testcases.html#) with classes)
+- output from all compilers on all platforms is the same - byte by byte
+- supports [**BDD style**](testcases.html) tests
+- only one core [**assertion macro**](assertions.html) for comparisons - standard C++ operators are used for the comparison (less than, equal, greater than...) - yet the full expression is decomposed and left and right values of the expression are logged
+- assertion macros for [**exceptions**](assertions.html) - if something should or shouldn't throw
+- floating point comparison support - see the [**```Approx()```**](assertions.html#floating-point-comparisons) helper
+- powerful mechanism for [**stringification**](stringification.html) of user types
+- tests can be grouped in [**test suites**](testcases.html)
+- powerful [**command line**](commandline.html) with lots of options
+- tests can be [**filtered**](commandline.html) based on their name/file/test suite using wildcards
+- failures can (optionally) break into the debugger on Windows and Mac
+- integration with the output window of Visual Studio for failing tests
+- a ```main()``` can be provided when implementing the library with the [**```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**](main.html) identifier
+- can write tests in headers - they will still be registered only once in the executable/shared object
+- [**range-based**](commandline.html) execution of tests - see the [**range_based_execution**](../../examples/range_based_execution/) example (the **run.py** script)
+- colored output in the console
+- controlling the order of test execution
+
+There is a list of planned features which are all important and big - see the [**roadmap**](roadmap.html).
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/main.html b/doc/html_generated/main.html
new file mode 100644
index 0000000..f118749
--- /dev/null
+++ b/doc/html_generated/main.html
@@ -0,0 +1,62 @@
+<!DOCTYPE html>
+<html>
+<title>main</title>
+<xmp theme="united" style="display:none;">
+
+## The ```main()``` entry point
+
+The usual way of writing tests in C++ has always been into separate source files from the code they test that form an executable containing only tests. In that scenario the default ```main()``` provided by **doctest** is usually sufficient:
+
+```
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include "doctest.h"
+```
+
+This should be done in exactly one source file and is even a good idea to do this in a separate file with nothing else in it.
+
+However if you need more control - want to set options with code to the execution context or want to integrate the framework in your production code - then the default ```main()``` just won't do the job. In that case use **```DOCTEST_CONFIG_IMPLEMENT```**.
+
+All the [**command line**](commandline.html) options can be set like this (flags cannot because it wouldn't make sense). Filters can only be appended - the user cannot remove a filter given from the command line with code.
+
+```
+#define DOCTEST_CONFIG_IMPLEMENT
+#include "doctest.h"
+
+int main(int argc, char** argv) {
+ doctest::Context context(argc, argv); // initialize
+
+ // overrides
+ context.addFilter("test-case-exclude", "*math*"); // exclude test cases with "math" in their name
+ context.setOption("no-breaks", true); // don't break in the debugger when assertions fail
+ context.setOption("abort-after", 5); // stop test execution after 5 failed assertions
+ context.setOption("sort", "name"); // sort the test cases by their name
+
+ int res = context.run(); // run
+
+ if(context.shouldExit()) // important - query flags (and --no-run) rely on the user doing this
+ return res; // propagate the result of the tests
+
+ int client_stuff_return_code = 0;
+ // your program - if the testing framework is integrated in your production code
+
+ return res + client_stuff_return_code;
+}
+
+```
+
+Note the call to ```.shouldExit()``` on the context - that is very important - it will be set when a query flag has been used (or the ```--no-run``` option is set to ```true```) and it is the user's responsibility to exit the application in a normal way.
+
+### Dealing with shared objects (DLLs)
+
+When integrating the framework in production code which gets built as a shared object (dll) everything still works. Many shared objects and an executable can have tests in them and can even use different versions of the **doctest** framework.
+
+Check out [**this**](../../examples/dll_and_executable/) example which showcases how to call the tests in a shared object from the executable (and it also showcases that if a file with a test case is included both in the shared object and the executable then the test is registered in both places).
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/random_dev_notes.html b/doc/html_generated/random_dev_notes.html
new file mode 100644
index 0000000..9a7b867
--- /dev/null
+++ b/doc/html_generated/random_dev_notes.html
@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+<title>random_dev_notes</title>
+<xmp theme="united" style="display:none;">
+
+on big releases spam in hackernews and reddit/r/cpp/gamedev/Cplusplus/programming
+
+how to deal with pull requests for the main branch instead of the dev branch
+- http://stackoverflow.com/questions/9135913/merge-pull-request-to-a-different-branch-than-default-in-github
+- git fetch origin pull/ID/head:BRANCHNAME
+
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/readme.html b/doc/html_generated/readme.html
new file mode 100644
index 0000000..20f8edb
--- /dev/null
+++ b/doc/html_generated/readme.html
@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html>
+<title>readme</title>
+<xmp theme="united" style="display:none;">
+
+Reference
+=======
+
+- [Features and design goals](features.html) - the complete list of features
+- [Roadmap](roadmap.html) - upcoming features
+- [Tutorial](tutorial.html) - make sure you have read it before the other parts of the documentation
+- [Benchmarks](benchmarks.html) - compile time supremacy
+- [Examples](../../examples)
+
+-------------
+
+- [Assertion macros](assertions.html)
+- [Test cases, subcases and test fixtures](testcases.html)
+- [Command line](commandline.html)
+- [Configuration](configuration.html)
+- [String conversions](stringification.html)
+- [```main()``` entry point and dealing with shared objects](main.html)
+- [FAQ](faq.html)
+
+Support the development of the project with donations! There is a list of planned features which are all important and big - see the [**roadmap**](roadmap.html). I work on this project in my spare time and every cent is a big deal.
+
+[](https://pledgie.com/campaigns/31280)
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/roadmap.html b/doc/html_generated/roadmap.html
new file mode 100644
index 0000000..74124f6
--- /dev/null
+++ b/doc/html_generated/roadmap.html
@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html>
+<title>roadmap</title>
+<xmp theme="united" style="display:none;">
+
+## Roadmap
+
+Support the development of the project with donations! I work on this project in my spare time and every cent is a big deal.
+
+[](https://pledgie.com/campaigns/31280)
+
+This is a list of planned features for future releases (maybe in the given order).
+
+- fix the test coverage reports - currently each example replaces the coverage from the last example
+- test with gcc 6 and use it in the CI builds
+- support for ```std::exception``` and derivatives (mainly for calling the ```.what()``` method when caught unexpectedly)
+- test with missed warning flags for GCC - look into https://github.com/Barro/compiler-warnings
+- crash handling: signals on UNIX platforms or structured exceptions on Windows
+- support for tags
+ - may fail tag
+ - invisible tag
+ - look at Catch - https://github.com/philsquared/Catch/blob/master/docs/test-cases-and-sections.html#special-tags
+- output to file
+- reporters
+ - a system for writing custom reporters
+ - ability to use multiple reporters at once (but only 1 to stdout)
+ - a compact reporter
+ - an xml reporter
+ - jUnit/xUnit reporters
+- add the ability to query if code is currently being ran in a test - ```doctest::isRunningInTest()```
+- convolution support for the assertion macros (with a predicate)
+- time stuff
+ - reporting running time of tests
+ - restricting duration of test cases
+ - killing a test that exceeds a time limit (will perhaps require threading or processes)
+- adding contextual info to asserts (logging) - with an ```INFO```/```CONTEXT``` /```TRACEPOINT``` macro
+- add ```ERROR```/```FAIL``` macros
+- running tests a few times
+- marking a test to run X times (should also multiply with the global test run times)
+- test execution in separate processes - ```fork()``` for UNIX and [this](https://github.com/nemequ/munit/issues/2) for Windows
+- ability to provide a temp folder that is cleared between each test case
+- detect floating point exceptions
+- ```Bitwise()``` class that has overloaded operators for comparison - to be used to check objects bitwise against each other
+- integrate static analysis on the CI: **msvc**, **clang**, **cppcheck**
+- get a build with **MinGW-w64** running on **appveyor**
+
+And here is a list of things that are being considered but not part of the roadmap yet:
+
+- matchers - should investigate what they are :D
+- option to list files in which there are test cases who match the current filters
+- handle ```wchar``` strings
+- refactor the assertion macros - make proxy functions that do most of the things to minimize code bloat
+- pool allocator for the ```String``` class - currently very unoptimized
+- ability to specify ASC/DESC for the order option
+- command line error handling/reporting
+- utf8? not sure if this should be here
+- print a warning when no assertion is encountered in a test case
+- hierarchical test suites - using a stack for the pushed ones - should be easy
+- put everything from the ```detail``` namespace also in a nested anonymous namespace to make them with internal linkage
+- ability to re-run only newly compiled tests based on time stamps using ```__DATE__``` and ```__TIME__``` - stored in some file
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/stringification.html b/doc/html_generated/stringification.html
new file mode 100644
index 0000000..93c5e02
--- /dev/null
+++ b/doc/html_generated/stringification.html
@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html>
+<title>stringification</title>
+<xmp theme="united" style="display:none;">
+
+## String conversions
+
+**doctest** needs to be able to convert types you use in assertions and logging expressions into strings (for logging and reporting purposes).
+Most built-in types are supported out of the box but there are three ways that you can tell **doctest** how to convert your own types (or other, third-party types) into strings.
+
+## ```operator<<``` overload for ```std::ostream```
+
+This is the standard way of providing string conversions in C++ - and the chances are you may already provide this for your own purposes. If you're not familiar with this idiom it involves writing a free function of the form:
+
+```
+std::ostream& operator<< (std::ostream& os, const T& value) {
+ os << convertMyTypeToString(value);
+ return os;
+}
+```
+
+(where ```T``` is your type and ```convertMyTypeToString``` is where you'll write whatever code is necessary to make your type printable - it doesn't have to be in another function).
+
+You should put this function in the same namespace as your type.
+
+Alternatively you may prefer to write it as a member function:
+
+```
+std::ostream& T::operator<<(std::ostream& os) const {
+ os << convertMyTypeToString(*this);
+ return os;
+}
+```
+
+## ```doctest::toString``` overload
+
+If you don't want to provide an ```operator<<``` overload, or you want to convert your type differently for testing purposes, you can provide an overload for ```doctest::toString()``` for your type.
+
+```
+namespace doctest {
+ String toString(const T& value) {
+ return convertMyTypeToString(value);
+ }
+}
+```
+
+Again ```T``` is your type and ```convertMyTypeToString``` is where you'll write whatever code is necessary to make your type printable. Note that the function must be in the **doctest** namespace which itself must be in the global namespace.
+
+## ```doctest::StringMaker<T>``` specialisation
+
+There are some cases where overloading ```toString``` does not work as expected. Specialising ```StringMaker<T>``` gives you more precise and reliable control - but at the cost of slightly more code and complexity:
+
+```
+namespace doctest {
+ template<> struct StringMaker<T> {
+ static String convert(const T& value) {
+ return convertMyTypeToString(value);
+ }
+ };
+}
+```
+
+------
+
+- Check out the [**example**](../../examples/stringification/main.cpp) which shows how to stringify ```std::vector<T>``` and other types.
+- Note that the type ```String``` is used when specializing ```StringMaker<T>``` or overloading ```toString()``` - it is the string type **doctest** works with. ```std::string``` is not an option for the library because then it would have to drag the ```<string>``` header with it.
+- To support the ```operator<<(std::ostream&...``` stringification the library has to offer a forward declaration of ```std::ostream``` and that is what the library does - but it is forbidden by the standard. It currently works everywhere - on all tested compilers - but if the user wishes to be 100% standards compliant - then the [**```DOCTEST_CONFIG_USE_IOSFWD```**](configuration.html) identifier can be used to force the inclusion of ```<iosfwd>```. The reason the header is not included by default is that on MSVC (for example) it drags a whole bunch of stuff with it - and after the preprocessor is finished the translation unit has grown to 42k lines of C++ code - while Clang and the libc++ are so well implemented that including ```<iosfwd>``` there results in 400 lines of code.
+
+---
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/testcases.html b/doc/html_generated/testcases.html
new file mode 100644
index 0000000..43eb624
--- /dev/null
+++ b/doc/html_generated/testcases.html
@@ -0,0 +1,108 @@
+<!DOCTYPE html>
+<html>
+<title>testcases</title>
+<xmp theme="united" style="display:none;">
+
+## Test cases
+
+While **doctest** fully supports the traditional, xUnit, style of class-based fixtures containing test case methods this is not the preferred style.
+
+Instead **doctest** provides a powerful mechanism for nesting subcases within a test case. For a more detailed discussion see the [**tutorial**](tutorial.html#test-cases-and-subcases).
+
+Test cases and subcases are very easy to use in practice:
+
+* **TEST_CASE(** _test name_ **)**
+* **SUBCASE(** _subcase name_ **)**
+
+_test name_ and _subcase name_ are free form, quoted, strings. Test names don't have to be unique within the **doctest** executable. They should also be string literals.
+
+For examples see the [Tutorial](tutorial.html)
+
+## BDD-style test cases
+
+In addition to **doctest**'s take on the classic style of test cases, **doctest** supports an alternative syntax that allow tests to be written as "executable specifications" (one of the early goals of [Behaviour Driven Development](http://dannorth.net/introducing-bdd/)). This set of macros map on to ```TEST_CASE```s and ```SUBCASE```s, with a little internal support to make them smoother to work with.
+
+* **SCENARIO(** _scenario name_ **)**
+
+This macro maps onto ```TEST_CASE``` and works in the same way, except that the test case name will be prefixed by "Scenario: "
+
+* **GIVEN(** _something_ **)**
+* **WHEN(** _something_ **)**
+* **THEN(** _something_ **)**
+
+These macros map onto ```SUBCASE```s except that the subcase names are the _something_s prefixed by "given: ", "when: " or "then: " respectively.
+
+* **AND_WHEN(** _something_ **)**
+* **AND_THEN(** _something_ **)**
+
+Similar to ```WHEN``` and ```THEN``` except that the prefixes start with "and ". These are used to chain ```WHEN```s and ```THEN```s together.
+
+When any of these macros are used the console reporter recognises them and formats the test case header such that the Givens, Whens and Thens are aligned to aid readability.
+
+Other than the additional prefixes and the formatting in the console reporter these macros behave exactly as ```TEST_CASE```s and ```SUBCASE```s. As such there is nothing enforcing the correct sequencing of these macros - that's up to the programmer!
+
+## Test fixtures
+
+Although **doctest** allows you to group tests together as subcases within a test case, it can still be convenient, sometimes, to group them using a more traditional test fixture. **doctest** fully supports this too. You define the test fixture as a simple structure:
+
+```
+class UniqueTestsFixture {
+ private:
+ static int uniqueID;
+ protected:
+ DBConnection conn;
+ public:
+ UniqueTestsFixture() : conn(DBConnection::createConnection("myDB")) {
+ }
+ protected:
+ int getID() {
+ return ++uniqueID;
+ }
+ };
+
+ int UniqueTestsFixture::uniqueID = 0;
+
+ TEST_CASE_FIXTURE(UniqueTestsFixture, "Create Employee/No Name") {
+ REQUIRE_THROWS(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), ""));
+ }
+ TEST_CASE_METHOD(UniqueTestsFixture, "Create Employee/Normal") {
+ REQUIRE(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), "Joe Bloggs"));
+ }
+```
+
+The two test cases here will create uniquely-named derived classes of UniqueTestsFixture and thus can access the `getID()` protected method and `conn` member variables. This ensures that both the test cases are able to create a DBConnection using the same method (DRY principle) and that any ID's created are unique such that the order that tests are executed does not matter.
+
+## Test suites
+
+Test cases can be grouped into test suites. This is done with the ```TEST_SUITE()``` and ```TEST_SUITE_END()``` macros.
+
+For example:
+
+```
+TEST_CASE("") {} // not part of any test suite
+
+TEST_SUITE("math");
+
+TEST_CASE("") {} // part of the math test suite
+TEST_CASE("") {} // part of the math test suite
+
+TEST_SUITE_END();
+
+TEST_CASE("") {} // not part of any test suite
+```
+
+Then test cases from specific test suites can be executed with the help of filters - check out the [**command line**](commandline.html)
+
+------
+
+- Check out the [**example**](../../examples/subcases_and_bdd/main.cpp)
+- Tests are registered from top to bottom of each processed cpp after the headers have been preprocessed and included but there is no ordering between cpp files.
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/html_generated/tutorial.html b/doc/html_generated/tutorial.html
new file mode 100644
index 0000000..74602a8
--- /dev/null
+++ b/doc/html_generated/tutorial.html
@@ -0,0 +1,218 @@
+<!DOCTYPE html>
+<html>
+<title>tutorial</title>
+<xmp theme="united" style="display:none;">
+
+## Tutorial
+
+To get started with **doctest** all you need is to download the [**latest version**](https://raw.githubusercontent.com/onqtam/doctest/master/doctest/doctest.h) which is just a single header and include it in your source files (or add this repository as a git submodule).
+
+This tutorial assumes you can use the header directly: ```#include "doctest.h"``` - so it is either in the same folder with your test source files or you have set up the include paths to it in your build system properly.
+
+[TDD](https://en.wikipedia.org/wiki/Test-driven_development) is not discussed in this tutorial.
+
+## A simple example
+
+Suppose we have a ```factorial()``` function that we want to test:
+
+```
+int factorial(int number) { return number <= 1 ? number : factorial(number - 1) * number; }
+```
+
+A complete compiling example with a self-registering test looks like this:
+
+```
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include "doctest.h"
+
+int factorial(int number) { return number <= 1 ? number : factorial(number - 1) * number; }
+
+TEST_CASE("testing the factorial function") {
+ CHECK(factorial(1) == 1);
+ CHECK(factorial(2) == 2);
+ CHECK(factorial(3) == 6);
+ CHECK(factorial(10) == 3628800);
+}
+```
+
+This will compile to a complete executable which responds to command line arguments. If you just run it with no arguments it will execute all test cases (in this case - just one), report any failures, report a summary of how many tests passed and failed and returns 0 on success and 1 if anything failed (useful if you just want a yes/no answer to: "did it work").
+
+If you run this as written it will pass. Everything is good. Right? Well there is still a bug here. We missed to check if ```factorial(0) == 1``` so lets add that check as well:
+
+```
+TEST_CASE("testing the factorial function") {
+ CHECK(factorial(0) == 1);
+ CHECK(factorial(1) == 1);
+ CHECK(factorial(2) == 2);
+ CHECK(factorial(3) == 6);
+ CHECK(factorial(10) == 3628800);
+}
+```
+
+Now we get a failure - something like:
+
+```
+test.cpp(7) FAILED!
+ CHECK( factorial(0) == 1 )
+with expansion:
+ CHECK( 0 == 1 )
+```
+
+Note that we get the actual return value of ```factorial(0)``` printed for us (0) - even though we used a natural expression with the ```==``` operator. That let's us immediately see what the problem is.
+
+Let's change the factorial function to:
+
+```
+int factorial(int number) { return number > 1 ? factorial(number - 1) * number : 1; }
+```
+
+Now all the tests pass.
+
+Of course there are still more issues to do deal with. For example we'll hit problems when the return value starts to exceed the range of an int. With factorials that can happen quite quickly. You might want to add tests for such cases and decide how to handle them. We'll stop short of doing that here.
+
+## What did we do here?
+
+Although this was a simple test it's been enough to demonstrate a few things about how **doctest** is used.
+
+1. All we did was ```#define``` one identifier and ```#include``` one header and we got everything - even an implementation of ```main()``` that will respond to command line arguments. You can only use that ```#define``` in one source file for (hopefully) obvious reasons. Once you have more than one file with unit tests in you'll just ```#include "doctest.h"``` and go. Usually it's a good idea to have a dedicated implementation file that just has ```#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN``` and ```#include "doctest.h"```. You can also provide your own implementation of main and drive **doctest** yourself - see [**supplying your own ```main()```**](main.html).
+2. We introduce test cases with the ```TEST_CASE``` macro. It takes one argument - a free form test name (for more see [**Test cases and subcases**](testcases.html)). The test name doesn't have to be unique. You can run sets of tests by specifying a wildcarded test name or a tag expression. See the [**command line**](commandline.html) docs for more information on running tests.
+3. The name is just a string. We haven't had to declare a function or method - or explicitly register the test case anywhere. Behind the scenes a function with a generated name is defined for you and automatically registered using static registry classes. By abstracting the function name away we can name our tests without the constraints of identifier names.
+4. We write our individual test assertions using the ```CHECK()``` macro. Rather than a separate macro for each type of condition (equal, less than, greater than, etc.) we express the condition naturally using C++ syntax. Behind the scenes a simple expression template captures the left-hand-side and right-hand-side of the expression so we can display the values in our test report. There are other [**assertion macros**](assertions.html) not covered in this tutorial - but because of this technique the number of them is drastically reduced.
+
+## Test cases and subcases
+
+Most test frameworks have a class-based fixture mechanism - test cases map to methods on a class and common setup and teardown can be performed in ```setup()``` and ```teardown()``` methods (or constructor/ destructor in languages like C++ that support deterministic destruction).
+
+While **doctest** fully supports this way of working there are a few problems with the approach. In particular the way your code must be split up and the blunt granularity of it may cause problems. You can only have one setup/ teardown pair across a set of methods but sometimes you want slightly different setup in each method or you may even want several levels of setup (a concept which we will clarify later on in this tutorial). It was [**problems like these**](http://jamesnewkirk.typepad.com/posts/2007/09/why-you-should-.html) that led James Newkirk who led the team that built NUnit to start again from scratch and build [**xUnit**](http://jamesnewkirk.typepad.com/posts/2007/09/announcing-xuni.html)).
+
+**doctest** takes a different approach (to both NUnit and xUnit) that is a more natural fit for C++ and the C family of languages.
+
+This is best explained through an example:
+
+```
+TEST_CASE("vectors can be sized and resized") {
+ std::vector<int> v(5);
+
+ REQUIRE(v.size() == 5);
+ REQUIRE(v.capacity() >= 5);
+
+ SUBCASE("adding to the vector increases it's size") {
+ v.push_back(1);
+
+ CHECK(v.size() == 6);
+ CHECK(v.capacity() >= 6);
+ }
+ SUBCASE("reserving increases just the capacity") {
+ v.reserve(6);
+
+ CHECK(v.size() == 5);
+ CHECK(v.capacity() >= 6);
+ }
+}
+```
+
+For each ```SUBCASE()``` the ```TEST_CASE()``` is executed from the start - so as we enter each subcase we know that the size is 5 and the capacity is at least 5. We enforce those requirements with the ```REQUIRE()``` macros at the top level so we can be confident in them. If a ```CHECK()``` fails - the test is marked as failed but the execution continues - but if a ```REQUIRE()``` fails - execution of the test stops.
+
+This works because the ```SUBCASE()``` macro contains an if statement that calls back into **doctest** to see if the subcase should be executed. One leaf subcase is executed on each run through a ```TEST_CASE()```. The other subcases are skipped. Next time the next subcase is executed and so on until no new subcases are encountered.
+
+So far so good - this is already an improvement on the setup/teardown approach because now we see our setup code inline and use the stack. The power of subcases really shows when we start nesting them like in the example below:
+
+<table><tr><td>
+Code
+</td><td>
+Output
+</td></tr><tr><td>
+<pre lang="c++">
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include "doctest.h"
+
+#include <iostream>
+using namespace std;
+
+TEST_CASE("lots of nested subcases") {
+ cout << endl << "root" << endl;
+ SUBCASE("") {
+ cout << "1" << endl;
+ SUBCASE("") { cout << "1.1" << endl; }
+ }
+ SUBCASE("") {
+ cout << "2" << endl;
+ SUBCASE("") { cout << "2.1" << endl; }
+ SUBCASE("") {
+ cout << "2.2" << endl;
+ SUBCASE("") {
+ cout << "2.2.1" << endl;
+ SUBCASE("") { cout << "2.2.1.1" << endl; }
+ SUBCASE("") { cout << "2.2.1.2" << endl; }
+ }
+ }
+ SUBCASE("") { cout << "2.3" << endl; }
+ SUBCASE("") { cout << "2.4" << endl; }
+ }
+}
+</pre>
+</td><td>
+<pre lang="">
+root
+1
+1.1
+
+root
+2
+2.1
+
+root
+2
+2.2
+2.2.1
+2.2.1.1
+
+root
+2
+2.2
+2.2.1
+2.2.1.2
+
+root
+2
+2.3
+
+root
+2
+2.4
+</pre>
+</td></tr></table>
+
+Subcases can be nested to an arbitrary depth (limited only by your stack size). Each leaf subcase (a subcase that contains no nested subcases) will be executed exactly once on a separate path of execution from any other leaf subcase (so no leaf subcase can interfere with another). A fatal failure in a parent subcase will prevent nested subcases from running - but then that's the idea.
+
+You can check out how subcases are implemented in [**this example**](../../scripts/how_subcases_work/main.cpp#L1).
+
+## Scaling up
+
+To keep the tutorial simple we put all our code in a single file. This is fine to get started - and makes jumping into **doctest** even quicker and easier. This is not really the best approach when you start writing more real-world tests.
+
+The requirement is that the following block of code ([**or equivalent**](main.html)):
+
+```
+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
+#include "doctest.h"
+```
+
+appears in _exactly_ one translation unit (source file). Use as many additional source files as you need for your tests - partitioned however makes most sense for your way of working. Each additional file needs only to ```#include "doctest.h"``` - do not repeat the ```#define```!
+
+In fact it is usually a good idea to put the block with the ```#define``` in it's own source file.
+
+## Next steps
+
+This has been a brief introduction to get you up and running with **doctest** and to point out some of the key differences between **doctest** and other frameworks you may already be familiar with. This will get you going quite far already and you are now in a position to dive in and write some tests.
+
+Of course there is more to learn - see the ever-growing [**reference**](readme.html#reference) section for what's available.
+
+---------------
+
+[Home](readme.html#reference)
+
+
+</xmp>
+<script src="strapdown.js/strapdown.js"></script>
+</html>
diff --git a/doc/markdown/features.md b/doc/markdown/features.md
index 1d32ce2..016852a 100644
--- a/doc/markdown/features.md
+++ b/doc/markdown/features.md
@@ -38,14 +38,14 @@
- **very** light, unintrusive and portable - see the sections above - and also the [**benchmarks**](benchmarks.md)
- offers a way to remove **everything** testing-related from the binary with the [**```DOCTEST_CONFIG_DISABLE```**](configuration.md) macro
- tests are registered automatically - no need to add them to a collection manually
-- supports [**subcases**](testcases.md#subcases) for easy setup/teardown of tests (also supports the retro [**test fixtures**](testcases.md#test-fixtures) with classes)
+- supports [**subcases**](testcases.md) for easy setup/teardown of tests (also supports the retro [**test fixtures**](testcases.md#) with classes)
- output from all compilers on all platforms is the same - byte by byte
-- supports [**BDD style**](testcases.md##bdd-style-test-cases) tests
+- supports [**BDD style**](testcases.md) tests
- only one core [**assertion macro**](assertions.md) for comparisons - standard C++ operators are used for the comparison (less than, equal, greater than...) - yet the full expression is decomposed and left and right values of the expression are logged
-- assertion macros for [**exceptions**](assertions.md#exceptions) - if something should or shouldn't throw
+- assertion macros for [**exceptions**](assertions.md) - if something should or shouldn't throw
- floating point comparison support - see the [**```Approx()```**](assertions.md#floating-point-comparisons) helper
- powerful mechanism for [**stringification**](stringification.md) of user types
-- tests can be grouped in [**test suites**](testcases.md#test-suites)
+- tests can be grouped in [**test suites**](testcases.md)
- powerful [**command line**](commandline.md) with lots of options
- tests can be [**filtered**](commandline.md) based on their name/file/test suite using wildcards
- failures can (optionally) break into the debugger on Windows and Mac