Allow adding line wrap markers when piping screen contents

Also make some data such as scroll position, cursor position and screen
geometry available via an env var when piping. See #719

docs/changelog.rst

@@ -13,7 +13,7 @@ Changelog
 - Modify the kittens sub-system to allow creating custom kittens without any
   user interface. This is useful for creating more complex actions that can
   be bound to key presses in :file:`kitty.conf`. See
-  `https://sw.kovidgoyal.net/kitty/kittens/custom.html`_. (:iss:`870`)
+  doc:`kittens/custom`. (:iss:`870`)
 
 - Add a new ``nth_window`` action that can be used to go to the nth window and
   also previously active windows, using negative numbers. Similarly,
@@ -443,7 +443,7 @@ Changelog
 
 - Add a config option (:opt:`editor`) to set the EDITOR kitty uses (:iss:`580`)
 
-- Add a config option (:opt:`x11_hide_window_decorations`) to hide window
+- Add a config option (``x11_hide_window_decorations``) to hide window
   decorations under X11/Wayland (:iss:`607`)
 
 - Add an option to @set-window-title to make the title change non-permanent

docs/pipe.rst

@@ -0,0 +1,88 @@
+Working with the screen and history buffer contents
+======================================================
+
+
+You can pipe the contents of the current screen and history buffer as
+:file:`STDIN` to an arbitrary program using the ``pipe`` function. The program
+can be displayed in a kitty window or overlay.
+
+For example, the following in :file:`kitty.conf` will open the scrollback
+buffer in less in an overlay window, when you press :kbd:`F1`::
+
+    map f1 pipe @ansi overlay less +G -R
+
+The syntax of the ``pipe`` function is::
+
+   pipe <input placeholder> <destination window type> <command line to run>
+
+
+The piping environment
+--------------------------
+
+The program to which the data is piped has a special environment variable
+declared, ``KITTY_PIPE_DATA`` whose contents are::
+
+   KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
+
+where ``scrolled_by`` is the number of lines kitty is currently scrolled by,
+``cursor_(x|y)`` is the position of the cursor on the screen with ``(1,1)``
+being the top left corner and ``{lines},{columns}`` being the number of rows
+and columns of the screen.
+
+You can choose where to run the pipe program:
+
+``overlay``
+   An overlay window over the current kitty window
+
+``window``
+   A new kitty window
+
+``os_window``
+   A new top-level window
+
+``tab``
+   A new window in a new tab
+
+``none``
+   Run it in the background
+
+
+Input placeholders
+--------------------
+
+There are various different kinds of placeholders
+
+``@text``
+   Plain text, current screen + scrollback buffer
+
+``@ansi``
+   Text with formatting, current screen + scrollback buffer
+
+``@screen``
+   Plain text, only current screen
+
+``@ansi_screen``
+   Text with formatting, only current screen
+
+``@alternate``
+   Plain text, secondary screen. The secondary screen is the screen not currently displayed. For
+   example if you run a fullscreen terminal application, the secondary screen will
+   be the screen you return to when quitting the application.
+
+``@ansi_alternate``
+   Text with formatting, secondary screen.
+
+``@alternate_scrollback``
+   Plain text, secondary screen + scrollback, if any.
+
+``@ansi_alternate_scrollback``
+   Text with formatting, secondary screen + scrollback, if any.
+
+``none``
+   No input
+
+
+You can also add the suffix ``_wrap`` to the placeholder, in which case kitty
+will insert the carriage return at every line wrap location (where long lines
+are wrapped at screen edges). This is useful if you want to pipe to program
+that wants to duplicate the screen layout of the screen.