7.Orgmode Properties and Columns

A property is a key-value pair associated with an entry. Properties can be set so they are associated with a single entry, with every entry in a tree, or with every entry in an Org file.

There are two main applications for properties in Org mode. First, properties are like tags, but with a value. Imagine maintaining a file where you document bugs and plan releases for a piece of software. Instead of using tags like ‘release_1’, ‘release_2’, you can use a property, say ‘Release’, that in different subtrees has different values, such as ‘1.0’ or ‘2.0’. Second, you can use properties to implement (very basic) database capabilities in an Org buffer. Imagine keeping track of your music CDs, where properties could be things such as the album, artist, date of release, number of tracks, and so on.

Properties can be conveniently edited and viewed in column view (see Column View).

• Property Syntax:	How properties are spelled out.
• Special Properties:	Access to other Org mode features.
• Property Searches:	Matching property values.
• Property Inheritance:	Passing values down a tree.
• Column View:	Tabular viewing and editing.

7.1 Property Syntax

这里先看一眼就完事.

Properties are key–value pairs. When they are associated with a single entry or with a tree they need to be inserted into a special drawer (see Drawers) with the name ‘PROPERTIES’, which has to be located right below a headline, and its planning line (see Deadlines and Scheduling) when applicable. Each property is specified on a single line, with the key—surrounded by colons—first, and the value after it. Keys are case-insensitive. Here is an example:

* CD collection
** Classic
*** Goldberg Variations
    :PROPERTIES:
    :Title:     Goldberg Variations
    :Composer:  J.S. Bach
    :Artist:    Glenn Gould
    :Publisher: Deutsche Grammophon
    :NDisks:    1
    :END:

Depending on the value of org-use-property-inheritance, a property set this way is associated either with a single entry, or with the sub-tree defined by the entry, see Property Inheritance.

You may define the allowed values for a particular property ‘Xyz’ by setting a property ‘Xyz_ALL’. This special property is inherited, so if you set it in a level 1 entry, it applies to the entire tree. When allowed values are defined, setting the corresponding property becomes easier and is less prone to typing errors. For the example with the CD collection, we can pre-define publishers and the number of disks in a box like this:

* CD collection
  :PROPERTIES:
  :NDisks_ALL:  1 2 3 4
  :Publisher_ALL: "Deutsche Grammophon" Philips EMI
  :END:

If you want to set properties that can be inherited by any entry in a file, use a line like:

#+PROPERTY: NDisks_ALL 1 2 3 4

If you want to add to the value of an existing property, append a ‘+’ to the property name. The following results in the property ‘var’ having the value ‘foo=1 bar=2’.

#+PROPERTY: var  foo=1
#+PROPERTY: var+ bar=2

It is also possible to add to the values of inherited properties. The following results in the ‘Genres’ property having the value ‘Classic Baroque’ under the ‘Goldberg Variations’ subtree.

* CD collection
** Classic
    :PROPERTIES:
    :Genres: Classic
    :END:
*** Goldberg Variations
    :PROPERTIES:
    :Title:     Goldberg Variations
    :Composer:  J.S. Bach
    :Artist:    Glenn Gould
    :Publisher: Deutsche Grammophon
    :NDisks:    1
    :Genres+:   Baroque
    :END:

Note that a property can only have one entry per drawer.

Property values set with the global variable org-global-properties can be inherited by all entries in all Org files.

The following commands help to work with properties:

• M-TAB (pcomplete)

  After an initial colon in a line, complete property keys. All keys used in the current file are offered as possible completions.

• C-c C-x p (org-set-property)

  Set a property. This prompts for a property name and a value. If necessary, the property drawer is created as well.

• C-u M-x org-insert-drawer

  Insert a property drawer into the current entry. The drawer is inserted early in the entry, but after the lines with planning information like deadlines.

• C-c C-c (org-property-action)

  With point in a property drawer, this executes property commands.

• C-c C-c s (org-set-property)

  Set a property in the current entry. Both the property and the value can be inserted using completion.

• S-RIGHT (org-property-next-allowed-values)

• S-LEFT (org-property-previous-allowed-value)

  Switch property at point to the next/previous allowed value.

• C-c C-c d (org-delete-property)

  Remove a property from the current entry.

• C-c C-c D (org-delete-property-globally)

  Globally remove a property, from all entries in the current file.

• C-c C-c c (org-compute-property-at-point)

  Compute the property at point, using the operator and scope from the nearest column format definition.

7.2 Special Properties

reserved properties, 看一样便可,

Special properties provide an alternative access method to Org mode features, like the TODO state or the priority of an entry, discussed in the previous chapters. This interface exists so that you can include these states in a column view (see Column View), or to use them in queries. The following property names are special and should not be used as keys in the properties drawer:

‘ALLTAGS’	All tags, including inherited ones.
‘BLOCKED’	t if task is currently blocked by children or siblings.
‘CATEGORY’	The category of an entry.
‘CLOCKSUM’	The sum of CLOCK intervals in the subtree. org-clock-sum
	must be run first to compute the values in the current buffer.
‘CLOCKSUM_T’	The sum of CLOCK intervals in the subtree for today.
	org-clock-sum-today must be run first to compute the
	values in the current buffer.
‘CLOSED’	When was this entry closed?
‘DEADLINE’	The deadline time string, without the angular brackets.
‘FILE’	The filename the entry is located in.
‘ITEM’	The headline of the entry.
‘PRIORITY’	The priority of the entry, a string with a single letter.
‘SCHEDULED’	The scheduling timestamp, without the angular brackets.
‘TAGS’	The tags defined directly in the headline.
‘TIMESTAMP’	The first keyword-less timestamp in the entry.
‘TIMESTAMP_IA’	The first inactive timestamp in the entry.
‘TODO’	The TODO keyword of the entry.

7.3 Property Searches

search是至关重要的一点.

To create sparse trees and special lists with selection based on properties, the same commands are used as for tag searches (see Tag Searches).

• C-c / m or C-c \ (org-match-sparse-tree)

  Create a sparse tree with all matching entries. With a C-u prefix argument, ignore headlines that are not a TODO line.

• M-x org-agenda m, org-tags-view

  Create a global list of tag/property matches from all agenda files.

• M-x org-agenda M (org-tags-view)

  Create a global list of tag matches from all agenda files, but check only TODO items and force checking of subitems (see the option org-tags-match-list-sublevels).

The syntax for the search string is described in Matching tags and properties.

There is also a special command for creating sparse trees based on a single property:

• C-c / p

  Create a sparse tree based on the value of a property. This first prompts for the name of a property, and then for a value. A sparse tree is created with all entries that define this property with the given value. If you enclose the value in curly braces, it is interpreted as a regular expression and matched against the property valu

7.4 Property Inheritance

有点意思了, 能将全部的内容打穿.

The outline structure of Org documents lends itself to an inheritance model of properties: if the parent in a tree has a certain property, the children can inherit this property. Org mode does not turn this on by default, because it can slow down property searches significantly and is often not needed. However, if you find inheritance useful, you can turn it on by setting the variable org-use-property-inheritance. It may be set to t to make all properties inherited from the parent, to a list of properties that should be inherited, or to a regular expression that matches inherited properties. If a property has the value nil, this is interpreted as an explicit un-define of the property, so that inheritance search stops at this value and returns nil.

Org mode has a few properties for which inheritance is hard-coded, at least for the special applications for which they are used:

• COLUMNS

  The ‘COLUMNS’ property defines the format of column view (see Column View). It is inherited in the sense that the level where a ‘COLUMNS’ property is defined is used as the starting point for a column view table, independently of the location in the subtree from where columns view is turned on.

• CATEGORY

  For agenda view, a category set through a ‘CATEGORY’ property applies to the entire subtree.

• ARCHIVE

  For archiving, the ‘ARCHIVE’ property may define the archive location for the entire subtree (see Moving subtrees).

• LOGGING

  The ‘LOGGING’ property may define logging settings for an entry or a subtree (see Tracking TODO state changes).

7.5 Column View

A great way to view and edit properties in an outline tree is column view. In column view, each outline node is turned into a table row. Columns in this table provide access to properties of the entries. Org mode implements columns by overlaying a tabular structure over the headline of each item. While the headlines have been turned into a table row, you can still change the visibility of the outline tree. For example, you get a compact table by switching to “contents” view—S-TAB S-TAB, or simply c while column view is active—but you can still open, read, and edit the entry below each headline. Or, you can switch to column view after executing a sparse tree command and in this way get a table only for the selected items. Column view also works in agenda buffers (see Agenda Views) where queries have collected selected items, possibly from a number of files.

• Defining columns:	The COLUMNS format property.
• Using column view:	How to create and use column view.
• Capturing column view:	A dynamic block for column view.

7.5.1 Defining columns

Setting up a column view first requires defining the columns. This is done by defining a column format line.

• Scope of column definitions:	Where defined, where valid?
• Column attributes:	Appearance and content of a column.

有点复杂, 不知道有啥用.

7.5.1.1 Scope of column definitions

To define a column format for an entire file, use a line like:

#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO

To specify a format that only applies to a specific tree, add a ‘COLUMNS’ property to the top node of that tree, for example:

** Top node for columns view
   :PROPERTIES:
   :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
   :END:

If a ‘COLUMNS’ property is present in an entry, it defines columns for the entry itself, and for the entire subtree below it. Since the column definition is part of the hierarchical structure of the document, you can define columns on level 1 that are general enough for all sublevels, and more specific columns further down, when you edit a deeper part of the tree.

7.5.1.2 Column attributes

A column definition sets the attributes of a column. The general definition looks like this:

%[WIDTH]PROPERTY[(TITLE)][{SUMMARY-TYPE}]

Except for the percent sign and the property name, all items are optional. The individual parts have the following meaning:

• WIDTH

  An integer specifying the width of the column in characters. If omitted, the width is determined automatically.

• PROPERTY

  The property that should be edited in this column. Special properties representing meta data are allowed here as well (see Special Properties).

• TITLE

  The header text for the column. If omitted, the property name is used.

• SUMMARY-TYPE

  The summary type. If specified, the column values for parent nodes are computed from the children57.Supported summary types are:‘+’Sum numbers in this column.‘+;%.1f’Like ‘+’, but format result with ‘%.1f’.‘$’Currency, short for ‘+;%.2f’.‘min’Smallest number in column.‘max’Largest number.‘mean’Arithmetic mean of numbers.‘X’Checkbox status, ‘[X]’ if all children are ‘[X]’.‘X/’Checkbox status, ‘[n/m]’.‘X%’Checkbox status, ‘[n%]’.‘:’Sum times, HH:MM, plain numbers are hours.‘:min’Smallest time value in column.‘:max’Largest time value.‘:mean’Arithmetic mean of time values.‘@min’Minimum age58 (in days/hours/mins/seconds).‘@max’Maximum age (in days/hours/mins/seconds).‘@mean’Arithmetic mean of ages (in days/hours/mins/seconds).‘est+’Add low-high estimates.You can also define custom summary types by setting org-columns-summary-types.

The ‘est+’ summary type requires further explanation. It is used for combining estimates, expressed as low-high ranges. For example, instead of estimating a particular task will take 5 days, you might estimate it as 5–6 days if you’re fairly confident you know how much work is required, or 1–10 days if you do not really know what needs to be done. Both ranges average at 5.5 days, but the first represents a more predictable delivery.

When combining a set of such estimates, simply adding the lows and highs produces an unrealistically wide result. Instead, ‘est+’ adds the statistical mean and variance of the subtasks, generating a final estimate from the sum. For example, suppose you had ten tasks, each of which was estimated at 0.5 to 2 days of work. Straight addition produces an estimate of 5 to 20 days, representing what to expect if everything goes either extremely well or extremely poorly. In contrast, ‘est+’ estimates the full job more realistically, at 10–15 days.

Here is an example for a complete columns definition, along with allowed values59.

:COLUMNS:  %25ITEM %9Approved(Approved?){X} %Owner %11Status \
                   %10Time_Estimate{:} %CLOCKSUM %CLOCKSUM_T
:Owner_ALL:    Tammy Mark Karl Lisa Don
:Status_ALL:   "In progress" "Not started yet" "Finished" ""
:Approved_ALL: "[ ]" "[X]"

The first column, ‘%25ITEM’, means the first 25 characters of the item itself, i.e., of the headline. You probably always should start the column definition with the ‘ITEM’ specifier. The other specifiers create columns ‘Owner’ with a list of names as allowed values, for ‘Status’ with four different possible values, and for a checkbox field ‘Approved’. When no width is given after the ‘%’ character, the column is exactly as wide as it needs to be in order to fully display all values. The ‘Approved’ column does have a modified title (‘Approved?’, with a question mark). Summaries are created for the ‘Time_Estimate’ column by adding time duration expressions like HH:MM, and for the ‘Approved’ column, by providing an ‘[X]’ status if all children have been checked. The ‘CLOCKSUM’ and ‘CLOCKSUM_T’ columns are special, they lists the sums of CLOCK intervals in the subtree, either for all clocks or just for today.

7.5.2 Using column view

平白叙述, 没有应用实例.

Turning column view on or off

• C-c C-x C-c (org-columns)

  Turn on column view. If point is before the first headline in the file, column view is turned on for the entire file, using the ‘#+COLUMNS’ definition. If point is somewhere inside the outline, this command searches the hierarchy, up from point, for a ‘COLUMNS’ property that defines a format. When one is found, the column view table is established for the tree starting at the entry that contains the ‘COLUMNS’ property. If no such property is found, the format is taken from the ‘#+COLUMNS’ line or from the variable org-columns-default-format, and column view is established for the current entry and its subtree.

• r or g (org-columns-redo)

  Recreate the column view, to include recent changes made in the buffer.

• q (org-columns-quit)

  Exit column view.

Editing values

• LEFT, RIGHT, UP, DOWN

  Move through the column view from field to field.

• 1..9,0

  Directly select the Nth allowed value, 0 selects the 10th value.

• n or S-RIGHT (org-columns-next-allowed-value)

• p or S-LEFT (org-columns-previous-allowed-value)

  Switch to the next/previous allowed value of the field. For this, you have to have specified allowed values for a property.

• e (org-columns-edit-value)

  Edit the property at point. For the special properties, this invokes the same interface that you normally use to change that property. For example, the tag completion or fast selection interface pops up when editing a ‘TAGS’ property.

• C-c C-c (org-columns-set-tags-or-toggle)
  n
  When there is a checkbox at point, toggle it.

• v (org-columns-show-value)

  View the full value of this property. This is useful if the width of the column is smaller than that of the value.

• a (org-columns-edit-allowed)

  Edit the list of allowed values for this property. If the list is found in the hierarchy, the modified values is stored there. If no list is found, the new value is stored in the first entry that is part of the current column view.

Modifying column view on-the-fly

• < (org-columns-narrow)

• (org-columns-widen)

  Make the column narrower/wider by one character.

• S-M-RIGHT (org-columns-new)

  Insert a new column, to the left of the current column.

• S-M-LEFT (org-columns-delete)

  Delete the current column.

7.5.3 Capturing column view

弄得这么负责, 有啥鸟用.

Since column view is just an overlay over a buffer, it cannot be exported or printed directly. If you want to capture a column view, use a ‘columnview’ dynamic block (see Dynamic Blocks). The frame of this block looks like this:

* The column view
#+BEGIN: columnview :hlines 1 :id "label"
#+END:

This dynamic block has the following parameters:

• ‘:id’

  This is the most important parameter. Column view is a feature that is often localized to a certain (sub)tree, and the capture block might be at a different location in the file. To identify the tree whose view to capture, you can use four values:‘local’Use the tree in which the capture block is located.‘global’Make a global view, including all headings in the file.‘file:FILENAME’Run column view at the top of the FILENAME file.‘LABEL’Call column view in the tree that has an ‘ID’ property with the value LABEL. You can use M-x org-id-copy to create a globally unique ID for the current entry and copy it to the kill-ring.

• ‘:hlines’

  When t, insert an hline after every line. When a number N, insert an hline before each headline with level <= N.

• ‘:vlines’

  When non-nil, force column groups to get vertical lines.

• ‘:maxlevel’

  When set to a number, do not capture entries below this level.

• ‘:skip-empty-rows’

  When non-nil, skip rows where the only non-empty specifier of the column view is ‘ITEM’.

• ‘:indent’

  When non-nil, indent each ‘ITEM’ field according to its level.

• ‘:format’

  Specify a column attribute (see Column attributes) for the dynamic block.

The following commands insert or update the dynamic block:

• C-c C-x i (org-insert-columns-dblock)

  Insert a dynamic block capturing a column view. Prompt for the scope or ID of the view.

• C-c C-c C-c C-x C-u (org-dblock-update)

  Update dynamic block at point. point needs to be in the ‘#+BEGIN’ line of the dynamic block.

• C-u C-c C-x C-u (org-update-all-dblocks)

  Update all dynamic blocks (see Dynamic Blocks). This is useful if you have several clock table blocks, column-capturing blocks or other dynamic blocks in a buffer.

You can add formulas to the column view table and you may add plotting instructions in front of the table—these survive an update of the block. If there is a ‘TBLFM’ keyword after the table, the table is recalculated automatically after an update.

An alternative way to capture and process property values into a table is provided by Eric Schulte’s ‘org-collector.el’, which is a contributed package60. It provides a general API to collect properties from entries in a certain scope, and arbitrary Lisp expressions to process these values before inserting them into a table or a dynamic block.