lots off additions to docs and archetype stuff

[SVN r8063]

bad_error_eg.cpp

@@ -0,0 +1,11 @@
+#include <list>
+#include <algorithm>
+
+struct foo {
+  bool operator<(const foo&) const { return false; }
+};
+int main(int, char*[]) {
+  std::list<foo> v;
+  std::stable_sort(v.begin(), v.end());
+  return 0;
+}