From c5e7f5f185aba4447de2d5ff3ae4731c39178903 Mon Sep 17 00:00:00 2001
From: Ethan P <eth-p+git@hidden.email>
Date: Wed, 24 Mar 2021 19:00:35 -0700
Subject: [PATCH] docs: Add docs for batpipe

---
 doc/batpipe.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 doc/batpipe.md

diff --git a/doc/batpipe.md b/doc/batpipe.md
new file mode 100644
index 0000000..ae68711
--- /dev/null
+++ b/doc/batpipe.md
@@ -0,0 +1,75 @@
+# bat-extras: batpipe
+
+A `less` (and `bat`) preprocessor for viewing more types of files in the terminal.
+
+The only thing better than syntax highlighting? Syntax highlighting *and* code formatting. This script combines the best of both worlds by using [various formatters](#Languages) to format source files before using `bat` to highlight them.
+
+
+
+## Usage
+Like [lesspipe](https://github.com/wofr06/lesspipe), `batpipe` is designed to work with programs that support preprocessing with the `LESSOPEN` environment variable. Setting up `batpipe` will depend on your shell:
+
+**Bash:**
+
+    eval "$(batpipe)"
+
+**Fish:**
+
+    eval (batpipe)
+
+
+
+## Built-in Viewers
+
+| Files                | Program                     |
+| -------------------- | --------------------------- |
+| Directories          | `ls`                        |
+| `*.tar`, `*.tar.gz`  | `tar`                       |
+
+
+
+## External Viewers
+
+For file formats that aren't supported by default, an external file viewer can be added to `batpipe` through the external viewer API.
+
+External viewers are be added to batpipe by creating bash scripts inside the `~/.config/batpipe/viewers.d/` directory.
+
+### Creating Viewers
+
+Viewers must define two functions and append the viewer's name to the `$BATPIPE_VIEWERS` array.
+
+ - `viewer_${viewer}_supports [file_path] [file_basename]`
+ - `viewer_${viewer}_process [file_path] [inner_file_path]`
+
+The `viewer_${viewer}_supports` function is called to determine if the external viewer is capable of viewing the provided file. If this function returns successfully, the corresponding `process` function will be called.  
+
+### API
+
+    $BATPIPE_VIEWERS      -- An array of loaded file viewers.
+    $BATPIPE_ENABLE_COLOR -- Whether color is supported. (`true`|`false`)
+    $BATPIPE_INSIDE_LESS  -- Whether batpipe is inside less. (`true`|`false`)
+    
+    batpipe_header [pattern] [...]    -- Print a viewer header line.
+    batpipe_subheader [pattern] [...] -- Print a viewer subheader line.
+
+    strip_trailing_slashes [path]     -- Strips trailing slashes from a path.
+
+
+
+
+## Caveats
+
+- By default, `batpipe` will not use colors when previewed inside `less`.
+  Colors must be explicitly enabled with `BATPIPE=color`.
+
+
+## Installation
+
+This script is a part of the `bat-extras` suite of scripts. You can find install instructions [here](../README.md#installation).
+
+
+
+## Issues?
+
+If you find an issue or have a feature suggestion, make a pull request or issue through GitHub!
+Contributions are always welcome.