Henrik Bengtsson
2009-Sep-24 02:08 UTC
[Rd] R v2.10.0: Doc clarification for cross references and where are we heading?
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. 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? 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? Q5. It sounds that (C) and (D) should be avoided. Is that correct? 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()? 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? Reading between the lines, the development of Rd looks exiting. Instead of 2nd guessing where we are heading, could someone in charge please give some thoughts on what the plans are and an estimate on how long it will take before we are there - what R version? MISC: I understand that \link[=<className>-class]{<className>} is part of standard Rd conventions, but to the best of my knowledge \link[=<className>.class]{<className>} is not, correct? I would like to suggest to write a separate paragraph for S4 classes without mentioning S3 classes. The following also adds to the confusion - there exists one Rd page with \name{terms} and one with \name{terms.object}, so it is not really clear what \link[=terms.object]{terms} is strictly supposed to do - is it of form \link[=<topic>]{<name>} or \link[=<topic>]{<label>}. Maybe it is helpful to clarify what the static/dynamic link will be and what will be display. Thanks Henrik PS. This is related to today's (Sept 23, 2009) BioConductor posts by Gordon Smyth - "[Bioc-devel] BioC 2.5: "suspect" interpackage links"; https://stat.ethz.ch/pipermail/bioc-devel/2009-September/001975.html
Duncan Murdoch
2009-Sep-24 02:54 UTC
[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?In 2.10.0, I believe this will be the case (but I'd have to check the code to be sure). I'd recommend being explicit if you are worried about this possibility.> Reading between the lines, the development of Rd looks exiting. > Instead of 2nd guessing where we are heading, could someone in charge > please give some thoughts on what the plans are and an estimate on how > long it will take before we are there - what R version?I don't think there's really someone "in charge", but I've been closely involved with this, so I'll give some thoughts. Generally speaking, we have releases on a regular schedule, we don't hold them up for particular features. So I don't think it would be possible to figure out when development on Rd files will be done. It depends on when people have the time to do what they think needs doing, and to a large extent, that depends on how things get used. Some things that are not there now, but which might be there in the future (i.e. later than 2.10.0): - Better support for the \Sexpr macros (which let the content of man pages depend on R code, executed just before rendering). Right now there's no special support for that R code; it would make sense to define some functions to make writing such stuff easier. (This is something that could be done in a contributed package, it needn't be in base R.) - Improved prompt() and package.skeleton() functions to take advantage of the above. - Graphs in man pages. - 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. - Some general rationalization of the whole help system. Duncan Murdoch> > MISC: > I understand that \link[=<className>-class]{<className>} is part of > standard Rd conventions, but to the best of my knowledge > \link[=<className>.class]{<className>} is not, correct? I would like > to suggest to write a separate paragraph for S4 classes without > mentioning S3 classes. The following also adds to the confusion - > there exists one Rd page with \name{terms} and one with > \name{terms.object}, so it is not really clear what > \link[=terms.object]{terms} is strictly supposed to do - is it of form > \link[=<topic>]{<name>} or \link[=<topic>]{<label>}. Maybe it is > helpful to clarify what the static/dynamic link will be and what will > be display. > > Thanks > > Henrik > > PS. This is related to today's (Sept 23, 2009) BioConductor posts by > Gordon Smyth - "[Bioc-devel] BioC 2.5: "suspect" interpackage links"; > https://stat.ethz.ch/pipermail/bioc-devel/2009-September/001975.html > > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel
Reasonably Related Threads
- S4 class help pages [Sec=Unclassified]
- How to see the implementation of print function for a class from a package?
- Namespace/inheritance problem in S4 methods for a union class
- S4 generic not exported correctly / incorrect dispatch?
- "False" warning on "replacing previous import" when re-exporting identical object