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

[akinomyoga]

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 akinomyoga/ble.sh#458 (comment) 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?

[akinomyoga]

For example, can we add separate entries for respective options under the corresponding section in addition to the existing explanations?

In commit 02e1188 in PR #2995, I added the sections below bat --generate-config-file and bat --no-lessopen to describe the related options.