From af463605f10459ae32cd2d8ee1f9ad0a7f333eff Mon Sep 17 00:00:00 2001
From: Rasmus <rasmus@gmx.us>
Date: Fri, 10 Jun 2016 10:07:36 +0200
Subject: [PATCH] Document org-block face changes

* doc/org.texi (Editing source code): Document org-block and
  org-block-LANG faces.
* lisp/org-faces.el (org-block): Mention org-block-LANG faces.
* lisp/org.el (org-src-fontify-natively): Add reference to org-block.
* etc/ORG-NEWS: Update entry.
---
 doc/org.texi      | 17 +++++++++++++++--
 etc/ORG-NEWS      | 12 ++----------
 lisp/org-faces.el |  5 ++++-
 lisp/org.el       |  3 ++-
 4 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 36ab99905..79f53206e 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -14963,8 +14963,21 @@ variable to @code{nil} to switch without asking.
 @end table
 
 To turn on native code fontification in the @emph{Org} buffer, configure the
-variable @code{org-src-fontify-natively}.
-
+variable @code{org-src-fontify-natively}.  You can also change the appearance
+of source blocks by customizing the @code{org-block} face or for specific
+languages, by defining @code{org-block-LANGUAGE} faces.  The following
+example shades the background of ``ordinary'' blocks while allowing Emacs
+Lisp source blocks to have a special color.
+@lisp
+(require 'color)
+(set-face-attribute 'org-block nil :background
+                    (color-darken-name
+                     (face-attribute 'default :background) 3))
+
+(defface org-block-emacs-lisp
+  '((t (:background "#EEE2FF")))
+  "Face for Emacs Lisp src blocks")
+@end lisp
 
 @node Exporting code blocks
 @section Exporting code blocks
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 8c23c50bf..3997c5afa 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -302,16 +302,8 @@ sensitive.  Otherwise, it is case insensitive.
 Repeated footnotes are now numbered by referring to a label in the
 first footnote.
 *** The ~org-block~ face is inherited by ~src-blocks~
-This works also when =org-src-fontify-natively= is non-nil.
-
-Thus, =org-block-background= Org 8.2 can be replicated with something
-like the following,
-#+BEGIN_SRC emacs-lisp
-  (require 'color)
-  (set-face-attribute 'org-block nil :background
-                      (color-darken-name
-                       (face-attribute 'default :background) 3))
-#+END_SRC
+This works also when =org-src-fontify-natively= is non-nil.  It is also
+possible to specify per-languages faces.  See the manual for details.  
 ** New functions
 *** ~org-next-line-empty-p~
 It replaces the deprecated ~next~ argument to ~org-previous-line-empty-p~.
diff --git a/lisp/org-faces.el b/lisp/org-faces.el
index f185e8882..ec93e9b4e 100644
--- a/lisp/org-faces.el
+++ b/lisp/org-faces.el
@@ -516,7 +516,10 @@ follows a #+DATE:, #+AUTHOR: or #+EMAIL: keyword."
        (:foreground "green"))
       (((class color) (min-colors 8) (background dark))
        (:foreground "yellow"))))
-  "Face text in #+begin ... #+end blocks."
+  "Face text in #+begin ... #+end blocks.
+In addition to this face that take precedence for particular
+languages.  For instance, to change the block face for Emacs-Lisp
+blocks define a `org-block-emacs-lisp' face."
   :group 'org-faces
   :version "22.1")
 
diff --git a/lisp/org.el b/lisp/org.el
index 036939501..c30b4bb39 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -5912,7 +5912,8 @@ prompted for."
     t))
 
 (defcustom org-src-fontify-natively t
-  "When non-nil, fontify code in code blocks."
+  "When non-nil, fontify code in code blocks.
+See also the `org-block' face."
   :type 'boolean
   :version "24.4"
   :package-version '(Org . "8.3")
-- 
2.11.4.GIT