Simplify the "Hard Indentation" section in the manual

* doc/org-manual.org (Hard Indentation): Simplify section.
This commit is contained in:
Carsten Dominik 2019-08-18 11:06:33 +02:00
parent 16f3fd69c3
commit 6dfd4e38d0
1 changed files with 25 additions and 51 deletions

View File

@ -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. To make more horizontal space, the headlines are shifted by two
This can be configured by the ~org-indent-indentation-per-level~ characters. This can be configured by the
variable. Only one star on each headline is visible, the rest are ~org-indent-indentation-per-level~ variable. Only one star on each
masked with the same font color as the background[fn:148]. 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/ :: - /Indentation of text below headlines/ (~org-adapt-indentation~) ::
Indent text to align with the headline.
#+begin_example
,*** Third level
more text, now indented
#+end_example
#+vindex: org-adapt-indentation #+vindex: org-adapt-indentation
Org supports this with paragraph filling, line wrapping, and The first setting modifies paragraph filling, line wrapping, and
structure editing, preserving or adapting the indentation as structure editing commands to preserving or adapting the indentation
appropriate[fn:150]. 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, #+vindex: org-hide, face
configure the variable ~org-hide-leading-stars~. For per-file The second setting makes leading stars invisible by applying the
preference, use these file =STARTUP= options: 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: - /Odd levels/ (~org-odd-levels-only~) ::
#+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/ ::
#+vindex: org-odd-levels-only #+vindex: org-odd-levels-only
Using stars for only odd levels, 1, 3, 5, ..., can also clean up the The third setting makes Org use only odd levels, 1, 3, 5, ..., in
clutter. This removes two stars from each level[fn:151]. For Org the outline to create more indentation. On a per-file level,
to properly handle this cleaner structure during edits and exports, control this with:
configure the variable ~org-odd-levels-only~. To set this per-file,
use either one of the following lines:
#+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 To convert a file between single and double stars layouts, use
org-convert-to-odd-levels)}}} and {{{kbd(M-x {{{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]].