Additional macros in .Rd files

The following are some proposed changes to .Rd files.

Including package metadata in FOO-package.Rd files

Currently (as of 2.3.1) authors must duplicate DESCRIPTION file metadata in FOO-package.Rd files, but frequently the information is not updated properly and becomes inconsistent. This would be solved by introducing a macro which expands at install or display time to show the information. Suggested names for this macro include:

\showDescriptionMetadata
\show_package_metadata
\showDescription
\showDESCRIPTION

The macro should take optional arguments listing which parts of the metadata to include, e.g.

\show_package_metadata[Package,Version,Title,License]{}

It would also be useful to be able to display an index of the package, generated automatically in the same way the INDEX file is currently generated. Suggested names for this macro include:

\showIndexMetadata
\showIndex
\showINDEX

This macro should also be able to select particular items to display. In order to do this, and to maintain reasonable formatting, it is probably not reasonable to handle a manually written INDEX file this way.

Include directive

It would be helpful to have an include directive in .Rd files. This would allow users to use a common set of examples for multiple help topics, or include a common explanation. It would also allow manually written INDEX files to be inserted into FOO-package.Rd files. If we are including text in man pages, many of the individual snippets will be stored in the package/man directory, and they need to be distinguished from full man pages. We could do this by using a different filename extension, or by examining the content of the file. I recommend the former, and suggest that we should be reasonably flexible about the choice of name. Examples might be stored in *.R, preformatted text in *.txt, etc.

Intermediate representation of .Rd files

To support processing of .Rd files, we need to have a formal description of what they contain, and a parser that can convert them into an internal representation on which we can compute. A simple proposal is as a list of lists: each component of the list is either a character vector containing lines of text from the .Rd file, or, in the case of a macro, a list of its arguments with the macro name as an attribute. We should aim to use a similar or identical representation as used in representing XML; this will eventually allow other input formats than .Rd to be used for man pages, and will allow easy output as XML so that other tools can be used for display.

Dynamic man pages

It is highly desirable to be able to generate man pages at run time. One approach to do this is to run a local HTTP server; it would generate the output page at the time when it is requested. Simon Urbanek is looking into the possibility of implementing this.

SVN: $ $Id:$ $