Added some more docs
diff --git a/docs/command-line.md b/docs/command-line.md
index b94dc86..915286c 100644
--- a/docs/command-line.md
+++ b/docs/command-line.md
@@ -21,7 +21,7 @@
Test cases, wildcarded test cases, tags and tag expressions are all passed directly as arguments. Tags are distinguished by being enclosed in square brackets.
-If no test specs are supplied then all test cases, except "hidden" tests (tagged ```[hide]``` or, in the legacy case, prefixed by `'./'`) are run
+If no test specs are supplied then all test cases, except "hidden" tests (tagged ```[hide]```, ```[.]``` or, in the legacy case, prefixed by `'./'`) are run.
Specs must be enclosed in quotes if they contain spaces. If they do not contain spaces the quotes are optional.
diff --git a/docs/test-cases-and-sections.md b/docs/test-cases-and-sections.md
index 4fc3f6f..863d5fa 100644
--- a/docs/test-cases-and-sections.md
+++ b/docs/test-cases-and-sections.md
@@ -15,7 +15,22 @@
## Tags
--{placeholder for documentation of tags}-
+Tags allow an arbitrary number of additional strings to be associated with a test case. Test cases can be selected (for running, or just for listing) by tag - or even by an expression that combines several tags. At their most basic level they provide a simple way to group several related tests together.
+
+As an example - given the following test cases:
+
+ TEST_CASE( "A", "[widget]" ) { /* ... */ }
+ TEST_CASE( "B", "[widget]" ) { /* ... */ }
+ TEST_CASE( "C", "[gadget]" ) { /* ... */ }
+ TEST_CASE( "D", "[widget][gadget]" ) { /* ... */ }
+
+The tag expression, ```"[widget]"``` selects A, B & D. ```"[gadget]"``` selects C & D. ```"[widget][gadget]"``` selects just D and ```"[widget],[gadget]"``` selects all four test cases.
+
+For more detail on command line selection see [the command line docs](command-line.md#specifying-which-tests-to-run)
+
+A special tag name, ```[hide]``` causes test cases to be skipped from the default list (ie when no test cases have been explicitly selected through tag expressions or name wildcards). ```[.]``` is an alias for ```[hide]```.
+
+Tag names are not case sensitive.
## BDD-style test cases
diff --git a/docs/tutorial.md b/docs/tutorial.md
index 058167d..2d75dab 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -140,7 +140,82 @@
So far so good - this is already an improvement on the setup/ teardown approach because now we see our setup code inline and we can use the stack.
--{placeholder for documentation on nested sections}-
+The power of sections really shows, however, when we need to execute a sequence of, checked, operations. Continuing the vector example we might want to verify that after reserving a larger capacity, if we reserve smaller capacity (but still larger than the current size) then the capacity is not, in fact, changed. We can do that, naturally, like so:
+
+ SECTION( "reserving bigger changes capacity but not size" ) {
+ v.reserve( 10 );
+
+ REQUIRE( v.size() == 5 );
+ REQUIRE( v.capacity() >= 10 );
+
+ SECTION( "reserving smaller again does not change capacity" ) {
+ v.reserve( 7 );
+
+ REQUIRE( v.capacity() >= 10 );
+ }
+ }
+
+Sections can be nested to an arbitrary depth (limited only by your stack size). Each leaf section (i.e. a section that contains no nested sections) will be executed exactly once, on a separate path of execution from any other leaf section (so no leaf section can interfere with another). Obviously a failure in a parent section will prevent nested sections from running - but that's the idea.
+
+## BDD-Style
+
+If you name your test cases and sections appropriately you can achieve a BDD-style specification structure. This became such a useful way of working that first class support has been added to Catch. Scenarios can be specified using ```SCENARIO```, ```GIVEN```, ```WHEN``` and ```THEN``` macros, which map on to ```TEST_CASE```s and ```SECTION```s, respectively (for more details see [Test cases and sections](test-cases-and-sections.md)).
+
+The vector example can be adjusted to use these macros like so:
+
+```c++
+SCENARIO( "vectors can be sized and resized", "[vector]" ) {
+
+ GIVEN( "A vector with some items" ) {
+ std::vector<int> v( 5 );
+
+ REQUIRE( v.size() == 5 );
+ REQUIRE( v.capacity() >= 5 );
+
+ WHEN( "the size is increased" ) {
+ v.resize( 10 );
+
+ THEN( "the size and capacity change" ) {
+ REQUIRE( v.size() == 10 );
+ REQUIRE( v.capacity() >= 10 );
+ }
+ }
+ WHEN( "the size is reduced" ) {
+ v.resize( 0 );
+
+ THEN( "the size changes but not capacity" ) {
+ REQUIRE( v.size() == 0 );
+ REQUIRE( v.capacity() >= 5 );
+ }
+ }
+ WHEN( "more capacity is reserved" ) {
+ v.reserve( 10 );
+
+ THEN( "the capacity changes but not the size" ) {
+ REQUIRE( v.size() == 5 );
+ REQUIRE( v.capacity() >= 10 );
+ }
+ }
+ WHEN( "less capacity is reserved" ) {
+ v.reserve( 0 );
+
+ THEN( "neither size nor capacity are changed" ) {
+ REQUIRE( v.size() == 5 );
+ REQUIRE( v.capacity() >= 5 );
+ }
+ }
+ }
+}
+```
+
+A nice consequence of this is that when these tests are run the test names are reported like this:
+
+```
+Scenario: vectors can be sized and resized
+ Given: A vector with some items
+ When: more capacity is reserved
+ Then: the capacity changes but not the size
+```
## Next steps
For more specific information see the [Reference pages](reference-index.md)