mailing-list for TeXmacs Users

[Michael Lachmann <address@hidden>]

Hi,

I continue to work on the R plugin, and added the ability to display  
help files within TeXmacs. The function that does that is called t.help:
t.help("read.table") will display the documentation about read.table  
inside TeXmacs. This works really well - html rendering in TeXmacs is  
very nice.

I encountered the following problem: some files fail to open, with the  
following error:
/usr/local/share/TeXmacs/progs/convert/tools/xmltm.scm:150:7: In  
procedure string-replace in expression (string-replace s cork- 
grave ...):
/usr/local/share/TeXmacs/progs/convert/tools/xmltm.scm:150:7: string  
contains #\nul character: "?\x00+\x00"

I attached a sample file that fails (it is the documentation of the R  
function "help"...)

The problem seems to be with a line that is part of the examples:
?`+`

A second problem I encountered repeatedly, but can't reproduce  
reliably is that sometimes, when I open an html help files, and then  
follow links in that help file, and then go back with C-<, then in  
some case if I press C-< when the top html file is display (i.e. the  
first opened), then TeXmacs crashes with the following error:

Assertion failed: (!is_nil (p)), function path_up, file ./Kernel/Types/ 
path.cpp, line 84.
'/usr/local/bin/texmacs ' terminated by signal SIGABRT (Abort)

Michael

Title: R: Documentation

help {utils}

R Documentation

Documentation

Description

These functions provide access to documentation. Documentation on a topic with name name (typically, an R object or a data set) can be displayed with either help("name") or ?name.

Usage

help(topic, offline = FALSE, package = NULL,
     lib.loc = NULL, verbose = getOption("verbose"),
     try.all.packages = getOption("help.try.all.packages"),
     chmhelp = getOption("chmhelp"),
     htmlhelp = getOption("htmlhelp"),
     pager = getOption("pager"))

?topic

type?topic

Arguments

topic	usually, a name or character string specifying the topic for which help is sought. A character string (enclosed in explicit single or double quotes) is always taken as naming a topic. For help, if the value of topic is a length-one character vector the topic is taken to be the value of the only element. Otherwise topic must be a name or a reserved word (if syntactically valid) or character string. For ? the topic argument may also be a function call, to ask for documentation on a corresponding method: see the section on S4 method documentation. Unlike help, all names are deparsed to give the desired topic. The forms pkg::topic and pkg:::topic are treated specially, and look for help on topic in package package. See ‘Details’ for what happens if this is omitted for help.
offline	a logical indicating whether documentation should be displayed on-line to the screen (the default) or hardcopy of it should be produced.
package	a name or character vector giving the packages to look into for documentation, or NULL. By default, all packages in the search path are used.
lib.loc	a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries.
verbose	logical; if TRUE, the file name is reported.
try.all.packages	logical; see Note.
chmhelp	logical (or NULL). Only relevant under Windows. If TRUE the Compiled HTML version of the help on the topic will be shown in a help viewer. If none is available, plain text help will be shown.
htmlhelp	logical (or NULL). If TRUE (which is the default after help.start has been called), the HTML version (if available) of the help on the topic will be shown in the browser specified by options("browser"). See browseURL for details of the browsers that are supported. Where possible an existing browser window is re-used.
pager	the pager to be used for file.show.
type	the special type of documentation to use for this topic; for example, if the type is class, documentation is provided for the class with name topic. The function topicName returns the actual name used in this case. See the section on method documentation for the uses of type to get help on formal methods.

Details

topic is not optional: if it is omitted R will give a hint as to suitable topics if a package is specified, to available packages if lib.loc only is specified, and help on help itself if nothing is specified. (In all cases this will be text help.)

Some topics need to be quoted (by backticks) or given as a character string. There include those which cannot syntactically appear on their own such as unary and binary operators, function and control-flow reserved words (including if, else for, in, repeat, while, break and next. The other reserved words can be used as if they were names, for example TRUE, NA and Inf.

If multiple help files matching topic are found, in interactive use a menu is presented for the user to choose one: otherwise the first on the search path is used. (The menu will be a graphical menu if possible if getOption("menu.graphics") is true, the default.)

HTML help works best if help.start() has been called in the session. Otherwise there will be a warning about ‘Using non-linked HTML file: hyperlinks may be incorrect’ and cross-library links will most likely not be resolved.

If offline is TRUE, hardcopy of the documentation is produced by running the LaTeX version of the help page through latex and dvips. Depending on your dvips configuration, hardcopy will be sent to the printer or saved in a file. If the programs are in non-standard locations and hence were not found at compile time, you can either set the options latexcmd and dvipscmd, or the environment variables R_LATEXCMD and R_DVIPSCMD appropriately. The appearance of the output can be customized through a file ‘Rhelp.cfg’ somewhere in your LaTeX search path: this will be input as a LaTeX style file after Rd.sty. Some environment variables are consulted, notably R_PAPERSIZE (via getOption("papersize")) and R_RD4DVI

If LaTeX versions of help pages were not built at the installation of the package, the print method will ask if conversion with R CMD Rdconv (which requires Perl) should be attempted.

S4 Method Documentation

The authors of formal (‘S4’) methods can provide documentation on specific methods, as well as overall documentation on the methods of a particular function. The "?" operator allows access to this documentation in three ways.

The _expression_ methods ? f will look for the overall documentation methods for the function f. Currently, this means the documentation file containing the alias f-methods.

There are two different ways to look for documentation on a particular method. The first is to supply the topic argument in the form of a function call, omitting the type argument. The effect is to look for documentation on the method that would be used if this function call were actually evaluated. See the examples below. If the function is not a generic (no S4 methods are defined for it), the help reverts to documentation on the function name.

The "?" operator can also be called with type supplied as "method"; in this case also, the topic argument is a function call, but the arguments are now interpreted as specifying the class of the argument, not the actual _expression_ that will appear in a real call to the function. See the examples below.

The first approach will be tedious if the actual call involves complicated expressions, and may be slow if the arguments take a long time to evaluate. The second approach avoids these difficulties, but you do have to know what the classes of the actual arguments will be when they are evaluated.

Both approaches make use of any inherited methods; the signature of the method to be looked up is found by using selectMethod (see the documentation for getMethod).

Note

Unless lib.loc is specified explicitly, the loaded packages are searched before those in the specified libraries. This ensures that if a library is loaded from a library not in the known library trees, then the help from the loaded library is used. If lib.loc is specified explicitly, the loaded packages are not searched.

If this search fails and argument try.all.packages is TRUE and neither packages nor lib.loc is specified, then all the packages in the known library trees are searched for help on topic and a list of (any) packages where help may be found is printed (but no help is shown). N.B. searching all packages can be slow.

The help files can be many small files. On some file systems it is desirable to save space, and the text files in the ‘help’ directory of an installed package can be zipped up as a zip archive ‘Rhelp.zip’. Ensure that file ‘AnIndex’ remains un-zipped. Similarly, all the files in the ‘latex’ directory can be zipped to ‘Rhelp.zip’.

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

See Also

help.search() or ?? for finding help pages on a vague topic; help.start() which opens the HTML version of the R help pages; library() for listing available packages and the user-level objects they contain; data() for listing available data sets; methods().

See prompt() to get a prototype for writing help pages of private packages.

Examples

help()
help(help)              # the same

help(lapply)
?lapply                 # the same

help("for")             # or ?"for", but quotes/backticks are needed
?`+`

help(package="splines") # get help even when package is not loaded

data()                  # list all available data sets
?women                  # information about data set "women"

topi <- "women"
help(topi)

try(help("bs", try.all.packages=FALSE)) # reports not found (an error)
help("bs", try.all.packages=TRUE)       # reports can be found
                                        # in package 'splines'

## Not run: 
require(methods)
## define a S4 generic function and some methods
combo <- function(x, y) c(x, y)
setGeneric("combo")
setMethod("combo", c("numeric", "numeric"), function(x, y) x+y)

## assume we have written some documentation
## for combo, and its methods ....

?combo  ## produces the function documentation

methods?combo  ## looks for the overall methods documentation

method?combo("numeric", "numeric")  ## documentation for the method above

?combo(1:10, rnorm(10))  ## ... the same method, selected according to
                         ## the arguments (one integer, the other numeric)

?combo(1:10, letters)    ## documentation for the default method
## End(Not run)

---

[Package utils version 2.9.1 Index]