mvbutils (version 2.5.4)

doc2Rd: 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 packa

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.

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.

More 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...

itemize

• Single quotes are OK within multi-code blocks, USAGE, and EXAMPLES. For multi-line code blocks in other sections, don't bother with the single-quotes mechanism. Instead, insert a "\%\%#" line before the first line of the block, and make sure there is a blank line after the block.
• You can insert "hidden lines", starting with a \% character, which get passed to the Rd conversion routines. If the line starts with \%\%, then the Rd conversion routines will ignore it too. The "\%\%#" line to introduce multi-line code blocks is a special case of this.
• Some other special constructs, such as links, can be obtained by using particular phrases in your documentation; seeSpecial fieldsbelow.

code

pre.install

subsection

• Subsections
• Another depth of nesting
• Special fields
• Format for non-function help
• Extreme details
• Infrequently asked questions

bold

• b
• not
• Q:
• A:
• Q:
• A:
• Q:
• A:
• Q:
• A:
• Q:
• A:

emph

• emphatic stuff
• displayed
• in-line
• doesn't

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