docs for INI file format

Progress in #193

doc/doxygen-pages/config-files.h

@@ -0,0 +1,51 @@
+/* +---------------------------------------------------------------------------+
+   |                     Mobile Robot Programming Toolkit (MRPT)               |
+   |                          http://www.mrpt.org/                             |
+   |                                                                           |
+   | Copyright (c) 2005-2017, Individual contributors, see AUTHORS file        |
+   | See: http://www.mrpt.org/Authors - All rights reserved.                   |
+   | Released under BSD License. See details in http://www.mrpt.org/License    |
+   +---------------------------------------------------------------------------+ */
+
+/** \page config_file_format Configuration file format in MRPT
+ *
+
+# Description
+
+Plain text configuration files in MRPT follows a custom version of the [INI file](https://en.wikipedia.org/wiki/INI_file)
+standard format, comprising "sections", "properties" (or "keys") with associated "values" and, optionally, comments.
+
+The following C++ classes are provided to read and write such files:
+- mrpt::utils::CConfigFile: Access to physical files.
+- mrpt::utils::CConfigFileMemory: Wrapper around a configuration file "in memory", without an associated physical file.
+
+See also:
+- mrpt::utils::CConfigFileBase: The base, virtual class underlying the two classes above. Users normally
+   inkove the API exposed in this base class.
+- mrpt::utils::CConfigFilePrefixer: A proxy class to manipulate an object of the two classes above such
+   that all accesses to sections and/or properties are *mapped* to modified versions of their names.
+
+
+# Format specifications
+
+- There exists only one level of hierarchy, i.e. only "toplevel" sections exist, there is no support for nested sections.
+  A possible workaround to this limitation is using  mrpt::utils::CConfigFilePrefixer.
+- Sections are formatted like: `[section_name]`
+- Key/values pair follow the format: `key = value`. Whitespaces are ignored before and after the `=` sign, up to the 
+first non-blank character of the value.
+- API methods exist to read and write different elementary data types (`int`,`double`,`std::string`) and also 
+ vectors, matrices and even `enum`s.
+- Comments can be included in different formats:
+  - Lines starting with `;`. Example: `; Comment line`
+  - Lines starting with `#`. Example: `# Comment line`
+  - After a value, with `//`. Example: `key = value    // Explanation of this value`
+  - An exception to the rule above is hard-coded to allow URLs, e.g. `key = http://www.google.com` is not considered to contain a comment.
+- Preprocessor:
+  - Just like in C/C++, lines can be ended in a backslash (`\`) to mean "line continuation". [New in MRPT 1.5.0]
+
+# Examples
+
+There are dozens of examples in the subdirectory [MRPT/share/mrpt/config_files](https://github.com/MRPT/mrpt/tree/master/share/mrpt/config_files).
+
+*/
+

doc/doxygen-pages/mainPage_doc.h.in

@@ -3,7 +3,7 @@
    |                                                                           |
    |                          http://www.mrpt.org/                             |
    |                                                                           |
-   | Copyright (c) 2005-2012, MAPIR group, University of Malaga                |
+   | Copyright (c) 2005-2017, MAPIR group, University of Malaga                |
    | All rights reserved.                                                      |
    |                                                                           |
    | Redistribution and use in source and binary forms, with or without        |

libs/base/include/mrpt/utils/CConfigFile.h

@@ -22,6 +22,9 @@ namespace utils
 	  *   to the file at the destructor, and only if at least one write operation has been applied.
 	  *
 	  * Use base class `CConfigFileBase`'s methods `read_{int,float,double,string,...}()` and `write()` to actually read and write values.
+	  *
+	  * See: \ref config_file_format
+	  *
 	  * \ingroup mrpt_base_grp
 	  */
 	class BASE_IMPEXP CConfigFile : public CConfigFileBase

libs/base/include/mrpt/utils/CConfigFileBase.h

@@ -26,7 +26,9 @@ namespace utils
 
 	/** This class allows loading and storing values and vectors of different types from a configuration text, which can be implemented as a ".ini" file, a memory-stored string, etc...
 	  *   This is a virtual class, use only as a pointer to an implementation of one of the derived classes.
-		 * \ingroup mrpt_base_grp
+	  *
+	  * See: \ref config_file_format
+	  * \ingroup mrpt_base_grp
 	  */
 	class BASE_IMPEXP CConfigFileBase
 	{

libs/base/include/mrpt/utils/CConfigFileMemory.h

@@ -21,6 +21,8 @@ namespace utils
 	/** This class implements a config file-like interface over a memory-stored string list.
 	*
 	 * Use base class `CConfigFileBase`'s methods `read_{int,float,double,string,...}()` and `write()` to actually read and write values.
+	 *
+	 * See: \ref config_file_format
 	 * \ingroup mrpt_base_grp
 	  */
 	class BASE_IMPEXP CConfigFileMemory : public CConfigFileBase

libs/base/include/mrpt/utils/CConfigFilePrefixer.h

@@ -30,6 +30,7 @@ namespace utils
 	  *     s1_bar = /dev/ttyUSB0
 	  *   \endcode
 	  *
+	  * See: \ref config_file_format
 	  * \sa CConfigFileBase
 	  * \ingroup mrpt_base_grp
 	  */