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. It is almost the inverse of "RCMD Rdconv -t=txt". Works either on a function with a character-mode doc attribute, or on a separate text object (useful for package and dataset documentation). doc2Rd will produce legal Rd even with completely informal documentation (see Details). However, if your documentation looks like plain pager-style R help, then doc2Rd makes a big effort to generate the special Rd fields (sections, code fragments, links, URLs, etc) that result in nice-looking help. You probably won't need to call doc2Rd yourself, because pre.install does 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 how to write good plain-text documentation.

Usage

doc2Rd( text, file=NULL, append=, warnings.on=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?

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{{}}{} construct, and the quotes will be removed. 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 follows. In SEE.ALSO, any single word between single quotes becomes a link. Everywhere else, anything of the form "See XXX" or "see XXX" or "XXX (qv)", where XXX is in single quotes, will be put into a \{}code{{}\{}link{{}}{}}{} construct, and the " (qv)" will be removed (see also next para). With "[pP]ackage XXX" and "XXX package", a \{}pkg{{}}{} construct will be used. References to .GlobalEnv and .BaseNamespaceEnv go into \{}env{{}}{} constructs. 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).

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 line 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 "DECRIPTION" line (or a "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. 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 IMO fancy equations don't belong in function doco; how about a 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 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 handled correctly by pre.install because you will of course have used the full name in the USAGE section, because it isn't a method. 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.

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). 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 or CHM 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...

There are no "escape characters"-- the system is "text WYSIWYG". For example, if you type a \\{} character in your doc,helpwill display a \\{} in that spot. Single quotes and percent signs can have special implications, though-- see below.
Section titles should either be fully capitalized, or end with a : character. The capitalized version shows up more clearly in informal help. Replace any spaces with periods, e.g. SEE.ALSO not SEE ALSO.
"Item lists", such as in the ARGUMENTS section and sometimes the VALUE section, should be indented. and have a colon to separate the item name from the item body.
General lists of items, like this bullet-point list, should be indented and should start with a "-" character or a "*" character, followed by a space.
Your spacing is generally ignored (exceptions: USAGE, EXAMPLES, multi-line code blocks; see previous point). Text is wrapped, so you should write paragraphs as single lines without hard line breaks. Use blank lines generously, to make your life easier; also, they will help readability of informal helpfiles.
To markin-linecode fragments (including variable names, package names, etc-- basically things that R could parse), put them in single quotes. Hence youcan'tuse single quoteswithinin-line code fragments.

#ifdef flub This flatdoc help file can't show you an example of what you can't do in a flatdoc help file! #endif An example of what you couldn't include: 'myfun( "'No no no!'")'

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.

Examples

Run this code

## 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

Run the code above in your browser using DataLab