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
