Merge branch 'master' into croposp

src/libs/libtsioxx/doxygen.txt

@@ -79,6 +79,71 @@ for these objects is supported for reading from libdatrwxx input streams.
   \par \c cmdlinefiles.h:
     ts::sff::SFile and ts::sff::DFile and reading functions
 
+\section main_sub_usage Usage example
+\subsection main_subsub_usage_input Reading files
+When reading a complete set of files, we recommend to nevertheless implement
+the loop over all files in the main program.
+This allows for more flexibility handling different files differently (with
+respect to file format for example) and comes at almost no overhead.
+\code
+#include <tfxx/commandline.h>
+#include <tsioxx/cmdlinefiles.h>
+
+struct Options {
+  bool verbose;
+  std::string inputformat;
+}; // struct Options
+
+int main(int iargc, char* argv[])
+{
+
+  // define commandline options
+  using namespace tfxx::cmdline;
+  static Declare options[]= 
+  {
+    // 0: print help
+    {"help",arg_no,"-"},
+    // 1: verbose mode
+    {"verbose",arg_no,"-"},
+    // 2: default input file format
+    {"itype",arg_yes,"sff"},
+    {NULL}
+  };
+
+  // define command line keys for input files
+  static const char tracekey[]="t";
+  static const char formatkey[]="f";
+
+  // define commandline argument modifier keys
+  static const char* cmdlinekeys[]={tracekey, formatkey, 0};
+
+  // collect options from commandline
+  Commandline cmdline(iargc, argv, options);
+
+  Options opt;
+  opt.verbose=cmdline.optset(1);
+  opt.inputformat=cmdline.string_arg(2);
+  
+  // extract commandline arguments
+  TFXX_assert(cmdline.extra(), "missing input file");
+  tfxx::cmdline::Tparsed arguments=parse_cmdline(cmdline, cmdlinekeys);
+
+  ts::sff::TDFileList input_file_list;
+  tfxx::cmdline::Tparsed::const_iterator file=arguments.begin();
+  while (file != arguments.end())
+  {
+    std::string format=opt.inputformat;
+    if (file->haskey(formatkey))
+    {
+      format=file->value(formatkey);
+    }
+    input_file_list.push_back(ts::sff::readDSFF(*file, opt.verbose, 
+                                                tracekey, format));
+    ++file;
+  }
+} // main()
+\endcode
+
 \section main_history History
 
 These modules previously were implemented in libtsxx and libtfxx.