[U] User's Guide

Technical note[ U ] 18.11 Ado-files 247You do not have to go to all the trouble we did to program the FVARATIO measure of influence orany other statistic that appeals to you. Whereas version 1 was not really an acceptable solution—itwas too specialized—version 2 was acceptable. Version 3 was better, and version 4 better yet, butthe improvements were of less and less importance.Putting aside the details of Stata’s language, you should understand that final versions of programsdo not just happen—they are the results of drafts that have been refined. How much refinementdepends on how often and who will be using the program. In this sense, the “official” ado-files thatcome with Stata are poor examples. They have been subject to substantial refinement because theywill be used by strangers with no knowledge of how the code works. When writing programs foryourself, you may want to stop refining at an earlier draft.18.11.6 Writing online helpWhen you write an ado-file, you should also write a help file to go with it. This file is astandard ASCII text file, named command.sthlp, that you place in the same directory as your ado-filecommand.ado. This way, when users type help followed by the name of your new command (orpulls down Help), they will see something better than “help for . . . not found”.You can obtain examples of help files by examining the .sthlp files in the official ado-directory;type “sysdir” and look in the lettered subdirectories of the directory defined as BASE:. sysdirSTATA:UPDATES:BASE:SITE:PLUS:PERSONAL:OLDPLACE:C:\Program Files\Stata11\C:\Program Files\Stata11\ado\updates\C:\Program Files\Stata11\ado\base\C:\Program Files\Stata11\ado\site\C:\ado\plus\C:\ado\personal\C:\ado\Here you would find examples of .sthlp files in the a, b, . . . subdirectories of C:\ProgramFiles\Stata11\ado\base.Help files are physically written on the disk in ASCII text format, but their contents are StataMarkup and Control Language (SMCL). For the most part, you can ignore that. If the file contains aline that readsAlso see help for the finishup commandit will display in just that way. However, SMCL contains many special directives, so that if the linein the file were to readAlso see {hi:help} for the {help finishup} commandwhat would be displayed would beAlso see help for the finishup commandand moreover, finishup would appear as a hypertext link, meaning that if users clicked on it, theywould see help on finishup.