doc2Rd yourself, because pre.install and patch.install do it for you when you are building a package; the entire documentation of package fixr for how to set up an empty template.doc2Rd( text, file=NULL, append=, warnings.on=TRUE, Rd.version=, def.valids=NULL, check.legality=TRUE)doc attribute that is a c.v. of d..!is.null(file); should output be appended rather than overwriting?doc2Rd is being called from pre.install, this will be set to all documented objects in your package. Cross-links to functions in other packaRd.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.class of "cat" so it prints nicely on the screen.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.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.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...helpwill display a \\ in that spot. Single quotes and percent signs can have special implications, though-- see below.'myfun( "'No no no!'")'