docs: added Motivation section -- a placeholder for now

doc/src/content/motivation/_index.md

@@ -0,0 +1,17 @@
++++
+title = "Motivation"
+weight = 8
++++
+
+This section describes techniques currently used to report and handle failures
+in functions, it also shows why this techniques might be insufficient.
+
+If you just want to learn how to use Outcome library go straight to [Tutorial
+section](../tutorial).
+
+{{% notice note %}}
+Motivation section of this documentation is not complete yet.
+{{% /notice %}}
+
+
+{{% children description="true" depth="1" %}}

doc/src/content/motivation/exceptions.md

@@ -0,0 +1,31 @@
++++
+title = "Exceptions"
+description = "Exceptions with their good and bad sides."
+weight = 10
++++
+
+## Exceptions
+
+Exceptions are the default mechanism in C++ for reporting, propagating and
+processing the information about function failures. Their main advantage is
+the ability to describe the "success dependency" between functions: if you want to
+say that calling function `g()` depends on the successful execution of function `f()`,
+you just put `g()` below `f()` and that's it:
+
+```c++
+int a()
+{
+  f();
+  g();        // don't call g() and further if f() fails
+  return h(); // don't call h() if g() fails
+}
+```
+
+In the Standard C++ terms this means that `f()` is *sequenced before* `g()`. 
+This makes failure handling extremely easy: in a lot of cases you do not have
+to do anything.
+
+But there is also cost to be paid when using exceptions.
+
+This tutorial is in the process of being written. Once done we will explain in detail
+why it is sometimes beneficial not to use exceptions to signal failures.

doc/src/content/tutorial/result/try.md

@@ -8,7 +8,7 @@ tags = ["try"]
 In the implementation of function `print_half` we have seen the usage of the macro {{< api try OUTCOME_TRY >}}:
 
 ```c++
-OUTCOME_TRY (i, (BigInt::fromString(text)));
+OUTCOME_TRY (i, BigInt::fromString(text));
 ```
 
 The `OUTCOME_TRY` macro uses C macro overloading to select between two implementations based on the number of

doc/src/snippets/intro_example.cpp

@@ -37,7 +37,7 @@ auto process(const string& content) noexcept
 auto get_int_from_file(string_view path) noexcept
   -> outcome::result<int>
 {
-  OUTCOME_TRY(str, (read_data_from_file(path)));
+  OUTCOME_TRY(str, read_data_from_file(path));
   // if control gets here read_data_from_file() has succeeded
   return process(str);  // decltype(str) == string
 }

doc/src/snippets/using_result.cpp

@@ -125,7 +125,7 @@ outcome::result<void> print_half(const std::string& text)
   {
     if (r.error() == ConversionErrc::TooLong)     // #3
     {
-      OUTCOME_TRY (i, (BigInt::fromString(text)));// #4
+      OUTCOME_TRY (i, BigInt::fromString(text));  // #4
       std::cout << i.half() << std::endl;
     }
     else