documentation changes

doc/gforth.texi.in

@@ -12430,18 +12430,42 @@ it, too (@pxref{Emacs and Gforth}).
 
 However, several Forth systems have a different kind of IDE: The Forth
 command line is the hub of the environment; you can view the source
-from there in various ways, and call an editor if needed.  An
-advantage of this approach is that it allows you to use your favourite
-editor.
+from there in various ways, and call an editor if needed.
 
 Gforth also implements such an IDE.  It mostly follows the conventions
 of SwiftForth where they exist, but implements features beyond them.
 
+An advantage of this approach is that it allows you to use your
+favourite editor: set the environment variable @code{EDITOR} to your
+favourite editor, and the editing commands will call that editor;
+Gforth invokes some GUI editors in the background (so you do not need
+to finish editing to continue with your Forth session), terminal
+editors in the foreground (default for editors not known to Gforth is
+foreground).  If you have not set @code{EDITOR}, the default editor is
+@file{vi}.
+
 doc-locate
+
+The @emph{current location} is set by a number of other words in
+addition to @code{locate}.  Also, when an error happens while loading
+a file, the location of the error becomes the current location.
+
+A number of words work with the current location:
+
+doc-l
 doc-n
 doc-b
-doc-l
 doc-g
+
+You can control how many lines @code{l}, @code{n} and @code{b} show by
+changing the values:
+
+doc-before-locate
+doc-after-locate
+
+Finally, you can directly go to the source code of a word in the
+editor with
+
 doc-edit
 
 @node Locating documentation, Locating uses of a word, Locating source code definitions, Programming Tools

except.fs

@@ -95,8 +95,10 @@ variable located-bottom \ last line to display with l
 2variable located-slurped \ the contents of the file in located-view, or 0 0
 
 \ lines to show before and after locate
-3 value before-locate
-12 value after-locate
+3 value before-locate ( -- u ) \ gforth
+\G number of lines shown before current location (default 3).
+12 value after-locate ( -- u ) \ gforth
+\G number of lines shown after current location (default 12).
 
 : view>filename# ( view -- u )
     \G filename-number of view (obtained by @code{name>view}) see @code{filename#>str}

locate1.fs

@@ -113,8 +113,7 @@ variable included-file-buffers
     view>filename# loadfilename#>str ;
 
 : l ( -- )
-    \g Display source code lines at compiler error location, or
-    \g @code{locate}, @code{help}, @code{ww}, or @code{tt} location.
+    \g Display source code lines at the current location.
     current-location?
     cr located-view @ view>filename type ': emit
     located-top @ dec.
@@ -127,23 +126,22 @@ variable included-file-buffers
     name-set-located-view l ;
 
 : locate ( "name" -- ) \ gforth
-    \g Show the source code of the word @i{name}.
+    \g Show the source code of the word @i{name} and set the current
+    \g location there.
     (') locate-name ;
 
 ' locate alias view ( "name" -- ) \ gforth
 
 : n ( -- ) \ gforth
-    \g Display lines after the last source or documentation file
-    \g display (error, @code{locate}, @code{help}, @code{ww},
-    \g @code{tt}).
+    \g Display lines behind the current location, or behind the last
+    \g @code{n} or @code{b} output (whichever was later).
     current-location?
     located-bottom @ dup located-top ! form drop 2/ + located-bottom !
     set-bn-view l1 ;
 
 : b ( -- ) \ gforth
-    \g Display lines before the last source or documentation
-    \g file display (error, @code{locate}, @code{help}, @code{ww},
-    \g @code{tt}).
+    \g Display lines before the current location, or before the last
+    \g @code{n} or @code{b} output (whichever was later).
     current-location?
     located-top @ dup located-bottom ! form drop 2/ - 0 max located-top !
     set-bn-view l1 ;
@@ -156,9 +154,8 @@ variable included-file-buffers
     throw ;
 
 Defer g ( -- ) \ gforth
-    \g Enter the editor at the compiler error location, or the
-    \g @code{locate}, @code{n}, @code{b}, @code{help}, @code{ww}, or
-    \g @code{tt} location.
+    \g Enter the editor at the current location, or at the start of
+    \g the last @code{n} or @code{b} output (whichever was later).
 ' extern-g is g
 
 : edit ( "name" -- ) \ gforth