6

Is there a way to do a lazy find/search within EMACS, for commands using their description?

Something in the lines of:

  • Say I am looking for how to add indent to org mode
  • I suspect there is a commands for it
  • I would like to type "org" and "indent" in any order and get some options/help buffer, based on the documentation as well as the actual commands.

In other words, I would like for emacs to suggest options/help, based on my description/keywords

This would come in handy, how can I do this?

P.S

I am a NOOB!

  • 1
    Maybe apropos-command is what you're looking for. It's bound to C-h a by default. – DoMiNeLa10 Dec 28 '17 at 12:19
  • Personally, I use helm-info-elisp, but I don't think there's a single answer for this one. – Felipe Lema Dec 28 '17 at 13:10
5

One way you can try to find such commands is to use C-h a. In vanilla Emacs this is bound to apropos-command.

For C-h a you can input words to match in the command documentation - e.g., org and indent.

C-h a org indent

This is the kind of output you get:

Type RET on an entry to view its full documentation.

org-indent-line (750)         M-x ... RET
   Indent line depending on context.
org-indent-mode (680)         M-x ... RET
   When active, indent text according to outline structure.
org-return-indent (671)       M-x ... RET
   Goto next table row or insert a newline and indent.
org-indent-region (654)       M-x ... RET
   Indent each non-blank line in the region.
org-unindent-buffer (647)     M-x ... RET
   Un-indent the visible part of the buffer.
org-indent-item (582)         M-x ... RET
   Indent a local list item, but not its children.
org-indent-block (579)        M-x ... RET
   Indent the block at point.
org-indent-drawer (573)       M-x ... RET
   Indent the drawer at point.
org-delete-indentation (567)  M-x ... RET
   Join current line to previous and fix whitespace at join.
org-indent-item-tree (564)    M-x ... RET
   Indent a local list item including its children.
org-indent-to-column (564)    M-x ... RET
   Indent from point with tabs and spaces until COLUMN is reached.
org-cdlatex-environment-indent (490)  M-x ... RET
   Execute `cdlatex-environment' and indent the inserted environment.

However, your question asks how to match against command descriptions, not just command names. C-h a cannot help with that - it matches only against command names.


If you use Icicles then you can match against command descriptions, i.e., doc strings.

There are several Icicles apropos commands, which can help.

You can see information about commands and other things by matching patterns incrementally: change your current minibuffer input and the set of matches changes accordingly.

In this case, you don't have a good idea about the command name, and you want to find a command whose doc string matches one or more patterns (e.g. regexps) - e.g., two simple patterns: org and indent.

Multi-command icicle-fundoc prompts you for a 2-part, multi-completion input.

  • The first part is a pattern that matches the name of a function

  • The second part is a pattern that matches its documentation.

If you use C-$ during completion it toggles between all functions and just commands (interactive functions).

To match both org and indent in either order, you can use progressive completion.

You use C-M-j to separate the parts of your input.

Summary:

  1. M-x icicle-fundoc

  2. C-$ - match only commands.

  3. At the prompt:

    • .* - you don't know what the command names are (or use org.* if you know the name contains org, or use ^org.* if you it starts with org)
    • C-M-j
    • .*[iI]ndent - match indent or Indent in the doc
    • S-SPC - to provide another pattern
    • .*org - and match org

In my Emacs that shows these 12 completion candidates:

org-cdlatex-environment-indent
Execute ‘cdlatex-environment’ and indent the inserted environment.

ENVIRONMENT and ITEM are passed to ‘cdlatex-environment’.

The inserted environment is indented to current indentation
unless point is at the beginning of the line, in which the
environment remains unintended.

org-indent-block
Indent the block at point.

org-indent-drawer
Indent the drawer at point.

org-indent-item
Indent a local list item, but not its children.
If a region is active, all items inside will be moved.

org-indent-item-tree
Indent a local list item including its children.
If a region is active, all items inside will be moved.

org-indent-line
Indent line depending on context.

Indentation is done according to the following rules:

 - Footnote definitions, diary sexps, headlines and inline tasks
   have to start at column 0.

 - On the very first line of an element, consider, in order, the
   next rules until one matches:

   1. If there’s a sibling element before, ignoring footnote
      definitions and inline tasks, indent like its first line.

   2. If element has a parent, indent like its contents.  More
      precisely, if parent is an item, indent after the
      description part, if any, or the bullet (see
      ‘org-list-description-max-indent’).  Else, indent like
      parent’s first line.

   3. Otherwise, indent relatively to current level, if
      ‘org-adapt-indentation’ is non-nil, or to left margin.

 - On a blank line at the end of an element, indent according to
   the type of the element.  More precisely

   1. If element is a plain list, an item, or a footnote
      definition, indent like the very last element within.

   2. If element is a paragraph, indent like its last non blank
      line.

   3. Otherwise, indent like its very first line.

 - In the code part of a source block, use language major mode
   to indent current line if ‘org-src-tab-acts-natively’ is
   non-nil.  If it is nil, do nothing.

 - Otherwise, indent like the first non-blank line above.

 The function doesn’t indent an item as it could break the whole
 list structure.  Instead, use ‘<M-S-left>’ or ‘<M-S-right>’.

 Also align node properties according to ‘org-property-format’.

org-indent-mode
When active, indent text according to outline structure.

Internally this works by adding ‘line-prefix’ and ‘wrap-prefix’
properties, after each buffer modification, on the modified zone.

The process is synchronous.  Though, initial indentation of
buffer, which can take a few seconds on large buffers, is done
during idle time.

org-list-repair
Fix indentation, bullets and checkboxes in the list at point.

org-return-indent
Goto next table row or insert a newline and indent.
Calls ‘org-table-next-row’ or ‘newline-and-indent’, depending on
context.  See the individual commands for more information.

org-unindent-buffer
Un-indent the visible part of the buffer.
Relative indentation (between items, inside blocks, etc.) isn’t
modified.

You can continue to use S-SPC to enter other patterns to match, to narrow the list of candidates.


  • Why did C-h a list also command org-delete-indentation, but it is missing from the list of Icicles candidates? Because we didn't try to match indent also in the command name, and indent is missing from that doc string.

  • Why is command org-list-repair included among the Icicles candidates but missing from the output of C-h a? Because it contains indent only in the doc string, not in the command name. C-h a does not match against doc.

With Icicles you can match anything in the command name or the doc string, or both. With apropos-command you can match only against the command name.

  • It feels like what you are saying might be the one I want. All I need to do is M-x package-install icicles and I should be ready to go after that right? I am noob, sorry. Also from what you said, it appears that I have to toggle between the different results, I don't get to see everything in a buffer, right? – Thej Kiran Dec 29 '17 at 17:39
  • Download the files from EmacsWiki (the files on MELPA are out-of-date). Put the files in a directory in your load-path. Add (require 'icicles) to your init file. Turn on Icicle mode (e.g., (icy-mode 1) in your init file, or use M-x icy-mode). Dunno what you mean by toggle between the results. The results are matches for your minibuffer input. You can choose one, to see it in buffer *Help*, or you can just hit C-g to cancel. icicle-fundoc is a help command - it shows you function+doc matching your input. – Drew Dec 29 '17 at 17:54
1

The closest thing to that might be <M-x describe-bindings> which is generally mapped to <C-h b>. Then you can switch to that window <C-x o> and search <C-s> for the bindings available in whatever modes you have set for the given buffer.

In addition, the way I've been learning comes from the way Spacemacs does it. I'm no longer actually using Spacemacs but it bundles a package called which-key: https://github.com/justbur/emacs-which-key which will do exactly what you described which is provide a keybind and a brief description. So if you key <C-x> for example, it will put up a window with all the possible following combinations with a brief description of what it will do. I'm still using it in my current configuration and find it very helpful.

  • I am afraid maybe what I am saying is not clear. I want to type keywords (that might be in the description or the actual command). For example, I want to know how to toggle my todos using key bindings. I would want to type "Toggle TODO" and expect to get the correct keybinding for it. What you are saying seems to me like something that shows a list of commands based on my first input. I wouldn't know where to start for "Toggle TODO". Get me? – Thej Kiran Dec 29 '17 at 17:31
  • 1
    In that case maybe the answer by @Drew is a little more helpful. Beyond that the only other thing I can think of that is close is <M-x describe-bindings> which is generally mapped to <C-h b>. Then you can switch to that window <C-x o> and search <C-s> for the bindings available in whatever modes you have set for the given buffer. – Ricky Nelson Dec 30 '17 at 4:15
  • `C-h b' is really good with my initial tests. I will test it out over the next few days and mark as answer if applicable. Some commands have no key binding set in the beginning, right? Then it becomes a problem. Can you still please update your answer? Thanks. – Thej Kiran Dec 31 '17 at 16:45
0

There is a built-in command that more or less does what you want called apropos-documentation, bound by default to C-h d. Here's its documentation:

(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.

A couple of points here:

  • Unless you're explicitly searching for something you know is built in to Emacs, you probably want to call this as C-u C-h d or set the variable apropos-do-all. (That is, the etc/DOC file referred to above appears to contain the pre-compiled docstrings for all functions defined in Emacs itself.)

  • The docs don't say it, but if you use multiple words, those words may appear in any order, but must be on the same line. When I tried searching for "org indent", for example, I didn't pull up org-cycle, in which both words appear but on separate lines.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.