Include wiki content into a doc folder (#850)

* Copied Tutorial from Google Code wiki.

* Initial Home page

* Copied How To Parse A Document from Google Code wiki

* Updated How To Parse A Document (markdown)

* Updated How To Parse A Document (markdown)

* Updated How To Parse A Document (Old API) (markdown)

* Copied How To Emit YAML from Google Code wiki

* Copied Breaking Changes from Google Code wiki

* Copied Strings from Google Code wiki

* Updated Strings (markdown)

* Updated Home (markdown)

* Fix typo.

* Updated Breaking Changes (markdown)

* Updated How To Parse A Document (Old API) (markdown)

* Updated Breaking Changes (markdown)

* Move wiki content to docs/

* Improve markdown and add colored code syntax
Co-authored-by: Jesse Beder <jbeder+github@gmail.com>

docs/Breaking-Changes.md

+# The following is a list of breaking changes to yaml-cpp, by version #
+
+# New API #
+
+## HEAD ##
+
+_none_
+
+## 0.6.0 ##
+
+  * Requires C++11.
+
+## 0.5.3 ##
+
+_none_
+
+## 0.5.2 ##
+
+_none_
+
+## 0.5.1 ##
+
+  * `Node::clear` was replaced by `Node::reset`, which takes an optional node, similar to smart pointers.
+
+## 0.5.0 ##
+
+Initial version of the new API.
+
+# Old API #
+
+## 0.3.0 ##
+
+_none_
+
+## 0.2.7 ##
+
+  * `YAML::Binary` now takes `const unsigned char *` for the binary data (instead of `const char *`).
+
+## 0.2.6 ##
+
+  * `Node::GetType()` is now `Node::Type()`, and returns an enum `NodeType::value`, where:
+> > ` struct NodeType { enum value { Null, Scalar, Sequence, Map }; }; `
+  * `Node::GetTag()` is now `Node::Tag()`
+  * `Node::Identity()` is removed, and `Node::IsAlias()` and `Node::IsReferenced()` have been merged into `Node::IsAliased()`. The reason: there's no reason to distinguish an alias node from its anchor - whichever happens to be emitted first will be the anchor, and the rest will be aliases.
+  * `Node::Read<T>` is now `Node::to<T>`. This wasn't a documented function, so it shouldn't break anything.
+  * `Node`'s comparison operators (for example, `operator == (const Node&, const T&)`) have all been removed. These weren't documented either (they were just used for the tests), so this shouldn't break anything either.
+  * The emitter no longer produces the document start by default - if you want it, you can supply it with the manipulator `YAML::BeginDoc`.
+
+## 0.2.5 ##
+
+This wiki was started with v0.2.5.
\ No newline at end of file

docs/Home.md

+To learn how to use the library, see the [Tutorial](https://github.com/jbeder/yaml-cpp/wiki/Tutorial) and [How To Emit YAML](https://github.com/jbeder/yaml-cpp/wiki/How-To-Emit-YAML)

docs/How-To-Emit-YAML.md

+## Contents ##
+
+
+
+# Basic Emitting #
+
+The model for emitting YAML is `std::ostream` manipulators. A `YAML::Emitter` objects acts as an output stream, and its output can be retrieved through the `c_str()` function (as in `std::string`). For a simple example:
+
+```cpp
+#include "yaml-cpp/yaml.h"
+
+int main()
+{
+   YAML::Emitter out;
+   out << "Hello, World!";
+   
+   std::cout << "Here's the output YAML:\n" << out.c_str(); // prints "Hello, World!"
+   return 0;
+}
+```
+
+# Simple Lists and Maps #
+
+A `YAML::Emitter` object acts as a state machine, and we use manipulators to move it between states. Here's a simple sequence:
+
+```cpp
+YAML::Emitter out;
+out << YAML::BeginSeq;
+out << "eggs";
+out << "bread";
+out << "milk";
+out << YAML::EndSeq;
+```
+
+produces
+
+```yaml
+- eggs
+- bread
+- milk
+```
+
+A simple map:
+
+```cpp
+YAML::Emitter out;
+out << YAML::BeginMap;
+out << YAML::Key << "name";
+out << YAML::Value << "Ryan Braun";
+out << YAML::Key << "position";
+out << YAML::Value << "LF";
+out << YAML::EndMap;
+```
+
+produces
+
+```yaml
+name: Ryan Braun
+position: LF
+```
+
+These elements can, of course, be nested:
+
+```cpp
+YAML::Emitter out;
+out << YAML::BeginMap;
+out << YAML::Key << "name";
+out << YAML::Value << "Barack Obama";
+out << YAML::Key << "children";
+out << YAML::Value << YAML::BeginSeq << "Sasha" << "Malia" << YAML::EndSeq;
+out << YAML::EndMap;
+```
+
+produces
+
+```yaml
+name: Barack Obama
+children:
+  - Sasha
+  - Malia
+```
+
+# Using Manipulators #
+
+To deviate from standard formatting, you can use manipulators to modify the output format. For example,
+
+```cpp
+YAML::Emitter out;
+out << YAML::Literal << "A\n B\n  C";
+```
+
+produces
+
+```yaml
+|
+A
+ B
+  C
+```
+and
+
+```cpp
+YAML::Emitter out;
+out << YAML::Flow;
+out << YAML::BeginSeq << 2 << 3 << 5 << 7 << 11 << YAML::EndSeq;
+```
+
+produces
+
+```yaml
+[2, 3, 5, 7, 11]
+```
+
+Comments act like manipulators:
+
+```cpp
+YAML::Emitter out;
+out << YAML::BeginMap;
+out << YAML::Key << "method";
+out << YAML::Value << "least squares";
+out << YAML::Comment("should we change this method?");
+out << YAML::EndMap;
+```
+
+produces
+
+```yaml
+method: least squares  # should we change this method?
+```
+
+And so do aliases/anchors:
+
+```cpp
+YAML::Emitter out;
+out << YAML::BeginSeq;
+out << YAML::Anchor("fred");
+out << YAML::BeginMap;
+out << YAML::Key << "name" << YAML::Value << "Fred";
+out << YAML::Key << "age" << YAML::Value << "42";
+out << YAML::EndMap;
+out << YAML::Alias("fred");
+out << YAML::EndSeq;
+```
+
+produces
+
+```yaml
+- &fred
+  name: Fred
+  age: 42
+- *fred
+```
+
+# STL Containers, and Other Overloads #
+We overload `operator <<` for `std::vector`, `std::list`, and `std::map`, so you can write stuff like:
+
+```cpp
+std::vector <int> squares;
+squares.push_back(1);
+squares.push_back(4);
+squares.push_back(9);
+squares.push_back(16);
+
+std::map <std::string, int> ages;
+ages["Daniel"] = 26;
+ages["Jesse"] = 24;
+
+YAML::Emitter out;
+out << YAML::BeginSeq;
+out << YAML::Flow << squares;
+out << ages;
+out << YAML::EndSeq;
+```
+
+produces
+
+```yaml
+- [1, 4, 9, 16]
+-
+  Daniel: 26
+  Jesse: 24
+```
+
+Of course, you can overload `operator <<` for your own types:
+
+```cpp
+struct Vec3 { int x; int y; int z; };
+YAML::Emitter& operator << (YAML::Emitter& out, const Vec3& v) {
+	out << YAML::Flow;
+	out << YAML::BeginSeq << v.x << v.y << v.z << YAML::EndSeq;
+	return out;
+}
+```
+and it'll play nicely with everything else.
+
+# Using Existing Nodes #
+
+We also overload `operator << ` for `YAML::Node`s in both APIs, so you can output existing Nodes. Of course, Nodes in the old API are read-only, so it's tricky to emit them if you want to modify them. So use the new API!
+
+# Output Encoding #
+
+The output is always UTF-8. By default, yaml-cpp will output as much as it can without escaping any characters. If you want to restrict the output to ASCII, use the manipulator `YAML::EscapeNonAscii`:
+
+```cpp
+emitter.SetOutputCharset(YAML::EscapeNonAscii);
+```
+
+# Lifetime of Manipulators #
+
+Manipulators affect the **next** output item in the stream. If that item is a `BeginSeq` or `BeginMap`, the manipulator lasts until the corresponding `EndSeq` or `EndMap`. (However, within that sequence or map, you can override the manipulator locally, etc.; in effect, there's a "manipulator stack" behind the scenes.)
+
+If you want to permanently change a setting, there are global setters corresponding to each manipulator, e.g.:
+
+```cpp
+YAML::Emitter out;
+out.SetIndent(4);
+out.SetMapStyle(YAML::Flow);
+```
+
+# When Something Goes Wrong #
+
+If something goes wrong when you're emitting a document, it must be something like forgetting a `YAML::EndSeq`, or a misplaced `YAML::Key`. In this case, emitting silently fails (no more output is emitted) and an error flag is set. For example:
+
+```cpp
+YAML::Emitter out;
+assert(out.good());
+out << YAML::Key;
+assert(!out.good());
+std::cout << "Emitter error: " << out.GetLastError() << "\n";
+```
\ No newline at end of file

docs/How-To-Parse-A-Document-(Old-API).md

+_The following describes the old API. For the new API, see the [Tutorial](https://github.com/jbeder/yaml-cpp/wiki/Tutorial)._
+
+## Contents ##
+
+
+# Basic Parsing #
+
+The parser accepts streams, not file names, so you need to first load the file. Since a YAML file can contain many documents, you can grab them one-by-one. A simple way to parse a YAML file might be:
+
+```
+#include <fstream>
+#include "yaml-cpp/yaml.h"
+
+int main()
+{
+    std::ifstream fin("test.yaml");
+    YAML::Parser parser(fin);
+
+    YAML::Node doc;
+    while(parser.GetNextDocument(doc)) {
+       // ...
+    }
+
+    return 0;
+}
+```
+
+# Reading From the Document #
+
+Suppose we have a document consisting only of a scalar. We can read that scalar like this:
+
+```
+YAML::Node doc;    // let's say we've already parsed this document
+std::string scalar;
+doc >> scalar;
+std::cout << "That scalar was: " << scalar << std::endl;
+```
+
+How about sequences? Let's say our document now consists only of a sequences of scalars. We can use an iterator:
+
+```
+YAML::Node doc;    // already parsed
+for(YAML::Iterator it=doc.begin();it!=doc.end();++it) {
+    std::string scalar;
+    *it >> scalar;
+    std::cout << "Found scalar: " << scalar << std::endl;
+}
+```
+
+... or we can just loop through:
+
+```
+YAML::Node doc;    // already parsed
+for(unsigned i=0;i<doc.size();i++) {
+    std::string scalar;
+    doc[i] >> scalar;
+    std::cout << "Found scalar: " << scalar << std::endl;
+}
+```
+
+And finally maps. For now, let's say our document is a map with all keys/values being scalars. Again, we can iterate:
+
+```
+YAML::Node doc;    // already parsed
+for(YAML::Iterator it=doc.begin();it!=doc.end();++it) {
+    std::string key, value;
+    it.first() >> key;
+    it.second() >> value;
+    std::cout << "Key: " << key << ", value: " << value << std::endl;
+}
+```
+
+Note that dereferencing a map iterator is undefined; instead, use the `first` and `second` methods to get the key and value nodes, respectively.
+
+Alternatively, we can pick off the values one-by-one, if we know the keys:
+
+```
+YAML::Node doc;    // already parsed
+std::string name;
+doc["name"] >> name;
+int age;
+doc["age"] >> age;
+std::cout << "Found entry with name '" << name << "' and age '" << age << "'\n";
+```
+
+One thing to be keep in mind: reading a map by key (as immediately above) requires looping through all entries until we find the right key, which is an O(n) operation. So if you're reading the entire map this way, it'll be O(n^2). For small n, this isn't a big deal, but I wouldn't recommend reading maps with a very large number of entries (>100, say) this way.
+
+## Optional Keys ##
+
+If you try to access a key that doesn't exist, `yaml-cpp` throws an exception (see [When Something Goes Wrong](https://github.com/jbeder/yaml-cpp/wiki/How-To-Parse-A-Document-(Old-API)#When_Something_Goes_Wrong). If you have optional keys, it's often easier to use `FindValue` instead of `operator[]`:
+
+```
+YAML::Node doc;    // already parsed
+if(const YAML::Node *pName = doc.FindValue("name")) {
+    std::string name;
+    *pName >> name;
+    std::cout << "Key 'name' exists, with value '" << name << "'\n";
+} else {
+    std::cout << "Key 'name' doesn't exist\n";
+}
+```
+
+# Getting More Complicated #
+
+The above three methods can be combined to read from an arbitrary document. But we can make life a lot easier. Suppose we're reading 3-vectors (i.e., vectors with three components), so we've got a structure looking like this:
+
+```
+struct Vec3 {
+    float x, y, z;
+};
+```
+
+We can read this in one operation by overloading the extraction (>>) operator:
+
+```
+void operator >> (const YAML::Node& node, Vec3& v)
+{
+    node[0] >> v.x;
+    node[1] >> v.y;
+    node[2] >> v.z;
+}
+
+// now it's a piece of cake to read it
+YAML::Node doc;    // already parsed
+Vec3 v;
+doc >> v;
+std::cout << "Here's the vector: (" << v.x << ", " << v.y << ", " << v.z << ")\n";
+```
+
+# A Complete Example #
+
+Here's a complete example of how to parse a complex YAML file:
+
+`monsters.yaml`
+
+```
+- name: Ogre
+  position: [0, 5, 0]
+  powers:
+    - name: Club
+      damage: 10
+    - name: Fist
+      damage: 8
+- name: Dragon
+  position: [1, 0, 10]
+  powers:
+    - name: Fire Breath
+      damage: 25
+    - name: Claws
+      damage: 15
+- name: Wizard
+  position: [5, -3, 0]
+  powers:
+    - name: Acid Rain
+      damage: 50
+    - name: Staff
+      damage: 3
+```
+
+`main.cpp`
+
+```
+#include "yaml-cpp/yaml.h"
+#include <iostream>
+#include <fstream>
+#include <string>
+#include <vector>
+
+// our data types
+struct Vec3 {
+   float x, y, z;
+};
+
+struct Power {
+   std::string name;
+   int damage;
+};
+
+struct Monster {
+   std::string name;
+   Vec3 position;
+   std::vector <Power> powers;
+};
+
+// now the extraction operators for these types
+void operator >> (const YAML::Node& node, Vec3& v) {
+   node[0] >> v.x;
+   node[1] >> v.y;
+   node[2] >> v.z;
+}
+
+void operator >> (const YAML::Node& node, Power& power) {
+   node["name"] >> power.name;
+   node["damage"] >> power.damage;
+}
+
+void operator >> (const YAML::Node& node, Monster& monster) {
+   node["name"] >> monster.name;
+   node["position"] >> monster.position;
+   const YAML::Node& powers = node["powers"];
+   for(unsigned i=0;i<powers.size();i++) {
+      Power power;
+      powers[i] >> power;
+      monster.powers.push_back(power);
+   }
+}
+
+int main()
+{
+   std::ifstream fin("monsters.yaml");
+   YAML::Parser parser(fin);
+   YAML::Node doc;
+   parser.GetNextDocument(doc);
+   for(unsigned i=0;i<doc.size();i++) {
+      Monster monster;
+      doc[i] >> monster;
+      std::cout << monster.name << "\n";
+   }
+
+   return 0;
+}
+```
+
+# When Something Goes Wrong #
+
+... we throw an exception (all exceptions are derived from `YAML::Exception`). If there's a parsing exception (i.e., a malformed YAML document), we throw a `YAML::ParserException`:
+
+```
+try {
+    std::ifstream fin("test.yaml");
+    YAML::Parser parser(fin);
+    YAML::Node doc;
+    parser.GetNextDocument(doc);
+    // do stuff
+} catch(YAML::ParserException& e) {
+    std::cout << e.what() << "\n";
+}
+```
+
+If you make a programming error (say, trying to read a scalar from a sequence node, or grabbing a key that doesn't exist), we throw some kind of `YAML::RepresentationException`. To prevent this, you can check what kind of node something is:
+
+```
+    YAML::Node node;
+    YAML::NodeType::value type = node.Type();  // should be:
+                                               // YAML::NodeType::Null
+                                               // YAML::NodeType::Scalar
+                                               // YAML::NodeType::Sequence
+                                               // YAML::NodeType::Map
+```
+
+# Note about copying `YAML::Node` #
+
+Currently `YAML::Node` is non-copyable, so you need to do something like
+
+```
+    const YAML::Node& node = doc["whatever"];
+```
+
+This is intended behavior. If you want to copy a node, use the `Clone` function:
+
+```
+    std::auto_ptr<YAML::Node> pCopy = myOtherNode.Clone();
+```
+
+The intent is that if you'd like to keep a `YAML::Node` around for longer than the document will stay in scope, you can clone it and store it as long as you like.
\ No newline at end of file

docs/Strings.md

+# Encodings and `yaml-cpp` #
+
+`yaml-cpp` will parse any file as specificed by the [YAML 1.2 spec](http://www.yaml.org/spec/1.2/spec.html#id2570322). Internally, it stores all strings in UTF-8, and representation is done with UTF-8. This means that in
+
+```
+std::string str;
+node >> str;
+```
+
+`str` will be UTF-8. Similarly, if you're accessing a map by string key, you need to pass the key in UTF-8. If your application uses a different encoding, you need to convert to and from UTF-8 to work with `yaml-cpp`. (It's possible we'll add some small conversion functions, but for now it's restricted.)
+
+---
+
+For convenience, Richard Weeks has kindly provided a google gadget that converts Unicode to a string literal. It's a Google Gadget, so unfortunately it does not work on GitHub. Patches welcome to port it to a usable format here:
+
+```
+<wiki:gadget url="http://hosting.gmodules.com/ig/gadgets/file/111180078345548400783/c-style-utf8-encoder.xml"/>
+```
\ No newline at end of file

docs/Tutorial.md

+# Introduction #
+
+A typical example, loading a configuration file, might look like this:
+
+```cpp
+YAML::Node config = YAML::LoadFile("config.yaml");
+
+if (config["lastLogin"]) {
+  std::cout << "Last logged in: " << config["lastLogin"].as<DateTime>() << "\n";
+}
+
+const std::string username = config["username"].as<std::string>();
+const std::string password = config["password"].as<std::string>();
+login(username, password);
+config["lastLogin"] = getCurrentDateTime();
+
+std::ofstream fout("config.yaml");
+fout << config;
+```
+
+# Basic Parsing and Node Editing #
+
+All nodes in a YAML document (including the root) are represented by `YAML::Node`. You can check what kind it is:
+
+```cpp
+YAML::Node node = YAML::Load("[1, 2, 3]");
+assert(node.Type() == YAML::NodeType::Sequence);
+assert(node.IsSequence());  // a shortcut!
+```
+
+Collection nodes (sequences and maps) act somewhat like STL vectors and maps:
+
+```cpp
+YAML::Node primes = YAML::Load("[2, 3, 5, 7, 11]");
+for (std::size_t i=0;i<primes.size();i++) {
+  std::cout << primes[i].as<int>() << "\n";
+}
+// or:
+for (YAML::const_iterator it=primes.begin();it!=primes.end();++it) {
+  std::cout << it->as<int>() << "\n";
+}
+
+primes.push_back(13);
+assert(primes.size() == 6);
+```
+
+and
+
+```cpp
+YAML::Node lineup = YAML::Load("{1B: Prince Fielder, 2B: Rickie Weeks, LF: Ryan Braun}");
+for(YAML::const_iterator it=lineup.begin();it!=lineup.end();++it) {
+  std::cout << "Playing at " << it->first.as<std::string>() << " is " << it->second.as<std::string>() << "\n";
+}
+
+lineup["RF"] = "Corey Hart";
+lineup["C"] = "Jonathan Lucroy";
+assert(lineup.size() == 5);
+```
+
+Querying for keys does **not** create them automatically (this makes handling optional map entries very easy)
+
+```cpp
+YAML::Node node = YAML::Load("{name: Brewers, city: Milwaukee}");
+if (node["name"]) {
+  std::cout << node["name"].as<std::string>() << "\n";
+}
+if (node["mascot"]) {
+  std::cout << node["mascot"].as<std::string>() << "\n";
+}
+assert(node.size() == 2); // the previous call didn't create a node
+```
+
+If you're not sure what kind of data you're getting, you can query the type of a node:
+
+```cpp
+switch (node.Type()) {
+  case Null: // ...
+  case Scalar: // ...
+  case Sequence: // ...
+  case Map: // ...
+  case Undefined: // ...
+}
+```
+
+or ask directly whether it's a particular type, e.g.:
+
+```cpp
+if (node.IsSequence()) {
+  // ...
+}
+```
+
+# Building Nodes #
+
+You can build `YAML::Node` from scratch:
+
+```cpp
+YAML::Node node;  // starts out as null
+node["key"] = "value";  // it now is a map node
+node["seq"].push_back("first element");  // node["seq"] automatically becomes a sequence
+node["seq"].push_back("second element");
+
+node["mirror"] = node["seq"][0];  // this creates an alias
+node["seq"][0] = "1st element";  // this also changes node["mirror"]
+node["mirror"] = "element #1";  // and this changes node["seq"][0] - they're really the "same" node
+
+node["self"] = node;  // you can even create self-aliases
+node[node["mirror"]] = node["seq"];  // and strange loops :)
+```
+
+The above node is now:
+
+```yaml
+&1
+key: value
+&2 seq: [&3 "element #1", second element]
+mirror: *3
+self: *1
+*3 : *2
+```
+
+# How Sequences Turn Into Maps #
+
+Sequences can be turned into maps by asking for non-integer keys. For example,
+
+```cpp
+YAML::Node node  = YAML::Load("[1, 2, 3]");
+node[1] = 5;  // still a sequence, [1, 5, 3]
+node.push_back(-3) // still a sequence, [1, 5, 3, -3]
+node["key"] = "value"; // now it's a map! {0: 1, 1: 5, 2: 3, 3: -3, key: value}
+```
+
+Indexing a sequence node by an index that's not in its range will _usually_ turn it into a map, but if the index is one past the end of the sequence, then the sequence will grow by one to accommodate it. (That's the **only** exception to this rule.) For example,
+
+```cpp
+YAML::Node node = YAML::Load("[1, 2, 3]");
+node[3] = 4; // still a sequence, [1, 2, 3, 4]
+node[10] = 10;  // now it's a map! {0: 1, 1: 2, 2: 3, 3: 4, 10: 10}
+```
+
+# Converting To/From Native Data Types #
+
+Yaml-cpp has built-in conversion to and from most built-in data types, as well as `std::vector`, `std::list`, and `std::map`. The following examples demonstrate when those conversions are used:
+
+```cpp
+YAML::Node node = YAML::Load("{pi: 3.14159, [0, 1]: integers}");
+
+// this needs the conversion from Node to double
+double pi = node["pi"].as<double>();
+
+// this needs the conversion from double to Node
+node["e"] = 2.71828;
+
+// this needs the conversion from Node to std::vector<int> (*not* the other way around!)
+std::vector<int> v;
+v.push_back(0);
+v.push_back(1);
+std::string str = node[v].as<std::string>();
+```
+
+To use yaml-cpp with your own data types, you need to specialize the YAML::convert<> template class. For example, suppose you had a simple `Vec3` class:
+
+```cpp
+struct Vec3 { double x, y, z; /* etc - make sure you have overloaded operator== */ };
+```
+
+You could write
+
+```cpp
+namespace YAML {
+template<>
+struct convert<Vec3> {
+  static Node encode(const Vec3& rhs) {
+    Node node;
+    node.push_back(rhs.x);
+    node.push_back(rhs.y);
+    node.push_back(rhs.z);
+    return node;
+  }
+
+  static bool decode(const Node& node, Vec3& rhs) {
+    if(!node.IsSequence() || node.size() != 3) {
+      return false;
+    }
+
+    rhs.x = node[0].as<double>();
+    rhs.y = node[1].as<double>();
+    rhs.z = node[2].as<double>();
+    return true;
+  }
+};
+}
+```
+
+Then you could use `Vec3` wherever you could use any other type:
+
+```cpp
+YAML::Node node = YAML::Load("start: [1, 3, 0]");
+Vec3 v = node["start"].as<Vec3>();
+node["end"] = Vec3(2, -1, 0);
+```
\ No newline at end of file