Squashed 'third_party/boostorg/property_tree/' content from commit bdfe275
Change-Id: I075a5e242aaddc356ecc81e756c4a0907fc38130
git-subtree-dir: third_party/boostorg/property_tree
git-subtree-split: bdfe275d172ac30bc5e89a6375a5a64dea20b3c0
diff --git a/doc/ini_parser.qbk b/doc/ini_parser.qbk
new file mode 100644
index 0000000..560817a
--- /dev/null
+++ b/doc/ini_parser.qbk
@@ -0,0 +1,37 @@
+[/
+ / Copyright (c) 2008 Marcin Kalicinski (kalita <at> poczta dot onet dot pl)
+ / Copyright (c) 2009 Sebastian Redl (sebastian dot redl <at> getdesigned dot at)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+[section INI Parser]
+[def __ini__ [@http://en.wikipedia.org/wiki/INI INI format]]
+The __ini__ was once widely used in the world of Windows. It is now deprecated,
+but is still used by a surprisingly large number of applications. The reason is
+probably its simplicity, plus that Microsoft recommends using the registry as
+a replacement, which not all developers want to do.
+
+INI is a simple key-value format with a single level of sectioning. It is thus
+less rich than the property tree dataset, which means that not all property
+trees can be serialized as INI files.
+
+The INI parser creates a tree node for every section, and a child node for
+every property in that section. All properties not in a section are directly
+added to the root node. Empty sections are ignored. (They don't round-trip, as
+described below.)
+
+The INI serializer reverses this process. It first writes out every child of the
+root that contains data, but no child nodes, as properties. Then it creates a
+section for every child that contains child nodes, but no data. The children of
+the sections must only contain data. It is an error if the root node contains
+data, or any child of the root contains both data and content, or there's more
+than three levels of hierarchy. There must also not be any duplicate keys.
+
+An empty tree node is assumed to be an empty property. There is no way to create
+empty sections.
+
+Since the Windows INI parser discards trailing spaces and does not support
+quoting, the property tree parser follows this example. This means that
+property values containing trailing spaces do not round-trip.
+[endsect] [/ini_parser]