{smcl}
{* 03apr2002}{...}
{hline}
help for {hi:adomaint}
{hline}

{title:Verify up-to-dateness of ado-files installed from the net}

{p 8 25}
{cmd:adomaint}
[{cmdab:q:uery}]
[{cmd:,}
	{cmdab:re:fresh}
	{cmdab:tr:ace}
	{cmd:dir(}{it:dirname}{cmd:)}
]

{p 8 25}
{cmd:adomaint}
{cmdab:n:otes}

{p 8 25}
{cmd:adomaint}
{cmdab:l:ist}{space 4}{c -(}
	{cmd:all} |
	{cmd:dups} |
	{cmdab:van:ished} |
	{cmdab:up:-to-date} |
	{cmdab:out:-of-date} |
	{cmdab:lac:king} |
	{cmdab:noinfo}
{c )-}
[{cmd:,}
	{cmdab:re:fresh}
	{cmdab:tr:ace}
	{cmd:dir(}{it:dirname}{cmd:)}
]

{p 8 25}
{cmd:adomaint}
{cmd:rmdups}{space 2}[{cmd:,}
	{cmdab:re:fresh}
	{cmdab:tr:ace}
	{cmd:dir(}{it:dirname}{cmd:)}
]

{p 8 25}
{cmd:adomaint}
{cmd:update}{space 2}[{cmd:,}
	{cmdab:re:fresh}
	{cmdab:tr:ace}
	{cmd:dir(}{it:dirname}{cmd:)}
]

{p 4}
and for programmer use:

{p 8 25}
{cmd:adomaint}
{cmd:_use}{space 4}[{cmd:,}
	{cmdab:re:fresh}
	{cmdab:tr:ace}
	{cmd:dir(}{it:dirname}{cmd:)}
	{cmd:nomsg}
	{cmd:trkfile}
	{cmd:label}
]

{p 4}
in all the above commands, {it:dirname} may be

{p 8 25}
	{cmd:SJPLUS} | {cmd:STBPLUS} | {cmd:SITE}

{p 4 4}
and {cmd:SJPLUS} ({cmd:STBPLUS}) is the default if option {cmd:dir()} is not
specified.  ({cmd:SJPLUS} and {cmd:STBPLUS} mean the same thing.)  Thus, the
{cmd:dir()} option really is {cmd:dir(SITE)}, and it is for site administrators
who, rather than working with their personal copies of additions, want to work
with the site's copy.


{title:Description}

{p 4 4}
If you install ado-files from the net -- such as additions from the 
{help ssc:SSC archive} using the {help ssc} command, or from other places such
as the {help sj:Stata Journal} or user-sites using the {help net} command or
by pulling {bf:Help} and selecting {bf:SJ and User-written programs}, the time
will come when you will wonder whether the programs you have installed are up
to date.  Might the author have updated the program?  {cmd:adomaint} will
answer that question.

{p 4 4}
{cmd:adomaint} works by looking at what you have installed and going back out
to the web to find out if the command (package) has been updated.  (Package is
a better terms because usually there is one more than one file associated with
an addition.)

{p 4 4}
{cmd:adomaint} determines whether a package is up to date by looking at the 
"distribution-date" line in the package's description that is written by the 
author.  Not all authors include that line; if it is missing, {cmd:adomaint}
will not be able to determine whether the package is up to date.

{p 4 4}
{cmd:adomaint query} provides a summary report about the number of packages
you have installed and their up-to-dateness.  ({cmd:adomaint notes} provides
information that will help you interpret {cmd:adomaint query}'s output.)

{p 4 4}
{cmd:adomaint list} lists the names of packages that are up to date, out out
of date, etc.

{p 4 4}
{cmd:adomaint rmdups} removes any duplicate packages you may have installed.

{p 4 4}
{cmd:adomaint update} will update your out-of-date packages.

{p 4 4}
{cmd:adomaint _use} is a utility for programmers who want to write code to
manipulate the installed packages.


{title:Options}

{p 4 8}
{cmd:refresh} specifies that {cmd:adomaint} should updates its cache of
    information about what is available over the web.

{p 4 8}
{cmd:trace} is only relevant if {cmd:refresh} is specified.  It asks that
    entertaining output be produced as {cmd:refresh} contacts each of the
    sites, thus reassuring those with lots of packages installed that
    {cmd:adomaint} is not broken.  (Contacting lots of sites can take a
    while.)

{p 4 8}
{cmd:dir(}{it:dirname}{cmd:)} specifies where the packages are installed.  You
    probably do not want to specify this option; the option is for site
    administrators -- who will specify {cmd:dir(SITE)} -- so that they can work
    with the site-wide copies rather than private copies.

{p 4 8}
{cmd:nomsg}, {cmd:trkfile}, and {cmd:label} are for use with the
    {cmd:adomaint} {cmd:_use} programmer's command.

{p 8 8}
    {cmd:nomsg} specifies that {cmd:adomaint _use} is not to present 
    messages about how old the cache file is.

{p 8 8}
    {cmd:trkfile} specifies that the dataset returned need only contain 
    information about what is installed and not the information about the
    web status of what is installed.  

{p 8 8}
    {cmd:label} specifies that the returned dataset is to be fully labeled.
    As you are learning about {cmd:adomaint _use}, you will find this 
    option useful.  In actual use as a subroutine inside other programs, 
    there is no reason to specify this option.

{title:adomaint query}

{p 4 4}
{cmd:adomaint query} provides summary output.  Begin by typing,

	. {cmd:adomaint query}

{p 4 4}
although you can omit the word {cmd:query}.  {cmd:query} is assumed when 
you do not specify a subcommand.  In any case, you will see output that 
looks like this:

{hline}
{com}. adomaint
{txt}{p 4 8}
(no previous web search information found;
you should specify the -refresh- option)
{p_end}

{col 6}{hline 64}
{col 7}number of user-written packages installed:{col 51}{res}       57
{txt}{col 30}earliest installed:{col 51}{res:05jan2001}
{col 32}latest installed:{col 51}{res:03apr2002}

{col 28}number of duplicates:{col 51}{res}        0{txt}  (note 1)
{col 22}number no longer available:{col 51}{res}        0{txt}  (note 2)
{col 19}number known to be up-to-date:{col 51}{res}        0{txt}  (note 3)
{col 18}number known to be out-to-date:{col 51}{res}        0{txt}  (note 4)
{col 17}number lacking date information:{col 51}{res}        0{txt}  (note 5)

{col 22}number with no information:{col 51}{res}       57{txt}  (note 6)
{col 6}{hline 64}
{col 6}(type -{stata adomaint notes}- for the text of the notes)
{hline}

{p 4 4}
We have 57 packages installed and, on all 57, there is no information.  Note
that at the top of the output it says, "no previous web search information
found; you should specify the -refresh- option".

{p 4 4}
{cmd:adomaint} works by going out to the web on each of the 57 packages and 
finding out what now is available.  Contacting all 57 sites can take a while,
so {cmd:adomaint} only does that when you specify the {cmd:refresh} option.
Otherwise, {cmd:adomaint} uses the last information it has left over and, 
since this is the first time you are using {cmd:adomaint}, there is not 
information from last time.  Type:

	. {cmd:adomaint, refresh}

{p 4 4}
The 57 packages will be categorized.  In the future, when you use any
{cmd:adomaint} subcommand, it will base its results on its findings from
having gone out to the web from the "{cmd:adomaint, refresh}" you have just
typed.  Periodically, you will want to type "{cmd:adomaint, refresh}" to
obtain more up-to-date information.  You do not have to do that often:  using
information that is minutes, hours, or even days old is perfectly
satisfactory.  What is the worse that can happen?  A packages will be
categorized as being "up-to-date" when in fact, a new version of it appeared
since the last time you specified the {cmd:refresh} option.

{p 4 4}
Note that in the {cmd:adomaint query} output appear references to notes and
the footnote "type -adomaint notes- for the text of the notes).  Eventually,
you will not need the notes, so that is why {cmd:adomaint query} does not
automatically display them.  All typing {cmd:adomaint notes} does is display
the prerecorded text of the notes.  Here they are:

    {title:1.  Number of duplicates}

{p 8 8}
    These are packages that have been installed more than once; perhaps 
    you installed a new version without eliminating the previous one.
    In any case, you should get rid of the duplicates, and that you can 
    do by typing "{cmd:adomaint rmdups}".

    {title:2.  Number no longer available}

{p 8 8}
    Either the package really is no longer available or the site is 
    temporarily offline.


    {title:3.  Number known to be up-to-date}

{p 8 8}
    Self explanatory.


    {title:4.  Number known to be out-of-date}

{p 8 8}
    Self explanatory.  To update these ado-files, all you need do is 
    type "{cmd:adomaint update}".

    {title:5.  Number unknowable whether up-to-date}

{p 8 8}
    The package does not contain a "distribution-date" field, so there is no
    easy way to tell whether the package has changed.  The "distribution-date"
    field was introduced on 02apr2002 and so many old sites have not been
    updated to include it, and some authors simply do not provide
    "distribution date" information.  Probably the versions you have installed
    are up to date.

    {title:6.  Number with no information}

{p 8 8}
    {cmd:adomaint} only obtains fresh information from the web when you
    specify the {cmd:refresh} option because contacting all the sites can take
    a while.  Using slightly dated information (measured, say, in hours or
    days) will work just as well as new information.  The no-information
    packages are packages you have installed since the last time you specified
    {cmd:adomaint}'s {cmd:refresh} option.  To categorize these packages into
    one of the above categories, you can type "{cmd:adomaint query, refresh}".


{title:adomaint list}

{p 4 4}
{cmd:adomaint list} will list the identities of the packages you have
installed based on their category (duplicate, no longer available, known 
to be up-to-date, etc.).  

{p 4 4}
{cmd:adomaint list} allows the {cmd:refresh} option, but most people use the
{cmd:refresh} option only with {cmd:query} and then base their subsequent work
off of that.


{title:adomaint rmdups}

{p 4 4}
{cmd:adomaint rmdups} will uninstall any duplicated packages you have 
installed, leaving just the most recent one of each installed.

{p 4 4}
{cmd:adomaint rmdups} allows the {cmd:refresh} option, but that is just 
for consistency.  It does not matter how out-of-date you web information 
is because determining a whether a package is a duplicate can be determined 
by examining what you have installed solely, and all {cmd:adomaint} commands
use the most up-to-date information about that, always.


{title:adomaint update}

{p 4 4}
{cmd:adomaint update} is the most useful of the {cmd:adomaint} commands.  It
tells {cmd:adomaint} to reinstall any of your user-written commands that have
been updated.


{title:Returned results}

{p 4 4}
{cmd:adomaint query} returns in {cmd:r()}

	{cmd:r(n)}             total number of packages installed
	{cmd:r(n_dups)}        # of packages, installed more than once
	{cmd:r(n_vanished)}    # of packages, no longer available
	{cmd:r(n_up_to_date)}  # of packages, known to be up-to-date
	{cmd:r(n_out_of_date)} # of packages, known to be out-of-date
	{cmd:r(n_lacking)}     # of packages, lacking date information 
	{cmd:r(n_noinfo)}      # of packages, no information

{cmd:adomaint rmdups} returns in {cmd:r()}
	{cmd:r(n_dups)}        # of packages, installed more than once
	{cmd:r(n_removed)}     # of packages, removed

{cmd:adomaint update} returns in {cmd:r()}

        {cmd:r(n_out_of_date)} # of packages, known to be out-of-date
        {cmd:r(n_updated)}     # of packages successfully updated


{title:Also see}

{p 5 14 2}
Manual:  {hi:[R] net}{p_end}
On-line: help for {help net}, {help ssc}