macro help

[tomrvincent]

A lot of times people who write macros have lots of comments and instructions in the text of the macro. I'd like to propose a way of showing those comments within a SAS session.  This would especially be handy when the original code file isn't available or convenient.

%macro foobar(a=,b=);

%help to run foobar, supply a, a date field, and b, a numeric field: %foobar(a=bdate,b=anum).  This will return something wonderful;

(body of macro)

%mend foobar;

So, in SAS you could run %foobar /help or %foobar(help) (or something like that); and it would display the help message.

[FreelanceReinh]

Easily accessible usage instructions (not only for macros) are indeed very helpful. With a bit more work on the part of the macro developer, this functionality could be implemented using common macro programming techniques. However, the exact syntax to retrieve the help text would depend on the particular implementation.

Another approach with existing SAS features are abbreviations in the Enhanced Editor:

Menu Tools --> Add Abbreviation...

Now, if the user enters %foobar in the Enhanced Editor, part of the help text will be displayed:

By pressing Return, the complete text will be inserted. It's even possible to move the cursor automatically to the position after the equals sign where the first parameter is to be entered: see a recent post about Keyboard macros and Abbreviations.

[tomrvincent]

That would require a lot of manual effort...each person would have to do that, right?  We've got a library of dozens of macros, so that wouldn't be practical at all.

[FreelanceReinh]

---

@tomrvincent wrote:

That would require a lot of manual effort...each person would have to do that, right?

---

Not necessarily. Keyboard macros (including those abbreviations) can be exported to a .kmf file. So, once created, this .kmf file could be distributed to all users. The import is easy.

[Quentin]

I'm not opposed to this, but have a few thoughts...

It's possible to do this now, by convention.  For example you can define a standard HELP parameter in your macros, something like:

%macro foobar(a=,b=,help=);

%if &help=1 %then %do;
  %put %nrstr(
  %help to run foobar, supply a, a date field, and b, a numeric field: 
  %foobar(a=bdate,b=anum).  This will return something wonderful;
  );
  %return;
%end;

(body of macro)

%mend foobar;

In EG, if you put comments in your parameter definitions they are displayed by the autocomplete tip thing, which is handy.  Assume SAS studio will show them as well.

If SAS were going to implement this maybe it could be done like the /des option, so that the help information is saved in the macro catalog entry?  Maybe until then, /des could be useful for this sort of info? I've never used /des.

Another option would be to write a %help(macroname) macro.  So you call %help(mymac), and it looks in the macro catalog to find the entry for mymac, and prints out the text stored in /des.  Or for autocall macros, it could look up the file with the macro definition , and parse that to get the help info.

If you can force colleagues to agree on a standard comment block header for macro definitions, then you can write code to extract the information about each macro as metadata.  One you have that metadata in a dataset, you can build documentation, or just make it available to people to query. I did a poster about that approach: https://www.lexjansen.com/nesug/nesug04/po/po04.pdf.

[ballardw]

Note that SAS actually includes examples of this in several places. The easiest for me to remember are the macros used for annotating graphics:

%annomac; For traditional graphics. At the end of the log where the macros are compiled you see something similar to:

*** ANNOTATE macros are now available ***

 For further information on ANNOTATE macros, enter,
    %HELPANO(macroname), (for specific macros)
    %HELPANO(ALL), (for information on all macros)
 or %HELPANO (for a list of macro names)

%sganno; for the SG annotate macros the log also shows this:

Following macros are available

     %SGANNO_HELP
     %SGARROW
     %SGIMAGE
     %SGLINE
     %SGOVAL
     %SGPOLYCONT
     %SGPOLYGON
     %SGPOLYLINE
     %SGRECTANGLE
     %SGTEXT
     %SGTEXTCONT

 Enter %SGANNO_HELP(macroname) for details on each SGANNO macro,
    or %SGANNO_HELP(ALL) for details on all SGANNO macros.

The actual source code for all of this should appear in your install. So you can dissect and use as needed if you need something like this. Otherwise it's a fairly trivial programming exercise as long as you use keyword parameter passing and not positional which would complain about missing parameters as @Quentin shows.

[tomrvincent]

I was looking for something more generic/universal.  That's why I suggested the %help(foobar) or %foobar /help or %foobar(help) structure...something like the keyword mouseover with EG (which would also be a nice alternative).