2.Orgmode Document Strucure

Posted on | In | Comments:

Org is an outliner. Outlines allow a document to be organized in a hierarchical structure, which, least for me, is the best representation of notes and thoughts. An overview of this structure is achieved by folding, i.e., hiding large parts of the document to show only the general document structure and the parts currently being worked on. Org greatly simplifies the use of outlines by compressing the entire show and hide functionalities into a single command, org-cycle, which is bound to the TAB key.

• Headlines: How to typeset Org tree headlines.
• Visibility Cycling: Show and hide, much simplified.
• Motion: Jumping to other headlines.
• Structure Editing: Changing sequence and level of headlines.
• Sparse Trees: Matches embedded in context.
• Plain Lists: Additional structure within an entry.
• Drawers: Tucking stuff away.
• Blocks: Folding blocks.
• Creating Footnotes: How footnotes are defined in Org’s syntax.

2.1 Headlines

最大的收获便是:
org-cycle-separator-lines 此功能可以控制.

Headlines define the structure of an outline tree. The headlines in Org start with one or more stars, on the left margin3. For example:

1
2
3
4
5
6
7
* Top level headline
** Second level
*** Third level
    some text
*** Third level
    more text
* Another top level headline

The name defined in org-footnote-section is reserved. Do not use it as a title for your own headings.

Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline starters. See Clean View.

An empty line after the end of a subtree is considered part of it and is hidden when the subtree is folded. However, if you leave at least two empty lines, one empty line remains visible after folding the subtree, in order to structure the collapsed view. See the variable org-cycle-separator-lines to modify this behavior.

See the variables org-special-ctrl-a/e, org-special-ctrl-k, and org-ctrl-k-protect-subtree to configure special behavior of C-a, C-e, and C-k in headlines. Note also that clocking only works with headings indented less than 30 stars.

2.2 Visibility Cycling

• Global and local cycling: Cycling through various visibility states.
• Initial visibility: Setting the initial visibility state.
• Catching invisible edits: Preventing mistakes when editing invisible parts.

2.2.1 Global and local cycling

Tab and S-Tab, 其余无关紧要.

Outlines make it possible to hide parts of the text in the buffer. Org uses just two commands, bound to TAB and S-TAB to change the visibility in the buffer.

  • TAB (org-cycle)

    Subtree cycling: Rotate current subtree among the states,

    1
    2
    3
    ,-> FOLDED -> CHILDREN -> SUBTREE --.
    '----------------------------------------------------'
    #有意思的一点, display的是subtree

    Point must be on a headline for this to work4.

  • S-TAB (org-global-cycle)

  • C-u TAB

    Global cycling: Rotate the entire buffer among the states, 

    1
    2
    3
    ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
    '---------------------------------------------------------'
    #棒呀.

    When S-TAB is called with a numeric prefix argument N, the CONTENTS view up to headlines of level N are shown. Note that inside tables (see Tables), S-TAB jumps to the previous field instead.You can run global cycling using TAB only if point is at the very beginning of the buffer, but not on a headline, and org-cycle-global-at-bob is set to a non-nil value.

    前面两个足够, 后面的用不到.

  • C-u C-u TAB (org-set-startup-visibility)

    Switch back to the startup visibility of the buffer (see Initial visibility).

  • C-u C-u C-u TAB (outline-show-all)

    Show all, including drawers.

  • C-c C-r (org-reveal)

    Reveal context around point, showing the current entry, the following heading and the hierarchy above. Useful for working near a location that has been exposed by a sparse tree command (see Sparse Trees) or an agenda command (see Agenda Commands). With a prefix argument show, on each level, all sibling headings. With a double prefix argument, also show the entire subtree of the parent.

  • C-c C-k (outline-show-branches)

    Expose all the headings of the subtree, CONTENTS view for just one subtree.

  • C-c TAB (outline-show-children)

    Expose all direct children of the subtree. With a numeric prefix argument N, expose all children down to level N.

  • C-c C-x b (org-tree-to-indirect-buffer)

    Show the current subtree in an indirect buffer5. With a numeric prefix argument, N, go up to level N and then take that tree. If N is negative then go up that many levels. With a C-u prefix, do not remove the previously used indirect buffer.

  • C-c C-x v (org-copy-visible)

    Copy the visible text in the region into the kill ring.

  1. See, however, the option org-cycle-emulate-tab.
  2. The indirect buffer contains the entire buffer, but is narrowed to the current tree. Editing the indirect buffer also changes the original buffer, but without affecting visibility in that buffer. For more information about indirect buffers, see (emacs)GNU Emacs Manual.

2.2.2 Initial visibility

When Emacs first visits an Org file, the global state is set to OVERVIEW, i.e., only the top level headlines are visible6. This can be configured through the variable org-startup-folded, or on a per-file basis by adding one of the following lines anywhere in the buffer:

1
2
3
4
#+STARTUP: overview
#+STARTUP: content
#+STARTUP: showall
#+STARTUP: showeverything

Furthermore, any entries with a ‘VISIBILITY’ property (see Properties and Columns) get their visibility adapted accordingly. Allowed values for this property are ‘folded’, ‘children’, ‘content’, and ‘all’.

  • C-u C-u TAB (org-set-startup-visibility)

    Switch back to the startup visibility of the buffer, i.e., whatever is requested by startup options and ‘VISIBILITY’ properties in individual entries.

2.2.3 Catching invisible edits

Sometimes you may inadvertently edit an invisible part of the buffer and be confused on what has been edited and how to undo the mistake. Setting org-catch-invisible-edits to non-nil helps preventing this. See the docstring of this option on how Org should catch invisible edits and process them.

2.3 Motion

The following commands jump to other headlines in the buffer.

  • C-c C-n (outline-next-visible-heading)

    Next heading.

  • C-c C-p (outline-previous-visible-heading)

    Previous heading.

  • C-c C-f (org-forward-same-level)

    Next heading same level.

  • C-c C-b (org-backward-same-level)

    Previous heading same level.

  • C-c C-u (outline-up-heading)

    Backward to higher level heading.

  • C-c C-j (org-goto)

    Jump to a different place without changing the current outline visibility. Shows the document structure in a temporary buffer, where you can use the following keys to find your destination:TABCycle visibility.DOWN / nnnnnnnnUPNext/previous visible headline.RETSelect this location./Do a Sparse-tree searchThe following keys work if you turn off org-goto-auto-isearchn / pNext/previous visible headline.f / bNext/previous headline same level.uOne level up.0 … 9Digit argument.qQuit.See also the variable org-goto-interface.

没啥用, 不必要如此精确的操作.

2.4 Structure Editing

不必要, 最基本的操作可以解决问题.

  • M-RET (org-meta-return)

    Insert a new heading, item or row.If the command is used at the beginning of a line, and if there is a heading or a plain list item (see Plain Lists) at point, the new heading/item is created before the current line. When used at the beginning of a regular line of text, turn that line into a heading.When this command is used in the middle of a line, the line is split and the rest of the line becomes the new item or headline. If you do not want the line to be split, customize org-M-RET-may-split-line.Calling the command with a C-u prefix unconditionally inserts a new heading at the end of the current subtree, thus preserving its contents. With a double C-u C-u prefix, the new heading is created at the end of the parent subtree instead.

  • C-RET (org-insert-heading-respect-content)

    Insert a new heading at the end of the current subtree.

  • M-S-RET (org-insert-todo-heading)

    Insert new TODO entry with same level as current heading. See also the variable org-treat-insert-todo-heading-as-state-change.

  • C-S-RET (org-insert-todo-heading-respect-content)

    Insert new TODO entry with same level as current heading. Like C-RET, the new headline is inserted after the current subtree.

  • TAB (org-cycle)

    In a new entry with no text yet, the first TAB demotes the entry to become a child of the previous one. The next TAB makes it a parent, and so on, all the way to top level. Yet another TAB, and you are back to the initial level.

  • M-LEFT (org-do-promote)

    Promote current heading by one level.

  • M-RIGHT (org-do-demote)

    Demote current heading by one level.

  • M-S-LEFT (org-promote-subtree)

    Promote the current subtree by one level.

  • M-S-RIGHT (org-demote-subtree)

    Demote the current subtree by one level.

  • M-UP (org-move-subtree-up)

    Move subtree up, i.e., swap with previous subtree of same level.

  • M-DOWN (org-move-subtree-down)

    Move subtree down, i.e., swap with next subtree of same level.

  • C-c @ (org-mark-subtree)

    Mark the subtree at point. Hitting repeatedly marks subsequent subtrees of the same level as the marked subtree.

  • C-c C-x C-w (org-cut-subtree)

    Kill subtree, i.e., remove it from buffer but save in kill ring. With a numeric prefix argument N, kill N sequential subtrees.

  • C-c C-x M-w (org-copy-subtree)

    Copy subtree to kill ring. With a numeric prefix argument N, copy the N sequential subtrees.

  • C-c C-x C-y (org-paste-subtree)

    Yank subtree from kill ring. This does modify the level of the subtree to make sure the tree fits in nicely at the yank position. The yank level can also be specified with a numeric prefix argument, or by yanking after a headline marker like ‘**’.

  • C-y (org-yank)

    Depending on the variables org-yank-adjusted-subtrees and org-yank-folded-subtrees, Org’s internal yank command pastes subtrees folded and in a clever way, using the same command as C-c C-x C-y. With the default settings, no level adjustment takes place, but the yanked tree is folded unless doing so would swallow text previously visible. Any prefix argument to this command forces a normal yank to be executed, with the prefix passed along. A good way to force a normal yank is C-u C-y. If you use yank-pop after a yank, it yanks previous kill items plainly, without adjustment and folding.

  • C-c C-x c (org-clone-subtree-with-time-shift)

    Clone a subtree by making a number of sibling copies of it. You are prompted for the number of copies to make, and you can also specify if any timestamps in the entry should be shifted. This can be useful, for example, to create a number of tasks related to a series of lectures to prepare. For more details, see the docstring of the command org-clone-subtree-with-time-shift.

  • C-c C-w (org-refile)

    Refile entry or region to a different location. See Refile and Copy.

  • C-c ^ (org-sort)

    Sort same-level entries. When there is an active region, all entries in the region are sorted. Otherwise the children of the current headline are sorted. The command prompts for the sorting method, which can be alphabetically, numerically, by time—first timestamp with active preferred, creation time, scheduled time, deadline time—by priority, by TODO keyword—in the sequence the keywords have been defined in the setup—or by the value of a property. Reverse sorting is possible as well. You can also supply your own function to extract the sorting key. With a C-u prefix, sorting is case-sensitive.

  • C-x n s (org-narrow-to-subtree)

    Narrow buffer to current subtree.

  • C-x n b (org-narrow-to-block)

    Narrow buffer to current block.

  • C-x n w (widen)

    Widen buffer to remove narrowing.

  • C-c * (org-toggle-heading)

    Turn a normal line or plain list item into a headline—so that it becomes a subheading at its location. Also turn a headline into a normal line by removing the stars. If there is an active region, turn all lines in the region into headlines. If the first line in the region was an item, turn only the item lines into headlines. Finally, if the first line is a headline, remove the stars from all headlines in the region.

When there is an active region—i.e., when Transient Mark mode is active—promotion and demotion work on all headlines in the region. To select a region of headlines, it is best to place both point and mark at the beginning of a line, mark at the beginning of the first headline, and point at the line just after the last headline to change. Note that when point is inside a table (see Tables), the Meta-Cursor keys have different functionality.

2.5 Sparse Trees

An important feature of Org mode is the ability to construct sparse trees for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it7. Just try it out and you will see immediately how it works.

Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher:

  • C-c / (org-sparse-tree)

    This prompts for an extra key to select a sparse-tree creating command.

  • C-c / r or C-c / / (org-occur)

    Prompts for a regexp and shows a sparse tree with all matches. If the match is in a headline, the headline is made visible. If the match is in the body of an entry, headline and body are made visible. In order to provide minimal context, also the full hierarchy of headlines above the match is shown, as well as the headline following the match. Each match is also highlighted; the highlights disappear when the buffer is changed by an editing command, or by pressing C-c C-c8. When called with a C-u prefix argument, previous highlights are kept, so several calls to this command can be stacked.

  • M-g n or M-g M-n (next-error)

    Jump to the next sparse tree match in this buffer.

  • M-g p or M-g M-p (previous-error) (M-g g就是go的含义)

    Jump to the previous sparse tree match in this buffer.

For frequently used sparse trees of specific search strings, you can use the variable org-agenda-custom-commands to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (see Agenda Dispatcher). For example:

1
2
(setq org-agenda-custom-commands
      '(("f" occur-tree "FIXME")))

defines the key f as a shortcut for creating a sparse tree matching the string ‘FIXME’.

The other sparse tree commands select headings based on TODO keywords, tags, or properties and are discussed later in this manual.

To print a sparse tree, you can use the Emacs command ps-print-buffer-with-faces which does not print invisible parts of the document. Or you can use the command C-c C-e v to export only the visible part of the document and print the resulting file.

  1. See also the variable org-show-context-detail to decide how much context is shown around each match.
  2. This depends on the option org-remove-highlights-with-change.

2.6 Plain Lists

关键的是几个转换的命令,
C-c C-* Turn全部, 尤其是checkbox, 日后将会常用

Within an entry of the outline tree, hand-formatted lists can provide additional structure. They also provide a way to create lists of checkboxes (see Checkboxes). Org supports editing such lists, and every exporter (see Exporting) can parse and format them.

Org knows ordered lists, unordered lists, and description lists.

  • Unordered list items start with ‘-’, ‘+’, or ‘*’9 as bullets.
  • Ordered list items start with a numeral followed by either a period or a right parenthesis10, such as ‘1.’ or ‘1)’11 If you want a list to start with a different value—e.g., 20—start the text of the item with ‘[@20]’12. Those constructs can be used in any item of the list in order to enforce a particular numbering.
  • Description list items are unordered list items, and contain the separator ‘::’ to distinguish the description term from the description.

Items belonging to the same list must have the same indentation on the first line. In particular, if an ordered list reaches number ‘10.’, then the 2-digit numbers must be written left-aligned with the other numbers in the list. An item ends before the next line that is less or equally indented than its bullet/number.

A list ends whenever every item has ended, which means before any line less or equally indented than items at top level. It also ends before two blank lines. In that case, all items are closed. Here is an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
* Lord of the Rings
My favorite scenes are (in this order)
1. The attack of the Rohirrim
2. Eowyn's fight with the witch king
   + this was already my favorite scene in the book
   + I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
   - on DVD only
   He makes a really funny face when it happens.
But in the end, no individual scenes matter but the film as a whole.
Important actors in this film are:
- Elijah Wood :: He plays Frodo
- Sean Astin :: He plays Sam, Frodo's friend. I still remember him
     very well from his role as Mikey Walsh in /The Goonies/.

Org supports these lists by tuning filling and wrapping commands to deal with them correctly, and by exporting them properly (see Exporting). Since indentation is what governs the structure of these lists, many structural constructs like ‘#+BEGIN_’ blocks can be indented to signal that they belong to a particular item.

If you find that using a different bullet for a sub-list—than that used for the current list-level—improves readability, customize the variable org-list-demote-modify-bullet. To get a greater difference of indentation between items and theirs sub-items, customize org-list-indent-offset.

The following commands act on items when point is in the first line of an item—the line with the bullet or number. Some of them imply the application of automatic rules to keep list structure intact. If some of these actions get in your way, configure org-list-automatic-rules to disable them individually.

  • TAB (org-cycle)

    Items can be folded just like headline levels. Normally this works only if point is on a plain list item. For more details, see the variable org-cycle-include-plain-lists. If this variable is set to integrate, plain list items are treated like low-level headlines. The level of an item is then given by the indentation of the bullet/number. Items are always subordinate to real headlines, however; the hierarchies remain completely separated. In a new item with no text yet, the first TAB demotes the item to become a child of the previous one. Subsequent TABs move the item to meaningful levels in the list and eventually get it back to its initial position.

  • M-RET (org-insert-heading)

    Insert new item at current level. With a prefix argument, force a new heading (see Structure Editing). If this command is used in the middle of an item, that item is split in two, and the second part becomes the new item13. If this command is executed before item’s body, the new item is created before the current one.

  • M-S-RET

    Insert a new item with a checkbox (see Checkboxes).

  • S-UP

  • S-DOWN

    Jump to the previous/next item in the current list, but only if org-support-shift-select is off14. If not, you can still use paragraph jumping commands like C-UP and C-DOWN to quite similar effect.

  • M-UP

  • M-DOWN

    Move the item including subitems up/down15, i.e., swap with previous/next item of same indentation. If the list is ordered, renumbering is automatic.

  • M-LEFT

  • M-RIGHT

    Decrease/increase the indentation of an item, leaving children alone.

  • M-S-LEFT

  • M-S-RIGHT

    Decrease/increase the indentation of the item, including subitems. Initially, the item tree is selected based on current indentation. When these commands are executed several times in direct succession, the initially selected region is used, even if the new indentation would imply a different hierarchy. To use the new hierarchy, break the command chain by moving point.As a special case, using this command on the very first item of a list moves the whole list. This behavior can be disabled by configuring org-list-automatic-rules. The global indentation of a list has no influence on the text after the list.

  • C-c C-c

    If there is a checkbox (see Checkboxes) in the item line, toggle the state of the checkbox. In any case, verify bullets and indentation consistency in the whole list.

  • C-c -

    Cycle the entire list level through the different itemize/enumerate bullets (‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’) or a subset of them, depending on org-plain-list-ordered-item-terminator, the type of list, and its indentation. With a numeric prefix argument N, select the Nth bullet from this list. If there is an active region when calling this, selected text is changed into an item. With a prefix argument, all lines are converted to list items. If the first line already was a list item, any item marker is removed from the list. Finally, even without an active region, a normal line is converted into a list item.

  • C-c *

    Turn a plain list item into a headline—so that it becomes a subheading at its location. See Structure Editing, for a detailed explanation.

  • C-c C-*

    Turn the whole plain list into a subtree of the current heading. Checkboxes (see Checkboxes) become TODO, respectively DONE, keywords when unchecked, respectively checked.

  • S-LEFT

  • S-RIGHT

    This command also cycles bullet styles when point is in on the bullet or anywhere in an item line, details depending on org-support-shift-select.

  • C-c ^

    Sort the plain list. Prompt for the sorting method: numerically, alphabetically, by time, or by custom function.

2.7 Drawers

最重要的基本概念之一．

Sometimes you want to keep information associated with an entry, but you normally do not want to see it. For this, Org mode has drawers. They can contain anything but a headline and another drawer. Drawers look like this:

1
2
3
4
5
6
** This is a headline
Still outside the drawer
:DRAWERNAME:
This is inside the drawer.
:END:
After the drawer.

You can interactively insert a drawer at point by calling org-insert-drawer, which is bound to C-c C-x d. With an active region, this command puts the region inside the drawer. With a prefix argument, this command calls org-insert-property-drawer, which creates a ‘PROPERTIES’ drawer right below the current headline. Org mode uses this special drawer for storing properties (seeProperties and Columns). You cannot use it for anything else.

Completion over drawer keywords is also possible using M-TAB16.

Visibility cycling (see Visibility Cycling) on the headline hides and shows the entry, but keep the drawer collapsed to a single line. In order to look inside the drawer, you need to move point to the drawer line and press TAB there.

You can also arrange for state change notes (see Tracking TODO state changes) and clock times (see Clocking Work Time) to be stored in a ‘LOGBOOK’ drawer. If you want to store a quick note there, in a similar way to state changes, use

  • C-c C-z

    Add a time-stamped note to the ‘LOGBOOK’ drawer.

    　手动插入便可．

##　2.8 Blocks

了解其formal概念是block即可.
文本编辑中的基本概念. 与HTML贯通起来.

Org mode uses ‘#+BEGIN’ … ‘#+END’ blocks for various purposes from including source code examples (see Literal Examples) to capturing time logging information (see Clocking Work Time). These blocks can be folded and unfolded by pressing TAB in the ‘#+BEGIN’ line. You can also get all blocks folded at startup by configuring the variable org-hide-block-startup or on a per-file basis by using

1
2
#+STARTUP: hideblocks
#+STARTUP: nohideblocks

2.9 Creating Footnotes

构建方式与markdown不同.

Org mode supports the creation of footnotes.

A footnote is started by a footnote marker in square brackets in column 0, no indentation allowed. It ends at the next footnote definition, headline, or after two consecutive empty lines. The footnote reference is simply the marker in square brackets, inside text. Markers always start with ‘fn:’. For example:

1
2
3
The Org homepage[fn:1] now looks a lot better than it used to.
...
[fn:1] The link is: https://orgmode.org

Org mode extends the number-based syntax to named footnotes and optional inline definition. Here are the valid references:

  • ‘[fn:NAME]’

    A named footnote reference, where NAME is a unique label word, or, for simplicity of automatic creation, a number.

  • ‘[fn:: This is the inline definition of this footnote]’

    A LaTeX-like anonymous footnote where the definition is given directly at the reference point.

  • ‘[fn:NAME: a definition]’

    An inline definition of a footnote, which also specifies a name for the note. Since Org allows multiple references to the same note, you can then use ‘[fn:NAME]’ to create additional references.

Footnote labels can be created automatically, or you can create names yourself. This is handled by the variable org-footnote-auto-label and its corresponding ‘STARTUP’ keywords. See the docstring of that variable for details.

The following command handles footnotes:

  • C-c C-x f

    The footnote action command.When point is on a footnote reference, jump to the definition. When it is at a definition, jump to the—first—reference.Otherwise, create a new footnote. Depending on the variable org-footnote-define-inline17, the definition is placed right into the text as part of the reference, or separately into the location determined by the variable org-footnote-section.When this command is called with a prefix argument, a menu of additional options is offered:sSort the footnote definitions by reference sequence.rRenumber the simple ‘fn:N’ footnotes.SShort for first r, then s action.nRename all footnotes into a ‘fn:1’ … ‘fn:n’ sequence.dDelete the footnote at point, including definition and references.Depending on the variable org-footnote-auto-adjust18, renumbering and sorting footnotes can be automatic after each insertion or deletion.

  • C-c C-c

    If point is on a footnote reference, jump to the definition. If it is at the definition, jump back to the reference. When called at a footnote location with a prefix argument, offer the same menu as C-c C-x f.

  • C-c C-o or mouse-1/2

    Footnote labels are also links to the corresponding definition or reference, and you can use the usual commands to follow these links.