feat: improve help, #113, close #110

Cargo.toml

@@ -77,7 +77,6 @@ async-trait = { version = "0.1.83", default-features = false }
 axum = { version = "0.7.7", default-features = false, features = ["http1", "http2", "tokio"] }
 byteorder = { version = "1.5.0", default-features = false, features = ["std"] }
 clap = { version = "4.5.18", features = ["derive"] }
-clap-verbosity-flag = { version = "2.2.2", default-features = false }
 enumset = { version = "1.1.5", default-features = false }
 futures = { version = "0.3.30", features = ["default"] }
 hyper = { version = "1.4.1", default-features = false, features = ["http2"] }

versatiles/Cargo.toml

@@ -26,7 +26,6 @@ anyhow = { workspace = true, features = ["std", "backtrace"] }
 async-trait.workspace = true
 axum = { workspace = true, optional = true }
 clap = { workspace = true, optional = true }
-clap-verbosity-flag = { workspace = true, optional = true }
 enumset = { workspace = true, optional = true }
 env_logger = { version = "0.11.5", default-features = false, optional = true }
 hyper = { workspace = true, optional = true }
@@ -57,7 +56,6 @@ versatiles_core = { workspace = true, features = ["test"] }
 default = ["cli"]
 cli = [
 	"dep:axum",
-	"dep:clap-verbosity-flag",
 	"dep:clap",
 	"dep:env_logger",
 	"dep:enumset",

versatiles/src/main.rs

@@ -29,7 +29,7 @@ mod tools;
 
 use anyhow::Result;
 use clap::{Parser, Subcommand};
-use clap_verbosity_flag::{ErrorLevel, Verbosity};
+use log::LevelFilter;
 use versatiles_container as container;
 use versatiles_core::*;
 use versatiles_pipeline as pipeline;
@@ -48,8 +48,32 @@ struct Cli {
 	#[command(subcommand)]
 	command: Commands, // Set subcommands
 
-	#[command(flatten)]
-	verbose: Verbosity<ErrorLevel>, // Set verbosity flag
+	#[arg(
+		long,
+		short = 'q',
+		action = clap::ArgAction::Count,
+		global = true,
+		help = "Decrease logging verbosity",
+		long_help = "Decrease the logging verbosity level.",
+		conflicts_with = "verbose",
+		display_order = 100,
+	)]
+	quiet: u8,
+
+	#[arg(
+		long,
+		short = 'v',
+		action = clap::ArgAction::Count,
+		global = true,
+		help = "Increase logging verbosity\n(add more 'v' for greater detail, e.g., '-vvvv' for trace-level logs).",
+		long_help = "Increase the logging verbosity level. Each 'v' increases the log level by one step:\n\
+			- `-v` enables warnings\n\
+			- `-vv` enables informational logs\n\
+			- `-vvv` enables debugging logs\n\
+			- `-vvvv` enables trace logs, which give the most detailed information about the tool's execution.",
+		display_order = 100,
+	)]
+	verbose: u8,
 }
 
 /// Define subcommands for the command-line interface
@@ -75,8 +99,18 @@ fn main() -> Result<()> {
 	let cli = Cli::parse();
 
 	// Initialize logger and set log level based on verbosity flag
+	let verbosity = cli.verbose as i16 - cli.quiet as i16;
+	let log_level = match verbosity {
+		i16::MIN..=-1 => LevelFilter::Off,
+		0 => LevelFilter::Error,
+		1 => LevelFilter::Warn,
+		2 => LevelFilter::Info,
+		3 => LevelFilter::Debug,
+		4..=i16::MAX => LevelFilter::Trace,
+	};
+
 	env_logger::Builder::new()
-		.filter_level(cli.verbose.log_level_filter())
+		.filter_level(log_level)
 		.format_timestamp(None)
 		.init();
 

versatiles/src/tools/convert.rs

@@ -16,45 +16,46 @@ pub struct Subcommand {
 	output_file: String,
 
 	/// minimum zoom level
-	#[arg(long, value_name = "int")]
+	#[arg(long, value_name = "int", display_order = 1)]
 	min_zoom: Option<u8>,
 
 	/// maximum zoom level
-	#[arg(long, value_name = "int")]
+	#[arg(long, value_name = "int", display_order = 1)]
 	max_zoom: Option<u8>,
 
 	/// use only tiles inside a bounding box
 	#[arg(
 		long,
 		short,
 		value_name = "lon_min,lat_min,lon_max,lat_max",
-		allow_hyphen_values = true
+		allow_hyphen_values = true,
+		display_order = 1
 	)]
 	bbox: Option<String>,
 
 	/// also include additional tiles surrounding the bounding box as a border
-	#[arg(long, value_name = "int")]
+	#[arg(long, value_name = "int", display_order = 1)]
 	bbox_border: Option<u32>,
 
-	/// swap rows and columns, e.g. z/x/y -> z/y/x
-	#[arg(long)]
-	swap_xy: bool,
-
-	/// flip input vertically
-	#[arg(long)]
-	flip_y: bool,
-
 	/// set new compression
-	#[arg(long, short, value_enum)]
+	#[arg(long, short, value_enum, display_order = 2)]
 	compress: Option<TileCompression>,
 
 	/// force recompression, e.g. to improve an existing gzip compression
-	#[arg(long, short)]
+	#[arg(long, short, display_order = 2)]
 	force_recompress: bool,
 
 	/// override the compression of the input source, e.g. to handle gzipped tiles in a tar, that do not end in .gz
-	#[arg(long, value_enum, value_name = "COMPRESSION")]
+	#[arg(long, value_enum, value_name = "COMPRESSION", display_order = 2)]
 	override_input_compression: Option<TileCompression>,
+
+	/// swap rows and columns, e.g. z/x/y -> z/y/x
+	#[arg(long, display_order = 3)]
+	swap_xy: bool,
+
+	/// flip input vertically
+	#[arg(long, display_order = 3)]
+	flip_y: bool,
 }
 
 #[tokio::main]

versatiles/src/tools/serve.rs

@@ -27,43 +27,43 @@ pub struct Subcommand {
 	pub tile_sources: Vec<String>,
 
 	/// Serve via socket ip.
-	#[arg(short = 'i', long, default_value = "0.0.0.0")]
+	#[arg(short = 'i', long, default_value = "0.0.0.0", display_order = 0)]
 	pub ip: String,
 
 	/// Serve via port.
-	#[arg(short, long, default_value = "8080")]
+	#[arg(short, long, default_value = "8080", display_order = 0)]
 	pub port: u16,
 
 	/// Serve static content at "http:/.../" from a local folder or a tar file.
 	/// Tar files can be compressed (.tar / .tar.gz / .tar.br).
 	/// If multiple static sources are defined, the first hit will be served.
 	/// You can also add an optional url prefix like "[/assets/styles]styles.tar".
-	#[arg(short = 's', long = "static", verbatim_doc_comment)]
+	#[arg(short = 's', long = "static", verbatim_doc_comment, display_order = 1)]
 	pub static_content: Vec<String>,
 
 	/// Shutdown server automatically after x milliseconds.
-	#[arg(long)]
+	#[arg(long, display_order = 4)]
 	pub auto_shutdown: Option<u64>,
 
 	/// swap rows and columns, e.g. z/x/y -> z/y/x
-	#[arg(long)]
+	#[arg(long, display_order = 3)]
 	pub swap_xy: bool,
 
 	/// flip input vertically
-	#[arg(long)]
+	#[arg(long, display_order = 3)]
 	pub flip_y: bool,
 
 	/// use minimal recompression to reduce server response time
-	#[arg(long)]
+	#[arg(long, display_order = 2)]
 	pub fast: bool,
 
 	/// disable API
-	#[arg(long)]
+	#[arg(long, display_order = 4)]
 	pub disable_api: bool,
 
 	/// override the compression of the input source, e.g. to handle gzipped tiles in a tar, that do not end in .gz
 	/// (deprecated in favor of a better solution that does not yet exist)
-	#[arg(long, value_enum, value_name = "COMPRESSION")]
+	#[arg(long, value_enum, value_name = "COMPRESSION", display_order = 4)]
 	override_input_compression: Option<TileCompression>,
 }