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 5 years 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_SRC
 #+end_example
 #+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=
 Org can manage the source code in the block delimited by =#+BEGIN_SRC=
 ... =#+END_SRC= in several ways that can simplify housekeeping tasks
 ... =#+END_SRC= in several ways that can simplify housekeeping tasks
 essential to modern source code maintenance.  Org can edit, format,
 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/
 mode literature sometimes refers to source code blocks as /live code/
 blocks because they can alter the content of the Org document or the
 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
 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
 For editing and formatting a source code block, Org uses an
 appropriate Emacs major mode that includes features specifically
 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
 the execution, and associated narratives, claims, references, and
 internal and external links in a single Org document.
 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
 ** Structure of Code Blocks
 :PROPERTIES:
 :PROPERTIES:
 :DESCRIPTION: Code block syntax described.
 :DESCRIPTION: Code block syntax described.