pacwrap/pacwrap
pacwrap/pacwrap
1
0
Fork 0
Code Issues Activity Actions

Additional documentation with refactoring and bug fix

Browse source 
- Documentation for desktop utils command module
- Split authorship and license sections in manual
- Cleaned up and reformatted some parameters in manual output
- Don't include symbolic containers with queue in filesystem module
- Tidy-up refactor of a few different functions across the library
This commit is contained in:
Xavier Moffett 2024-04-10 20:12:08 -04:00
parent fde67122ad
commit 6c8f7374e6
8 changed files with 298 additions and 200 deletions
Download patch file Download diff file Expand all files Collapse all files

155
dist/man/pacwrap.1 vendored
View file

@ -1,5 +1,5 @@
.nh
.TH pacwrap 1 "05/04/2024" "pacwrap version_string_placeholder" "User Manual"
.TH pacwrap 1 "10/04/2024" "pacwrap version_string_placeholder" "User Manual"
.SH
NAME\fR
@ -59,18 +59,18 @@ List available containers managed by pacwrap.
\fB-U, --utils\fR
Engage miscellaneous utilities to manage containers.
.TP
\fB-h, --help, --help=[OPERATION | VERB]\fR
Print this manual to \fBSTDOUT\fR.
.TP
\fB-V, --version\fR
Display version banner or information.
.TP
\fB-h, --help\fR <\fBOPERATION\fR | \fBVERB\fR | \fBTOPIC\fR>
Print the help manual to \fBSTDOUT\fR.
.SH
EXECUTE\fR
.PP
Invoke a container to execute the provided command sequence. Command verb \fB`run`\fR` provides a
Invoke a container to execute the provided command sequence. Command verb \fB`run`\fR provides a
shortcut to this module.
.TP
@ -81,7 +81,7 @@ of the container environment.
.TP
\fB-s, --shell\fR
Invoke a bash shell in the target container. Command verb `\fBshell\fR` provides a shortcut
Invoke a bash shell in the target container. Command verb \fB`shell`\fR provides a shortcut
to this module with this option.
.TP
@ -99,7 +99,7 @@ Launch firefox inside an instance of the firefox container.
Open a fakeroot bash shell inside an instance of the base container.
.SH
SYNCHRONIZATION\fR.
SYNCHRONIZATION\fR
.PP
Provides the facilities required to be able to synchronize and create containers in aggregate.
@ -109,7 +109,7 @@ Synchronize remote package databases. Specify up to 2 times to force a refresh.
.TP
\fB-u, --upgrade\fR
Execute aggregate upgrade routine on all or specified containers. Use \fB`-t, --target=[CONTAINER]`\fR followed
Execute aggregate upgrade routine on all or specified containers. Use \fB`-t, --target[=CONTAINER]`\fR followed
by a list of packages to specify package targets. Packages applicable to a target \fBmust\fR only be specified
after the target operand.
@ -149,12 +149,8 @@ Useful for all general purpose applications, browsers, e-mail clients, or even t
applications such as IRC clients. It is recommended to base your containers on aggregate type containers.
.TP
\fB-t, --target=[CONTAINER]\fR
Declare a target container for the specified operation.
.TP
\fB<PACKAGE>\fR
Package target declared for target container specified.
\fB-t, --target\fR <\fBCONTAINER\fR> <..\fBPACKAGE\fR>
Declare a target container for the specified operation, followed by a list of package target(s).
.TP
\fB-f, --filesystem\fR
@ -168,7 +164,7 @@ of manual filesystem changes to all aggregate containers.
Apply specified operation on the specified target(s) only.
.TP
\fB-d, --dep=[CONTAINER]\fR
\fB-d, --dep\fR <\fBCONTAINER\fR>
Specify dependencies for a container create operation.
.TP
@ -231,7 +227,7 @@ associated dependencies, provided they are not required by other packages, and a
marked as being upstream of the target container.
.TP
\fB-t, --target=[CONTAINER]\fR
\fB-t, --target\fR <\fBCONTAINER\fR>
Specify a target container for the specified operation. At least one container target is
is required for package removal operations.
@ -284,7 +280,7 @@ Compose an available, existing container for composition. The pre-existing conta
will be deleted and the container will be composited from the configuration data enumerated.
.TP
\fB-t, --target=[CONTAINER]\fR
\fB-t, --target=\fR <\fBCONTAINER\fR>
Specify a target container for the specified operation.
.TP
@ -328,7 +324,7 @@ Query package list on target container.
Quiet the output by truncating the package string.
.TP
\fB-t, --target=[CONTAINER]\fR
\fB-t, --target\fR <\fBCONTAINER\fR>
Specify a target container for the specified operation.
.TP
@ -348,7 +344,11 @@ Table a process list of running containers. Containers may be filtered on target
.TP
\fB-s, --summary\fR
Enumerate a process summary of containers being executed by pacwrap.
Enumerate a process summary of containers instantiated by pacwrap.
.TP
\fB-i, --id-list\fR
Enumerate a process id list of containers instantiated by pacwrap.
.TP
\fB-k, --kill\fR
@ -356,14 +356,14 @@ Kill target containers and their associated processes.
.TP
\fB-a, --all\fR
Enumerate all processes associated with running containers.
Target all containers and enumerate their associated processes.
.TP
\fB-d, --depth\fR
Enumerate all processes at the specified depth associated with running containers.
.TP
\fB-t, --target=[CONTAINER]\fR
\fB-t, --target\fR <\fBCONTAINER\fR>
Specify a target container for the specified operation.
.TP
@ -371,11 +371,16 @@ Specify a target container for the specified operation.
Override confirmation prompts and confirm all operations.
.SS
EXAMPLE\fR
EXAMPLES\fR
.TP
`$ pacwrap -Psaxc`
Print table enumerating all container processes to \fBSTDOUT\fR with process
arguments and execution path split into separate columns.
Print table enumerating all container processes to \fBSTDOUT\fR with process arguments
and execution path split into separate columns.
.TP
`$ ps up "$(pacwrap -Pia)"`
Enumerate container processes with `ps` via encapsulating an enumeration of pids from all instances
into a space-delimited bash string.
.SH
LIST\fR
@ -415,7 +420,12 @@ Then print a summation of total, actual consumption below.
UTILITIES\fR
.PP
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and
maintenance of containers.
maintenance of containers. Each utility is considered a command module and therefore can be shortcuted
with a command verb.
.TP
\fB-d, --desktop\fR
Create desktop file to launch application inside of a pacwrap container.
.TP
\fB-v, --view\fR
@ -441,24 +451,42 @@ Create a symbolic container.
\fB-r, --remove\fR
Delete a container(s) root filesystem.
.SS
DESKTOP OPTIONS\fR
.PP
Create and manage desktop files to launch applications in pacwrap from your favourite applications menu.
.TP
\fB-c, --create\fR <\fBCONTAINER\fR> <\fBAPPLICATION\fR>
Create desktop file associated with application at `$HOME/.local/share/applications/` launching an
application in pacwrap.
.TP
\fB-l, --list\fR <\fBCONTAINER\fR>
List available desktop files in the container root located at `/usr/share/applications/`.
.TP
\fB-r, --remove\fR <\fBAPPLICATION\fR>
Remove desktop file associated with application from `$HOME/.local/share/applications/`.
.SS
EDITOR OPTIONS\fR
.PP
These options are associated with the \fB--edit\fR and \fB--view\fR utility command modules.
.TP
\fB-c, --config=[CONTAINER]\fR
\fB-c, --config\fR <\fBCONTAINER\fR>
Edit specified container configuration located in the pacwrap data directory. Defaults to
the primary configuration file: '\fB$PACWRAP_CONFIG_DIR\fR/pacwrap.yml' if no option is otherwise
specified.
.TP
\fB-d, --desktop=[APPLICATION]\fR
\fB-d, --desktop\fR <\fBAPPLICATION\fR>
Edit specified desktop file associated with a pacwrap container.
.TP
\fB-r, --repo\fR
Edit repositories configuration file: '\fB$PACWRAP_CONFIG_DIR\fR/repositories.conf'.
Edit repositories configuration file: `$PACWRAP_CONFIG_DIR/repositories.conf`.
.TP
\fB-l, --log\fR
@ -470,15 +498,15 @@ OPEN OPTIONS\fR
These options are associated with the \fB--open\fR utility command module.
.TP
\fB-h, --home, --home=[CONTAINER]\fR
\fB-h, --home\fR <\fBCONTAINER\fR>
Specified container's home filesystem.
.TP
\fB-r, --home, --root=[CONTAINER]\fR
\fB-r, --root\fR <\fBCONTAINER\fR>
Specified container's root filesystem.
.TP
\fB-t, --target=[CONTAINER]\fR
\fB-t, --target\fR <\fBCONTAINER\fR>
Target container to perform the operation.
.SS
@ -508,7 +536,7 @@ REMOVE OPTIONS\fR
These options are associated with the \fB--remove\fR utility command module.
.TP
\fB-t, --target\fR
\fB-t, --target\fR <\fBCONTAINER\fR>
Target container to perform the operation.
.TP
@ -538,17 +566,22 @@ EXAMPLES\fR
`$ pacwrap -Uoh firefox`
Open firefox's home directory in the default file manager.
.TP
`$ pacwrap -Us java runelite`
Create a symbolic container called `runelite` of `java`.
.TP
`$ pacwrap -Uvl`
View '\fB$PACWRAP_DATA_DIR\fR/pacwrap.log' with \fB$EDITOR\fR.
View `\fB$PACWRAP_DATA_DIR\fR/pacwrap.log` with \fB$EDITOR\fR.
.TP
`$ pacwrap -Uec firefox`
Edit '\fB$PACWRAP_CONFIG_DIR\fR/container/firefox.yml' with \fB$EDITOR\fR.
Edit `$PACWRAP_CONFIG_DIR\fR/container/firefox.yml` with \fB$EDITOR\fR.
.TP
`$ pacwrap utils -dc firefox firefox`
Create desktop file `$HOME/.local/share/applications/pacwrap.firefox.desktop` derived from
`/usr/share/applications/firefox.desktop` in the root of the firefox container.
.TP
`$ pacwrap utils symlink java runelite`
Create a symbolic container called `runelite` of `java`.
.TP
`$ pacwrap -Uld`
@ -556,7 +589,7 @@ Print container tabulation out to \fBSTDOUT\fR with two total columns, one listi
container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
.TP
`$ pacwrap -Ulbtbts`
`$ pacwrap utils -lbtbts`
Print container tabulation to \fBSTDOUT\fR with three total columns, first listing the
container name, second the total amount of bytes, and the last showing the total with byteunits.
Then print a summation of total, actual consumption below.
@ -570,12 +603,16 @@ The 'min' option provides a minimalistic output as is provided to non-colour ter
.SH
HELP\fR
.TP
\fB-h, --help\fR <\fBTOPIC\fR>
Print the specified topic to \fBSTDOUT\fR.
.TP
\fB-m, --more\fR
When specifying a topic to display, show the default topic in addition to specified options.
.TP
\fB-f, --format=[FORMAT]\fR
\fB-f, --format\fR <\fBFORMAT\fR>
Change output format of help in \fBSTDOUT\fR. Format options include: 'ansi', 'dumb', 'markdown', and 'man'.
This option is for the express purposes of generating documentation at build time, and has little utility
outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages.
@ -594,28 +631,29 @@ All environment variables listed are case sensitive.
Use with care: These variables if used improperly could result in undesired behaviour.
.TP
\fBPACWRAP_CONFIG_DIR=[DIR]\fR
Set the configuration directory, overriding the default location.
\fBPACWRAP_CONFIG_DIR\fR <\fBDIR\fR>
Set path of the configuration directory, overriding the default location.
.TP
\fBPACWRAP_DATA_DIR=[DIR]\fR
Set the data directory, overriding the default location.
\fBPACWRAP_DATA_DIR\fR <\fBDIR\fR>
Set path of the data directory, overriding the default location.
.TP
\fBPACWRAP_CACHE_DIR=[DIR]\fR
Set the cache directory, overriding the default location.
\fBPACWRAP_CACHE_DIR\fR <\fBDIR\fR>
Set path of the cache directory, overriding the default location.
.TP
\fBPACWRAP_VERBOSE=[0 | 1]\fR
Toggle verbose output during a transaction. This option may be subject to change.
\fBPACWRAP_HOME\fR <\fBDIR\fR>
Upon container invocation, mount the set path provided when engaging the \fB`home`\fR filesystem module.
.TP
\fBPACWRAP_HOME=[DIR]\fR
Upon container invocation, mount the set path provided when engaging the '\fBhome\fR' filesystem module.
\fBPACWRAP_ROOT\fR <\fBDIR\fR>
Upon container invocation, mount the set path provided when engaging the \fB`root`\fR filesystem module.
.TP
\fBPACWRAP_ROOT=[DIR]\fR
Upon container invocation, mount the set path provided when engaging the '\fBroot\fR' filesystem module.
\fBPACWRAP_VERBOSE\fR <\fB0\fR | \fB1\fR>
Toggle verbose output during a transaction. Valid options are `1` for enablement and `0` for
disablement of verbosity.
.SS
DEFAULT\fR
@ -632,13 +670,14 @@ included here in this subsection are to be assumed to have inert values by defau
`$HOME/.config/pacwrap`: Default configuration directory.
.TP
\fBPACWRAP_DATA_DIR
\fBPACWRAP_DATA_DIR\fR
`$HOME/.local/share/pacwrap`: Default data directory.
.SH
COPYRIGHT\fR
Copyright (C) 2023-2024 Xavier R.M.
AUTHOR\fR
Copyright (C) 2023-2024 Xavier R.M. <sapphirus@azorium.net>
This program may be freely redistributed under the
terms of the GNU General Public License v3 only.
.SH
LICENSE\fR
This program may be freely redistributed under the terms of the GNU General Public License v3 only.