Browse Source

org-manual: New "features" section about source blocks

* doc/org-manual.org (Features): New section.

The main motivation behind this is to avoid starting "Working with
source code" section with a wall of text that hides the menu.
Nicolas Goaziou 11 months ago
parent
commit
d20e45b187
1 changed files with 15 additions and 11 deletions
  1. 15 11
      doc/org-manual.org

+ 15 - 11
doc/org-manual.org

@@ -16180,6 +16180,19 @@ Here is an example source code block in the Emacs Lisp language:
 ,#+END_SRC
 #+end_example
 
+Source code blocks are one of many Org block types, which also include
+"center", "comment", "dynamic", "example", "export", "quote",
+"special", and "verse".  This section pertains to blocks between
+=#+BEGIN_SRC= and =#+END_SRC=.
+
+Details of Org's facilities for working with source code are described
+in the following sections.
+
+** Features
+:PROPERTIES:
+:DESCRIPTION: Enjoy the versatility of source blocks.
+:END:
+
 Org can manage the source code in the block delimited by =#+BEGIN_SRC=
 ... =#+END_SRC= in several ways that can simplify housekeeping tasks
 essential to modern source code maintenance.  Org can edit, format,
@@ -16188,14 +16201,8 @@ and execute a source code block, then capture the results.  The Org
 mode literature sometimes refers to source code blocks as /live code/
 blocks because they can alter the content of the Org document or the
 material that it exports.  Users can control how live they want each
-source code block by tweaking the header arguments (see [[*Using
-Header Arguments]]) for compiling, execution, extraction, and
-exporting.
-
-Source code blocks are one of many Org block types, which also include
-"center", "comment", "dynamic", "example", "export", "quote",
-"special", and "verse".  This section pertains to blocks between
-=#+BEGIN_SRC= and =#+END_SRC=.
+source code block by tweaking the header arguments (see [[*Using Header
+Arguments]]) for compiling, execution, extraction, and exporting.
 
 For editing and formatting a source code block, Org uses an
 appropriate Emacs major mode that includes features specifically
@@ -16233,9 +16240,6 @@ configuration settings of the execution environment, the results of
 the execution, and associated narratives, claims, references, and
 internal and external links in a single Org document.
 
-Details of Org's facilities for working with source code are described
-in the following sections.
-
 ** Structure of Code Blocks
 :PROPERTIES:
 :DESCRIPTION: Code block syntax described.