@@ -1,18 +1,23 @@
11.TH {{PROJECT_EXECUTABLE | upcase}} "1"
22.SH NAME
3−{{PROJECT_EXECUTABLE}} \- manual page for {{PROJECT_NAME}}
4−.SH DESCRIPTION
5−{{PROJECT_EXECUTABLE}} - a cat(1) clone with syntax highlighting and Git integration.
3+{{PROJECT_EXECUTABLE}} \- a cat(1) clone with syntax highlighting and Git integration.
64.SH "USAGE"
7−.IP
8−{{PROJECT_EXECUTABLE}} [OPTIONS] [FILE]...
9−.IP
10−{{PROJECT_EXECUTABLE}} <SUBCOMMAND>
5+.IP "{{PROJECT_EXECUTABLE}} [OPTIONS] [FILE]..."
6+.IP "{{PROJECT_EXECUTABLE}} cache [CACHE-OPTIONS] [--build|--clear]
7+.SH DESCRIPTION
8+{{PROJECT_EXECUTABLE}} prints the syntax-highlighted content of a collection of FILEs to the
9+terminal. If no FILE is specified, or when FILE is '-', it reads from standard input.
10+
11+{{PROJECT_EXECUTABLE}} supports a large number of programming and markup languages.
12+It also communicates with git(1) to show modifications with respect to the git index.
13+{{PROJECT_EXECUTABLE}} automatically pipes its output through a pager (by default: less).
14+
15+Whenever the output of {{PROJECT_EXECUTABLE}} goes to a non-interactive terminal, i.e. when the
16+output is piped into another process or into a file, {{PROJECT_EXECUTABLE}} will act as a drop-in
17+replacement for cat(1) and fall back to printing the plain file contents.
18+
1119.SH "OPTIONS"
12−.HP
13−General remarks
14−.IP
15−Command-line options like '-l'/'--language' that take values can be specified as
20+General remarks: Command-line options like '-l'/'--language' that take values can be specified as
1621either '--language value', '--language=value', '-l value' or '-lvalue'.
1722.HP
1823\fB\-A\fR, \fB\-\-show\-all\fR
@@ -33,78 +38,80 @@ specified as a name (like 'C++' or 'LaTeX') or possible file extension
3338(like 'cpp', 'hpp' or 'md'). Use '\-\-list\-languages' to show all supported
3439language names and file extensions.
3540.HP
36−\fB\-H\fR, \fB\-\-highlight\-line\fR <N>...
41+\fB\-H\fR, \fB\-\-highlight\-line\fR <N:M>...
3742.IP
38−Highlight the N\-th line with a different background color
43+Highlight the specified line ranges with a different background color For example:
44+.RS
45+.IP "\-\-highlight\-line 40"
46+highlights line 40
47+.IP "\-\-highlight\-line 30:40"
48+highlights lines 30 to 40
49+.IP "\-\-highlight\-line :40"
50+highlights lines 1 to 40
51+.IP "\-\-highlight\-line 40:"
52+highlights lines 40 to the end of the file
53+.RE
3954.HP
4055\fB\-\-tabs\fR <T>
4156.IP
42−Set the tab width to T spaces. Use a width of 0 to pass tabs through
43−directly
57+Set the tab width to T spaces. Use a width of 0 to pass tabs through directly
4458.HP
4559\fB\-\-wrap\fR <mode>
4660.IP
47−Specify the text\-wrapping mode (*auto*, never, character). The
48−\&'\-\-terminal\-width' option can be used in addition to control the output
49−width.
61+Specify the text\-wrapping mode (*auto*, never, character). The '\-\-terminal\-width' option
62+can be used in addition to control the output width.
5063.HP
5164\fB\-\-terminal\-width\fR <width>
5265.IP
53−Explicitly set the width of the terminal instead of determining it
54−automatically. If prefixed with '+' or '\-', the value will be treated as
55−an offset to the actual terminal width. See also: '\-\-wrap'.
66+Explicitly set the width of the terminal instead of determining it automatically. If
67+prefixed with '+' or '\-', the value will be treated as an offset to the actual terminal
68+width. See also: '\-\-wrap'.
5669.HP
5770\fB\-n\fR, \fB\-\-number\fR
5871.IP
59−Only show line numbers, no other decorations. This is an alias for
60−\&'\-\-style=numbers'
72+Only show line numbers, no other decorations. This is an alias for '\-\-style=numbers'
6173.HP
6274\fB\-\-color\fR <when>
6375.IP
64−Specify when to use colored output. The automatic mode only enables colors
65−if an interactive terminal is detected. Possible values: *auto*, never,
66−always.
76+Specify when to use colored output. The automatic mode only enables colors if an
77+interactive terminal is detected. Possible values: *auto*, never, always.
6778.HP
6879\fB\-\-italic\-text\fR <when>
6980.IP
70−Specify when to use ANSI sequences for italic text in the output. Possible
71−values: always, *never*.
81+Specify when to use ANSI sequences for italic text in the output. Possible values:
82+always, *never*.
7283.HP
7384\fB\-\-decorations\fR <when>
7485.IP
75−Specify when to use the decorations that have been specified via
76−\&'\-\-style'. The automatic mode only enables decorations if an interactive
77−terminal is detected. Possible values: *auto*, never, always.
86+Specify when to use the decorations that have been specified via '\-\-style'. The
87+automatic mode only enables decorations if an interactive terminal is detected. Possible
88+values: *auto*, never, always.
7889.HP
7990\fB\-\-paging\fR <when>
8091.IP
81−Specify when to use the pager. To control which pager is used, set the
82−PAGER or BAT_PAGER environment variables (the latter takes precedence) or
83−use the '\-\-pager' option. To disable the pager permanently, set BAT_PAGER
84−to an empty string or set '\-\-paging=never' in the configuration file.
85−Possible values: *auto*, never, always.
92+Specify when to use the pager. To control which pager is used, set the PAGER or
93+BAT_PAGER environment variables (the latter takes precedence) or use the '\-\-pager'
94+option. To disable the pager permanently, set BAT_PAGER to an empty string or set
95+\&'\-\-paging=never' in the configuration file. Possible values: *auto*, never, always.
8696.HP
8797\fB\-\-pager\fR <command>
8898.IP
89−Determine which pager is used. This option will overwrite the PAGER and
90−BAT_PAGER environment variables. The default pager is 'less'. To disable
91−the pager completely, use the '\-\-paging' option. Example: '\-\-pager "less
92−\fB\-RF\fR"'.
99+Determine which pager is used. This option will overwrite the PAGER and BAT_PAGER
100+environment variables. The default pager is 'less'. To disable the pager completely, use
101+the '\-\-paging' option. Example: '\-\-pager "less \fB\-RF\fR"'.
93102.HP
94103\fB\-m\fR, \fB\-\-map\-syntax\fR <from:to>...
95104.IP
96−Map a file extension or file name to an existing syntax (specified by a
97−file extension or file name). For example, to
98−highlight *.build files with the Python syntax, use '\-m build:py'. To
99−highlight files named '.myignore' with the Git Ignore syntax, use '\-m
105+Map a file extension or file name to an existing syntax (specified by a file extension
106+or file name). For example, to highlight *.build files with the Python syntax, use '\-m
107+build:py'. To highlight files named '.myignore' with the Git Ignore syntax, use '\-m
100108\&.myignore:gitignore'.
101109.HP
102110\fB\-\-theme\fR <theme>
103111.IP
104−Set the theme for syntax highlighting. Use '\-\-list\-themes' to see all
105−available themes. To set a default theme, add the '\-\-theme="..."' option
106−to the configuration file or export the BAT_THEME environment variable
107−(e.g.: export BAT_THEME="...").
112+Set the theme for syntax highlighting. Use '\-\-list\-themes' to see all available themes.
113+To set a default theme, add the '\-\-theme="..."' option to the configuration file or
114+export the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
108115.HP
109116\fB\-\-list\-themes\fR
110117.IP
@@ -112,12 +119,11 @@ Display a list of supported themes for syntax highlighting.
112119.HP
113120\fB\-\-style\fR <style\-components>
114121.IP
115−Configure which elements (line numbers, file headers, grid borders, Git
116−modifications, ..) to display in addition to the file contents. The
117−argument is a comma\-separated list of components to display (e.g.
118−\&'numbers,changes,grid') or a pre\-defined style ('full'). To set a default
119−style, add the '\-\-style=".."' option to the configuration file or export
120−the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible
122+Configure which elements (line numbers, file headers, grid borders, Git modifications,
123+\&..) to display in addition to the file contents. The argument is a comma\-separated list
124+of components to display (e.g. 'numbers,changes,grid') or a pre\-defined style ('full').
125+To set a default style, add the '\-\-style=".."' option to the configuration file or
126+export the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible
121127values: *auto*, full, plain, changes, header, grid, numbers, snip.
122128.HP
123129\fB\-r\fR, \fB\-\-line\-range\fR <N:M>...
@@ -138,8 +144,8 @@ Display a list of supported languages for syntax highlighting.
138144.HP
139145\fB\-u\fR, \fB\-\-unbuffered\fR
140146.IP
141−This option exists for POSIX\-compliance reasons ('u' is for 'unbuffered').
142−The output is always unbuffered \- this option is simply ignored.
147+This option exists for POSIX\-compliance reasons ('u' is for 'unbuffered'). The output is
148+always unbuffered \- this option is simply ignored.
143149.HP
144150\fB\-h\fR, \fB\-\-help\fR
145151.IP
@@ -148,13 +154,20 @@ Print this help message.
148154\fB\-V\fR, \fB\-\-version\fR
149155.IP
150156Show version information.
151−.SH "ARGS"
152−.IP
153−<FILE>...
157+.SH "POSITIONAL ARGUMENTS"
158+.HP
159+\fB<FILE>...\fR
154160.IP
155−File(s) to print / concatenate. Use a dash ('\-') or no argument at all to read
156−from standard input.
161+Files to print and concatenate. Use a dash ('\-') or no argument at all to read from
162+standard input.
157163.SH "SUBCOMMANDS"
158−.IP
159−cache
160−Modify the syntax\-definition and theme cache
164+.HP
165+\fBcache\fR - Modify the syntax\-definition and theme cache.
166+.SH "FILES"
167+{{PROJECT_EXECUTABLE}} can also be customized with a configuration file. The location of the file
168+is dependent on your operating system. To get the default path for your system, call:
169+
170+\fB{{PROJECT_EXECUTABLE}} --config-file\fR
171+
172+Alternatively, you can use the BAT_CONFIG_PATH environment variable to point bat to a non-default
173+location of the configuration file.