Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On 09/24/2009 05:21 AM, Gabor Grothendieck wrote: On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdochmurd...@stats.uwo.ca wrote: - Ways to link from man pages to vignettes. The reverse would be nice, but it's not possible with the current design, so that would be far off. If feasible I would like to be able to link to any text, html or pdf file in the package. For example, it would be nice to be able to link to the NEWS file and pdf files that are included in the package even if they are not vignettes, etc. I would second this wish. Adding content to the package index (00Index.html) would be a bonus as well, so that we could link the files from the index page. In addition to those mentionned by Gabor, I'm also thinking about other forms of documentation that might be in a package such as unit test results, javadoc generated documentation of java code, doxygen generated documentation of c++ code, ... Romain -- Romain Francois Professional R Enthusiast +33(0) 6 28 91 30 30 http://romainfrancois.blog.free.fr |- http://tr.im/ztCu : RGG #158:161: examples of package IDPmisc |- http://tr.im/yw8E : New R package : sos `- http://tr.im/y8y0 : search the graph gallery from R __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On 23/09/2009 11:21 PM, Gabor Grothendieck wrote:
On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdoch murd...@stats.uwo.ca wrote:
- Ways to link from man pages to vignettes. The reverse would be nice, but
it's not possible with the current design, so that would be far off.
If feasible I would like to be able to link to any text, html or pdf
file in the package. For example, it would be nice to be able to link
to the NEWS file and pdf files that are included in the package even
if they are not vignettes, etc.
The \Sexpr mechanism probably allows this, though there are currently no
built-in support functions to help you get there. As I mentioned, that
could all be done by code in a contributed package.
One way would be to have one help page which contains only
\Sexpr[stage=render, results=rd]{generatePage()}
and it will be 100% generated at render time, containing whatever you
want it to contain. (Presumably you'll have some way to communicate
what you want through variables that generatePage() can see.) Each time
you link to it you'll see something different.
Duncan Murdoch
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On 09/24/2009 11:28 AM, Duncan Murdoch wrote:
On 23/09/2009 11:21 PM, Gabor Grothendieck wrote:
On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdoch
murd...@stats.uwo.ca wrote:
- Ways to link from man pages to vignettes. The reverse would be
nice, but
it's not possible with the current design, so that would be far off.
If feasible I would like to be able to link to any text, html or pdf
file in the package. For example, it would be nice to be able to link
to the NEWS file and pdf files that are included in the package even
if they are not vignettes, etc.
The \Sexpr mechanism probably allows this, though there are currently no
built-in support functions to help you get there. As I mentioned, that
could all be done by code in a contributed package.
One way would be to have one help page which contains only
\Sexpr[stage=render, results=rd]{generatePage()}
and it will be 100% generated at render time, containing whatever you
want it to contain. (Presumably you'll have some way to communicate what
you want through variables that generatePage() can see.) Each time you
link to it you'll see something different.
Duncan Murdoch
Brilliant. Thanks. That solves my question as well.
I did not see results = documented in ?Rd2HTML, what is allowed ?
Is \Sexpr ignored when rendering other formats (tex, ...) ?
or is there a way (similar to #ifdef) to only provide some content to
some renderers ?
Romain
--
Romain Francois
Professional R Enthusiast
+33(0) 6 28 91 30 30
http://romainfrancois.blog.free.fr
|- http://tr.im/ztCu : RGG #158:161: examples of package IDPmisc
|- http://tr.im/yw8E : New R package : sos
`- http://tr.im/y8y0 : search the graph gallery from R
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On 24/09/2009 5:42 AM, Romain Francois wrote:
On 09/24/2009 11:28 AM, Duncan Murdoch wrote:
On 23/09/2009 11:21 PM, Gabor Grothendieck wrote:
On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdoch
murd...@stats.uwo.ca wrote:
- Ways to link from man pages to vignettes. The reverse would be
nice, but
it's not possible with the current design, so that would be far off.
If feasible I would like to be able to link to any text, html or pdf
file in the package. For example, it would be nice to be able to link
to the NEWS file and pdf files that are included in the package even
if they are not vignettes, etc.
The \Sexpr mechanism probably allows this, though there are currently no
built-in support functions to help you get there. As I mentioned, that
could all be done by code in a contributed package.
One way would be to have one help page which contains only
\Sexpr[stage=render, results=rd]{generatePage()}
and it will be 100% generated at render time, containing whatever you
want it to contain. (Presumably you'll have some way to communicate what
you want through variables that generatePage() can see.) Each time you
link to it you'll see something different.
Duncan Murdoch
Brilliant. Thanks. That solves my question as well.
I did not see results = documented in ?Rd2HTML, what is allowed ?
Is \Sexpr ignored when rendering other formats (tex, ...) ?
or is there a way (similar to #ifdef) to only provide some content to
some renderers ?
As of yesterday, it's documented in Writing R Extensions. \Sexpr is
format-agnostic: it doesn't output HTML, it outputs plain text which is
wrapped in the appropriate HTML/LaTeX/whatever, or Rd input which is
processed by the whole system. So the generator would currently have to
use sneaky methods to figure out the format, looking at which function
called it, etc. I imagine in the long run we'll define some state
variables which the code can look at, but I'd rather see use-cases
before deciding what those should be.
Duncan Murdoch
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On 09/24/2009 12:04 PM, Duncan Murdoch wrote:
On 24/09/2009 5:42 AM, Romain Francois wrote:
On 09/24/2009 11:28 AM, Duncan Murdoch wrote:
On 23/09/2009 11:21 PM, Gabor Grothendieck wrote:
On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdoch
murd...@stats.uwo.ca wrote:
- Ways to link from man pages to vignettes. The reverse would be
nice, but
it's not possible with the current design, so that would be far off.
If feasible I would like to be able to link to any text, html or pdf
file in the package. For example, it would be nice to be able to link
to the NEWS file and pdf files that are included in the package even
if they are not vignettes, etc.
The \Sexpr mechanism probably allows this, though there are
currently no
built-in support functions to help you get there. As I mentioned, that
could all be done by code in a contributed package.
One way would be to have one help page which contains only
\Sexpr[stage=render, results=rd]{generatePage()}
and it will be 100% generated at render time, containing whatever you
want it to contain. (Presumably you'll have some way to communicate
what
you want through variables that generatePage() can see.) Each time you
link to it you'll see something different.
Duncan Murdoch
Brilliant. Thanks. That solves my question as well.
I did not see results = documented in ?Rd2HTML, what is allowed ?
Is \Sexpr ignored when rendering other formats (tex, ...) ?
or is there a way (similar to #ifdef) to only provide some content to
some renderers ?
As of yesterday, it's documented in Writing R Extensions. \Sexpr is
format-agnostic: it doesn't output HTML, it outputs plain text which is
wrapped in the appropriate HTML/LaTeX/whatever, or Rd input which is
processed by the whole system. So the generator would currently have to
use sneaky methods to figure out the format, looking at which function
called it, etc. I imagine in the long run we'll define some state
variables which the code can look at, but I'd rather see use-cases
before deciding what those should be.
Duncan Murdoch
Sure. One last thing, can the \Sexpr trigger some code that redirects to
some other page ? I suppose one could just call browseURL, but this
would bring another tab, ...
Do I need to depend on R = 2.10.0 if I use \Sexpr ?
Gabor, would you like to team up to generate some sort of incubator
package to take advantage of the new system ?
Romain
--
Romain Francois
Professional R Enthusiast
+33(0) 6 28 91 30 30
http://romainfrancois.blog.free.fr
|- http://tr.im/ztCu : RGG #158:161: examples of package IDPmisc
|- http://tr.im/yw8E : New R package : sos
`- http://tr.im/y8y0 : search the graph gallery from R
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On 24/09/2009 6:29 AM, Romain Francois wrote:
On 09/24/2009 12:04 PM, Duncan Murdoch wrote:
On 24/09/2009 5:42 AM, Romain Francois wrote:
On 09/24/2009 11:28 AM, Duncan Murdoch wrote:
On 23/09/2009 11:21 PM, Gabor Grothendieck wrote:
On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdoch
murd...@stats.uwo.ca wrote:
- Ways to link from man pages to vignettes. The reverse would be
nice, but
it's not possible with the current design, so that would be far off.
If feasible I would like to be able to link to any text, html or pdf
file in the package. For example, it would be nice to be able to link
to the NEWS file and pdf files that are included in the package even
if they are not vignettes, etc.
The \Sexpr mechanism probably allows this, though there are
currently no
built-in support functions to help you get there. As I mentioned, that
could all be done by code in a contributed package.
One way would be to have one help page which contains only
\Sexpr[stage=render, results=rd]{generatePage()}
and it will be 100% generated at render time, containing whatever you
want it to contain. (Presumably you'll have some way to communicate
what
you want through variables that generatePage() can see.) Each time you
link to it you'll see something different.
Duncan Murdoch
Brilliant. Thanks. That solves my question as well.
I did not see results = documented in ?Rd2HTML, what is allowed ?
Is \Sexpr ignored when rendering other formats (tex, ...) ?
or is there a way (similar to #ifdef) to only provide some content to
some renderers ?
As of yesterday, it's documented in Writing R Extensions. \Sexpr is
format-agnostic: it doesn't output HTML, it outputs plain text which is
wrapped in the appropriate HTML/LaTeX/whatever, or Rd input which is
processed by the whole system. So the generator would currently have to
use sneaky methods to figure out the format, looking at which function
called it, etc. I imagine in the long run we'll define some state
variables which the code can look at, but I'd rather see use-cases
before deciding what those should be.
Duncan Murdoch
Sure. One last thing, can the \Sexpr trigger some code that redirects to
some other page ? I suppose one could just call browseURL, but this
would bring another tab, ...
Do I need to depend on R = 2.10.0 if I use \Sexpr ?
I think so.
Duncan Murdoch
Gabor, would you like to team up to generate some sort of incubator
package to take advantage of the new system ?
Romain
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On 24/09/2009 7:30 AM, Duncan Murdoch wrote:
On 24/09/2009 6:29 AM, Romain Francois wrote:
On 09/24/2009 12:04 PM, Duncan Murdoch wrote:
On 24/09/2009 5:42 AM, Romain Francois wrote:
On 09/24/2009 11:28 AM, Duncan Murdoch wrote:
On 23/09/2009 11:21 PM, Gabor Grothendieck wrote:
On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdoch
murd...@stats.uwo.ca wrote:
- Ways to link from man pages to vignettes. The reverse would be
nice, but
it's not possible with the current design, so that would be far off.
If feasible I would like to be able to link to any text, html or pdf
file in the package. For example, it would be nice to be able to link
to the NEWS file and pdf files that are included in the package even
if they are not vignettes, etc.
The \Sexpr mechanism probably allows this, though there are
currently no
built-in support functions to help you get there. As I mentioned, that
could all be done by code in a contributed package.
One way would be to have one help page which contains only
\Sexpr[stage=render, results=rd]{generatePage()}
and it will be 100% generated at render time, containing whatever you
want it to contain. (Presumably you'll have some way to communicate
what
you want through variables that generatePage() can see.) Each time you
link to it you'll see something different.
Duncan Murdoch
Brilliant. Thanks. That solves my question as well.
I did not see results = documented in ?Rd2HTML, what is allowed ?
Is \Sexpr ignored when rendering other formats (tex, ...) ?
or is there a way (similar to #ifdef) to only provide some content to
some renderers ?
As of yesterday, it's documented in Writing R Extensions. \Sexpr is
format-agnostic: it doesn't output HTML, it outputs plain text which is
wrapped in the appropriate HTML/LaTeX/whatever, or Rd input which is
processed by the whole system. So the generator would currently have to
use sneaky methods to figure out the format, looking at which function
called it, etc. I imagine in the long run we'll define some state
variables which the code can look at, but I'd rather see use-cases
before deciding what those should be.
Duncan Murdoch
Sure. One last thing, can the \Sexpr trigger some code that redirects to
some other page ? I suppose one could just call browseURL, but this
would bring another tab, ...
Sorry, I missed this. The answer is no, not currently, but it could
generate a link for the user to manually navigate there.
Duncan Murdoch
Do I need to depend on R = 2.10.0 if I use \Sexpr ?
I think so.
Duncan Murdoch
Gabor, would you like to team up to generate some sort of incubator
package to take advantage of the new system ?
Romain
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On 23/09/2009 10:08 PM, Henrik Bengtsson wrote:
Hi,
in 'Writing R Extensions of R v2.10.0, under Section
'Cross-references' (2009-09-07) it says:
1. The markup \link{foo} (usually in the combination
\code{\link{foo}}) produces a hyperlink to the help for foo. Here foo
is a topic, that is the argument of \alias markup in another Rd file
(possibly in another package).
2. You can specify a link to a different topic than its name by
\link[=dest]{name} which links to topic dest with name name. This can
be used to refer to the documentation for S3/4 classes, for example
\code{\link[=abc-class]{abc}} would be a way to refer to the
documentation of an S4 class abc defined in your package, and
\code{\link[=terms.object]{terms}} to the S3 terms class (in
package stats). To make these easy to read, \code{\linkS4class{abc}}
expands to the form given above.
3. There are two other forms of optional argument specified as
\link[pkg]{foo} and \link[pkg:bar]{foo} to link to the package pkg, to
files foo.html and bar.html respectively. 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 topic20
(in which case the present package has precedence so this is only
needed to refer to other packages). They are only in used in HTML help
(and ignored for hyperlinks in LaTeX conversions of help pages), and
link to the file rather than the topic (since there is no way to know
which topics are in which files in an uninstalled package). The *only*
reason to use these forms for base and recommended packages is to
force a reference to a package that might be further down the search
path. Because they have been frequently misused, as from R 2.10.0 the
HTML help system will look for topic foo in package pkg if it does not
find file foo.html.
Trying to summarize the above, do we have the following markups/rules?
A. \link{topic} - where topic must occur as an \alias{topic},
but not necessarily as an \name{topic}. The link will be display as
the string topic.
B. \link[=topic]{name} - where topic must occur as an
\alias{topic} with a \name{name}. The link will be display as the
string name.
C. \link{packageName]{name} - where name must be a \name{name}
in a package named packageName. The link will be display as the
string name.
D. \link{packageName:name]{label} - where name must be a
\name{name} in a package named packageName. The link will be
display as the string label. There are no restrictions on label.
E. \linkS4class{className} expands to
\link[=className-class]{className}. From (B) it then follows that
there must be an \alias{className-class} and a \name{className}.
Q1. Is that correct? To me it look a bit inconsistent.
No, \name{} is irrelevant for links. It's the filename that matters in
the 3rd form.
Q2. Are there more?
Q3. Will there be more?
Q4. What about
\link[=topic]{label}
\link{packageName:topic]{label}
where label can be (almost) any string?
The first is what the 2nd form refers to. Name there is what is
displayed in the file making the link.
The second is new, as of 2.10.0, and is the fallback if a filename
matching topic is not found.
Q4. Are (A) and (B) only supposed to be used for linking within a
package, or can it be used to link to wherever topic exist?
They should work anywhere. The difficulty arises if you link to
something that a user doesn't have installed, or if the link is ambiguous.
Q5. It sounds that (C) and (D) should be avoided. Is that correct?
I think good practice is to make sure that the base of the filename
(less .Rd) is also an alias in the file, and also the \name{} of the
file. The system would probably be less confusing if this were forced,
but there are lots of files out there where it's not true.
You want the filename to be an alias because links sometimes go to
aliases and sometimes to filenames; you want the name to match because
that's what is displayed at the top of the page, so people might
remember just go to the Foo man page.
Q6. What if topic exist in two packages 'pkgA' and 'pkgB' and I want
to specify that I mean topic topic of package 'pkgA', cf namespaces
and pkgA::foo()?
If you follow the good practice above, then use \link[pkgA]{topic}. If
you don't follow that practice, you may be out of luck, because R will
look for the filename topic.Rd in pkgA, not \alias{topic}. However, as
of 2.10.0, it will fall back to the latter.
Q7. I the 1st paragraph above it says (possibly in another package)
and in the 3rd paragraph above it is mentioned at The only reason to
use these forms [...] is to force a reference to a package that might
be further down the search path - is that the answer to Q4? Will
\link{topic} be *dynamically* linked to whatever comes first on the
search() path - to reflect the running environment rather than the
intention of the document?
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
On Wed, Sep 23, 2009 at 10:54 PM, Duncan Murdoch murd...@stats.uwo.ca wrote: - Ways to link from man pages to vignettes. The reverse would be nice, but it's not possible with the current design, so that would be far off. If feasible I would like to be able to link to any text, html or pdf file in the package. For example, it would be nice to be able to link to the NEWS file and pdf files that are included in the package even if they are not vignettes, etc. __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
You want the filename to be an alias because links sometimes go to aliases and sometimes to filenames; you want the name to match because that's what is displayed at the top of the page, so people might remember just go to the Foo man page. It would be really good to emphasise this somewhere. I didn't that this was best practice. It would be nice to have a base R function that converts a function name to a filename - then there would be a convention for how to do so, and perhaps some of the filename - function name mismatches would be resolved. A heuristic along the following lines might work: - replace . with - - modify the following special strings: * +,-,/,* to add, subtract, divide, multiply * [ to subset, [[ to subset2 * $ to dollar * $- dollar-assign * [- subset-assign, [[ subset2-assign Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
