Alan,
Quoting Alan Riley <[email protected]>:
> Mark Schaffer ([email protected]), as part of an exchange
> concerning interactive examples in help files, wrote
> > In this particular case I have a programming difficulty, as
> follows.
> >
> > After the user types -help mycommand-, s/he faces a screen with a
> list of
> > of clickable examples, the first of which will load the data.
> After the
> > click, the data are loaded and the user is ready to click on one
> or more
> > other examples, as s/he choses.
> >
> > The alternative is to put a
> preserve/load-example-data/restore-user-data
> > cycle into each clickable example. This seems to me to be likely
> to be
> > painfully slow, mostly because the data would have to be
> downloaded off
> > the net each time (the added loss of time via preserve and restore
> is
> > probably just icing on the cake). I haven't been able to check
> how Stata
> > developers handle this, but my guess is that the dataset that a
> clickable
> > example uses comes built-in with Stata and doesn't have to be
> downloaded
> > with each click. I don't see any way I can emulate this approach
> and at
> > the same time avoid the cost in speed, short of requiring users to
>
> > download the clickable example dataset at the same time that the
> rest of
> > the package is installed. Am I missing something?
>
> I personally would recommend the
> preserve/load-example-data/restore-user-data
> cycle. I also have a tip to ad which will help with that.
>
> Users expect to be able to click as they please in help files
> without
> fear that doing so might damage part of their current Stata state.
> Thus, a preserve/perform-example/restore cycle is a good idea.
> Also, it might be nice for a user to be able to click on any step
> of
> an example and have it work properly, even if they have not
> clicked
> on the earlier steps, such as one to load the appropriate dataset.
>
> -preserve- and -restore- are typically fast enough that users
> won't
> really notice that they are being run behind the scenes (unless
> the
> user has a many megabyte dataset in memory). A http download of
> an
> example dataset, however, could indeed make the examples painfully
> slow.
>
> It would be ideal for the example dataset to have been downloaded
> by the user at the same time as the ado-file and help file which
> contains the links to the examples. But, it is not desirable to
> make the user download this dataset separately with a -net get-
> command. Also, how will the help file (rather, the wrapper
> ado-file which the help file is using to run the examples) know
> where the .dta file is if the user downloads it into their
> current directory and then changes directories?
>
> The solution is to use the "F" package directive. In the Stata 8
> manuals, you can read about it at the bottom of page 26 of the N-R
> Reference. It tells Stata to treat the filename following it as
> if it were a .ado file for the purposes of placement during a
> -net install- command. That is, if a .pkg file contained
>
> .f myexample.ado
> .f myexample.hlp
> .f myexample.dta
>
> Stata would place the first two files in the PLUS/m/ user ado
> subdirectory after a -net install- and the third file in the
> current
> directory after a -net get-.
>
> If the .pkg file instead contained
>
> .f myexample.ado
> .f myexample.hlp
> .F myexample.dta
>
> Stata would download all three files upon a -net install- and
> would place all three in the PLUS/m user ado subdirectory.
>
> This has the nice side-effect of making "myexample.dta" always
> easy to find for any ado-file (such as myexample.ado) which might
> need to -use- it. In fact, once a .dta file is in the ado-path,
> even in a user directory, it may be found with -sysuse
> <filename>-,
> making it very easy for a wrapper ado-file to load it for an
> example.
>
>
> --Alan
> ([email protected])
Thanks for the tips - that's very helpful. I'll go back to my coauthors
of the package and decide if and how we want to go down this route.
A question and a couple of last comments:
- Will the "F" package directive accept a URL location? We had been
planning on providing examples using real datasets that are downloadable
from SSC and/or the Stata website.
- In the simple scheme that I had outlined that has a separate clickable
link for for loading the example data, I had envisioned a call to -use-
without the -clear- option, so that a user would not inadvertently wipe
out their current data.
- An advantage of the simple scheme that does not use preserve/perform-
example/restore is that after users load the sample dataset, they can then
easily experiment with variations on the supplied examples. Click once to
perform the supplied example, then <page-up> and edit it to see what
happens with changes.
Thanks again for the advice!
--Mark
Prof. Mark Schaffer
Director, CERT
Department of Economics
School of Management & Languages
Heriot-Watt University, Edinburgh EH14 4AS
tel +44-131-451-3494 / fax +44-131-451-3008
email: [email protected]
web: http://www.sml.hw.ac.uk/ecomes
________________________________________________________________
DISCLAIMER:
This e-mail and any files transmitted with it are confidential
and intended solely for the use of the individual or entity to
whom it is addressed. If you are not the intended recipient
you are prohibited from using any of the information contained
in this e-mail. In such a case, please destroy all copies in
your possession and notify the sender by reply e-mail. Heriot
Watt University does not accept liability or responsibility
for changes made to this e-mail after it was sent, or for
viruses transmitted through this e-mail. Opinions, comments,
conclusions and other information in this e-mail that do not
relate to the official business of Heriot Watt University are
not endorsed by it.
________________________________________________________________
*
* For searches and help try:
* http://www.stata.com/support/faqs/res/findit.html
* http://www.stata.com/support/statalist/faq
* http://www.ats.ucla.edu/stat/stata/
