Merge remote-tracking branch 'Delapouite/buffers'

README.asciidoc

@@ -900,28 +900,13 @@ buffer. The following command defines `<alias>` as an alias for `<command>`:
 Will remove the given alias in the given scope. If `<expected>` is specified
 the alias will only be removed if its current value is `<expected>`.
 
-FIFO Buffer
+FIFO Buffers
 ~~~~~~~~~~~
 
-The `:edit` command can take a `-fifo` parameter:
+FIFO buffers are very useful for running some commands asynchronously while
+progressively displaying their result in Kakoune.
 
----------------------------------------------
-:edit -fifo <filename> [-scroll] <buffername>
----------------------------------------------
-
-In this case, a buffer named `<buffername>` is created which reads its content
-from fifo `<filename>`. When the fifo is written to, the buffer is automatically
-updated.
-
-If the `-scroll` switch is specified, the initial cursor position will be made
-such as the window displaying the buffer will scroll as new data is read.
-
-This is very useful for running some commands asynchronously while displaying
-their result in a buffer. See `rc/make.kak` and `rc/grep.kak` for examples.
-
-When the buffer is deleted, the fifo will be closed, so any program writing
-to it will receive `SIGPIPE`. This is useful as it permits to stop the writing
-program when the buffer is deleted.
+See <<doc/pages/buffers#fifo-buffers,`:doc buffers fifo-buffers`>>.
 
 Menus
 ~~~~~

doc/pages/buffers.asciidoc

@@ -0,0 +1,49 @@
+= Buffers
+
+== Commands
+
+To open buffers or navigate through the buffers list
+see <<commands#files-and-buffers,`:doc commands files-and-buffers`>>.
+
+== Scratch Buffers
+
+Scratch buffers are useful for volatile data and quick prototyping.
+They are not linked to files.
+
+One particular scratch buffer, named *\*scratch*\*, is automatically created
+when there are no other buffers left in the current session. (which is also
+the case at Kakoune's startup when no files to open have been provided)
+
+You can create you own by using the `-scratch` parameter of the `:edit` command.
+
+== Debug Buffers
+
+Debug buffers are used to gather diagnostics. They are not accessible while cycling
+over the buffers list.
+
+A specific *\*debug*\* buffer is used by Kakoune to write errors or warnings.
+This is also where the ouput of the `:debug` and the `:echo -debug` commands will land.
+
+You can create you own by using the `-debug` parameter of the `:edit` command.
+
+== FIFO Buffers
+
+The `:edit` command can take a `-fifo` parameter:
+
+---------------------------------------------
+:edit -fifo <filename> [-scroll] <buffername>
+---------------------------------------------
+
+In this case, a buffer named `<buffername>` is created which reads its content
+from the fifo `<filename>`. When the fifo is written to, the buffer is
+automatically updated.
+
+If the `-scroll` switch is specified, the window displaying the buffer
+will scroll so that the newest data is always visible.
+
+This is very useful for running some commands asynchronously while displaying
+their result in a buffer. See `rc/make.kak` and `rc/grep.kak` for examples.
+
+When the buffer is deleted, the fifo will be closed, so any program writing
+to it will receive `SIGPIPE`. This is useful as it permits to stop the writing
+program when the buffer is deleted.