formalize.package is useful when you have a set of functions with flat-format documentation that you want to make into a formal package. It creates a package with Rsource and Rd documentation (and optionally a NAMESPACE file) ready for RCMD CHECK and RCMD BUILD.formalize.package()
formalize.package( funs=find.funs( where), package, where=1, dir.=,
description.file=, new.index=TRUE, README.goes.first=TRUE, keep.flatdoc=FALSE)where.path attribute of search pos whereRdindexREADME, should its documentation file be renamed so that it's found first? See "Package structure details".dir.. The package will have a DESCRIPTION file, a single Rsource file with name "<dir. will be left alone, so you can set up inst directories, etc. More details of the package structure, including control of namespacing, are given below.
The recommended way to use formalize.package is to have your collection of functions as a task called e.g. my.proto.package, use cd(my.proto.package) to bring it to the top workspace, and then call formalize.package(). This will create the formal skeleton in the "my.proto.package" subdirectory of the task directory.
The name of the package is determined by the package parameter, which will default to the obvious, as above. If package is not supplied and no sensible default can be deduced, there will be an error message. The gory details are: package defaults to the name attribute of search pos where, without preceding "package:" if any; if this is NULL, package defaults to the names attribute of the path attribute of search pos where, which will have been set if the thing being packaged is a task.
The mvbutils and .First as proto-packages using mlibrary. Eventually they acquired flat-format documentation-- informal at first, then massaged towards Rd format as CRAN release approached. I then used formalize.package and (repeatedly!) RCMD CHECK. Using formalize.package and the flatdoc documentation system has made it much easier for me to get new versions ready for release.
Package structure details:
All pre-existing files in the "man" and "R" subdirectories of the package will be removed. If there is a "changes.txt" file in the dir. directory, it will be copied to the inst subdirectory of the package. Similarly, any DESCRIPTION file in dir. will be copied to the package directory, after removing the "Built:" line. If there is no DESCRIPTION file in dir., a default DESCRIPTION file will be created in the package directory, but you'd certainly want to edit it before CRAN release. No other files or subdirectories in the package directory will be created or removed, but some essential files will be modified.
If there is already a NAMESPACE file in the package directory, formalize.package will overwrite it by calling make.NAMESPACE, which makes sensible decisions about what to import, export, and S3methodize. However, if no NAMESPACE file is present, none will be created. Hence, to make a namespaced package, just include a dummy NAMESPACE file in the package directory (not dir.) before calling formalize.package; to make a non-namespaced package, just make sure there is no NAMESPACE file present.
By default, the Rsource file will only contain functions, but you can include other objects too by naming them in the funs argument. For functions, only source code will be included; in other words, any attributes except source are removed before printing. In particular, any export.me attribute (see make.NAMESPACE (qv)) and any flat-format documentation in the doc attribute do not go into the Rfile. However, the doc attribute is used to create the Rd files, bydoc2Rd.
If any of the Rd files starts with a period (e.g. ".dotty.name"), it will be renamed to "01.dotty.name.Rd" (to avoid some problems with rcmd).
Any undocumented functions (i.e. functions not in find.documented( doctype="any")) will receive skeletal documentation in a my.proto.package-internals.Rd file. The doco is OK for RCMD CHECK, but says little more than "don't use these functions yourself".
If README.goes.first is TRUE, any Rd file starting with README will be renamed 00README.... This will ensure that the README...function appears first in the "package manual", and top of the list when library(help=mypackage) is called. Package users often find it helpful to have something like a README.xxx function, rather than just an alphabetical list of functions in the package.cd, flatdoc, doc2Rd, README.mvbutils, make.usage.section, make.arguments.section