diff --git a/doc/examples/arguments.cxx b/doc/examples/arguments.cxx
new file mode 100644
index 0000000..653bfd6
--- /dev/null
+++ b/doc/examples/arguments.cxx
@@ -0,0 +1,89 @@
+/*! @file
+
+    @id $Id$
+*/
+//       1         2         3         4         5         6         7         8
+// 45678901234567890123456789012345678901234567890123456789012345678901234567890
+
+#include <mrw/args>
+
+void test_func() {
+  std::cout<<"test parameter was given on command line"<<std::endl;
+}
+
+int main(int argc, char** argv) try {
+
+  // option variables
+  bool flag(false);
+  int r(5);
+  std::string txt("Hello World");
+  int x(0), y(0);
+
+  // bind and evaluate options
+#ifdef ARGS__OLD_PRE11_COMPILER
+  args::list options;
+  std::vector<std::shared_ptr<args::abstract_parameter> > params;
+  params.push_back(args::help());
+  params.push_back(args::exit());
+  options.push_back(args::declaration("h", "help", "show this help", params));
+  params.clear();
+  params.push_back(args::param(r, "number"));
+  options.push_back(args::declaration("r", "repeat", "number of repetitions",
+                                      params));
+  params.clear();
+  params.push_back(args::param(flag));
+  options.push_back(args::declaration("f", "flag", "check a flag", params));
+  params.clear();
+  params.push_back(args::param(txt, "text"));
+  options.push_back(args::declaration("t", "text", "pass a text", params));
+  params.clear();
+  params.push_back(args::param(x, "x"));
+  params.push_back(args::param(y, "y"));
+  options.push_back(args::declaration("c", "coord", "add some 2D coordinates",
+                                      params));
+  params.clear();
+  params.push_back(args::func(test_func));
+  options.push_back(args::declaration("",  "test",
+                                      "call test_func, no shortcut", params));
+  args::init(argc, argv, "This is an example for argument processing.",
+             options);
+#else
+  args::init(argc, argv,
+             "This is an example for argument processing. If the description "
+             "is very long, it is automatically splitted over several lines "
+             "and indented on each new line. Arguments may have several "
+             "parameters. Help is generated automatically from the argument "
+             "declaration. The argument declaration contains long and short "
+             "options and a list of parameters.",
+             {
+               {"h", "help", "show this help", {args::help(), args::exit()}},
+               {"r", "repeat", "number of repetitions",
+                   {args::param(r, "number")}},
+               {"f", "flag",
+                   "check a flag; this is a boolean, so it is false by "
+                   "default and true if the user specifies the flag on "
+                   "the command line", {args::param(flag)}},
+               {"t", "text", "pass a text", {args::param(txt, "text")}},
+               {"c", "coord",
+                   "add some 2D coordinates; this is an example on how "
+                   "you can add more than one parameter",
+                     {args::param(x, "x"), args::param(y, "y")}},
+               {"",  "test", "call test_func, no shortcut",
+                   {args::func(test_func)}},
+             },
+             "Returns a status of 0 on success and 1 on any error.");
+#endif
+  
+  // show the result
+  std::cout<<std::endl
+           <<"commandline is parsed, these are the settings now:"<<std::endl
+           <<"r           = "<<r<<std::endl
+           <<"flag        = "<<(flag?"yes":"no")<<std::endl
+           <<"txt         = "<<txt<<std::endl
+           <<"coordinates = "<<x<<", "<<y<<std::endl;
+  
+  return 0;
+ } catch (const std::exception& x) {
+  std::cerr<<"**** ERROR: "<<x.what()<<std::endl;
+  return 1;
+ }