[R] grDevices::bringToTop is documented but not available: A bug?

[Martin Maechler]

>>>>> Duncan Murdoch 
>>>>>     on Thu, 21 Nov 2024 05:41:58 -0500 writes:

    > It's a Windows-only function.  It looks like revision
    > r75103 moved it out of the Windows section of the help
    > pages six years ago.  Some other help pages were similarly
    > moved, e.g.  - ?windows and ?windowsFonts, document the
    > functions as being Windows-only.  - ?msgWindow and
    > ?windows.options have the same issue as ?bringToTop.

    > Maybe someone remembers the intention of that move...

    > Duncan Murdoch

Yes, I do.
R-core had agreed that the R Reference Manual  should not be
platform dependent and we would want all such documentation to
be available and the same, independently of the platform,
*but* then of course, mark  paragraphs (mostly) or full "pages"
(in this case) as  "Windows only" / etc.

I had been working quite a lot afterwards to get close to this
goal, but there are still parts to do, notably in the "devices space",
where *some* platform dependency may seem ok.

==> To answer the OP's question:

 Yes, there *is* a documentation bug here:

 All three help you (Duncan) mention above should be marked with something like
 __"Only on Windows"__

Martin

--
Martin Maechler
ETH Zurich   and   R Core team

    > On 2024-11-20 1:09 p.m., ressw using meer.net wrote:
    >> 
    >> 
    >> There is help for grDevices::bringToTop but the function
    >> is not present.
    >> 
    >>> bringToTop()
    >> Error in bringToTop() : could not find function
    >> "bringToTop"
    >>> grDevices::bringToTop()
    >> Error: 'bringToTop' is not an exported object from
    >> 'namespace:grDevices'
    >>> getAnywhere(bringToTop)
    >> no object named ‘bringToTop’ was found # help output:
    >>> ?bringToTop
    >> bringToTop package:grDevices R Documentation
    >> 
    >> Assign Focus to a Window
    >> 
    >> ... etc
    >> 
    >> Is this considered a bug?
    >> 
    >> (first time posting; hope I did this right)
    >> 
    >> sessionInfo:
    >> 
    >> R version 4.4.2 (2024-10-31) Platform:
    >> x86_64-pc-linux-gnu Running under: Ubuntu 20.04.6 LTS
    >> 
    >> Matrix products: default BLAS:
    >> /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.9.0 LAPACK:
    >> /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.9.0
    >> 
    >> locale: [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C [3]
    >> LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8 [5]
    >> LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8 [7]
    >> LC_PAPER=en_US.UTF-8 LC_NAME=C [9] LC_ADDRESS=C
    >> LC_TELEPHONE=C [11] LC_MEASUREMENT=en_US.UTF-8
    >> LC_IDENTIFICATION=C
    >> 
    >> time zone: America/Los_Angeles tzcode source: system
    >> (glibc)
    >> 
    >> attached base packages: [1] stats graphics grDevices
    >> utils datasets methods base
    >> 
    >> loaded via a namespace (and not attached): [1]
    >> compiler_4.4.2
    >> 
    >> Output from "library(help=grDevices)"
    >> 
    >> Information on package ‘grDevices’
    >> 
    >> Description:
    >> 
    >> Package: grDevices Version: 4.4.2 Priority: base Title:
    >> The R Graphics Devices and Support for Colours and Fonts
    >> Author: R Core Team and contributors worldwide
    >> Maintainer: R Core Team
    >> <do-use-Contact-address using r-project.org> Contact: R-help
    >> mailing list <r-help using r-project.org> Description: Graphics
    >> devices and support for base and grid graphics.  License:
    >> Part of R 4.4.2 Suggests: KernSmooth NeedsCompilation:
    >> yes Built: R 4.4.2; x86_64-pc-linux-gnu; 2024-11-04
    >> 01:29:04 UTC; unix
    >> 
    >> ______________________________________________
    >> R-help using r-project.org mailing list -- To UNSUBSCRIBE and
    >> more, see https://stat.ethz.ch/mailman/listinfo/r-help
    >> PLEASE do read the posting guide
    >> https://www.R-project.org/posting-guide.html and provide
    >> commented, minimal, self-contained, reproducible code.

    > ______________________________________________
    > R-help using r-project.org mailing list -- To UNSUBSCRIBE and
    > more, see https://stat.ethz.ch/mailman/listinfo/r-help
    > PLEASE do read the posting guide
    > https://www.R-project.org/posting-guide.html and provide
    > commented, minimal, self-contained, reproducible code.