What do I need to know sharing dialog boxes and menus?

Sharing submenus and dialog boxes

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 user-written 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.

Proposed "ground rules"

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 user-written 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 new program name.ado should provide name.hlp for a shared package to be acceptable and for "ownership" of name.ado and name.hlp to be obtained.

  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.

• In the absence of name.dlg by the original author of name.ado, anyone else is entitled to post name.dlg and claim "ownership" of it. When possible, it is considered good practice to consult with the original author of name.ado , but consultation is not absolutely required. Consultation likely would consist of determining whether the original author has a dialog under development, is planning to develop a dialog, would like to coauthor a dialog, would be willing to help test and debug your dialog, will allow you to add your dialog to the original author's package, or perhaps, would simply be pleased to learn that someone else has taken on the burden of writing a dialog. In addition, consultation would establish a relationship that could facilitate a dialog update should the original program be updated. The consultation could also be used to arrange to have the original author add, or give you permission to add, text to the help file that links to the dialog. If the dialog is placed in a separate package, then a sentence might be added to the 'abstract' of the original program submission saying something like, "A dialog for this command is available in package name_dialog (ssc describe name_dialog)." A name.dlg by a different author must be placed in a separate package unless permission is obtained to add the dialog to the existing package. Nonetheless, getting permission to place the dialog in the original package is the preferred approach.
• Should the original author or, indeed, anyone else subsequently write another name.dlg, the parties should ideally agree on either different names for different files or withdraw one in favor of the other. If the parties fail to agree, a name.dlg already on the SSC archive or in the Stata Journal takes precedence over the new name.dlg, and the new name.dlg must be renamed to be posted.
• At their discretion, authors may choose an alternative name for a dialog-box program for an existing name.ado. A suggested alternative naming format is name_xxx.dlg, where xxx is the author's initials. This approach should be reserved, though, for situations where there is an existing name .dlg or where consultation failed to yield the cooperative use of the preferred dialog name.
• It is also considered good practice for submissions that include a dialog-box program to also include a suggested window menu append item ... command for creating a menu item. For a submission of a single dialog, this would best be done via initial comments in the dialog-box program itself. For submissions of multiple dialogs and a connecting submenu, a plain text file or a Stata .h lp help file containing a suggested window menu append submenu ... command for creating the submenu and the suggested window menu append item ... commands for creating the menu items should be provided.
  

Statistical Software Components (SSC) archive

Recommendation 4

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 user-written 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.

Prev    1    2    3    4