[Rd] package introductions

[Paul Gilbert]

I have been experimenting with different possibilities for an 
"introduction" page for my packages. That is, a good place to tell users 
about the most important things in a package, and where to start.

Recently there was a discussion about this, and a suggestion to use 
<foo>-package.Rd, and also a function that generates a skeleton 
document. My problem with this suggestion is that <foo>-package may not 
be high in the sort order, so users will not find this unless they know 
to look for it (and so there is difficulty establishing the convention). 
A second problem is that the skeleton document has information that may 
be useful, but is not really what I am looking for. (It has all the 
methods in the package, but what I want is to tell users the most 
important ones to look at first. It also has "high maintenance" 
information, like version numbers. I want something that is either 
completely automatic, or manual but low maintenance.) Another related 
problem is that the information put in the skeleton  <foo>-package.Rd 
possibly should be in a man page somewhere, so if this does happen, that 
naming convention will likely be used and would then conflict with my 
introduction.

I now think I have found something that works fairly well. I put the 
introduction in a file 00.foo.Intro.Rd and in that file have

/name{00.foo.Intro}
/alias{00.foo.Intro}
/alias{foo.Intro}

Then sorting puts the 00 version at the beginning of the table of 
contents in both the pdf version with all the help pages, and in the 
html version for the help.start() system. Also, ?foo.Intro works. 
(?"00.foo.Intro" works too, but the quote marks are necessary and this 
seems likely to cause problems for beginners.)

It is also helpful to put something like "See ?foo.Intro for more 
details" in the "Description:" line of the DESCRIPTION file, so users 
see this with help(package="foo"). (I don't think users of the 
help.start() system ever see this, but perhaps someone can correct me.)

I also would like to put in my vote for a DESCRIPTION file tag
   GettingStarted: foo.Intro
probably as an optional tag to begin.

Of course, the biggest simplification happens when things like this are 
done in a similar way by everyone. ( "configure ; make" is not 
intuitively simple, but everyone now knows the incantation.)

Paul Gilbert
-------------- next part --------------
====================================================================================

La version fran?aise suit le texte anglais.

------------------------------------------------------------------------------------

This email message from the Bank of Canada is given in good faith, and shall not be
binding or construed as constituting any obligation on the part of the Bank.

This email may contain privileged and/or confidential information, and the Bank of
Canada does not waive any related rights. Any distribution, use, or copying of this
email or the information it contains by other than the intended recipient is
unauthorized. If you received this email in error please delete it immediately from
your system and notify the sender promptly by email that you have done so. 

Recipients are advised to apply their own virus checks to this message upon receipt.

------------------------------------------------------------------------------------

L'information communiqu?e dans les courriels en provenance de la Banque du Canada
est soumise de bonne foi, mais elle ne saurait lier la Banque et ne doit aucunement
?tre interpr?t?e comme constituant une obligation de sa part.

Le pr?sent courriel peut contenir de l'information privil?gi?e ou confidentielle.
La Banque du Canada ne renonce pas aux droits qui s'y rapportent. Toute diffusion,
utilisation ou copie de ce courriel ou des renseignements qu'il contient par une
personne autre que le ou les destinataires d?sign?s est interdite Si vous recevez
ce courriel par erreur, veuillez le supprimer imm?diatement et envoyer sans d?lai ?
l'exp?diteur un message ?lectronique pour l'aviser que vous avez ?limin? de votre
ordinateur toute copie du courriel re?u.

D?s la r?ception du pr?sent message, le ou les destinataires doivent activer leur
programme de d?tection de virus pour ?viter toute contamination possible.