branch: externals/org
commit d98ca046cc7633dd9c06236d1221e97c876795f5
Author: Ihor Radchenko <yanta...@posteo.net>
Commit: Ihor Radchenko <yanta...@posteo.net>
org-manual.org: Clarify that LANGUAGE may be omitted in code blocks
* doc/org-manual.org (Structure of Code Blocks):
(Editing Source Code): Clarify that <language> is optional. Link to
possible consequences of <language> being omitted.
---
doc/org-manual.org | 23 ++++++++++++++++++-----
1 file changed, 18 insertions(+), 5 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 77ae185468..e20a9e3db2 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17314,9 +17314,16 @@ or
- =<language>= ::
#+cindex: language, in code blocks
- Mandatory. It is the identifier of the source code language in the
+ Optional. It is the identifier of the source code language in the
block. See [[*Languages]], for identifiers of supported languages.
+ When =<language>= identifier is omitted, the block also cannot
+ have =<switches>= and =<header arguments>=.
+
+ Language identifier is also used to fontify code blocks in Org
+ buffers, when ~org-src-fontify-natively~ is set to non-~nil~. See
+ [[*Editing Source Code]].
+
- =<switches>= ::
#+cindex: switches, in code blocks
@@ -18952,6 +18959,9 @@ group ~org-edit-structure~.
header line, then the edit buffer uses that major mode. Use this
variable to arbitrarily map language identifiers to major modes.
+ When language identifier is omitted in the src block, Org mode's
+ behavior is undefined.
+
- ~org-src-window-setup~ ::
#+vindex: org-src-window-setup
@@ -18977,10 +18987,13 @@ group ~org-edit-structure~.
#+vindex: org-src-fontify-natively
#+vindex: org-src-block-faces
-Set ~org-src-fontify-natively~ to non-~nil~ to turn on native code
-fontification in the /Org/ buffer. Fontification of code blocks can
-give visual separation of text and code on the display page. To
-further customize the appearance of ~org-block~ for specific
+Fontification of code blocks can give visual separation of text and
+code on the display page. Set ~org-src-fontify-natively~ to non-~nil~
+to turn on native code fontification in the /Org/ buffer. The
+fontification follows the major mode used to edit the code block (see
+~org-src-lang-modes~ above).
+
+To further customize the appearance of ~org-block~ for specific
languages, customize ~org-src-block-faces~. The following example
shades the background of regular blocks, and colors source blocks only
for Python and Emacs Lisp languages.
