[PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Bart Van Assche]

For new kernel developers who use emacs it is tedious to follow the
instructions in Documentation/process/coding-style.rst for configuring
emacs. Make it easier for emacs users by moving these settings into the
top-level .dir-locals.el file. Emacs supports directory-local variables
since version 23.1, released in 2009. See also
https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.html

The settings in .dir-locals.el are not identical to those in
Documentation/process/coding-style.rst. The most important difference
is that "(arglist-cont-nonempty c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only)" (which is not a valid alist) has been
changed into "(arglist-cont-nonempty . c-lineup-arglist)". I have
verified with several large and nontrivial kernel source files that
the settings in .dir-locals.el format code according to what checkpatch
expects.

The Italian and Chinese translations of the modified paragraphs have
been generated by Google Translate.

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
Cc: Geyslan G. Bem <geyslan@gmail.com>
Cc: Tiago Natel de Moura <tiago4orion@gmail.com>
Cc: Alison Chaiken <alison_chaiken@mentor.com>
Cc: Joe Perches <joe@perches.com>
Cc: Federico Vaga <federico.vaga@vaga.pv.it>
Cc: Zhang Le <r0bertz@gentoo.org>
Cc: Li Yang <leo@zh-kernel.org>
---
 .dir-locals.el                                | 41 +++++++++++++++
 Documentation/process/coding-style.rst        | 49 ++----------------
 .../it_IT/process/coding-style.rst            | 50 ++-----------------
 .../translations/zh_CN/coding-style.rst       | 43 +---------------
 4 files changed, 53 insertions(+), 130 deletions(-)
 create mode 100644 .dir-locals.el

diff --git a/.dir-locals.el b/.dir-locals.el
new file mode 100644
index 000000000000..8cf857a00772
--- /dev/null
+++ b/.dir-locals.el
@@ -0,0 +1,41 @@
+;; Emacs settings for Linux kernel C code.
+
+(
+ (c-mode . (
+	(c-basic-offset . 8)
+	(c-cleanup-list . (brace-else-brace))
+	(c-hanging-braces-alist . (
+			(arglist-cont-nonempty)
+			(block-close . c-snug-do-while)
+			(brace-entry-open)
+			(brace-list-open)
+			(substatement-open after)
+			))
+	(c-label-minimum-indentation . 0)
+	(c-offsets-alist . (
+			(arglist-cont-nonempty . c-lineup-arglist)
+			(arglist-intro         . +)
+			(brace-list-intro      . +)
+			(c                     . c-lineup-C-comments)
+			(case-label            . 0)
+			(comment-intro         . c-lineup-comment)
+			(cpp-define-intro      . +)
+			(cpp-macro             . -1000)
+			(cpp-macro-cont        . +)
+			(defun-block-intro     . +)
+			(else-clause           . 0)
+			(func-decl-cont        . +)
+			(inclass               . +)
+			(inher-cont            . c-lineup-multi-inher)
+			(knr-argdecl-intro     . 0)
+			(label                 . 0)
+			(statement             . 0)
+			(statement-block-intro . +)
+			(statement-case-intro  . +)
+			(statement-cont        . +)
+			(substatement          . +)
+			))
+	(indent-tabs-mode . t)
+	)
+ )
+)
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 277c113376a6..e12b845d6766 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -571,50 +571,11 @@ item, explaining its use.
 9) You've made a mess of it
 ---------------------------
 
-That's OK, we all do.  You've probably been told by your long-time Unix
-user helper that ``GNU emacs`` automatically formats the C sources for
-you, and you've noticed that yes, it does do that, but the defaults it
-uses are less than desirable (in fact, they are worse than random
-typing - an infinite number of monkeys typing into GNU emacs would never
-make a good program).
-
-So, you can either get rid of GNU emacs, or change it to use saner
-values.  To do the latter, you can stick the following in your .emacs file:
-
-.. code-block:: none
-
-  (defun c-lineup-arglist-tabs-only (ignored)
-    "Line up argument lists by tabs, not spaces"
-    (let* ((anchor (c-langelem-pos c-syntactic-element))
-           (column (c-langelem-2nd-pos c-syntactic-element))
-           (offset (- (1+ column) anchor))
-           (steps (floor offset c-basic-offset)))
-      (* (max steps 1)
-         c-basic-offset)))
-
-  (add-hook 'c-mode-common-hook
-            (lambda ()
-              ;; Add kernel style
-              (c-add-style
-               "linux-tabs-only"
-               '("linux" (c-offsets-alist
-                          (arglist-cont-nonempty
-                           c-lineup-gcc-asm-reg
-                           c-lineup-arglist-tabs-only))))))
-
-  (add-hook 'c-mode-hook
-            (lambda ()
-              (let ((filename (buffer-file-name)))
-                ;; Enable kernel mode for the appropriate files
-                (when (and filename
-                           (string-match (expand-file-name "~/src/linux-trees")
-                                         filename))
-                  (setq indent-tabs-mode t)
-                  (setq show-trailing-whitespace t)
-                  (c-set-style "linux-tabs-only")))))
-
-This will make emacs go better with the kernel coding style for C
-files below ``~/src/linux-trees``.
+``GNU emacs`` automatically formats the C sources for you. However,
+the defaults it uses are less than desirable. Use a version of emacs
+that support directory local variables such that it automatically
+picks up the settings from .dir-locals.el in the kernel top level
+directory.
 
 But even if you fail in getting emacs to do sane formatting, not
 everything is lost: use ``indent``.
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index b707bdbe178c..05a86c69bd5d 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -578,51 +578,11 @@ commento per spiegarne l'uso.
 9) Avete fatto un pasticcio
 ---------------------------
 
-Va bene, li facciamo tutti.  Probabilmente vi è stato detto dal vostro
-aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il
-codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che
-i modi predefiniti non sono proprio allettanti (infatti, sono peggio che
-premere tasti a caso - un numero infinito di scimmie che scrivono in
-GNU emacs non faranno mai un buon programma).
-
-Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più
-sensati.  Per fare quest'ultima cosa, potete appiccicare il codice che
-segue nel vostro file .emacs:
-
-.. code-block:: none
-
-  (defun c-lineup-arglist-tabs-only (ignored)
-    "Line up argument lists by tabs, not spaces"
-    (let* ((anchor (c-langelem-pos c-syntactic-element))
-           (column (c-langelem-2nd-pos c-syntactic-element))
-           (offset (- (1+ column) anchor))
-           (steps (floor offset c-basic-offset)))
-      (* (max steps 1)
-         c-basic-offset)))
-
-  (add-hook 'c-mode-common-hook
-            (lambda ()
-              ;; Add kernel style
-              (c-add-style
-               "linux-tabs-only"
-               '("linux" (c-offsets-alist
-                          (arglist-cont-nonempty
-                           c-lineup-gcc-asm-reg
-                           c-lineup-arglist-tabs-only))))))
-
-  (add-hook 'c-mode-hook
-            (lambda ()
-              (let ((filename (buffer-file-name)))
-                ;; Enable kernel mode for the appropriate files
-                (when (and filename
-                           (string-match (expand-file-name "~/src/linux-trees")
-                                         filename))
-                  (setq indent-tabs-mode t)
-                  (setq show-trailing-whitespace t)
-                  (c-set-style "linux-tabs-only")))))
-
-Questo farà funzionare meglio emacs con lo stile del kernel per i file che
-si trovano nella cartella ``~/src/linux-trees``.
+`` GNU emacs`` formatta automaticamente le sorgenti C per te. Tuttavia,
+le impostazioni predefinite che utilizza sono meno desiderabili.
+Utilizzare una versione di emacs che supporti le variabili locali della
+directory in modo tale che raccolga automaticamente le impostazioni da
+.dir-locals.el nella directory di livello superiore del kernel.
 
 Ma anche se doveste fallire nell'ottenere una formattazione sensata in emacs
 non tutto è perduto: usate ``indent``.
diff --git a/Documentation/translations/zh_CN/coding-style.rst b/Documentation/translations/zh_CN/coding-style.rst
index 1466aa64b8b4..32a72a9c110a 100644
--- a/Documentation/translations/zh_CN/coding-style.rst
+++ b/Documentation/translations/zh_CN/coding-style.rst
@@ -516,47 +516,8 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。
 9) 你已经把事情弄糟了
 ------------------------------
 
-这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你
-``GNU emacs`` 能自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它
-所使用的默认值和我们想要的相去甚远 (实际上，甚至比随机打的还要差——无数个猴子
-在 GNU emacs 里打字永远不会创造出一个好程序) (译注：Infinite Monkey Theorem)
-
-所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，
-你可以把下面这段粘贴到你的 .emacs 文件里。
-
-.. code-block:: none
-
-  (defun c-lineup-arglist-tabs-only (ignored)
-    "Line up argument lists by tabs, not spaces"
-    (let* ((anchor (c-langelem-pos c-syntactic-element))
-           (column (c-langelem-2nd-pos c-syntactic-element))
-           (offset (- (1+ column) anchor))
-           (steps (floor offset c-basic-offset)))
-      (* (max steps 1)
-         c-basic-offset)))
-
-  (add-hook 'c-mode-common-hook
-            (lambda ()
-              ;; Add kernel style
-              (c-add-style
-               "linux-tabs-only"
-               '("linux" (c-offsets-alist
-                          (arglist-cont-nonempty
-                           c-lineup-gcc-asm-reg
-                           c-lineup-arglist-tabs-only))))))
-
-  (add-hook 'c-mode-hook
-            (lambda ()
-              (let ((filename (buffer-file-name)))
-                ;; Enable kernel mode for the appropriate files
-                (when (and filename
-                           (string-match (expand-file-name "~/src/linux-trees")
-                                         filename))
-                  (setq indent-tabs-mode t)
-                  (setq show-trailing-whitespace t)
-                  (c-set-style "linux-tabs-only")))))
-
-这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。
+``GNU emacs``會自動為您設置C源代碼。但是，它使用的默認值不太理想。
+使用支持目錄本地變量的emacs版本，以便它自動從內核頂級目錄中的.dir-locals.el中獲取設置。
 
 不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可
 以用 ``indent`` 。
-- 
2.20.1.415.g653613c723-goog

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Matthew Wilcox]

On Thu, Jan 03, 2019 at 04:39:57PM -0800, Bart Van Assche wrote:
> @@ -571,50 +571,11 @@ item, explaining its use.
>  9) You've made a mess of it
>  ---------------------------
>  
> -That's OK, we all do.  You've probably been told by your long-time Unix
> -user helper that ``GNU emacs`` automatically formats the C sources for
> -you, and you've noticed that yes, it does do that, but the defaults it
> -uses are less than desirable (in fact, they are worse than random
> -typing - an infinite number of monkeys typing into GNU emacs would never
> -make a good program).

I feel like this patch makes the mistake a lot of doc patches do ... it
removes some of the whimsical humourous comments that have been with
us for years.  I don't think this paragraph needs to be changed in
the slightest.

> -So, you can either get rid of GNU emacs, or change it to use saner
> -values.  To do the latter, you can stick the following in your .emacs file:
> -
[...]
> -
> -This will make emacs go better with the kernel coding style for C
> -files below ``~/src/linux-trees``.
> +``GNU emacs`` automatically formats the C sources for you. However,
> +the defaults it uses are less than desirable. Use a version of emacs
> +that support directory local variables such that it automatically
> +picks up the settings from .dir-locals.el in the kernel top level
> +directory.

How about:

So, you can either get rid of GNU emacs, or change it to use saner
defaults.  Versions of emacs since [...] support directory local
variables and will pick up the settings from .dir-locals.el in the
kernel top level directory.

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Federico Vaga]

On Friday, January 4, 2019 1:39:57 AM CET Bart Van Assche wrote:
> For new kernel developers who use emacs it is tedious to follow the
> instructions in Documentation/process/coding-style.rst for configuring
> emacs. Make it easier for emacs users by moving these settings into the
> top-level .dir-locals.el file. Emacs supports directory-local variables
> since version 23.1, released in 2009. See also
> https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.html
> 
> The settings in .dir-locals.el are not identical to those in
> Documentation/process/coding-style.rst. The most important difference
> is that "(arglist-cont-nonempty c-lineup-gcc-asm-reg
> c-lineup-arglist-tabs-only)" (which is not a valid alist) has been
> changed into "(arglist-cont-nonempty . c-lineup-arglist)". I have
> verified with several large and nontrivial kernel source files that
> the settings in .dir-locals.el format code according to what checkpatch
> expects.

Isn't it better if we collect such configuration files into a dedicated 
directory (where exactly?) instead of putting them in the top-level one? Then, 
the developer has to copy/link the configuration file into the top-level 
directory.

If we accept emacs configuration files in the top-level directory we will have 
to accept also the ones from other editors (of course, when they support local 
configurations). In addition, probably, there are people who do not want to 
use local configurations.

> The Italian and Chinese translations of the modified paragraphs have
> been generated by Google Translate.

Thanks for the Italian translation but unfortunately Google Translate is not 
up to the task :) Any one can understand the translation that Google did but 
it is incorrect.

I can give you a correct translation once it has been agreed on the English 
version.

> 
> Signed-off-by: Bart Van Assche <bvanassche@acm.org>
> Cc: Geyslan G. Bem <geyslan@gmail.com>
> Cc: Tiago Natel de Moura <tiago4orion@gmail.com>
> Cc: Alison Chaiken <alison_chaiken@mentor.com>
> Cc: Joe Perches <joe@perches.com>
> Cc: Federico Vaga <federico.vaga@vaga.pv.it>
> Cc: Zhang Le <r0bertz@gentoo.org>
> Cc: Li Yang <leo@zh-kernel.org>
> ---
>  .dir-locals.el                                | 41 +++++++++++++++
>  Documentation/process/coding-style.rst        | 49 ++----------------
>  .../it_IT/process/coding-style.rst            | 50 ++-----------------
>  .../translations/zh_CN/coding-style.rst       | 43 +---------------
>  4 files changed, 53 insertions(+), 130 deletions(-)
>  create mode 100644 .dir-locals.el
> 
> diff --git a/.dir-locals.el b/.dir-locals.el
> new file mode 100644
> index 000000000000..8cf857a00772
> --- /dev/null
> +++ b/.dir-locals.el
> @@ -0,0 +1,41 @@
> +;; Emacs settings for Linux kernel C code.
> +
> +(
> + (c-mode . (
> +	(c-basic-offset . 8)
> +	(c-cleanup-list . (brace-else-brace))
> +	(c-hanging-braces-alist . (
> +			(arglist-cont-nonempty)
> +			(block-close . c-snug-do-while)
> +			(brace-entry-open)
> +			(brace-list-open)
> +			(substatement-open after)
> +			))
> +	(c-label-minimum-indentation . 0)
> +	(c-offsets-alist . (
> +			(arglist-cont-nonempty . c-lineup-arglist)
> +			(arglist-intro         . +)
> +			(brace-list-intro      . +)
> +			(c                     . c-lineup-C-comments)
> +			(case-label            . 0)
> +			(comment-intro         . c-lineup-comment)
> +			(cpp-define-intro      . +)
> +			(cpp-macro             . -1000)
> +			(cpp-macro-cont        . +)
> +			(defun-block-intro     . +)
> +			(else-clause           . 0)
> +			(func-decl-cont        . +)
> +			(inclass               . +)
> +			(inher-cont            . c-lineup-multi-inher)
> +			(knr-argdecl-intro     . 0)
> +			(label                 . 0)
> +			(statement             . 0)
> +			(statement-block-intro . +)
> +			(statement-case-intro  . +)
> +			(statement-cont        . +)
> +			(substatement          . +)
> +			))
> +	(indent-tabs-mode . t)
> +	)
> + )
> +)
> diff --git a/Documentation/process/coding-style.rst
> b/Documentation/process/coding-style.rst index 277c113376a6..e12b845d6766
> 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -571,50 +571,11 @@ item, explaining its use.
>  9) You've made a mess of it
>  ---------------------------
> 
> -That's OK, we all do.  You've probably been told by your long-time Unix
> -user helper that ``GNU emacs`` automatically formats the C sources for
> -you, and you've noticed that yes, it does do that, but the defaults it
> -uses are less than desirable (in fact, they are worse than random
> -typing - an infinite number of monkeys typing into GNU emacs would never
> -make a good program).
> -
> -So, you can either get rid of GNU emacs, or change it to use saner
> -values.  To do the latter, you can stick the following in your .emacs file:
> -
> -.. code-block:: none
> -
> -  (defun c-lineup-arglist-tabs-only (ignored)
> -    "Line up argument lists by tabs, not spaces"
> -    (let* ((anchor (c-langelem-pos c-syntactic-element))
> -           (column (c-langelem-2nd-pos c-syntactic-element))
> -           (offset (- (1+ column) anchor))
> -           (steps (floor offset c-basic-offset)))
> -      (* (max steps 1)
> -         c-basic-offset)))
> -
> -  (add-hook 'c-mode-common-hook
> -            (lambda ()
> -              ;; Add kernel style
> -              (c-add-style
> -               "linux-tabs-only"
> -               '("linux" (c-offsets-alist
> -                          (arglist-cont-nonempty
> -                           c-lineup-gcc-asm-reg
> -                           c-lineup-arglist-tabs-only))))))
> -
> -  (add-hook 'c-mode-hook
> -            (lambda ()
> -              (let ((filename (buffer-file-name)))
> -                ;; Enable kernel mode for the appropriate files
> -                (when (and filename
> -                           (string-match (expand-file-name
> "~/src/linux-trees") -                                         filename))
> -                  (setq indent-tabs-mode t)
> -                  (setq show-trailing-whitespace t)
> -                  (c-set-style "linux-tabs-only")))))
> -
> -This will make emacs go better with the kernel coding style for C
> -files below ``~/src/linux-trees``.
> +``GNU emacs`` automatically formats the C sources for you. However,
> +the defaults it uses are less than desirable. Use a version of emacs
> +that support directory local variables such that it automatically
> +picks up the settings from .dir-locals.el in the kernel top level
> +directory.
> 
>  But even if you fail in getting emacs to do sane formatting, not
>  everything is lost: use ``indent``.
> diff --git a/Documentation/translations/it_IT/process/coding-style.rst
> b/Documentation/translations/it_IT/process/coding-style.rst index
> b707bdbe178c..05a86c69bd5d 100644
> --- a/Documentation/translations/it_IT/process/coding-style.rst
> +++ b/Documentation/translations/it_IT/process/coding-style.rst
> @@ -578,51 +578,11 @@ commento per spiegarne l'uso.
>  9) Avete fatto un pasticcio
>  ---------------------------
> 
> -Va bene, li facciamo tutti.  Probabilmente vi è stato detto dal vostro
> -aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il
> -codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che
> -i modi predefiniti non sono proprio allettanti (infatti, sono peggio che
> -premere tasti a caso - un numero infinito di scimmie che scrivono in
> -GNU emacs non faranno mai un buon programma).
> -
> -Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più
> -sensati.  Per fare quest'ultima cosa, potete appiccicare il codice che
> -segue nel vostro file .emacs:
> -
> -.. code-block:: none
> -
> -  (defun c-lineup-arglist-tabs-only (ignored)
> -    "Line up argument lists by tabs, not spaces"
> -    (let* ((anchor (c-langelem-pos c-syntactic-element))
> -           (column (c-langelem-2nd-pos c-syntactic-element))
> -           (offset (- (1+ column) anchor))
> -           (steps (floor offset c-basic-offset)))
> -      (* (max steps 1)
> -         c-basic-offset)))
> -
> -  (add-hook 'c-mode-common-hook
> -            (lambda ()
> -              ;; Add kernel style
> -              (c-add-style
> -               "linux-tabs-only"
> -               '("linux" (c-offsets-alist
> -                          (arglist-cont-nonempty
> -                           c-lineup-gcc-asm-reg
> -                           c-lineup-arglist-tabs-only))))))
> -
> -  (add-hook 'c-mode-hook
> -            (lambda ()
> -              (let ((filename (buffer-file-name)))
> -                ;; Enable kernel mode for the appropriate files
> -                (when (and filename
> -                           (string-match (expand-file-name
> "~/src/linux-trees") -                                         filename))
> -                  (setq indent-tabs-mode t)
> -                  (setq show-trailing-whitespace t)
> -                  (c-set-style "linux-tabs-only")))))
> -
> -Questo farà funzionare meglio emacs con lo stile del kernel per i file che
> -si trovano nella cartella ``~/src/linux-trees``.
> +`` GNU emacs`` formatta automaticamente le sorgenti C per te. Tuttavia,
> +le impostazioni predefinite che utilizza sono meno desiderabili.
> +Utilizzare una versione di emacs che supporti le variabili locali della
> +directory in modo tale che raccolga automaticamente le impostazioni da
> +.dir-locals.el nella directory di livello superiore del kernel.
> 
>  Ma anche se doveste fallire nell'ottenere una formattazione sensata in
> emacs non tutto è perduto: usate ``indent``.
> diff --git a/Documentation/translations/zh_CN/coding-style.rst
> b/Documentation/translations/zh_CN/coding-style.rst index
> 1466aa64b8b4..32a72a9c110a 100644
> --- a/Documentation/translations/zh_CN/coding-style.rst
> +++ b/Documentation/translations/zh_CN/coding-style.rst
> @@ -516,47 +516,8 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。
>  9) 你已经把事情弄糟了
>  ------------------------------
> 
> -这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你
> -``GNU emacs`` 能自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它
> -所使用的默认值和我们想要的相去甚远 (实际上，甚至比随机打的还要差——无数个猴子
> -在 GNU emacs 里打字永远不会创造出一个好程序) (译注：Infinite Monkey Theorem)
> -
> -所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，
> -你可以把下面这段粘贴到你的 .emacs 文件里。
> -
> -.. code-block:: none
> -
> -  (defun c-lineup-arglist-tabs-only (ignored)
> -    "Line up argument lists by tabs, not spaces"
> -    (let* ((anchor (c-langelem-pos c-syntactic-element))
> -           (column (c-langelem-2nd-pos c-syntactic-element))
> -           (offset (- (1+ column) anchor))
> -           (steps (floor offset c-basic-offset)))
> -      (* (max steps 1)
> -         c-basic-offset)))
> -
> -  (add-hook 'c-mode-common-hook
> -            (lambda ()
> -              ;; Add kernel style
> -              (c-add-style
> -               "linux-tabs-only"
> -               '("linux" (c-offsets-alist
> -                          (arglist-cont-nonempty
> -                           c-lineup-gcc-asm-reg
> -                           c-lineup-arglist-tabs-only))))))
> -
> -  (add-hook 'c-mode-hook
> -            (lambda ()
> -              (let ((filename (buffer-file-name)))
> -                ;; Enable kernel mode for the appropriate files
> -                (when (and filename
> -                           (string-match (expand-file-name
> "~/src/linux-trees") -                                         filename))
> -                  (setq indent-tabs-mode t)
> -                  (setq show-trailing-whitespace t)
> -                  (c-set-style "linux-tabs-only")))))
> -
> -这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。
> +``GNU emacs``會自動為您設置C源代碼。但是，它使用的默認值不太理想。
> +使用支持目錄本地變量的emacs版本，以便它自動從內核頂級目錄中的.dir-locals.el中獲取設置。
> 
>  不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可
>  以用 ``indent`` 。

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Jani Nikula]

On Fri, 04 Jan 2019, Federico Vaga <federico.vaga@vaga.pv.it> wrote:
> Isn't it better if we collect such configuration files into a
> dedicated directory (where exactly?) instead of putting them in the
> top-level one? Then, the developer has to copy/link the configuration
> file into the top-level directory.
>
> If we accept emacs configuration files in the top-level directory we
> will have to accept also the ones from other editors (of course, when
> they support local configurations). In addition, probably, there are
> people who do not want to use local configurations.

Fully agreed.

Also, you probably do not wish the file to change when you switch
branches with different upstream baselines. Or deal with possible emacs
version dependent changes. I do like having the example in the kernel
tree, but let the users deal with actually using the file. Placing the
file at the top level makes it harder for users to have a file of their
own there. This from an emacs user.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Bart Van Assche]

On Thu, 2019-01-03 at 18:12 -0800, Matthew Wilcox wrote:
> On Thu, Jan 03, 2019 at 04:39:57PM -0800, Bart Van Assche wrote:
> > @@ -571,50 +571,11 @@ item, explaining its use.
> >  9) You've made a mess of it
> >  ---------------------------
> >  
> > -That's OK, we all do.  You've probably been told by your long-time Unix
> > -user helper that ``GNU emacs`` automatically formats the C sources for
> > -you, and you've noticed that yes, it does do that, but the defaults it
> > -uses are less than desirable (in fact, they are worse than random
> > -typing - an infinite number of monkeys typing into GNU emacs would never
> > -make a good program).
> 
> I feel like this patch makes the mistake a lot of doc patches do ... it
> removes some of the whimsical humourous comments that have been with
> us for years.  I don't think this paragraph needs to be changed in
> the slightest.
> 
> > -So, you can either get rid of GNU emacs, or change it to use saner
> > -values.  To do the latter, you can stick the following in your .emacs file:
> > -
> 
> [...]
> > -
> > -This will make emacs go better with the kernel coding style for C
> > -files below ``~/src/linux-trees``.
> > +``GNU emacs`` automatically formats the C sources for you. However,
> > +the defaults it uses are less than desirable. Use a version of emacs
> > +that support directory local variables such that it automatically
> > +picks up the settings from .dir-locals.el in the kernel top level
> > +directory.
> 
> How about:
> 
> So, you can either get rid of GNU emacs, or change it to use saner
> defaults.  Versions of emacs since [...] support directory local
> variables and will pick up the settings from .dir-locals.el in the
> kernel top level directory.

Hi Matthew,

Thanks for having taken a look. I had removed the first paragraph of section
9 since it seemed more negative than humouristic to me. Anyway, I will make
the change that you proposed.

Bart.

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Bart Van Assche]

On Fri, 2019-01-04 at 10:44 +0100, Federico Vaga wrote:
> On Friday, January 4, 2019 1:39:57 AM CET Bart Van Assche wrote:
> > For new kernel developers who use emacs it is tedious to follow the
> > instructions in Documentation/process/coding-style.rst for configuring
> > emacs. Make it easier for emacs users by moving these settings into the
> > top-level .dir-locals.el file. Emacs supports directory-local variables
> > since version 23.1, released in 2009. See also
> > https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.html
> > 
> > The settings in .dir-locals.el are not identical to those in
> > Documentation/process/coding-style.rst. The most important difference
> > is that "(arglist-cont-nonempty c-lineup-gcc-asm-reg
> > c-lineup-arglist-tabs-only)" (which is not a valid alist) has been
> > changed into "(arglist-cont-nonempty . c-lineup-arglist)". I have
> > verified with several large and nontrivial kernel source files that
> > the settings in .dir-locals.el format code according to what checkpatch
> > expects.
> 
> Isn't it better if we collect such configuration files into a dedicated 
> directory (where exactly?) instead of putting them in the top-level one? Then, 
> the developer has to copy/link the configuration file into the top-level 
> directory.

I don't think so. The reason we have the checkpatch script and the
coding-style.rst document in the kernel tree is to promote coding style
uniformity. Placing the .dir-locals.el at the top level serves the same
purpose. Additionally, if the .dir-locals.el file is not at the top level
many kernel developers will overlook it.

> If we accept emacs configuration files in the top-level directory we will have 
> to accept also the ones from other editors (of course, when they support local 
> configurations).

I am aware of this and I'm fine with this.

> In addition, probably, there are people who do not want to use local
> configurations.

I expect that only a minority will not want to use the .dir-locals.el file.
Anyone who wants to override any of the settings from .dir-locals.el
can do that by using one of the methods explained in the emacs manual, e.g.
by adding a .dir-locals-2.el file. See also
https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html.

> > The Italian and Chinese translations of the modified paragraphs have
> > been generated by Google Translate.
> 
> Thanks for the Italian translation but unfortunately Google Translate is not 
> up to the task :) Any one can understand the translation that Google did but 
> it is incorrect.
> 
> I can give you a correct translation once it has been agreed on the English 
> version.

Thank you for this offer. I will leave out the Italian translation.

Bart.

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Bart Van Assche]

On Fri, 2019-01-04 at 13:18 +0200, Jani Nikula wrote:
> Also, you probably do not wish the file to change when you switch
> branches with different upstream baselines. Or deal with possible emacs
> version dependent changes. I do like having the example in the kernel
> tree, but let the users deal with actually using the file. Placing the
> file at the top level makes it harder for users to have a file of their
> own there. This from an emacs user.

If this patch gets accepted upstream it won't take long before the
.dir-locals.el file ends up in all branches. Additionally, I expect that
the rate of change for this file will be low so I do not except any
inconsistencies between branches.

Regarding emacs versions: this patch has been tested with different emacs
versions. Additionally, the rate of change in emacs' CC mode is slow. Any
backwards incompatible changes in that mode would cause trouble to a very
large number of users so I do not expect radical changes in emacs' CC mode.

Regarding users having their own version of .dir-locals.el: why do you think
anyone would want to do that? Anyway, if anyone wants to replace that file
they can provide a .dir-locals-2.el file. See also
https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html.

Bart.

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Jonathan Corbet]

On Fri, 04 Jan 2019 08:32:38 -0800
Bart Van Assche <bvanassche@acm.org> wrote:

> > Isn't it better if we collect such configuration files into a dedicated 
> > directory (where exactly?) instead of putting them in the top-level one? Then, 
> > the developer has to copy/link the configuration file into the top-level 
> > directory.  
> 
> I don't think so. The reason we have the checkpatch script and the
> coding-style.rst document in the kernel tree is to promote coding style
> uniformity. Placing the .dir-locals.el at the top level serves the same
> purpose. Additionally, if the .dir-locals.el file is not at the top level
> many kernel developers will overlook it.

I think we have to be careful about silently configuring other developers'
tools.  We put checkpatch.pl in the kernel tree, but we don't add a git
hook for everybody to run it.  I'm totally in favor of adding this .el
file to the documentation (or samples) directory and pointing users to it;
I'm less thrilled about putting in a dotfile where emacs will just pick it
up.

jon

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Joe Perches]

On Fri, 2019-01-04 at 09:41 -0700, Jonathan Corbet wrote:
> On Fri, 04 Jan 2019 08:32:38 -0800
> Bart Van Assche <bvanassche@acm.org> wrote:
> > > Isn't it better if we collect such configuration files into a dedicated 
> > > directory (where exactly?) instead of putting them in the top-level one? Then, 
> > > the developer has to copy/link the configuration file into the top-level 
> > > directory.
[]
> I think we have to be careful about silently configuring other developers'
> tools.

I agree and as an emacs user I am also not a
proponent of this change.

Longtime emacs users are very sensitive to their
keybindings and styles and having these change
unexpectedly can be unsettling.

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Jani Nikula]

On Fri, 04 Jan 2019, Bart Van Assche <bvanassche@acm.org> wrote:
> Regarding users having their own version of .dir-locals.el: why do you
> think anyone would want to do that?

Err, .dir-locals.el is not only for a project to enforce local variables
on emacs users, it's also for the users to set local variables for the
project.

> Anyway, if anyone wants to replace that file they can provide a
> .dir-locals-2.el file.

It does not replace anything, it's loaded in addition to .dir-locals.el.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Bart Van Assche]

On Fri, 2019-01-04 at 13:08 -0800, Bart Van Assche wrote:
> For new kernel developers who use emacs it is tedious to follow the
> instructions in Documentation/process/coding-style.rst for configuring
> [ ... ]

Please ignore this patch - this is the old version (v1). The other patch,
the one this is a reply to, is version 2.

Bart.

[PATCH] Documentation/CodingStyle: Move emacs settings into .dir-locals.el

[Bart Van Assche]

For new kernel developers who use emacs it is tedious to follow the
instructions in Documentation/process/coding-style.rst for configuring
emacs. Make it easier for emacs users by moving these settings into the
top-level .dir-locals.el file. Emacs supports directory-local variables
since version 23.1, released in 2009. See also
https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.html

The settings in .dir-locals.el are not identical to those in
Documentation/process/coding-style.rst. The most important difference
is that "(arglist-cont-nonempty c-lineup-gcc-asm-reg
c-lineup-arglist-tabs-only)" (which is not a valid alist) has been
changed into "(arglist-cont-nonempty . c-lineup-arglist)". I have
verified with several large and nontrivial kernel source files that
the settings in .dir-locals.el format code according to what checkpatch
expects.

The Italian and Chinese translations of the modified paragraphs have
been generated by Google Translate.

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
Cc: Geyslan G. Bem <geyslan@gmail.com>
Cc: Tiago Natel de Moura <tiago4orion@gmail.com>
Cc: Alison Chaiken <alison_chaiken@mentor.com>
Cc: Joe Perches <joe@perches.com>
Cc: Federico Vaga <federico.vaga@vaga.pv.it>
Cc: Zhang Le <r0bertz@gentoo.org>
Cc: Li Yang <leo@zh-kernel.org>
---
 .dir-locals.el                                | 41 +++++++++++++++
 Documentation/process/coding-style.rst        | 49 ++----------------
 .../it_IT/process/coding-style.rst            | 50 ++-----------------
 .../translations/zh_CN/coding-style.rst       | 43 +---------------
 4 files changed, 53 insertions(+), 130 deletions(-)
 create mode 100644 .dir-locals.el

diff --git a/.dir-locals.el b/.dir-locals.el
new file mode 100644
index 000000000000..8cf857a00772
--- /dev/null
+++ b/.dir-locals.el
@@ -0,0 +1,41 @@
+;; Emacs settings for Linux kernel C code.
+
+(
+ (c-mode . (
+	(c-basic-offset . 8)
+	(c-cleanup-list . (brace-else-brace))
+	(c-hanging-braces-alist . (
+			(arglist-cont-nonempty)
+			(block-close . c-snug-do-while)
+			(brace-entry-open)
+			(brace-list-open)
+			(substatement-open after)
+			))
+	(c-label-minimum-indentation . 0)
+	(c-offsets-alist . (
+			(arglist-cont-nonempty . c-lineup-arglist)
+			(arglist-intro         . +)
+			(brace-list-intro      . +)
+			(c                     . c-lineup-C-comments)
+			(case-label            . 0)
+			(comment-intro         . c-lineup-comment)
+			(cpp-define-intro      . +)
+			(cpp-macro             . -1000)
+			(cpp-macro-cont        . +)
+			(defun-block-intro     . +)
+			(else-clause           . 0)
+			(func-decl-cont        . +)
+			(inclass               . +)
+			(inher-cont            . c-lineup-multi-inher)
+			(knr-argdecl-intro     . 0)
+			(label                 . 0)
+			(statement             . 0)
+			(statement-block-intro . +)
+			(statement-case-intro  . +)
+			(statement-cont        . +)
+			(substatement          . +)
+			))
+	(indent-tabs-mode . t)
+	)
+ )
+)
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 277c113376a6..e12b845d6766 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -571,50 +571,11 @@ item, explaining its use.
 9) You've made a mess of it
 ---------------------------
 
-That's OK, we all do.  You've probably been told by your long-time Unix
-user helper that ``GNU emacs`` automatically formats the C sources for
-you, and you've noticed that yes, it does do that, but the defaults it
-uses are less than desirable (in fact, they are worse than random
-typing - an infinite number of monkeys typing into GNU emacs would never
-make a good program).
-
-So, you can either get rid of GNU emacs, or change it to use saner
-values.  To do the latter, you can stick the following in your .emacs file:
-
-.. code-block:: none
-
-  (defun c-lineup-arglist-tabs-only (ignored)
-    "Line up argument lists by tabs, not spaces"
-    (let* ((anchor (c-langelem-pos c-syntactic-element))
-           (column (c-langelem-2nd-pos c-syntactic-element))
-           (offset (- (1+ column) anchor))
-           (steps (floor offset c-basic-offset)))
-      (* (max steps 1)
-         c-basic-offset)))
-
-  (add-hook 'c-mode-common-hook
-            (lambda ()
-              ;; Add kernel style
-              (c-add-style
-               "linux-tabs-only"
-               '("linux" (c-offsets-alist
-                          (arglist-cont-nonempty
-                           c-lineup-gcc-asm-reg
-                           c-lineup-arglist-tabs-only))))))
-
-  (add-hook 'c-mode-hook
-            (lambda ()
-              (let ((filename (buffer-file-name)))
-                ;; Enable kernel mode for the appropriate files
-                (when (and filename
-                           (string-match (expand-file-name "~/src/linux-trees")
-                                         filename))
-                  (setq indent-tabs-mode t)
-                  (setq show-trailing-whitespace t)
-                  (c-set-style "linux-tabs-only")))))
-
-This will make emacs go better with the kernel coding style for C
-files below ``~/src/linux-trees``.
+``GNU emacs`` automatically formats the C sources for you. However,
+the defaults it uses are less than desirable. Use a version of emacs
+that support directory local variables such that it automatically
+picks up the settings from .dir-locals.el in the kernel top level
+directory.
 
 But even if you fail in getting emacs to do sane formatting, not
 everything is lost: use ``indent``.
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index b707bdbe178c..05a86c69bd5d 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -578,51 +578,11 @@ commento per spiegarne l'uso.
 9) Avete fatto un pasticcio
 ---------------------------
 
-Va bene, li facciamo tutti.  Probabilmente vi è stato detto dal vostro
-aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il
-codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che
-i modi predefiniti non sono proprio allettanti (infatti, sono peggio che
-premere tasti a caso - un numero infinito di scimmie che scrivono in
-GNU emacs non faranno mai un buon programma).
-
-Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più
-sensati.  Per fare quest'ultima cosa, potete appiccicare il codice che
-segue nel vostro file .emacs:
-
-.. code-block:: none
-
-  (defun c-lineup-arglist-tabs-only (ignored)
-    "Line up argument lists by tabs, not spaces"
-    (let* ((anchor (c-langelem-pos c-syntactic-element))
-           (column (c-langelem-2nd-pos c-syntactic-element))
-           (offset (- (1+ column) anchor))
-           (steps (floor offset c-basic-offset)))
-      (* (max steps 1)
-         c-basic-offset)))
-
-  (add-hook 'c-mode-common-hook
-            (lambda ()
-              ;; Add kernel style
-              (c-add-style
-               "linux-tabs-only"
-               '("linux" (c-offsets-alist
-                          (arglist-cont-nonempty
-                           c-lineup-gcc-asm-reg
-                           c-lineup-arglist-tabs-only))))))
-
-  (add-hook 'c-mode-hook
-            (lambda ()
-              (let ((filename (buffer-file-name)))
-                ;; Enable kernel mode for the appropriate files
-                (when (and filename
-                           (string-match (expand-file-name "~/src/linux-trees")
-                                         filename))
-                  (setq indent-tabs-mode t)
-                  (setq show-trailing-whitespace t)
-                  (c-set-style "linux-tabs-only")))))
-
-Questo farà funzionare meglio emacs con lo stile del kernel per i file che
-si trovano nella cartella ``~/src/linux-trees``.
+`` GNU emacs`` formatta automaticamente le sorgenti C per te. Tuttavia,
+le impostazioni predefinite che utilizza sono meno desiderabili.
+Utilizzare una versione di emacs che supporti le variabili locali della
+directory in modo tale che raccolga automaticamente le impostazioni da
+.dir-locals.el nella directory di livello superiore del kernel.
 
 Ma anche se doveste fallire nell'ottenere una formattazione sensata in emacs
 non tutto è perduto: usate ``indent``.
diff --git a/Documentation/translations/zh_CN/coding-style.rst b/Documentation/translations/zh_CN/coding-style.rst
index 1466aa64b8b4..32a72a9c110a 100644
--- a/Documentation/translations/zh_CN/coding-style.rst
+++ b/Documentation/translations/zh_CN/coding-style.rst
@@ -516,47 +516,8 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。
 9) 你已经把事情弄糟了
 ------------------------------
 
-这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你
-``GNU emacs`` 能自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它
-所使用的默认值和我们想要的相去甚远 (实际上，甚至比随机打的还要差——无数个猴子
-在 GNU emacs 里打字永远不会创造出一个好程序) (译注：Infinite Monkey Theorem)
-
-所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，
-你可以把下面这段粘贴到你的 .emacs 文件里。
-
-.. code-block:: none
-
-  (defun c-lineup-arglist-tabs-only (ignored)
-    "Line up argument lists by tabs, not spaces"
-    (let* ((anchor (c-langelem-pos c-syntactic-element))
-           (column (c-langelem-2nd-pos c-syntactic-element))
-           (offset (- (1+ column) anchor))
-           (steps (floor offset c-basic-offset)))
-      (* (max steps 1)
-         c-basic-offset)))
-
-  (add-hook 'c-mode-common-hook
-            (lambda ()
-              ;; Add kernel style
-              (c-add-style
-               "linux-tabs-only"
-               '("linux" (c-offsets-alist
-                          (arglist-cont-nonempty
-                           c-lineup-gcc-asm-reg
-                           c-lineup-arglist-tabs-only))))))
-
-  (add-hook 'c-mode-hook
-            (lambda ()
-              (let ((filename (buffer-file-name)))
-                ;; Enable kernel mode for the appropriate files
-                (when (and filename
-                           (string-match (expand-file-name "~/src/linux-trees")
-                                         filename))
-                  (setq indent-tabs-mode t)
-                  (setq show-trailing-whitespace t)
-                  (c-set-style "linux-tabs-only")))))
-
-这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。
+``GNU emacs``會自動為您設置C源代碼。但是，它使用的默認值不太理想。
+使用支持目錄本地變量的emacs版本，以便它自動從內核頂級目錄中的.dir-locals.el中獲取設置。
 
 不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可
 以用 ``indent`` 。
-- 
2.20.1.415.g653613c723-goog