mvbutils (version 2.2.0)

flatdoc: Flat-format documentation

Description

flatdoc lets you edit plain-text documentation in the same file as your function definition. The documentation can be completely informal, or can be close to the standard on-screen appearance of R help files (and if so can be converted to actual Rd files by doc2Rd). This can be useful for your own notes, for informal distribution, and for formal distribution when you are trying to avoid managing dozens of separate source and documentation files.

Usage

# ALWAYS use it like this:
# structure( function( ...) {body},
# doc=flatdoc( EOF="<>"))
# plaintext doco goes here...
# NEVER use it like this:
flatdoc( EOF="<>")

Arguments

EOF

character string showing when plain text ends, as in readlines.mvb

body

replace with your function code

...

replace with your function arg list

Value

• Character vector of class docattr, as read from the current.source() (qv) connection.

Details

A combined function-and-documentation text file should contain your function code wrapped in a structure( construct, followed by a line like this: , doc=flatdoc()) The rest of the file is plain-text documentation, which will be formatted and shown by dochelp when help or ? is called. The documentation can be very informal, but if you follow some guidelines you will be able to convert it automatically to an Rd-format file by calling doc2Rd. There are no escape characters, so a single backslash "\{}" really means a single backslash. When such a file is read in using source.mvb, the flatdoc call will cause the rest of the file to be read in as plain text, and assigned to the doc attribute of the function. Documentation can be terminated with this line: <> The above line will causes source.mvb to revert to normal statement processing mode for the rest of the file. Note that vanilla source will not respect flatdoc; you do need to use source.mvb. Files in this format can be produced by write.sourceable.function, or by hand. The fixr editing system automatically outputs and inputs flatdoc format for functions with flat-format documentation. On some text editors, you can modify syntax highlighting so that the "start of comment block" marker is set to the string "doc=flatdoc(". It's possible to use flatdoc to read in more than one free-format text attribute. The EOF argument can be used to distinguish one block of free text from the next. flatdoc should never be called from the command line; it should only appear in text files designed for source.mvb. The fixr editor interface automatically uses the flatdoc approach to allow editing of source code and plain-text documentation in the same file. If you use a different editor interface, but like the idea of using flatdoc-style documentation, then you will need to:

• make suresource.mvbrather thansourceis used to read in text files;
• if your system produces text files for the editor directly from function objects (whichfixrdoes), then make sure that the files are produced bywrite.sourceable.functionrather thanprintorwriteorcat.

See Also

source.mvb, doc2Rd, dochelp, write.sourceable.function, make.usage.section, make.arguments.section, fixr, the demo in "flatdoc.demo.R"

Examples

## Put everything before the next comment into a text file <<your filename>>
structure( function( x) {
  x*x
}
,doc=flatdoc("<<end of doc>>"))
Here is some informal documentation for the "SQUARE" function
<<end of doc>>
## Now try SQUARE <- source.mvb( <<your filename>>); ?SQUARE
## Put everything before the next comment into a text file
myfun <- structure( function(...) {}
,  att1=flatdoc( EOF="<<end of part 1>>")
,  att2=flatdoc( EOF="<<end of part 2>>"))
This goes into "att1"
<<end of part 1>>
and this goes into "att2"
<<end of part 2>>
## Now "source.mvb" that file, to create "myfun"
cat( attr( myfun, "att1")) # This goes into "att1"
cat( attr( myfun, "att2")) # This goes into "att2"