[Rd] Rd, S4 classes and PDFs

[Thomas Themel]

Hi,

I'm documenting a package that makes heavy use of S4 methods at the moment, and
I'm having a hard time from keeping the PDF output of Rd from looking really
terrible.

First of all, what is the preferred way to actually document S4 methods? When I
use promptClass/promptMethod, I get a style that doesn't use the \S4method
macro and puts the entire function signature into a \item.

The generated PDFs look terrible because there is no way to get line breaks
into these \item titles (?) and so a lot of lines just overflow the page.

Manually writing the docs and using \S4method is a noticeable improvement since it

a) separates the types of the arguments into an extra line and 
b) allows line breaks in the argument list

Typographic issues aside, I like that R CMD check will actually make sure that
all the parameters are documented etc.

However, there are still some overflows for methods with many parameters, my
worst offender currently being

\S4method{readWorksheet}{workbook,numeric,numeric,numeric,numeric,numeric,logical}(object,sheet,startRow,startCol,endRow,endCol,header)

where just the type signature alone is too long. I tried various ways of
introducing line breaks in the type signature, but they all seem to fail (\cr,
\, raw line breaks, double raw line breaks), is there anything that can be done
about it?

Another PDF ugliness issue is the index - the S4 class documentation
conventions require a ton of alias that are not directly intended to be
human-readable, my index is cluttered with many overflowing entries of the form

readWorksheet,workbook,character,numeric,missing,missing,missing,missing-method

Is there a way to get rid of these in the PDF?

In another somewhat unpleasant interaction with these conventions, all the
sections in my PDF are titled foo-methods instead of just foo. 

I'd appreciate guidance on the issues above and maybe some pointers to some
well-documented S4 packages.

thanks,
-- 
[*Thomas  Themel*]      Oh, well.  Size isn't everything, I hear; uptime may also
[extended contact]      be important.
[info provided in]              - Arvid Grøtting in the monastery
[*message header*]