doc2Rd {mvbutils}R Documentation

Converts plain-text documentation to Rd format

Description

Converts plain-text documentation into an Rd-format character vector, optionally writing it to a file. You probably won't need to call doc2Rd yourself, because pre.install and patch.install do it for you when you are building a package; the entire documentation of package mvbutils was produced this way. The main point of this helpfile is to describe plain-text documentation details. However, rather than wading through all the material below, just have a look at a couple of R's help screens in the pager (i.e. text-style help, not HTML help) and try making one yourself. See fixr for how to set up an empty template.

Usage

doc2Rd( text, file=NULL, append=, warnings.on=TRUE, Rd.version=, def.valids=NULL, check.legality=TRUE)

Arguments

text (character or function) character vector of documentation, or a function with a doc attribute that is a c.v. of d..
file (string or connection) if non-NULL, write the output to this file
append (logical) only applies if !is.null(file); should output be appended rather than overwriting?
warnings.on (logical) ?display warnings about apparently informal documentation?
Rd.version (character) what Rdoc version to create "man" files in? Currently "1" means pre-R2.10, "2" means R2.10 and up. Default is set according to what version of R is running.
def.valids (character) objects or helpfiles for which links should be generated automatically. When doc2Rd is being called from pre.install, this will be set to all documented objects in your package. Cross-links to functions in other packages are not currently generated automatically (in fact not at all, yet).
check.legality if TRUE and Rd.version is 2 or more, then the output Rd will be run thru parse_Rd and a try-error will be returned if that fails; normal return otherwise. Not applicable if Rd.version is 1.

Details

Flat-format (plain-text) documentation in doc attributes can be displayed by the replacement help in mvbutils (see dochelp) without any further ado. This is very useful while developing code before the package-creation stage, and you can write such documentation any way you want. When you want to generate a package, doc2Rd will convert pretty much anything into a legal Rd file. However, if you can follow a very few rules, using doc2Rd will actually give nice-looking authentic R help. For this to work, your documentation basically needs to look like a plain-text help file, as displayed by help( ..., pager=T) (pre-2.10) or help(..., help_type="text") (post-2.10).

Rather than wading through this help file to work out how to write plain-text help, just have a look at a couple of R's help screens in the pager (i.e. not HTML help) and try making one yourself. You can also use help2flatdoc to convert an existing plain-text help file. Also check the file "sample.fun.rrr" in the "demostuff" subdirectory of this package (see Examples). If something doesn't work, delve more deeply...

An example of what you couldn't include:

'myfun( "'No no no!'")'

Value

Character vector containing the text as it would appear in an Rd file, with class of "cat" so it prints nicely on the screen.

Special fields

Almost anything between a pair of single quotes will be put into a \code{} or \code{\link{}} or \pkg{} or \env{} construct, and the quotes will be removed. A link will be used if the thing between the quotes is a one-word name of something documented in your package (assuming doc2Rd is being called from pre.install). A link will also be used in all cases of the form "See XXX" or "see XXX" or "XXX (qv)", where XXX is in single quotes, and any " (qv)" will be removed. With "[pP]ackage XXX" and "XXX package", a \pkg{} construct will be used. References to .GlobalEnv and .BaseNamespaceEnv go into \env{} constructs. Otherwise, a \code{} construct will be used, unless the following exceptions apply. The first exception is if the quotes are inside USAGE, EXAMPLES, or a multi-line code block. The second is if the first quote is preceded by anything other than " ", "(" or "-". The final semi-exception is that a few special cases are put into other constructs, as next.

URLs and email addresses should be enclosed in <...>; they are auto-detected and put into \url{} and \email{} constructs respectively.

Lines that start with a % will have the % removed before conversion, so their contents will be passed to RCMD Rdconv later (unless you start the line with %%). They aren't displayed by dochelp, though, so can be used to hide an unhelpful USAGE, say, or to hide an "#ifdef windows".

Triple dots are converted to \dots, regardless of whether they're in code or normal text. A solitary capital-R is converted to \R.

Any reasonable "*b*old" or "_emphatic stuff_" constructions (no quotes, just the asterisks) will go into \bold{} and \emph{} constructs respectively, to give bold or emphatic stuff. (Those first two didn't, because they are "unreasonable"– in particular, they're quoted.) No other fancy constructs are supported (yet).

FORMAT.FOR.NON-FUNCTION.HELP

For documenting datasets, the mandatory sections are DESCRIPTION, USAGE, and FORMAT; the latter works just like ARGUMENTS, in that you specify field names in a list. Other common sections include EXAMPLES, SOURCE, REFERENCES, and DETAILS.

Extreme details

The first line should be the docfile name (without the Rd) followed by a few spaces and the package descriptor, like so:

utility-funs package:mypack

When doc2Rd runs, the docfile name will appear in both the \name{} field and the first \alias{} field. pre.install will actually create the file "utility-funs.Rd". The next non-blank lines form the other alias entries. Each of those lines should consist of one word, preceded by one or more spaces for safety (not necessary if they have normal names).

"Informal documentation" is interpreted as any documentation that doesn't include a "DESCRIPTION" (or "Description:") line. If this is the case, doc2Rd first looks for a blank line, treats everything before it as \alias{} entries, and then generates a DESCRIPTION section into which all the rest of your documentation goes. No other sections in your documentation are recognized, but all the special field substitutions above are applied. (If you really don't want them to be, use the multi-line code block mechanism.) Token USAGE, ARGUMENTS, and KEYWORDS sections are appended automatically, to keep RCMD happy.

Section titles built into Rd are: DESCRIPTION, USAGE, SYNOPSIS, ARGUMENTS, VALUE, DETAILS, EXAMPLES, AUTHOR or AUTHOR(S), SEE.ALSO, REFERENCES, NOTE, KEYWORDS and, for data documentation only, FORMAT and SOURCE. Other section titles (in capitals, or terminated with a colon) can be used, and will be sentence-cased and wrapped in a \section{} construct. Cross-refs to sections will be picked up if of the form "see ANOTHER.SECTION" or "ANOTHER.SECTION (qv)".

The \docType field is set automatically for data documentation (iff a FORMAT section is found) and for package documentation (iff the name on the first line includes "-package").

Spacing within lines does matter in USAGE, EXAMPLES, and multi-line code blocks, where what you type really is what you get (except that a fixed indent at the start of all lines in such a block is removed, usually to be reinstated later by the help facilities). The main issue is in the package "manual" that RCMD generates for you, where the line lengths are very short and overflows are common. (Overflows are also common with in-line code fragments, but little can be done about that.) The "RCMD Rd2dvi –pdf" utility is helpful for seeing how individual helpfiles come out.

In SEE.ALSO, the syntax is slightly different; names of things to link to should not be in single quotes, and should be separated by commas or semicolons; they will be put into \code{\link{}} constructs. You can split SEE.ALSO across several lines; this won't matter for pager help, but can help produce tidier output in the file "***-manual.tex" produced by RCMD CHECK.

In EXAMPLES, to designate "don't run" segments, put a "## Don't run" line before and a "## End don't run" line after.

In KEYWORDS, separate the keywords with commas, semicolons, or line breaks; don't use quotes. A token KEYWORDS section will be auto-generated if you don't include one, to keep RCMD happy.

Infrequently asked questions

Q: I have written a fancy displayed equation using \deqn{} and desperately want to include it. Can I?

A: Yes (though are you sure that a fancy equation really belongs in your function doco? how about in an attached PDF, or vignette?). Just prefix all the lines of your \deqn with %. If you want something to show up in informal help, too, then make sure you also include lines with the text version of the equation.

Q: I have written a fancy in-line equation using \eqn{} and desperately want to include it. Can I?

A: No. Sorry.

Q: For some reason I want to see one thing in informal help (i.e. when the package isn't actually loaded but just sitting in a task on the search path), but a different thing in formal help. Can I do that?

A: If you must. Use the %-line mechanism for the formal help version, and then insert a line "%#ifdef flub" before the informal version, and a line "%#endif" after it. Your text version will show up in informal help, and your fancy version will show up in all help produced via Rd. (Anyone using the "flub" operating system will see both versions...)

Q: How can I insert a file/kbd/samp/option/acronym etc tag?

A: You can't. They all look like single quotes in pager-style help, anyway.

Q: What about S3?

A: S3 methods can be documented just like any other function, except for one small detail: in the USAGE section, the generic name instead of your method name should be used. IE if you are documenting a method print.cat, the USAGE section should contain a call to print(x,...) rather than print.cat(x,...). doc2Rd will detect this and produce correct Rd format. If you document several different S3 methods for the same generic in the same piece of documentation (and even if you don't), then it may help the user if you put a comment with the method name after each call, e.g. print(x,...) # print.cat, especially if the optional arguments are different. Doing that also gives pre.install a better chance of correctly sorting out the documentation.

Sometimes you have a function which looks like it might be an S3 method, but isn't (e.g. as.data.frame.I in package mvbutils). This will be not be labelled as S3 by pre.install because you will of course have used the full name in the USAGE section, because it isn't a method. However, it can still be found by NextMethod etc., so you probably shouldn't do this.

S3 classes themselves need to be documented via a relevant function, using aliasses.

Q: What about S4?

A: I am not a fan of S4 and have found no need for it in many 1000s of lines of R code... hence I haven't included any explicit support for it so far. Nevertheless, things might well work anyway, unless special Rd constructs are needed. If doc2Rd doesn't work for your S4 stuff (bear in mind that the %-line mechanism may help), then for now you'll still have to write S4 Rd files yourself; see pre.install for where to put them. However, if anyone would like the flatdoc facility for S4 and is willing to help out, I'm happy to try to add support.

Note

In rare cases, backslashes and braces inside marked code (fragments, multi-line blocks, and the USAGE and EXAMPLES sections) will cause harmless but annoying warnings about missing links during RCMD CHECK. This is a consequence of buggy behaviour in the Rd conversion routines; the only way I could get these characters to display completely reliably, was by introducing empty links.

Author(s)

Mark Bravington

See Also

The file "sample.fun.rrr" in subdirectory "demostuff", and the demo "flatdoc.demo.r".

To do a whole group at once: pre.install.

To check the results: "RCMD Rd2dvi –pdf XXX.Rd" and "RCMD Rdconv -t=html XXX.Rd" and/or "-t=txt" (though patch.installed will allow to check the HTML version immediately).

To convert existing Rd documentation: help2flatdoc.

If you want to tinker with the underlying mechanisms: flatdoc, write.sourceable.function

Examples

## Needs a function with the right kind of "doc" attr
## Look at file "demostuff/sample.fun.rrr"
lodlibs <- library()[[2]]
mvb.lib.loc <- lodlibs[ lodlibs[,1]=='mvbutils', 2][1]
sample.fun <- source.mvb( file.path( mvb.lib.loc, 'mvbutils', 'demostuff', 'sample.fun.rrr'))
cat( '***Original plain-text doco:***\n')
print( as.cat( attr( sample.fun, 'doc'))) # unescaped, ie what you'd actually edit
cat( '\n***Rd output:***\n')
sample.fun.Rd <- doc2Rd( sample.fun)
print( sample.fun.Rd) # already "cat" class

[Package mvbutils version 2.5.0 Index]