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.
