Stata 15 help for usersite

[R] net -- Install and manage community-contributed additions from the net

Creating your own site

Below we provide instructions on how to create your own site to distribute do-files, ado-files, help files, datasets, ... that other users can fetch using the net command. Also see [R] net for examples.

Remarks

Remarks are presented under the following headings:

Introduction 1. Place the files on your homepage 2. Make a site 3. Make a package 4. Improve your site Types of files you can deliver The full details of package files The full details of content files SMCL in content and package-description files Error-free file delivery

Introduction

If you have not tried net, do that first. From the command line, type

. net

or pull down Help and choose SJ and community-contributed commands.

Additions to Stata are available from Stata and from other users. This help file provides the information necessary for constructing a site to provide additions to Stata.

To do this, you must have access to a homepage on the World Wide Web. Let's pretend that your home page is http://www.zzz.edu/users/~me, and you wish to make the following files available:

myprog.ado myprog.sthlp mydata.dta

Basically, you can place these files in the directory containing your home page, and Stata can access them. By adding a few more files, you can make accessing them easier. The files do not interfere with the normal operation of HTML pages.

1. Place the files on your homepage

Copy the files to the directory containing your home page. After that, users all over the world can access them from inside Stata by simply typing

. copy http://www.zzz.edu/users/~me/myprog.ado myprog.ado . copy http://www.zzz.edu/users/~me/myprog.sthlp myprog.sthlp . copy http://www.zzz.edu/users/~me/mydata.dta mydata.dta

Users would still need to "install" (copy) myprog.ado and myprog.sthlp to the appropriate place.

The dataset would, of course, be ready to use. Actually, the dataset need not even be copied down by users; they could use it directly by typing

. use http://www.zzz.edu/users/~me/mydata.dta, clear

2. Make a site

Stata's net command and corresponding pulldown is the way users want to fetch your materials. Right now, that will not work with your site:

. net from http://www.zzz.edu/users/~me file from http://www.zzz.edu/users/~me not found http://www.zzz.edu/users/~me/ either 1) is not a valid URL, or 2) could not be contacted, or 3) is not a Stata download site (has no stata.toc file). r(601);

To make a download site, create another new file, stata.toc, on your home page.

If you leave stata.toc empty, the following will happen when someone links to your site:

. net from http://www.zzz.edu/users/~me

------------------------------------------------------------ http://www.zzz.edu/users/~me (no title) ------------------------------------------------------------ This site provides additions and other materials for use with Stata but provides no table of contents. No doubt you have a memo from somebody telling you what you can net install and net get. ------------------------------------------------------------

It is the presence of this file that tells Stata that your URL provides Stata materials as well as HTML pages.

We will discuss making a pretty site shortly.

3. Make a package

A package is a collection of files; the files

myprog.ado myprog.sthlp mydata.dta

form a package. A package file lists the files in a package. Package files end in the suffix .pkg. If you created myprog.pkg describing the above three files, users could type

. net from http://www.zzz.edu/users/~me/ <output omitted>

. net describe myprog ------------------------------------------------------------ package myprog from http://www.zzz.edu/users/~me ------------------------------------------------------------

TITLE myprog. Package to analyze data.

DESCRIPTION/AUTHORS Program by me. Other lines describing the package could appear here.

INSTALLATION FILES (type net install myprog) myprog.ado myprog.sthlp

ANCILLARY FILES (type net get myprog) mydata.dta ------------------------------------------------------------

and, if they wanted to install your package, they could type

. net install myprog

The package file that would cause all this to happen is

--- BEGIN --- myprog.pkg ----------------------------------- v 3 d myprog. Package to analyze data. d Program by me. d Other lines describing the package could appear here.

* I can also insert comments; these will not be displayed. * f lines name the files that comprise your package:

f myprog.ado f myprog.sthlp f mydata.dta --- END ----- myprog.pkg -----------------------------------

This file does not look like much, but looks pretty when the user asks Stata about it.

4. Improve your site

The problem now is that nobody knows to type "net install myprog" unless you tell them. Go back and change your stata.toc file:

--- BEGIN --- stata.toc ------------------------------------ v 3 d Materials by me

d Here are some useful things I have written

p myprog A program to analyze data --- END ----- stata.toc ------------------------------------

Now when users type,

. net from http://www.zzz.edu/users/~me/

------------------------------------------------------------ http://www.zzz.edu/users/~me/ Materials by me ------------------------------------------------------------

Here are some useful things I have written

PACKAGES you could -net describe- myprog A program to analyze data ------------------------------------------------------------

they will see what you have to offer.

Types of files you can deliver

Most packages contain ado-files and help files and, sometimes, a dataset that is used for demonstration purposes. By default, the ado-files and help files are installed and the data file is made available to the user should he or she wish to load it.

Stata determines whether a file is installable or is instead simply ancillary based on its suffix. The following filetypes are automatically installed:

File suffix Description -------------------------------------------------------------- .ado executable code .class executable code .sthlp explanation to be displayed by help .key keyword information to be used by search .mnu contents of menu .dlg code describing dialog box .idlg include file sometimes used by .dlg files .scheme graphics scheme used by graph .style graphics style used by graph --------------------------------------------------------------

In addition, you can force other filetypes to be installed rather than categorized as ancillary by coding F rather than f in the package file. This is sometimes done with .dta datasets that are used by the ado-files.

The full details of package files

v 3 line: v indicates version -- specify v 3; old-style pkg files do not have this.

blank lines: Put in as many as you wish; they are ignored.

* lines: Lines starting with * are comment lines. They are also ignored.

d lines: Lines starting with d are description lines. The first d line is considered the title. Subsequent d lines are considered to be the description text. You may code d followed by nothing to display a blank line.

f lines: Lines starting with f name the files that the package is to provide. The syntax is

First type f next type one or more blanks finally type the name of a file

For instance, you might code

f myprog.ado f myprog.sthlp f myprog.dta

or you might organize your files into subdirectories:

f myprog/myprog.ado f myprog/myprog.sthlp f myprog/myprog.dta

F lines: Lines starting with F are a variation on f lines. The difference is that, when the file is installed, it will be copied to the system directories (and not the current directory) in all cases.

With f lines, the determination on where the file is to be installed is made on the basis of the file's suffix. For instance, xyz.ado would be installed in the system directories whereas xyz.dta would be installed in the current directory.

Coding "F xyz.ado" would have the same result as "f xyz.ado". Coding "F xyz.dta", however, would state xyz.dta is to be installed in the system directories.

g lines: Lines starting with g are also a variation of f lines. The syntax is

First type g next type one or more blanks then type a platformname next type one or more blanks finally type the name of a file

g specifies that the file be installed only if the user's computer is of type platformname; otherwise, the file is ignored. The platform names are WIN64 (64-bit x86-64) and WIN32 (32-bit x86) for Windows; MACINTEL64 (64-bit Intel, GUI) and OSX.X8664 (64-bit Intel, console) for Mac; and LINUX64 (64-bit x86-64) and LINUX (32-bit x86) for Unix.

Additionally, a second filename may be specified. In this case, the first filename is the name of the file on the server (the file to be copied), and the second filename is to be the name of the file on the user's system. For example, you might code

g WIN64 mydll.forwin mydll.plugin g LINUX64 mydll.forlinux mydll.plugin

When you specify one filename, the result is the same as specifying two identical filenames.

G lines: G is a variation on g in the same way that F is a variation of f. The file, if not ignored, is to be installed in the system directories.

h lines: Lines beginning with h are used to indicate that a file must be loaded or else the entire package is not to be installed. The syntax is

First type h next type one or more blanks finally type the name of a file

For instance, you might code

G WIN64 mydll.forwin mydll.plugin G LINUX64 mydll.forlinux mydll.plugin h mydll.plugin

if you were offering the plugin mydll.plugin for Windows and Linux only.

e lines: A line starting with e means stop reading input from the file. An e line is optional.

The full details of content files

v 3 line: v indicates version -- specify v 3; old-style pkg files do not have this.

blank lines: Put in as many as you wish; they are ignored.

* lines: Lines starting with * are comment lines. They are also ignored.

d lines: Lines starting with d are description lines. The first d line is considered the title. Subsequent d lines are considered to be the description text. You may code d followed by nothing to display a blank line.

t lines: Lines starting with t are links to other subdirectories containing other stata.toc lines. The syntax is

First type t next type one or more blanks then type the name of the subdirectory next type one or more blanks finally type any description you wish

For instance, you might code:

t stats Statistics programs I have written t dm Data management programs

To understand what this does, pretend X is the directory containing your home page. Then directory X/stats contains another stata.toc file, and presumably other things, and directory X/dm contains a stata.toc file along with its associated pieces.

The idea here is to nest pieces into categories if you have a large site.

l lines Lines starting with l are links to other sites or links to other places on your site that are not just subdirectories. The syntax is

First type l (lowercase letter ell) next type one or more blanks then type a short name of your choosing next type one or more blanks then type the full URL of the link next type one or more blanks finally type any description you wish

For instance, you could include a link to StataCorp by coding

l stata http://www.stata.com StataCorp

p lines Lines starting with p describe a package or, more technically, plant a link to a package file. The syntax is

First type p next type one or more blanks next type the name of the .pkg file next type one or more blanks finally type any description you wish

For example,

p xyregression xyreg.pkg XY-style regression or p xyregression xyreg XY-style regression

Stata will understand xyreg to mean xyreg.pkg. Package files must be in the same directory as the contents file. Do NOT code "f xyregression xyreg/xyreg.pkg XY-style regression"

SMCL in content and package-description files

The text listed on the second and subsequent d lines in both stata.toc and pkgname.pkg may contain SMCL as long as you include v 3 (or v 2); see [P] smcl.

Error-free file delivery

Most people transport files over the Internet and never worry about the file being corrupted in the process. They do that because corruption rarely occurs. If, however, it is of great importance to you that the files be delivered perfectly or not at all, you can include checksum files in the directory.

For instance, say that included in your package is big.dta and it is of great importance that it be sent perfectly. First use Stata to make the checksum file for big.dta:

. checksum big.dta, save

That creates a small file called big.sum; see [D] checksum. Then copy both big.dta and big.sum to your homepage. That is all there is to do. Stata will now automatically verify that when big.dta is copied it is copied without error.

Whenever you change big.dta remember to also create a new big.sum.


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index