reprompt: Update the documentation of a topic
In GeoBosh/Rdpack: Update and Manipulate Rd Documentation Objects
reprompt R Documentation
Update the documentation of a topic
Description
Examine the documentation of functions, methods or classes and
update it with additional arguments, aliases, methods or slots, as
appropriate. This is an extention of the promptXXX() family of functions.
Usage
reprompt(object, infile = NULL, Rdtext = NULL, final = TRUE,
type = NULL, package = NULL, methods = NULL, verbose = TRUE,
filename = NULL, sec_copy = TRUE, edit = FALSE, ...)
Arguments
object
the object whose documentation is to be updated, such as
a string, a function, a help topic, a parsed Rd object, see
‘Details’.
infile
a file name containing Rd documentation, see ‘Details’.
Rdtext
a character string with Rd formatted text, see ‘Details’.
final
logical, if TRUE modifies the output of
prompt so that the package can be built.
type
type of topic, such as "methods" or
"class", see ‘Details’.
package
package name; document only objects defined in this
package, especially useful for methods, see ‘Details’.
methods
used for documentation of S4 methods only, rarely needed even for
them. This argument is passed on to
promptMethods, see its documentation for
details.
verbose
if TRUE print messages on the screen.
filename
name of the file for the generated Rd content; if
NULL, a suitable file name is generated, if TRUE it
will be set to infile,
if FALSE the Rd text is returned, see ‘Details’.
...
currently not used.
sec_copy
if TRUE copy Rd contents of unchanged sections
in the result, see Details.
edit
if TRUE call file.edit just before
returning. This argument is ignored if filename is FALSE.
Details
The typical use of reprompt is with one argument, as in
reprompt(infile = "./Rdpack/man/reprompt.Rd")
reprompt(reprompt)
reprompt("reprompt")
reprompt updates the requested documentation and writes the new
Rd file in the current working directory. When argument infile
is used, the descriptions of all objects described in the input file
are updated. When an object or its name is given, reprompt
looks first for installed documentation and processes it in the same
way as in the case of infile. If there is no documentation for
the object, reprompt creates a skeleton Rd file similar to the
one produced by the base R functions from the prompt family (if
final = TRUE, the default, it modifies the output of
prompt(), so that the package can be built).
To document a function, say myfun, in an existing Rd file, just
add myfun() to the usage section in the file and call
reprompt() on that file. Put quotes around the function name if
it is non-syntactic. For replacement functions (functions with names
ending in <-) reprompt() will insert the proper usage
statement. For example, if the signature of xxx<- is (x,
..., value) then both, "xxx<-"() and xxx() <- value
will be replaced by xxx(x, ...) <- value.
For S4 methods and classes the argument "package" is often needed to
restrict the output to methods defined in the package of interest.
reprompt("myfun-methods")
reprompt("[<--methods", package = "mypackage")
reprompt("[<-", type = "methods", package = "mypackage") # same
reprompt("myclass", type = "class", package = "mypackage")
reprompt("myclass-class", package = "mypackage") # same
Without the "package" argument the reprompt for "[<-" would give
all methods defined by loaded packages at the time of the call.
Currently reprompt functionality is not implemented for topic
"package" but if object has the form "name-package" (or the
equivalent with argument topic) and there is no documentation
for package?name, reprompt calls
promptPackageSexpr to create the required shell.
Note that the shell produced by promptPackageSexpr does not
need ‘reprompting’ since the automatically generated information is
included by \Sexpr's, not literal strings.
Below are the details.
Typically, only one of object, infile, and Rdtext
is supplied. Warning messages are issued if this is not the case.
The object must have been made available by the time when
reprompt() is issued. If the object is in a package this is
typically achieved by a library() command.
object may be a function or a name, as accepted by the ?
operator. If it has the form "name-class" and "name-methods" a
documentation shell for class "name" or the methods for generic function
"name" will be examined/created. Alternatively, argument type
may be set to "class" or "methods" to achieve the same effect.
infile specifies a documentation file to be updated. If it
contains the documentation for one or more functions, reprompt
examines their usage statements and updates them if they have
changed. It also adds arguments to the "arguments" section if not all
arguments in the usage statements have entries there. If infile
describes the methods of a function or a class, the checks made are as
appropriate for them. For example, new methods and/or slots are added
to the corresponding sections.
It is all too easy in interactive use to forget to name the
infile argument, compare
reprompt("./man/reprompt.Rd") vs.
reprompt(infile = "./man/reprompt.Rd")).
A convenience feature is that if infile is missing
and object is a character string ending in ".Rd" and containing
a forward slash (i.e. it looks like Rd file in a directory), then it
is taken to be infile.
Rdtext is similar to infile but the Rd content is taken
from a character vector.
If Rd content is supplied by infile or Rdtext,
reprompt uses it as a basis for comparison. Otherwise it tries
to find installed documentation for the object or topic requested.
If that fails, it resorts to one of the promptXXX functions to
generate a documentation shell. If that also fails, the requested
object or topic does not exist.
If the above succeeds, the function examines the current definition of
the requested object(s), methods, or class and amends the
documentation with any additional items it finds.
For Rd objects describing one or more functions, the usage expressions
are checked and replaced, if they have changed. Arguments appearing in
one or more usage expressions and missing from section "Arguments" are
amended to it with content "Describe ..." and a message is
printed. Arguments no longer in the usage statements are NOT removed
but a message is issued to alert the user. Alias sections are inserted
for any functions with "usage" but without "alias" section.
If filename is a character string, it is used as is, so any
path should be included in the string. Argument filename
usuallly is omitted since the automatically generated file name is
suitable in most cases. Exceptions are functions with non-standard
names (such as replacement functions whose names end in "<-")
for which the generated file names may not be acceptable on some
operating systems.
If filename is missing or NULL, a suitable name is
generated as follows. If infile is supplied, filename is
set to a file with the same name in the current working directory
(i.e. any path information in infile is dropped). Otherwise,
filename is obtained by appending the name tag of the Rd object
with ".Rd".
If filename is TRUE, it is set to infile or, if
infile is missing or NULL, a suitable name is generated
as above. This can be used to change infile in place.
If filename is FALSE, the Rd text is returned as a
character vector and not written to a file.
If edit is TRUE, the reprompted file is opened in an
editor, see also ereprompt (‘e’ for ‘edit’) which is
like reprompt but has as default edit = TRUE and some
other related settings.
file.edit() is used to call the editor. Which editor is opened
depends on the OS and on the user configuration. RStudio users will
probably prefer the 'Reprompt' add-in or the underlying function
RStudio_reprompt. Emacs users would normally have set
up emacsclient as their editor and this is automatically done
by EMACS/ESS (even on Windows).
If argument sec_copy is TRUE (the default),
reprompt will, effectively, copy the contents of (some)
unchanged sections, thus ensuring that they are exactly the same as in
the original. This needs additional work, since parsing an Rd file
and then exporting the created Rd object to an Rd file does not
necessarilly produce an identical Rd file (some escape sequences may
be changed in the process, for example). Even though the new version
should be functionally equivalent to the original, such changes are
usually not desirable. For example, if such changes creep into the
Details section (which reprompt never changes) the user may be
annoyed or worried.
Value
if filename is a character string or NULL, the name of
the file to which the updated shell was written.
Otherwise, the Rd text is returned as a character vector.
Note
The arguments of reprompt are similar to prompt, with some
additions. As in prompt, filename specifies the output
file. In reprompt a new argument, infile, specifies the
input file containing the Rd source.
When reprompt is used to update sources of Rd documentation for
a package, it is best to supply the original Rd file in argument
infile. Otherwise, if the original Rd file contains
\Sexpr commands, reprompt may not be able to recover the
original Rd content from the installed documentation. Also, the fields
(e.g. the keywords) in the installed documentation may not be were you
expect them to be. (This may be addressed in a future revision.)
While reprompt adds new items to the documentation, it never
removes existing content. It only issues a suggestion to remove an
item, if it does not seem necessary any more (e.g. a removed argument
from a function definition).
reprompt handles usage statements for S3 and S4 methods
introduced with any of the macros \method, \S3method and
\S4method, as in
\method{fun}{class}(args...). reprompt understands also
subsetting ans subassignment operators. For example, suppose that the
\arguments section of file "bracket.Rd" contains these
directives (or any other wrong signatures):
\method{[}{ts}()
\method{[[}{Date}()
Then reprompt("./bracket.Rd") will change them to
\method{[}{ts}(x, i, j, drop = TRUE)
\method{[[}{Date}(x, \dots, drop = TRUE)
This works for the assignment operators and functions, as well. For
example, any of these
\method{`[<-`}{POSIXlt}()
\method{[}{POSIXlt}(x, j) <- value
will be converted by reprompt to the standard form
\method{[}{POSIXlt}(x, i, j) <- value
Note that the quotes in `[<-` above.
Usage statements for functions are split over two or more lines if
necessary. The user may edit them afterwards if the automatic
splitting is not appropriate, see below.
The usage section of Rd objects describing functions is left intact if
the usage has not changed. To force reprompt to recreate the
usage section (e.g. to reformat long lines), invalidate the usage of
one of the described functions by removing an argument from its usage
expression. Currently the usage section is recreated completely if
the usage of any of the described functions has changed. Manual
formatting may be lost in such cases.
Author(s)
Georgi N. Boshnakov
See Also
ereprompt which by default calls the editor on the
original file
Examples
## note: usage of reprompt() is simple. the examples below are bulky
## because they simulate various usage scenarios with commands,
## while in normal usage they would be due to editing.
## change to a temporary directory to avoid clogging up user's
cur_wd <- getwd()
tmpdir <- tempdir()
setwd(tmpdir)
## as for prompt() the default is to save in current dir as "seq.Rd".
## the argument here is a function, reprompt finds its doc and
## updates all objects described along with `seq'.
## (In this case there is nothing to update, we have not changed `seq'.)
fnseq <- reprompt(seq)
## let's parse the saved Rd file (the filename is returned by reprompt)
rdoseq <- tools::parse_Rd(fnseq) # parse fnseq to see the result.
Rdo_show(rdoseq)
## we replace usage statements with wrong ones for illustration.
## (note there is an S3 method along with the functions)
dummy_usage <- char2Rdpiece(paste("seq()", "\\method{seq}{default}()",
"seq.int()", "seq_along()", "seq_len()", sep="\n"),
"usage")
rdoseq_dummy <- Rdo_replace_section(rdoseq, dummy_usage)
Rdo_show(rdoseq_dummy) # usage statements are wrong
reprompt(rdoseq_dummy, file = "seqA.Rd")
Rdo_show(tools::parse_Rd("seqA.Rd")) # usage ok after reprompt
## define function myseq()
myseq <- function(from, to, x){
if(to < 0) {
seq(from = from, to = length(x) + to)
} else seq(from, to)
}
## we wish to describe myseq() along with seq();
## it is sufficient to put myseq() in the usage section
## and let reprompt() do the rest
rdo2 <- Rdo_modify_simple(rdoseq, "myseq()", "usage")
reprompt(rdo2, file = "seqB.Rd") # updates usage of myseq
## show the rendered result:
Rdo_show(tools::parse_Rd("seqB.Rd"))
## Run this if you wish to see the Rd file:
## file.show("seqB.Rd")
reprompt(infile = "seq.Rd", filename = "seq2.Rd")
reprompt(infile = "seq2.Rd", filename = "seq3.Rd")
## Rd objects for installed help may need some tidying for human editing.
#hseq_inst <- help("seq")
#rdo <- utils:::.getHelpFile(hseq_inst)
rdo <- Rdo_fetch("seq", "base")
rdo
rdo <- Rdpack:::.Rd_tidy(rdo) # tidy up (e.g. insert new lines
# for human readers)
reprompt(rdo) # rdo and rdoseq are equivalent
all.equal(reprompt(rdo), reprompt(rdoseq)) # TRUE
## clean up
unlink("seq.Rd") # remove temporary files
unlink("seq2.Rd")
unlink("seq3.Rd")
unlink("seqA.Rd")
unlink("seqB.Rd")
setwd(cur_wd) # restore user's working directory
unlink(tmpdir)
GeoBosh/Rdpack documentation built on Nov. 11, 2023, 5:22 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| reprompt | R Documentation |
Update the documentation of a topic
Description
Examine the documentation of functions, methods or classes and update it with additional arguments, aliases, methods or slots, as appropriate. This is an extention of the promptXXX() family of functions.
Usage
reprompt(object, infile = NULL, Rdtext = NULL, final = TRUE,
type = NULL, package = NULL, methods = NULL, verbose = TRUE,
filename = NULL, sec_copy = TRUE, edit = FALSE, ...)
Arguments
object |
the object whose documentation is to be updated, such as a string, a function, a help topic, a parsed Rd object, see ‘Details’. |
infile |
a file name containing Rd documentation, see ‘Details’. |
Rdtext |
a character string with Rd formatted text, see ‘Details’. |
final |
logical, if |
type |
type of topic, such as |
package |
package name; document only objects defined in this package, especially useful for methods, see ‘Details’. |
methods |
used for documentation of S4 methods only, rarely needed even for
them. This argument is passed on to
|
verbose |
if |
filename |
name of the file for the generated Rd content; if
|
... |
currently not used. |
sec_copy |
if |
edit |
if |
Details
The typical use of reprompt is with one argument, as in
reprompt(infile = "./Rdpack/man/reprompt.Rd")
reprompt(reprompt)
reprompt("reprompt")
reprompt updates the requested documentation and writes the new
Rd file in the current working directory. When argument infile
is used, the descriptions of all objects described in the input file
are updated. When an object or its name is given, reprompt
looks first for installed documentation and processes it in the same
way as in the case of infile. If there is no documentation for
the object, reprompt creates a skeleton Rd file similar to the
one produced by the base R functions from the prompt family (if
final = TRUE, the default, it modifies the output of
prompt(), so that the package can be built).
To document a function, say myfun, in an existing Rd file, just
add myfun() to the usage section in the file and call
reprompt() on that file. Put quotes around the function name if
it is non-syntactic. For replacement functions (functions with names
ending in <-) reprompt() will insert the proper usage
statement. For example, if the signature of xxx<- is (x,
..., value) then both, "xxx<-"() and xxx() <- value
will be replaced by xxx(x, ...) <- value.
For S4 methods and classes the argument "package" is often needed to restrict the output to methods defined in the package of interest.
reprompt("myfun-methods")
reprompt("[<--methods", package = "mypackage")
reprompt("[<-", type = "methods", package = "mypackage") # same
reprompt("myclass", type = "class", package = "mypackage")
reprompt("myclass-class", package = "mypackage") # same
Without the "package" argument the reprompt for "[<-" would give
all methods defined by loaded packages at the time of the call.
Currently reprompt functionality is not implemented for topic
"package" but if object has the form "name-package" (or the
equivalent with argument topic) and there is no documentation
for package?name, reprompt calls
promptPackageSexpr to create the required shell.
Note that the shell produced by promptPackageSexpr does not
need ‘reprompting’ since the automatically generated information is
included by \Sexpr's, not literal strings.
Below are the details.
Typically, only one of object, infile, and Rdtext
is supplied. Warning messages are issued if this is not the case.
The object must have been made available by the time when
reprompt() is issued. If the object is in a package this is
typically achieved by a library() command.
object may be a function or a name, as accepted by the ?
operator. If it has the form "name-class" and "name-methods" a
documentation shell for class "name" or the methods for generic function
"name" will be examined/created. Alternatively, argument type
may be set to "class" or "methods" to achieve the same effect.
infile specifies a documentation file to be updated. If it
contains the documentation for one or more functions, reprompt
examines their usage statements and updates them if they have
changed. It also adds arguments to the "arguments" section if not all
arguments in the usage statements have entries there. If infile
describes the methods of a function or a class, the checks made are as
appropriate for them. For example, new methods and/or slots are added
to the corresponding sections.
It is all too easy in interactive use to forget to name the
infile argument, compare
reprompt("./man/reprompt.Rd") vs.
reprompt(infile = "./man/reprompt.Rd")).
A convenience feature is that if infile is missing
and object is a character string ending in ".Rd" and containing
a forward slash (i.e. it looks like Rd file in a directory), then it
is taken to be infile.
Rdtext is similar to infile but the Rd content is taken
from a character vector.
If Rd content is supplied by infile or Rdtext,
reprompt uses it as a basis for comparison. Otherwise it tries
to find installed documentation for the object or topic requested.
If that fails, it resorts to one of the promptXXX functions to
generate a documentation shell. If that also fails, the requested
object or topic does not exist.
If the above succeeds, the function examines the current definition of the requested object(s), methods, or class and amends the documentation with any additional items it finds.
For Rd objects describing one or more functions, the usage expressions are checked and replaced, if they have changed. Arguments appearing in one or more usage expressions and missing from section "Arguments" are amended to it with content "Describe ..." and a message is printed. Arguments no longer in the usage statements are NOT removed but a message is issued to alert the user. Alias sections are inserted for any functions with "usage" but without "alias" section.
If filename is a character string, it is used as is, so any
path should be included in the string. Argument filename
usuallly is omitted since the automatically generated file name is
suitable in most cases. Exceptions are functions with non-standard
names (such as replacement functions whose names end in "<-")
for which the generated file names may not be acceptable on some
operating systems.
If filename is missing or NULL, a suitable name is
generated as follows. If infile is supplied, filename is
set to a file with the same name in the current working directory
(i.e. any path information in infile is dropped). Otherwise,
filename is obtained by appending the name tag of the Rd object
with ".Rd".
If filename is TRUE, it is set to infile or, if
infile is missing or NULL, a suitable name is generated
as above. This can be used to change infile in place.
If filename is FALSE, the Rd text is returned as a
character vector and not written to a file.
If edit is TRUE, the reprompted file is opened in an
editor, see also ereprompt (‘e’ for ‘edit’) which is
like reprompt but has as default edit = TRUE and some
other related settings.
file.edit() is used to call the editor. Which editor is opened
depends on the OS and on the user configuration. RStudio users will
probably prefer the 'Reprompt' add-in or the underlying function
RStudio_reprompt. Emacs users would normally have set
up emacsclient as their editor and this is automatically done
by EMACS/ESS (even on Windows).
If argument sec_copy is TRUE (the default),
reprompt will, effectively, copy the contents of (some)
unchanged sections, thus ensuring that they are exactly the same as in
the original. This needs additional work, since parsing an Rd file
and then exporting the created Rd object to an Rd file does not
necessarilly produce an identical Rd file (some escape sequences may
be changed in the process, for example). Even though the new version
should be functionally equivalent to the original, such changes are
usually not desirable. For example, if such changes creep into the
Details section (which reprompt never changes) the user may be
annoyed or worried.
Value
if filename is a character string or NULL, the name of
the file to which the updated shell was written.
Otherwise, the Rd text is returned as a character vector.
Note
The arguments of reprompt are similar to prompt, with some
additions. As in prompt, filename specifies the output
file. In reprompt a new argument, infile, specifies the
input file containing the Rd source.
When reprompt is used to update sources of Rd documentation for
a package, it is best to supply the original Rd file in argument
infile. Otherwise, if the original Rd file contains
\Sexpr commands, reprompt may not be able to recover the
original Rd content from the installed documentation. Also, the fields
(e.g. the keywords) in the installed documentation may not be were you
expect them to be. (This may be addressed in a future revision.)
While reprompt adds new items to the documentation, it never
removes existing content. It only issues a suggestion to remove an
item, if it does not seem necessary any more (e.g. a removed argument
from a function definition).
reprompt handles usage statements for S3 and S4 methods
introduced with any of the macros \method, \S3method and
\S4method, as in
\method{fun}{class}(args...). reprompt understands also
subsetting ans subassignment operators. For example, suppose that the
\arguments section of file "bracket.Rd" contains these
directives (or any other wrong signatures):
\method{[}{ts}()
\method{[[}{Date}()
Then reprompt("./bracket.Rd") will change them to
\method{[}{ts}(x, i, j, drop = TRUE)
\method{[[}{Date}(x, \dots, drop = TRUE)
This works for the assignment operators and functions, as well. For example, any of these
\method{`[<-`}{POSIXlt}()
\method{[}{POSIXlt}(x, j) <- value
will be converted by reprompt to the standard form
\method{[}{POSIXlt}(x, i, j) <- value
Note that the quotes in `[<-` above.
Usage statements for functions are split over two or more lines if necessary. The user may edit them afterwards if the automatic splitting is not appropriate, see below.
The usage section of Rd objects describing functions is left intact if
the usage has not changed. To force reprompt to recreate the
usage section (e.g. to reformat long lines), invalidate the usage of
one of the described functions by removing an argument from its usage
expression. Currently the usage section is recreated completely if
the usage of any of the described functions has changed. Manual
formatting may be lost in such cases.
Author(s)
Georgi N. Boshnakov
See Also
ereprompt which by default calls the editor on the
original file
Examples
## note: usage of reprompt() is simple. the examples below are bulky
## because they simulate various usage scenarios with commands,
## while in normal usage they would be due to editing.
## change to a temporary directory to avoid clogging up user's
cur_wd <- getwd()
tmpdir <- tempdir()
setwd(tmpdir)
## as for prompt() the default is to save in current dir as "seq.Rd".
## the argument here is a function, reprompt finds its doc and
## updates all objects described along with `seq'.
## (In this case there is nothing to update, we have not changed `seq'.)
fnseq <- reprompt(seq)
## let's parse the saved Rd file (the filename is returned by reprompt)
rdoseq <- tools::parse_Rd(fnseq) # parse fnseq to see the result.
Rdo_show(rdoseq)
## we replace usage statements with wrong ones for illustration.
## (note there is an S3 method along with the functions)
dummy_usage <- char2Rdpiece(paste("seq()", "\\method{seq}{default}()",
"seq.int()", "seq_along()", "seq_len()", sep="\n"),
"usage")
rdoseq_dummy <- Rdo_replace_section(rdoseq, dummy_usage)
Rdo_show(rdoseq_dummy) # usage statements are wrong
reprompt(rdoseq_dummy, file = "seqA.Rd")
Rdo_show(tools::parse_Rd("seqA.Rd")) # usage ok after reprompt
## define function myseq()
myseq <- function(from, to, x){
if(to < 0) {
seq(from = from, to = length(x) + to)
} else seq(from, to)
}
## we wish to describe myseq() along with seq();
## it is sufficient to put myseq() in the usage section
## and let reprompt() do the rest
rdo2 <- Rdo_modify_simple(rdoseq, "myseq()", "usage")
reprompt(rdo2, file = "seqB.Rd") # updates usage of myseq
## show the rendered result:
Rdo_show(tools::parse_Rd("seqB.Rd"))
## Run this if you wish to see the Rd file:
## file.show("seqB.Rd")
reprompt(infile = "seq.Rd", filename = "seq2.Rd")
reprompt(infile = "seq2.Rd", filename = "seq3.Rd")
## Rd objects for installed help may need some tidying for human editing.
#hseq_inst <- help("seq")
#rdo <- utils:::.getHelpFile(hseq_inst)
rdo <- Rdo_fetch("seq", "base")
rdo
rdo <- Rdpack:::.Rd_tidy(rdo) # tidy up (e.g. insert new lines
# for human readers)
reprompt(rdo) # rdo and rdoseq are equivalent
all.equal(reprompt(rdo), reprompt(rdoseq)) # TRUE
## clean up
unlink("seq.Rd") # remove temporary files
unlink("seq2.Rd")
unlink("seq3.Rd")
unlink("seqA.Rd")
unlink("seqB.Rd")
setwd(cur_wd) # restore user's working directory
unlink(tmpdir)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.