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

This is a discussion on assets/manual/bat.1.in, the man pages of bat itself, (but not the styles of the man page shown by bat). I received a report https://github.com/akinomyoga/ble.sh/issues/458#issuecomment-2156378867 that the descriptions of some of the options of bat cannot be extracted from the man page of bat.

I submitted PR #2995 to solve some part of it.

It turned out that some of the options are missing on the man page (although the bash completion setting `assets/completion/bat.bash.in` generates the options). I submitted a pull request to include those missing options at #2995. However, I haven't included the option `--cache-dir` because it doesn't seem to be mentioned even in `--help`. Why is `--cache-dir` not mentioned in `bat --help` and `man bat`, yet it is generated as a candidate for the completion? Is that because the output of `bat --help` and `man bat` are not up-to-date? Or is it because the option `--cache-dir` is a hidden option? If possible, I also would like to suggest adding `--cache-dir` in `bat --help` and `man bat`.

I'd like to discuss the rest part of the problem here. It turned out that some other options are not described in a separate entry, but mentioned in the text or an example command bat --.... See the following section on the man page (where I put ⭐ to the corresponding parts).

FILES
       bat  can  also be customized with a configuration file. The location of
       the file is dependent on your operating system. To get the default path
       for your system, call:

       bat --config-file ⭐

       Alternatively, you can use the BAT_CONFIG_PATH environment variable  to
       point bat to a non-default location of the configuration file.

       To generate a default configuration file, call:

       bat --generate-config-file ⭐

ADDING CUSTOM LANGUAGES
       bat  supports  Sublime  Text .sublime-syntax language files, and can be
       customized to add additional languages to your local  installation.  To
       do  this,  add  the  .sublime-syntax language files to `$(bat --config-
       dir)/syntaxes` ⭐ and run `bat cache --build`.

       Example:

            mkdir -p "$(bat --config-dir)/syntaxes" ⭐
            cd "$(bat --config-dir)/syntaxes"

Those options do not have independent lines that start with --config-file, etc. Then, it is hard to heuristically identify the location where it is described.

Here, I'd like to request adjusting the format of the man page so that those options and descriptions can be extracted by a general heuristic algorithm. For example, can we add separate entries for respective options under the corresponding section in addition to the existing explanations?

sharkdp / bat

Format of the man page of `bat` (`assets/manual/bat.1.in`) #2996