Browse Source

Simplify the "Hard Indentation" section in the manual

* doc/org-manual.org (Hard Indentation): Simplify section.
Carsten Dominik 6 years ago
parent
commit
6dfd4e38d0
1 changed files with 25 additions and 51 deletions
  1. 25 51
      doc/org-manual.org

+ 25 - 51
doc/org-manual.org

@@ -18425,9 +18425,9 @@ star and indents text to line up with the heading:
 ,* Top level headline             |    * Top level headline
 ,** Second level                  |      * Second level
 ,*** Third level                  |        * Third level
-    some text                    |          some text
+some text                        |          some text
 ,*** Third level                  |        * Third level
-    more text                    |          more text
+more text                        |          more text
 ,* Another top level headline     |    * Another top level headline
 #+end_example
 
@@ -18440,16 +18440,17 @@ and hiding leading stars.
 
 #+cindex: Indent mode
 #+findex: org-indent-mode
-To display the buffer in the indented view, use the minor mode,
+To display the buffer in the indented view, use the minor mode
 ~org-indent-mode~.  Text lines that are not headlines are prefixed
 with virtual spaces to vertically align with the headline
 text[fn:147].
 
 #+vindex: org-indent-indentation-per-level
-To make more horizontal space, the headlines are shifted by two stars.
-This can be configured by the ~org-indent-indentation-per-level~
-variable.  Only one star on each headline is visible, the rest are
-masked with the same font color as the background[fn:148].
+To make more horizontal space, the headlines are shifted by two
+characters.  This can be configured by the
+~org-indent-indentation-per-level~ variable.  Only one star on each
+headline is visible, the rest are masked with the same font color as
+the background[fn:148].
 
 #+vindex: org-startup-indented
 To globally turn on ~org-indent-mode~ for all files, customize the
@@ -18463,7 +18464,7 @@ files, use =STARTUP= keyword as follows:
 It is possible to use hard spaces to achieve the indentation instead,
 if the bare ASCII file should have the indented look also outside
 Emacs[fn:149].  With Org's support, you have to indent all lines to
-line up with the outline headers.  You need these settings:
+line up with the outline headers.  You would use these settings:
 
   #+begin_src emacs-lisp
   (setq org-adapt-indentation t
@@ -18471,64 +18472,42 @@ line up with the outline headers.  You need these settings:
         org-odd-levels-only t)
   #+end_src
 
-- /Indentation of text below headlines/ ::
-
-  Indent text to align with the headline.
-
-  #+begin_example
-  ,*** Third level
-      more text, now indented
-  #+end_example
+- /Indentation of text below headlines/ (~org-adapt-indentation~) ::
 
   #+vindex: org-adapt-indentation
-  Org supports this with paragraph filling, line wrapping, and
-  structure editing, preserving or adapting the indentation as
-  appropriate[fn:150].
+  The first setting modifies paragraph filling, line wrapping, and
+  structure editing commands to preserving or adapting the indentation
+  as appropriate.
 
-- /Hiding leading stars/ ::
+- /Hiding leading stars/ (~org-hide-leading-stars~) ::
 
   #+vindex: org-hide-leading-stars
-  Org can make leading stars invisible.  For global preference,
-  configure the variable ~org-hide-leading-stars~.  For per-file
-  preference, use these file =STARTUP= options:
+  #+vindex: org-hide, face
+  The second setting makes leading stars invisible by applying the
+  face ~org-hide~ to them.  For per-file preference, use these file
+  =STARTUP= options:
 
   #+begin_example
   ,#+STARTUP: hidestars
   ,#+STARTUP: showstars
   #+end_example
 
-  With stars hidden, the tree is shown as:
-
-  #+begin_example
-  ,* Top level headline
-   ,* Second level
-    ,* Third level
-    ...
-  #+end_example
-
-  #+vindex: org-hide, face
-  Because Org makes the font color the same as the background color
-  to hide to stars, sometimes ~org-hide~ face may need tweaking to
-  get the effect right.  For some black and white combinations,
-  ~grey90~ on a white background might mask the stars better.
-
-- /Odd levels/ ::
+- /Odd levels/ (~org-odd-levels-only~) ::
 
   #+vindex: org-odd-levels-only
-  Using stars for only odd levels, 1, 3, 5, ..., can also clean up the
-  clutter.  This removes two stars from each level[fn:151].  For Org
-  to properly handle this cleaner structure during edits and exports,
-  configure the variable ~org-odd-levels-only~.  To set this per-file,
-  use either one of the following lines:
+  The third setting makes Org use only odd levels, 1, 3, 5, ..., in
+  the outline to create more indentation.  On a  per-file level,
+  control this with:
 
   #+begin_example
   ,#+STARTUP: odd
   ,#+STARTUP: oddeven
   #+end_example
 
-  To switch between single and double stars layouts, use {{{kbd(M-x
-  org-convert-to-odd-levels)}}} and {{{kbd(M-x
+  To convert a file between single and double stars layouts, use
+  {{{kbd(M-x org-convert-to-odd-levels)}}} and {{{kbd(M-x
   org-convert-to-oddeven-levels)}}}.
+
 ** Dynamic Headline Numbering
 :PROPERTIES:
 :DESCRIPTION: Display and update outline numbering.
@@ -21609,11 +21588,6 @@ through ~word-wrap~.
 [fn:149] This works, but requires extra effort.  Org Indent mode is
 more convenient for most applications.
 
-[fn:150] Also see the variable ~org-adapt-indentation~.
-
-[fn:151] Because =LEVEL=2= has 3 stars, =LEVEL=3= has 5 stars, and so
-on.
-
 [fn:152] For a server to host files, consider using a WebDAV server,
 such as [[https://nextcloud.com][Nextcloud]].  Additional help is at this [[https://orgmode.org/worg/org-faq.html#mobileorg_webdav][FAQ entry]].