start a help command

it is connected to the 'help' keyword and runs a few examples for the
user showing what could be typed in and the resulting printout on their
machine.

add more insect-like help printout

short description plus some examples and a link to the full
documentation online

use package description for uniformity

fixup help printout by changing Cargo description.

- Just formatting changes to the Cargo description (removing the initial
  whitepsace and adding an ending period).
- don't use `let` in example to avoid polluting the namespace of the
  user
- use keyword markup for numbat and link to documentation so they stand
  out

run cargo fmt

numbat-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "numbat-cli"
-description = " A statically typed programming language for scientific computations with first class support for physical dimensions and units"
+description = "A statically typed programming language for scientific computations with first class support for physical dimensions and units."
 authors = ["David Peter <[email protected]>"]
 categories = ["command-line-utilities", "science", "mathematics", "compilers"]
 keywords = ["language", "compiler", "physics", "units", "calculation"]

numbat-cli/src/main.rs

@@ -130,6 +130,45 @@ impl Cli {
         }
     }
 
+    fn help(&mut self) -> Result<()> {
+        let output = m::nl()
+            + m::keyword("numbat")
+            + m::space()
+            + m::text(env!("CARGO_PKG_DESCRIPTION"))
+            + m::nl()
+            + m::text("You can start by trying one of the examples:")
+            + m::nl();
+
+        println!("{}", ansi_format(&output, false));
+
+        let examples = vec![
+            "8 km / (1 h + 25 min)",
+            "atan2(30 cm, 1 m) -> deg",
+            r#"print("Energy of red photons: {ℏ 2 π c / 660 cm -> eV}")"#,
+        ];
+        for example in examples.iter() {
+            println!("{}{}", PROMPT, example);
+            let eg_result = self.parse_and_evaluate(
+                example,
+                CodeSource::Internal,
+                ExecutionMode::Normal,
+                self.args.pretty_print,
+            );
+            if eg_result.is_break() {
+                bail!("Interpreter failed during help examples")
+            }
+        }
+
+        let output = m::nl() // extra whitespace after last example
+            +m::text("Full documentation:")
+            +m::space()
+            +m::keyword("https://numbat.dev/doc/")
+            +m::nl();
+        println!("{}", ansi_format(&output, false));
+
+        Ok(())
+    }
+
     fn run(&mut self) -> Result<()> {
         let load_prelude = !self.args.no_prelude;
         let load_init = !(self.args.no_prelude || self.args.no_init);
@@ -284,6 +323,12 @@ impl Cli {
                             "quit" | "exit" => {
                                 return Ok(());
                             }
+                            "help" | "?" => {
+                                // purposefully ignoring result of help
+                                // because if the examples are failing I am assuming
+                                // the user is a developer intentionally changing numbat
+                                let _ = self.help();
+                            }
                             _ => {
                                 let result = self.parse_and_evaluate(
                                     &line,