Nicer readme after meeting

Henry Fredrick Schreiner
1 parent 3b6def13
Showing 1 changed file with 34 additions and 22 deletions
README.md
@@ -3,32 +3,42 @@
 # CLI11
  
 CLI11 provides all the features you expect in a powerful command line parser, with a beautiful, minimal syntax and no dependencies beyond C++11. It is header only, and comes in a single file form for easy inclusion in projects. It is easy to use for small projects, but powerful enough for complex command line projects, and can be customized for frameworks.
-It is tested on Travis with a suite of tests, and is being included in the [GooFit GPU fitting framework](https://github.com/GooFit/GooFit). It was inspired by [`plumbum.cli`](http://plumbum.readthedocs.io/en/latest/) for Python.
+It is tested on [Travis with a suite of tests](https://travis-ci.org/henryiii/CLI11), and is being included in the [GooFit GPU fitting framework](https://github.com/GooFit/GooFit). It was inspired by [`plumbum.cli`](http://plumbum.readthedocs.io/en/latest/) for Python. It has both a user friendly introduction here, as well as [API documentation](https://henryiii.github.io/CLI11/index.html) generated by Travis.
  
 ### Why write another CLI parser?
  
-The following attributes are what I believe are important in a CLI parser library:
+An acceptable CLI parser library should be all of the following:
  
 * Easy to include (i.e., header only, one file if possible, no external requirements): While many programs depend on Boost, that should not be a requirement if all you want is CLI parsing.
 * Short Syntax: This is one of the main points of a CLI parser, it should make variables from the command line nearly as easy to define as any other variables. If most of your program is hidden in CLI parsing, this is a problem for readability.
-* Work with GCC 4.7+ (such as GCC 4.8 on CentOS 7) or above, or Clang 3.5+. (3.4 only fails because of tests, googlemock does not support it.) Works on Linux and MacOS.
+* C++11 or better: Should work with GCC 4.7+ (such as GCC 4.8 on CentOS 7) or above, or Clang 3.5+. (Note: for CLI11, Clang 3.4 only fails because of tests, googlemock does not support it.)
+* Work at least on Linux and MacOS.
 * Well tested using Travis.
-* Good help printing (in progress).
-* Standard idioms supported naturally, like grouping flags, the positional separator, etc.
+* Clear help printing.
+* Standard shell idioms supported naturally, like grouping flags, a positional separator, etc.
 * Easy to execute, with help, parse errors, etc. providing correct exit and details.
-* Easy to extend as part of a framework that provides "applications".
-* Human readable support for subcommands.
-* Produce real values that can be used directly in code, not something you have pay compute time to look up.
+* Easy to extend as part of a framework that provides "applications" to users.
+* Usable subcommands.
+* Produce real values that can be used directly in code, not something you have pay compute time to look up, for HPC applications.
  
-The major CLI parsers out there include:
+The major CLI parsers for C++ include:
  
-* [Boost Program Options](http://www.boost.org/doc/libs/1_63_0/doc/html/program_options.html): A great library if you already depend on Boost, its pre-C++11 syntax is really odd and setting up the correct call in the main function is poorly documented. A simple wrapper for the Boost library (Program.hpp) was originally developed, but has been discarded in favor of CLI11.
-* [The Lean Mean C++ Option Parser](http://optionparser.sourceforge.net): One header file is great, but the syntax is atrocious, IMO.
-* [TCLAP](http://tclap.sourceforge.net): Not quite standard command line parsing, seems to not be well supported anymore. Header only, but in quite a few files. Not even moved to GitHub yet.
-* [Cxxopts](https://github.com/jarro2783/cxxopts): C++ 11, single file, and nice CMake support, but requires regex, therefore GCC 4.8 (CentOS 7 default) does not work. Syntax closely based on Boost PO, so not ideal but familiar.
+* [Boost Program Options](http://www.boost.org/doc/libs/1_63_0/doc/html/program_options.html): A great library if you already depend on Boost, but its pre-C++11 syntax is really odd and setting up the correct call in the main function is poorly documented (and is nearly a page of code). A simple wrapper for the Boost library was originally developed, but was discarded as CLI11 became more powerful. The idea of capturing a value and setting it originated with Boost PO.
+* [The Lean Mean C++ Option Parser](http://optionparser.sourceforge.net): One header file is great, but the syntax is atrocious, in my opinion. It was quite impractical to wrap the syntax or to use in a complex project. It seems to handle standard parsing quite well.
+* [TCLAP](http://tclap.sourceforge.net): The not-quite-standard command line parsing causes common shortcuts to fail. It also seems to be poorly supported, with only minimal bugfixes accepted. Header only, but in quite a few files. Has not managed to get enough support to move to GitHub yet. No subcommands. Produced wrapped values.
+* [Cxxopts](https://github.com/jarro2783/cxxopts): C++11, single file, and nice CMake support, but requires regex, therefore GCC 4.8 (CentOS 7 default) does not work. Syntax closely based on Boost PO, so not ideal but familiar.
  
 So, this library was designed to provide a great syntax, good compiler compatibility, and minimal installation fuss.
  
+## Current status:
+
+This library was built to supply the Application object for the GooFit CUDA/OMP fitting library. Before version 2.0 of GooFit is released, this library will reach version 1.0 status. The current tasks still planned are:
+
+* Expand tests to include a few more features
+* Improve documentation
+* Collect user feedback
+* Evaluate compatibility with [ROOT](https://root.cern.ch)'s TApplication object.
+
 ## Installing
  
 To use, there are two methods:
@@ -36,7 +46,7 @@ To use, there are two methods:
 1. Copy `CLI11.hpp` from the [most recent release](https://github.com/henryiii/CLI11/releases) into your include directory, and you are set. This is combined from the source files  for every release.
 2. Checkout the repository and add as a subdirectory for CMake. You can use the CLI interface target. (CMake 3.4+ recommended)
  
-To build the tests, get the entire directory and use CMake:
+To build the tests, checkout the repository and use CMake:
  
 ```bash
 mkdir build
@@ -67,7 +77,7 @@ The initialization is just one line, adding options is just two each. The try/ca
  
 The supported values are:
  
-```
+```cpp
 app.add_options(option_name,
                 variable_to_bind_to, // int, float, vector, or string-like
                 help_string="",
@@ -92,7 +102,7 @@ App* subcom = app.add_subcommand(name, discription);
  
 ```
  
-An option name must start with a alphabetic character or underscore. For long options, anything but an equals sign or a comma is valid after that. Names are given as a comma separated string, with the dash or dashes. An option or flag can have as many names as you want, and afterward, using `count`, you can use any of the names, with dashes as needed, to count the options. One of the names is allowed to be given without proceeding dash(es); if present the option is a positional option, and that name will be used on help line for its positional form.
+An option name must start with a alphabetic character or underscore. For long options, anything but an equals sign or a comma is valid after that. Names are given as a comma separated string, with the dash or dashes. An option or flag can have as many names as you want, and afterward, using `count`, you can use any of the names, with dashes as needed, to count the options. One of the names is allowed to be given without proceeding dash(es); if present the option is a positional option, and that name will be used on help line for its positional form. If you want the default value to print in the help description, pass in `true` for the final parameter for `add_option` or `add_set`.
  
 Adding a configuration option is special. If it is present, it will be read along with the normal command line arguments. The file will be read if it exists, and does not throw an error unless required is `true`.
  
@@ -103,7 +113,7 @@ Adding a configuration option is special. If it is present, it will be read alon
 > * `"-a,-b,-c"` No limit to the number of non-positional option names
  
  
-The add commands return a pointer to an internally stored `Option`. If you set the final argument to true, the default value is captured and printed on the command line with the help flag. This option can be used direcly to check for the count (`->count()`) after parsing to avoid a string based lookup. Before parsing, you can set the following options:
+The add commands return a pointer to an internally stored `Option`. If you set the final argument to true, the default value is captured and printed on the command line with the help flag. This option can be used directly to check for the count (`->count()`) after parsing to avoid a string based lookup. Before parsing, you can set the following options:
  
 * `->required()`: The program will quit if this option is not present. This is `mandatory` in Plumbum, but required options seems to be a more standard term. For compatibility, `->mandatory()` also works.
 * `->expected(N)`: Take `N` values instead of as many as possible, only for vector args
@@ -143,17 +153,19 @@ All `App`s have a `get_subcommand()` method, which returns a pointer to the subc
 even exit the program through the callback. The main `App` has a callback slot, as well, but it is generally not as useful.
  
  
-
 ## Subclassing
  
-The App class was designed allow toolkits to subclass it, to provide default options and setup/teardown code. Subcommands remain `App`'s, since those are not expected to need setup and teardown. The default `App` only adds a help flag, `-h,--help`, but provides an option to disable it in the constructor (and in `add_subcommand`). 
+The App class was designed allow toolkits to subclass it, to provide default options and setup/teardown code. Subcommands remain an unsubclassed `App`, since those are not expected to need setup and teardown. The default `App` only adds a help flag, `-h,--help`, but provides an option to disable it in the constructor (and in `add_subcommand`). 
  
-Also, in a related note, the `App`s you get a pointer to are stored in the parent `App` in `unique_ptr`s (like `Option`s) and are deleted when the main `App` goes out of scope.
+Also, in a related note, the `App` you get a pointer to is stored in the parent `App` in a `unique_ptr`s (like `Option`s) and are deleted when the main `App` goes out of scope.
  
  
 ## How it works
  
-Every `add_` option you've seen depends on one method that takes a lambda function. Each of these methods is just making a different lambda function with capture to populate the option. The function has full access to the vector of vector of strings, so it knows how many times an option was passed, and how many arguments each passing received (flags add empty strings to keep the counts correct). The lambda returns true if it could validate the option strings, and
-false if it failed.
+Every `add_` option you have seen so far depends on one method that takes a lambda function. Each of these methods is just making a different lambda function with capture to populate the option. The function has full access to the vector of vector of strings, so it knows how many times an option was passed, and how many arguments each passing received (flags add empty strings to keep the counts correct). The lambda returns `true` if it could validate the option strings, and
+`false` if it failed.
+
+## Contributing
  
+To contribute, open an issue or pull request on GitHub.