[Rd] Link to pdf documentation from other package ?

[Duncan Murdoch]

On 11/18/2009 8:01 AM, ml-it-r-devel at epigenomics.com wrote:
> Ulrike Grömping wrote, On 11/18/09 13:28:
>> Duncan Murdoch schrieb:
>>> Ulrike Groemping wrote:
>>>>
>>>> Duncan Murdoch-2 wrote:
>>>>  
>>>>> Ulrike Groemping wrote:
>>>>>   
>>>>>> Dear developeRs,
>>>>>>
>>>>>> I have not found anything recent about how to link to a vignette or
>>>>>> other
>>>>>> documentation from within Rd-files. Is this now possible with the new
>>>>>> help
>>>>>> system ? For example, I would like to link to the file AlgDesign.pdf
>>>>>> provided within the doc directory of package AlgDesign.
>>>>>>
>>>>>>         
>>>>> Yes, you can do it with a \url{} macro.  Use a relative link, acting
>>>>> as though the starting page is located in
>>>>> /library/AlgDesign/html/*.  So \url{../doc/AlgDesign.pdf}
>>>>> should work from the same package,
>>>>> \url{../../AlgDesign/doc/AlgDesign.pdf} from elsewhere.  Please let
>>>>> me know if this doesn't work, I haven't tested.
>>>>>
>>>>> Duncan Murdoch
>>>>>
>>>>>     
>>>>
>>>> Yes, this works, thanks! Is it also possible to display an
>>>> alternative text
>>>> instead of the URL itself, like with other links (e.g. show text
>>>> "Open pdf"
>>>> that operates the link) ?
>>>>
>>>>   
>>>
>>> There's no optional text in the \url{} tag, but you could embed it in
>>> an \ifelse tag, e.g.
>>>
>>> \ifelse{html}{\url{ ....  }}{ [open pdf ...] }
>>>
>>> might work.  Using the \ifelse tag will make your package depend on R
>>> >= 2.10.0.
>>>
>>> Duncan Murdoch
>>>>   
>> Another thought: the link only works, if the two packages are installed
>> in the same library, doesn't it ? Would there be a way to make it work
>> independently of this restriction ?
> 
> you could use the Sweave like macro to compute the path inside the Rd environments
> 
> \Sexpr{file.path(system.file(package="AlgDesign", "doc"), "AlgDesign.pdf")}
> 
> described in 'Writing R extensions' 2.11
> <http://stat.ethz.ch/R-manual/R-patched/doc/manual/R-exts.html#Dynamic-pages>


That won't work with dynamic help. (It surprised me, too.)  You can't 
link to the file system from within the dynamic help pages.  You can't 
link to a file:// link, which is what you'd need to get that to work.

This is a browser restriction, for security reasons.  You don't want 
someone's Javascript to be able to read your private files, because it 
could then send them anywhere.

Within the dynamic help, you're also restricted in what files you can 
link to:  they need to be help pages, or files in the doc directory of a 
package, or a few other special cases.

Duncan Murdoch