These are great suggestions. I have updated the file to reflect them
as much as I managed to.

I have moved the discussion of the canvas and the possible graphical
systems into the "specification" section and updated the
(canvas-refresh) explanation to reflect the changes suggested.

Could people have another "last look"?

On Wed, 16 Sep 2020 at 03:13, Wolfgang Corcoran-Mathe <xxxxxx@sigwinch.xyz> wrote:
>
> On 2020-09-15 23:34 +0800, Vladimir Nikishkin wrote:
> > Could people have a look at the last commit/pull request once again?
> >
> > I have added two quite large pieces of text to explain why
> > (canvas-refresh) and (canvas-reset) are needed. I am still not sure
> > that the wording is good enough.
>
> Some important information which appears deep in the explanation of
> canvas-refresh could be moved to the specification; In general, I
> think the points could be made clearer.  Here's my attempt.  Feel free
> to use anything from the following, if I haven't misunderstood
> everything:
>
>
> Procedure: (canvas-refresh)
>
> Updates the display in an implementation-defined manner to reflect the
> state of the canvas.  Returns a system-dependent identifier (not to be
> confused with Scheme identifiers) of the canvas.  The canvas may not
> exist unless it has been drawn on.
>
> Explanation: canvas-refresh is an attempt to reconcile as many drawing
> approaches as possible.  After a call to (canvas-refresh), the state
> of the display (whatever it may be) is expected to be a faithful
> representation of the image drawn by a previous sequence of calls to
> the drawing routines, regardless of the underlying approach that a
> system is using.
>
> Many systems are likely to use a so-called "double-buffering" or
> "delayed drawing" technique, in which drawing and displaying are two
> different operations.  In these implementations, canvas-refresh might
> be called to "flush" drawing operations to the display.  Other systems
> may use other routines not specified by this SRFI to display the
> "picture value" returned by canvas-refresh.  (This is the approach
> used by the Kawa sample implementation, which displays the "picture
> value" returned by canvas-refresh in a graphical REPL.)  canvas-refresh
> thus has both "pure" and side-effecting semantics: it may change the
> display, or it may simply return a value which can be displayed.
>
> A "canvas" is anything that the drawing procedures draw on.  It may be
> a window, or a file, or some other drawing device.
>
> If canvas-refresh is called and no canvas exists, the implementation
> is expected to do something reasonable.  In the case of the reference
> implementation, canvas-refresh returns a file name that could have
> been used for drawing; the file may or may not exist.  In case of a
> window-based implementation, it is reasonable to return a value that
> could serve as a window indentifier.  If an implementation displays
> images in the REPL, canvas-refresh might return an empty picture
> value.
>
> --
> Wolfgang Corcoran-Mathe  <xxxxxx@sigwinch.xyz>
>
> "All this currying's just a phase, though it seldom hinders."
> --Fritz Ruehr

--
Yours sincerely, Vladimir Nikishkin