From a7c5aa3431cc1946aa7f8055c39e18e5afc4cef4 Mon Sep 17 00:00:00 2001 Message-Id: From: Ihor Radchenko Date: Mon, 16 Jan 2023 12:59:47 +0300 Subject: [PATCH 1/2] 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 is optional. Link to possible consequences of 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 4466af8e4..c241e170f 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -17313,9 +17313,16 @@ ** Structure of Code Blocks - == :: #+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 == identifier is omitted, the block also cannot + have == and =
=. + + 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]]. + - == :: #+cindex: switches, in code blocks @@ -18951,6 +18958,9 @@ ** Editing Source Code 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 @@ -18976,10 +18986,13 @@ ** Editing Source Code #+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. -- 2.39.0