Every User Language Program should contain information about its function, how to use it and maybe who wrote it.
The directive
#usage text [, text...]
implements a standard way to make this information available.

If the #usage directive is present, its text (which has to be a string constant) will be used in the Control Panel to display a description of the program.

In case the ULP needs to use this information in, for example, a dlgMessageBox(), the text is available to the program through the builtin constant usage.

Only the #usage directive of the main program file (that is the one started with the RUN command) will take effect. Therefore pure include files can (and should!) also have #usage directives of their own.

It is best to have the #usage directive at the beginning of the file, so that the Control Panel doesn't have to parse all the rest of the text when looking for the information to display.

If the usage information shall be made available in several langauges, the texts of the individual languages have to be separated by commas. Each of these texts has to start with the two letter code of the respective language (as delivered by the language() function), followed by a colon and any number of blanks. If no suitable text is found for the language used on the actual system, the first given text will be used (this one should generally be English in order to make the program accessible to the largest number of users).


#usage "en: A sample ULP\n"
           "Implements an example that shows how to use the EAGLE User Language\n"
           "Usage: RUN sample.ulp\n"
           "Author: john@home.org",
       "de: Beispiel eines ULPs\n"
           "Implementiert ein Beispiel das zeigt, wie man die EAGLE User Language benutzt\n"
           "Aufruf: RUN sample.ulp\n"
           "Author: john@home.org"

Index Copyright © 2005 CadSoft Computer GmbH