mirrors
/
org-mode
mirror of https://git.savannah.gnu.org/git/emacs/org-mode.git
0
0
Fork 1
Code Releases Activity

Clarify the difference between org-indent-mode and hard indentation 

doc/org-manual.org (A Cleaner Outline View): Clarify the difference
between org-indent-mode and hard indentation.
This commit is contained in:
Nicolas Goaziou 2019-08-17 02:00:42 +02:00
parent 518691598d
commit 836f1396fc
1 changed files with 78 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
doc/org-manual.org
View File

@ -7036,7 +7036,7 @@ special command:
~org-outline-path-complete-in-steps~. If you would like to be able
to create new nodes as new parents for refiling on the fly, check
the variable ~org-refile-allow-creating-parent-nodes~. When the
variable ~org-log-refile~[fn:88] is set, a timestamp or a note is
variable ~org-log-refile~[fn:82] is set, a timestamp or a note is
recorded whenever an entry is refiled.
- {{{kbd(C-u C-c C-w)}}} ::
@ -7501,7 +7501,7 @@ Now lets look at the elements of a template definition. Each entry in
- =(file+olp+datetree "filename" [ "Level 1 heading" ...])= ::
This target[fn:82] creates a heading in a date tree[fn:83] for
This target[fn:83] creates a heading in a date tree[fn:84] for
today's date. If the optional outline path is given, the tree
will be built under the node it is pointing to, instead of at top
level. Check out the ~:time-prompt~ and ~:tree-type~ properties
@ -7607,7 +7607,7 @@ Now lets look at the elements of a template definition. Each entry in
:DESCRIPTION: Filling in information about time and context.
:END:
In the template itself, special "%-escapes"[fn:84] allow dynamic
In the template itself, special "%-escapes"[fn:85] allow dynamic
insertion of content. The templates are expanded in the order given
here:
@ -7734,7 +7734,7 @@ here:
After completing the template, position point here.
#+vindex: org-store-link-props
For specific link types, the following keywords are defined[fn:85]:
For specific link types, the following keywords are defined[fn:86]:
#+vindex: org-link-from-user-regexp
| Link type | Available keywords |
@ -7747,7 +7747,7 @@ For specific link types, the following keywords are defined[fn:85]:
| | =%:date= (message date header field) |
| | =%:date-timestamp= (date as active timestamp) |
| | =%:date-timestamp-inactive= (date as inactive timestamp) |
| | =%:fromto= (either "to NAME" or "from NAME")[fn:86] |
| | =%:fromto= (either "to NAME" or "from NAME")[fn:87] |
| gnus | =%:group=, for messages also all email fields |
| w3, w3m | =%:url= |
| info | =%:file=, =%:node= |
@ -7802,7 +7802,7 @@ By default, org-attach will use ID properties when adding attachments
to outline nodes. This makes working with attachments fully
automated. There is no decision needed for folder-name or location.
ID-based directories are by default located in the =data/= directory,
which lives in the same directory where your Org file lives[fn:87].
which lives in the same directory where your Org file lives[fn:88].
For more control over the setup, see [[*Attachment options]].
When attachments are made using ~org-attach~ a default tag =ATTACH= is
@ -19105,11 +19105,11 @@ manual, but here is a consolidated list for easy reference.
#+cindex: odd-levels-only outlines
#+cindex: clean outline view
Org's default outline with stars and no indents can become too
cluttered for short documents. For /book-like/ long documents, the
effect is not as noticeable. Org provides an alternate stars and
indentation scheme, as shown on the right in the following table. It
uses only one star and indents text to line with the heading:
Org's outline with stars and no indents can look cluttered for short
documents. For /book-like/ long documents, the effect is not as
noticeable. Org provides an alternate stars and indentation scheme,
as shown on the right in the following table. It displays only one
star and indents text to line up with the heading:
#+begin_example
,* Top level headline | * Top level headline
@ -19121,32 +19121,45 @@ uses only one star and indents text to line with the heading:
,* Another top level headline | * Another top level headline
#+end_example
Org can achieve this in two ways. (1) By just displaying the buffer
in this way without changing it (~org-indent-mode~), or (2) by
actually indenting every line in the desired amount with hard spaces
and hiding leading stars.
*** Org Indent Mode
#+cindex: Indent mode
#+findex: org-indent-mode
To turn this mode on, use the minor mode, ~org-indent-mode~. Text
lines that are not headlines are prefixed with spaces to vertically
align with the headline text[fn:148].
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:148].
#+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.
Note that turning on ~org-indent-mode~ sets ~org-hide-leading-stars~
to ~t~ and ~org-adapt-indentation~ to ~nil~.
masked with the same font color as the background[fn:149].
#+vindex: org-startup-indented
To globally turn on ~org-indent-mode~ for all files, customize the
variable ~org-startup-indented~.
To turn on indenting for individual files, use =STARTUP= keyword as
follows:
variable ~org-startup-indented~. To turn on indenting for individual
files, use =STARTUP= keyword as follows:
: #+STARTUP: indent
Indent on startup makes Org use hard spaces to align text with
headings as shown in examples below.
*** Hard indentation
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:150]. With Org's support, you have to indent all lines to
line up with the outline headers. You need these settings:
#+begin_src emacs-lisp
(setq org-adapt-indentation t
org-hide-leading-stars t
org-odd-levels-only t)
#+end_src
- /Indentation of text below headlines/ ::
@ -19160,7 +19173,7 @@ headings as shown in examples below.
#+vindex: org-adapt-indentation
Org supports this with paragraph filling, line wrapping, and
structure editing, preserving or adapting the indentation as
appropriate[fn:149].
appropriate[fn:151].
- /Hiding leading stars/ ::
@ -19193,7 +19206,7 @@ headings as shown in examples below.
#+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:150]. For Org
clutter. This removes two stars from each level[fn:152]. 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:
@ -19592,7 +19605,7 @@ these variables.
#+vindex: org-mobile-directory
The mobile application needs access to a file directory on
a server[fn:151] to interact with Emacs. Pass its location through
a server[fn:153] to interact with Emacs. Pass its location through
the ~org-mobile-directory~ variable. If you can mount that directory
locally just set the variable to point to that directory:
@ -19613,7 +19626,7 @@ With a public server, consider encrypting the files. Org also
requires OpenSSL installed on the local computer. To turn on
encryption, set the same password in the mobile application and in
Emacs. Set the password in the variable
~org-mobile-use-encryption~[fn:152]. Note that even after the mobile
~org-mobile-use-encryption~[fn:154]. Note that even after the mobile
application encrypts the file contents, the file name remains visible
on the file systems of the local computer, the server, and the mobile
device.
@ -19629,15 +19642,15 @@ The command ~org-mobile-push~ copies files listed in
~org-mobile-files~ into the staging area. Files include agenda files
(as listed in ~org-agenda-files~). Customize ~org-mobile-files~ to
add other files. File names are staged with paths relative to
~org-directory~, so all files should be inside this directory[fn:153].
~org-directory~, so all files should be inside this directory[fn:155].
Push creates a special Org file =agendas.org= with custom agenda views
defined by the user[fn:154].
defined by the user[fn:156].
Finally, Org writes the file =index.org=, containing links to other
files. The mobile application reads this file first from the server
to determine what other files to download for agendas. For faster
downloads, it is expected to only read files whose checksums[fn:155]
downloads, it is expected to only read files whose checksums[fn:157]
have changed.
*** Pulling from the mobile application
@ -19654,7 +19667,7 @@ data in an inbox file format, through the following steps:
1.
#+vindex: org-mobile-inbox-for-pull
Org moves all entries found in =mobileorg.org=[fn:156] and appends
Org moves all entries found in =mobileorg.org=[fn:158] and appends
them to the file pointed to by the variable
~org-mobile-inbox-for-pull~. It should reside neither in the
staging area nor on the server. Each captured entry and each
@ -19990,9 +20003,9 @@ of these strategies:
#+cindex: @LaTeX{}, and Orgtbl mode
To wrap a source table in LaTeX, use the =comment= environment
provided by =comment.sty=[fn:157]. To activate it, put
provided by =comment.sty=[fn:159]. To activate it, put
~\usepackage{comment}~ in the document header. Orgtbl mode inserts
a radio table skeleton[fn:158] with the command {{{kbd(M-x
a radio table skeleton[fn:160] with the command {{{kbd(M-x
orgtbl-insert-radio-table)}}}, which prompts for a table name. For
example, if =salesfigures= is the name, the template inserts:
@ -20011,7 +20024,7 @@ The line =#+ORGTBL: SEND= tells Orgtbl mode to use the function
~orgtbl-to-latex~ to convert the table to LaTeX format, then insert
the table at the target (receive) location named =salesfigures=. Now
the table is ready for data entry. It can even use spreadsheet
features[fn:159]:
features[fn:161]:
#+begin_example
% BEGIN RECEIVE ORGTBL salesfigures
@ -20228,7 +20241,7 @@ Dynamic blocks, like any other block, can be narrowed with
#+vindex: org-agenda-skip-function
#+vindex: org-agenda-skip-function-global
Org provides a special hook to further limit items in agenda views:
~agenda~, ~agenda*~[fn:160], ~todo~, ~alltodo~, ~tags~, ~tags-todo~,
~agenda~, ~agenda*~[fn:162], ~todo~, ~alltodo~, ~tags~, ~tags-todo~,
~tags-tree~. Specify a custom function that tests inclusion of every
matched item in the view. This function can also skip as much as is
needed.
@ -20271,7 +20284,7 @@ meaningful string suitable for the agenda view.
#+vindex: org-agenda-skip-function
Search for entries with a limit set on levels for the custom search.
This is a general approach to creating custom searches in Org. To
include all levels, use =LEVEL>0=[fn:161]. Then to selectively pick
include all levels, use =LEVEL>0=[fn:163]. Then to selectively pick
the matched entries, use ~org-agenda-skip-function~, which also
accepts Lisp forms, such as ~org-agenda-skip-entry-if~ and
~org-agenda-skip-subtree-if~. For example:
@ -21457,33 +21470,33 @@ On other systems, idle time refers to Emacs idle time only.
[fn:81] Please note the pitfalls of summing hierarchical data in
a flat list (see [[*Using Column View in the Agenda]]).
[fn:82] Org used to offer four different targets for date/week tree
[fn:82] Note the corresponding =STARTUP= options =logrefile=,
=lognoterefile=, and =nologrefile=.
[fn:83] Org used to offer four different targets for date/week tree
capture. Now, Org automatically translates these to use
~file+olp+datetree~, applying the ~:time-prompt~ and ~:tree-type~
properties. Please rewrite your date/week-tree targets using
~file+olp+datetree~ since the older targets are now deprecated.
[fn:83] A date tree is an outline structure with years on the highest
[fn:84] A date tree is an outline structure with years on the highest
level, months or ISO weeks as sublevels and then dates on the lowest
level. Tags are allowed in the tree structure.
[fn:84] If you need one of these sequences literally, escape the =%=
[fn:85] If you need one of these sequences literally, escape the =%=
with a backslash.
[fn:85] If you define your own link types (see [[*Adding Hyperlink
[fn:86] If you define your own link types (see [[*Adding Hyperlink
Types]]), any property you store with ~org-store-link-props~ can be
accessed in capture templates in a similar way.
[fn:86] This is always the other, not the user. See the variable
[fn:87] This is always the other, not the user. See the variable
~org-link-from-user-regexp~.
[fn:87] If you move entries or Org files from one directory to
[fn:88] If you move entries or Org files from one directory to
another, you may want to configure ~org-attach-id-dir~ to contain
an absolute path.
[fn:88] Note the corresponding =STARTUP= options =logrefile=,
=lognoterefile=, and =nologrefile=.
[fn:89] If the value of that variable is not a list, but a single file
name, then the list of agenda files in maintained in that external
file.
@ -21713,40 +21726,46 @@ for indenting and wrapping long lines of headlines or text. This
minor mode handles ~visual-line-mode~ and directly applied settings
through ~word-wrap~.
[fn:149] Also see the variable ~org-adapt-indentation~.
[fn:149] Note that turning on ~org-indent-mode~ sets
~org-hide-leading-stars~ to ~t~ and ~org-adapt-indentation~ to ~nil~.
[fn:150] Because =LEVEL=2= has 3 stars, =LEVEL=3= has 5 stars, and so
[fn:150] This works, but requires extra effort. Org Indent mode is
more convenient for most applications.
[fn:151] Also see the variable ~org-adapt-indentation~.
[fn:152] Because =LEVEL=2= has 3 stars, =LEVEL=3= has 5 stars, and so
on.
[fn:151] For a server to host files, consider using a WebDAV server,
[fn:153] 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]].
[fn:152] If Emacs is configured for safe storing of passwords, then
[fn:154] If Emacs is configured for safe storing of passwords, then
configure the variable ~org-mobile-encryption-password~; please read
the docstring of that variable.
[fn:153] Symbolic links in ~org-directory~ need to have the same name
[fn:155] Symbolic links in ~org-directory~ need to have the same name
as their targets.
[fn:154] While creating the agendas, Org mode forces =ID= properties
[fn:156] While creating the agendas, Org mode forces =ID= properties
on all referenced entries, so that these entries can be uniquely
identified if Org Mobile flags them for further action. To avoid
setting properties configure the variable
~org-mobile-force-id-on-agenda-items~ to ~nil~. Org mode then relies
on outline paths, assuming they are unique.
[fn:155] Checksums are stored automatically in the file
[fn:157] Checksums are stored automatically in the file
=checksums.dat=.
[fn:156] The file will be empty after this operation.
[fn:158] The file will be empty after this operation.
[fn:157] https://www.ctan.org/pkg/comment
[fn:159] https://www.ctan.org/pkg/comment
[fn:158] By default this works only for LaTeX, HTML, and Texinfo.
[fn:160] By default this works only for LaTeX, HTML, and Texinfo.
Configure the variable ~orgtbl-radio-table-templates~ to install
templates for other modes.
[fn:159] If the =TBLFM= keyword contains an odd number of dollar
[fn:161] If the =TBLFM= keyword contains an odd number of dollar
characters, this may cause problems with Font Lock in LaTeX mode. As
shown in the example you can fix this by adding an extra line inside
the =comment= environment that is used to balance the dollar
@ -21754,9 +21773,9 @@ expressions. If you are using AUCTeX with the font-latex library,
a much better solution is to add the =comment= environment to the
variable ~LaTeX-verbatim-environments~.
[fn:160] The ~agenda*~ view is the same as ~agenda~ except that it
[fn:162] The ~agenda*~ view is the same as ~agenda~ except that it
only considers /appointments/, i.e., scheduled and deadline items that
have a time specification =[h]h:mm= in their time-stamps.
[fn:161] Note that, for ~org-odd-levels-only~, a level number
[fn:163] Note that, for ~org-odd-levels-only~, a level number
corresponds to order in the hierarchy, not to the number of stars.