Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
> None of these solutions seem perfect to me. I think that my suggestion is the > most natural, but as you point out it won’t work in all contexts. Perhaps the > safest approach is to give the vignette() command in the text of the help > file, one of your suggestions. If you do that, and you use pkgdown (https://pkgdown.r-lib.org), that code chunk will automatically be linked to the vignette when you build the website. Hadley -- http://hadley.nz __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
Dear Georgi,
Thank you for this.
None of these solutions seem perfect to me. I think that my suggestion is the
most natural, but as you point out it won’t work in all contexts. Perhaps the
safest approach is to give the vignette() command in the text of the help file,
one of your suggestions.
Best,
John
> On Nov 20, 2018, at 4:36 AM, Georgi Boshnakov
> wrote:
>
> It is somewhat problematic to make the link to the vignette fully portable.
> The solution with "../doc/..." may not work if the reference manual is read
> off the CRAN page of a package. For a CRAN package, an alternative is to link
> to the vignette on its CRAN page (if the vignette is already there), with the
> downside that the link will not work offline.
>
> An alternative, which can be used along with a link, is to give a command
> that opens the vignette \code{vignette("xxx", package = "pkg")} or even
> \code{browseVignettes(package = "pkg")}. This will be directly usable also
> when the help is rendered in text mode. The vignette() command could also be
> put in the "Examples" section.
>
> Georgi Boshnakov
>
>
> -Original Message-
> From: R-package-devel [mailto:r-package-devel-boun...@r-project.org] On
> Behalf Of Fox, John
> Sent: 20 November 2018 01:16
> To: Hadley Wickham
> Cc: R Package Development
> Subject: Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
>
> Dear Hadley,
>
> You're right -- my approach was flawed and the document doesn't open even
> when the file URL is hard-coded in the .Rd file. With that hint, I found the
> following solution:
>
> \href{../doc/partial-residuals.pdf}{partial-residuals vignette}
>
> This works and passes package checking. A caveat: I tried it only under
> Windows, both inside and outside of RStudio. I'll follow up on macOS and
> Linux and report if there are problems.
>
> I'm surprised that this question hasn't arisen more frequently -- wanting to
> link to vignettes from help pages seems natural to me. I found a couple of
> queries in a web search but no solution.
>
> Thanks for this,
> John
>
>> -Original Message-
>> From: Hadley Wickham [mailto:h.wick...@gmail.com]
>> Sent: Monday, November 19, 2018 6:21 PM
>> To: Fox, John
>> Cc: R Package Development
>> Subject: Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
>>
>> On Mon, Nov 19, 2018 at 4:49 PM Fox, John wrote:
>>>
>>> Dear r-package-devel list members,
>>>
>>> I'd like to create a link to a package vignette from a help file in the same
>> package, for example to the "partial-residuals" vignette in the effects
>> package
>> from effect.Rd. I'm able to generate a URL for the vignette as follows:
>>>
>>>\Sexpr[results=text]{paste0("file://", system.file("doc",
>>> "partial-residuals.pdf", package="effects"))}
>>>
>>> but I'm unable to link to the resulting text string using href{}{} or url{}
>> because \Sexpr[etc]{etc.} is treated as verbatim text rather than evaluated.
>>>
>>> Is there a way around this problem or another approach that works?
>>
>> Have you confirmed that a raw file:// url works? I would be mildly
>> surprised if
>> it did, given my understanding of how web browser security works (which is
>> patchy, but you should still check before going too far down this path).
>>
>> Don't you just need `results=rd` ?
>>
>> \Sexpr[results=rd]{paste0("\\url{file://", system.file("doc", "partial-
>> residuals.pdf", package="effects"), "}")}
>>
>> Hadley
>>
>> --
>> http://hadley.nz
> __
> R-package-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
It is somewhat problematic to make the link to the vignette fully portable.
The solution with "../doc/..." may not work if the reference manual is read off
the CRAN page of a package. For a CRAN package, an alternative is to link to
the vignette on its CRAN page (if the vignette is already there), with the
downside that the link will not work offline.
An alternative, which can be used along with a link, is to give a command that
opens the vignette \code{vignette("xxx", package = "pkg")} or even
\code{browseVignettes(package = "pkg")}. This will be directly usable also when
the help is rendered in text mode. The vignette() command could also be put in
the "Examples" section.
Georgi Boshnakov
-Original Message-
From: R-package-devel [mailto:r-package-devel-boun...@r-project.org] On Behalf
Of Fox, John
Sent: 20 November 2018 01:16
To: Hadley Wickham
Cc: R Package Development
Subject: Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
Dear Hadley,
You're right -- my approach was flawed and the document doesn't open even when
the file URL is hard-coded in the .Rd file. With that hint, I found the
following solution:
\href{../doc/partial-residuals.pdf}{partial-residuals vignette}
This works and passes package checking. A caveat: I tried it only under
Windows, both inside and outside of RStudio. I'll follow up on macOS and Linux
and report if there are problems.
I'm surprised that this question hasn't arisen more frequently -- wanting to
link to vignettes from help pages seems natural to me. I found a couple of
queries in a web search but no solution.
Thanks for this,
John
> -Original Message-
> From: Hadley Wickham [mailto:h.wick...@gmail.com]
> Sent: Monday, November 19, 2018 6:21 PM
> To: Fox, John
> Cc: R Package Development
> Subject: Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
>
> On Mon, Nov 19, 2018 at 4:49 PM Fox, John wrote:
> >
> > Dear r-package-devel list members,
> >
> > I'd like to create a link to a package vignette from a help file in the same
> package, for example to the "partial-residuals" vignette in the effects
> package
> from effect.Rd. I'm able to generate a URL for the vignette as follows:
> >
> > \Sexpr[results=text]{paste0("file://", system.file("doc",
> > "partial-residuals.pdf", package="effects"))}
> >
> > but I'm unable to link to the resulting text string using href{}{} or url{}
> because \Sexpr[etc]{etc.} is treated as verbatim text rather than evaluated.
> >
> > Is there a way around this problem or another approach that works?
>
> Have you confirmed that a raw file:// url works? I would be mildly surprised
> if
> it did, given my understanding of how web browser security works (which is
> patchy, but you should still check before going too far down this path).
>
> Don't you just need `results=rd` ?
>
> \Sexpr[results=rd]{paste0("\\url{file://", system.file("doc", "partial-
> residuals.pdf", package="effects"), "}")}
>
> Hadley
>
> --
> http://hadley.nz
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
Dear Hadley,
You're right -- my approach was flawed and the document doesn't open even when
the file URL is hard-coded in the .Rd file. With that hint, I found the
following solution:
\href{../doc/partial-residuals.pdf}{partial-residuals vignette}
This works and passes package checking. A caveat: I tried it only under
Windows, both inside and outside of RStudio. I'll follow up on macOS and Linux
and report if there are problems.
I'm surprised that this question hasn't arisen more frequently -- wanting to
link to vignettes from help pages seems natural to me. I found a couple of
queries in a web search but no solution.
Thanks for this,
John
> -Original Message-
> From: Hadley Wickham [mailto:h.wick...@gmail.com]
> Sent: Monday, November 19, 2018 6:21 PM
> To: Fox, John
> Cc: R Package Development
> Subject: Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
>
> On Mon, Nov 19, 2018 at 4:49 PM Fox, John wrote:
> >
> > Dear r-package-devel list members,
> >
> > I'd like to create a link to a package vignette from a help file in the same
> package, for example to the "partial-residuals" vignette in the effects
> package
> from effect.Rd. I'm able to generate a URL for the vignette as follows:
> >
> > \Sexpr[results=text]{paste0("file://", system.file("doc",
> > "partial-residuals.pdf", package="effects"))}
> >
> > but I'm unable to link to the resulting text string using href{}{} or url{}
> because \Sexpr[etc]{etc.} is treated as verbatim text rather than evaluated.
> >
> > Is there a way around this problem or another approach that works?
>
> Have you confirmed that a raw file:// url works? I would be mildly surprised
> if
> it did, given my understanding of how web browser security works (which is
> patchy, but you should still check before going too far down this path).
>
> Don't you just need `results=rd` ?
>
> \Sexpr[results=rd]{paste0("\\url{file://", system.file("doc", "partial-
> residuals.pdf", package="effects"), "}")}
>
> Hadley
>
> --
> http://hadley.nz
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] creating a link to a vignette in a .Rd file
On Mon, Nov 19, 2018 at 4:49 PM Fox, John wrote:
>
> Dear r-package-devel list members,
>
> I'd like to create a link to a package vignette from a help file in the same
> package, for example to the "partial-residuals" vignette in the effects
> package from effect.Rd. I'm able to generate a URL for the vignette as
> follows:
>
> \Sexpr[results=text]{paste0("file://", system.file("doc",
> "partial-residuals.pdf", package="effects"))}
>
> but I'm unable to link to the resulting text string using href{}{} or url{}
> because \Sexpr[etc]{etc.} is treated as verbatim text rather than evaluated.
>
> Is there a way around this problem or another approach that works?
Have you confirmed that a raw file:// url works? I would be mildly
surprised if it did, given my understanding of how web browser
security works (which is patchy, but you should still check before
going too far down this path).
Don't you just need `results=rd` ?
\Sexpr[results=rd]{paste0("\\url{file://", system.file("doc",
"partial-residuals.pdf", package="effects"), "}")}
Hadley
--
http://hadley.nz
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
