documentation changes

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

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}

    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.

    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 ;

    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