Stata 15 help for keyfiles

Title

[P] keyfiles -- Key files used by the search command

Description

The search command examines a keyword database found in "key" files to determine matches while doing a "local" search (that is, the local option of search); see [R] search. Below we provide a description of key files.

Remarks

Remarks are presented under the following headings:

Introduction Key file structure Help, browser, and net links within key files Highlighting text

Introduction

These key files provide the keywords for official Stata commands, undocumented help files, NetCourses, Stata Press books, FAQs posted on the Stata website, selected articles on StataCorp's official blog, selected community-contributed FAQs and examples, and the articles in the Stata Journal and the Stata Technical Bulletin.

Updates to Stata's key files are provided on a regular basis. Use the update command (see [R] update) to obtain the latest Stata updates, or simply click here.

Additionally, the key files site.key and user.key, if present, are also examined by search. These two key files may be used to store keywords for additional items of interest to a user. The results from searching the stata#.key files are presented first, followed by the results from searching site.key (if available), and then by the results from searching user.key (if available).

Stata looks along the adopath to find these files; see [P] sysdir. The stata#.key files are located in the BASE directory. The site.key and user.key files would typically be placed in the SITE, PERSONAL, or PLUS directories depending upon the source of the files.

Key file structure

Key files are text files. Entries in a key file are separated by one or more blank lines. Each line of an entry begins with a period (.) followed by one of the letters: c, e, t, o, a, k, z, or x, followed by one or more spaces, followed by information appropriate for the particular key file directive. The following table and discussion outline what these directives are used for within key files.

+-------------------------------------------+ | Directive | Description | |-----------+-------------------------------| | .c | Class | | .e | Entry name | | .t | Title | | .o | Help | | .a | Author | | .k | Keywords | | .z | Mark as historic | | .x | As is text on following lines | +-------------------------------------------+

.c lines indicate the entry class. While any word may follow a .c line, certain words have special meaning to Stata. manual indicates an official Stata command; faq indicates a FAQ; sj and stb are treated as synonyms and indicate Stata Journal and STB; and error indicates error code.

Examples:

.c manual

.c faq

.c whatever

There should be only one .c line in an entry.

The faq option of search limits the search to entries that have a .c faq line. The manual option of search limits the search to entries with a .c manual line. The sj option of search limits the search to entries with a .c sj or .c stb line.

search has an undocumented option class(classname) that allows you to restrict your search to those entries having classname as their class. For instance

. search ... , class(foo)

would restrict the search to key-file entries that had

.c foo

lines.

.e lines provide the entry name. The text that follows the .e is displayed on the left side of the first line of output. The first "word" of text following the .e is displayed to the far left of the output, and the remaining words, if any, are displayed starting at the first tab stop.

Examples:

.e [R] regress

.e FAQ

.e SJ-2-4 pr0007

There should be only one .e line in an entry.

After displaying the .e information, the title (see the .t directive below) is presented to the far right on the first line, with repeated periods and spaces between the entry name and the title.

.t lines provide a title. The title is presented on the far right of the first line displayed; see the discussion of the .e directive above.

Examples:

.t Linear regression

.t Calculating power by simulation

There should be only one .t line in an entry.

.o lines are used to provide links to help files. When a .o line is present, the second line of output has "(help " followed by whatever follows the .o followed by ")" placed at the first tab stop. A link to the help file is created if the word is enclosed in @; see the section titled Help, browser, and net links within key files below.

Examples:

.o @regress@

.o @help@, @search@, @viewer@

.o @clustergram@ if installed

There should be only one .o line in an entry.

.a lines indicate the author or authors. This information is presented on the far right of the second line displayed, with repeated periods and spaces preceding it. .o (see above) and .a information are both presented on the same line. The .o information on the left, and the .a information on the right.

Examples:

.a D. W. Hosmer

.a N. J. Cox and C. F. Baum

There should be only one .a line in an entry.

.k lines provide the keywords for the entry. Hyphens indicate the minimum allowed abbreviations for matching against keywords. Multiple .k lines are allowed, and one or more keywords may be specified per line.

Examples:

.k stat-istics mean-s med-ians

.k data-sets set-s manage-ment

Certain keywords are used to restrict the context of the search; see searchadvice for details.

To provide consistent abbreviations, pick your keywords, search for each keyword, and then examine some of the entries it finds and use the same length of abbreviation.

.z indicates that the entry is only of historic interest, and should not be presented. Entries marked with a .z are only presented when the historical option is specified with search.

.x indicates that the lines that follow are to be presented "as is" after the information displayed by the .e, .t, .o, and .a directives.

Help, browser, and net links within key files

The key files currently do not use smcl. Instead, key files use @ to indicate links. For example, @regress@ creates a link to regress.sthlp.

@browser:http://www.stata.com/!http://www.stata.com/@ creates a link to the http://www.stata.com/ webpage. The ! in the middle is required. @browser:http://www.stata.com/!click here@ creates the same link, but the words "click here" will be shown as the link instead of http://www.stata.com/.

@net:sj 2-1 st0005!st0005@ produces a link that executes the net command. Here the link points to the st0005 entry of Stata Journal 2-1. The text that will appear will be "st0005", because it follows the !.

Highlighting text

To highlight text, enclose it in ^. For instance, ^hello^ will make the word "hello" appear highlighted.

Example

Here is an example of an entry for a FAQ.

.e FAQ .c faq .t My FAQ title .a S. Body .k stat-istics what-ever ever .k test-s test-ing .x 1/03 How do you do whatever? @browser:http://www.z/wever.html!http://www.z/wever.html@

What the user will see when they type search whatever is

FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . My FAQ title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . S. Body 1/03 How do you do whatever? http://www.z/wever.html


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