Finding possible prefix arguments

Question

Emacs is aweseome but sometimes it feels it's too smart for its own good. You may feel you learned everything there's to know about a function and then someone tells you to try a prefix argument and suddenly it does something you never knew about.

For example - you can jump to Magit without opening a project, by calling magit-status with 2 prefix arguments (it will prompt you with a "choose directory" dialog) - I just learned that

So my question is: Is it possible to build a list of functions that take prefix arguments and for each row grab the description (maybe from describe-function) that explains what calling the function with a prefix would do?

Answer 1

Here is one way to get the functions that mention prefix in the doc string. This saves the output to a file

(with-temp-file "prefix-cmds.org"
  (loop for cmd-name in smex-ido-cache
    do
    (let* ((cmd (intern cmd-name))
           (doc (documentation cmd)))
      (when (and doc (string-match "prefix" doc))
        (insert
         (format "** %s\n\n%s\n\n"
             cmd
             (org-escape-code-in-string doc)))))))

This misses any function that doesn't specifically call it a prefix, e.g. a universal argument, or prfix, etc... You might catch those with a better string match. It is also limited to functions in smex-ido-cache, but that is what counsel-M-x uses, so I assume it is not missing any. Maybe there is a better way to get a full list of interactive commands.

Still, this listed 1457 commands for me!

Answer 2

1. A list of all commands "that take prefix arguments" means a list of all commands.

2. If you instead mean a list of only those commands whose doc mentions prefix-argument behavior then you need to search command doc strings.

   • An easy way to do this is to use command apropos-documentation, which is bound to C-h d. Give it the regexp prefix[- ]+arg, for example. And yes, use C-u if you have not customized apropos-do-all to non-nil (which I recommend).

      apropos-documentation is an interactive autoloaded compiled Lisp
      function in `apropos.el'.
     
      It is bound to C-h d, f1 d, help d, C-h M-a, f1 M-a, help M-a,
      menu-bar help-menu apropos apropos-doc, menu-bar help-menu
      search-documentation search-documentation-strings.
     
      (apropos-documentation PATTERN &optional DO-ALL)
     
      Show symbols whose documentation contains matches for PATTERN.
      PATTERN can be a word, a list of words (separated by spaces),
      or a regexp (using some regexp special characters).  If it is a word,
      search for matches for that word as a substring.  If it is a list of words,
      search for matches for any two (or more) of those words.
     
      Note that by default this command only searches in the file specified by
      `internal-doc-file-name'; i.e., the etc/DOC file.  With C-u prefix,
      or if `apropos-do-all' is non-nil, it searches all currently defined
      documentation strings.
     
      Returns list of symbols and documentation found.
     

     See the Emacs manual, node Apropos, for more information.

   • Another easy way to do this is to use Icicles command icicle-fundoc.