This issue is meant as a design doc/tracking issue for the documentation for the work I've started in #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 Removing long help strings from the source code #2816 and Create help_section macro and use it for numfmt #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 :)