usage: tasks

src/arg/mod.rs

@@ -21,7 +21,7 @@ pub fn print_usage()
 	     version = env!("CARGO_PKG_VERSION"),
 	     author = env!("CARGO_PKG_AUTHORS"));
     println!(r#"
-Usage: {prog} [OPTIONS]...
+Usage: {prog} [OPTIONS] [TASKS]...
 Usage: {prog} --help
 
 {opts}

src/arg/usage.rs

@@ -147,6 +147,30 @@ impl fmt::Display for Opt
     }
 }
 
+// ---
+
+#[inline] fn filespec() -> impl Iterator<Item = Opt>
+{
+    iter![
+	opt!(in "TASKS"),
+	opt!(where "There are various ways to add processes to the task list"),
+	
+	opt!("--execute", "-e" => "process, args..."; "Add this process to the task list with this arguments. It should be in the format 'program arg1 arg2 ...', with each sperated by whitespace and in a single argument. (this will usually require escaping the whitespace)."),
+	opt!("--shell-execute", "-es" => "expression"; "Add this shell expression to the task list. The default shell can be specified", ["ENVIRONMENT"]),
+	opt!("--+execute", "-E"; * 3 "Interpret the rest of the arguments as if they were passed to `--execute`. The same format should be used."),
+	opt!("--+shell-execute", "-Es"; * 3 "Interpret the rest of the arguments as if they were passed to `--shell-execute`. The same format should be used"),
+	opt!("--"; * 5 "Read inputs from stdin and interpret them as if they were passed by `--execute`. There should be one task per line. The process will keep reading lines from stdin until an explicit termination or error occurs, or the stream is closed."),
+	opt!("--s"; * 5 "The same as `--` but for `--shell-execute` instead."),
+	opt!(),
+	
+	opt!("Explicit tasks"),
+	opt!(where "You can apply very specific rules to individually provided tasks.\nFull explanations are below", ["EXPLICITY"]),
+	//TODO
+	
+	opt!()
+    ]
+}
+
 /// The `options` section
 #[inline] fn options() -> impl Iterator<Item = Opt>
 {
@@ -159,7 +183,11 @@ impl fmt::Display for Opt
 	opt!("--completion", "-c" => "action"; "Set the default action on completion",  ["ACTIONS", "COMPLETION"], "ignore"),
 	opt!("--silent", "-s"; * 3 "Output no messages other than that of child processes"),
 	opt!("--stfu", "-S"; * 3 "Output no messages at all"),
-
+	
+	opt!("--path:override", "-P" => "path"; * 1 "Override the path to search for programs in for execution. They should be in the same format as the Unix `PATH` environment variable."),
+	opt!("--path", "-p" => "path"; * 2 "Append these semi-colon seperated entries to the search path for programs."),
+	opt!("--path:none", "-N"; * 2 "Do not use any look-up paths for finding programs for execution, assume each entry resolves to a path itself"),
+	
 	opt!("\nChild I/O"),
 	opt!(where "Defaults for I/O redirections of children\nThese can be overwritten individually with explicit inputs."),
 	opt!("--stdout" => "where"; * 2 "Set default redirect option for childrens' `stdout`", ["ACTIONS"] ,"inherit"),
@@ -187,6 +215,7 @@ impl fmt::Display for Opt
 	opt!("file:clobber" => "filename"; "Only valid for outputs, overwrite the file and write to it, instead of appending"),
 	opt!("stderr"; * 3  "Redirect stdout to the same location as stderr.\n\t\t\t\tIf there is a cycle detected here, or it is used for anything other that stdout, there is a panic"),
 	opt!("stdout"; * 3 "Redirect stderr to the same location as stdout.\n\t\t\t\tIf there is a cycle detected here, or it is used for anything other that stdout, there is a panic"),
+	opt!(),
 
 	opt!("Control"),
 	opt!(where "Controlling how processes are spawned\nThese can be overridden individually with explicit inputs"),
@@ -233,6 +262,24 @@ impl fmt::Display for Opt
 	opt!("warn"; * 2 "Only warnings and errors"),
 	opt!("error"; * 2 "Only errors"),
 	opt!("none"; * 2 "No diagnostic messages", ""),
+	opt!(),
+	
+	opt!("PATH"),
+	opt!(where "Programs are looked up through the set path. This behaviour can be changed", ["OPTIONS"]),
+
+	opt!("SHELL"),
+	opt!(where "The path to the default shell used for shell execution tasks, if it is unset, this will default to `/bin/sh`"),
+	
+	opt!()
+    ]
+}
+
+/// Section for explaining the options for explicit task dispatch
+fn explicity() -> impl Iterator<Item = Opt>
+{
+    iter![
+	opt!(in "EXPLICITY"),
+	opt!(where "Using the `-*x` family of arguments, the options for explicit dispatch are described here"),
 
 	opt!()
     ]
@@ -242,7 +289,9 @@ impl fmt::Display for Opt
 /// Each item in the iterator is intended to be written as a single line.
 pub fn sections() -> impl Iterator<Item = impl fmt::Display>
 {
-    options()
+    filespec()
+	.chain(options())
+	.chain(explicity())
 	.chain(actions())
 	.chain(completion())
 	.chain(environment())