From 5e9211a53099d7e3cc4d6f820741cdeeac1f37bd Mon Sep 17 00:00:00 2001 From: Xavier Date: Fri, 5 Apr 2024 23:33:10 -0400 Subject: [PATCH] Refactored help module and updated help manual --- pacwrap/src/help.rs | 21 +-- pacwrap/src/help/config.rs | 4 +- pacwrap/src/help/manual.rs | 351 ++++++++++++++++++++++--------------- 3 files changed, 218 insertions(+), 158 deletions(-) diff --git a/pacwrap/src/help.rs b/pacwrap/src/help.rs index f2448c3..1b1682c 100644 --- a/pacwrap/src/help.rs +++ b/pacwrap/src/help.rs @@ -27,10 +27,11 @@ use pacwrap_core::{ utils::{arguments::Operand, is_color_terminal, Arguments}, Error, ErrorTrait, + Result, }; -mod manual; mod config; +mod manual; pub mod version; pub use version::print_version; @@ -43,11 +44,11 @@ lazy_static! { HelpTopic::Compose, HelpTopic::Query, HelpTopic::Process, - HelpTopic::Utils, HelpTopic::List, + HelpTopic::Utils, + HelpTopic::Version, HelpTopic::Help, HelpTopic::Env, - HelpTopic::Version, HelpTopic::Copyright ] .into(); @@ -61,7 +62,7 @@ enum ErrorKind { impl_error!(ErrorKind); impl Display for ErrorKind { - fn fmt(&self, fmter: &mut Formatter<'_>) -> std::result::Result<(), std::fmt::Error> { + fn fmt(&self, fmter: &mut Formatter<'_>) -> FmtResult { match self { Self::InvalidTopic(err) => write!(fmter, "Topic '{}' is not available.", err), }?; @@ -70,7 +71,7 @@ impl Display for ErrorKind { } } -pub fn help(mut args: &mut Arguments) -> Result<(), Error> { +pub fn help(mut args: &mut Arguments) -> Result<()> { let help = ascertain_help(&mut args)?; let mut buffer = String::new(); @@ -87,7 +88,7 @@ pub fn help(mut args: &mut Arguments) -> Result<(), Error> { Ok(()) } -fn ascertain_help<'a>(args: &'a mut Arguments) -> Result<(IndexSet<&'a HelpTopic>, &'a HelpLayout), Error> { +fn ascertain_help<'a>(args: &'a mut Arguments) -> Result<(IndexSet<&'a HelpTopic>, &'a HelpLayout)> { let mut layout = match is_color_terminal() { true => &HelpLayout::Console, false => &HelpLayout::Dumb, @@ -133,14 +134,14 @@ enum HelpTopic { Process, List, Help, + Version, Env, Copyright, - Version, PacwrapYml, } impl HelpTopic { - fn from(str: &str) -> Result<&Self, Error> { + fn from(str: &str) -> Result<&Self> { Ok(match str { "E" | "exec" | "run" => &HelpTopic::Execute, "S" | "sync" | "init" => &HelpTopic::Sync, @@ -216,7 +217,7 @@ impl HelpLayout { fn sub_section(&self) -> &str { match self { - Self::Console => " ", + Self::Console => " ", Self::Markdown => "### **", Self::Man => ".SS\n", Self::Dumb => " ", @@ -252,7 +253,7 @@ impl HelpLayout { fn reset_underline(&self) -> &str { match self { Self::Console => "", - Self::Man => "\n.I", + Self::Man => "\\fR", Self::Markdown => "", Self::Dumb => "", } diff --git a/pacwrap/src/help/config.rs b/pacwrap/src/help/config.rs index bfd0ba2..2bf56f4 100644 --- a/pacwrap/src/help/config.rs +++ b/pacwrap/src/help/config.rs @@ -17,11 +17,11 @@ * along with this program. If not, see . */ -use std::fmt::{Result as FmtResult, Write}; +use std::fmt::{Result, Write}; use crate::help::{version_string, HelpLayout}; -pub fn default(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn default(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let tab = layout.tab(); let bold = layout.bold(); diff --git a/pacwrap/src/help/manual.rs b/pacwrap/src/help/manual.rs index 52499a2..7d97c89 100644 --- a/pacwrap/src/help/manual.rs +++ b/pacwrap/src/help/manual.rs @@ -17,11 +17,11 @@ * along with this program. If not, see . */ -use std::fmt::{Result as FmtResult, Write}; +use std::fmt::{Result, Write}; use crate::help::{version_string, HelpLayout}; -fn header(buf: &mut String, layout: &HelpLayout) -> FmtResult { +fn header(buf: &mut String, layout: &HelpLayout) -> Result { let name = env!("CARGO_PKG_NAME"); let date = env!("PACWRAP_BUILDSTAMP"); @@ -38,7 +38,7 @@ This document was generated by the {name} binary with version {} of the program. } } -pub fn default(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn default(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let tab = layout.tab(); let sub_para = layout.sub_paragraph(); @@ -54,7 +54,7 @@ pub fn default(buf: &mut String, layout: &HelpLayout) -> FmtResult { {tab}pacwrap {head}SYNOPSIS{reset} -{tab}pacwrap [{bold}OPERATION{reset_bold} | {bold}COMMAND MODULE{reset_bold}] [{bold}ARGUMENTS{reset_bold}] [{bold}TARGETS{reset_bold}] +{tab}pacwrap [{bold}OPERATION{reset_bold} | {bold}VERB{reset_bold}] [{bold}ARGUMENTS{reset_bold}] [{bold}TARGETS{reset_bold}] {head}DESCRIPTION{reset} {sub_para}A package management front-end which utilises libalpm to facilitate the creation of unprivileged, @@ -65,82 +65,81 @@ pub fn default(buf: &mut String, layout: &HelpLayout) -> FmtResult { {tab}containerised environments for general-purpose use. CLI and GUI applications are all supported. {tab}Once a container environment is configured, it can be re-established or replicated on any system. +{sub_para}Each long-option parameter can also be specified herein as a command verb for a matter of convenience. +{tab}Additional command verb shortcuts are available and are documented alongside their relevancy. + {head}OPERATIONS{reset} +{sub_bold}-E, --exec, run{reset_bold} +{tab}{tab}Invoke a container to execute the provided command sequence. + {sub_bold}-S, --sync{reset_bold} -{tab}{tab}Synchronize package databases and update packages in target containers. +{tab}{tab}Synchronize package databases and containers in aggregate. {sub_bold}-R, --remove{reset_bold} -{tab}{tab}Remove packages from target containers. - -{sub_bold}-Q, --query{reset_bold} -{tab}{tab}Query package information from target container. +{tab}{tab}Remove packages from target containers in aggregate. {sub_bold}-C, --compose{reset_bold} {tab}{tab}Compose a container from configuration. +{sub_bold}-Q, --query{reset_bold} +{tab}{tab}Query package information from target container. + {sub_bold}-P, --process{reset_bold} {tab}{tab}Manage and show status of running container processes. -{sub_bold}-E, --execute{reset_bold} -{tab}{tab}Executes application in target container using bubblewrap. - {sub_bold}-L, --list{reset_bold} -{tab}{tab}List of available containers managed by pacwrap. +{tab}{tab}List available containers managed by pacwrap. {sub_bold}-U, --utils{reset_bold} -{tab}{tab}Invoke miscellaneous utilities to manage containers. +{tab}{tab}Engage miscellaneous utilities to manage containers. -{sub_bold}-h, --help=MODULE{reset_bold} -{tab}{tab}Invoke a printout of this manual to {bold}STDOUT{reset_bold}. +{sub_bold}-h, --help, --help=[OPERATION | VERB]{reset_bold} +{tab}{tab}Print this manual to {bold}STDOUT{reset_bold}. {sub_bold}-V, --version{reset_bold} -{tab}{tab}Display version and copyright information in {bold}STDOUT{reset_bold}.\n" +{tab}{tab}Display version banner or information.\n" ) } -pub fn execute(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn execute(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); - let sub_bold = layout.sub_bold(); let tab = layout.tab(); let reset = layout.reset(); + let bold = layout.bold(); + let sub = layout.sub(); + let sub_sect = layout.sub_section(); + let sub_bold = layout.sub_bold(); + let sub_para = layout.sub_paragraph(); let reset_bold = layout.reset_bold(); writeln!( buf, "{head}EXECUTE{reset} -{sub_bold}-r, --root{reset_bold} -{tab}{tab}Execute operation with fakeroot and fakechroot. Facilitates a command with faked privileges. - +{sub_para}Invoke a container to execute the provided command sequence. Command verb `{bold}run{reset_bold}` provides a +{tab}shortcut to this module. + +{sub_bold} {reset_bold} +{tab}{tab}Container name to spawn an instance of, along with the proceeding command-line sequence to execute. +{tab}{tab}execute. All command-line parameters after the container name are passed through to execute inside +{tab}{tab}of the container environment. + {sub_bold}-s, --shell{reset_bold} -{tab}{tab}Invoke a bash shell\n" +{tab}{tab}Invoke a bash shell in the target container. Command verb `{bold}shell{reset_bold}` provides a shortcut +{tab}{tab}to this module with this option. + +{sub_bold}-r, --root{reset_bold} +{tab}{tab}Execute the provided command sequence with fakeroot and fakechroot. + +{sub_sect}EXAMPLES{reset_bold} +{sub}`$ pacwrap run firefox firefox` +{tab}{tab}Launch firefox inside an instance of the firefox container. + +{sub}`$ pacwrap shell -r base` +{tab}{tab}Open a fakeroot bash shell inside an instance of the base container.\n" ) } -pub fn meta(buf: &mut String, layout: &HelpLayout) -> FmtResult { - let head = layout.head(); - let bold = layout.bold(); - let sub_bold = layout.sub_bold(); - let reset = layout.reset(); - let reset_bold = layout.reset_bold(); - let tab = layout.tab(); - - writeln!( - buf, - "{head}HELP{reset} -{sub_bold}-m, --more{reset_bold} -{tab}{tab}When specifying a topic to display, show the default topic in addition to specified options. - -{sub_bold}-f, --format=FORMAT{reset_bold} -{tab}{tab}Change output format of help in {bold}STDOUT{reset_bold}. Format options include: 'ansi', 'dumb', 'markdown', and 'man'. -{tab}{tab}This option is for the express purposes of generating documentation at build time, and has little utility -{tab}{tab}outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages. - -{sub_bold}-a, --all, --help=all{reset_bold} -{tab}{tab}Display all help topics.\n" - ) -} - -pub fn sync(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn sync(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let bold = layout.bold(); let tab = layout.tab(); @@ -153,7 +152,7 @@ pub fn sync(buf: &mut String, layout: &HelpLayout) -> FmtResult { writeln!( buf, - "{head}SYNCHRONIZATION{reset} + "{head}SYNCHRONIZATION{reset}. {sub_para}Provides the facilities required to be able to synchronize and create containers in aggregate. {sub_bold}-y, --refresh{reset_bold} @@ -164,14 +163,9 @@ pub fn sync(buf: &mut String, layout: &HelpLayout) -> FmtResult { {tab}{tab}a list of packages to specify package targets. Packages applicable to a target {bold}must{reset_bold} only be specified {tab}{tab}after the target operand. -{sub_bold}-f, --filesystem{reset_bold} -{tab}{tab}Force execution of filesystem synchronization target on all or specified containers. In combination -{tab}{tab}with {bold}-o/--target-only{reset_bold}, in addition to no other specified targets, filesystem slices will be synchronized -{tab}{tab}without package synhcronization on on all applicable containers. This operation is useful for propagation -{tab}{tab}of manual filesystem changes to all aggregate containers. - {sub_bold}-c, --create{reset_bold} -{tab}{tab}Create a container with the first specified target. A container type argument is also required. +{tab}{tab}Create a container with the first specified target. A container type argument is also required. Command verb +{tab}{tab}`{bold}init{reset_bold}` provides a shortcut to the synchronization module, equivalent to specifying the options `{bold}-Syuc{reset_bold}`. {sub_bold}-b, --base{reset_bold} {tab}{tab}Base container type. Specify alongside {bold}-c, --create{reset_bold} to assign this container type during creation. @@ -182,6 +176,7 @@ pub fn sync(buf: &mut String, layout: &HelpLayout) -> FmtResult { {sub_bold}-s, --slice{reset_bold} {tab}{tab}Slice container type. Specify alongside {bold}-c, --create{reset_bold} to assign this container type during creation. + {tab}{tab}Requires a base dependency, and optionally one or more sliced dependencies, to ascertain foreign {tab}{tab}packages and influence ordering of downstream synchronization target(s). Container slicing provides {tab}{tab}the ability to install packages in a lightweight, sliced filesytem, which aid in the deduplication @@ -191,31 +186,40 @@ pub fn sync(buf: &mut String, layout: &HelpLayout) -> FmtResult { {sub_bold}-a, --aggegrate{reset_bold} {tab}{tab}Aggregate container type. Specify alongside {bold}-c, --create{reset_bold} to this assign container type during creation. -{tab}{tab} + {tab}{tab}Requires a base dependency, and optionally one or more sliced dependencies, in order to acertain foreign {tab}{tab}packages and amalgamate the target. These containers are ideal for installing software with the aid of {tab}{tab}filesystem and package deduplication. -{tab}{tab} + {tab}{tab}Useful for all general purpose applications, browsers, e-mail clients, or even terminal user interface {tab}{tab}applications such as IRC clients. It is recommended to base your containers on aggregate type containers. -{sub_bold}-t, --target=TARGET{reset_bold} -{tab}{tab}Specify a target container for the specified operation. +{sub_bold}-t, --target={reset_bold} +{tab}{tab}Declare a target container for the specified operation. -{sub_bold}-d, --dep=DEPEND{reset_bold} -{tab}{tab}Specify a dependent container for the specified operation. +{sub_bold}{reset_bold} +{tab}{tab}Package target declared for target container specified. -{sub_bold}-p, --preview{reset_bold} -{tab}{tab}Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified. -{tab}{tab}Only applicable to +{sub_bold}-f, --filesystem{reset_bold} +{tab}{tab}Force execution of filesystem synchronization target on all or specified containers. In combination +{tab}{tab}with {bold}-o/--target-only{reset_bold}, in addition to no other specified targets, filesystems will be synchronized +{tab}{tab}without package synhcronization on on all applicable containers. This operation is useful for propagation +{tab}{tab}of manual filesystem changes to all aggregate containers. {sub_bold}-o, --target-only{reset_bold} {tab}{tab}Apply specified operation on the specified target(s) only. +{sub_bold}-d, --dep={reset_bold} +{tab}{tab}Specify dependencies for a container create operation. + +{sub_bold}-p, --preview{reset_bold} +{tab}{tab}Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified. +{tab}{tab}Only applicable to pre-existing targets and not create operations. + {sub_bold}--force-foreign{reset_bold} {tab}{tab}Force synchronization of foreign packages on resident container. Useful for when installing {tab}{tab}a new package in an aggregate container without all the prerequisite foreign dependencies -{tab}{tab}synchronized to this container's package database. +{tab}{tab}synchronized to the resident container's package database. {sub_bold}--dbonly{reset_bold} {tab}{tab}Transact on resident containers with a database-only transaction. @@ -224,25 +228,26 @@ pub fn sync(buf: &mut String, layout: &HelpLayout) -> FmtResult { {tab}{tab}Override confirmation prompts and confirm all operations. {sub_sect}EXAMPLES{reset_bold} -{sub}`$ pacwrap -Syucbt base` -{tab}{tab}Create a base container named base with no additional packages +{sub}`$ pacwrap init --base --target base` +{tab}{tab}Synchronize remotes and create a base-type container named `base` with no additional packages. -{sub}`$ pacwrap -Syucbt firefox firefox --dep=base,common,nvidia` -{tab}{tab}Create aggregate container named firefox with firefox installed. +{sub}`$ pacwrap -Syucst common gtk3 qt6-base --dep=base -st nvidia nvidia-utils --dep=base,common` +{tab}{tab}Synchronize remote databases, create two sliced containers, one named `common` with the packages +{tab}{tab}`gtk3`, `qt6-base`, and another named `nvidia` with the package `nvidia-utils`. -{sub}`$ pacwrap -Syut electron element-desktop -t mozilla firefox thunderbird` -{tab}{tab}Synchronize package databases and upgrade all containers, as well as install element-desktop -{tab}{tab}in the target electron, and install firefox and thunderbird in the target mozilla. +{sub}`$ pacwrap -Syucat mozilla firefox --dep=base,common,nvidia` +{tab}{tab}Synchronize remote databases and upgrade container dependencies, then create aggregate container +{tab}{tab}named `mozilla` with the package `firefox`. -{sub}`$ pacwrap -Syucst common gtk3 qt6-base --dep=base -cst nvidia nvidia-utils --dep=base,common` -{tab}{tab}Create two sliced containers, one named common with the packages gtk3, qt6-base, and another -{tab}{tab}named nvidia with the package nvidia-utils. +{sub}`$ pacwrap -Sot mozilla thunderbird` +{tab}{tab}Install `thunderbird` in the target container `mozilla`. {sub}`$ pacwrap -Sof` -{tab}{tab}Synchronize filesystem state of all associated containers present in the data directory.\n") +{tab}{tab}Synchronize filesystem state of all associated containers present in the data directory.\n" + ) } -pub fn remove(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn remove(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let tab = layout.tab(); let sub = layout.sub(); @@ -293,12 +298,11 @@ pub fn remove(buf: &mut String, layout: &HelpLayout) -> FmtResult { {tab}{tab}Remove the target package firefox from target container firefox. {sub}`$ pacwrap rm firefox` -{tab}{tab}Delete the root filesystem for the firefox container. -\n" +{tab}{tab}Delete the root filesystem for the firefox container.\n" ) } -pub fn compose(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn compose(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let tab = layout.tab(); let bold = layout.bold(); @@ -323,8 +327,6 @@ pub fn compose(buf: &mut String, layout: &HelpLayout) -> FmtResult { {tab}{tab}Compose an available, existing container for composition. The pre-existing container root {tab}{tab}will be deleted and the container will be composited from the configuration data enumerated. -{tab}{tab}Reinitialize container - {sub_bold}-t, --target=TARGET{reset_bold} {tab}{tab}Specify a target container for the specified operation. @@ -350,11 +352,11 @@ pub fn compose(buf: &mut String, layout: &HelpLayout) -> FmtResult { {tab}{tab}from the file 'element.yml'. {sub}`$ pacwrap compose --reinitialize-all --from-config` -{tab}{tab}Reinitialize all available containers as configured in '{bold}$PACWRAP_CONFIG_DIR{reset_bold}/container/'.\n" +{tab}{tab}Reinitialize all container configurations available in '{bold}$PACWRAP_CONFIG_DIR{reset_bold}/container/'.\n" ) } -pub fn query(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn query(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let tab = layout.tab(); let sub_bold = layout.sub_bold(); @@ -368,7 +370,7 @@ pub fn query(buf: &mut String, layout: &HelpLayout) -> FmtResult { writeln!( buf, "{head}QUERY{reset} -{sub_para}Query package list on target container. This module presently is not complete. +{sub_para}Query package list on target container. {sub_bold}-q, --quiet{reset_bold} {tab}{tab}Quiet the output by truncating the package string. @@ -385,7 +387,7 @@ pub fn query(buf: &mut String, layout: &HelpLayout) -> FmtResult { ) } -pub fn process(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn process(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let tab = layout.tab(); let sub_bold = layout.sub_bold(); @@ -426,7 +428,47 @@ pub fn process(buf: &mut String, layout: &HelpLayout) -> FmtResult { ) } -pub fn utils(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn list(buf: &mut String, layout: &HelpLayout) -> Result { + let head = layout.head(); + let tab = layout.tab(); + let sub = layout.sub(); + let sub_sect = layout.sub_section(); + let sub_bold = layout.sub_bold(); + let sub_para = layout.sub_paragraph(); + let bold = layout.bold(); + let reset = layout.reset(); + let reset_bold = layout.reset_bold(); + + writeln!( + buf, + "{head}LIST{reset} +{sub_para}List all initialized containers presently managed by pacwrap. + +{sub_para}This command module is a shortcut to {bold}-Ul{reset_bold}. Command verb `{bold}ls{reset_bold}` also is a +{tab}{tab}shortcut to this command module. + +{sub_bold}-t, --total{reset_bold} +{tab}{tab}Display a total column. + +{sub_bold}-o, --on-disk{reset_bold} +{tab}{tab}Display a size on disk column. + +{sub_bold}-b, --bytes{reset_bold} +{tab}{tab}Toggle byte unit display. + +{sub_sect}EXAMPLES{reset_bold} +{sub}`$ pacwrap -Ld` +{tab}{tab}Print container tabulation out to {bold}STDOUT{reset_bold} with two total columns, one listing the +{tab}{tab}container name, and the other detailing the total size-on-disk consumption displayed with byteunits. + +{sub}`$ pacwrap ls -btbts` +{tab}{tab}Print container tabulation to {bold}STDOUT{reset_bold} with three total columns, first listing the +{tab}{tab}container name, second the total amount of bytes, and the last showing the total with byteunits. +{tab}{tab}Then print a summation of total, actual consumption below.\n" + ) +} + +pub fn utils(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let tab = layout.tab(); let sub = layout.sub(); @@ -441,7 +483,7 @@ pub fn utils(buf: &mut String, layout: &HelpLayout) -> FmtResult { buf, "{head}UTILITIES{reset} {sub_para}Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and -{tab}maintenance of operate containers. +{tab}maintenance of containers. {sub_bold}-v, --view{reset_bold} {tab}{tab}Invoke {bold}$EDITOR{reset_bold} to view file associated with pacwrap. @@ -527,88 +569,105 @@ pub fn utils(buf: &mut String, layout: &HelpLayout) -> FmtResult { {tab}{tab}Create a fresh configuration rather than derive it from the target. {sub_sect}EXAMPLES{reset_bold} -{sub}`$ pacwrap -Ulbtbts` -{tab}{tab}Print table listing containers out to {bold}STDOUT{reset_bold} with two total columns, one showing -{tab}{tab}the total amount of bytes. Then print a summary calculation of total consumption below. +{sub}`$ pacwrap -Uoh firefox` +{tab}{tab}Open firefox's home directory in the default file manager. + +{sub}`$ pacwrap -Us java runelite` +{tab}{tab}Create a symbolic container called `runelite` of `java`. {sub}`$ pacwrap -Uvl` -{tab}{tab}View '{bold}$PACWRAP_DATA_DIR{reset_bold}/pacwrap.log' with {bold}$EDITOR{reset_bold}.\n" +{tab}{tab}View '{bold}$PACWRAP_DATA_DIR{reset_bold}/pacwrap.log' with {bold}$EDITOR{reset_bold}. + +{sub}`$ pacwrap -Uec firefox` +{tab}{tab}Edit '{bold}$PACWRAP_CONFIG_DIR{reset_bold}/container/firefox.yml' with {bold}$EDITOR{reset_bold}. + +{sub}`$ pacwrap -Uld` +{tab}{tab}Print container tabulation out to {bold}STDOUT{reset_bold} with two total columns, one listing the +{tab}{tab}container name, and the other detailing the total size-on-disk consumption displayed with byteunits. + +{sub}`$ pacwrap -Ulbtbts` +{tab}{tab}Print container tabulation to {bold}STDOUT{reset_bold} with three total columns, first listing the +{tab}{tab}container name, second the total amount of bytes, and the last showing the total with byteunits. +{tab}{tab}Then print a summation of total, actual consumption below.\n" ) } -pub fn list(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn meta(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); + let bold = layout.bold(); + let sub_bold = layout.sub_bold(); + let reset = layout.reset(); + let reset_bold = layout.reset_bold(); + let tab = layout.tab(); + + writeln!( + buf, + "{head}HELP{reset} +{sub_bold}-m, --more{reset_bold} +{tab}{tab}When specifying a topic to display, show the default topic in addition to specified options. + +{sub_bold}-f, --format=FORMAT{reset_bold} +{tab}{tab}Change output format of help in {bold}STDOUT{reset_bold}. Format options include: 'ansi', 'dumb', 'markdown', and 'man'. +{tab}{tab}This option is for the express purposes of generating documentation at build time, and has little utility +{tab}{tab}outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages. + +{sub_bold}-a, --all, --help=all{reset_bold} +{tab}{tab}Display all help topics.\n" + ) +} + +pub fn environment(buf: &mut String, layout: &HelpLayout) -> Result { + let head = layout.head(); + let bold = layout.bold(); let tab = layout.tab(); - let sub = layout.sub(); let sub_sect = layout.sub_section(); let sub_bold = layout.sub_bold(); let sub_para = layout.sub_paragraph(); - let bold = layout.bold(); let reset = layout.reset(); let reset_bold = layout.reset_bold(); writeln!( buf, - "{head}LIST{reset} -{sub_para}List all initialized containers presently managed by pacwrap. - -{sub_para}This command module is a shortcut to {bold}-Ul{reset_bold}. - -{sub_bold}-t, --total{reset_bold} -{tab}{tab}Display a total column. - -{sub_bold}-o, --on-disk{reset_bold} -{tab}{tab}Display a size on disk column. - -{sub_bold}-b, --bytes{reset_bold} -{tab}{tab}Toggle byte unit display. - -{sub_sect}EXAMPLE{reset_bold} -{sub}`$ pacwrap ls -btbts` -{tab}{tab}Print table listing containers out to {bold}STDOUT{reset_bold} with two total columns, one showing -{tab}{tab}the total amount of bytes. Then print a summary calculation of total consumption below.\n" - ) -} - -pub fn environment(buf: &mut String, layout: &HelpLayout) -> FmtResult { - let head = layout.head(); - let sub_bold = layout.sub_bold(); - let tab = layout.tab(); - let reset = layout.reset(); - let reset_bold = layout.reset_bold(); - let sub_para = layout.sub_paragraph(); - - writeln!( - buf, - "{head}ENVIRONMENT VARIABLES{reset} + "{head}ENVIRONMENT{reset} {sub_para}Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters. -{tab}{tab}Use with care: These variables if used improperly could result in undesired behaviour. +{tab}All environment variables listed are case sensitive. -{sub_bold}PACWRAP_CONFIG_DIR{reset_bold} -{tab}{tab}Set the configuration directory. This environment variable overrides the default, -{tab}{tab}XDG Directory Specification compliant path. +{sub_para}Use with care: These variables if used improperly could result in undesired behaviour. -{sub_bold}PACWRAP_DATA_DIR{reset_bold} -{tab}{tab}Set the data directory. This environment variable overrides the default, -{tab}{tab}XDG Directory Specification compliant path. +{sub_bold}PACWRAP_CONFIG_DIR={reset_bold} +{tab}{tab}Set the configuration directory, overriding the default location. -{sub_bold}PACWRAP_CACHE_DIR{reset_bold} -{tab}{tab}Set the cache directory. This environment variable overrides the default, -{tab}{tab}XDG Directory Specification compliant path. +{sub_bold}PACWRAP_DATA_DIR={reset_bold} +{tab}{tab}Set the data directory, overriding the default location. + +{sub_bold}PACWRAP_CACHE_DIR={reset_bold} +{tab}{tab}Set the cache directory, overriding the default location. {sub_bold}PACWRAP_VERBOSE=[0|1]{reset_bold} -{tab}{tab}Toggle verbose output during a transaction. This option may be removed or otherwise -{tab}{tab}differ in functionality in future. +{tab}{tab}Toggle verbose output during a transaction. This option may be subject to change. -{sub_bold}PACWRAP_HOME{reset_bold} -{tab}{tab}Upon execution, mount the set path provided when engaging the 'home' module. +{sub_bold}PACWRAP_HOME={reset_bold} +{tab}{tab}Upon container invocation, mount the set path provided when engaging the '{bold}home{reset_bold}' filesystem module. -{sub_bold}PACWRAP_ROOT{reset_bold} -{tab}{tab}Upon execution, Mount the set path provided when engaging the 'root' module.\n" +{sub_bold}PACWRAP_ROOT={reset_bold} +{tab}{tab}Upon container invocation, mount the set path provided when engaging the '{bold}root{reset_bold}' filesystem module. + +{sub_sect}DEFAULT{reset_bold} +{sub_para}For the following environment variables, contained herein are default runtime values. Any variables not +{tab}included here in this subsection are to be assumed to have inert values by default. + +{sub_bold}PACWRAP_CACHE_DIR{reset_bold} +{tab}{tab}`{bold}$HOME{reset_bold}/.cache/pacwrap`: Default cache directory. + +{sub_bold}PACWRAP_CONFIG_DIR{reset_bold} +{tab}{tab}`{bold}$HOME{reset_bold}/.config/pacwrap`: Default configuration directory. + +{sub_bold}PACWRAP_DATA_DIR +{tab}{tab}`${bold}HOME{reset_bold}/.local/share/pacwrap`: Default data directory.\n" ) } -pub fn version(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn version(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let sub_bold = layout.sub_bold(); let tab = layout.tab(); @@ -625,7 +684,7 @@ pub fn version(buf: &mut String, layout: &HelpLayout) -> FmtResult { ) } -pub fn copyright(buf: &mut String, layout: &HelpLayout) -> FmtResult { +pub fn copyright(buf: &mut String, layout: &HelpLayout) -> Result { let head = layout.head(); let tab = layout.tab(); let reset = layout.reset();