Update documentation

docs2/src/boxed/cases.md

@@ -0,0 +1,10 @@
+It is also possible to make dynamic choice about the parsers. This example defines two parsers
+for distance - imperial and metric and picks one from some source available at runtime only.
+
+Help message will contain only one parser
+
+> --help
+
+and only one parser will produce a result
+
+> --distance 10

docs2/src/boxed/combine.rs

@@ -0,0 +1,26 @@
+//
+use bpaf::*;
+
+pub fn options() -> OptionParser<f64> {
+    let miles = long("distance")
+        .help("distance in miles")
+        .argument::<f64>("MILES")
+        .map(|d| d * 1.609344);
+
+    let km = long("distance")
+        .help("distance in km")
+        .argument::<f64>("KM");
+
+    // suppose this is reading from config fule
+    let use_metric = true;
+
+    // without use of `boxed` here branches have different types so it won't typecheck
+    // boxed make it so branches have the same type as long as they return the same type
+    let distance = if use_metric {
+        km.boxed()
+    } else {
+        miles.boxed()
+    };
+
+    distance.to_options()
+}

docs2/src/numeric_prefix/cases.md

@@ -0,0 +1,16 @@
+If `bpaf` can parse first positional argument as number - it becomes a numeric prefix
+
+> 10 eat
+
+Otherwise it gets ignored
+
+> "just eat"
+
+
+If validation passes but second argument is missing - in this example there's no fallback
+
+> 10
+
+Help should show that the prefix is optional
+
+> --help

documentation/_documentation/_2_howto/_07_skip_positional/index.md

@@ -1,3 +1,7 @@
 #### Skipping optional positional items if parsing or validation fails
 
-#![cfg_attr(not(doctest), doc = include_str!("docs/numeric_prefix.md"))]
+Combinations like [`Parser::optional`] and
+[`ParseOptional::catch`](crate::parsers::ParseOptional::catch) allow to try to parse something
+and then handle the error as if pase attempt never existed
+
+#![cfg_attr(not(doctest), doc = include_str!("docs2/numeric_prefix.md"))]

documentation/_documentation/_2_howto/_08_cargo_helper/index.md

@@ -1,5 +1,6 @@
 #### Implementing cargo commands
 
-With [`cargo_helper`](crate::batteries::cargo_helper) you can use your application as a `cargo` command
+With [`cargo_helper`](crate::batteries::cargo_helper) you can use your application as a `cargo` command.
+You will need to enable `batteries` feature while importing `bpaf`.
 
-#![cfg_attr(not(doctest), doc = include_str!("docs/cargo_helper.md"))]
+#![cfg_attr(not(doctest), doc = include_str!("docs2/cargo_helper.md"))]

src/_documentation.rs

@@ -2463,7 +2463,11 @@
             //! 
             //! #### Skipping optional positional items if parsing or validation fails
             //! 
-            #![cfg_attr(not(doctest), doc = include_str!("docs/numeric_prefix.md"))]
+            //! Combinations like [`Parser::optional`] and
+            //! [`ParseOptional::catch`](crate::parsers::ParseOptional::catch) allow to try to parse something
+            //! and then handle the error as if pase attempt never existed
+            //! 
+            #![cfg_attr(not(doctest), doc = include_str!("docs2/numeric_prefix.md"))]
             //!
             //!
             //!  
@@ -2511,9 +2515,10 @@
             //! 
             //! #### Implementing cargo commands
             //! 
-            //! With [`cargo_helper`](crate::batteries::cargo_helper) you can use your application as a `cargo` command
+            //! With [`cargo_helper`](crate::batteries::cargo_helper) you can use your application as a `cargo` command.
+            //! You will need to enable `batteries` feature while importing `bpaf`.
             //! 
-            #![cfg_attr(not(doctest), doc = include_str!("docs/cargo_helper.md"))]
+            #![cfg_attr(not(doctest), doc = include_str!("docs2/cargo_helper.md"))]
             //!
             //!
             //!