README: Order argument options alphabetically

[tooomm]

Linked to #1789

Changes:

• Reorder alphabetically (by long names)
• Added the version number next to the deprecation note of --bump and --exclude-file
• Made the lines more narrow and reduce/prevent scrolling in the code block to read all information
• More uniform representation of examples or available options
• Few wording changes

I like that this also highlights now that casing matters for -v/-V, -t/-T or -h/-H.

Please check and review!
See it here: https://github.com/tooomm/lychee/tree/patch-2?tab=readme-ov-file#commandline-parameters

Questions:
1) Since which lychee version is --exclude-file deprecated?
2) What is the default for --cache-exclude-status?
The list shows "[default: ]", does that mean there is no default?
3) Should we add an example on when to separate inputs from options with "--"?
4) For --github-token, how to understand the [env: GITHUB_TOKEN] note?
5) For --help, the explanation reads Print help (see a summary with '-h').
Isn't -h the same as --help? So I do not really get the comment in brackets.
6) How many levels of quiet and verbose are there? -qq << -q << none >> -v >> -vv ?
How do they interact/relate, I assume they are mutually exclusive?
7) How to interpret the ... behind a few options?

Notes:

• -X/--method has not a short form derived from its long form
• I could imagine something like --dump-options, --dump-args, or --dump-params could be helpful.
  The idea would be to not only list the provided options, but also list out default values otherwise hidden
• Following the logic in other places, shouldn't --hidden be named something like the many other includes,
  e.g. --include-hidden
• README: Parameters not sorted? #1789 (comment)_

Edit:
Looks like the output of --help is out of sync with this README change, but is expected to match (See test). Can look at that after the rest is clarified.

[thomas-zahner]

Thanks @tooomm for the PR. I do agree that it would be great if all the options are in alphabetical order. As you noticed yourself already, we have a test which validates the content in the README. This is because the information in the README is basically copy/paste from the automatically generated help message for documentation purposes. The code is the actual source of truth, please take a look at lychee-bin/src/options.rs. The message is generated via clap.

1. Don't know it by heart, you can look at the commit history
2. This has to do with clap. Take a look at the attributes for cache_exclude_status in lychee-bin/src/options.rs
3. We could do that. Can you give me an example for --? I can't remember using that with lychee, only with cargo run
4. This comes from #[arg(long, env = "GITHUB_TOKEN", hide_env_values = true)] which is just a macro and syntactic sugar for the env method. Reading the docs you can see that it means: Read from name environment variable when argument is not present.
5. You are totally right that this sounds weird. I think this might be generated by clap. You can try to overwrite the message by explicitly specifying the help arg and setting the message, as I didn't see the help arg itself anywhere.
6. Basically as many as you want. See lychee-bin/src/verbosity.rs for the documentation and implementation. action = clap::ArgAction::Count is probably responsible for allowing many q and v
7. It means that the argument can be repeated. (remember that this comes from clap)

So in summary, you can see that clap is responsible for the generation of the help message. I advise you to change the code (source of truth) first to reorder the args alphabetically, and update the messages. The README is only a copy of the generated help message.

If you reordered the options alphabetically it would make sense to create a new test, which validates that the options are ordered. This would prevent regressions, i.e. prevent people from screwing up the order in the future. Maybe there's even an argument for clap to just sort the flags alphabetically, but I didn't see anything with a quick search.

[tooomm]

Thanks for your reply, Thomas!
I can have a closer look only like next week.

---

Changes since creation & updates not reflected here yet: #1777, #1803
To monitor #1787, #1799, #1725

[mre]

@tooomm, any updates? Would love to get this merged at some point.

[thomas-zahner]

@tooomm @mre Actually, I have started fixing this on a new branch as I was starting to work on #1505. So I will complete issue #1505 and #1789 simultaneously. Also see my comment over here. Current state is, that I have created a regression test, which will prevent that arguments are in unalphabetical order. Next I will finish reordering them. I might even try to introduce help categories as cURL does, but not really sure yet.

You can take a look at my branch here master...thomas-zahner:lychee:man-pages. But I haven't pushed the argument order related changes yet as I'm currently on another device. But you can expect the argument order to be fixed within the next few weeks. I will close this PR now, thanks for your efforts.

[mre]

Cool. Can you create a draft PR so that we don't forget about this important work?

[thomas-zahner]

Sure: #1858