Fix markdown issues and add linter to CI

Found via `markdownlint -f --disable MD004 MD013 MD033 MD036 MD042 --
**/*.md`

See a detailed description of the rules is available at
https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md

Also added `markdowlint` to CI pipeline.

Author: kianmeng

.github/workflows/ci.yml

@@ -15,9 +15,15 @@ jobs:
     env:
       RUSTFLAGS: -D warnings
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           ref: ${{ github.event.pull_request.head.sha }}
+      - uses: DavidAnson/markdownlint-cli2-action@v10
+        with:
+          command: config
+          globs: |
+            .markdownlint.yaml
+            '**/*.md'
       - uses: actions-rs/toolchain@v1
         with:
           toolchain: stable

.markdownlint.yaml

@@ -0,0 +1,6 @@
+# markdownlint configuration
+MD004: false
+MD013: false
+MD033: false
+MD036: false
+MD042: false

README.md

@@ -20,7 +20,6 @@ git clone https://github.com/sunshowers-code/rust-cli-recommendations --branch g
 
 then pointing your web browser at `rust-cli-recommendations/index.html`.
 
-
 Pull requests to fix typos or unclear language are welcome! If you have a suggestion for a change to the document, please [search through the issues] to see if it's been discussed already. If not, please [open an issue].
 
 [search through the issues]: https://github.com/sunshowers-code/rust-cli-recommendations/issues?q=is%3Aissue+sort%3Aupdated-desc

src/SUMMARY.md

@@ -3,19 +3,25 @@
 - [Introduction](../README.md)
 - [Picking an argument parser](./cli-parser.md)
   - [Handling arguments and subcommands](./handling-arguments.md)
+
 ---
+
 - [Binaries vs libraries](./binaries-vs-libraries.md)
   - [Machine-readable output](./machine-readable-output.md)
   - [Organizing code in binary crates](./organizing-binary.md)
 - [Versioning](./versioning.md)
+
 ---
+
 - [Adding colors to applications](./colors.md)
   - [Managing colors in Rust](./managing-colors-in-rust.md)
 
 - [Configuration](./configuration.md)
   - [Hierarchical configuration](./hierarchical-config.md)
   - [Merging command-line arguments and config files]()
+
 ---
+
 - [Dry runs and the interpreter pattern]()
 - [Logging]()
 - [Error handling and exit codes]()

src/binaries-vs-libraries.md

@@ -3,10 +3,12 @@
 You *may* expose your application's functionality as a library. Some binaries are simple and don't necessarily need to expose their functionality as a library. Other binaries are more complex, in which case their functionality can be exposed as a library that others can build upon.
 
 **Why separate libraries from binaries?**
+
 * For other consumers of the library, clap and other binary-only dependencies are unnecessary.
 * The binary's versioning is separated out from the library's versioning; see [Versioning](versioning.html) for more.
 
 **Reasons against exposing a library**
+
 * Maintaining a library in addition to a binary is hard work. It involves documentation and versioning.
 * In some cases, maintainers can decide to expose their functionality *only* as a binary to force a looser coupling with downstream consumers.
   * *Case study:* The presence of the [libgit2](https://libgit2.org/) and [JGit](https://www.eclipse.org/jgit/) libraries for Git has made it significantly harder to improve Git's data structures. These libraries are tightly coupled to their consumers, which in practice means that Git improvements are tied to the release schedules of commercial projects like Xcode and Visual Studio.
@@ -17,14 +19,17 @@ You *may* expose your application's functionality as a library. Some binaries ar
 > Note: In this section, "package" means all code scoped to a single `Cargo.toml` file.
 
 If your code is meant to be uploaded to a registry like crates.io:
+
 * Binary packages *must not* expose their library functionality within the same package.
 * The library package *must* be separated out, with an appropriate name linking the two.
 
 If your code is internal to the workspace:
+
 * Binary packages *should not* expose a library within the same package.
 * The library package *should* be separated out, with an appropriate name linking the two.
 
 Some examples of linked names:
+
 * *my-lib* for the library, and *my-lib-cli* for the binary, if most people are going to use the library.
 * *my-app-core* for the library, and *my-app* for the binary, if most people are going to use the binary.
 * *my-utility* for the library, and *cargo-my-utility* for the binary, if your program is a Cargo plugin.

src/cli-parser.md

@@ -4,12 +4,14 @@ When you're writing a Rust command-line application, one of the first things you
 There are a number of different command-line parsers for Rust programs. However, projects *should* use [**clap**](https://crates.io/crates/clap).
 
 **Why?**
+
 * clap is actively maintained: as of January 2022, clap just came out with a [v3 release]().
 * clap is the most popular command-line parsing library for Rust, which means that there's an existing ecosystem of projects around clap.
 * clap comes with a number of extra features, such as suggestions based on [Jaro–Winkler distance](https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance) and full configurability of [commands](https://docs.rs/clap/latest/clap/enum.AppSettings.html) and [arguments](https://docs.rs/clap/latest/clap/enum.ArgSettings.html).
 * There are a number of standard conventions for Unix CLIs: see [this comment](https://github.com/google/argh/issues/3#issuecomment-581144181) by [Stephen Sokolow](https://github.com/ssokolow). clap supports all of them. Another actively maintained project, [argh](https://github.com/google/argh), does not target Unix platforms and so does not support all of these conventions.
 
 **Reasons against using clap**
+
 * clap pulls in several dependencies and takes quite a while to build.
 * clap increases binary size significantly.
 * clap is a complex parser with many different options. I've found uses for most of them, but they can be overwhelming.
@@ -32,10 +34,12 @@ The doc comments are processed as help text by clap. Here's what the help text l
 ```
 
 **Why?**
+
 * Derive-style arguments are significantly easier to read, write, and modify.
 * Derive-style components can be written once, and reused across multiple commands.
 
 **Why not?**
+
 * The derive macro is an optional feature that pulls in extra dependencies and increases build times.
 * The derive macro can be a bit magical. Looking at [the source code of clap_derive](https://github.com/clap-rs/clap/blob/master/clap_derive/src/lib.rs), or the generated output with [cargo-expand](https://crates.io/crates/cargo-expand), may be useful.
 * The derive macro is less flexible than the builder API. For example, for an argument used multiple times like `-v -v -v`, the builder API can tell you exactly which position each `-v` was used in. The derive macro can only tell you how many times `-v` was used.
@@ -45,6 +49,7 @@ The doc comments are processed as help text by clap. Here's what the help text l
 ## Command and argument case
 
 Following Unix and GNU conventions, all commands and arguments, except for short arguments, *must* be in [kebab case](https://en.wikipedia.org/wiki/Kebab_case). This means that:
+
 * Commands and arguments *must* be in lowercase.
 * Multiple words *must* be separated by hyphens: `--example-opt`, not `--example_opt` or `--exampleOpt`.
 

src/colors.md

@@ -20,11 +20,13 @@ These rules apply to all command-line programs, not just Rust ones.
 ## Color palettes
 
 Terminals may support one of three color palettes:
+
 * *16 colors:* 4-bit color; black, red, green, yellow, blue, magenta, cyan, white, and a "bright" version of each.
 * *256 colors:* 8-bit color; the 16 colors above, a 6×6×6 cube for each of red, green and blue, and 24 grayscale tones. [This page by Pádraig Brady](http://www.pixelbeat.org/docs/terminal_colours/#256) has more information about them.
 * *Truecolor (16 million colors):* 24-bit color; 8 bits for each of red, green and blue. This is the standard that web pages and most monitors support. You may have seen these colors written as e.g. <span style="color:#9b4fd1">#9b4fd1</span>.
 
 **The default color schemes in applications *must* be restricted to 12 colors: red, green, yellow, blue, magenta, cyan, and the bright versions of each of these.**
+
 * While the wider palettes are useful for terminal theming controlled by the user, applications *must not* use them by default. The reason is that users may be using a variety of terminal themes with different backgrounds. **Truecolors and 8-bit colors will not render properly with all terminal themes.** Light-colored text will fade into a light background, and dark-colored text will fade into a dark background.
 * Most terminals allow you to configure these colors to whatever one pleases. In most themes, these 12 colors are set to contrast with the background.
 <tt><span style="color: #acacab; background-color:#050505">Themes with dark backgrounds <span style="color: #a9cdeb">set "blue" to be lighter</span></span></tt>,

src/configuration.md

@@ -13,6 +13,7 @@ Some utilities require more expressive power in their configuration; for example
 ## Configuration scopes
 
 Depending on the application, the following scopes for a configuration are often seen in practice:
+
 1. *Directory-scoped.* Applies to a directory and its subdirectories. Controlled by a file somewhere in this directory or a parent. For example, [`.gitignore`](https://git-scm.com/docs/gitignore) is directory-scoped.
 2. *Repository-scoped.* Applies to a repository: controlled by a file somewhere in a code repository. For example, [`clippy.toml`](https://github.com/rust-lang/rust-clippy#configuration) is repository-scoped.
 3. *User-scoped.* A file somewhere in the user's home directory.
@@ -21,16 +22,19 @@ Depending on the application, the following scopes for a configuration are often
 Not all applications support all of these: which scopes make sense is a matter of judgment and thinking about use cases. Some server-side applications support fetching configuration from a remote server; they are out of scope here.
 
 **If applications support repository-scoped configuration:**
+
 * Applications *should* put repository-scoped configuration in a `.config` directory under the repository root. Typically, applications place their configuration at the top level of the repository. However, too many config files at the top level can pollute directory listings.
 * Applications *should* allow both local and checked-in configuration files. For example, an application `myapp` should support configuration in both `.config/myapp.toml` and `.config/myapp.local.toml`. Entries in `./config/myapp.local.toml` *must* override those in `.config/myapp.toml`.
 
 **If applications support user-scoped configuration:**
+
 * On Unix platforms other than macOS, applications *should* follow the [XDG specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
 * On macOS and Windows, applications *should* either use `$HOME/.config` or the platform-native config directory. On macOS and Windows, the platform-native directories are somewhat harder to access on the command line, so `$HOME/.config` is a suitable alternative.
 
 [dirs](https://crates.io/crates/dirs) is the most actively maintained Rust library for getting the native config directory (and other directories) for every platform.
 
 **Applications *may* read configuration options over the command line and the environment.** It is often reasonable to let users override configuration via command-line options and environment variables. If so, then:
+
 * Environment variables *must* be prefixed with a unique identifier based on the app. For example, an app called `myapp` can support a "limit" configuration through a `MYAPP_LIMIT` variable.
 * Environment variables *should* also be supported as command-line options. For example, `myapp --limit`. Command-line options are more discoverable than environment variables. If you actually *want* your options to be less discoverable, for example if exposing them would increase support load, you can add hidden command-line options.
 * Command-line arguments *must* override environment variables. An environment variable can be set further up in the environment. A command-line argument expresses user intent most directly.

src/handling-arguments.md

@@ -7,6 +7,7 @@ For a program that has subcommands, the following code structure is *recommended
 ```
 
 Notes:
+
 * **Only the top-level `App` is public.**
 * **`App` is a struct, one level above the command enum.**
   * While it is possible to make `App` an enum with all the subcommands, in my experience this design has always come back to bite me. This has always been because I've wanted to introduce global options later.

src/hierarchical-config.md

@@ -1,6 +1,7 @@
 # Hierarchical configuration
 
 **Applications *should* follow a hierarchical configuration structure.** Use the following order, from highest priority to lowest.
+
 1. Command-line arguments
 2. Environment variables
 3. Directory or repository-scoped configuration