Rdocmacros.html

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>Additional macros in .Rd files</title>
<link rel=stylesheet href="Rtech.css" >
</head>

<body>
<h1>Additional macros in .Rd files</h1>

The following are some proposed changes to .Rd files.

<h3>Including package metadata in FOO-package.Rd files</h3>

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:
<pre>
\showDescriptionMetadata
\show_package_metadata
\showDescription
\showDESCRIPTION
</pre>
The macro should take optional arguments listing which parts of the
metadata to include, e.g.
<pre>
\show_package_metadata[Package,Version,Title,License]{}
</pre>

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:
<pre>
\showIndexMetadata
\showIndex
\showINDEX
</pre>
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.

<h3>Include directive</h3>

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. 

<h3>Intermediate representation of .Rd files</h3>

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.

<h3>Dynamic man pages</h3>

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.
<hr>
<pre>
SVN: $ $Id:$ $
</pre>
</body> </html>