Emacs-Lisp mode indentation problem when doc string contains left parenthesis in first column

Question

Usually when I write Lisp code (in an Emacs-Lisp mode buffer), I can press TAB (bound to indent-for-tab-command) to indent code properly. However, if I write a defun with a docstring (longer than one line) that also contains a left parenthesis (in the first column), TAB stops working for the given defun. For example:

(defun test ()
  "Hello
(ok) xxx."

nil)

If I put cursor on n in nil and press TAB I would expect nil to be indented 2 places, but it does not work ( unless I remove the left parenthesis ( from the first column on the second line of the docstring).

I am using Emacs 25.1 on Ubuntu 16.04.

Answer 1

TLDR (setq open-paren-in-column-0-is-defun-start nil)

The docstring for indent-for-tab-command tells us it calls the function in variable indent-line-function. In emacs-lisp mode this is lisp-indent-line, defined in lisp-mode.el. We can see in the source code that it calls calculate-lisp-indent. M-x traceing these two functions, both with and without the offending ( at first col and looking at calculate-lisp-indent source code, I saw the call to beginning-of-defun. Tried with with M-: (beginning-of-defun) w/ and w/o the ( in first col showed this was relevant. Then the docstring says:

beginning-of-defun is an interactive compiled Lisp function in `lisp.el'.

[...]

When `open-paren-in-column-0-is-defun-start' is non-nil, a defun is assumed to start where there is a char with open-parenthesis syntax at the beginning of a line.

I suspect beginning-of-defun to at least be slower then.

EDIT: as found at by @Häkon Hægland this is actually discussed in Chapter 26.2.1 : Left Margin Convention of the Emacs manual.