|Sharing dialogs (part 4)—Submenus and dialogs
|T. J. Steichen
The menus and dialog boxes introduced in Stata 8 added a new layer of complexity to the sharing of Stata-related resources. The defunct Stata Technical Bulletin (STB), the current Stata Journal (SJ), and the Statistical Software Components (SSC) archive hosted by the Boston College Department of Economics, as well as a number of user- and organization-specific archive sites, provide a rich and extensive selection of community-contributed Stata programs and their help files. A number of these programs were made available by authors who no longer are active in the Stata community or who no longer can or wish to provide continued support or needed updates. For many users, having access to these programs via dialog boxes in the Stata menu system would be of real value. Nonetheless, a dialog-box program may never be provided by the original author.
Further, there are useful programs that are clearly a part of a package of related programs that deserve to have a common dialog design and, logically, need to be placed in a single submenu. Nonetheless, it seems almost certain that the authors of some of these programs will never attempt to create a dialog box.
So how do we make dialogs and submenus of related commands available in this situation?
The next section proposes a set of "ground rules" and suggestions for "ownership" of dialog file names. The words "rules" and "ownership" are used very loosely here; you should not assume their most strict interpretations.
The rules for "ownership" of .dlg filenames should be consistent with the generally accepted rules for "ownership" of names of shared .ado and related .hlp files, as defined by the practices of the Stata Technical Bulletin (STB), the Stata Journal (SJ), the Statistical Software Components (SSC) archive, and StataCorp. In large part, these rules give ownership of name to the author who first submits name.ado to the Stata Journal or to the SSC archive. Ownership of name.hlp is implicitly assumed, as it is considered unacceptable to submit a program file without a help file. Nonetheless, StataCorp reserves the right to adopt any name, "owned" or not, for an official Stata command and recommends that proper words not be used for community-contributed program names.
The question of who should "own" name.dlg is not so clear, but there is value to the user in having a dialog-box program for name.ado be called name.dlg. This arises because it is possible to invoke name.dlg directly from the Stata command line via command db name. Having a dialog with the same name as the program is clearly easier to remember. Nonetheless, a dialog invoked from the menu system does not need to have the same name as the program being requested, and it is possible to use an alternative name for the dialog box program.
With these thoughts in mind (but subject to StataCorp's preemptive rights), the following "rules" are proposed:
The author of name.ado may, at their discretion, also provide name.dlg as part of the same package and claim "ownership" of name.dlg.
SSC submissions of dialog box programs or collections of dialogs that are not a part of a new package or an update of an existing package should be submitted as a separate package containing the informative word "dialog" as part of their package name. An included help or text file of menu construction-related commands should be named consistent with the package name: (for example, meta_dialog.hlp or meta_dialog.txt in package metadialog.)
The SSC archive is the generally accepted and primary public storage mechanism for shared community-contributed Stata-related contributions. Submissions of dialog box programs that are not included as part of a new package or as an update of an existing package should be submitted as a separate package, as should collections of dialogs intended as part of a submenu of related commands.
Such a submission should contain the informative word "dialog" as part of its submission name. For example, the dialog used as an example throughout this FAQ, galbr.dlg, was part of a package of related dialogs all pertaining to meta-analysis; the package name was metadialog. Had the dialog been submitted as a standalone file, an informative name would have been galbr_dialog.
Consistent with this philosophy of informative names, we recommend the optional help file or plain text file included with the submission to provide suggested menu item and submenu creation commands (see "rule" 5, in section 3.1 above) be named consistently with the package name. For example, the help file included with package metadialog was called meta_dialog.hlp. If a plain-text file had been included instead, it would have been called meta_dialog.txt. This naming convention is especially important for plain-text files because the findit, ssc, and underlying net commands of Stata (the available tools for automatic installation of packages) will install such text files in your "current directory", whic h is where data files are stored, not program-related .ado, .hlp, or .dlg files. The logic behind this location is that most ancillary files included with packages are sample datasets to be used for testing features of a submitted command. Generally, any file that is not a program, help or dialog file (i.e., not an .ado, .hlp, or .dlg file) is considered ancillary.
Because help files are stored in the same directory as the dialog files, they are much easier to locate and are accessible from within Stata. For these reasons, a help file is preferred over a plain text file. Regardless of which format is chosen, informatively named text files will greatly assist the user in associating these optional files with the package to which they belongs.