{smcl}
{* 22may2008}{...}
{cmd: help docs}
{hline}

{title:Title} 
 
{p 5 18 2}{hi:docs} - Look up documentation for datasets

{title:Syntax} 
 
{phang}List docs installed

{p 8 17 2}{cmdab:docs dir}

{phang}Display documentation

{p 8 17 2}
{cmdab:docs} [{cmd:@}{it:docname}] [{cmd:(}{it:datasetlist}{cmd:)}] [{it:varlist}|{it:indexlist}|{it:keyname}{cmd::}{it:keyterms}] [{cmd:,} {it:options}] 

{synoptset 18 tabbed}{...}
{synopthdr}
{synoptline}
{synopt :{it:metadata}}The metadata to list for each variable; the possibilities are specific to each {it:docname}{p_end}
{synopt :{opt none}}Display {it:no} info other than dataset, index, and variable name{p_end}
{synopt :{opt search(terms)}}Restrict display to items including search terms{p_end}
{synopt :{opt sxs}}Display side-by-side columns, one for each variable{p_end}
{synopt :{cmdab:nomem:ory}}Do not save any part of the command for later use{p_end}
{synoptline}
{p2colreset}{...}

{title:Description}

{pstd}{cmd:docs} is intended to display documentation for data files, especially for sets of related data files.

{pstd}{cmd:docs dir} will list the {it:docname}s of documentation that are installed/available. Clicking on a {it:docname} (or equivalently, doing {cmd:help docs }{it:docname})
will bring up a help file with additional details for that {it:docname}. 

{pstd}The final output from each {cmd:docs} command (other than {cmd:docs dir}) is a recap of the command as it was run, which is useful for several reasons:

{p 8 11 2}o- The recap serves as a key for the displayed metadata; the metadata labels are not included in the main output because of formatting considerations.{p_end}
{p 8 11 2}o- The recap highlights the specified metata options, but also shows the other possibilities, to save the trouble of looking them up in {cmd:help docs} {it:docname}.{p_end}
{p 8 11 2}o- All the specifiers in the command are optional, so the recap shows, for example, which variables were requested, even when variable names were omitted from the command itself.{p_end}

{title:Remarks}

{pstd}There are four main aspects, or dimensions, of information that can be specified:

{pstd}
1. Which documentation to use{break}
2. The datasets to select from those documented{break}
3. The variables within each dataset{break}
4. The metadata about each variable{p_end}

{pstd}So, the syntax diagram could be rewritten as (ignoring the few other options for now):

{p 8 17 2}
{cmdab:docs} [{cmd:@}{it:1. documentation}] [{cmd:(}{it:2. datasets}{cmd:)}] [{it:3. variables}] {cmd:,} [{it:4. metadata}]  

{pstd}In fact, the first three elements can be specified in any order. {it:docname} is recognized by the {cmd:@} attached to it, {it:datasets} are recognized by being inside parentheses, and {it:variables} are recognized by being everything else.

{pstd}{ul:{bf:1. Documentation}}

{pmore}{cmd:@}{it:docname} specifies the documentation to use. For example you might have 5 years of surveys on teen smoking, and a database of vital signs from people hospitalized with cancer.
They might conceivably be selected with:

{pmore}{cmd:. docs @teensmoking} {it:other optional specs}

{pmore}{cmd:. docs @cancervitals} {it:other optional specs}

{pstd}{ul:{bf:2. Datasets}}

{pmore}{opt (datasetlist)} is a {help docs##lists:list} {help docs##lists:(see below)} of dataset names, where the names available are determined by the documentation. Continuing with the prior examples, 
the smoking surveys might be arranged by year, and the vital signs by type of cancer:

{pmore}{cmd:. docs @teensmoking (1970 1975 1978)} {it:other optional specs} 

{pmore}{cmd:. docs @cancervitals (lung skin toenail)} {it:other optional specs} 

{pmore}The available dataset names within each set of documemtation are listed in {cmd:help docs} {it:docname}.

{pstd}{ul:{bf:3. Variables}}

{pmore}There are three possible ways to specify the variables of interest: variable name, variable index (that is, the position of the variable within the dataset), or by another {bf:key} that may be provided by the documentation.
Each of the three can be specified as a {help docs##lists:list} {help docs##lists:(see below)}; however, {it:keyterms} can include wildcards but not ranges. For example:

{phang2}Using variable name:{break}
{cmd:. docs name age birthdate} {it:other optional specs}

{phang2}Using variable index:{break}
{cmd:. docs 1 5 23} {it:other optional specs}{break}

{phang2}Using a {bf:key} (with the syntax {it:keyname}{cmd::}{it:keyterms}):{break}
{cmd:. docs sensitivity: private restricted open} {it:other optional specs}

{pstd}{ul:{bf:4. Metadata}}

{pmore}The information to retrieve for each data element is specified as a series of options. Suppose that for some dataset, every variable had a documented source, percentage missing, and supplemental comments. 
The defined names for these bits of metadata could be: {cmdab:s:ource}, {cmdab:m:issing}, and {cmdab:c:omments}.
Then you could retrieve them with, e.g.:

{pmore}{cmd:. docs} {it:other optional specs} {cmd:, source} 

{pmore}{cmd:. docs} {it:other optional specs} {cmd:, missing} 

{pmore}{cmd:. docs} {it:other optional specs} {cmd:, so miss com} 

{pmore}All the option names can be abbreviated, so long as the abbreviation does not conflict with one of the main {cmd:docs} options.

{pmore}The metadata options for each {it:docname} are listed in {cmd:help docs }{it:docname}, and are also output after every {cmd:docs} command.

{pstd}{ul:{bf:Optional Specifications}}

{pmore}All four types of specifiers (ie, documentation, datasets, variables, metadata) are optional; {cmd:docs} can be invoked with any combination or none at all.
Any element that is omitted is carried over from the most recent relevant invocation; in other words, only the elements that you want to change need to be specified. 

{pmore}For example:

{p2colset 9 37 37 2}
{p2col:{cmd:. docs var1-var5}}changes only the variables

{p2col:{cmd:. docs, label definition}}changes only the metadata

{p2col:{cmd:. docs @teensmoking}}uses the datasets, variables, and metadata chosen the last time the command was run with the {cmd:teensmoking} documentation

{p2col:{cmd:. docs}}re-runs the command exactly as it ran the last time.

{pmore}All elements are remembered permanently, across Stata sessions.

{pstd}{ul:{bf:Lists}}{marker lists}

{pmore}Datasets and variables can be specified in a manner similar to a Stata {varlist}, though with more flexibility since variables may not be present or ordered consistently across datasets.

{pmore}Abbreviations and wildcards ({cmd:*}, {cmd:?}, and {cmd:~}) work in the standard way.

{pmore}Ranges can be specified in two distinct ways. First, similarly to a {varlist},  as all items between two endpoints. For example:

{pmore2}{cmd:. docs (ds1-ds3) varA-varZ}

{pmore2}Unlike a {varlist}, the endpoints can be listed in either order, and the indivdual terms can include wildcards. E.g.:

{pmore2}{cmd:. docs (ds3-ds1) *A-var?}

{pmore2}When a wildcard is included, the most extreme member(s) of the specfied set are used as the endpoint(s).

{pmore}The second way to specify a range is as {bf:extensions} around one or more anchor items. The syntax would be:

{pmore3}{it:anchor}[{it:ext1}][{it:ext2}]

{pmore2}where {it:anchor} can include wildcards, and {it:ext1} and {it:ext2} are of the form

{pmore3}{{cmd:<}|{cmd:>}}{it:#}

{pmore2}where {it:#} indicates how many variables/datasets before ({cmd:<}) and/or after ({cmd:>}) the {it:anchor} to include. For example:

{p2colset 12 30 30 2}
{p2col:{cmd:. docs varA>1}}specifies {cmd:varA} and the variable after varA - whatever that may be in the different datsets.

{p2col:{cmd:. docs varA>3<3}}specifies all variables within 3 of {cmd:varA}. 

{p2col:{cmd:. docs varA>3>6}}specifies the variables from 3 to 6 after {cmd:varA}. {cmd:varA} itself would not be included.

{p2col:{cmd:. docs var*>2}}specfies all variables starting with {cmd:var}, and for each of those, the following two variables.

{title:Options}

{phang}{it:metadata} options are specific to each {it:docname}. They should be documented in:{break} {cmd:help docs} {it:docname}, and are also listed after every {cmd:docs} command.

{phang}{opt none} restricts normal output to dataset, index, and variable names only. 

{phang}{opt search(terms)} searches for any of the included {it:terms} (which may include the usual wildcards) in the information that would otherwise be displayed. 
That is, it searches dataset and variable names, and metadata selected with {it:info-options}; it does {bf:not} search metadata that has not been selected with an {it:info-option}.

{pmore}If {it:item} is taken to be all information about a specific variable in a specific dataset, only {it:item}s in which a search {it:term} is found are displayed, and all {it:terms} found are highlighted.

{phang}{opt sxs} switches the output from the usual sequential paragraphs to a side-by-side display in which variables are aligned across columns (where possible),
and variables with the same names in different positions are indicated with up- and down- arrows. This can be useful for comparing among datasets included in a documentation.
At the moment, only variable names are included in the output.

{phang}{opt nomem:ory} is intended mainly for automated use: one bit of documentation can link to and display another bit, without disrupting the user-set choices.

{title:Also see}

{pstd}Contact: {browse "mailto:elliott.lowy@va.gov":Elliott Lowy}