From gavin.simpson at ucl.ac.uk  Wed Jun 18 21:47:51 2008
From: gavin.simpson at ucl.ac.uk (Gavin Simpson)
Date: Wed, 18 Jun 2008 20:47:51 +0100
Subject: [Rd] bug in (and patch for) example preserving device 'ask' state
	[Was	Re: example() and "ask"]
In-Reply-To: <1213792100.30251.48.camel@prometheus.geog.ucl.ac.uk>
References: <1213792100.30251.48.camel@prometheus.geog.ucl.ac.uk>
Message-ID: <1213818471.30251.100.camel@prometheus.geog.ucl.ac.uk>

Dear List,

In investigating this a bit more, I've just realised that the source has
this nice comment (in the svn trunk) indicating that there is a problem,
and it is known about:

        ## <FIXME>
        ## This ensures that any device opened by the examples will
        ## have ask = TRUE set, but it does not return the device to
        ## the expected 'ask' state if it is left as the current device.
        ## </FIXME>
        op <- options(device.ask.default = TRUE)
        on.exit(options(op), add = TRUE)

I can get what appears to be correct behaviour if I replace the two
lines above with:

        oldask <- grDevices::devAskNewPage(ask = TRUE)
        on.exit(grDevices::devAskNewPage(oldask), add = TRUE)

Which are the same as the two lines in the if statement directly above,
which checks if .Device is not "null device". This suggests that the
check for "null device" is not needed and we can just reset the 'ask'
status to what it was before example was called. This is the approach I
have taken in the attached patch.

If I understand what ?example means when discussing argument 'ask',
there is an added complication, in that an example may open new devices.
If we take the above fix then the device that is returned to
the /original/ 'ask' state will be the last newly opened device. An
alternative might be to recall which device was current upon calling
example() and then to make that device active and reset its 'ask' state.

This is the approach I have taken in the attached patch, produced via
svn diff against the current R devel trunk.

In the event that the device that was current gets closed during the
example, then upon exit and attempt to reset what was the current
device, the next device is made active and its 'ask' status is set to
the original 'ask' status. This is the behaviour of dev.set when
argument 'which' is not an available device.

I've built R devel (r45948) and tested this patch as best I can here
within an R session and it works ok for the limited use-cases I tried. I
didn't try an explicit example that opens an additional new device as
part of the example as I don't have one of those to hand. I did run make
check-all and there were no problems, but I guess this was all not
interactive so didn't really test the new code. If anyone knows of such
an example, I'd be happy to run it in my local R devel build and see how
the new code performs.

All the best,

G

On Wed, 2008-06-18 at 13:28 +0100, Gavin Simpson wrote:
> Dear list,
> 
> Is it intentional that example() opens a new device and leaves it in a
> mode where it asks (prompts) the user to Press return to see the next
> plot for *all* subsequent plots on that device.
> 
> For example; with an already opened device, example() works as I would
> expect:
> 
> > par("ask")
> [1] FALSE
> > example(lm)
> .... OUTPUT CLIPPED ....
> lm> plot(lm.D9, las = 1)      # Residuals, Fitted, ...
> Hit <Return> to see next plot: 
> 
> lm> par(opar)
> 
> lm> ## model frame :
> lm> stopifnot(identical(lm(weight ~ group, method = "model.frame"),
> lm+                     model.frame(lm.D9)))
> > plot(1:10)
> >
> 
> So with an already opened device, plots /within/ example prompt the user
> (by default) but at the end of the example, we return to default and we
> are not prompted to display subsequent plots on that device (par("ask)
> == FALSE)
> 
> However, if example opens a device (i.e. example is the first plotting
> function called in a session), then the device remains in "prompt" mode:
> 
> > # continue example from above, so close the device
> > dev.off()
> null device 
>           1 
> > example(lm) # will open device when required
> .... output suppressed ....
> lm> plot(lm.D9, las = 1)      # Residuals, Fitted, ...
> Hit <Return> to see next plot: 
> 
> lm> par(opar)
> 
> lm> ## model frame :
> lm> stopifnot(identical(lm(weight ~ group, method = "model.frame"),
> lm+                     model.frame(lm.D9)))
> > par("ask")
> [1] TRUE
> > plot(1:10)
> Hit <Return> to see next plot: 
> 
> Device remains in "prompt" mode.
> 
> I would have expected example() to clean up and return par("ask") to
> what it was before example() was called in the case where it opens it's
> own device, just as it does if called with an already open and active
> device.
> 
> If this is intentional, it doesn't strike me as being intuitive or user
> friendly. Is there scope and a will to change this behaviour?
> 
> This is with R 2.7.1RC and R 2.8.0 to be:
> 
> > version
>                _                                     
> platform       x86_64-unknown-linux-gnu              
> arch           x86_64                                
> os             linux-gnu                             
> system         x86_64, linux-gnu                     
> status         RC                                    
> major          2                                     
> minor          7.1                                   
> year           2008                                  
> month          06                                    
> day            16                                    
> svn rev        45948                                 
> language       R                                     
> version.string R version 2.7.1 RC (2008-06-16 r45948)
> 
> > version
>                _                                                               
> platform       x86_64-unknown-linux-gnu                                        
> arch           x86_64                                                          
> os             linux-gnu                                                       
> system         x86_64, linux-gnu                                               
> status         Under development (unstable)                                    
> major          2                                                               
> minor          8.0                                                             
> year           2008                                                            
> month          06                                                              
> day            18                                                              
> svn rev        45948                                                           
> language       R                                                               
> version.string R version 2.8.0 Under development (unstable) (2008-06-18 r45948)
> 
> Many thanks,
> 
> G
> -- 
> %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
>  Dr. Gavin Simpson             [t] +44 (0)20 7679 0522
>  ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
>  Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
>  Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
>  UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
> %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
-- 
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
 Dr. Gavin Simpson             [t] +44 (0)20 7679 0522
 ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
 Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
 Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
 UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
-------------- next part --------------
A non-text attachment was scrubbed...
Name: patch_example.diff
Type: text/x-patch
Size: 1212 bytes
Desc: not available
URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20080618/5a784b84/attachment.bin>


[Rd] bug in (and patch for) example preserving device 'ask' state [Was Re: example() and "ask"]
Gavin Simpson