diff --git a/doc/pages/buffers.asciidoc b/doc/pages/buffers.asciidoc
index 9c748c05..b8106347 100644
--- a/doc/pages/buffers.asciidoc
+++ b/doc/pages/buffers.asciidoc
@@ -8,7 +8,8 @@ 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.
+They are not linked to files, so Kakoune does not warn about unsaved
+changes at exit, and the `:write` command requires an explicit filename.
 
 One particular scratch buffer, named *\*scratch*\*, is automatically
 created when there are no other buffers left in the current
@@ -49,6 +50,8 @@ 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.
+When the write end of the fifo is closed, the buffer becomes an ordinary
+<<buffers#scratch-buffers,scratch buffer>>. When the buffer is deleted,
+Kakoune closes the read end of the fifo, 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.
diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc
index 3afb8837..f24be1a9 100644
--- a/doc/pages/commands.asciidoc
+++ b/doc/pages/commands.asciidoc
@@ -19,11 +19,37 @@ of the file onto the filesystem
     change the current directory to *directory*, or the home directory if
     unspecified
 
-*edit[!]* <filename> [<line> [<column>]]::
+*edit[!]* [<switches>] <filename> [<line> [<column>]]::
     *alias* e +
     open buffer on file, go to given line and column. If file is already
     opened, just switch to this file. Use edit! to force reloading
 
+    *-debug*:::
+        The new buffer (if any) will be created as a debug buffer.
+        (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
+
+    *-existing*:::
+        If the named file does not exist, fail instead of creating a new buffer.
+
+    *-readonly*:::
+        The new buffer (if any) will be set read-only.
+
+    *-fifo* <fifoname>:::
+        Creates a new scratch buffer named <filename>, and continually appends
+        data from the fifo (named pipe) <fifoname> as it arrives.
+        (See <<buffers#fifo-buffers,`:doc buffers fifo-buffers`>>)
+
+    *-scratch*:::
+        Creates a new buffer named <filename>, which doesn't correspond to any
+        file on disk.
+        (See <<buffers#scratch-buffers,`:doc buffers scratch-buffers`>>)
+
+    *-scroll*:::
+        If used with `-fifo`, when new data arrives Kakoune will scroll the
+        buffer down to make the new data visible.
+        Otherwise, does nothing.
+
+
 *write[!]* [-sync] [<filename>]::
     *alias* w +
     write buffer to <filename> or use its name if filename is not
@@ -57,11 +83,15 @@ of the file onto the filesystem
 
 *buffer-next*::
     *alias* bn +
-    switch to the next buffer
+    switch to the next buffer.
+    Debug buffers are skipped.
+    (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
 
 *buffer-prev*::
     *alias* bp +
-    switch to the previous buffer
+    switch to the previous buffer.
+    Debug buffers are skipped.
+    (See <<buffers#debug-buffers,`:doc buffers debug-buffers`>>)
 
 *delete-buffer[!]* [<name>]::
     *alias* db +