[Bioc-devel] BioC 3.7 Windows check warning "file link zz in package yy does not exist "

On 04/18/2018 02:45 PM, Vincent Carey wrote:

On Mon, Apr 9, 2018 at 11:23 AM, Martin Morgan <
martin.morgan at roswellpark.org <mailto:martin.morgan at roswellpark.org>>
wrote:



    On 04/09/2018 10:51 AM, Ramon Diaz-Uriarte wrote:


        Dear Martin,

        On Fri, 06-April-2018, at 18:59:00, Martin Morgan
        <martin.morgan at roswellpark.org
        <mailto:martin.morgan at roswellpark.org>> wrote:

            On 04/06/2018 10:44 AM, Llu?s Revilla wrote:

                I have recently faced a similar warning.
                This is when a link to a help page of another package is
                broken (there is
                not such help page). Although those could be false
                positives:
                mclapply help page does exists in parallel package.
                as.MAList does exists in devel limma


            when \link-ing to another package, from RShowDoc("R-exts")
            section 2.5
            the [] has to name the html help page, not the name of the
            function. For
            instance, `mclapply` is documented on a man page called
            mcdummies.Rd
            (!), so '\link[parallel:mcdummies]{nearest} would presumably
not


        I am confused here: as far as I can tell, there is an
        mclapply.html file:

        http://stat.ethz.ch/R-manual/R-devel/library/parallel/html/m
clapply.html
        <http://stat.ethz.ch/R-manual/R-devel/library/parallel/html/
mclapply.html>

        In addition, when I use the \link[parallel:mcdummies] I get a
        warning when
        testing under Linux.


    yeah, this is a pretty good one. If you look at

    https://github.com/wch/r-source/tree/trunk/src/library/parallel/man
    <https://github.com/wch/r-source/tree/trunk/src/library/parallel/man>

    you'll see that there are different man pages for different
    operating systems. On windows there is mcdummies, on unix mclapply &
    friends. This seems like a bad idea (users comparing notes to work
    through a problem get different help pages!). I don't really know
    how to link explicitly to these in a conditional manner.


Does this mean that to cross-reference to MArrayLM-class, I need to find
limma source and
determine that the topic is covered in marraylm.Rd and use
\link[limma:marraylm]{MArrayLM-class} for
the cross-reference?  I don't see how this is good -- are the page names
programmatically accessible
to developers who want to cross-reference?  here's the grep result:

marraylm.Rd:\alias{MArrayLM-class}

I agree that this is a bad idea.

I think the first solution is not to use \link[pkg]{foo} when it is not
needed, which Writing R Extensions (https://cran.r-project.org/do
c/manuals/r-release/R-exts.html#Cross_002dreferences) says

  "These are rarely needed, perhaps to refer to not-yet-installed packages
(but there the HTML help system will resolve the link at run time) or in
the normally undesirable event that more than one package offers help on a
topic"

Packages you depend / import and even suggest will be installed by the
build system, so the only need is when two or more packages define the same
topic.

But even then, when faced with a WARNING, and even Bioc core team members
or reviewers for new packages hassling you about correcting WARNINGs, I
personally would trade off sanity for perfection and stick with
\link[limma]{MArrayLM-class} -- there is a WARNING, but the warning says
that it's going to treat MArrayLM-class as a topic (alias) and it'll get
resolved correctly.

Also, for what it's worth, the opinion expressed in
https://cran.r-project.org/doc/manuals/r-release/R-exts.html
#Cross_002dreferences is that the fact that these WARNINGs are often
Windows-specific is more likely that the linux check is wrong (i.e., the
WARNING should also be generated there). I will try to investigate that
further.

Martin

    And in general it seems highly fragile to link to the name of the
    help page, rather than to the alias. I'd treat the 'warning' as
    (maybe bad) advice, rather than a requirement.

        On rereading section 2.5, I think \link[pkg]{foo} should work
        too (if there
        is a foo.html file.)


    it does (but on windows there is no mclapply.html). But also on
    windows the '...treated as a topic' part of the warning actually
    indicates that R has figured out where it should link, so you get
    the warning but also a working link.

        Nevertheless, section 2.5 indicates that \link[pkg]{foo} and
        \link[pkg:bar]{foo} are rarely needed, so I'll try to remove
        them (except
        in those cases, covered in section 2.5, where "more than one
        package offers
        help on a topic")


    yes the first pass should also be the simplest -- no fancy markup
    unless necessary.

    Martin




            generate the warning. Similarly
            \link[limma:asmalist]{as.MAList}.

            There are several things that still need exploration.

            - platform-specific (I have a vague understanding that
            Windows is
            special, but that might be outdated... [at least in this
            context...])


        I am only getting the warnings under Windows (which lead me to
        think it was
        windows misbehaving).


            - recent. I have to admit to changing the text of the
            warning with this
            commit


            https://github.com/wch/r-source/commit/cbd7ca1b1aedf0405e11e
e2440fbde891cba524e
            <https://github.com/wch/r-source/commit/cbd7ca1b1aedf0405e11
ee2440fbde891cba524e>

                 but what I was intending to do was to change what it
            says, from the
            warning in release ('missing file link') to what it says,
            correctly, in
            devel 'file link ... does not exist and so has been treated
            as a topic'.
            The old text appears in release, and the new in devel, as
            anticipated.
            If I messed up somehow please let me know...

            - even with the warning, the link isn't broken in the
            dynamic help
            system (it might have been broken prior to my commit...).


        OK, thanks.

        Best,


        R.



            Martin


                HTH

                On 6 April 2018 at 16:35, Vincent Carey
                <stvjc at channing.harvard.edu
                <mailto:stvjc at channing.harvard.edu>> wrote:

                    ive seen this too apropos bigrquery on windows

                    On Fri, Apr 6, 2018 at 10:22 AM Ramon Diaz-Uriarte
                    <rdiaz02 at gmail.com <mailto:rdiaz02 at gmail.com>>

                    wrote:


                        Dear All,

                        Two packages I maintain are showing, in Windows,
                        a warning during check
                        with messages like

                        Rd warning:
                        C:/Users/biocbuild/bbs-3.7-bio
c/tmpdir/Rtmp21WlQD/R.INSTALL23343f935731/

                    OncoSimulR/man/oncoSimulIndiv.Rd:570:

                        file link 'mclapply' in package 'parallel' does
                        not exist and so has been
                        treated as a topic

                        or

                        Rd warning:
                        C:/Users/biocbuild/bbs-3.7-bio
c/tmpdir/RtmpQfQaA1/R.

                    INSTALL1ec81d5b6233/ADaCGH2/man/inputToADaCGH.Rd:45:

                        file link 'as.MAList' in package 'limma' does
                        not exist and so has been
                        treated as a topic



                        that I cannot reproduce under Linux and that I
                        think are false
                        positives. Is there a way to avoid this warning?
                        As far as I can tell,
                        those links really exist.

                        Best,


                        R.

                        --
                        Ramon Diaz-Uriarte
                        Department of Biochemistry, Lab B-25
                        Facultad de Medicina
                        Universidad Aut?noma de Madrid
                        Arzobispo Morcillo, 4
                        28029 Madrid
                        Spain

                        Phone: +34-91-497-2412

                        Email: rdiaz02 at gmail.com <mailto:
rdiaz02 at gmail.com>
                        ramon.diaz at iib.uam.es <mailto:
ramon.diaz at iib.uam.es>

                        http://ligarto.org/rdiaz

This email message may contain legally privileged and/or confidential
information.  If you are not the intended recipient(s), or the employee or
agent responsible for the delivery of this message to the intended
recipient(s), you are hereby notified that any disclosure, copying,
distribution, or use of this email message is prohibited.  If you have
received this message in error, please notify the sender immediately by
e-mail and delete this email message from your computer. Thank you.