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])
*
* 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/
