How to post Stata program via Dropbox or private website?

Here is a sample program .do file, sampleprog.do:

program sampleprog
egen newVar = group (`1' `2')
end

How can I post it on my website (or dropbox), so that other people could install it to their Stata like this?

net from http://www.mywebsite.com/sampleprog.do
*** or may be like like this:
ssc install ...

I read the documentation about stata.toc...but I did not quite get it. What files should I upload and should it be one folder or what?

(PS: I definitely can simply email the .do file but this is not an option in my case.)

Solution

Here is a full explanation of how to share program or data files with others using your own website. I tried using Dropbox, but Stata 12 appears to have issues with https, which is the protocol for all Dropbox public links. If you want to use Dropbox, I recommend creating a shared folder that will sync on your collaborators' machines. The rest of this answer assumes you have a website serving pages over http or are using Stata 13, which supports https.

If this is a one-time thing, you can skip the rest of this answer by putting the file on your website and telling your collaborator to type:

. copy http://your-site.com/ado/program.ado program.ado

That will copy the ado file at the specified url into the user's current directory. If you want to provide information about your files, plan on sharing with multiple people and need to maintain/document a set files, read on!

Step 1 Create a folder on your website to hold the programs. I will call mine ado/

Step 2 Add the program files, help files, and data files you want to share. For this example, I have created a simple ado file called unique.ado with the following contents:

********************************************** unique.ado
capture program drop unique
program define unique
    *! Count and number observations within group defined by varlist
    *  Example: unique person_id, obs(prow) tobs(pcount) sortby(time)
    *           to count and number rows by a variable called person_id
    syntax varlist, obs(name) tobs(name) [sortby(varlist)]
    bys `varlist' (`sortby') : gen long `obs' = _n
    bys `varlist' (`sortby') : gen long `tobs' = _N
    la var `obs' "Number of this row within `varlist' group."
    la var `tobs' "Total number of rows with identical `varlist' values."
end

Step 3 Create a file called stata.toc to describe the files you wish to share. Here is mine:

********************************************** stata.toc
v 3
d Program to count observations by group
p unique [The unique.ado program for counting observations by group]

These files can be complicated. There are many features I won't cover here, but you can read this documentation to learn more.

Step 4 Create a package file for each of the packages defined by the lines in stata.toc that start with the letter p. Here is my package file for the unique package defined above:

********************************************** unique.pkg
v 3
d unique
d Program to count observations by group
d Distribution-Date: 28 June 2012
f unique.ado

Your directory now looks like this:

ado/
    stata.toc
    unique.ado
    unique.pkg

Step 5 Use the site! Here are the commands to enter.

. net from http://example.com/ado/
. net describe unique
. net install unique

Here is what you'll see after entering the first command:

-----------------------------------------------------------------------------------
http://www.example.com/ado/
Program to count observations by group
-----------------------------------------------------------------------------------

PACKAGES you could -net describe-:
    unique            [The unique.ado program for counting observations by group]
-----------------------------------------------------------------------------------

The second command will tell you more about the package net describe unique:

---------------------------------------------------------------------------------------
package unique from http://www.example.com/ado
---------------------------------------------------------------------------------------

TITLE
      unique

DESCRIPTION/AUTHOR(S)
      Program to count observations by group
      Distribution-Date: 28 June 2012

INSTALLATION FILES                               (type net install unique)
      unique.ado
---------------------------------------------------------------------------------------

The third command will install the package net install unique:

checking unique consistency and verifying not already installed...
installing into /Users/cpoliquin/Library/Application Support/Stata/ado/plus/...
installation complete.

EDIT

See Nick's comments in the answer below. I intended this example to be simple and I don't expect other people to use this program. If you plan on submitting things to Stata Journal or SSC then his comments certainly apply! I hope this answer can serve as a decent tutorial for those confused by the official documentation.