Merge pull request #4457 from sylvestre/md-check

Various improvements in the docs

.github/workflows/CICD.yml

@@ -291,7 +291,13 @@ jobs:
       shell: bash
       run: |
         RUSTDOCFLAGS="-Dwarnings" cargo doc  ${{ steps.vars.outputs.CARGO_FEATURES_OPTION }} --no-deps --workspace --document-private-items
-
+    - uses: DavidAnson/markdownlint-cli2-action@v9
+      with:
+        command: fix
+        globs: |
+          *.md
+          docs/src/*.md
+          src/uu/*/*.md
 
   min_version:
     name: MinRustV # Minimum supported rust version (aka, MinSRV or MSRV)

.markdownlint.yaml

@@ -0,0 +1,6 @@
+# Disable 'Line length'. Doesn't provide much values
+MD013: false
+# Disable 'Fenced code blocks should have a language specified'
+# Doesn't provide much in src/ to enforce it
+MD040: false
+

CODE_OF_CONDUCT.md

@@ -116,7 +116,7 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
@@ -124,5 +124,5 @@ enforcement ladder](https://github.com/mozilla/diversity).
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

CONTRIBUTING.md

@@ -38,20 +38,19 @@ search the issues to make sure no one else is working on it.
 
 ## Platforms
 
-We take pride in supporting many operating systems and architectures. 
+We take pride in supporting many operating systems and architectures.
 
 **Tip:**
-For Windows, Microsoft provides some images (VMWare, Hyper-V, VirtualBox and Parallels) 
+For Windows, Microsoft provides some images (VMWare, Hyper-V, VirtualBox and Parallels)
 for development:
-https://developer.microsoft.com/windows/downloads/virtual-machines/
-
+<https://developer.microsoft.com/windows/downloads/virtual-machines/>
 
 ## Commit messages
 
 To help the project maintainers review pull requests from contributors across
 numerous utilities, the team has settled on conventions for commit messages.
 
-From http://git-scm.com/book/ch5-2.html:
+From <http://git-scm.com/book/ch5-2.html>:
 
 ```
 Short (50 chars or less) summary of changes

DEVELOPER_INSTRUCTIONS.md

@@ -1,21 +1,19 @@
-Documentation
--------------
+# Documentation
 
 The source of the documentation is available on:
 
-https://uutils.github.io/dev/coreutils/
+<https://uutils.github.io/dev/coreutils/>
 
 The documentation is updated everyday on this repository:
 
-https://github.com/uutils/uutils.github.io/
+<https://github.com/uutils/uutils.github.io/>
 
-Running GNU tests
------------------
+## Running GNU tests
 
 <!-- spell-checker:ignore gnulib -->
 
-- Check out https://github.com/coreutils/coreutils next to your fork as gnu
-- Check out https://github.com/coreutils/gnulib next to your fork as gnulib
+- Check out <https://github.com/coreutils/coreutils> next to your fork as gnu
+- Check out <https://github.com/coreutils/gnulib> next to your fork as gnulib
 - Rename the checkout of your fork to uutils
 
 At the end you should have uutils, gnu and gnulib checked out next to each other.
@@ -23,9 +21,7 @@ At the end you should have uutils, gnu and gnulib checked out next to each other
 - Run `cd uutils && ./util/build-gnu.sh && cd ..` to get everything ready (this may take a while)
 - Finally, you can run tests with `bash uutils/util/run-gnu-test.sh <tests>`. Instead of `<tests>` insert the tests you want to run, e.g. `tests/misc/wc-proc.sh`.
 
-
-Code Coverage Report Generation
----------------------------------
+## Code Coverage Report Generation
 
 <!-- spell-checker:ignore (flags) Ccodegen Coverflow Cpanic Zinstrument Zpanic -->
 
@@ -35,14 +31,14 @@ Code coverage report can be generated using [grcov](https://github.com/mozilla/g
 
 To generate [gcov-based](https://github.com/mozilla/grcov#example-how-to-generate-gcda-files-for-a-rust-project) coverage report
 
-```bash
-$ export CARGO_INCREMENTAL=0
-$ export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"
-$ export RUSTDOCFLAGS="-Cpanic=abort"
-$ cargo build <options...> # e.g., --features feat_os_unix
-$ cargo test <options...> # e.g., --features feat_os_unix test_pathchk
-$ grcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing --ignore build.rs --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?\#\[derive\()" -o ./target/debug/coverage/
-$ # open target/debug/coverage/index.html in browser
+```shell
+export CARGO_INCREMENTAL=0
+export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"
+export RUSTDOCFLAGS="-Cpanic=abort"
+cargo build <options...> # e.g., --features feat_os_unix
+cargo test <options...> # e.g., --features feat_os_unix test_pathchk
+grcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing --ignore build.rs --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?\#\[derive\()" -o ./target/debug/coverage/
+# open target/debug/coverage/index.html in browser
 ```
 
 if changes are not reflected in the report then run `cargo clean` and run the above commands.
@@ -52,19 +48,21 @@ if changes are not reflected in the report then run `cargo clean` and run the ab
 If you are using stable version of Rust that doesn't enable code coverage instrumentation by default
 then add `-Z-Zinstrument-coverage` flag to `RUSTFLAGS` env variable specified above.
 
-
-pre-commit hooks
-----------------
+## pre-commit hooks
 
 A configuration for `pre-commit` is provided in the repository. It allows automatically checking every git commit you make to ensure it compiles, and passes `clippy` and `rustfmt` without warnings.
 
 To use the provided hook:
 
 1. [Install `pre-commit`](https://pre-commit.com/#install)
-2. Run `pre-commit install` while in the repository directory
+1. Run `pre-commit install` while in the repository directory
 
 Your git commits will then automatically be checked. If a check fails, an error message will explain why, and your commit will be canceled. You can then make the suggested changes, and run `git commit ...` again.
 
-### Using Clippy
+## Using Clippy
 
 The `msrv` key in the clippy configuration file `clippy.toml` is used to disable lints pertaining to newer features by specifying the minimum supported Rust version (MSRV). However, this key is only supported on `nightly`. To invoke clippy without errors, use `cargo +nightly clippy`. In order to also check tests and non-default crate features, use `cargo +nightly clippy --all-targets --all-features`.
+
+## Markdown linter
+
+We use <https://github.com/DavidAnson/markdownlint> to lint the Markdown files.

README.md

@@ -21,11 +21,12 @@ or different behavior might be experienced.
 
 To install it:
 
-```
-$ cargo install coreutils
-$ ~/.cargo/bin/coreutils
+```shell
+cargo install coreutils
+~/.cargo/bin/coreutils
 ```
 
+<!-- markdownlint-disable-next-line MD026 -->
 ## Why?
 
 uutils aims to work on as many platforms as possible, to be able to use the
@@ -35,6 +36,7 @@ chosen not only because it is fast and safe, but is also excellent for
 writing cross-platform code.
 
 ## Documentation
+
 uutils has both user and developer documentation available:
 
 - [User Manual](https://uutils.github.io/user/)
@@ -46,8 +48,8 @@ Both can also be generated locally, the instructions for that can be found in th
 <!-- ANCHOR: build (this mark is needed for mdbook) -->
 ## Requirements
 
-* Rust (`cargo`, `rustc`)
-* GNU Make (optional)
+- Rust (`cargo`, `rustc`)
+- GNU Make (optional)
 
 ### Rust Version
 
@@ -64,9 +66,9 @@ or GNU Make.
 
 For either method, we first need to fetch the repository:
 
-```bash
-$ git clone https://github.com/uutils/coreutils
-$ cd coreutils
+```shell
+git clone https://github.com/uutils/coreutils
+cd coreutils
 ```
 
 ### Cargo
@@ -74,8 +76,8 @@ $ cd coreutils
 Building uutils using Cargo is easy because the process is the same as for
 every other Rust program:
 
-```bash
-$ cargo build --release
+```shell
+cargo build --release
 ```
 
 This command builds the most portable common core set of uutils into a multicall
@@ -85,20 +87,20 @@ Additional platform-specific uutils are often available. Building these
 expanded sets of uutils for a platform (on that platform) is as simple as
 specifying it as a feature:
 
-```bash
-$ cargo build --release --features macos
+```shell
+cargo build --release --features macos
 # or ...
-$ cargo build --release --features windows
+cargo build --release --features windows
 # or ...
-$ cargo build --release --features unix
+cargo build --release --features unix
 ```
 
 If you don't want to build every utility available on your platform into the
 final binary, you can also specify which ones you want to build manually.
 For example:
 
-```bash
-$ cargo build --features "base32 cat echo rm" --no-default-features
+```shell
+cargo build --features "base32 cat echo rm" --no-default-features
 ```
 
 If you don't want to build the multicall binary and would prefer to build
@@ -107,8 +109,8 @@ is contained in its own package within the main repository, named
 "uu_UTILNAME". To build individual utilities, use cargo to build just the
 specific packages (using the `--package` [aka `-p`] option). For example:
 
-```bash
-$ cargo build -p uu_base32 -p uu_cat -p uu_echo -p uu_rm
+```shell
+cargo build -p uu_base32 -p uu_cat -p uu_echo -p uu_rm
 ```
 
 ### GNU Make
@@ -117,30 +119,30 @@ Building using `make` is a simple process as well.
 
 To simply build all available utilities:
 
-```bash
-$ make
+```shell
+make
 ```
 
 To build all but a few of the available utilities:
 
-```bash
-$ make SKIP_UTILS='UTILITY_1 UTILITY_2'
+```shell
+make SKIP_UTILS='UTILITY_1 UTILITY_2'
 ```
 
 To build only a few of the available utilities:
 
-```bash
-$ make UTILS='UTILITY_1 UTILITY_2'
+```shell
+make UTILS='UTILITY_1 UTILITY_2'
 ```
 
 ## Installation
 
-### Cargo
+### Install with Cargo
 
 Likewise, installing can simply be done using:
 
-```bash
-$ cargo install --path .
+```shell
+cargo install --path .
 ```
 
 This command will install uutils into Cargo's *bin* folder (*e.g.* `$HOME/.cargo/bin`).
@@ -148,49 +150,49 @@ This command will install uutils into Cargo's *bin* folder (*e.g.* `$HOME/.cargo
 This does not install files necessary for shell completion or manpages.
 For manpages or shell completion to work, use `GNU Make` or see `Manually install shell completions`/`Manually install manpages`.
 
-### GNU Make
+### Install with GNU Make
 
 To install all available utilities:
 
-```bash
-$ make install
+```shell
+make install
 ```
 
 To install using `sudo` switch `-E` must be used:
 
-```bash
-$ sudo -E make install
+```shell
+sudo -E make install
 ```
 
 To install all but a few of the available utilities:
 
-```bash
-$ make SKIP_UTILS='UTILITY_1 UTILITY_2' install
+```shell
+make SKIP_UTILS='UTILITY_1 UTILITY_2' install
 ```
 
 To install only a few of the available utilities:
 
-```bash
-$ make UTILS='UTILITY_1 UTILITY_2' install
+```shell
+make UTILS='UTILITY_1 UTILITY_2' install
 ```
 
 To install every program with a prefix (e.g. uu-echo uu-cat):
 
-```bash
-$ make PROG_PREFIX=PREFIX_GOES_HERE install
+```shell
+make PROG_PREFIX=PREFIX_GOES_HERE install
 ```
 
 To install the multicall binary:
 
-```bash
-$ make MULTICALL=y install
+```shell
+make MULTICALL=y install
 ```
 
 Set install parent directory (default value is /usr/local):
 
-```bash
+```shell
 # DESTDIR is also supported
-$ make PREFIX=/my/path install
+make PREFIX=/my/path install
 ```
 
 Installing with `make` installs shell completions for all installed utilities
@@ -203,14 +205,15 @@ The `coreutils` binary can generate completions for the `bash`, `elvish`, `fish`
 and `zsh` shells. It prints the result to stdout.
 
 The syntax is:
-```bash
+
+```shell
 cargo run completion <utility> <shell>
 ```
 
 So, to install completions for `ls` on `bash` to `/usr/local/share/bash-completion/completions/ls`,
 run:
 
-```bash
+```shell
 cargo run completion ls bash > /usr/local/share/bash-completion/completions/ls
 ```
 
@@ -234,106 +237,107 @@ Un-installation differs depending on how you have installed uutils.  If you used
 Cargo to install, use Cargo to uninstall.  If you used GNU Make to install, use
 Make to uninstall.
 
-### Cargo
+### Uninstall with Cargo
 
 To uninstall uutils:
 
-```bash
-$ cargo uninstall uutils
+```shell
+cargo uninstall uutils
 ```
 
-### GNU Make
+### Uninstall with GNU Make
 
 To uninstall all utilities:
 
-```bash
-$ make uninstall
+```shell
+make uninstall
 ```
 
 To uninstall every program with a set prefix:
 
-```bash
-$ make PROG_PREFIX=PREFIX_GOES_HERE uninstall
+```shell
+make PROG_PREFIX=PREFIX_GOES_HERE uninstall
 ```
 
 To uninstall the multicall binary:
 
-```bash
-$ make MULTICALL=y uninstall
+```shell
+make MULTICALL=y uninstall
 ```
 
 To uninstall from a custom parent directory:
 
-```bash
+```shell
 # DESTDIR is also supported
-$ make PREFIX=/my/path uninstall
+make PREFIX=/my/path uninstall
 ```
+
 <!-- ANCHOR_END: build (this mark is needed for mdbook) -->
 
 ## Testing
 
 Testing can be done using either Cargo or `make`.
 
-### Cargo
+### Testing with Cargo
 
 Just like with building, we follow the standard procedure for testing using
 Cargo:
 
-```bash
-$ cargo test
+```shell
+cargo test
 ```
 
 By default, `cargo test` only runs the common programs. To run also platform
 specific tests, run:
 
-```bash
-$ cargo test --features unix
+```shell
+cargo test --features unix
 ```
 
 If you would prefer to test a select few utilities:
 
-```bash
-$ cargo test --features "chmod mv tail" --no-default-features
+```shell
+cargo test --features "chmod mv tail" --no-default-features
 ```
 
 If you also want to test the core utilities:
 
-```bash
-$ cargo test  -p uucore -p coreutils
+```shell
+cargo test  -p uucore -p coreutils
 ```
 
 To debug:
 
-```bash
-$ gdb --args target/debug/coreutils ls
+```shell
+gdb --args target/debug/coreutils ls
 (gdb) b ls.rs:79
 (gdb) run
 ```
 
-### GNU Make
+### Testing with GNU Make
 
 To simply test all available utilities:
 
-```bash
-$ make test
+```shell
+make test
 ```
 
 To test all but a few of the available utilities:
 
-```bash
-$ make SKIP_UTILS='UTILITY_1 UTILITY_2' test
+```shell
+make SKIP_UTILS='UTILITY_1 UTILITY_2' test
 ```
 
 To test only a few of the available utilities:
 
-```bash
-$ make UTILS='UTILITY_1 UTILITY_2' test
+```shell
+make UTILS='UTILITY_1 UTILITY_2' test
 ```
 
 To include tests for unimplemented behavior:
 
-```bash
-$ make UTILS='UTILITY_1 UTILITY_2' SPEC=y test
+```shell
+make UTILS='UTILITY_1 UTILITY_2' SPEC=y test
 ```
 
 ### Run Busybox Tests
@@ -343,20 +347,20 @@ requires `make`.
 
 To run busybox tests for all utilities for which busybox has tests
 
-```bash
-$ make busytest
+```shell
+make busytest
 ```
 
 To run busybox tests for a few of the available utilities
 
-```bash
-$ make UTILS='UTILITY_1 UTILITY_2' busytest
+```shell
+make UTILS='UTILITY_1 UTILITY_2' busytest
 ```
 
 To pass an argument like "-v" to the busybox test runtime
 
-```bash
-$ make UTILS='UTILITY_1 UTILITY_2' RUNTEST_ARGS='-v' busytest
+```shell
+make UTILS='UTILITY_1 UTILITY_2' RUNTEST_ARGS='-v' busytest
 ```
 
 ### Comparing with GNU
@@ -369,15 +373,15 @@ breakdown of the GNU test results of the main branch can be found
 
 To run locally:
 
-```bash
-$ bash util/build-gnu.sh
-$ bash util/run-gnu-test.sh
+```shell
+bash util/build-gnu.sh
+bash util/run-gnu-test.sh
 # To run a single test:
-$ bash util/run-gnu-test.sh tests/touch/not-owner.sh # for example
+bash util/run-gnu-test.sh tests/touch/not-owner.sh # for example
 # To run several tests:
-$ bash util/run-gnu-test.sh tests/touch/not-owner.sh tests/rm/no-give-up.sh # for example
+bash util/run-gnu-test.sh tests/touch/not-owner.sh tests/rm/no-give-up.sh # for example
 # If this is a perl (.pl) test, to run in debug:
-$ DEBUG=1 bash util/run-gnu-test.sh tests/misc/sm3sum.pl
+DEBUG=1 bash util/run-gnu-test.sh tests/misc/sm3sum.pl
 ```
 
 Note that it relies on individual utilities (not the multicall binary).
@@ -401,7 +405,6 @@ To improve the GNU compatibility, the following process is recommended:
 1. Start to modify the Rust implementation to match the expected behavior
 1. Add a test to make sure that we don't regress (our test suite is super quick)
 
-
 ## Contributing
 
 To contribute to uutils, please see [CONTRIBUTING](CONTRIBUTING.md).
@@ -409,11 +412,12 @@ To contribute to uutils, please see [CONTRIBUTING](CONTRIBUTING.md).
 ## Utilities
 
 Please note that this is not fully accurate:
-* Some new options can be added / removed in the GNU implementation;
-* Some error management might be missing;
-* Some behaviors might be different.
 
-See https://github.com/uutils/coreutils/issues/3336 for the main meta bugs
+- Some new options can be added / removed in the GNU implementation;
+- Some error management might be missing;
+- Some behaviors might be different.
+
+See <https://github.com/uutils/coreutils/issues/3336> for the main meta bugs
 (many are missing).
 
 | Done      | WIP       |

docs/src/build.md

@@ -1,3 +1,3 @@
 # Build from source
 
-{{#include ../../README.md:build }}
+{{#include ../../README.md:build }}

docs/src/contributing.md

@@ -1 +1,3 @@
-{{ #include ../../CONTRIBUTING.md }}
+<!-- markdownlint-disable MD041 -->
+
+{{ #include ../../CONTRIBUTING.md }}

docs/src/index.md

@@ -1,5 +1,9 @@
+<!-- markdownlint-disable MD041 -->
+
 {{#include logo.svg}}
 
+<!-- markdownlint-disable MD033 -->
+
 <style>
     /* Make the logo a bit bigger and center */
     #logo {

docs/src/installation.md

@@ -11,9 +11,10 @@ You can also [build uutils from source](/build.md).
 <!-- toc -->
 
 ## Cargo
+
 [![crates.io package](https://repology.org/badge/version-for-repo/crates_io/uutils-coreutils.svg)](https://repology.org/project/uutils-coreutils/versions)
 
-```bash
+```shell
 # Linux
 cargo install coreutils --features unix
 # MacOs
@@ -23,11 +24,12 @@ cargo install coreutils --features windows
 ```
 
 ## Linux
+
 ### Alpine
 
 [![Alpine Linux Edge package](https://repology.org/badge/version-for-repo/alpine_edge/uutils-coreutils.svg)](https://pkgs.alpinelinux.org/packages?name=uutils-coreutils)
 
-```bash
+```shell
 apk update uutils-coreutils
 ```
 
@@ -37,7 +39,7 @@ apk update uutils-coreutils
 
 [![Arch package](https://repology.org/badge/version-for-repo/arch/uutils-coreutils.svg)](https://archlinux.org/packages/community/x86_64/uutils-coreutils/)
 
-```bash
+```shell
 pacman -S uutils-coreutils
 ```
 
@@ -45,7 +47,7 @@ pacman -S uutils-coreutils
 
 [![Debian package](https://repology.org/badge/version-for-repo/debian_unstable/uutils-coreutils.svg)](https://packages.debian.org/sid/source/rust-coreutils)
 
-```bash
+```shell
 apt install rust-coreutils
 # To use it:
 export PATH=/usr/lib/cargo/bin/coreutils:$PATH
@@ -57,32 +59,35 @@ export PATH=/usr/lib/cargo/bin/coreutils:$PATH
 
 [![Gentoo package](https://repology.org/badge/version-for-repo/gentoo/uutils-coreutils.svg)](https://packages.gentoo.org/packages/sys-apps/uutils-coreutils)
 
-```bash
+```shell
 emerge -pv sys-apps/uutils-coreutils
 ```
 
 ### Manjaro
+
 ![Manjaro Stable package](https://repology.org/badge/version-for-repo/manjaro_stable/uutils-coreutils.svg)
 [![Manjaro Testing package](https://repology.org/badge/version-for-repo/manjaro_testing/uutils-coreutils.svg)](https://repology.org/project/uutils-coreutils/versions)
 [![Manjaro Unstable package](https://repology.org/badge/version-for-repo/manjaro_unstable/uutils-coreutils.svg)](https://repology.org/project/uutils-coreutils/versions)
 
-```bash
+```shell
 pacman -S uutils-coreutils
 # or
 pamac install uutils-coreutils
 ```
 
 ### NixOS
+
 [![nixpkgs unstable package](https://repology.org/badge/version-for-repo/nix_unstable/uutils-coreutils.svg)](https://repology.org/project/uutils-coreutils/versions)
 
-```bash
+```shell
 nix-env -iA nixos.uutils-coreutils
 ```
 
 ### OpenMandriva Lx
+
 [![openmandriva cooker package](https://repology.org/badge/version-for-repo/openmandriva_cooker/uutils-coreutils.svg)](https://repology.org/project/uutils-coreutils/versions)
 
-```bash
+```shell
 dnf install uutils-coreutils
 ```
 
@@ -90,7 +95,7 @@ dnf install uutils-coreutils
 
 [![Ubuntu package](https://repology.org/badge/version-for-repo/ubuntu_23_04/uutils-coreutils.svg)](https://packages.ubuntu.com/source/lunar/rust-coreutils)
 
-```bash
+```shell
 apt install rust-coreutils
 # To use it:
 export PATH=/usr/lib/cargo/bin/coreutils:$PATH
@@ -101,13 +106,15 @@ export PATH=/usr/lib/cargo/bin/coreutils:$PATH
 ## MacOS
 
 ### Homebrew
+
 [![Homebrew package](https://repology.org/badge/version-for-repo/homebrew/uutils-coreutils.svg)](https://formulae.brew.sh/formula/uutils-coreutils)
 
-```bash
+```shell
 brew install uutils-coreutils
 ```
 
 ### MacPorts
+
 [![MacPorts package](https://repology.org/badge/version-for-repo/macports/uutils-coreutils.svg)](https://ports.macports.org/port/coreutils-uutils/)
 
 ```
@@ -115,6 +122,7 @@ port install coreutils-uutils
 ```
 
 ## FreeBSD
+
 [![FreeBSD port](https://repology.org/badge/version-for-repo/freebsd/uutils-coreutils.svg)](https://repology.org/project/uutils-coreutils/versions)
 
 ```sh
@@ -124,9 +132,10 @@ pkg install uutils
 ## Windows
 
 ### Scoop
+
 [![Scoop package](https://repology.org/badge/version-for-repo/scoop/uutils-coreutils.svg)](https://scoop.sh/#/apps?q=uutils-coreutils&s=0&d=1&o=true)
 
-```bash
+```shell
 scoop install uutils-coreutils
 ```
 
@@ -136,4 +145,6 @@ scoop install uutils-coreutils
 
 [![AUR package](https://repology.org/badge/version-for-repo/aur/coreutils-hybrid.svg)](https://aur.archlinux.org/packages/coreutils-hybrid)
 
-A GNU coreutils / uutils coreutils hybrid package. Uses stable uutils programs mixed with GNU counterparts if uutils counterpart is unfinished or buggy.
+A GNU coreutils / uutils coreutils hybrid package. Uses stable uutils
+programs mixed with GNU counterparts if uutils counterpart is
+unfinished or buggy.

docs/src/multicall.md

@@ -1,4 +1,5 @@
-#  Multi-call binary
+# Multi-call binary
+
 uutils includes a multi-call binary from which the utils can be invoked. This
 reduces the binary size of the binary and can be useful for portability.
 
@@ -12,6 +13,7 @@ coreutils [util] [util options]
 The `--help` flag will print a list of available utils.
 
 ## Example
-```
+
+```shell
 coreutils ls -l
-```
+```

docs/src/test_coverage.md

@@ -1,5 +1,7 @@
 # GNU Test Coverage
 
+<!-- markdownlint-disable MD033 -->
+
 uutils is actively tested against the GNU coreutils test suite. The results
 below are automatically updated every day.
 

src/uu/arch/arch.md

@@ -4,11 +4,8 @@
 arch
 ```
 
-
 Display machine architecture
 
-
 ## After Help
 
 Determine architecture name for current machine.
-

src/uu/base32/base32.md

@@ -7,8 +7,8 @@ base32 [OPTION]... [FILE]
 encode/decode data and print to standard output
 With no FILE, or when FILE is -, read standard input.
 
-The data are encoded as described for the base32 alphabet in RFC
-4648. When decoding, the input may contain newlines in addition
+The data are encoded as described for the base32 alphabet in RFC 4648.
+When decoding, the input may contain newlines in addition
 to the bytes of the formal base32 alphabet. Use --ignore-garbage
 to attempt to recover from any other non-alphabet bytes in the
 encoded stream.

src/uu/base64/base64.md

@@ -7,8 +7,8 @@ base64 [OPTION]... [FILE]
 encode/decode data and print to standard output
 With no FILE, or when FILE is -, read standard input.
 
-The data are encoded as described for the base64 alphabet in RFC
-3548. When decoding, the input may contain newlines in addition
+The data are encoded as described for the base64 alphabet in RFC 3548.
+When decoding, the input may contain newlines in addition
 to the bytes of the formal base64 alphabet. Use --ignore-garbage
 to attempt to recover from any other non-alphabet bytes in the
 encoded stream.

src/uu/chcon/chcon.md

@@ -7,5 +7,5 @@ chcon [OPTION]... [-u USER] [-r ROLE] [-l RANGE] [-t TYPE] FILE...
 chcon [OPTION]... --reference=RFILE FILE...
 ```
 
-Change the SELinux security context of each FILE to CONTEXT. 
-With --reference, change the security context of each FILE to that of RFILE.
+Change the SELinux security context of each FILE to CONTEXT.
+With --reference, change the security context of each FILE to that of RFILE.

src/uu/cp/README.md

@@ -1,18 +1,18 @@
 <!-- markdownlint-disable first-line-heading -->
 <!-- spell-checker:ignore (markdown) markdownlint -->
 
-## Feature list
+# Feature list
 
 <!-- spell-checker:ignore (options) linkgs reflink -->
 
-### To Do
+## To Do
 
 - [ ] cli-symbolic-links
 - [ ] context
 - [ ] copy-contents
 - [ ] sparse
 
-### Completed
+## Completed
 
 - [x] archive
 - [x] attributes-only

src/uu/cut/BENCHMARKING.md

@@ -1,46 +1,45 @@
-## Benchmarking cut
+# Benchmarking cut
 
-### Performance profile
+## Performance profile
 
 In normal use cases a significant amount of the total execution time of `cut`
 is spent performing I/O. When invoked with the `-f` option (cut fields) some
 CPU time is spent on detecting fields (in `Searcher::next`). Other than that
 some small amount of CPU time is spent on breaking the input stream into lines.
 
-
-### How to
+## How to
 
 When fixing bugs or adding features you might want to compare
 performance before and after your code changes.
 
--   `hyperfine` can be used to accurately measure and compare the total
+- `hyperfine` can be used to accurately measure and compare the total
     execution time of one or more commands.
 
-    ```
-    $ cargo build --release --package uu_cut
+    ```shell
+    cargo build --release --package uu_cut
 
-    $ hyperfine -w3 "./target/release/cut -f2-4,8 -d' ' input.txt" "cut -f2-4,8 -d' ' input.txt"
+    hyperfine -w3 "./target/release/cut -f2-4,8 -d' ' input.txt" "cut -f2-4,8 -d' ' input.txt"
     ```
+
     You can put those two commands in a shell script to be sure that you don't
     forget to build after making any changes.
 
 When optimizing or fixing performance regressions seeing the number of times a
 function is called, and the amount of time it takes can be useful.
 
--   `cargo flamegraph` generates flame graphs from function level metrics it records using `perf` or `dtrace`
+- `cargo flamegraph` generates flame graphs from function level metrics it records using `perf` or `dtrace`
 
-    ```
-    $ cargo flamegraph --bin cut --package uu_cut -- -f1,3-4 input.txt > /dev/null
+    ```shell
+    cargo flamegraph --bin cut --package uu_cut -- -f1,3-4 input.txt > /dev/null
     ```
 
-
-### What to benchmark
+## What to benchmark
 
 There are four different performance paths in `cut` to benchmark.
 
--   Byte ranges `-c`/`--characters` or `-b`/`--bytes` e.g. `cut -c 2,4,6-`
--   Byte ranges with output delimiters e.g. `cut -c 4- --output-delimiter=/`
--   Fields e.g. `cut -f -4`
--   Fields with output delimiters e.g. `cut -f 7-10 --output-delimiter=:`
+- Byte ranges `-c`/`--characters` or `-b`/`--bytes` e.g. `cut -c 2,4,6-`
+- Byte ranges with output delimiters e.g. `cut -c 4- --output-delimiter=/`
+- Fields e.g. `cut -f -4`
+- Fields with output delimiters e.g. `cut -f 7-10 --output-delimiter=:`
 
 Choose a test input file with large number of lines so that program startup time does not significantly affect the benchmark.

src/uu/dd/BENCHMARKING.md

@@ -45,7 +45,7 @@ be roughly equivalent to the total bytes copied (`blocksize` x `count`).
 
 Some useful invocations for testing would be the following:
 
-```
+```shell
 hyperfine "./target/release/dd bs=4k count=1000000 < /dev/zero > /dev/null"
 hyperfine "./target/release/dd bs=1M count=20000 < /dev/zero > /dev/null"
 hyperfine "./target/release/dd bs=1G count=10 < /dev/zero > /dev/null"
@@ -57,7 +57,7 @@ Typically you would choose a small blocksize for measuring the performance of
 typically does some set amount of work per block which only depends on the size
 of the block if conversions are used.
 
-As an example, https://github.com/uutils/coreutils/pull/3600 made a change to
+As an example, <https://github.com/uutils/coreutils/pull/3600> made a change to
 reuse the same buffer between block copies, avoiding the need to reallocate a
 new block of memory for each copy. The impact of that change mostly had an
 impact on large block size copies because those are the circumstances where the

src/uu/dd/dd.md

@@ -1,6 +1,7 @@
-<!-- spell-checker:ignore convs iseek oseek -->
 # dd
 
+<!-- spell-checker:ignore convs iseek oseek -->
+
 ```
 dd [OPERAND]...
 dd OPTION
@@ -10,117 +11,116 @@ Copy, and optionally convert, a file system resource
 
 ## After Help
 
-OPERANDS:
+### Operands
 
-    bs=BYTES        read and write up to BYTES bytes at a time (default: 512);
-                    overwrites ibs and obs.
-    cbs=BYTES       the 'conversion block size' in bytes. Applies to
-                    the conv=block, and conv=unblock operations.
-    conv=CONVS      a comma-separated list of conversion options or
-                    (for legacy reasons) file flags.
-    count=N         stop reading input after N ibs-sized read operations rather
-                    than proceeding until EOF. See iflag=count_bytes if stopping 
-                    after N bytes is preferred
-    ibs=N           the size of buffer used for reads (default: 512)
-    if=FILE         the file used for input. When not specified, stdin is used instead
-    iflag=FLAGS     a comma-separated list of input flags which specify how the input
-                    source is treated. FLAGS may be any of the input-flags or 
-                    general-flags specified below.
-    skip=N          (or iseek=N) skip N ibs-sized records into input before beginning 
-                    copy/convert operations. See iflag=seek_bytes if seeking N bytes 
-                    is preferred.
-    obs=N           the size of buffer used for writes (default: 512)
-    of=FILE         the file used for output. When not specified, stdout is used 
-                    instead
-    oflag=FLAGS     comma separated list of output flags which specify how the output 
-                    source is treated. FLAGS may be any of the output flags or 
-                    general flags specified below
-    seek=N          (or oseek=N) seeks N obs-sized records into output before 
-                    beginning copy/convert operations. See oflag=seek_bytes if 
-                    seeking N bytes is preferred
-    status=LEVEL    controls whether volume and performance stats are written to 
-                    stderr.
-                             
-                    When unspecified, dd will print stats upon completion. An example is below.
-                        6+0 records in
-                        16+0 records out
-                        8192 bytes (8.2 kB, 8.0 KiB) copied, 0.00057009 s, 14.4 MB/s
-                    The first two lines are the 'volume' stats and the final line is 
-                    the 'performance' stats.
-                    The volume stats indicate the number of complete and partial 
-                    ibs-sized reads, or obs-sized writes that took place during the 
-                    copy. The format of the volume stats is
-                    <complete>+<partial>. If records have been truncated (see 
-                    conv=block), the volume stats will contain the number of 
-                    truncated records.
-                    
-                    Possible LEVEL values are:
-                        progress: Print periodic performance stats as the copy 
-                            proceeds.
-                        noxfer: Print final volume stats, but not performance stats.
-                        none: Do not print any stats.
+- `Bs=BYTES` : read and write up to BYTES bytes at a time (default: 512);
+   overwrites `ibs` and `obs`.
+- `cbs=BYTES` : the 'conversion block size' in bytes. Applies to the
+   `conv=block`, and `conv=unblock` operations.
+- `conv=CONVS` : a comma-separated list of conversion options or (for legacy
+   reasons) file flags.
+- `count=N` : stop reading input after N ibs-sized read operations rather
+   than proceeding until EOF. See `iflag=count_bytes` if stopping after N bytes
+   is preferred
+- `ibs=N` : the size of buffer used for reads (default: 512)
+- `if=FILE` : the file used for input. When not specified, stdin is used instead
+- `iflag=FLAGS` : a comma-separated list of input flags which specify how the
+   input source is treated. FLAGS may be any of the input-flags or general-flags
+   specified below.
+- `skip=N` (or `iseek=N`) : skip N ibs-sized records into input before beginning
+   copy/convert operations. See iflag=seek_bytes if seeking N bytes is preferred.
+- `obs=N` : the size of buffer used for writes (default: 512)
+- `of=FILE` : the file used for output. When not specified, stdout is used
+   instead
+- `oflag=FLAGS` : comma separated list of output flags which specify how the
+   output source is treated. FLAGS may be any of the output flags or general
+   flags specified below
+- `seek=N` (or `oseek=N`) : seeks N obs-sized records into output before
+   beginning copy/convert operations. See oflag=seek_bytes if seeking N bytes is
+   preferred
+- `status=LEVEL` : controls whether volume and performance stats are written to
+   stderr.
 
-                    Printing performance stats is also triggered by the INFO signal 
-                    (where supported), or the USR1 signal. Setting the 
-                    POSIXLY_CORRECT environment variable to any value (including an
-                    empty value) will cause the USR1 signal to be ignored.
+  When unspecified, dd will print stats upon completion. An example is below.
 
-CONVERSION OPTIONS:
+  ```plain
+    6+0 records in
+    16+0 records out
+    8192 bytes (8.2 kB, 8.0 KiB) copied, 0.00057009 s,
+    14.4 MB/s
+  ```
 
-    ascii       convert from EBCDIC to ASCII. This is the inverse of the 'ebcdic'
-                option. Implies conv=unblock.
-    ebcdic      convert from ASCII to EBCDIC. This is the inverse of the 'ascii'
-                option. Implies conv=block.
-    ibm         convert from ASCII to EBCDIC, applying the conventions for '[', ']' 
-                and '~' specified in POSIX. Implies conv=block.
+  The first two lines are the 'volume' stats and the final line is the
+  'performance' stats.
+  The volume stats indicate the number of complete and partial ibs-sized reads,
+  or obs-sized writes that took place during the copy. The format of the volume
+  stats is `<complete>+<partial>`. If records have been truncated (see
+  `conv=block`), the volume stats will contain the number of truncated records.
 
-    ucase       convert from lower-case to upper-case
-    lcase       converts from upper-case to lower-case.
+  Possible LEVEL values are:
+  - `progress` : Print periodic performance stats as the copy proceeds.
+  - `noxfer` : Print final volume stats, but not performance stats.
+  - `none` : Do not print any stats.
 
-    block       for each newline less than the size indicated by cbs=BYTES, remove 
-                the newline and pad with spaces up to cbs. Lines longer than cbs are 
-                truncated.
-    unblock     for each block of input of the size indicated by cbs=BYTES, remove
-                right-trailing spaces and replace with a newline character.
+  Printing performance stats is also triggered by the INFO signal (where supported),
+  or the USR1 signal. Setting the POSIXLY_CORRECT environment variable to any value
+  (including an empty value) will cause the USR1 signal to be ignored.
 
-    sparse      attempts to seek the output when an obs-sized block consists of only
-                zeros.
-    swab        swaps each adjacent pair of bytes. If an odd number of bytes is
-                present, the final byte is omitted.
-    sync        pad each ibs-sided block with zeros. If 'block' or 'unblock' is
-                specified, pad with spaces instead.
-    excl        the output file must be created. Fail if the output file is already
-                present.
-    nocreat     the output file will not be created. Fail if the output file in not
-                already present.
-    notrunc     the output file will not be truncated. If this option is not
-                present, output will be truncated when opened.
-    noerror     all read errors will be ignored. If this option is not present, dd
-                will only ignore Error::Interrupted.
-    fdatasync   data will be written before finishing.
-    fsync       data and metadata will be written before finishing.
+### Conversion Options
 
-INPUT FLAGS:
+- `ascii` : convert from EBCDIC to ASCII. This is the inverse of the `ebcdic`
+  option. Implies `conv=unblock`.
+- `ebcdic` : convert from ASCII to EBCDIC. This is the inverse of the `ascii`
+  option. Implies `conv=block`.
+- `ibm` : convert from ASCII to EBCDIC, applying the conventions for `[`, `]`
+  and `~` specified in POSIX. Implies `conv=block`.
 
-    count_bytes     a value to count=N will be interpreted as bytes.
-    skip_bytes      a value to skip=N will be interpreted as bytes.
-    fullblock       wait for ibs bytes from each read. zero-length reads are still
-                    considered EOF.
+- `ucase` : convert from lower-case to upper-case.
+- `lcase` : converts from upper-case to lower-case.
 
-OUTPUT FLAGS:
+- `block` : for each newline less than the size indicated by cbs=BYTES, remove
+  the newline and pad with spaces up to cbs. Lines longer than cbs are truncated.
+- `unblock` : for each block of input of the size indicated by cbs=BYTES, remove
+  right-trailing spaces and replace with a newline character.
 
-    append      open file in append mode. Consider setting conv=notrunc as well.
-    seek_bytes  a value to seek=N will be interpreted as bytes.
+- `sparse` : attempts to seek the output when an obs-sized block consists of
+  only zeros.
+- `swab` : swaps each adjacent pair of bytes. If an odd number of bytes is
+  present, the final byte is omitted.
+- `sync` : pad each ibs-sided block with zeros. If `block` or `unblock` is
+  specified, pad with spaces instead.
+- `excl` : the output file must be created. Fail if the output file is already
+  present.
+- `nocreat` : the output file will not be created. Fail if the output file in
+  not already present.
+- `notrunc` : the output file will not be truncated. If this option is not
+  present, output will be truncated when opened.
+- `noerror` : all read errors will be ignored. If this option is not present,
+  dd will only ignore Error::Interrupted.
+- `fdatasync` : data will be written before finishing.
+- `fsync` : data and metadata will be written before finishing.
 
-GENERAL FLAGS:
+### Input flags
 
-    direct      use direct I/O for data.
-    directory   fail unless the given input (if used as an iflag) or output (if used 
-                as an oflag) is a directory.
-    dsync       use synchronized I/O for data.
-    sync        use synchronized I/O for data and metadata.
-    nonblock    use non-blocking I/O.
-    noatime     do not update access time.
-    nocache     request that OS drop cache.
-    noctty      do not assign a controlling tty.
-    nofollow    do not follow system links.
+- `count_bytes` : a value to `count=N` will be interpreted as bytes.
+- `skip_bytes` : a value to `skip=N` will be interpreted as bytes.
+- `fullblock` : wait for ibs bytes from each read. zero-length reads are still
+  considered EOF.
+
+### Output flags
+
+- `append` : open file in append mode. Consider setting conv=notrunc as well.
+- `seek_bytes` : a value to seek=N will be interpreted as bytes.
+
+### General Flags
+
+- `Direct` : use direct I/O for data.
+- `directory` : fail unless the given input (if used as an iflag) or
+  output (if used as an oflag) is a directory.
+- `dsync` : use synchronized I/O for data.
+- `sync` : use synchronized I/O for data and metadata.
+- `nonblock` : use non-blocking I/O.
+- `noatime` : do not update access time.
+- `nocache` : request that OS drop cache.
+- `noctty` : do not assign a controlling tty.
+- `nofollow` : do not follow system links.