Review: passive voice links and pronouns through dev tools

src/algorithms/randomness/rand-choose.md

@@ -1,5 +1,3 @@
-[ex-rand-choose]: #ex-rand-choose
-<a name="ex-rand-choose"></a>
 ## Create random passwords from a set of user-defined characters
 
 [![rand-badge]][rand] [![cat-os-badge]][cat-os]

src/algorithms/randomness/rand-custom.md

@@ -1,5 +1,3 @@
-[ex-rand-custom]: #ex-rand-custom
-<a name="ex-rand-custom"></a>
 ## Generate random values of a custom type
 
 [![rand-badge]][rand] [![cat-science-badge]][cat-science]

src/algorithms/randomness/rand-dist.md

@@ -1,11 +1,8 @@
-[ex-rand-dist]: #ex-rand-dist
-<a name="ex-rand-dist"></a>
-
 ## Generate random numbers with given distribution
 
 [![rand-badge]][rand] [![cat-science-badge]][cat-science]
 
-By default, random numbers are generated with [uniform distribution].
+By default, random numbers have [uniform distribution].
 To generate numbers with other distributions you instantiate a
 distribution, then sample from that distribution using
 [`IndependentSample::ind_sample`] with help of a random-number

src/algorithms/randomness/rand-passwd.md

@@ -1,5 +1,3 @@
-[ex-rand-passwd]: #ex-rand-passwd
-<a name="ex-rand-passwd"></a>
 ## Create random passwords from a set of alphanumeric characters
 
 [![rand-badge]][rand] [![cat-os-badge]][cat-os]

src/algorithms/randomness/rand-range.md

@@ -18,7 +18,7 @@ fn main() {
 }
 ```
 
-Alternatively, one can use [`Range`] to obtain values with [uniform distribution].
+[`Range`] can obtain values with [uniform distribution].
 This has the same effect, but may be faster when repeatedly generating numbers
 in the same range.
 
@@ -41,6 +41,6 @@ fn main() {
 }
 ```
 
-[`Range`]: https://doc.rust-lang.org/rand/rand/distributions/range/struct.Range.html
-[`Rng::gen_range`]: https://doc.rust-lang.org/rand/rand/trait.Rng.html#method.gen_range
+[`Range`]: https://doc.rust-lang.org/rand/*/rand/distributions/range/struct.Range.html
+[`Rng::gen_range`]: https://doc.rust-lang.org/rand/*/rand/trait.Rng.html#method.gen_range
 [uniform distribution]: https://en.wikipedia.org/wiki/Uniform_distribution_(continuous)

src/algorithms/randomness/rand.md

@@ -1,5 +1,3 @@
-[ex-rand]: #ex-rand
-<a name="ex-rand"></a>
 ## Generate random numbers
 
 [![rand-badge]][rand] [![cat-science-badge]][cat-science]

src/cli/arguments.md

@@ -1,3 +1,3 @@
-{{#include clap-basic.md}}
+{{#include arguments/clap-basic.md}}
 
 {{#include ../links.md}}

src/cli/clap-basic.md → src/cli/arguments/clap-basic.md

@@ -1,9 +1,16 @@
-[ex-clap-basic]: #ex-clap-basic
-<a name="ex-clap-basic"></a>
 ## Parse command line arguments
 
 [![clap-badge]][clap] [![cat-command-line-badge]][cat-command-line]
 
+This application describes the structure of its command-line interface using
+`clap`'s builder style. The [documentation] gives two other possible ways to
+instantiate an application.
+
+In the builder style, `with_name` is the unique identifier that `value_of` will
+use to retrieve the value passed. The `short` and `long` options control the
+flag the user will be expected to type; short flags look like `-f` and long
+flags look like `--file`.
+
 ```rust
 extern crate clap;
 
@@ -45,19 +52,6 @@ fn main() {
 }
 ```
 
-The `clap` crate is a simple-to-use, efficient, and full-featured library for
-parsing command line arguments and subcommands when writing console/terminal
-applications.
-
-The application can describe the structure of its command-line interface using
-`clap`'s builder style. The [documentation] gives two other possible ways to
-instantiate an application.
-
-In the builder style, `with_name` is the unique identifier that `value_of` will
-use to retrieve the value passed. The `short` and `long` options control the
-flag the user will be expected to type; short flags look like `-f` and long
-flags look like `--file`.
-
 Usage information is generated by `clap`. The usage for the example application
 looks like this.
 

src/compression/tar/tar-compress.md

@@ -1,10 +1,8 @@
-[ex-tar-compress]: #ex-tar-compress
-<a name="ex-tar-compress"></a>
 ## Compress a directory into tarball
 
 [![flate2-badge]][flate2] [![tar-badge]][tar] [![cat-compression-badge]][cat-compression]
 
-Compresses `/var/log` directory into `archive.tar.gz`.
+Compress `/var/log` directory into `archive.tar.gz`.
 
 Creates a [`File`] wrapped in [`GzEncoder`]
 and [`tar::Builder`]. </br>Adds contents of `/var/log` directory recursively into the archive

src/compression/tar/tar-decompress.md

@@ -1,12 +1,11 @@
-[ex-tar-decompress]: #ex-tar-decompress
-<a name="ex-tar-decompress"></a>
 ## Decompress a tarball
 
 [![flate2-badge]][flate2] [![tar-badge]][tar] [![cat-compression-badge]][cat-compression]
 
 Decompress ([`GzDecoder`]) and
 extract ([`Archive::unpack`]) all files from a compressed tarball
-named `archive.tar.gz` located in the current working directory.
+named `archive.tar.gz` located in the current working directory
+to the same location.
 
 ```rust,no_run
 # #[macro_use]

src/compression/tar/tar-strip-prefix.md

@@ -1,13 +1,9 @@
-[ex-tar-strip-prefix]: #ex-tar-strip-prefix
-<a name="ex-tar-strip-prefix"></a>
 ## Decompress a tarball while removing a prefix from the paths
 
 [![flate2-badge]][flate2] [![tar-badge]][tar] [![cat-compression-badge]][cat-compression]
 
-Strip a path prefix from the entries of a tarball before unpacking them.
-
-We iterate over the [`Archive::entries`], using [`Path::strip_prefix`] to remove
-the specified path prefix (`bundle/logs`) before extracting the [`tar::Entry`]
+Iterate over the [`Archive::entries`].  Use [`Path::strip_prefix`] to remove
+the specified path prefix (`bundle/logs`).  Finally, extract the [`tar::Entry`]
 via [`Entry::unpack`].
 
 ```rust,no_run

src/concurrency/parallel/rayon-any-all.md

@@ -1,5 +1,3 @@
-[ex-rayon-any-all]: #ex-rayon-any-all
-<a name="ex-rayon-any-all"></a>
 ## Test in parallel if any or all elements of a collection match a given predicate
 
 [![rayon-badge]][rayon] [![cat-concurrency-badge]][cat-concurrency]

src/concurrency/parallel/rayon-iter-mut.md

@@ -1,11 +1,10 @@
-<a name="ex-rayon-iter-mut"></a>
 ## Mutate the elements of an array in parallel
 
 [![rayon-badge]][rayon] [![cat-concurrency-badge]][cat-concurrency]
 
 The example uses the `rayon` crate, which is a data parallelism library for Rust.
 `rayon` provides the [`par_iter_mut`] method for any parallel iterable data type.
-It lets us write iterator-like chains that execute in parallel.
+This is an iterator-like chain that potentially executes in parallel.
 
 ```rust
 extern crate rayon;

src/concurrency/parallel/rayon-map-reduce.md

@@ -1,18 +1,15 @@
-[ex-rayon-map-reduce]: #ex-rayon-map-reduce
-<a name="ex-rayon-map-reduce"></a>
 ## Map-reduce in parallel
 
 [![rayon-badge]][rayon] [![cat-concurrency-badge]][cat-concurrency]
 
 This example uses [`rayon::filter`], [`rayon::map`], and [`rayon::reduce`]
-to calculate the conditional average age of a vector of `Person` objects.
-
-[`rayon::filter`] allows (in parallel) conditional inclusion of elements from
-a collection that satisfy the given predicate.  Similarly, [`rayon::map`] and
-[`rayon::reduce`] allow us to transform the filtered elements via a unary
-operation and reduce them to a single value via a given binary operation,
-respectively.  Also shows use of [`rayon::sum`], which has the same result as
-the reduce operation in this example.
+to calculate the average age of `Person` objects whose age is over 30.
+
+[`rayon::filter`] returns elements from a collection that satisfy the given
+predicate.  [`rayon::map`] performs an operation on every element, creating a
+new iteration, and [`rayon::reduce`] performs an operation given the previous
+reduction and the current element.  Also shows use of [`rayon::sum`],
+which has the same result as the reduce operation in this example.
 
 ```rust
 extern crate rayon;

src/concurrency/parallel/rayon-parallel-search.md

@@ -1,5 +1,3 @@
-[ex-rayon-parallel-search]: #ex-rayon-parallel-search
-<a name="ex-rayon-parallel-search"></a>
 ## Search items using given predicate in parallel
 
 [![rayon-badge]][rayon] [![cat-concurrency-badge]][cat-concurrency]
@@ -8,11 +6,11 @@ This example uses [`rayon::find_any`] and [`par_iter`] to search a vector in
 parallel for an element satisfying the predicate in the given closure.
 
 If there are multiple elements satisfying the predicate defined in the closure
-argument of [`rayon::find_any`], we are only guaranteed that one of them will be
-found, but not necessarily that the first will be found.
+argument of [`rayon::find_any`], `rayon` returns the first one found, not
+necessarily the first one.
 
 Also note that the argument to the closure is a reference to a reference
-(`&&x`). Please see the discussion on [`std::find`] for additional details.
+(`&&x`). See the discussion on [`std::find`] for additional details.
 
 ```rust
 extern crate rayon;

src/concurrency/parallel/rayon-parallel-sort.md

@@ -1,19 +1,13 @@
-[ex-rayon-parallel-sort]: #ex-rayon-parallel-sort
-<a name="ex-rayon-parallel-sort"></a>
 ## Sort a vector in parallel
 
 [![rayon-badge]][rayon] [![rand-badge]][rand] [![cat-concurrency-badge]][cat-concurrency]
 
 This example will sort in parallel a vector of Strings.
 
-[1] We start by preallocating a vector of empty Strings, so we can mutate the information in parallel later,
-to populate the vector with random Strings.
-
-[2] `par_iter_mut().for_each` takes a closure and applies it in parallel on all the elements of the vector.<br/>
-[3] Inside the passed closure we modify the element in the vector with a 5 character-long String, random generated.
-
-[4] We have [multiple options] to sort an Iterable data type, we chose here to use [`par_sort_unstable`]
-because it is usually faster than [stable sorting] algorithms which `rayon` also supports.
+Allocate a vector of empty Strings. `par_iter_mut().for_each` populates random
+values in parallel.  Although [multiple options]
+exist to sort an enumerable data type, [`par_sort_unstable`]
+is usually faster than [stable sorting] algorithms.
 
 ```rust
 extern crate rand;

src/concurrency/parallel/rayon-thumbnails.md

@@ -1,12 +1,12 @@
-[ex-rayon-thumbnails]: #ex-rayon-thumbnails
-<a name="ex-rayon-thumbnails"></a>
 ## Generate jpg thumbnails in parallel
 
 [![rayon-badge]][rayon] [![glob-badge]][glob] [![image-badge]][image] [![cat-concurrency-badge]][cat-concurrency] [![cat-filesystem-badge]][cat-filesystem]
 
-This example generates thumbnails for all .jpg in the current directory and saves them in a new folder called `thumbnails`.
+This example generates thumbnails for all .jpg files in the current directory
+then saves them in a new folder called `thumbnails`.
 
-Files are found using [`glob::glob_with`] to match case insensitively on both `.jpg` and `.JPG`. `rayon` is then used to resize images in parallel using [`par_iter`] along with the `make_thumbnail()` helper function which internally uses [`DynamicImage::resize`].
+[`glob::glob_with`] finds jpeg files in current directory. `rayon` resizes
+images in parallel using [`par_iter`] calling  [`DynamicImage::resize`].
 
 ```rust,no_run
 # #[macro_use]

src/concurrency/thread/crossbeam-spawn.md

@@ -1,5 +1,3 @@
-[ex-crossbeam-spawn]: #ex-crossbeam-spawn
-<a name="ex-crossbeam-spawn"></a>
 ## Spawn a short-lived thread
 
 [![crossbeam-badge]][crossbeam] [![cat-concurrency-badge]][cat-concurrency]
@@ -9,6 +7,8 @@ for concurrent and parallel programming. [`Scope::spawn`] spawns a new scoped th
 to terminate before returning from the closure that passed into [`crossbeam::scope`] function, meaning that
 you can reference data from the calling function.
 
+This example splits the array in half and performs the work in separate threads.  
+
 ```rust
 extern crate crossbeam;
 

src/concurrency/thread/global-mut-state.md

@@ -1,12 +1,10 @@
-[ex-global-mut-state]: #ex-global-mut-state
-<a name="ex-global-mut-state"></a>
 ## Maintain global mutable state
 
 [![lazy_static-badge]][lazy_static] [![cat-rust-patterns-badge]][cat-rust-patterns]
 
-Declares some global state using [lazy_static]. Since [lazy_static]
-creates a globally available `static ref` we also need to wrap our state
-in a [`Mutex`] to allow mutation (also see [`RwLock`]). The [`Mutex`] ensures
+Declare global state using [lazy_static]. [lazy_static]
+creates a globally available `static ref` which requires a [`Mutex`]
+to allow mutation (also see [`RwLock`]). The [`Mutex`] wrap ensures
 the state cannot be simultaneously accessed by multiple threads, preventing
 race conditions. A [`MutexGuard`] must be acquired to read or mutate the
 value stored in a [`Mutex`].

src/concurrency/thread/threadpool-fractal.md

@@ -1,20 +1,20 @@
-[ex-threadpool-fractal]: #ex-threadpool-fractal
-<a name="ex-threadpool-fractal"></a>
 ## Draw fractal dispatching work to a thread pool
 
 [![threadpool-badge]][threadpool] [![num-badge]][num] [![num_cpus-badge]][num_cpus] [![image-badge]][image] [![cat-concurrency-badge]][cat-concurrency][![cat-science-badge]][cat-science][![cat-rendering-badge]][cat-rendering]
 
-This example draws a fractal from [Julia set] to an image utilizing a thread pool for computation.
+This example generates an image by drawing a fractal from the [Julia set]
+with a thread pool for distributed computation.
 
 <a href="https://cloud.githubusercontent.com/assets/221000/26546700/9be34e80-446b-11e7-81dc-dd9871614ea1.png"><img src="https://cloud.githubusercontent.com/assets/221000/26546700/9be34e80-446b-11e7-81dc-dd9871614ea1.png" width="150" /></a>
 
-Firstly, the example allocates memory for output image of given width and height with [`ImageBuffer::new`]
-and pre-calculates all possible RGB pixel values using [`Rgb::from_channels`].
-Secondly, creates a new [`ThreadPool`] with thread count equal to number of
-logical cores in CPU obtained with [`num_cpus::get`].
-Subsequently, dispatches calculation to thread pool [`ThreadPool::execute`].
+Allocate memory for output image of given width and height with [`ImageBuffer::new`].
+[`Rgb::from_channels`] calculates RGB pixel values.
+Create [`ThreadPool`] with thread count equal to number of cores with [`num_cpus::get`].
+[`ThreadPool::execute`] receives each pixel as a separate job.
 
-Lastly, collects calculation results via [`mpsc::channel`] with [`Receiver::recv`], draws them with [`ImageBuffer::put_pixel`] and encodes the final image into `output.png` using [`ImageBuffer::save`].
+[`mpsc::channel`] receives the jobs and [`Receiver::recv`] retrieves them.
+[`ImageBuffer::put_pixel`] uses the data to set the pixel color.
+[`ImageBuffer::save`] writes the image to `output.png`.
 
 ```rust,no_run
 # #[macro_use]

src/concurrency/thread/threadpool-walk.md

@@ -1,11 +1,12 @@
-[ex-threadpool-walk]: #ex-threadpool-walk
-<a name="ex-threadpool-walk"></a>
-
 ## Calculate SHA1 sum of iso files concurrently
 
 [![threadpool-badge]][threadpool] [![num_cpus-badge]][num_cpus] [![walkdir-badge]][walkdir] [![ring-badge]][ring] [![cat-concurrency-badge]][cat-concurrency][![cat-filesystem-badge]][cat-filesystem]
 
-This example calculates the SHA1 for every file present in the current directory. A threadpool is created using the number of cpus present in the system with [`num_cpus::get`]. Then every returned by [`Walkdir::new`] is passed into this pool to perform the operations of reading and computing SHA1. At the end the program waits for all jobs to finish. To get better results, compile this program in release mode.
+This example calculates the SHA1 for every file with iso extension in the
+current directory. A threadpool generates threads equal to the number of cores
+present in the system found with [`num_cpus::get`].  [`Walkdir::new`] iterates
+the current directory and calls [`execute`] to perform the operations of reading
+and computing SHA1 hash.
 
 ```rust,no_run
 # #[macro_use]
@@ -83,5 +84,6 @@ fn run() -> Result<()> {
 # quick_main!(run);
 ```
 
+[`execute`]: https://docs.rs/threadpool/*/threadpool/struct.ThreadPool.html#method.execute
 [`num_cpus::get`]: https://docs.rs/num_cpus/*/num_cpus/fn.get.html
 [`Walkdir::new`]: https://docs.rs/walkdir/*/walkdir/struct.WalkDir.html#method.new

src/cryptography/encryption/pbkdf2.md

@@ -4,7 +4,7 @@
 [![ring-badge]][ring] [![data-encoding-badge]][data-encoding] [![cat-cryptography-badge]][cat-cryptography]
 
 Uses [`ring::pbkdf2`] to hash a salted password using the PBKDF2 key derivation
-function [`pbkdf2::derive`] and then verifies the hash is correct with
+function [`pbkdf2::derive`].  Verifies the hash is correct with
 [`pbkdf2::verify`]. The salt is generated using
 [`SecureRandom::fill`], which fills the salt byte array with
 securely generated random numbers.
@@ -73,7 +73,7 @@ fn run() -> Result<()> {
 # quick_main!(run);
 ```
 
-[`pbkdf2::derive`]: https://docs.rs/ring/v0.4/ring/pbkdf2/fn.derive.html
-[`pbkdf2::verify`]: https://docs.rs/ring/v0.4/ring/pbkdf2/fn.verify.html
-[`ring::pbkdf2`]: https://docs.rs/ring/v0.4/ring/pbkdf2/index.html
-[`SecureRandom::fill`]: https://docs.rs/ring/*/ring/rand/trait.SecureRandom.html#tymethod.fill
+[`pbkdf2::derive`]: https://briansmith.org/rustdoc/ring/pbkdf2/fn.derive.html
+[`pbkdf2::verify`]: https://briansmith.org/rustdoc/ring/pbkdf2/fn.verify.html
+[`ring::pbkdf2`]: https://briansmith.org/rustdoc/ring/pbkdf2/index.html
+[`SecureRandom::fill`]: https://briansmith.org/rustdoc/ring/rand/trait.SecureRandom.html#tymethod.fill

src/cryptography/hashing/hmac.md

@@ -1,4 +1,3 @@
-<a name="ex-hmac"></a>
 ## Sign and verify a message with HMAC digest
 
 [![ring-badge]][ring] [![cat-cryptography-badge]][cat-cryptography]
@@ -35,5 +34,5 @@ fn run() -> Result<()> {
 # quick_main!(run);
 ```
 
-[`hmac::Signature`]: https://docs.rs/ring/v0.4/ring/hmac/struct.Signature.html
-[`ring::hmac`]: https://docs.rs/ring/v0.4/ring/hmac/
+[`hmac::Signature`]: https://briansmith.org/rustdoc/ring/hmac/struct.Signature.html
+[`ring::hmac`]: https://briansmith.org/rustdoc/ring/hmac/

src/cryptography/hashing/sha-digest.md

@@ -1,4 +1,3 @@
-<a name="ex-sha-digest"></a>
 ## Calculate the SHA-256 digest of a file
 
 [![ring-badge]][ring] [![data-encoding-badge]][data-encoding] [![cat-cryptography-badge]][cat-cryptography]
@@ -58,5 +57,5 @@ fn run() -> Result<()> {
 # quick_main!(run);
 ```
 
-[`digest::Context`]: https://docs.rs/ring/*/ring/digest/struct.Context.html
-[`digest::Digest`]: https://docs.rs/ring/*/ring/digest/struct.Digest.html
+[`digest::Context`]: https://briansmith.org/rustdoc/ring/digest/struct.Context.html
+[`digest::Digest`]: https://briansmith.org/rustdoc/ring/digest/struct.Digest.html

src/data_structures/constant/lazy-constant.md

@@ -1,4 +1,3 @@
-<a name="ex-lazy-constant"></a>
 ## Declare lazily evaluated constant
 
 [![lazy_static-badge]][lazy_static] [![cat-caching-badge]][cat-caching] [![cat-rust-patterns-badge]][cat-rust-patterns]

src/data_structures/custom/bitfield.md

@@ -1,9 +1,8 @@
-<a name="ex-bitflags"></a>
 ## Define and operate on a type represented as a bitfield
 
 [![bitflags-badge]][bitflags] [![cat-no-std-badge]][cat-no-std]
 
-Creates typesafe bitfield type `MyFlags` with help of [`bitflags!`] macro
+Creates type safe bitfield type `MyFlags` with help of [`bitflags!`] macro
 and implements elementary `clear` operation as well as [`Display`] trait for it.
 Subsequently, shows basic bitwise operations and formatting.