--- a/runtime/doc/popup.txt
+++ b/runtime/doc/popup.txt
@@ -1,16 +1,26 @@
-*popup.txt*  For Vim version 8.1.  Last change: 2019 Jun 30
+*popup.txt*  For Vim version 8.1.  Last change: 2019 Jul 04
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
 
 
-Displaying text in floating window.			*popup* *popup-window*
+Displaying text in a floating window.			*popup* *popup-window*
 
-THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
 
 1. Introduction			|popup-intro|
+   Window position and size	|popup-position|
+   Closing the popup window	|popup-close|
+   Popup buffer and window	|popup-buffer|
 2. Functions			|popup-functions|
-3. Examples			|popup-examples|
+   Details			|popup-function-details|
+3. Usage			|popup-usage|
+   popup_create() arguments	|popup_create-arguments|
+   Popup text properties	|popup-props|
+   Popup filter			|popup-filter|
+   Popup callback		|popup-callback|
+   Popup scrollbar		|popup-scrollbar|
+   Popup mask			|popup-mask|
+4. Examples			|popup-examples|
 
 
 {not available if the |+textprop| feature was disabled at compile time}
@@ -55,7 +65,7 @@ If this is not what you are looking for,
 - balloon, see |balloon-eval|
 
 
-WINDOW POSITION AND SIZE			*popup-position*
+WINDOW POSITION AND SIZE				*popup-position*
 
 The height of the window is normally equal to the number of, possibly
 wrapping, lines in the buffer.  It can be limited with the "maxheight"
@@ -85,7 +95,7 @@ That way you can still see where it is, 
 that it is in.
 
 
-CLOSING THE POPUP WINDOW			*popup-close*
+CLOSING THE POPUP WINDOW				*popup-close*
 
 Normally the plugin that created the popup window is also in charge of closing
 it.  If somehow a popup hangs around, you can close all of them with: >
@@ -97,40 +107,41 @@ or by clicking anywhere inside the popup
 "close" property.  It is set by default for notifications.
 
 
-TODO:
-- Add test for when popup with mask is off the left and off the right of the
-  screen.
-- check padding/border when popup is off the left and right of the screen.
-- Have a way to scroll to the bottom? (#4577)
-- Why does 'nrformats' leak from the popup window buffer???
-- Disable commands, feedkeys(), CTRL-W, etc. in a popup window.
-  Use ERROR_IF_POPUP_WINDOW for more commands.
-- Add 'balloonpopup': instead of showing text, let the callback open a popup
-  window and return the window ID.   The popup will then be closed when the
-  mouse moves, except when it moves inside the popup.
-- For the "moved" property also include mouse movement?
-- Can the buffer be re-used, to avoid using up lots of buffer numbers?
-- Have an option to attach the popup to a text position, like text properties
-  do. (#4560)
-- Make redrawing more efficient and avoid flicker:
-    - put popup menu also put in popup_mask?
-- Invoke filter with character before mapping?
-- Figure out the size and position better.
-    if wrapping splits a double-wide character
-    if wrapping inserts indent
-- When drawing on top half a double-wide character, display ">" or "<" in the
-  incomplete cell.
-- Use a popup window for the "info" item of completion instead of using a
-  preview window.  Ideas in issue #4544.
-  How to add highlighting?
-- Implement:
-	flip option
+POPUP BUFFER AND WINDOW					*popup-buffer*
+
+If a popup function is called to create a popup from text, a new buffer is
+created to hold the text and text properties of the popup window.  The buffer
+is always associated with the popup window and manipulation is restricted:
+- the buffer has no name
+- 'buftype' is "popup"
+- 'swapfile' is off
+- 'bufhidden' is "hide"
+- 'buflisted' is off
+- 'undolevels' is -1: no undo at all
+- all other buffer-local and window-local options are set to their Vim default
+  value.
+
+It is possible to change the specifically mentioned options, but anything
+might break then, so better leave them alone.
+
+The window does have a cursor position, but the cursor is not displayed.
+
+To execute a command in the context of the popup window and buffer use
+`win_execute()`.  Example: >
+	call win_execute(winid, 'syntax enable')
+
+Options can be set on the window with `setwinvar()`, e.g.: >
+	call setwinvar(winid, '&wrap', 0)
+And options can be set on the buffer with `setbufvar()`, e.g.: >
+	call setbufvar(winbufnr(winid), '&filetype', 'java')
+Note that this does not trigger autocommands.  Use `win_execute()` if you do
+need them.
+
+
 
 ==============================================================================
 2. Functions						*popup-functions*
 
-THIS IS UNDER DESIGN - ANYTHING MAY STILL CHANGE
-
 Creating a popup window:
 	|popup_create()|	centered in the screen
 	|popup_atcursor()|	just above the cursor position, closes when
@@ -159,9 +170,9 @@ Other:
 	|popup_getpos()|	get actual position and size of a popup
 
 
-[functions help to be moved to eval.txt later]
+DETAILS						*popup-function-details*
 
-popup_atcursor({what}, {options})			 *popup_atcursor()*
+popup_atcursor({what}, {options})			*popup_atcursor()*
 		Show the {what} above the cursor, and close it when the cursor
 		moves.  This works like: >
 			call popup_create({what}, {
@@ -199,7 +210,7 @@ popup_create({what}, {options})				*popu
 		the popup closes.
 
 		{options} is a dictionary with many possible entries.
-		See |popup_create-usage| for details.
+		See |popup_create-arguments| for details.
 
 		Returns a window-ID, which can be used with other popup
 		functions.  Use `winbufnr()` to get the number of the buffer
@@ -417,38 +428,10 @@ popup_settext({id}, {text})				*popup_se
 		by the different text.
 
 
-POPUP BUFFER AND WINDOW					*popup-buffer*
-
-A new buffer is created to hold the text and text properties of the popup
-window.  The buffer is always associated with the popup window and
-manipulation is restricted:
-- the buffer has no name
-- 'buftype' is "popup"
-- 'swapfile' is off
-- 'bufhidden' is "hide"
-- 'buflisted' is off
-- 'undolevels' is -1: no undo at all
-- all other buffer-local and window-local options are set to their Vim default
-  value.
+==============================================================================
+3. Usage						*popup-usage*
 
-It is possible to change the specifically mentioned options, but anything
-might break then, so better leave them alone.
-
-The window does have a cursor position, but the cursor is not displayed.
-
-To execute a command in the context of the popup window and buffer use
-`win_execute()`.  Example: >
-	call win_execute(winid, 'syntax enable')
-
-Options can be set on the window with `setwinvar()`, e.g.: >
-	call setwinvar(winid, '&wrap', 0)
-And options can be set on the buffer with `setbufvar()`, e.g.: >
-	call setbufvar(winbufnr(winid), '&filetype', 'java')
-Note that this does not trigger autocommands.  Use `win_execute()` if you do
-need them.
-
-
-POPUP_CREATE() ARGUMENTS				*popup_create-usage*
+POPUP_CREATE() ARGUMENTS			 *popup_create-arguments*
 
 The first argument of |popup_create()| (and the second argument to
 |popup_settext()|) specifies the text to be displayed, and optionally text
@@ -709,9 +692,9 @@ To make the four corners transparent:
 	[[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]]
 
 ==============================================================================
-3. Examples						*popup-examples*
+4. Examples						*popup-examples*
 
-TODO
+TODO: more interesting examples
 					*popup_dialog-example*
 Prompt the user to press y/Y or n/N: >