Better user documentation with markdown formatting

This issue is meant as a design doc/tracking issue for the documentation for the work I've started in https://github.com/uutils/coreutils/pull/3180, because it might take some time and many PRs to fully implement.

First, let me state a few goals that I have in mind for the documentation:

• We should have 3 pieces of documentation from the user's perspective: --help, man and the online docs.
• man and the online docs should show the same information, which is:
  • Description
  • Usage
  • Detailed help
  • Flags & arguments
  • Examples
  • Metadata, such as: authors (always "uutils contributors"), copyright and a link for reporting bugs
• --help should focus on a short description, flags and arguments.
• Every bit of information for these should come from the same source.
• The information should be generated automatically from the code as much as possible.

Note: This approach could be considered as having 2 levels of documentation, --help and man. It is worth noting that GNU has 3 levels: --help, man & info. Where --help is the shortest, man is longer and info is the longest and may span several pages. To me, the distinction between man and info is mostly useless, except for the larger utils that have multiple pages in info.

All this currently brings me to the following design:

flowchart LR
    code((code)) --> clap
    helpmd((help.md)) --> render(render md for terminal) --> clap --> help((help)) & uudoc
    helpmd --> uudoc --> mdbook & mdbook-man
    mdbook --> docs((docs))
    mdbook-man --> man((man))

This means that the sources for the documentation are

• help.md for all the custom text (written in markdown),
• and the source code for flags and arguments.

The contents of help.md is inserted into the source code at compile time via proc-macros, which render the markdown into a format that works well in the terminal.

For this to be implemented, we need several steps:

• (proc-)macros that insert parts of help.md into the source code. See https://github.com/uutils/coreutils/issues/2816 and https://github.com/uutils/coreutils/pull/3180.
• Markdown rendering for the terminal in these macros.
• Update all the utils to use these macros and markdown formatting.
• Get parts of the documentation directly from help.md in uudoc.
• Add metadata to uudoc output.
• Set up mdbook-man.

A downside to this plan is that most of the help strings will need to be reformatted manually, so the whole thing will probably take a while.

Feel free to pick on any of the points above. I'm sure I've missed some important considerations :)

This is a design and tracking issue rather than a single scoped change. Start by reading issue #2816 and PR #3180, then inspect the documented flow involving help.md, proc-macros, uudoc, mdbook, and mdbook-man. A contribution is done when one listed step is implemented and its documentation output follows the stated goals.