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
 ,* Top level headline             |    * Top level headline
 ,** Second level                  |      * Second level
 ,** Second level                  |      * Second level
 ,*** Third level                  |        * Third level
 ,*** Third level                  |        * Third level
-    some text                    |          some text
+some text                        |          some text
 ,*** Third level                  |        * Third level
 ,*** Third level                  |        * Third level
-    more text                    |          more text
+more text                        |          more text
 ,* Another top level headline     |    * Another top level headline
 ,* Another top level headline     |    * Another top level headline
 #+end_example
 #+end_example
 
 
@@ -18440,16 +18440,17 @@ and hiding leading stars.
 
 
 #+cindex: Indent mode
 #+cindex: Indent mode
 #+findex: org-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
 ~org-indent-mode~.  Text lines that are not headlines are prefixed
 with virtual spaces to vertically align with the headline
 with virtual spaces to vertically align with the headline
 text[fn:147].
 text[fn:147].
 
 
 #+vindex: org-indent-indentation-per-level
 #+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
 #+vindex: org-startup-indented
 To globally turn on ~org-indent-mode~ for all files, customize the
 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,
 It is possible to use hard spaces to achieve the indentation instead,
 if the bare ASCII file should have the indented look also outside
 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
 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
   #+begin_src emacs-lisp
   (setq org-adapt-indentation t
   (setq org-adapt-indentation t
@@ -18471,64 +18472,42 @@ line up with the outline headers.  You need these settings:
         org-odd-levels-only t)
         org-odd-levels-only t)
   #+end_src
   #+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
   #+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
   #+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
   #+begin_example
   ,#+STARTUP: hidestars
   ,#+STARTUP: hidestars
   ,#+STARTUP: showstars
   ,#+STARTUP: showstars
   #+end_example
   #+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
   #+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
   #+begin_example
   ,#+STARTUP: odd
   ,#+STARTUP: odd
   ,#+STARTUP: oddeven
   ,#+STARTUP: oddeven
   #+end_example
   #+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)}}}.
   org-convert-to-oddeven-levels)}}}.
+
 ** Dynamic Headline Numbering
 ** Dynamic Headline Numbering
 :PROPERTIES:
 :PROPERTIES:
 :DESCRIPTION: Display and update outline numbering.
 :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
 [fn:149] This works, but requires extra effort.  Org Indent mode is
 more convenient for most applications.
 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,
 [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]].
 such as [[https://nextcloud.com][Nextcloud]].  Additional help is at this [[https://orgmode.org/worg/org-faq.html#mobileorg_webdav][FAQ entry]].