[Rd] package introductions

From: Paul Gilbert <pgilbert_at_bank-banque-canada.ca>
Date: Wed 01 Feb 2006 - 16:54:20 GMT


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


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.



R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Thu Feb 02 04:18:10 2006

This archive was generated by hypermail 2.1.8 : Wed 01 Feb 2006 - 22:54:36 GMT