Merge pull request #130 from terminalforlife/master

New File, New Examples, and Some Code/Comment Tweaks

sheets/cdparanoia

@@ -0,0 +1,5 @@
+# cdparanoia
+# Audio-extraction tool for sampling CDs
+
+# Rip tracks 1-20 from an audio CD in the provided device.
+cdparanoia -B 1-20 -d /dev/sr1

sheets/ch-build

@@ -2,7 +2,6 @@
 # Utility to build a Charliecloud image and place it in the builder’s back-end
 # storage. More information: <https://github.com/hpc/charliecloud>.
 
-# Create an image tagged foo and specified by the file /bar/Dockerfile.
-# Use /bar as the Docker context directory. Use the default builder.
+# Create an image tagged foo and specified by the file /bar/Dockerfile. Use
+# /bar as the Docker context directory. Use the default builder.
 ch-build -t foo --file=/bar/Dockerfile /bar
-

sheets/ch-build2dir

@@ -2,7 +2,6 @@
 # Utility to build a Charliecloud image from Dockerfile and unpack it into a
 # directory. More information: <https://github.com/hpc/charliecloud>.
 
-# Build a Charliecloud image using ./Dockerfile.foo and create image
-# directory /var/tmp/foo
+# Build a Charliecloud image using './Dockerfile.foo' and create image
+# directory '/var/tmp/foo'.
 ch-build2dir -t foo -f ./Dockerfile.foo . /var/tmp
-

sheets/ch-builder2squash

@@ -2,7 +2,6 @@
 # Utility to flatten a builder image into a Charliecloud SquashFS file.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Flattens the builder image tagged "debian" into a SquashFS file named
-# debian.sqfs in /var/tmp.
+# Flattens the builder image tagged 'debian' into a SquashFS file named
+# 'debian.sqfs' in '/var/tmp'.
 ch-builder2squash debian /var/tmp
-

sheets/ch-builder2tar

@@ -2,7 +2,6 @@
 # Utility to flatten a builder image into a Charliecloud image tarball.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Flatten the builder image tagged "hello" into a Charliecloud tarball in
-# directory /var/tmp
+# Flatten the builder image tagged 'hello' into a Charliecloud tarball in
+# directory '/var/tmp'.
 ch-builder2tar hello /var/tmp
-

sheets/ch-dir2squash

@@ -2,7 +2,6 @@
 # Utility to create a SquashFS file from a Charliecloud image directory.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Create a Charliecloud SquashFS file debian.sqfs under the directory /var/tmp
-# from the image directory /var/tmp/debian.
+# Create a Charliecloud SquashFS file debian.sqfs under the directory
+# '/var/tmp' from the image directory '/var/tmp/debian'.
 ch-dir2squash /var/tmp/debian /var/tmp
-

sheets/ch-grow

@@ -3,10 +3,8 @@
 # It is completely unprivileged, with no setuid/setgid/setcap helpers.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Build the image "bar" using ./foo/bar/Dockerfile and context directory
-# ./foo/bar
+# Build image 'bar' using './foo/bar/Dockerfile' and context dir './foo/bar'.
 ch-grow build -t bar -f ./foo/bar/Dockerfile ./foo/bar
 
-# Download the Debian Buster image and place it in /tmp/buster.
+# Download the Debian Buster image and place it in '/tmp/buster'.
 ch-grow pull debian:buster /tmp/buster
-

sheets/ch-mount

@@ -2,7 +2,6 @@
 # Utility to mount a SquashFS image file using FUSE.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Create a new empty directory named debian, then mount it on /var/tmp
-# directory. The /var/tmp directory must not already exist.
+# Create a new empty directory named 'debian', then mount it to '/var/tmp'. The
+# '/var/tmp' directory must not already exist.
 ch-mount /var/tmp/debian.sqfs /var/tmp
-

sheets/ch-pull2dir

@@ -2,7 +2,6 @@
 # Utility to pull an image from the Docker Hub and unpack it into a directory.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Pull Docker image named alpine:latest from Docker Hub and extract it into
-# a subdirectory of /var/tmp. A temporary tarball will be stored in /var/tmp.
+# Pull Docker image named 'alpine:latest' from Docker Hub, then extract it into
+# a subdirectory named '/var/tmp', in which a temporary tarball will be stored.
 ch-pull2dir alpine:latest /var/tmp
-

sheets/ch-pull2tar

@@ -2,7 +2,6 @@
 # Utility to pull an image from the Docker Hub and flatten it into a tarball.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Pull a Docker image named alpine:latest from Docker Hub and flatten it into
-# a Charliecloud tarball in the directory /var/tmp.
+# Pull a Docker image named 'alpine:latest' from Docker Hub and flatten it into
+# a Charliecloud tarball in the directory '/var/tmp'.
 ch-pull2tar alpine:latest /var/tmp
-

sheets/ch-run

@@ -2,7 +2,6 @@
 # Utility to run a command in a Charliecloud container.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Run the command echo hello inside a Charliecloud container using
-# the unpacked image at /data/foo.
+# Run the given `echo` command inside a Charliecloud container, using the
+# unpacked image at '/data/foo'.
 ch-run /data/foo -- echo hello
-

sheets/ch-tar2dir

@@ -2,8 +2,7 @@
 # Utility to unpack a Charliecloud image tarball into a directory.
 # More information: <https://github.com/hpc/charliecloud>.
 
-# Extract the tarball /var/tmp/hello.tar.gz into a subdirectory of /var/tmp.
-# hello.tar.gz must contain a Linux filesystem image, e.g. as created
-# by ch-builder2tar.
+# Extract tarball '/var/tmp/hello.tar.gz' into a subdirectory of '/var/tmp'.
+# The tarball must contain a Linux filesystem image, such as is created by
+# ch-builder2tar.
 ch-tar2dir /var/tmp/hello.tar.gz /var/tmp
-

sheets/printf

@@ -26,3 +26,7 @@ printf '%#.3d\n' 12
 # As above, but instead, space-pad the number. Prefix the `3` with a hyphen
 # (`-`) to left-align the number, causing the padding to occur on the right.
 printf '%3d\n' 12
+
+# Set a field's spacing by using an integer provided as a variable. This is
+# incredibly useful when you're dealing with inconsistent field lengths.
+printf '%*s\n' $Integer 'Example Field'

sheets/read

@@ -0,0 +1,29 @@
+# read (The Bash Built-in)
+# Read a line from the standard input and split it into fields
+
+# Standard approach to prompting the user for a single-character response, such
+# as a simple 'Y' or 'N' response. Using Bash's `read`, you can save time and
+# lines by having the prompt taken care of by `read` itself.
+#
+# The use of the `-e` flag tells read to return a new line afterwards. As the
+# `help read` output says:
+#
+#   use Readline to obtain the line in an interactive shell
+#
+# Because we're using the `-n 1` flag and argument, we'll want `-e`, as the
+# user will not get a chance to press the Enter or Return key which would
+# otherwise give us that new line.
+read -n 1 -e -p 'Prompt: '
+
+# A while read loop in Bash is easily one of the best features, when properly
+# utilized; it often makes the use of tools like grep(1), sed(1), and even
+# awk(1) redundant, depending on the functionality required. This can offer
+# more efficiency, depending on what's needed and the amount of data to parse.
+#
+# In this example, the [I]nput [F]ield [S]eperator is set to `=` for only the
+# `read` built-in, and the `-a` flag is used to split the input, per the
+# provided IFS, into an array. This then means the first index is the key and
+# the second index the value, which is ideal when parsing configurtion files.
+while IFS='=' read -a Line; do
+	COMMANDS
+done < INPUT_FILE

sheets/udisksctl

@@ -1,20 +1,34 @@
+# udisksctl
+# The udisks command line tool
+
 # Output low-level information for the provided block device and partition.
 udisksctl info -b /dev/sdd1
 
-# Mount partition on the given block device. This will by default use '/media', and
-# on typical systems won't even require root privileges.
+# Mount partition on the given block device. This will by default use
+# '/media', and on typical systems won't even require root privileges.
 udisksctl mount -b /dev/sd??
 
 # Set up a loop device using 'imagefile'. This only sets it up, so you will
-# probably also want to mount it thereafter, using the device given to you after
-# executing this command. often, if not always, this is '/dev/loopX', where X is
-# the loop device number.
+# probably also want to mount it thereafter, using the device given to you
+# after executing this command. often, if not always, this is '/dev/loopX', -
+# where X is the loop device number.
 udisksctl loop-setup -f image file
 
 # Like the above, except this will delete the loop device (assuming 'loop0' was
-# previously created) but note that this will NOT delete the image file. Be sure to
-# unmount the filesystem(s) on the device first, before deleting it.
+# previously created) but note that this will NOT delete the image file. Be
+# sure to unmount the filesystem(s) on the device first, before deleting it.
 udisksctl loop-delete -b /dev/loop0
 
-# Power off a block device. May not work for all devices, and may vary in effect.
+# Power off block device. May not work for all devices, and may vary in effect.
 udisksctl power-off -b /dev/sdb
+
+# Example of a suitable mount request for auto-mounting at startup. Useful if
+# fstab isn't playing nice. This also demonstrates using `mount`-style options.
+udisksctl mount --no-user-interaction --options noatime -b /dev/sde1
+
+# In some distributions of Linux, such as an Ubuntu 18.04 base install, will
+# not have its policies set to allow regular users to mount filesystems with
+# udisksctl(1) without root access, despite that being the point of this tool.
+# This can be resolved by updating the policies to this effect. In Ubuntu 18.04
+# it's as easy as a simple package installation procedure.
+sudo apt-get install policykit-desktop-privileges

sheets/xargs

@@ -1,26 +1,32 @@
-# Find all file names ending with .pdf and remove them
+# xargs
+# Build and execute command lines from standard input
+
+# Find all file names ending with .pdf, then remove them.
 find -name \*.pdf | xargs rm
-# The above, however, is preferable written without xargs:
+# The above, however, is better-written without xargs:
 find -name \*.pdf -exec rm {} \+
-# Or, for find's own functionality, it's best as:
+# Although it's best to use find's own functionality, in this situation.
 find -name \*.pdf -delete
 
-# Find all file name ending with .pdf and remove them
-# (bulletproof version: handles filenames with \n and skips *.pdf directories)
-# -r = --no-run-if-empty
-# -n10 = group by 10 files
-find -name \*.pdf -type f -print0 | xargs -0rn10 rm
+# Find all file names ending with '.pdf' and remove them. This approach also
+# handles filenames with '\n' and skips '*.pdf' directories. The xargs(1) flag
+# `-r` is equivalent to `--no-run-if-empty`, and the use of `-n` will in this
+# case group execution by 10 files.
+find -name \*.pdf -type f -print0 | xargs -0 -r -n 10 rm
 
-# If file name contains spaces you should use this instead
-find -name \*.pdf | xargs -I{} rm -rf '{}'
+# If file names may contains spaces, you can use the xargs(1) flag `-I` and its
+# proceeding argument to specify the filename placeholder, as in find(1)'s use
+# of `{}` in `-exec`. Although find(1)'s `{}` needs not be cuddled by quotes, -
+# xargs(1) does.
+find -name \*.pdf | xargs -I {} rm -r '{}'
 
-# Will show every .pdf like:
-#    &toto.pdf=
-#    &titi.pdf=
-# -n1 => One file by one file. ( -n2 => 2 files by 2 files )
-find -name \*.pdf | xargs -I{} -n1 echo '&{}='
-# The above is, however, much faster and easier without xargs:
-find -name \*.pdf -printf "%p\n"
+# Print a list of files in the format of `*FILE=`. The use of xargs(1) flag
+# `-n` here with its argument of `1` means to process the files one-by-one.
+find -name \*.pdf | xargs -I {} -n 1 echo '&{}='
+# The above is, however, much faster, more efficient, and easier without xargs.
+find -name \*.pdf -printf '&%f=\n'
 
-# Group words by three in a string
-seq 1 10 | xargs -n3
+# Group words by three in a string.
+seq 1 10 | xargs -n 3
+# Alternatively, and more efficiently, use Bash brace expansion, if available.
+printf '%d ' {1..10} | xargs -n 3