Update the man page of bat (assets/manual/bat.1.in)

[akinomyoga]

The man page of bat (assets/manual/bat.1.in) doesn't seem to be up-to-date compared to the output obtained by bat --help and the options completed by assets/completion/bat.bash.in.

---

Originally reported by akinomyoga/ble.sh#458 (comment). A Bash interactive setting ble.sh extracts the descriptions of the options generated by programmable completions from the man page, but the discrepancy between the programmable completion assets/completion/bat.bash.in and the man page assets/manual/bat.1.in causes missing descriptions for some options.

However, I still see discrepancies between different files:

• doc/long-help.txt and bat --help
• doc/short-help.txt and bat -h
• assets/completion/bat.bash.in
• assets/completion/bat.fish.in
• assets/completion/bat.zsh.in
• assets/manual/bat.1.in

Not a single one out of the above list matches another, which means that there are six different sets of options. Also, some options appearing in several files have different descriptions in the above files. Which one would be considered the up-to-date information that reflects the public interface? Or may all of the options defined in src/bin/bat/clap_app.rs be used by the users (i.e., there are no hidden options)?

---

Fixes: #2996 ... I initially didn't include the fix for #2996, but I decided to include also the fix for #2996 in this PR cf #2995 (comment).

[keith-hall]

Or may all of the options defined in src/bin/bat/clap_app.rs be used by the users (i.e., there are no hidden options)?

I believe this to be the case, nothing is hidden

[akinomyoga]

I believe this to be the case, nothing is hidden

Thanks! I now checked clap_app.rs in detail and noticed that some options are explicitly marked as .hide(true):

• --no-config (added in Add simple configuration file #338)
• --no-custom-assets (added in Support a hidden arg --no-custom-assets that skips loading assets from the cache #1758)
• --no-lessopen (added in Add $LESSOPEN and $LESSCLOSE support #2444)
• -P, --no-paging (added in Add alias for --paging=never #1082)
• --generate-config-file (added in Add option to generate a default config file, fixes #870 #885)
• --config-file (added in 8dc7e2e)
• --config-dir and --cache-dir (added in Refactor cache subcommand #498)

They seem to be intentionally hidden from the help text. However, the completion settings seem to generate such "hidden" options.

• The first three --no-* options were added in the fish completion in fix(completions): add missing fish completions #2750.
• -P is generated by the fish completion
• The last three items in the above list are generated by all the bash/zsh/fish completions except for --cache-dir missing in the fish completion.

I also note that the last four items (-P, ... --config-dir and --cache-dir) are mentioned in the text in the man page (as I raised the discussion in #2996).

[akinomyoga]

I added the other missing options (except for --no-paging) to the man page and the completions in commits 8e00b9f, 090b605, 02e1188. Each commit can be dropped if it is unwanted.

Edit: Commit 02e1188 includes the changes related to #2996.

[akinomyoga]

May I ask what is blocking this PR? Is there anything I can do for this PR?

[akinomyoga]

@keith-hall Wow, thank you for your quick response!