Major update for the man page, closes #573

assets/manual/bat.1.in

@@ -1,18 +1,23 @@
 .TH {{PROJECT_EXECUTABLE | upcase}} "1"
 .SH NAME
-{{PROJECT_EXECUTABLE}} \- manual page for {{PROJECT_NAME}}
+{{PROJECT_EXECUTABLE}} \- a cat(1) clone with syntax highlighting and Git integration.
-.SH DESCRIPTION
-{{PROJECT_EXECUTABLE}} - a cat(1) clone with syntax highlighting and Git integration.
 .SH "USAGE"
-.IP
+.IP "{{PROJECT_EXECUTABLE}} [OPTIONS] [FILE]..."
-{{PROJECT_EXECUTABLE}} [OPTIONS] [FILE]...
+.IP "{{PROJECT_EXECUTABLE}} cache [CACHE-OPTIONS] [--build|--clear]
-.IP
+.SH DESCRIPTION
-{{PROJECT_EXECUTABLE}} <SUBCOMMAND>
+{{PROJECT_EXECUTABLE}} prints the syntax-highlighted content of a collection of FILEs to the
+terminal. If no FILE is specified, or when FILE is '-', it reads from standard input.
+
+{{PROJECT_EXECUTABLE}} supports a large number of programming and markup languages.
+It also communicates with git(1) to show modifications with respect to the git index.
+{{PROJECT_EXECUTABLE}} automatically pipes its output through a pager (by default: less).
+
+Whenever the output of {{PROJECT_EXECUTABLE}} goes to a non-interactive terminal, i.e. when the
+output is piped into another process or into a file, {{PROJECT_EXECUTABLE}} will act as a drop-in
+replacement for cat(1) and fall back to printing the plain file contents.
+
 .SH "OPTIONS"
-.HP
+General remarks: Command-line options like '-l'/'--language' that take values can be specified as
-General remarks
-.IP
-Command-line options like '-l'/'--language' that take values can be specified as
 either '--language value', '--language=value', '-l value' or '-lvalue'.
 .HP
 \fB\-A\fR, \fB\-\-show\-all\fR
@@ -33,78 +38,80 @@ specified as a name (like 'C++' or 'LaTeX') or possible file extension
 (like 'cpp', 'hpp' or 'md'). Use '\-\-list\-languages' to show all supported
 language names and file extensions.
 .HP
-\fB\-H\fR, \fB\-\-highlight\-line\fR <N>...
+\fB\-H\fR, \fB\-\-highlight\-line\fR <N:M>...
 .IP
-Highlight the N\-th line with a different background color
+Highlight the specified line ranges with a different background color For example:
+.RS
+.IP "\-\-highlight\-line 40"
+highlights line 40
+.IP "\-\-highlight\-line 30:40"
+highlights lines 30 to 40
+.IP "\-\-highlight\-line :40"
+highlights lines 1 to 40
+.IP "\-\-highlight\-line 40:"
+highlights lines 40 to the end of the file
+.RE
 .HP
 \fB\-\-tabs\fR <T>
 .IP
-Set the tab width to T spaces. Use a width of 0 to pass tabs through
+Set the tab width to T spaces. Use a width of 0 to pass tabs through directly
-directly
 .HP
 \fB\-\-wrap\fR <mode>
 .IP
-Specify the text\-wrapping mode (*auto*, never, character). The
+Specify the text\-wrapping mode (*auto*, never, character). The '\-\-terminal\-width' option
-\&'\-\-terminal\-width' option can be used in addition to control the output
+can be used in addition to control the output width.
-width.
 .HP
 \fB\-\-terminal\-width\fR <width>
 .IP
-Explicitly set the width of the terminal instead of determining it
+Explicitly set the width of the terminal instead of determining it automatically. If
-automatically. If prefixed with '+' or '\-', the value will be treated as
+prefixed with '+' or '\-', the value will be treated as an offset to the actual terminal
-an offset to the actual terminal width. See also: '\-\-wrap'.
+width. See also: '\-\-wrap'.
 .HP
 \fB\-n\fR, \fB\-\-number\fR
 .IP
-Only show line numbers, no other decorations. This is an alias for
+Only show line numbers, no other decorations. This is an alias for '\-\-style=numbers'
-\&'\-\-style=numbers'
 .HP
 \fB\-\-color\fR <when>
 .IP
-Specify when to use colored output. The automatic mode only enables colors
+Specify when to use colored output. The automatic mode only enables colors if an
-if an interactive terminal is detected. Possible values: *auto*, never,
+interactive terminal is detected. Possible values: *auto*, never, always.
-always.
 .HP
 \fB\-\-italic\-text\fR <when>
 .IP
-Specify when to use ANSI sequences for italic text in the output. Possible
+Specify when to use ANSI sequences for italic text in the output. Possible values:
-values: always, *never*.
+always, *never*.
 .HP
 \fB\-\-decorations\fR <when>
 .IP
-Specify when to use the decorations that have been specified via
+Specify when to use the decorations that have been specified via '\-\-style'. The
-\&'\-\-style'. The automatic mode only enables decorations if an interactive
+automatic mode only enables decorations if an interactive terminal is detected. Possible
-terminal is detected. Possible values: *auto*, never, always.
+values: *auto*, never, always.
 .HP
 \fB\-\-paging\fR <when>
 .IP
-Specify when to use the pager. To control which pager is used, set the
+Specify when to use the pager. To control which pager is used, set the PAGER or
-PAGER or BAT_PAGER environment variables (the latter takes precedence) or
+BAT_PAGER environment variables (the latter takes precedence) or use the '\-\-pager'
-use the '\-\-pager' option. To disable the pager permanently, set BAT_PAGER
+option. To disable the pager permanently, set BAT_PAGER to an empty string or set
-to an empty string or set '\-\-paging=never' in the configuration file.
+\&'\-\-paging=never' in the configuration file. Possible values: *auto*, never, always.
-Possible values: *auto*, never, always.
 .HP
 \fB\-\-pager\fR <command>
 .IP
-Determine which pager is used. This option will overwrite the PAGER and
+Determine which pager is used. This option will overwrite the PAGER and BAT_PAGER
-BAT_PAGER environment variables. The default pager is 'less'. To disable
+environment variables. The default pager is 'less'. To disable the pager completely, use
-the pager completely, use the '\-\-paging' option. Example: '\-\-pager "less
+the '\-\-paging' option. Example: '\-\-pager "less \fB\-RF\fR"'.
-\fB\-RF\fR"'.
 .HP
 \fB\-m\fR, \fB\-\-map\-syntax\fR <from:to>...
 .IP
-Map a file extension or file name to an existing syntax (specified by a
+Map a file extension or file name to an existing syntax (specified by a file extension
-file extension or file name). For example, to
+or file name). For example, to highlight *.build files with the Python syntax, use '\-m
-highlight *.build files with the Python syntax, use '\-m build:py'. To
+build:py'. To highlight files named '.myignore' with the Git Ignore syntax, use '\-m
-highlight files named '.myignore' with the Git Ignore syntax, use '\-m
 \&.myignore:gitignore'.
 .HP
 \fB\-\-theme\fR <theme>
 .IP
-Set the theme for syntax highlighting. Use '\-\-list\-themes' to see all
+Set the theme for syntax highlighting. Use '\-\-list\-themes' to see all available themes.
-available themes. To set a default theme, add the '\-\-theme="..."' option
+To set a default theme, add the '\-\-theme="..."' option to the configuration file or
-to the configuration file or export the BAT_THEME environment variable
+export the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
-(e.g.: export BAT_THEME="...").
 .HP
 \fB\-\-list\-themes\fR
 .IP
@@ -112,12 +119,11 @@ Display a list of supported themes for syntax highlighting.
 .HP
 \fB\-\-style\fR <style\-components>
 .IP
-Configure which elements (line numbers, file headers, grid borders, Git
+Configure which elements (line numbers, file headers, grid borders, Git modifications,
-modifications, ..) to display in addition to the file contents. The
+\&..) to display in addition to the file contents. The argument is a comma\-separated list
-argument is a comma\-separated list of components to display (e.g.
+of components to display (e.g. 'numbers,changes,grid') or a pre\-defined style ('full').
-\&'numbers,changes,grid') or a pre\-defined style ('full'). To set a default
+To set a default style, add the '\-\-style=".."' option to the configuration file or
-style, add the '\-\-style=".."' option to the configuration file or export
+export the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible
-the BAT_STYLE environment variable (e.g.: export BAT_STYLE=".."). Possible
 values: *auto*, full, plain, changes, header, grid, numbers, snip.
 .HP
 \fB\-r\fR, \fB\-\-line\-range\fR <N:M>...
@@ -138,8 +144,8 @@ Display a list of supported languages for syntax highlighting.
 .HP
 \fB\-u\fR, \fB\-\-unbuffered\fR
 .IP
-This option exists for POSIX\-compliance reasons ('u' is for 'unbuffered').
+This option exists for POSIX\-compliance reasons ('u' is for 'unbuffered'). The output is
-The output is always unbuffered \- this option is simply ignored.
+always unbuffered \- this option is simply ignored.
 .HP
 \fB\-h\fR, \fB\-\-help\fR
 .IP
@@ -148,13 +154,20 @@ Print this help message.
 \fB\-V\fR, \fB\-\-version\fR
 .IP
 Show version information.
-.SH "ARGS"
+.SH "POSITIONAL ARGUMENTS"
+.HP
+\fB<FILE>...\fR
 .IP
-<FILE>...
+Files to print and concatenate. Use a dash ('\-') or no argument at all to read from
-.IP
+standard input.
-File(s) to print / concatenate. Use a dash ('\-') or no argument at all to read
-from standard input.
 .SH "SUBCOMMANDS"
-.IP
+.HP
-cache
+\fBcache\fR - Modify the syntax\-definition and theme cache.
-Modify the syntax\-definition and theme cache
+.SH "FILES"
+{{PROJECT_EXECUTABLE}} 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:
+
+\fB{{PROJECT_EXECUTABLE}} --config-file\fR
+
+Alternatively, you can use the BAT_CONFIG_PATH environment variable to point bat to a non-default
+location of the configuration file.