-------------------------------------------------------------------------------
help for usepackage
-------------------------------------------------------------------------------

 Program to find and install a list of user-written packages needed to run a do
> -file

    usepackage pkgnames [ , update nearest ]

Description

    usepackage finds and installs user-written packages that are needed to
    run a do-file.  When sharing a do-file that contains calls to
    user-written commands from SSC or elsewhere, you can use usepackage to
    include a list of packages rather than writing a series of net install or
    ssc install commands to install a list of user-written packages (or
    instructing the user to find and install a list of packages via commands
    like findit or search) from net-aware Stata.

    Since the do-file will need to first include a command to install
    usepackage from SSC:

            ssc install usepackage

    usepackage will only save typing if more than one package is needed to
    run a do-file.

    usepackage is particularly useful when user-written packages come from
    locations other than the SSC Archives because usepackage first searches
    the SSC and then if it does not find a match it searches other internet
    locations (e.g., those searched by net search by default), including but
    not limited to user-written additions published in the Stata Journal (SJ)
    and the Stata Technical Bulletin (STB).  Otherwise, in order to install
    user packages, such as statplot (from SSC) or dropmiss (from Stata
    Journal), the user would need to include in the do-file lines:

            ssc install statplot, replace
 
            net install dm89_1,
        from(http://www.stata-journal.com/software/sj8-4)
 

Options 

    update forces usepackage to update all user-written commands specified in
        pkgnames if they are already installed.

    nearest specifies that, after looking for an exact match for each command
        listed in pkgnames on SSC and other internet locations searched by
        net search, usepackage should install its best match of a similar
        package name found in a net search (that is, packages with words in
        the title or description matching the unmatched command in the
        pkgnames list). For example, the command:

            usepackage statplo
 
        would return no matches; however, if you also specified the nearest
        option, usepackage would find and install the user-written package
        statplot as the nearest match.

Remarks

    If usepackage does not find a match for a command in the pkglist in the
    SSC Archives, it next searches other internet locations searched by net
    search.  In doing so, usepackage produces the full net search output in
    the Results window. Currently, this output cannot be surpressed.  The
    reason for this is that usepackage searches for the matching packages and
    descriptions in a log-file of this output.  Further, this output cannot
    be surpressed by running usepackage quietly (doing so will produce an
    error).

    usepackage is partly inspired by the LaTeX command with the same name
    (\usepackage{}) and similar functionality.


Examples

// Setup //
  ** Uninstall user packages statplot and bacon
    . cap ado uninstall statplot //uinstall package statplot
    . cap ado uninstall st0197 //uninstall package bacon

  ** Specify that usepackage is installed from SSC
    . cap ssc install usepackage
        
// Install a list of user packages from various internet locations //
    . usepackage estout dropmiss rtfutil ralpha mac_unab

// Install missing package statplot (from SSC) //
    . usepackage statplot

// Install missing package bacon (aka package st0197) (from Stata Journal) // 
    . usepackage bacon

   ** Alternatively:
    . usepackage st0197, update

// Install and Update packages, including near-matches, from various locations 
> //
    . usepackage tabou dropmis num2wor, near up

Author

    Eric A. Booth, Texas A&M University
    ebooth@ppri.tamu.edu
    http://www.eric-a-booth.com

Also see

    On-line:  help for net install; ssc install; findit; search