docs: generate man page via xtask

.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --package xtask --"

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 resolver = "2"
-members = ["brush-shell", "brush-parser", "brush-core", "brush-interactive", "fuzz"]
+members = ["brush-shell", "brush-parser", "brush-core", "brush-interactive", "fuzz", "xtask"]
 default-members = ["brush-shell"]
 
 [workspace.package]

brush-shell/src/args.rs

@@ -0,0 +1,142 @@
+use clap::{builder::styling, Parser};
+use std::io::IsTerminal;
+
+use crate::{events, productinfo};
+
+const SHORT_DESCRIPTION: &str = "Bo[u]rn[e] RUsty SHell";
+
+const LONG_DESCRIPTION: &str = r#"
+brush is a Rust-implemented, POSIX-style shell that aims to be compatible with bash.
+
+brush is a work in progress. If you encounter any issues or discrepancies in behavior from bash, please report them at https://github.com/reubeno/brush.
+"#;
+
+const VERSION: &str = const_format::concatcp!(
+    productinfo::PRODUCT_VERSION,
+    " (",
+    productinfo::PRODUCT_GIT_VERSION,
+    ")"
+);
+
+/// Parsed command-line arguments for the brush shell.
+#[derive(Parser)]
+#[clap(name = productinfo::PRODUCT_NAME,
+       version = VERSION,
+       about = SHORT_DESCRIPTION,
+       long_about = LONG_DESCRIPTION,
+       author,
+       disable_help_flag = true,
+       disable_version_flag = true,
+       styles = brush_help_styles())]
+pub struct CommandLineArgs {
+    /// Display usage information.
+    #[clap(long = "help", action = clap::ArgAction::HelpLong)]
+    pub help: Option<bool>,
+
+    /// Display shell version.
+    #[clap(long = "version", action = clap::ArgAction::Version)]
+    pub version: Option<bool>,
+
+    /// Execute the provided command and then exit.
+    #[arg(short = 'c', value_name = "COMMAND")]
+    pub command: Option<String>,
+
+    /// Run in interactive mode.
+    #[clap(short = 'i')]
+    pub interactive: bool,
+
+    /// Make shell act as if it had been invoked as a login shell.
+    #[clap(short = 'l', long = "login")]
+    pub login: bool,
+
+    /// Do not execute commands.
+    #[clap(short = 'n')]
+    pub do_not_execute_commands: bool,
+
+    /// Don't use readline for input.
+    #[clap(long = "noediting")]
+    pub no_editing: bool,
+
+    /// Don't process any profile/login files (/etc/profile, ~/.bash_profile, ~/.bash_login,
+    /// ~/.profile).
+    #[clap(long = "noprofile")]
+    pub no_profile: bool,
+
+    /// Don't process "rc" files if the shell is interactive (e.g., ~/.bashrc, ~/.brushrc).
+    #[clap(long = "norc")]
+    pub no_rc: bool,
+
+    /// Enable shell option.
+    #[clap(short = 'O', value_name = "OPTION")]
+    pub enabled_shopt_options: Vec<String>,
+
+    /// Disable shell option.
+    #[clap(long = "+O", hide = true)]
+    pub disabled_shopt_options: Vec<String>,
+
+    /// Disable non-POSIX extensions.
+    #[clap(long = "posix")]
+    pub posix: bool,
+
+    /// Read commands from standard input.
+    #[clap(short = 's')]
+    pub read_commands_from_stdin: bool,
+
+    /// Run in sh compatibility mode.
+    #[clap(long = "sh")]
+    pub sh_mode: bool,
+
+    /// Print input when it's processed.
+    #[clap(short = 'v', long = "verbose")]
+    pub verbose: bool,
+
+    /// Print commands as they execute.
+    #[clap(short = 'x')]
+    pub print_commands_and_arguments: bool,
+
+    /// Disable bracketed paste.
+    #[clap(long = "disable-bracketed-paste")]
+    pub disable_bracketed_paste: bool,
+
+    /// Enable debug logging for classes of tracing events.
+    #[clap(long = "log-enable", value_name = "EVENT")]
+    pub enabled_log_events: Vec<events::TraceEvent>,
+
+    /// Path to script to execute.
+    pub script_path: Option<String>,
+
+    /// Arguments for script.
+    pub script_args: Vec<String>,
+}
+
+impl CommandLineArgs {
+    pub fn is_interactive(&self) -> bool {
+        if self.interactive {
+            return true;
+        }
+
+        if self.command.is_some() || self.script_path.is_some() {
+            return false;
+        }
+
+        if !std::io::stdin().is_terminal() || !std::io::stderr().is_terminal() {
+            return false;
+        }
+
+        true
+    }
+}
+
+/// Returns clap styling to be used for command-line help.
+#[doc(hidden)]
+fn brush_help_styles() -> clap::builder::Styles {
+    styling::Styles::styled()
+        .header(
+            styling::AnsiColor::Yellow.on_default()
+                | styling::Effects::BOLD
+                | styling::Effects::UNDERLINE,
+        )
+        .usage(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD)
+        .literal(styling::AnsiColor::Magenta.on_default() | styling::Effects::BOLD)
+        .placeholder(styling::AnsiColor::Cyan.on_default())
+}

brush-shell/src/events.rs

@@ -7,7 +7,7 @@ use tracing_subscriber::{
 
 /// Type of event to trace.
 #[derive(Clone, Debug, Eq, Hash, PartialEq, clap::ValueEnum)]
-pub(crate) enum TraceEvent {
+pub enum TraceEvent {
     /// Traces parsing and evaluation of arithmetic expressions.
     #[clap(name = "arithmetic")]
     Arithmetic,

brush-shell/src/lib.rs

@@ -0,0 +1,7 @@
+#![allow(dead_code)]
+
+mod args;
+mod events;
+mod productinfo;
+
+pub use args::CommandLineArgs;

brush-shell/src/main.rs

@@ -2,119 +2,14 @@
 
 #![deny(missing_docs)]
 
+mod args;
 mod brushctl;
 mod events;
 mod productinfo;
 
-use clap::{builder::styling, Parser};
-use std::{io::IsTerminal, path::Path, sync::Arc};
-
-/// Parsed command-line arguments for the brush shell.
-#[derive(Parser)]
-#[clap(name = productinfo::PRODUCT_NAME,
-       version = const_format::concatcp!(productinfo::PRODUCT_VERSION, " (", productinfo::PRODUCT_GIT_VERSION, ")"),
-       about,
-       disable_help_flag = true,
-       disable_version_flag = true,
-       styles = brush_help_styles())]
-struct CommandLineArgs {
-    /// Display usage information.
-    #[clap(long = "help", action = clap::ArgAction::HelpLong)]
-    help: Option<bool>,
-
-    /// Display shell version.
-    #[clap(long = "version", action = clap::ArgAction::Version)]
-    version: Option<bool>,
-
-    /// Execute the provided command and then exit.
-    #[arg(short = 'c')]
-    command: Option<String>,
-
-    /// Run in interactive mode.
-    #[clap(short = 'i')]
-    interactive: bool,
-
-    /// Make shell act as if it had been invoked as a login shell.
-    #[clap(short = 'l', long = "login")]
-    login: bool,
-
-    /// Do not execute commands.
-    #[clap(short = 'n')]
-    do_not_execute_commands: bool,
-
-    /// Don't use readline for input.
-    #[clap(long = "noediting")]
-    no_editing: bool,
-
-    /// Don't process any profile/login files (`/etc/profile`, `~/.bash_profile`, `~/.bash_login`,
-    /// `~/.profile`).
-    #[clap(long = "noprofile")]
-    no_profile: bool,
-
-    /// Don't process "rc" files if the shell is interactive (e.g., `~/.bashrc`, `~/.brushrc`).
-    #[clap(long = "norc")]
-    no_rc: bool,
-
-    /// Enable shell option.
-    #[clap(short = 'O')]
-    enabled_shopt_options: Vec<String>,
-
-    /// Disable shell option.
-    #[clap(long = "+O", hide = true)]
-    disabled_shopt_options: Vec<String>,
-
-    /// Disable non-POSIX extensions.
-    #[clap(long = "posix")]
-    posix: bool,
-
-    /// Read commands from standard input.
-    #[clap(short = 's')]
-    read_commands_from_stdin: bool,
-
-    /// Run in sh compatibility mode.
-    #[clap(long = "sh")]
-    sh_mode: bool,
-
-    /// Print input when it's processed.
-    #[clap(short = 'v', long = "verbose")]
-    verbose: bool,
-
-    /// Print commands as they execute.
-    #[clap(short = 'x')]
-    print_commands_and_arguments: bool,
-
-    /// Disable bracketed paste.
-    #[clap(long = "disable-bracketed-paste")]
-    disable_bracketed_paste: bool,
-
-    /// Enable debug logging for classes of tracing events.
-    #[clap(long = "log-enable")]
-    enabled_log_events: Vec<events::TraceEvent>,
-
-    /// Path to script to execute.
-    script_path: Option<String>,
-
-    /// Arguments for script.
-    script_args: Vec<String>,
-}
-
-impl CommandLineArgs {
-    pub fn is_interactive(&self) -> bool {
-        if self.interactive {
-            return true;
-        }
-
-        if self.command.is_some() || self.script_path.is_some() {
-            return false;
-        }
-
-        if !std::io::stdin().is_terminal() || !std::io::stderr().is_terminal() {
-            return false;
-        }
-
-        true
-    }
-}
+use crate::args::CommandLineArgs;
+use clap::Parser;
+use std::{path::Path, sync::Arc};
 
 lazy_static::lazy_static! {
     static ref TRACE_EVENT_CONFIG: Arc<tokio::sync::Mutex<Option<events::TraceEventConfig>>> =
@@ -263,17 +158,3 @@ async fn instantiate_shell(
 pub(crate) fn get_event_config() -> Arc<tokio::sync::Mutex<Option<events::TraceEventConfig>>> {
     TRACE_EVENT_CONFIG.clone()
 }
-
-/// Returns clap styling to be used for command-line help.
-#[doc(hidden)]
-fn brush_help_styles() -> clap::builder::Styles {
-    styling::Styles::styled()
-        .header(
-            styling::AnsiColor::Yellow.on_default()
-                | styling::Effects::BOLD
-                | styling::Effects::UNDERLINE,
-        )
-        .usage(styling::AnsiColor::Green.on_default() | styling::Effects::BOLD)
-        .literal(styling::AnsiColor::Magenta.on_default() | styling::Effects::BOLD)
-        .placeholder(styling::AnsiColor::Cyan.on_default())
-}

xtask/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "xtask"
+publish = false
+version = "0.1.0"
+authors.workspace = true
+categories.workspace = true
+edition.workspace = true
+keywords.workspace = true
+license.workspace = true
+readme.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+anyhow = "1.0.86"
+brush-shell = { version = "^0.2.7", path = "../brush-shell" }
+clap = { version = "4.5.11", features = ["derive"] }
+clap_mangen = "0.2.23"
+clap-markdown = "0.1.4"