From e0a66de87d135a5f8acde048219cb0c1510d5df1 Mon Sep 17 00:00:00 2001
From: Irvin Cardoza <86453572+irvincardoza@users.noreply.github.com>
Date: Mon, 9 Dec 2024 12:55:36 -0800
Subject: [PATCH 1/4] Create Clara.md

created docs of Clara inside, fixing issue #2312
---
 docs/Clara.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 docs/Clara.md

diff --git a/docs/Clara.md b/docs/Clara.md
new file mode 100644
index 0000000000..8c4af7a505
--- /dev/null
+++ b/docs/Clara.md
@@ -0,0 +1,101 @@
+# Clara v1.1.5
+[![Build Status](https://travis-ci.org/catchorg/Clara.svg?branch=master)](https://travis-ci.org/catchorg/Clara)
+[![Build status](https://ci.appveyor.com/api/projects/status/github/catchorg/Clara?brach=master&svg=true)](https://ci.appveyor.com/project/catchorg/clara)
+[![codecov](https://codecov.io/gh/catchorg/Clara/branch/master/graph/badge.svg)](https://codecov.io/gh/catchorg/Clara)
+
+-----------------------------
+
+
+A simple to use, composable, command line parser for C++ 11 and beyond.
+
+Clara is a single-header library.
+
+To use, just `#include "clara.hpp"`
+
+A parser for a single option can be created like this:
+
+```c++
+int width = 0;
+// ...
+using namespace clara;
+auto cli
+    = Opt( width, "width" )
+        ["-w"]["--width"]
+        ("How wide should it be?");
+```
+
+You can use this parser directly like this:
+
+```c++
+auto result = cli.parse( Args( argc, argv ) );
+if( !result ) {
+    std::cerr << "Error in command line: " << result.errorMessage() << std::endl;
+    exit(1);
+}
+
+// Everything was ok, width will have a value if supplied on command line
+```
+
+Note that exceptions are not used for error handling.
+
+You can combine parsers by composing with `|`, like this:
+
+```c++
+int width = 0;
+std::string name;
+bool doIt = false;
+std::string command;
+auto cli
+    = Opt( width, "width" )
+        ["-w"]["--width"]
+        ("How wide should it be?")
+    | Opt( name, "name" )
+        ["-n"]["--name"]
+        ("By what name should I be known")
+    | Opt( doIt )
+        ["-d"]["--doit"]
+        ("Do the thing" )
+    | Arg( command, "command" )
+        ("which command to run");
+```
+
+`Opt`s specify options that start with a short dash (`-`) or long dash (`--`).
+On Windows forward slashes are also accepted (and automatically interpretted as a short dash).
+Options can be argument taking (such as `-w 42`), in which case the `Opt` takes a second argument - a hint,
+or they are pure flags (such as `-d`), in which case the `Opt` has only one argument - which must be a boolean.
+The option names are provided in one or more sets of square brackets, and a description string can
+be provided in parentheses. The first argument to an `Opt` is any variable, local, global member, of any type
+that can be converted from a string using `std::ostream`.
+
+`Arg`s specify arguments that are not tied to options, and so have no square bracket names. They otherwise work just like `Opt`s.
+
+A, console optimised, usage string can be obtained by inserting the parser into a stream.
+The usage string is built from the information supplied and is formatted for the console width.
+
+As a convenience, the standard help options (`-h`, `--help` and `-?`) can be specified using the `Help` parser,
+which just takes a boolean to bind to.
+
+For more usage please see the unit tests or look at how it is used in the Catch code-base (catch-lib.net).
+Fuller documentation will be coming soon.
+
+Some of the key features:
+
+- A single header file with no external dependencies (except the std library).
+- Define your interface once to get parsing, type conversions and usage strings with no redundancy.
+- Composable. Each `Opt` or `Arg` is an independent parser. Combine these to produce a composite parser - this can be done in stages across multiple function calls - or even projects.
+- Bind parsers directly to variables that will receive the results of the parse - no intermediate dictionaries to worry about.
+- Or can also bind parsers to lambdas for more custom handling.
+- Deduces types from bound variables or lambdas and performs type conversions (via `ostream <<`), with error handling, behind the scenes.
+- Bind parsers to vectors for args that can have multiple values.
+- Uses Result types for error propagation, rather than exceptions (doesn't yet build with exceptions disabled, but that will be coming later)
+- Models POSIX standards for short and long opt behaviour.
+
+
+## Old version
+
+If you used the earlier, v0.x, version of Clara please note that this is a complete rewrite which assumes C++11 and has
+a different interface (composability was a big step forward). Conversion between v0.x and v1.x is a fairly simple and mechanical task, but is a bit of manual
+work - so don't take this version until you're ready (and, of course, able to use C++11).
+
+I hope you'll find the new interface an improvement - and this will be built on to offer new features moving forwards.
+I don't expect to maintain v0.x any further, but it remains on a branch.

From 866d4f9eabee4baa22a1c5951d9457253865b65c Mon Sep 17 00:00:00 2001
From: Irvin Cardoza <86453572+irvincardoza@users.noreply.github.com>
Date: Mon, 9 Dec 2024 12:59:41 -0800
Subject: [PATCH 2/4] Update own-main.md

updated Clara docs with link to new docs inside the catch documentation itself. Fixing issue #2312
---
 docs/own-main.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/own-main.md b/docs/own-main.md
index 26dfa86da6..dbae178a8b 100644
--- a/docs/own-main.md
+++ b/docs/own-main.md
@@ -110,7 +110,7 @@ int main( int argc, char* argv[] ) {
 }
 ```
 
-See the [Clara documentation](https://github.com/catchorg/Clara/blob/master/README.md)
+See the [Clara documentation](https://github.com/irvincardoza/Catch2/blob/devel/docs/Clara.md)
 for more details on how to use the Clara parser.
 
 

From 6f83f210d90b1e43d0e5216882bf0344a2e23255 Mon Sep 17 00:00:00 2001
From: Irvin Cardoza <86453572+irvincardoza@users.noreply.github.com>
Date: Tue, 31 Dec 2024 19:58:16 +0000
Subject: [PATCH 3/4] removed required changes

---
 docs/Clara.md | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/docs/Clara.md b/docs/Clara.md
index 8c4af7a505..f5bae7a8f9 100644
--- a/docs/Clara.md
+++ b/docs/Clara.md
@@ -1,16 +1,9 @@
 # Clara v1.1.5
-[![Build Status](https://travis-ci.org/catchorg/Clara.svg?branch=master)](https://travis-ci.org/catchorg/Clara)
-[![Build status](https://ci.appveyor.com/api/projects/status/github/catchorg/Clara?brach=master&svg=true)](https://ci.appveyor.com/project/catchorg/clara)
-[![codecov](https://codecov.io/gh/catchorg/Clara/branch/master/graph/badge.svg)](https://codecov.io/gh/catchorg/Clara)
-
------------------------------
 
 
 A simple to use, composable, command line parser for C++ 11 and beyond.
 
-Clara is a single-header library.
 
-To use, just `#include "clara.hpp"`
 
 A parser for a single option can be created like this:
 

From f64178348a4c3533571e3990b5e421d20947cabc Mon Sep 17 00:00:00 2001
From: Irvin Cardoza <86453572+irvincardoza@users.noreply.github.com>
Date: Tue, 31 Dec 2024 20:01:55 +0000
Subject: [PATCH 4/4] relinked to new file clara.md

---
 docs/own-main.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/own-main.md b/docs/own-main.md
index dbae178a8b..1e864a6cf9 100644
--- a/docs/own-main.md
+++ b/docs/own-main.md
@@ -110,7 +110,7 @@ int main( int argc, char* argv[] ) {
 }
 ```
 
-See the [Clara documentation](https://github.com/irvincardoza/Catch2/blob/devel/docs/Clara.md)
+See the [Clara documentation](https://github.com/catchorg/Catch2/blob/devel/docs/Clara.md)
 for more details on how to use the Clara parser.