From 7261dba7ed9afedd1dd56a9bf1b19f6b764ef45f Mon Sep 17 00:00:00 2001 From: Delapouite Date: Fri, 10 Nov 2017 19:50:54 +0100 Subject: [PATCH] Docs: add a new buffers.asciidoc to move over FIFO parts from README --- README.asciidoc | 23 ++++-------------- doc/pages/buffers.asciidoc | 49 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 19 deletions(-) create mode 100644 doc/pages/buffers.asciidoc diff --git a/README.asciidoc b/README.asciidoc index dbcd7982f..3776a75e3 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -900,28 +900,13 @@ buffer. The following command defines `` as an alias for ``: Will remove the given alias in the given scope. If `` is specified the alias will only be removed if its current value is ``. -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 [-scroll] ---------------------------------------------- - -In this case, a buffer named `` is created which reads its content -from fifo ``. 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 <>. Menus ~~~~~ diff --git a/doc/pages/buffers.asciidoc b/doc/pages/buffers.asciidoc new file mode 100644 index 000000000..68de13602 --- /dev/null +++ b/doc/pages/buffers.asciidoc @@ -0,0 +1,49 @@ += Buffers + +== Commands + +To open buffers or navigate through the buffers list +see <>. + +== 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 [-scroll] +--------------------------------------------- + +In this case, a buffer named `` is created which reads its content +from the fifo ``. 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.