Mercurial > emacs
comparison doc/misc/org.texi @ 87836:22ad67b23797
(Property inheritance): New section
(Conventions): New section.
(Structure editing): Document C-RET, the prefix arg to the cut/cpy
commands, and the new bindings for refiling.
(Sparse trees): Document the new special command for sparse trees.
(References): Be more clear about the counting of hilines.
(Handling links): Document M-p/n for accessing links.
(Fast access to TODO states): New section.
(Per file keywords): New section.
(Property inheritance): New section.
(Column attributes): New summary types.
(Capturing Column View): New section.
(The date/time prompt): Cover the new features in the date/time
prompt. Compactify the table of keys for the calendar remote
control.
(Clocking work time): Document the new :scope parameter.
(Remember): Promoted to chapter.
(Quoted examples): New section.
(Enhancing text): New verbatim environments.
author | Carsten Dominik <dominik@science.uva.nl> |
---|---|
date | Fri, 18 Jan 2008 15:18:01 +0000 |
parents | 3d431f1997d8 |
children | f991f10f15ec |
comparison
equal
deleted
inserted
replaced
87835:4180a8a753f6 | 87836:22ad67b23797 |
---|---|
1 \input texinfo | 1 \input texinfo |
2 @c %**start of header | 2 @c %**start of header |
3 @setfilename ../../info/org | 3 @setfilename ../../info/org |
4 @settitle Org Mode Manual | 4 @settitle Org Mode Manual |
5 | 5 |
6 @set VERSION 5.07 | 6 @set VERSION 5.19 |
7 @set DATE August 2007 | 7 @set DATE January 2008 |
8 | 8 |
9 @dircategory Emacs | 9 @dircategory Emacs |
10 @direntry | 10 @direntry |
11 * Org Mode: (org). Outline-based notes management and organizer | 11 * Org Mode: (org). Outline-based notes management and organizer |
12 @end direntry | 12 @end direntry |
13 | 13 |
14 @c Version and Contact Info | 14 @c Version and Contact Info |
15 @set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage} | 15 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} |
16 @set AUTHOR Carsten Dominik | 16 @set AUTHOR Carsten Dominik |
17 @set MAINTAINER Carsten Dominik | 17 @set MAINTAINER Carsten Dominik |
18 @set MAINTAINEREMAIL @email{dominik at science dot uva dot nl} | 18 @set MAINTAINEREMAIL @email{carsten at orgmode dot org} |
19 @set MAINTAINERCONTACT @uref{mailto:dominik at science dot uva dot nl,contact the maintainer} | 19 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} |
20 @c %**end of header | 20 @c %**end of header |
21 @finalout | 21 @finalout |
22 | 22 |
23 @c Macro definitions | 23 @c Macro definitions |
24 | 24 |
33 @end macro | 33 @end macro |
34 | 34 |
35 @copying | 35 @copying |
36 This manual is for Org-mode (version @value{VERSION}). | 36 This manual is for Org-mode (version @value{VERSION}). |
37 | 37 |
38 Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation | 38 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 Free Software Foundation |
39 | 39 |
40 @quotation | 40 @quotation |
41 Permission is granted to copy, distribute and/or modify this document | 41 Permission is granted to copy, distribute and/or modify this document |
42 under the terms of the GNU Free Documentation License, Version 1.1 or | 42 under the terms of the GNU Free Documentation License, Version 1.1 or |
43 any later version published by the Free Software Foundation; with no | 43 any later version published by the Free Software Foundation; with no |
79 * Document structure:: A tree works like your brain | 79 * Document structure:: A tree works like your brain |
80 * Tables:: Pure magic for quick formatting | 80 * Tables:: Pure magic for quick formatting |
81 * Hyperlinks:: Notes in context | 81 * Hyperlinks:: Notes in context |
82 * TODO items:: Every tree branch can be a TODO item | 82 * TODO items:: Every tree branch can be a TODO item |
83 * Tags:: Tagging headlines and matching sets of tags | 83 * Tags:: Tagging headlines and matching sets of tags |
84 * Properties and columns:: | 84 * Properties and columns:: Storing information about an entry |
85 * Timestamps:: Assign date and time to items | 85 * Dates and times:: Making items useful for planning |
86 * Remember:: Quickly adding nodes to the outline tree | |
86 * Agenda views:: Collecting information into views | 87 * Agenda views:: Collecting information into views |
87 * Embedded LaTeX:: LaTeX fragments and formulas | 88 * Embedded LaTeX:: LaTeX fragments and formulas |
88 * Exporting:: Sharing and publishing of notes | 89 * Exporting:: Sharing and publishing of notes |
89 * Publishing:: Create a web site of linked Org-mode files | 90 * Publishing:: Create a web site of linked Org-mode files |
90 * Miscellaneous:: All the rest which did not fit elsewhere | 91 * Miscellaneous:: All the rest which did not fit elsewhere |
91 * Extensions and Hacking:: It is possible to write add-on code | 92 * Extensions and Hacking:: It is possible to write add-on code |
92 * History and Acknowledgments:: How Org-mode came into being | 93 * History and Acknowledgments:: How Org-mode came into being |
93 * Index:: The fast road to specific information | 94 * Main Index:: |
94 * Key Index:: Key bindings and where they are described | 95 * Key Index:: Key bindings and where they are described |
95 | 96 |
96 @detailmenu | 97 @detailmenu |
97 --- The Detailed Node Listing --- | 98 --- The Detailed Node Listing --- |
98 | 99 |
100 | 101 |
101 * Summary:: Brief summary of what Org-mode does | 102 * Summary:: Brief summary of what Org-mode does |
102 * Installation:: How to install a downloaded version of Org-mode | 103 * Installation:: How to install a downloaded version of Org-mode |
103 * Activation:: How to activate Org-mode for certain buffers. | 104 * Activation:: How to activate Org-mode for certain buffers. |
104 * Feedback:: Bug reports, ideas, patches etc. | 105 * Feedback:: Bug reports, ideas, patches etc. |
106 * Conventions:: Type-setting conventions in the manual | |
105 | 107 |
106 Document Structure | 108 Document Structure |
107 | 109 |
108 * Outlines:: Org-mode is based on outline-mode | 110 * Outlines:: Org-mode is based on outline-mode |
109 * Headlines:: How to typeset org-tree headlines | 111 * Headlines:: How to typeset org-tree headlines |
148 * Handling links:: Creating, inserting and following | 150 * Handling links:: Creating, inserting and following |
149 * Using links outside Org-mode:: Linking from my C source code? | 151 * Using links outside Org-mode:: Linking from my C source code? |
150 * Link abbreviations:: Shortcuts for writing complex links | 152 * Link abbreviations:: Shortcuts for writing complex links |
151 * Search options:: Linking to a specific location | 153 * Search options:: Linking to a specific location |
152 * Custom searches:: When the default search is not enough | 154 * Custom searches:: When the default search is not enough |
153 * Remember:: Org-trees store quick notes | |
154 | 155 |
155 Internal links | 156 Internal links |
156 | 157 |
157 * Radio targets:: Make targets trigger links in plain text. | 158 * Radio targets:: Make targets trigger links in plain text. |
159 | |
160 TODO items | |
161 | |
162 * TODO basics:: Marking and displaying TODO entries | |
163 * TODO extensions:: Workflow and assignments | |
164 * Progress logging:: Dates and notes for progress | |
165 * Priorities:: Some things are more important than others | |
166 * Breaking down tasks:: Splitting a task into manageable pieces | |
167 * Checkboxes:: Tick-off lists | |
168 | |
169 Extended use of TODO keywords | |
170 | |
171 * Workflow states:: From TODO to DONE in steps | |
172 * TODO types:: I do this, Fred does the rest | |
173 * Multiple sets in one file:: Mixing it all, and still finding your way | |
174 * Fast access to TODO states:: Single letter selection of a state | |
175 * Per-file keywords:: Different files, different requirements | |
176 * Faces for TODO keywords:: Highlighting states | |
177 | |
178 Progress Logging | |
179 | |
180 * Closing items:: When was this entry marked DONE? | |
181 * Tracking TODO state changes:: When did the status change? | |
182 | |
183 Tags | |
184 | |
185 * Tag inheritance:: Tags use the tree structure of the outline | |
186 * Setting tags:: How to assign tags to a headline | |
187 * Tag searches:: Searching for combinations of tags | |
188 | |
189 Properties and Columns | |
190 | |
191 * Property syntax:: How properties are spelled out | |
192 * Special properties:: Access to other Org-mode features | |
193 * Property searches:: Matching property values | |
194 * Property inheritance:: Passing values down the tree | |
195 * Column view:: Tabular viewing and editing | |
196 * Property API:: Properties for Lisp programmers | |
197 | |
198 Column View | |
199 | |
200 * Defining columns:: The COLUMNS format property | |
201 * Using column view:: How to create and use column view | |
202 * Capturing Column View:: A dynamic block for column view | |
203 | |
204 Defining Columns | |
205 | |
206 * Scope of column definitions:: Where defined, where valid? | |
207 * Column attributes:: Appearance and content of a column | |
208 | |
209 Dates and Times | |
210 | |
211 * Time stamps:: Assigning a time to a tree entry | |
212 * Creating timestamps:: Commands which insert timestamps | |
213 * Deadlines and scheduling:: Planning your work | |
214 * Clocking work time:: | |
215 | |
216 Creating timestamps | |
217 | |
218 * The date/time prompt:: How org-mode helps you entering date and time | |
219 * Custom time format:: Making dates look differently | |
220 | |
221 Deadlines and Scheduling | |
222 | |
223 * Inserting deadline/schedule:: Planning items | |
224 * Repeated tasks:: Items that show up again and again | |
158 | 225 |
159 Remember | 226 Remember |
160 | 227 |
161 * Setting up remember:: Some code for .emacs to get things going | 228 * Setting up remember:: Some code for .emacs to get things going |
162 * Remember templates:: Define the outline of different note types | 229 * Remember templates:: Define the outline of different note types |
163 * Storing notes:: Directly get the note to where it belongs | 230 * Storing notes:: Directly get the note to where it belongs |
164 | 231 * Refiling notes:: Moving a note or task to a project |
165 TODO items | |
166 | |
167 * TODO basics:: Marking and displaying TODO entries | |
168 * TODO extensions:: Workflow and assignments | |
169 * Priorities:: Some things are more important than others | |
170 * Breaking down tasks:: Splitting a task into manageable pieces | |
171 * Checkboxes:: Tick-off lists | |
172 | |
173 Extended use of TODO keywords | |
174 | |
175 * Workflow states:: From TODO to DONE in steps | |
176 * TODO types:: I do this, Fred the rest | |
177 * Multiple sets in one file:: Mixing it all, and still finding your way | |
178 * Per file keywords:: Different files, different requirements | |
179 | |
180 Tags | |
181 | |
182 * Tag inheritance:: Tags use the tree structure of the outline | |
183 * Setting tags:: How to assign tags to a headline | |
184 * Tag searches:: Searching for combinations of tags | |
185 | |
186 Properties and Columns | |
187 | |
188 * Property syntax:: How properties are spelled out | |
189 * Special properties:: Access to other Org-mode features | |
190 * Property searches:: Matching property values | |
191 * Column view:: Tabular viewing and editing | |
192 * Property API:: Properties for Lisp programmers | |
193 | |
194 Column View | |
195 | |
196 * Defining columns:: The COLUMNS format property | |
197 * Using column view:: How to create and use column view | |
198 | |
199 Defining Columns | |
200 | |
201 * Scope of column definitions:: Where defined, where valid? | |
202 * Column attributes:: Appearance and content of a column | |
203 | |
204 Timestamps | |
205 | |
206 * Time stamps:: Assigning a time to a tree entry | |
207 * Creating timestamps:: Commands which insert timestamps | |
208 * Deadlines and scheduling:: Planning your work | |
209 * Progress logging:: Documenting when what work was done. | |
210 | |
211 Creating timestamps | |
212 | |
213 * The date/time prompt:: How org-mode helps you entering date and time | |
214 * Custom time format:: Making dates look differently | |
215 | |
216 Deadlines and Scheduling | |
217 | |
218 * Inserting deadline/schedule:: Planning items | |
219 * Repeated tasks:: Items that show up again and again | |
220 | |
221 Progress Logging | |
222 | |
223 * Closing items:: When was this entry marked DONE? | |
224 * Tracking TODO state changes:: When did the status change? | |
225 * Clocking work time:: When exactly did you work on this item? | |
226 | 232 |
227 Agenda Views | 233 Agenda Views |
228 | 234 |
229 * Agenda files:: Files being searched for agenda information | 235 * Agenda files:: Files being searched for agenda information |
230 * Agenda dispatcher:: Keyboard access to agenda views | 236 * Agenda dispatcher:: Keyboard access to agenda views |
282 | 288 |
283 LaTeX export | 289 LaTeX export |
284 | 290 |
285 * LaTeX export commands:: How to invoke LaTeX export | 291 * LaTeX export commands:: How to invoke LaTeX export |
286 * Quoting LaTeX code:: Incorporating literal LaTeX code | 292 * Quoting LaTeX code:: Incorporating literal LaTeX code |
293 * Sectioning structure:: | |
287 | 294 |
288 Text interpretation by the exporter | 295 Text interpretation by the exporter |
289 | 296 |
290 * Comment lines:: Some lines will not be exported | 297 * Comment lines:: Some lines will not be exported |
291 * Initial text:: Text before the first headline | 298 * Initial text:: Text before the first headline |
292 * Footnotes:: Numbers like [1] | 299 * Footnotes:: Numbers like [1] |
300 * Quoted examples:: Inserting quoted chnuks of text | |
293 * Enhancing text:: Subscripts, symbols and more | 301 * Enhancing text:: Subscripts, symbols and more |
294 * Export options:: How to influence the export settings | 302 * Export options:: How to influence the export settings |
295 | 303 |
296 Publishing | 304 Publishing |
297 | 305 |
337 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs | 345 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs |
338 * Dynamic blocks:: Automatically filled blocks | 346 * Dynamic blocks:: Automatically filled blocks |
339 * Special agenda views:: Customized views | 347 * Special agenda views:: Customized views |
340 * Using the property API:: Writing programs that use entry properties | 348 * Using the property API:: Writing programs that use entry properties |
341 | 349 |
342 Tables in arbitrary syntax | 350 Tables and Lists in arbitrary syntax |
343 | 351 |
344 * Radio tables:: Sending and receiving | 352 * Radio tables:: Sending and receiving |
345 * A LaTeX example:: Step by step, almost a tutorial | 353 * A LaTeX example:: Step by step, almost a tutorial |
346 * Translator functions:: Copy and modify | 354 * Translator functions:: Copy and modify |
355 * Radio lists:: Doing the same for lists. | |
347 | 356 |
348 @end detailmenu | 357 @end detailmenu |
349 @end menu | 358 @end menu |
350 | 359 |
351 @node Introduction, Document structure, Top, Top | 360 @node Introduction, Document structure, Top, Top |
355 @menu | 364 @menu |
356 * Summary:: Brief summary of what Org-mode does | 365 * Summary:: Brief summary of what Org-mode does |
357 * Installation:: How to install a downloaded version of Org-mode | 366 * Installation:: How to install a downloaded version of Org-mode |
358 * Activation:: How to activate Org-mode for certain buffers. | 367 * Activation:: How to activate Org-mode for certain buffers. |
359 * Feedback:: Bug reports, ideas, patches etc. | 368 * Feedback:: Bug reports, ideas, patches etc. |
369 * Conventions:: Type-setting conventions in the manual | |
360 @end menu | 370 @end menu |
361 | 371 |
362 @node Summary, Installation, Introduction, Introduction | 372 @node Summary, Installation, Introduction, Introduction |
363 @section Summary | 373 @section Summary |
364 @cindex summary | 374 @cindex summary |
375 time stamps, and scheduling. It dynamically compiles entries into an | 385 time stamps, and scheduling. It dynamically compiles entries into an |
376 agenda that utilizes and smoothly integrates much of the Emacs calendar | 386 agenda that utilizes and smoothly integrates much of the Emacs calendar |
377 and diary. Plain text URL-like links connect to websites, emails, | 387 and diary. Plain text URL-like links connect to websites, emails, |
378 Usenet messages, BBDB entries, and any files related to the projects. | 388 Usenet messages, BBDB entries, and any files related to the projects. |
379 For printing and sharing of notes, an Org-mode file can be exported as a | 389 For printing and sharing of notes, an Org-mode file can be exported as a |
380 structured ASCII file, as HTML, or (todo and agenda items only) as an | 390 structured ASCII file, as HTML, or (TODO and agenda items only) as an |
381 iCalendar file. It can also serve as a publishing tool for a set of | 391 iCalendar file. It can also serve as a publishing tool for a set of |
382 linked webpages. | 392 linked webpages. |
383 | 393 |
384 An important design aspect that distinguishes Org-mode from for example | 394 An important design aspect that distinguishes Org-mode from for example |
385 Planner/Muse is that it encourages to store every piece of information | 395 Planner/Muse is that it encourages to store every piece of information |
402 @r{@bullet{} ASCII table editor with spreadsheet-like capabilities} | 412 @r{@bullet{} ASCII table editor with spreadsheet-like capabilities} |
403 @r{@bullet{} TODO list editor} | 413 @r{@bullet{} TODO list editor} |
404 @r{@bullet{} full agenda and planner with deadlines and work scheduling} | 414 @r{@bullet{} full agenda and planner with deadlines and work scheduling} |
405 @r{@bullet{} environment to implement David Allen's GTD system} | 415 @r{@bullet{} environment to implement David Allen's GTD system} |
406 @r{@bullet{} a basic database application} | 416 @r{@bullet{} a basic database application} |
407 @r{@bullet{} simple hypertext system, with HTML export} | 417 @r{@bullet{} simple hypertext system, with HTML and LaTeX export} |
408 @r{@bullet{} publishing tool to create a set of interlinked webpages} | 418 @r{@bullet{} publishing tool to create a set of interlinked webpages} |
409 @end example | 419 @end example |
410 | 420 |
411 Org-mode's automatic, context sensitive table editor with spreadsheet | 421 Org-mode's automatic, context sensitive table editor with spreadsheet |
412 capabilities can be integrated into any major mode by activating the | 422 capabilities can be integrated into any major mode by activating the |
417 | 427 |
418 @cindex FAQ | 428 @cindex FAQ |
419 There is a website for Org-mode which provides links to the newest | 429 There is a website for Org-mode which provides links to the newest |
420 version of Org-mode, as well as additional information, frequently asked | 430 version of Org-mode, as well as additional information, frequently asked |
421 questions (FAQ), links to tutorials etc. This page is located at | 431 questions (FAQ), links to tutorials etc. This page is located at |
422 @uref{http://www.astro.uva.nl/~dominik/Tools/org/}. | 432 @uref{http://orgmode.org}. |
423 | 433 |
424 @page | 434 @page |
425 | 435 |
426 | 436 |
427 @node Installation, Activation, Summary, Introduction | 437 @node Installation, Activation, Summary, Introduction |
522 | 532 |
523 @noindent which will select Org-mode for this buffer no matter what | 533 @noindent which will select Org-mode for this buffer no matter what |
524 the file's name is. See also the variable | 534 the file's name is. See also the variable |
525 @code{org-insert-mode-line-in-empty-file}. | 535 @code{org-insert-mode-line-in-empty-file}. |
526 | 536 |
527 @node Feedback, , Activation, Introduction | 537 @node Feedback, Conventions, Activation, Introduction |
528 @section Feedback | 538 @section Feedback |
529 @cindex feedback | 539 @cindex feedback |
530 @cindex bug reports | 540 @cindex bug reports |
531 @cindex maintainer | 541 @cindex maintainer |
532 @cindex author | 542 @cindex author |
578 @item | 588 @item |
579 When you hit the error, a @file{*Backtrace*} buffer will appear on the | 589 When you hit the error, a @file{*Backtrace*} buffer will appear on the |
580 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and | 590 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and |
581 attach it to your bug report. | 591 attach it to your bug report. |
582 @end enumerate | 592 @end enumerate |
593 | |
594 @node Conventions, , Feedback, Introduction | |
595 @section Typesetting conventions used in this manual | |
596 | |
597 Org-mode uses three types of keywords: TODO keywords, tags, and property | |
598 names. In this manual we use the following conventions: | |
599 | |
600 @table @code | |
601 @item TODO | |
602 @itemx WAITING | |
603 TODO keywords are written with all capitals, even if they are | |
604 user-defined. | |
605 @item boss | |
606 @itemx ARCHIVE | |
607 User-defined tags are written in lowercase; built-in tags with special | |
608 meaning are written with all capitals. | |
609 @item Release | |
610 @itemx PRIORITY | |
611 User-defined properties are capitalized; built-in properties with | |
612 special meaning are written with all capitals. | |
613 @end table | |
583 | 614 |
584 @node Document structure, Tables, Introduction, Top | 615 @node Document structure, Tables, Introduction, Top |
585 @chapter Document Structure | 616 @chapter Document Structure |
586 @cindex document structure | 617 @cindex document structure |
587 @cindex structure of document | 618 @cindex structure of document |
706 Show all. | 737 Show all. |
707 @kindex C-c C-r | 738 @kindex C-c C-r |
708 @item C-c C-r | 739 @item C-c C-r |
709 Reveal context around point, showing the current entry, the following | 740 Reveal context around point, showing the current entry, the following |
710 heading and the hierarchy above. Useful for working near a location | 741 heading and the hierarchy above. Useful for working near a location |
711 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda | 742 that has been exposed by a sparse tree command (@pxref{Sparse trees}) or |
712 command (@pxref{Agenda commands}). With prefix arg show, on each | 743 an agenda command (@pxref{Agenda commands}). With prefix arg show, on |
744 each | |
745 | |
713 level, all sibling headings. | 746 level, all sibling headings. |
714 @kindex C-c C-x b | 747 @kindex C-c C-x b |
715 @item C-c C-x b | 748 @item C-c C-x b |
716 Show the current subtree in an indirect buffer@footnote{The indirect | 749 Show the current subtree in an indirect buffer@footnote{The indirect |
717 buffer | 750 buffer |
804 headline, the new headline is created before the current line. If at | 837 headline, the new headline is created before the current line. If at |
805 the beginning of any other line, the content of that line is made the | 838 the beginning of any other line, the content of that line is made the |
806 new heading. If the command is used at the end of a folded subtree | 839 new heading. If the command is used at the end of a folded subtree |
807 (i.e. behind the ellipses at the end of a headline), then a headline | 840 (i.e. behind the ellipses at the end of a headline), then a headline |
808 like the current one will be inserted after the end of the subtree. | 841 like the current one will be inserted after the end of the subtree. |
842 @kindex C-@key{RET} | |
843 @item C-@key{RET} | |
844 Insert a new heading after the current subtree, same level as the | |
845 current headline. This command works from anywhere in the entry. | |
809 @kindex M-S-@key{RET} | 846 @kindex M-S-@key{RET} |
810 @item M-S-@key{RET} | 847 @item M-S-@key{RET} |
811 Insert new TODO entry with same level as current heading. | 848 Insert new TODO entry with same level as current heading. |
812 @kindex M-@key{left} | 849 @kindex M-@key{left} |
813 @item M-@key{left} | 850 @item M-@key{left} |
831 @kindex C-c C-x C-w | 868 @kindex C-c C-x C-w |
832 @kindex C-c C-x C-k | 869 @kindex C-c C-x C-k |
833 @item C-c C-x C-w | 870 @item C-c C-x C-w |
834 @itemx C-c C-x C-k | 871 @itemx C-c C-x C-k |
835 Kill subtree, i.e. remove it from buffer but save in kill ring. | 872 Kill subtree, i.e. remove it from buffer but save in kill ring. |
873 With prefix arg, kill N sequential subtrees. | |
836 @kindex C-c C-x M-w | 874 @kindex C-c C-x M-w |
837 @item C-c C-x M-w | 875 @item C-c C-x M-w |
838 Copy subtree to kill ring. | 876 Copy subtree to kill ring. With prefix arg, copy N sequential subtrees. |
839 @kindex C-c C-x C-y | 877 @kindex C-c C-x C-y |
840 @item C-c C-x C-y | 878 @item C-c C-x C-y |
841 Yank subtree from kill ring. This does modify the level of the subtree to | 879 Yank subtree from kill ring. This does modify the level of the subtree to |
842 make sure the tree fits in nicely at the yank position. The yank | 880 make sure the tree fits in nicely at the yank position. The yank |
843 level can also be specified with a prefix arg, or by yanking after a | 881 level can also be specified with a prefix arg, or by yanking after a |
844 headline marker like @samp{****}. | 882 headline marker like @samp{****}. |
883 @kindex C-c C-w | |
884 @item C-c C-w | |
885 Refile entry to a different location. @xref{Refiling notes}. | |
845 @kindex C-c ^ | 886 @kindex C-c ^ |
846 @item C-c ^ | 887 @item C-c ^ |
847 Sort same-level entries. When there is an active region, all entries in | 888 Sort same-level entries. When there is an active region, all entries in |
848 the region will be sorted. Otherwise the children of the current | 889 the region will be sorted. Otherwise the children of the current |
849 headline are sorted. The command prompts for the sorting method, which | 890 headline are sorted. The command prompts for the sorting method, which |
850 can be alphabetically, numerically, by time (using the first time stamp | 891 can be alphabetically, numerically, by time (using the first time stamp |
851 in each entry), by priority, and each of these in reverse order. With a | 892 in each entry), by priority, and each of these in reverse order. You |
893 can also supply your own function to extract the sorting key. With a | |
852 @kbd{C-u} prefix, sorting will be case-sensitive. With two @kbd{C-u | 894 @kbd{C-u} prefix, sorting will be case-sensitive. With two @kbd{C-u |
853 C-u} prefixes, duplicate entries will also be removed. | 895 C-u} prefixes, duplicate entries will also be removed. |
854 @end table | 896 @end table |
855 | 897 |
856 @cindex region, active | 898 @cindex region, active |
954 The default archive location is a file in the same directory as the | 996 The default archive location is a file in the same directory as the |
955 current file, with the name derived by appending @file{_archive} to the | 997 current file, with the name derived by appending @file{_archive} to the |
956 current file name. For information and examples on how to change this, | 998 current file name. For information and examples on how to change this, |
957 see the documentation string of the variable | 999 see the documentation string of the variable |
958 @code{org-archive-location}. There is also an in-buffer option for | 1000 @code{org-archive-location}. There is also an in-buffer option for |
959 setting this variable, for example | 1001 setting this variable, for example@footnote{For backward compatibility, |
1002 the following also works: If there are several such lines in a file, | |
1003 each specifies the archive location for the text below it. The first | |
1004 such line also applies to any text before its definition. However, | |
1005 using this method is @emph{strongly} deprecated as it is incompatible | |
1006 with the outline structure of the document. The correct method for | |
1007 setting multiple archive locations in a buffer is using a property.}: | |
960 | 1008 |
961 @example | 1009 @example |
962 #+ARCHIVE: %s_done:: | 1010 #+ARCHIVE: %s_done:: |
963 @end example | 1011 @end example |
964 | 1012 |
965 @noindent | 1013 @noindent |
966 You may have several such lines in the buffer, they will then be valid | 1014 If you would like to have a special ARCHIVE location for a single entry |
967 for the entries following the line (the first will also apply to any | 1015 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the |
968 text before it). | 1016 location as the value (@pxref{Properties and columns}). |
969 | 1017 |
970 @node Sparse trees, Plain lists, Archiving, Document structure | 1018 @node Sparse trees, Plain lists, Archiving, Document structure |
971 @section Sparse trees | 1019 @section Sparse trees |
972 @cindex sparse trees | 1020 @cindex sparse trees |
973 @cindex trees, sparse | 1021 @cindex trees, sparse |
974 @cindex folding, sparse trees | 1022 @cindex folding, sparse trees |
975 @cindex occur, command | 1023 @cindex occur, command |
976 | 1024 |
977 An important feature of Org-mode is the ability to construct | 1025 An important feature of Org-mode is the ability to construct |
978 @emph{sparse trees} for selected information in an outline tree. A | 1026 @emph{sparse trees} for selected information in an outline tree, so that |
979 sparse tree means that the entire document is folded as much as | 1027 the entire document is folded as much as possible, but the selected |
980 possible, but the selected information is made visible along with the | 1028 information is made visible along with the headline structure above |
981 headline structure above it@footnote{See also the variables | 1029 it@footnote{See also the variables @code{org-show-hierarchy-above}, |
982 @code{org-show-hierarchy-above}, @code{org-show-following-heading}, and | 1030 @code{org-show-following-heading}, and @code{org-show-siblings} for |
983 @code{org-show-siblings} for detailed control on how much context is | 1031 detailed control on how much context is shown around each match.}. Just |
984 shown around each match.}. Just try it out and you will see immediately | 1032 try it out and you will see immediately how it works. |
985 how it works. | 1033 |
986 | 1034 Org-mode contains several commands creating such trees, all these |
987 Org-mode contains several commands creating such trees. The most | 1035 commands can be accessed through a dispatcher: |
988 basic one is @command{org-occur}: | |
989 | 1036 |
990 @table @kbd | 1037 @table @kbd |
991 @kindex C-c / | 1038 @kindex C-c / |
992 @item C-c / | 1039 @item C-c / |
1040 This prompts for an extra key to select a sparse-tree creating command. | |
1041 @kindex C-c / r | |
1042 @item C-c / r | |
993 Occur. Prompts for a regexp and shows a sparse tree with all matches. | 1043 Occur. Prompts for a regexp and shows a sparse tree with all matches. |
994 If the match is in a headline, the headline is made visible. If the | 1044 If the match is in a headline, the headline is made visible. If the |
995 match is in the body of an entry, headline and body are made visible. | 1045 match is in the body of an entry, headline and body are made visible. |
996 In order to provide minimal context, also the full hierarchy of | 1046 In order to provide minimal context, also the full hierarchy of |
997 headlines above the match is shown, as well as the headline following | 1047 headlines above the match is shown, as well as the headline following |
998 the match. Each match is also highlighted; the highlights disappear | 1048 the match. Each match is also highlighted; the highlights disappear |
999 when the buffer is changed by an editing command, or by pressing | 1049 when the buffer is changed by an editing command, or by pressing |
1000 @kbd{C-c C-c}. When called with a @kbd{C-u} prefix argument, previous | 1050 @kbd{C-c C-c}. When called with a @kbd{C-u} prefix argument, previous |
1001 highlights are kept, so several calls to this command can be stacked. | 1051 highlights are kept, so several calls to this command can be stacked. |
1002 @end table | 1052 @end table |
1053 | |
1003 @noindent | 1054 @noindent |
1004 For frequently used sparse trees of specific search strings, you can | 1055 For frequently used sparse trees of specific search strings, you can |
1005 use the variable @code{org-agenda-custom-commands} to define fast | 1056 use the variable @code{org-agenda-custom-commands} to define fast |
1006 keyboard access to specific sparse trees. These commands will then be | 1057 keyboard access to specific sparse trees. These commands will then be |
1007 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}). | 1058 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}). |
1013 @end lisp | 1064 @end lisp |
1014 | 1065 |
1015 @noindent will define the key @kbd{C-c a f} as a shortcut for creating | 1066 @noindent will define the key @kbd{C-c a f} as a shortcut for creating |
1016 a sparse tree matching the string @samp{FIXME}. | 1067 a sparse tree matching the string @samp{FIXME}. |
1017 | 1068 |
1018 Other commands use sparse trees as well. For example @kbd{C-c | 1069 The other sparse tree commands select headings based on TODO keywords, |
1019 C-v} creates a sparse TODO tree (@pxref{TODO basics}). | 1070 tags, or properties and will be discussed later in this manual. |
1020 | 1071 |
1021 @kindex C-c C-e v | 1072 @kindex C-c C-e v |
1022 @cindex printing sparse trees | 1073 @cindex printing sparse trees |
1023 @cindex visible text, printing | 1074 @cindex visible text, printing |
1024 To print a sparse tree, you can use the Emacs command | 1075 To print a sparse tree, you can use the Emacs command |
1036 @cindex ordered lists | 1087 @cindex ordered lists |
1037 | 1088 |
1038 Within an entry of the outline tree, hand-formatted lists can provide | 1089 Within an entry of the outline tree, hand-formatted lists can provide |
1039 additional structure. They also provide a way to create lists of | 1090 additional structure. They also provide a way to create lists of |
1040 checkboxes (@pxref{Checkboxes}). Org-mode supports editing such lists, | 1091 checkboxes (@pxref{Checkboxes}). Org-mode supports editing such lists, |
1041 and the HTML exporter (@pxref{Exporting}) does parse and format them. | 1092 and the HTML exporter (@pxref{Exporting}) parses and formats them. |
1042 | 1093 |
1043 Org-mode knows ordered and unordered lists. Unordered list items start | 1094 Org-mode knows ordered and unordered lists. Unordered list items start |
1044 with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a | 1095 with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a |
1045 bullet, lines must be indented or they will be seen as top-level | 1096 bullet, lines must be indented or they will be seen as top-level |
1046 headlines. Also, when you are hiding leading stars to get a clean | 1097 headlines. Also, when you are hiding leading stars to get a clean |
1047 outline view, plain list items starting with a star are visually | 1098 outline view, plain list items starting with a star are visually |
1048 indistinguishable from true headlines. In short: even though @samp{*} | 1099 indistinguishable from true headlines. In short: even though @samp{*} |
1049 is supported, it may be better not to use it for plain list items.} as | 1100 is supported, it may be better to not use it for plain list items.} as |
1050 bullets. Ordered list items start with @samp{1.} or @samp{1)}. Items | 1101 bullets. Ordered list items start with a numeral followed by either a |
1102 period or a right parenthesis, such as @samp{1.} or @samp{1)}. Items | |
1051 belonging to the same list must have the same indentation on the first | 1103 belonging to the same list must have the same indentation on the first |
1052 line. In particular, if an ordered list reaches number @samp{10.}, then | 1104 line. In particular, if an ordered list reaches number @samp{10.}, then |
1053 the 2--digit numbers must be written left-aligned with the other numbers | 1105 the 2--digit numbers must be written left-aligned with the other numbers |
1054 in the list. Indentation also determines the end of a list item. It | 1106 in the list. Indentation also determines the end of a list item. It |
1055 ends before the next line that is indented like the bullet/number, or | 1107 ends before the next line that is indented like the bullet/number, or |
1129 would imply a different hierarchy. To use the new hierarchy, break | 1181 would imply a different hierarchy. To use the new hierarchy, break |
1130 the command chain with a cursor motion or so. | 1182 the command chain with a cursor motion or so. |
1131 @kindex C-c C-c | 1183 @kindex C-c C-c |
1132 @item C-c C-c | 1184 @item C-c C-c |
1133 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the | 1185 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the |
1134 state of the checkbox. If not, make this command makes sure that all | 1186 state of the checkbox. If not, this command makes sure that all the |
1135 the items on this list level use the same bullet. Furthermore, if this | 1187 items on this list level use the same bullet. Furthermore, if this is |
1136 is an ordered list, make sure the numbering is ok. | 1188 an ordered list, make sure the numbering is ok. |
1137 @kindex C-c - | 1189 @kindex C-c - |
1138 @item C-c - | 1190 @item C-c - |
1139 Cycle the entire list level through the different itemize/enumerate | 1191 Cycle the entire list level through the different itemize/enumerate |
1140 bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). | 1192 bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). |
1141 With prefix arg, select the nth bullet from this list. | 1193 With prefix arg, select the nth bullet from this list. |
1146 @cindex drawers | 1198 @cindex drawers |
1147 @cindex visibility cycling, drawers | 1199 @cindex visibility cycling, drawers |
1148 | 1200 |
1149 Sometimes you want to keep information associated with an entry, but you | 1201 Sometimes you want to keep information associated with an entry, but you |
1150 normally don't want to see it. For this, Org-mode has @emph{drawers}. | 1202 normally don't want to see it. For this, Org-mode has @emph{drawers}. |
1151 Drawers need to be configured with the variable @code{org-drawers}, and | 1203 Drawers need to be configured with the variable |
1204 @code{org-drawers}@footnote{You can define drawers on a per-file basis | |
1205 with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers | |
1152 look like this: | 1206 look like this: |
1153 | 1207 |
1154 @example | 1208 @example |
1155 ** This is a headline | 1209 ** This is a headline |
1156 Still outside the drawer | 1210 Still outside the drawer |
1192 @node Tables, Hyperlinks, Document structure, Top | 1246 @node Tables, Hyperlinks, Document structure, Top |
1193 @chapter Tables | 1247 @chapter Tables |
1194 @cindex tables | 1248 @cindex tables |
1195 @cindex editing tables | 1249 @cindex editing tables |
1196 | 1250 |
1197 Org-mode has a very fast and intuitive table editor built-in. | 1251 Org-mode comes with a fast and intuitive table editor. Spreadsheet-like |
1198 Spreadsheet-like calculations are supported in connection with the | 1252 calculations are supported in connection with the Emacs @file{calc} |
1199 Emacs @file{calc} package. | 1253 package |
1254 @ifinfo | |
1255 (@pxref{Calc,,,calc,Gnu Emacs Calculator Manual}). | |
1256 @end ifinfo | |
1257 @ifnotinfo | |
1258 (see the Emacs Calculator manual for more information about the Emacs | |
1259 calculator). | |
1260 @end ifnotinfo | |
1200 | 1261 |
1201 @menu | 1262 @menu |
1202 * Built-in table editor:: Simple tables | 1263 * Built-in table editor:: Simple tables |
1203 * Narrow columns:: Stop wasting space in tables | 1264 * Narrow columns:: Stop wasting space in tables |
1204 * Column groups:: Grouping to trigger vertical lines | 1265 * Column groups:: Grouping to trigger vertical lines |
1252 @tsubheading{Creation and conversion} | 1313 @tsubheading{Creation and conversion} |
1253 @kindex C-c | | 1314 @kindex C-c | |
1254 @item C-c | | 1315 @item C-c | |
1255 Convert the active region to table. If every line contains at least one | 1316 Convert the active region to table. If every line contains at least one |
1256 TAB character, the function assumes that the material is tab separated. | 1317 TAB character, the function assumes that the material is tab separated. |
1318 If every line contains a comma, comma-separated values (CSV) are assumed. | |
1257 If not, lines are split at whitespace into fields. You can use a prefix | 1319 If not, lines are split at whitespace into fields. You can use a prefix |
1258 argument to indicate the minimum number of consecutive spaces required | 1320 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u |
1259 to identify a field separator (default: just one).@* | 1321 C-u} forces TAB, and a numeric argument N indicates that at least N |
1322 consequtive spaces, or alternatively a TAB will be the separator. | |
1323 @* | |
1260 If there is no active region, this command creates an empty Org-mode | 1324 If there is no active region, this command creates an empty Org-mode |
1261 table. But it's easier just to start typing, like | 1325 table. But it's easier just to start typing, like |
1262 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}. | 1326 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}. |
1263 | 1327 |
1264 @tsubheading{Re-aligning and field motion} | 1328 @tsubheading{Re-aligning and field motion} |
1386 Edit the current field in a separate window. This is useful for fields | 1450 Edit the current field in a separate window. This is useful for fields |
1387 that are not fully visible (@pxref{Narrow columns}). When called with a | 1451 that are not fully visible (@pxref{Narrow columns}). When called with a |
1388 @kbd{C-u} prefix, just make the full field visible, so that it can be | 1452 @kbd{C-u} prefix, just make the full field visible, so that it can be |
1389 edited in place. | 1453 edited in place. |
1390 @c | 1454 @c |
1391 @kindex C-c @key{TAB} | |
1392 @item C-c @key{TAB} | |
1393 This is an alias for @kbd{C-u C-c `} to make the current field fully | |
1394 visible. | |
1395 @c | |
1396 @item M-x org-table-import | 1455 @item M-x org-table-import |
1397 Import a file as a table. The table should be TAB- or whitespace | 1456 Import a file as a table. The table should be TAB- or whitespace |
1398 separated. Useful, for example, to import an Excel table or data from a | 1457 separated. Useful, for example, to import a spreadsheet table or data |
1399 database, because these programs generally can write TAB-separated text | 1458 from a database, because these programs generally can write |
1400 files. This command works by inserting the file into the buffer and | 1459 TAB-separated text files. This command works by inserting the file into |
1401 then converting the region to a table. Any prefix argument is passed on | 1460 the buffer and then converting the region to a table. Any prefix |
1402 to the converter, which uses it to determine the separator. | 1461 argument is passed on to the converter, which uses it to determine the |
1462 separator. | |
1403 @item C-c | | 1463 @item C-c | |
1404 Tables can also be imported by pasting tabular text into the org-mode | 1464 Tables can also be imported by pasting tabular text into the org-mode |
1405 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the | 1465 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the |
1406 @kbd{C-c |} command (see above under @i{Creation and conversion}. | 1466 @kbd{C-c |} command (see above under @i{Creation and conversion}. |
1407 @c | 1467 @c |
1408 @item M-x org-table-export | 1468 @item M-x org-table-export |
1409 Export the table as a TAB-separated file. Useful for data exchange with, | 1469 Export the table as a TAB-separated file. Useful for data exchange with, |
1410 for example, Excel or database programs. | 1470 for example, spreadsheet or database programs. |
1411 @end table | 1471 @end table |
1412 | 1472 |
1413 If you don't like the automatic table editor because it gets in your | 1473 If you don't like the automatic table editor because it gets in your |
1414 way on lines which you would like to start with @samp{|}, you can turn | 1474 way on lines which you would like to start with @samp{|}, you can turn |
1415 it off with | 1475 it off with |
1581 | 1641 |
1582 The row specification only counts data lines and ignores horizontal | 1642 The row specification only counts data lines and ignores horizontal |
1583 separator lines (hlines). You can use absolute row numbers | 1643 separator lines (hlines). You can use absolute row numbers |
1584 @samp{1}...@samp{N}, and row numbers relative to the current row like | 1644 @samp{1}...@samp{N}, and row numbers relative to the current row like |
1585 @samp{+3} or @samp{-1}. Or specify the row relative to one of the | 1645 @samp{+3} or @samp{-1}. Or specify the row relative to one of the |
1586 hlines: @samp{I} refers to the first hline, @samp{II} to the second etc. | 1646 hlines: @samp{I} refers to the first hline@footnote{Note that only |
1587 @samp{-I} refers to the first such line above the current line, | 1647 hlines are counted that @emph{separate} table lines. If the table |
1588 @samp{+I} to the first such line below the current line. You can also | 1648 starts with a hline above the header, it does not count.}, @samp{II} to |
1589 write @samp{III+2} which is the second data line after the third hline | 1649 the second etc. @samp{-I} refers to the first such line above the |
1590 in the table. Relative row numbers like @samp{-3} will not cross hlines | 1650 current line, @samp{+I} to the first such line below the current line. |
1591 if the current line is too close to the hline. Instead, the value | 1651 You can also write @samp{III+2} which is the second data line after the |
1592 directly at the hline is used. | 1652 third hline in the table. Relative row numbers like @samp{-3} will not |
1653 cross hlines if the current line is too close to the hline. Instead, | |
1654 the value directly at the hline is used. | |
1593 | 1655 |
1594 @samp{0} refers to the current row and column. Also, if you omit | 1656 @samp{0} refers to the current row and column. Also, if you omit |
1595 either the column or the row part of the reference, the current | 1657 either the column or the row part of the reference, the current |
1596 row/column is implied. | 1658 row/column is implied. |
1597 | 1659 |
1654 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 | 1716 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 |
1655 @end example | 1717 @end example |
1656 | 1718 |
1657 @noindent | 1719 @noindent |
1658 Also properties (@pxref{Properties and columns}) can be used as | 1720 Also properties (@pxref{Properties and columns}) can be used as |
1659 constants in table formulas: For a property @samp{:XYZ:} use the name | 1721 constants in table formulas: For a property @samp{:Xyz:} use the name |
1660 @samp{$PROP_XYZ}, and the property will be searched in the current | 1722 @samp{$PROP_Xyz}, and the property will be searched in the current |
1661 outline entry and in the hierarchy above it. If you have the | 1723 outline entry and in the hierarchy above it. If you have the |
1662 @file{constants.el} package, it will also be used to resolve constants, | 1724 @file{constants.el} package, it will also be used to resolve constants, |
1663 including natural constants like @samp{$h} for Planck's constant, and | 1725 including natural constants like @samp{$h} for Planck's constant, and |
1664 units like @samp{$km} for kilometers@footnote{@file{Constant.el} can | 1726 units like @samp{$km} for kilometers@footnote{@file{Constant.el} can |
1665 supply the values of constants in two different unit systems, @code{SI} | 1727 supply the values of constants in two different unit systems, @code{SI} |
2085 | 2147 |
2086 @node Hyperlinks, TODO items, Tables, Top | 2148 @node Hyperlinks, TODO items, Tables, Top |
2087 @chapter Hyperlinks | 2149 @chapter Hyperlinks |
2088 @cindex hyperlinks | 2150 @cindex hyperlinks |
2089 | 2151 |
2090 Just like HTML, Org-mode provides links inside a file, and external | 2152 Like HTML, Org-mode provides links inside a file, external links to |
2091 links to other files, Usenet articles, emails, and much more. | 2153 other files, Usenet articles, emails, and much more. |
2092 | 2154 |
2093 @menu | 2155 @menu |
2094 * Link format:: How links in Org-mode are formatted | 2156 * Link format:: How links in Org-mode are formatted |
2095 * Internal links:: Links to other places in the current file | 2157 * Internal links:: Links to other places in the current file |
2096 * External links:: URL-like links to the world | 2158 * External links:: URL-like links to the world |
2097 * Handling links:: Creating, inserting and following | 2159 * Handling links:: Creating, inserting and following |
2098 * Using links outside Org-mode:: Linking from my C source code? | 2160 * Using links outside Org-mode:: Linking from my C source code? |
2099 * Link abbreviations:: Shortcuts for writing complex links | 2161 * Link abbreviations:: Shortcuts for writing complex links |
2100 * Search options:: Linking to a specific location | 2162 * Search options:: Linking to a specific location |
2101 * Custom searches:: When the default search is not enough | 2163 * Custom searches:: When the default search is not enough |
2102 * Remember:: Org-trees store quick notes | |
2103 @end menu | 2164 @end menu |
2104 | 2165 |
2105 @node Link format, Internal links, Hyperlinks, Hyperlinks | 2166 @node Link format, Internal links, Hyperlinks, Hyperlinks |
2106 @section Link format | 2167 @section Link format |
2107 @cindex link format | 2168 @cindex link format |
2302 @item C-c C-l | 2363 @item C-c C-l |
2303 Insert a link. This prompts for a link to be inserted into the buffer. | 2364 Insert a link. This prompts for a link to be inserted into the buffer. |
2304 You can just type a link, using text for an internal link, or one of the | 2365 You can just type a link, using text for an internal link, or one of the |
2305 link type prefixes mentioned in the examples above. All links stored | 2366 link type prefixes mentioned in the examples above. All links stored |
2306 during the current session are part of the history for this prompt, so | 2367 during the current session are part of the history for this prompt, so |
2307 you can access them with @key{up} and @key{down}. Completion, on the | 2368 you can access them with @key{up} and @key{down} (or @kbd{M-p/n}). |
2308 other hand, will help you to insert valid link prefixes like | 2369 Completion, on the other hand, will help you to insert valid link |
2309 @samp{http:} or @samp{ftp:}, including the prefixes defined through link | 2370 prefixes like @samp{http:} or @samp{ftp:}, including the prefixes |
2310 abbreviations (@pxref{Link abbreviations}). The link will be inserted | 2371 defined through link abbreviations (@pxref{Link abbreviations}). The |
2311 into the buffer@footnote{After insertion of a stored link, the link will | 2372 link will be inserted into the buffer@footnote{After insertion of a |
2312 be removed from the list of stored links. To keep it in the list later | 2373 stored link, the link will be removed from the list of stored links. To |
2313 use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the | 2374 keep it in the list later use, use a triple @kbd{C-u} prefix to @kbd{C-c |
2314 option @code{org-keep-stored-link-after-insertion}.}, along with a | 2375 C-l}, or configure the option |
2315 descriptive text. If some text was selected when this command is | 2376 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive |
2316 called, the selected text becomes the default description.@* Note that | 2377 text. If some text was selected when this command is called, the |
2317 you don't have to use this command to insert a link. Links in Org-mode | 2378 selected text becomes the default description.@* Note that you don't |
2318 are plain text, and you can type or paste them straight into the buffer. | 2379 have to use this command to insert a link. Links in Org-mode are plain |
2319 By using this command, the links are automatically enclosed in double | 2380 text, and you can type or paste them straight into the buffer. By using |
2320 brackets, and you will be asked for the optional descriptive text. | 2381 this command, the links are automatically enclosed in double brackets, |
2382 and you will be asked for the optional descriptive text. | |
2321 @c | 2383 @c |
2322 @c If the link is a @samp{file:} link and | 2384 @c If the link is a @samp{file:} link and |
2323 @c the linked file is located in the same directory as the current file or | 2385 @c the linked file is located in the same directory as the current file or |
2324 @c a subdirectory of it, the path of the file will be inserted relative to | 2386 @c a subdirectory of it, the path of the file will be inserted relative to |
2325 @c the current directory. | 2387 @c the current directory. |
2511 As a degenerate case, a file link with an empty file name can be used | 2573 As a degenerate case, a file link with an empty file name can be used |
2512 to search the current file. For example, @code{[[file:::find me]]} does | 2574 to search the current file. For example, @code{[[file:::find me]]} does |
2513 a search for @samp{find me} in the current file, just as | 2575 a search for @samp{find me} in the current file, just as |
2514 @samp{[[find me]]} would. | 2576 @samp{[[find me]]} would. |
2515 | 2577 |
2516 @node Custom searches, Remember, Search options, Hyperlinks | 2578 @node Custom searches, , Search options, Hyperlinks |
2517 @section Custom Searches | 2579 @section Custom Searches |
2518 @cindex custom search strings | 2580 @cindex custom search strings |
2519 @cindex search strings, custom | 2581 @cindex search strings, custom |
2520 | 2582 |
2521 The default mechanism for creating search strings and for doing the | 2583 The default mechanism for creating search strings and for doing the |
2535 for Bib@TeX{} database files, and you can use the corresponding code as | 2597 for Bib@TeX{} database files, and you can use the corresponding code as |
2536 an implementation example. Search for @samp{BibTeX links} in the source | 2598 an implementation example. Search for @samp{BibTeX links} in the source |
2537 file. | 2599 file. |
2538 | 2600 |
2539 | 2601 |
2540 @node Remember, , Custom searches, Hyperlinks | |
2541 @section Remember | |
2542 @cindex @file{remember.el} | |
2543 | |
2544 Another way to create org entries with links to other files is through | |
2545 the @i{remember} package by John Wiegley. @i{Remember} lets you store | |
2546 quick notes with little interruption of your work flow. See | |
2547 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more | |
2548 information. The notes produced by @i{Remember} can be stored in | |
2549 different ways, and Org-mode files are a good target. Org-mode | |
2550 significantly expands the possibilities of @i{remember}: You may define | |
2551 templates for different note types, and to associate target files and | |
2552 headlines with specific templates. It also allows you to select the | |
2553 location where a note should be stored interactively, on the fly. | |
2554 | |
2555 @menu | |
2556 * Setting up remember:: Some code for .emacs to get things going | |
2557 * Remember templates:: Define the outline of different note types | |
2558 * Storing notes:: Directly get the note to where it belongs | |
2559 @end menu | |
2560 | |
2561 @node Setting up remember, Remember templates, Remember, Remember | |
2562 @subsection Setting up remember | |
2563 | |
2564 The following customization will tell @i{remember} to use org files as | |
2565 target, and to create annotations compatible with Org-mode links. | |
2566 | |
2567 @example | |
2568 (setq org-directory "~/path/to/my/orgfiles/") | |
2569 (setq org-default-notes-file "~/.notes") | |
2570 (setq remember-annotation-functions '(org-remember-annotation)) | |
2571 (setq remember-handler-functions '(org-remember-handler)) | |
2572 (add-hook 'remember-mode-hook 'org-remember-apply-template) | |
2573 @end example | |
2574 | |
2575 @node Remember templates, Storing notes, Setting up remember, Remember | |
2576 @subsection Remember templates | |
2577 @cindex templates, for remember | |
2578 | |
2579 In combination with Org-mode, you can use templates to generate | |
2580 different types of @i{remember} notes. For example, if you would like | |
2581 to use one template to create general TODO entries, another one for | |
2582 journal entries, and a third one for collecting random ideas, you could | |
2583 use: | |
2584 | |
2585 @example | |
2586 (setq org-remember-templates | |
2587 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org") | |
2588 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") | |
2589 (?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) | |
2590 @end example | |
2591 | |
2592 @noindent In these entries, the character specifies how to select the | |
2593 template. The first string specifies the template. Two more (optional) | |
2594 strings give the file in which, and the headline under which the new | |
2595 note should be stored. The file defaults (if not present or @code{nil}) | |
2596 to @code{org-default-notes-file}, the heading to | |
2597 @code{org-remember-default-headline}. Both defaults help to get to the | |
2598 storing location quickly, but you can change the location interactively | |
2599 while storing the note. | |
2600 | |
2601 When you call @kbd{M-x remember} (or @kbd{M-x org-remember}) to remember | |
2602 something, org will prompt for a key to select the template (if you have | |
2603 more than one template) and then prepare the buffer like | |
2604 @example | |
2605 * TODO | |
2606 [[file:link to where you called remember]] | |
2607 @end example | |
2608 | |
2609 @noindent or | |
2610 | |
2611 @example | |
2612 * [2006-03-21 Tue 15:37] | |
2613 | |
2614 [[file:link to where you called remember]] | |
2615 @end example | |
2616 | |
2617 @noindent | |
2618 During expansion of the template, special @kbd{%}-escapes allow dynamic | |
2619 insertion of content: | |
2620 @example | |
2621 %^@{prompt@} @r{prompt the user for a string and replace this sequence with it.} | |
2622 %t @r{time stamp, date only} | |
2623 %T @r{time stamp with date and time} | |
2624 %u, %U @r{like the above, but inactive time stamps} | |
2625 %^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}} | |
2626 @r{You may define a prompt like @code{%^@{Birthday@}t}} | |
2627 %n @r{user name (taken from @code{user-full-name})} | |
2628 %a @r{annotation, normally the link created with @code{org-store-link}} | |
2629 %i @r{initial content, the region when remember is called with C-u.} | |
2630 @r{The entire text will be indented like @code{%i} itself.} | |
2631 %^g @r{prompt for tags, with completion on tags in target file.} | |
2632 %^G @r{prompt for tags, with completion all tags in all agenda files.} | |
2633 %:keyword @r{specific information for certain link types, see below} | |
2634 @end example | |
2635 | |
2636 @noindent | |
2637 For specific link types, the following keywords will be defined: | |
2638 | |
2639 @example | |
2640 Link type | Available keywords | |
2641 -------------------+---------------------------------------------- | |
2642 bbdb | %:name %:company | |
2643 vm, wl, mh, rmail | %:type %:subject %:message-id | |
2644 | %:from %:fromname %:fromaddress | |
2645 | %:to %:toname %:toaddress | |
2646 | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}} | |
2647 gnus | %:group, @r{for messages also all email fields} | |
2648 w3, w3m | %:url | |
2649 info | %:file %:node | |
2650 calendar | %:date" | |
2651 @end example | |
2652 | |
2653 @noindent | |
2654 To place the cursor after template expansion use: | |
2655 | |
2656 @example | |
2657 %? @r{After completing the template, position cursor here.} | |
2658 @end example | |
2659 | |
2660 @noindent | |
2661 If you change you mind about which template to use, call | |
2662 @code{org-remember} in the remember buffer. You may then select a new | |
2663 template that will be filled with the previous context information. | |
2664 | |
2665 @node Storing notes, , Remember templates, Remember | |
2666 @subsection Storing notes | |
2667 | |
2668 When you are finished preparing a note with @i{remember}, you have to press | |
2669 @kbd{C-c C-c} to file the note away. The handler first prompts for a | |
2670 target file - if you press @key{RET}, the value specified for the | |
2671 template is used. Then the command offers the headings tree of the | |
2672 selected file, with the cursor position at the default headline (if you | |
2673 had specified one in the template). You can either immediately press | |
2674 @key{RET} to get the note placed there. Or you can use the following | |
2675 keys to find a better location: | |
2676 @example | |
2677 @key{TAB} @r{Cycle visibility.} | |
2678 @key{down} / @key{up} @r{Next/previous visible headline.} | |
2679 n / p @r{Next/previous visible headline.} | |
2680 f / b @r{Next/previous headline same level.} | |
2681 u @r{One level up.} | |
2682 @c 0-9 @r{Digit argument.} | |
2683 @end example | |
2684 @noindent | |
2685 Pressing @key{RET} or @key{left} or @key{right} | |
2686 then leads to the following result. | |
2687 | |
2688 @multitable @columnfractions 0.2 0.15 0.65 | |
2689 @item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted} | |
2690 @item buffer-start @tab @key{RET} @tab as level 2 heading at end of file | |
2691 @item on headline @tab @key{RET} @tab as sublevel of the heading at cursor | |
2692 @item @tab @key{left}/@key{right} @tab as same level, before/after current heading | |
2693 @item not on headline @tab @key{RET} | |
2694 @tab at cursor position, level taken from context. | |
2695 @end multitable | |
2696 | |
2697 So a fast way to store the note to its default location is to press | |
2698 @kbd{C-c C-c @key{RET} @key{RET}}. Even shorter would be @kbd{C-u C-c | |
2699 C-c}, which does the same without even asking for a file or showing the | |
2700 tree. | |
2701 | |
2702 Before inserting the text into a tree, the function ensures that the | |
2703 text has a headline, i.e. a first line that starts with a @samp{*}. | |
2704 If not, a headline is constructed from the current date and some | |
2705 additional data. If the variable @code{org-adapt-indentation} is | |
2706 non-nil, the entire text is also indented so that it starts in the | |
2707 same column as the headline (after the asterisks). | |
2708 | |
2709 | 2602 |
2710 @node TODO items, Tags, Hyperlinks, Top | 2603 @node TODO items, Tags, Hyperlinks, Top |
2711 @chapter TODO items | 2604 @chapter TODO items |
2712 @cindex TODO items | 2605 @cindex TODO items |
2713 | 2606 |
2714 Org-mode does not maintain TODO lists as a separate document. TODO | 2607 Org-mode does not maintain TODO lists as separate documents. Instead, |
2715 items are an integral part of the notes file, because TODO items | 2608 TODO items are an integral part of the notes file, because TODO items |
2716 usually come up while taking notes! With Org-mode, you simply mark | 2609 usually come up while taking notes! With Org-mode, simply mark any |
2717 any entry in a tree as being a TODO item. In this way, the | 2610 entry in a tree as being a TODO item. In this way, information is not |
2718 information is not duplicated, and the entire context from which the | 2611 duplicated, and the entire context from which the TODO item emerged is |
2719 item emerged is always present when you check. | 2612 always present. |
2720 | 2613 |
2721 Of course, this technique causes TODO items to be scattered throughout | 2614 Of course, this technique for managing TODO items scatters them |
2722 your file. Org-mode provides methods to give you an overview over all | 2615 throughout your notes file. Org-mode compensates for this by providing |
2723 things you have to do. | 2616 methods to give you an overview of all the things that you have to do. |
2724 | 2617 |
2725 @menu | 2618 @menu |
2726 * TODO basics:: Marking and displaying TODO entries | 2619 * TODO basics:: Marking and displaying TODO entries |
2727 * TODO extensions:: Workflow and assignments | 2620 * TODO extensions:: Workflow and assignments |
2621 * Progress logging:: Dates and notes for progress | |
2728 * Priorities:: Some things are more important than others | 2622 * Priorities:: Some things are more important than others |
2729 * Breaking down tasks:: Splitting a task into manageable pieces | 2623 * Breaking down tasks:: Splitting a task into manageable pieces |
2730 * Checkboxes:: Tick-off lists | 2624 * Checkboxes:: Tick-off lists |
2731 @end menu | 2625 @end menu |
2732 | 2626 |
2733 @node TODO basics, TODO extensions, TODO items, TODO items | 2627 @node TODO basics, TODO extensions, TODO items, TODO items |
2734 @section Basic TODO functionality | 2628 @section Basic TODO functionality |
2735 | 2629 |
2736 Any headline can become a TODO item by starting it with the word TODO, | 2630 Any headline becomes a TODO item when it starts with the word |
2737 for example: | 2631 @samp{TODO}, for example: |
2738 | 2632 |
2739 @example | 2633 @example |
2740 *** TODO Write letter to Sam Fortune | 2634 *** TODO Write letter to Sam Fortune |
2741 @end example | 2635 @end example |
2742 | 2636 |
2754 '--------------------------------' | 2648 '--------------------------------' |
2755 @end example | 2649 @end example |
2756 | 2650 |
2757 The same rotation can also be done ``remotely'' from the timeline and | 2651 The same rotation can also be done ``remotely'' from the timeline and |
2758 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). | 2652 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). |
2653 | |
2654 @kindex C-u C-c C-t | |
2655 @item C-u C-c C-t | |
2656 Select a specific keyword using completion or (if it has been set up) | |
2657 the fast selection interface. | |
2658 | |
2759 @kindex S-@key{right} | 2659 @kindex S-@key{right} |
2760 @kindex S-@key{left} | 2660 @kindex S-@key{left} |
2761 @item S-@key{right} | 2661 @item S-@key{right} |
2762 @itemx S-@key{left} | 2662 @itemx S-@key{left} |
2763 Select the following/preceding TODO state, similar to cycling. Mostly | 2663 Select the following/preceding TODO state, similar to cycling. Useful |
2764 useful if more than two TODO states are possible (@pxref{TODO | 2664 mostly if more than two TODO states are possible (@pxref{TODO |
2765 extensions}). | 2665 extensions}). |
2766 @kindex C-c C-c | 2666 @kindex C-c C-c |
2767 @item C-c C-c | 2667 @item C-c C-c |
2768 Use the fast tag interface to quickly and directly select a specific | 2668 Use the fast tag interface to directly select a specific TODO state. |
2769 TODO state. For this you need to assign keys to TODO state, like this: | 2669 For this you need to assign keys to TODO states, like this: |
2770 @example | 2670 @example |
2771 #+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) | 2671 #+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) |
2772 @end example | 2672 @end example |
2773 @noindent See @ref{Per file keywords} and @ref{Setting tags} for more | 2673 @noindent See @ref{Per-file keywords} and @ref{Setting tags} for more |
2774 information. | 2674 information. |
2775 @kindex C-c C-v | 2675 @kindex C-c C-v |
2676 @kindex C-c / t | |
2776 @cindex sparse tree, for TODO | 2677 @cindex sparse tree, for TODO |
2777 @item C-c C-v | 2678 @item C-c C-v |
2679 @itemx C-c / t | |
2778 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds | 2680 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds |
2779 the entire buffer, but shows all TODO items and the headings hierarchy | 2681 the entire buffer, but shows all TODO items and the headings hierarchy |
2780 above them. With prefix arg, search for a specific TODO. You will be | 2682 above them. With prefix arg, search for a specific TODO. You will be |
2781 prompted for the keyword, and you can also give a list of keywords like | 2683 prompted for the keyword, and you can also give a list of keywords like |
2782 @code{kwd1|kwd2|...}. With numerical prefix N, show the tree for the | 2684 @code{KWD1|KWD2|...}. With numerical prefix N, show the tree for the |
2783 Nth keyword in the variable @code{org-todo-keywords}. With two prefix | 2685 Nth keyword in the variable @code{org-todo-keywords}. With two prefix |
2784 args, find all TODO and DONE entries. | 2686 args, find all TODO and DONE entries. |
2785 @kindex C-c a t | 2687 @kindex C-c a t |
2786 @item C-c a t | 2688 @item C-c a t |
2787 Show the global TODO list. This collects the TODO items from all | 2689 Show the global TODO list. Collects the TODO items from all agenda |
2788 agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in | 2690 files (@pxref{Agenda views}) into a single buffer. The new buffer will |
2789 @code{agenda-mode}, so there are commands to examine and manipulate | 2691 be in @code{agenda-mode}, which provides commands to examine and |
2790 the TODO entries directly from that buffer (@pxref{Agenda commands}). | 2692 manipulate the TODO entries from the new buffer (@pxref{Agenda |
2791 @xref{Global TODO list}, for more information. | 2693 commands}). @xref{Global TODO list}, for more information. |
2792 @kindex S-M-@key{RET} | 2694 @kindex S-M-@key{RET} |
2793 @item S-M-@key{RET} | 2695 @item S-M-@key{RET} |
2794 Insert a new TODO entry below the current one. | 2696 Insert a new TODO entry below the current one. |
2795 @end table | 2697 @end table |
2796 | 2698 |
2797 @node TODO extensions, Priorities, TODO basics, TODO items | 2699 @node TODO extensions, Progress logging, TODO basics, TODO items |
2798 @section Extended use of TODO keywords | 2700 @section Extended use of TODO keywords |
2799 @cindex extended TODO keywords | 2701 @cindex extended TODO keywords |
2800 | 2702 |
2801 The default implementation of TODO entries is just two states: TODO and | 2703 By default, marked TODO entries have one of only two states: TODO and |
2802 DONE. You can use the TODO feature for more complicated things by | 2704 DONE. Org-mode allows you to classify TODO items in more complex ways |
2803 configuring the variable @code{org-todo-keywords}. With special setup, | 2705 with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With |
2804 the TODO keyword system can work differently in different files. | 2706 special setup, the TODO keyword system can work differently in different |
2707 files. | |
2805 | 2708 |
2806 Note that @i{tags} are another way to classify headlines in general and | 2709 Note that @i{tags} are another way to classify headlines in general and |
2807 TODO items in particular (@pxref{Tags}). | 2710 TODO items in particular (@pxref{Tags}). |
2808 | 2711 |
2809 @menu | 2712 @menu |
2810 * Workflow states:: From TODO to DONE in steps | 2713 * Workflow states:: From TODO to DONE in steps |
2811 * TODO types:: I do this, Fred the rest | 2714 * TODO types:: I do this, Fred does the rest |
2812 * Multiple sets in one file:: Mixing it all, and still finding your way | 2715 * Multiple sets in one file:: Mixing it all, and still finding your way |
2813 * Per file keywords:: Different files, different requirements | 2716 * Fast access to TODO states:: Single letter selection of a state |
2717 * Per-file keywords:: Different files, different requirements | |
2718 * Faces for TODO keywords:: Highlighting states | |
2814 @end menu | 2719 @end menu |
2815 | 2720 |
2816 @node Workflow states, TODO types, TODO extensions, TODO extensions | 2721 @node Workflow states, TODO types, TODO extensions, TODO extensions |
2817 @subsection TODO keywords as workflow states | 2722 @subsection TODO keywords as workflow states |
2818 @cindex TODO workflow | 2723 @cindex TODO workflow |
2873 to @kbd{C-c C-v}. For example, to see all things Lucy has to do, you | 2778 to @kbd{C-c C-v}. For example, to see all things Lucy has to do, you |
2874 would use @kbd{C-3 C-c C-v}. To collect Lucy's items from all agenda | 2779 would use @kbd{C-3 C-c C-v}. To collect Lucy's items from all agenda |
2875 files into a single buffer, you would use the prefix arg as well when | 2780 files into a single buffer, you would use the prefix arg as well when |
2876 creating the global todo list: @kbd{C-3 C-c t}. | 2781 creating the global todo list: @kbd{C-3 C-c t}. |
2877 | 2782 |
2878 @node Multiple sets in one file, Per file keywords, TODO types, TODO extensions | 2783 @node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions |
2879 @subsection Multiple keyword sets in one file | 2784 @subsection Multiple keyword sets in one file |
2880 @cindex todo keyword sets | 2785 @cindex todo keyword sets |
2881 | 2786 |
2882 Sometimes you may want to use different sets of TODO keywords in | 2787 Sometimes you may want to use different sets of TODO keywords in |
2883 parallel. For example, you may want to have the basic | 2788 parallel. For example, you may want to have the basic |
2916 @kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through | 2821 @kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through |
2917 @emph{all} keywords from all sets, so for example @kbd{S-@key{<right>}} | 2822 @emph{all} keywords from all sets, so for example @kbd{S-@key{<right>}} |
2918 would switch from @code{DONE} to @code{REPORT} in the example above. | 2823 would switch from @code{DONE} to @code{REPORT} in the example above. |
2919 @end table | 2824 @end table |
2920 | 2825 |
2921 @node Per file keywords, , Multiple sets in one file, TODO extensions | 2826 @node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions |
2827 @subsection Fast access to TODO states | |
2828 | |
2829 If you would like to quickly change an entry to an arbitrary TODO state | |
2830 instead of cycling through the states, you can set up keys for | |
2831 single-letter access to the states. This is done by adding the section | |
2832 key after each keyword, in parenthesis. For example: | |
2833 | |
2834 @lisp | |
2835 (setq org-todo-keywords | |
2836 '((sequence "TODO(t)" "|" "DONE(d)") | |
2837 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") | |
2838 (sequence "|" "CANCELED(c)"))) | |
2839 @end lisp | |
2840 | |
2841 If you then press @code{C-u C-c C-t} followed by the selection key, the | |
2842 entry will be switched to this state. @key{SPC} can be used to remove | |
2843 any TODO keyword from an entry. Should you like this way of selecting | |
2844 TODO states a lot, you might want to set the variable | |
2845 @code{org-use-fast-todo-selection} to @code{t} and make this behavior | |
2846 the default. Check also the variable | |
2847 @code{org-fast-tag-selection-include-todo}, it allows to change the TODO | |
2848 state through the tags interface (@pxref{Setting tags}). | |
2849 | |
2850 @node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions | |
2922 @subsection Setting up keywords for individual files | 2851 @subsection Setting up keywords for individual files |
2923 @cindex keyword options | 2852 @cindex keyword options |
2924 @cindex per file keywords | 2853 @cindex per-file keywords |
2925 | 2854 |
2926 It can be very useful to use different aspects of the TODO mechanism in | 2855 It can be very useful to use different aspects of the TODO mechanism in |
2927 different files. For file-local settings, you need to add special lines | 2856 different files. For file-local settings, you need to add special lines |
2928 to the file which set the keywords and interpretation for that file | 2857 to the file which set the keywords and interpretation for that file |
2929 only. For example, to set one of the two examples discussed above, you | 2858 only. For example, to set one of the two examples discussed above, you |
2959 known to Org-mode@footnote{Org-mode parses these lines only when | 2888 known to Org-mode@footnote{Org-mode parses these lines only when |
2960 Org-mode is activated after visiting a file. @kbd{C-c C-c} with the | 2889 Org-mode is activated after visiting a file. @kbd{C-c C-c} with the |
2961 cursor in a line starting with @samp{#+} is simply restarting Org-mode | 2890 cursor in a line starting with @samp{#+} is simply restarting Org-mode |
2962 for the current buffer.}. | 2891 for the current buffer.}. |
2963 | 2892 |
2964 @node Priorities, Breaking down tasks, TODO extensions, TODO items | 2893 @node Faces for TODO keywords, , Per-file keywords, TODO extensions |
2894 @subsection Faces for TODO keywords | |
2895 @cindex faces, for TODO keywords | |
2896 | |
2897 Org-mode highlights TODO keywords with special faces: @code{org-todo} | |
2898 for keywords indicating that an item still has to be acted upon, and | |
2899 @code{org-done} for keywords indicating that an item is finished. If | |
2900 you are using more than 2 different states, you might want to use | |
2901 special faces for some of them. This can be done using the variable | |
2902 @code{org-todo-keyword-faces}. For example: | |
2903 | |
2904 @lisp | |
2905 (setq org-todo-keyword-faces | |
2906 '(("TODO" . org-warning) | |
2907 ("DEFERRED" . shadow) | |
2908 ("CANCELED" . (:foreground "blue" :weight bold)))) | |
2909 @end lisp | |
2910 | |
2911 @page | |
2912 @node Progress logging, Priorities, TODO extensions, TODO items | |
2913 @section Progress Logging | |
2914 @cindex progress logging | |
2915 @cindex logging, of progress | |
2916 | |
2917 Org-mode can automatically record a time stamp and even a note when you | |
2918 mark a TODO item as DONE, or even each time you change the state of | |
2919 a TODO item. | |
2920 | |
2921 @menu | |
2922 * Closing items:: When was this entry marked DONE? | |
2923 * Tracking TODO state changes:: When did the status change? | |
2924 @end menu | |
2925 | |
2926 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging | |
2927 @subsection Closing items | |
2928 | |
2929 If you want to keep track of @emph{when} a certain TODO item was | |
2930 finished, turn on logging with@footnote{The corresponding in-buffer | |
2931 setting is: @code{#+STARTUP: logdone}. You may also set this for the | |
2932 scope of a subtree by adding a @code{:LOGGING:} property with one or more | |
2933 of the logging keywords in the value.} | |
2934 | |
2935 @lisp | |
2936 (setq org-log-done t) | |
2937 @end lisp | |
2938 | |
2939 @noindent | |
2940 Then each time you turn a TODO entry into DONE using either @kbd{C-c | |
2941 C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line | |
2942 @samp{CLOSED: [timestamp]} will be inserted just after the headline. If | |
2943 you turn the entry back into a TODO item through further state cycling, | |
2944 that line will be removed again. In the timeline (@pxref{Timeline}) and | |
2945 in the agenda (@pxref{Weekly/Daily agenda}), you can then use the | |
2946 @kbd{l} key to display the TODO items closed on each day, giving you an | |
2947 overview of what has been done on a day. If you want to record a note | |
2948 along with the timestamp, use@footnote{The corresponding in-buffer | |
2949 setting is: @code{#+STARTUP: lognotedone}} | |
2950 | |
2951 @lisp | |
2952 (setq org-log-done '(done)) | |
2953 @end lisp | |
2954 | |
2955 @node Tracking TODO state changes, , Closing items, Progress logging | |
2956 @subsection Tracking TODO state changes | |
2957 | |
2958 When TODO keywords are used as workflow states (@pxref{Workflow | |
2959 states}), you might want to keep track of when a state change occurred | |
2960 and record a note about this change. With the setting@footnote{The | |
2961 corresponding in-buffer setting is: @code{#+STARTUP: lognotestate}.} | |
2962 | |
2963 @lisp | |
2964 (setq org-log-done '(state)) | |
2965 @end lisp | |
2966 | |
2967 @noindent | |
2968 each state change will prompt you for a note that will be attached to | |
2969 the current headline. If you press @kbd{C-c C-c} without typing | |
2970 anything into the note buffer, only the time of the state change will be | |
2971 noted. Very likely you do not want this verbose tracking all the time, | |
2972 so it is probably better to configure this behavior with in-buffer | |
2973 options. For example, if you are tracking purchases, put these into a | |
2974 separate file that contains: | |
2975 | |
2976 @example | |
2977 #+SEQ_TODO: TODO(t) ORDERED(o) INVOICE(i) PAYED(p) | RECEIVED(r) | |
2978 #+STARTUP: lognotestate | |
2979 @end example | |
2980 | |
2981 If you only need to take a note for some of the states, mark those | |
2982 states with an additional @samp{@@}, like this: | |
2983 | |
2984 @example | |
2985 #+SEQ_TODO: TODO(t) ORDERED(o@@) INVOICE(i@@) PAYED(p) | RECEIVED(r) | |
2986 #+STARTUP: lognotestate | |
2987 @end example | |
2988 | |
2989 @node Priorities, Breaking down tasks, Progress logging, TODO items | |
2965 @section Priorities | 2990 @section Priorities |
2966 @cindex priorities | 2991 @cindex priorities |
2967 | 2992 |
2968 If you use Org-mode extensively to organize your work, you may end up | 2993 If you use Org-mode extensively, you may end up enough TODO items that |
2969 with a number of TODO entries so large that you'd like to prioritize | 2994 it starts to make sense to prioritize them. Prioritizing can be done by |
2970 them. This can be done by placing a @emph{priority cookie} into the | 2995 placing a @emph{priority cookie} into the headline of a TODO item, like |
2971 headline, like this | 2996 this |
2972 | 2997 |
2973 @example | 2998 @example |
2974 *** TODO [#A] Write letter to Sam Fortune | 2999 *** TODO [#A] Write letter to Sam Fortune |
2975 @end example | 3000 @end example |
2976 | 3001 |
2977 @noindent | 3002 @noindent |
2978 With its standard setup, Org-mode supports priorities @samp{A}, | 3003 By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and |
2979 @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry | 3004 @samp{C}. @samp{A} is the highest priority. An entry without a cookie |
2980 without a cookie is treated as priority @samp{B}. Priorities make a | 3005 is treated as priority @samp{B}. Priorities make a difference only in |
2981 difference only in the agenda (@pxref{Weekly/Daily agenda}). | 3006 the agenda (@pxref{Weekly/Daily agenda}); outside the agenda, they have |
3007 no inherent meaning to Org-mode. | |
3008 | |
3009 Priorities can be attached to any outline tree entries; they do not need | |
3010 to be TODO items. | |
2982 | 3011 |
2983 @table @kbd | 3012 @table @kbd |
2984 @kindex @kbd{C-c ,} | 3013 @kindex @kbd{C-c ,} |
2985 @item @kbd{C-c ,} | 3014 @item @kbd{C-c ,} |
2986 Set the priority of the current headline. The command prompts for a | 3015 Set the priority of the current headline. The command prompts for a |
2991 @c | 3020 @c |
2992 @kindex S-@key{up} | 3021 @kindex S-@key{up} |
2993 @kindex S-@key{down} | 3022 @kindex S-@key{down} |
2994 @item S-@key{up} | 3023 @item S-@key{up} |
2995 @itemx S-@key{down} | 3024 @itemx S-@key{down} |
2996 Increase/decrease priority of current headline. Note that these keys | 3025 Increase/decrease priority of current headline@footnote{See also the |
2997 are also used to modify time stamps (@pxref{Creating timestamps}). | 3026 option @code{org-priority-start-cycle-with-default'}.}. Note that these |
3027 keys are also used to modify time stamps (@pxref{Creating timestamps}). | |
2998 Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}). | 3028 Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}). |
2999 @end table | 3029 @end table |
3000 | 3030 |
3001 You can change the range of allowed priorities by setting the variables | 3031 You can change the range of allowed priorities by setting the variables |
3002 @code{org-highest-priority}, @code{org-lowest-priority}, and | 3032 @code{org-highest-priority}, @code{org-lowest-priority}, and |
3024 | 3054 |
3025 @node Checkboxes, , Breaking down tasks, TODO items | 3055 @node Checkboxes, , Breaking down tasks, TODO items |
3026 @section Checkboxes | 3056 @section Checkboxes |
3027 @cindex checkboxes | 3057 @cindex checkboxes |
3028 | 3058 |
3029 Every item in a plain list (@pxref{Plain lists}) can be made a checkbox | 3059 Every item in a plain list (@pxref{Plain lists}) can be made into a |
3030 by starting it with the string @samp{[ ]}. This feature is similar to | 3060 checkbox by starting it with the string @samp{[ ]}. This feature is |
3031 TODO items (@pxref{TODO items}), but more lightweight. Checkboxes are | 3061 similar to TODO items (@pxref{TODO items}), but is more lightweight. |
3032 not included into the global TODO list, so they are often great to split | 3062 Checkboxes are not included into the global TODO list, so they are often |
3033 a task into a number of simple steps. Or you can use them in a shopping | 3063 great to split a task into a number of simple steps. Or you can use |
3034 list. To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's | 3064 them in a shopping list. To toggle a checkbox, use @kbd{C-c C-c}, or |
3035 @file{org-mouse.el}. Here is an example of a checkbox list. | 3065 use the mouse (thanks to Piotr Zielinski's @file{org-mouse.el}). |
3066 | |
3067 Here is an example of a checkbox list. | |
3036 | 3068 |
3037 @example | 3069 @example |
3038 * TODO Organize party [3/6] | 3070 * TODO Organize party [3/6] |
3039 - call people [1/3] | 3071 - call people [1/3] |
3040 - [ ] Peter | 3072 - [ ] Peter |
3046 @end example | 3078 @end example |
3047 | 3079 |
3048 @cindex statistics, for checkboxes | 3080 @cindex statistics, for checkboxes |
3049 @cindex checkbox statistics | 3081 @cindex checkbox statistics |
3050 The @samp{[3/6]} and @samp{[1/3]} in the first and second line are | 3082 The @samp{[3/6]} and @samp{[1/3]} in the first and second line are |
3051 cookies indicating how many checkboxes are present in this entry, and | 3083 cookies indicating how many checkboxes present in this entry have been |
3052 how many of them have been checked off. This can give you an idea on | 3084 checked off, and the total number of checkboxes are present. This can |
3053 how many checkboxes remain, even without opening a folded entry. The | 3085 give you an idea on how many checkboxes remain, even without opening a |
3054 cookies can be placed into a headline or into (the first line of) a | 3086 folded entry. The cookies can be placed into a headline or into (the |
3055 plain list item. Each cookie covers all checkboxes structurally below | 3087 first line of) a plain list item. Each cookie covers all checkboxes |
3056 that headline/item. You have to insert the cookie yourself by typing | 3088 structurally below the headline/item on which the cookie appear. You |
3057 either @samp{[/]} or @samp{[%]}. In the first case you get an @samp{n | 3089 have to insert the cookie yourself by typing either @samp{[/]} or |
3058 out of m} result, in the second case you get information about the | 3090 @samp{[%]}. With @samp{[/]} you get an @samp{n out of m} result, as in |
3091 the examples above. With @samp{[%]} you get information about the | |
3059 percentage of checkboxes checked (in the above example, this would be | 3092 percentage of checkboxes checked (in the above example, this would be |
3060 @samp{[50%]} and @samp{[33%], respectively}). | 3093 @samp{[50%]} and @samp{[33%]}, respectively). |
3061 | 3094 |
3062 @noindent The following commands work with checkboxes: | 3095 @noindent The following commands work with checkboxes: |
3063 | 3096 |
3064 @table @kbd | 3097 @table @kbd |
3065 @kindex C-c C-c | 3098 @kindex C-c C-c |
3094 with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}. If you | 3127 with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}. If you |
3095 delete boxes or add/change them by hand, use this command to get things | 3128 delete boxes or add/change them by hand, use this command to get things |
3096 back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}. | 3129 back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}. |
3097 @end table | 3130 @end table |
3098 | 3131 |
3099 | |
3100 @node Tags, Properties and columns, TODO items, Top | 3132 @node Tags, Properties and columns, TODO items, Top |
3101 @chapter Tags | 3133 @chapter Tags |
3102 @cindex tags | 3134 @cindex tags |
3103 @cindex headline tagging | 3135 @cindex headline tagging |
3104 @cindex matching, tags | 3136 @cindex matching, tags |
3105 @cindex sparse tree, tag based | 3137 @cindex sparse tree, tag based |
3106 | 3138 |
3107 If you wish to implement a system of labels and contexts for | 3139 An excellent way to implement labels and contexts for cross-correlating |
3108 cross-correlating information, an excellent way is to assign @i{tags} to | 3140 information is to assign @i{tags} to headlines. Org-mode has extensive |
3109 headlines. Org-mode has extensive support for using tags. | 3141 support for tags. |
3110 | 3142 |
3111 Every headline can contain a list of tags, at the end of the headline. | 3143 Every headline can contain a list of tags; they occur at the end of the |
3112 Tags are normal words containing letters, numbers, @samp{_}, and | 3144 headline. Tags are normal words containing letters, numbers, @samp{_}, |
3113 @samp{@@}. Tags must be preceded and followed by a single colon; like | 3145 and @samp{@@}. Tags must be preceded and followed by a single colon, |
3114 @samp{:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}. | 3146 e.g., @samp{:WORK:}. Several tags can be specified, as in |
3147 @samp{:work:URGENT:}. | |
3115 | 3148 |
3116 @menu | 3149 @menu |
3117 * Tag inheritance:: Tags use the tree structure of the outline | 3150 * Tag inheritance:: Tags use the tree structure of the outline |
3118 * Setting tags:: How to assign tags to a headline | 3151 * Setting tags:: How to assign tags to a headline |
3119 * Tag searches:: Searching for combinations of tags | 3152 * Tag searches:: Searching for combinations of tags |
3120 @end menu | 3153 @end menu |
3121 | 3154 |
3122 @node Tag inheritance, Setting tags, Tags, Tags | 3155 @node Tag inheritance, Setting tags, Tags, Tags |
3123 @section Tag inheritance | 3156 @section Tag inheritance |
3157 @cindex tag inheritance | |
3124 @cindex inheritance, of tags | 3158 @cindex inheritance, of tags |
3125 @cindex sublevels, inclusion into tags match | 3159 @cindex sublevels, inclusion into tags match |
3126 | 3160 |
3127 @i{Tags} make use of the hierarchical structure of outline trees. If a | 3161 @i{Tags} make use of the hierarchical structure of outline trees. If a |
3128 heading has a certain tag, all subheadings will inherit the tag as | 3162 heading has a certain tag, all subheadings will inherit the tag as |
3129 well. For example, in the list | 3163 well. For example, in the list |
3130 | 3164 |
3131 @example | 3165 @example |
3132 * Meeting with the French group :WORK: | 3166 * Meeting with the French group :work: |
3133 ** Summary by Frank :BOSS:NOTES: | 3167 ** Summary by Frank :boss:notes: |
3134 *** TODO Prepare slides for him :ACTION: | 3168 *** TODO Prepare slides for him :action: |
3135 @end example | 3169 @end example |
3136 | 3170 |
3137 @noindent | 3171 @noindent |
3138 the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:}, | 3172 the final heading will have the tags @samp{:work:}, @samp{:boss:}, |
3139 @samp{:NOTES:}, and @samp{:ACTION:}. When executing tag searches and | 3173 @samp{:notes:}, and @samp{:action:} even though the final heading is not |
3174 explicitly marked with those tags. When executing tag searches and | |
3140 Org-mode finds that a certain headline matches the search criterion, it | 3175 Org-mode finds that a certain headline matches the search criterion, it |
3141 will not check any sublevel headline, assuming that these likely also | 3176 will not check any sublevel headline, assuming that these also match and |
3142 match, and that the list of matches can become very long. This may | 3177 that the list of matches could become very long because of that. If you |
3143 not be what you want, however, and you can influence inheritance and | 3178 do want the subevels be tested and listed as well, you may set the |
3144 searching using the variables @code{org-use-tag-inheritance} and | 3179 variable @code{org-tags-match-list-sublevels}. To turn off tag |
3145 @code{org-tags-match-list-sublevels}. | 3180 inheritance entirely, use the variable @code{org-use-tag-inheritance}. |
3146 | 3181 |
3147 @node Setting tags, Tag searches, Tag inheritance, Tags | 3182 @node Setting tags, Tag searches, Tag inheritance, Tags |
3148 @section Setting tags | 3183 @section Setting tags |
3149 @cindex setting tags | 3184 @cindex setting tags |
3150 @cindex tags, setting | 3185 @cindex tags, setting |
3172 currently used in the buffer. You may also globally specify a hard list | 3207 currently used in the buffer. You may also globally specify a hard list |
3173 of tags with the variable @code{org-tag-alist}. Finally you can set | 3208 of tags with the variable @code{org-tag-alist}. Finally you can set |
3174 the default tags for a given file with lines like | 3209 the default tags for a given file with lines like |
3175 | 3210 |
3176 @example | 3211 @example |
3177 #+TAGS: @@WORK @@HOME @@TENNISCLUB | 3212 #+TAGS: @@work @@home @@tennisclub |
3178 #+TAGS: Laptop Car PC Sailboat | 3213 #+TAGS: laptop car pc sailboat |
3179 @end example | 3214 @end example |
3180 | 3215 |
3181 If you have globally defined your preferred set of tags using the | 3216 If you have globally defined your preferred set of tags using the |
3182 variable @code{org-tag-alist}, but would like to use a dynamic tag list | 3217 variable @code{org-tag-alist}, but would like to use a dynamic tag list |
3183 in a specific file: Just add an empty TAGS option line to that file: | 3218 in a specific file, add an empty TAGS option line to that file: |
3184 | 3219 |
3185 @example | 3220 @example |
3186 #+TAGS: | 3221 #+TAGS: |
3187 @end example | 3222 @end example |
3188 | 3223 |
3191 selection}. This method allows to select and deselect tags with a | 3226 selection}. This method allows to select and deselect tags with a |
3192 single key per tag. To function efficiently, you should assign unique | 3227 single key per tag. To function efficiently, you should assign unique |
3193 keys to most tags. This can be done globally with | 3228 keys to most tags. This can be done globally with |
3194 | 3229 |
3195 @lisp | 3230 @lisp |
3196 (setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l))) | 3231 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) |
3197 @end lisp | 3232 @end lisp |
3198 | 3233 |
3199 @noindent or on a per-file basis with | 3234 @noindent or on a per-file basis with |
3200 | 3235 |
3201 @example | 3236 @example |
3202 #+TAGS: @@WORK(w) @@HOME(h) @@TENNISCLUB(t) Laptop(l) PC(p) | 3237 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) |
3203 @end example | 3238 @end example |
3204 | 3239 |
3205 @noindent | 3240 @noindent |
3206 You can also group together tags that are mutually exclusive. With | 3241 You can also group together tags that are mutually exclusive. With |
3207 curly braces@footnote{In @code{org-mode-alist} use | 3242 curly braces@footnote{In @code{org-mode-alist} use |
3208 @code{'(:startgroup)} and @code{'(:endgroup)}, respectively. Several | 3243 @code{'(:startgroup)} and @code{'(:endgroup)}, respectively. Several |
3209 groups are allowed.} | 3244 groups are allowed.} |
3210 | 3245 |
3211 @example | 3246 @example |
3212 #+TAGS: @{ @@WORK(w) @@HOME(h) @@TENNISCLUB(t) @} Laptop(l) PC(p) | 3247 #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p) |
3213 @end example | 3248 @end example |
3214 | 3249 |
3215 @noindent you indicate that at most one of @samp{@@WORK}, @samp{@@HOME}, | 3250 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home}, |
3216 and @samp{@@TENNISCLUB} should be selected. | 3251 and @samp{@@tennisclub} should be selected. |
3217 | 3252 |
3218 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of | 3253 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of |
3219 these lines to activate any changes. | 3254 these lines to activate any changes. |
3220 | 3255 |
3221 If at least one tag has a selection key, pressing @kbd{C-c C-c} will | 3256 If at least one tag has a selection key, pressing @kbd{C-c C-c} will |
3253 selection window. | 3288 selection window. |
3254 @end table | 3289 @end table |
3255 | 3290 |
3256 @noindent | 3291 @noindent |
3257 This method lets you assign tags to a headline with very few keys. With | 3292 This method lets you assign tags to a headline with very few keys. With |
3258 the above setup, you could clear the current tags and set @samp{@@HOME}, | 3293 the above setup, you could clear the current tags and set @samp{@@home}, |
3259 @samp{Laptop} and @samp{PC} tags with just the following keys: @kbd{C-c | 3294 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c |
3260 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@HOME} to | 3295 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to |
3261 @samp{@@WORK} would be done with @kbd{C-c C-c w @key{RET}} or | 3296 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or |
3262 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag | 3297 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag |
3263 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h | 3298 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h |
3264 @key{RET} @key{RET}}. | 3299 @key{RET} @key{RET}}. |
3265 | 3300 |
3266 If you find that most of the time, you need only a single keypress to | 3301 If you find that most of the time, you need only a single keypress to |
3277 @node Tag searches, , Setting tags, Tags | 3312 @node Tag searches, , Setting tags, Tags |
3278 @section Tag searches | 3313 @section Tag searches |
3279 @cindex tag searches | 3314 @cindex tag searches |
3280 @cindex searching for tags | 3315 @cindex searching for tags |
3281 | 3316 |
3282 Once a tags system has been set up, it can be used to collect related | 3317 Once a system of tags has been set up, it can be used to collect related |
3283 information into special lists. | 3318 information into special lists. |
3284 | 3319 |
3285 @table @kbd | 3320 @table @kbd |
3286 @kindex C-c \ | 3321 @kindex C-c \ |
3322 @kindex C-c / T | |
3287 @item C-c \ | 3323 @item C-c \ |
3324 @itemx C-c / T | |
3288 Create a sparse tree with all headlines matching a tags search. With a | 3325 Create a sparse tree with all headlines matching a tags search. With a |
3289 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line. | 3326 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line. |
3290 @kindex C-c a m | 3327 @kindex C-c a m |
3291 @item C-c a m | 3328 @item C-c a m |
3292 Create a global list of tag matches from all agenda files. | 3329 Create a global list of tag matches from all agenda files. |
3305 by @samp{-}, to select against it, and @samp{+} is syntactic sugar for | 3342 by @samp{-}, to select against it, and @samp{+} is syntactic sugar for |
3306 positive selection. The AND operator @samp{&} is optional when @samp{+} | 3343 positive selection. The AND operator @samp{&} is optional when @samp{+} |
3307 or @samp{-} is present. Examples: | 3344 or @samp{-} is present. Examples: |
3308 | 3345 |
3309 @table @samp | 3346 @table @samp |
3310 @item +WORK-BOSS | 3347 @item +work-boss |
3311 Select headlines tagged @samp{:WORK:}, but discard those also tagged | 3348 Select headlines tagged @samp{:work:}, but discard those also tagged |
3312 @samp{:BOSS:}. | 3349 @samp{:boss:}. |
3313 @item WORK|LAPTOP | 3350 @item work|laptop |
3314 Selects lines tagged @samp{:WORK:} or @samp{:LAPTOP:}. | 3351 Selects lines tagged @samp{:work:} or @samp{:laptop:}. |
3315 @item WORK|LAPTOP&NIGHT | 3352 @item work|laptop&night |
3316 Like before, but require the @samp{:LAPTOP:} lines to be tagged also | 3353 Like before, but require the @samp{:laptop:} lines to be tagged also |
3317 @samp{NIGHT}. | 3354 @samp{:night:}. |
3318 @end table | 3355 @end table |
3319 | 3356 |
3320 @cindex TODO keyword matching, with tags search | 3357 @cindex TODO keyword matching, with tags search |
3321 If you are using multi-state TODO keywords (@pxref{TODO extensions}), it | 3358 If you are using multi-state TODO keywords (@pxref{TODO extensions}), it |
3322 can be useful to also match on the TODO keyword. This can be done by | 3359 can be useful to also match on the TODO keyword. This can be done by |
3328 lines are checked that actually have any TODO keyword, use @kbd{C-c a | 3365 lines are checked that actually have any TODO keyword, use @kbd{C-c a |
3329 M}, or equivalently start the todo part after the slash with @samp{!}. | 3366 M}, or equivalently start the todo part after the slash with @samp{!}. |
3330 Examples: | 3367 Examples: |
3331 | 3368 |
3332 @table @samp | 3369 @table @samp |
3333 @item WORK/WAITING | 3370 @item work/WAITING |
3334 Select @samp{:WORK:}-tagged TODO lines with the specific TODO | 3371 Select @samp{:work:}-tagged TODO lines with the specific TODO |
3335 keyword @samp{WAITING}. | 3372 keyword @samp{WAITING}. |
3336 @item WORK/!-WAITING-NEXT | 3373 @item work/!-WAITING-NEXT |
3337 Select @samp{:WORK:}-tagged TODO lines that are neither @samp{WAITING} | 3374 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING} |
3338 nor @samp{NEXT} | 3375 nor @samp{NEXT} |
3339 @item WORK/+WAITING|+NEXT | 3376 @item work/+WAITING|+NEXT |
3340 Select @samp{:WORK:}-tagged TODO lines that are either @samp{WAITING} or | 3377 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or |
3341 @samp{NEXT}. | 3378 @samp{NEXT}. |
3342 @end table | 3379 @end table |
3343 | 3380 |
3344 @cindex regular expressions, with tags search | 3381 @cindex regular expressions, with tags search |
3345 Any element of the tag/todo match can be a regular expression - in this | 3382 Any element of the tag/todo match can be a regular expression - in this |
3346 case it must be enclosed in curly braces. For example, | 3383 case it must be enclosed in curly braces. For example, |
3347 @samp{WORK+@{^BOSS.*@}} matches headlines that contain the tag | 3384 @samp{work+@{^boss.*@}} matches headlines that contain the tag |
3348 @samp{WORK} and any tag @i{starting} with @samp{BOSS}. | 3385 @samp{:work:} and any tag @i{starting} with @samp{boss}. |
3349 | 3386 |
3350 @cindex level, require for tags match | 3387 @cindex level, require for tags/property match |
3351 You can also require a headline to be of a certain level, by writing | 3388 @cindex category, require for tags/property match |
3352 instead of any TAG an expression like @samp{LEVEL=3}. For example, a | 3389 You can also require a headline to be of a certain level or category, by |
3353 search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that | 3390 writing instead of any TAG an expression like @samp{LEVEL=3} or |
3354 have the tag BOSS and are @emph{not} marked with the todo keyword DONE. | 3391 @samp{CATEGORY="work"}, respectively. For example, a search |
3355 | 3392 @samp{+LEVEL=3+boss/-DONE} lists all level three headlines that have the |
3356 @node Properties and columns, Timestamps, Tags, Top | 3393 tag @samp{boss} and are @emph{not} marked with the todo keyword DONE. |
3394 | |
3395 @node Properties and columns, Dates and times, Tags, Top | |
3357 @chapter Properties and Columns | 3396 @chapter Properties and Columns |
3358 @cindex properties | 3397 @cindex properties |
3359 | 3398 |
3360 Properties are a set of key-value pairs associated with an entry. There | 3399 Properties are a set of key-value pairs associated with an entry. There |
3361 are two main applications for properties in Org-mode. First, properties | 3400 are two main applications for properties in Org-mode. First, properties |
3362 are like tags, but with a value. For example, in a file where you | 3401 are like tags, but with a value. Second, you can use properties to |
3363 document bugs and plan releases of a piece of software, instead of using | 3402 implement (very basic) database capabilities in an Org-mode buffer. For |
3364 tags like @code{:release_1:}, @code{:release_2:}, it can be more | 3403 an example of the first application, imagine maintaining a file where |
3365 efficient to use a property @code{RELEASE} with a value @code{1.0} or | 3404 you document bugs and plan releases of a piece of software. Instead of |
3366 @code{2.0}. Second, you can use properties to implement (very basic) | 3405 using tags like @code{:release_1:}, @code{:release_2:}, one can use a |
3367 database capabilities in an Org-mode buffer, for example to create a | 3406 property, say @code{:Release:}, that in different subtrees has different |
3368 list of Music CD's you own. You can edit and view properties | 3407 values, such as @code{1.0} or @code{2.0}. For an example of the second |
3408 application of properties, imagine keeping track of one's music CD's, | |
3409 where properties could be things such as the album artist, date of | |
3410 release, number of tracks, and so on. | |
3411 | |
3412 Properties can be conveiently edited and viewed in column view | |
3413 (@pxref{Column view}). | |
3414 | |
3415 Properties are like tags, but with a value. For example, in a file | |
3416 where you document bugs and plan releases of a piece of software, | |
3417 instead of using tags like @code{:release_1:}, @code{:release_2:}, it | |
3418 can be more efficient to use a property @code{:Release:} with a value | |
3419 @code{1.0} or @code{2.0}. Second, you can use properties to implement | |
3420 (very basic) database capabilities in an Org-mode buffer, for example to | |
3421 create a list of Music CD's you own. You can edit and view properties | |
3369 conveniently in column view (@pxref{Column view}). | 3422 conveniently in column view (@pxref{Column view}). |
3370 | 3423 |
3371 @menu | 3424 @menu |
3372 * Property syntax:: How properties are spelled out | 3425 * Property syntax:: How properties are spelled out |
3373 * Special properties:: Access to other Org-mode features | 3426 * Special properties:: Access to other Org-mode features |
3374 * Property searches:: Matching property values | 3427 * Property searches:: Matching property values |
3428 * Property inheritance:: Passing values down the tree | |
3375 * Column view:: Tabular viewing and editing | 3429 * Column view:: Tabular viewing and editing |
3376 * Property API:: Properties for Lisp programmers | 3430 * Property API:: Properties for Lisp programmers |
3377 @end menu | 3431 @end menu |
3378 | 3432 |
3379 @node Property syntax, Special properties, Properties and columns, Properties and columns | 3433 @node Property syntax, Special properties, Properties and columns, Properties and columns |
3397 :Publisher: Deutsche Grammphon | 3451 :Publisher: Deutsche Grammphon |
3398 :NDisks: 1 | 3452 :NDisks: 1 |
3399 :END: | 3453 :END: |
3400 @end example | 3454 @end example |
3401 | 3455 |
3402 You may define the allowed values for a particular property @samp{XYZ} | 3456 You may define the allowed values for a particular property @samp{:Xyz:} |
3403 by setting a property @samp{XYZ_ALL}. This special property is | 3457 by setting a property @samp{:Xyz_ALL:}. This special property is |
3404 @emph{inherited}, so if you set it in a level 1 entry, it will apply to | 3458 @emph{inherited}, so if you set it in a level 1 entry, it will apply to |
3405 the entire tree. When allowed values are defined, setting the | 3459 the entire tree. When allowed values are defined, setting the |
3406 corresponding property becomes easier and is less prone to typing | 3460 corresponding property becomes easier and is less prone to typing |
3407 errors. For the example with the CD collection, we can predefine | 3461 errors. For the example with the CD collection, we can predefine |
3408 publishers and the number of disks in a box like this: | 3462 publishers and the number of disks in a box like this: |
3432 @table @kbd | 3486 @table @kbd |
3433 @kindex M-@key{TAB} | 3487 @kindex M-@key{TAB} |
3434 @item M-@key{TAB} | 3488 @item M-@key{TAB} |
3435 After an initial colon in a line, complete property keys. All keys used | 3489 After an initial colon in a line, complete property keys. All keys used |
3436 in the current file will be offered as possible completions. | 3490 in the current file will be offered as possible completions. |
3491 @kindex C-c C-x p | |
3492 @item C-c C-x p | |
3493 Set a property. This prompts for a property name and a value. If | |
3494 necessary, the property drawer is created as well. | |
3437 @item M-x org-insert-property-drawer | 3495 @item M-x org-insert-property-drawer |
3438 Insert a property drawer into the current entry. The drawer will be | 3496 Insert a property drawer into the current entry. The drawer will be |
3439 inserted early in the entry, but after the lines with planning | 3497 inserted early in the entry, but after the lines with planning |
3440 information like deadlines. | 3498 information like deadlines. |
3441 @kindex C-c C-c | 3499 @kindex C-c C-c |
3450 Switch property at point to the next/previous allowed value. | 3508 Switch property at point to the next/previous allowed value. |
3451 @item C-c C-c d | 3509 @item C-c C-c d |
3452 Remove a property from the current entry. | 3510 Remove a property from the current entry. |
3453 @item C-c C-c D | 3511 @item C-c C-c D |
3454 Globally remove a property, from all entries in the current file. | 3512 Globally remove a property, from all entries in the current file. |
3513 @item C-c C-c c | |
3514 Compute the property at point, using the operator and scope from the | |
3515 nearest column format definition. | |
3455 @end table | 3516 @end table |
3456 | 3517 |
3457 @node Special properties, Property searches, Property syntax, Properties and columns | 3518 @node Special properties, Property searches, Property syntax, Properties and columns |
3458 @section Special Properties | 3519 @section Special Properties |
3459 @cindex properties, special | 3520 @cindex properties, special |
3460 | 3521 |
3461 Special properties provide alternative access method to Org-mode | 3522 Special properties provide alternative access method to Org-mode |
3462 features discussed in the previous chapters, like the TODO state or the | 3523 features discussed in the previous chapters, like the TODO state or the |
3463 priority of an entry. This interface exists so that you can include | 3524 priority of an entry. This interface exists so that you can include |
3464 these states into columns view (@pxref{Column view}). The following | 3525 these states into columns view (@pxref{Column view}), or to use them in |
3465 property names are special and should not be used as keys in the | 3526 queries. The following property names are special and should not be |
3466 properties drawer: | 3527 used as keys in the properties drawer: |
3467 | 3528 |
3468 @example | 3529 @example |
3469 TODO @r{The TODO keyword of the entry.} | 3530 TODO @r{The TODO keyword of the entry.} |
3470 TAGS @r{The tags defined directly in the headline.} | 3531 TAGS @r{The tags defined directly in the headline.} |
3471 ALLTAGS @r{All tags, including inherited ones.} | 3532 ALLTAGS @r{All tags, including inherited ones.} |
3472 PRIORITY @r{The priority of the entry, a string with a single letter.} | 3533 PRIORITY @r{The priority of the entry, a string with a single letter.} |
3473 DEADLINE @r{The deadline time string, without the angular brackets.} | 3534 DEADLINE @r{The deadline time string, without the angular brackets.} |
3474 SCHEDULED @r{The scheduling time stamp, without the angular brackets.} | 3535 SCHEDULED @r{The scheduling time stamp, without the angular brackets.} |
3475 @end example | 3536 TIMESTAMP @r{The first keyword-less time stamp in the entry.} |
3476 | 3537 TIMESTAMP_IA @r{The first inactive time stamp in the entry.} |
3477 @node Property searches, Column view, Special properties, Properties and columns | 3538 CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}} |
3539 @r{must be run first to compute the values.} | |
3540 @end example | |
3541 | |
3542 @node Property searches, Property inheritance, Special properties, Properties and columns | |
3478 @section Property searches | 3543 @section Property searches |
3479 @cindex properties, searching | 3544 @cindex properties, searching |
3545 @cindex properties, inheritance | |
3546 @cindex searching, of properties | |
3547 @cindex inheritance, of properties | |
3480 | 3548 |
3481 To create sparse trees and special lists with selection based on | 3549 To create sparse trees and special lists with selection based on |
3482 properties, the same commands are used as for tag searches (@pxref{Tag | 3550 properties, the same commands are used as for tag searches (@pxref{Tag |
3483 searches}), and the same logic applies. For example, a search string | 3551 searches}), and the same logic applies. For example, a search string |
3484 | 3552 |
3485 @example | 3553 @example |
3486 +WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with=@{Sarah\|Denny@} | 3554 +work-boss+PRIORITY="A"+Coffee="unlimited"+With=@{Sarah\|Denny@} |
3487 @end example | 3555 @end example |
3488 | 3556 |
3489 @noindent | 3557 @noindent |
3490 finds entries tagged @samp{:WORK:} but not @samp{:BOSS:}, which | 3558 finds entries tagged @samp{:work:} but not @samp{:boss:}, which |
3491 also have a priority value @samp{A}, a @samp{:coffee:} property with the | 3559 also have a priority value @samp{A}, a @samp{:Coffee:} property with the |
3492 value @samp{unlimited}, and a @samp{:with:} property that is matched by | 3560 value @samp{unlimited}, and a @samp{:With:} property that is matched by |
3493 the regular expression @samp{Sarah\|Denny}. | 3561 the regular expression @samp{Sarah\|Denny}. |
3494 | 3562 |
3495 @node Column view, Property API, Property searches, Properties and columns | 3563 You can configure Org-mode to use property inheritance during a search, |
3564 see @ref{Property inheritance} for details. | |
3565 | |
3566 There is also a special command for creating sparse trees based on a | |
3567 single property: | |
3568 | |
3569 @table @kbd | |
3570 @kindex C-c / p | |
3571 @item C-c / p | |
3572 Create a sparse tree based on the value of a property. This first | |
3573 prompts for the name of a property, and then for a value. A sparse tree | |
3574 is created with all entries that define this property with the given | |
3575 value. If you enclose the value into curly braces, it is interpreted as | |
3576 a regular expression and matched against the property values. | |
3577 @end table | |
3578 | |
3579 @node Property inheritance, Column view, Property searches, Properties and columns | |
3580 @section Property Inheritance | |
3581 | |
3582 The outline structure of Org-mode documents lends itself for an | |
3583 inheritance model of properties: If the parent in a tree has a certain | |
3584 property, the children can inherit this property. Org-mode does not | |
3585 turn this on by default, because it can slow down property searches | |
3586 significantly and is often not needed. However, if you find inheritance | |
3587 useful, you can turn it on by setting the variable | |
3588 @code{org-use-property-inheritance}. It may be set to @code{t}, to make | |
3589 all properties inherited from the parent, or to a list of properties | |
3590 that should be inherited. | |
3591 | |
3592 Org-mode has a few properties for which inheritance is hard-coded, at | |
3593 least for the special applications for which they are used: | |
3594 | |
3595 @table @code | |
3596 @item COLUMNS | |
3597 The @code{:COLUMNS:} property defines the format of column view | |
3598 (@pxref{Column view}). It is inherited in the sense that the level | |
3599 where a @code{:COLUMNS:} property is defined is used as the starting | |
3600 point for a column view table, independently of the location in the | |
3601 subtree from where columns view is turned on. | |
3602 @item CATEGORY | |
3603 For agenda view, a category set through a @code{:CATEGORY:} property | |
3604 applies to the entire subtree. | |
3605 @item ARCHIVE | |
3606 For archiving, the @code{:ARCHIVE:} property may define the archive | |
3607 location for the entire subtree (@pxref{Moving subtrees}). | |
3608 @end table | |
3609 | |
3610 @node Column view, Property API, Property inheritance, Properties and columns | |
3496 @section Column View | 3611 @section Column View |
3497 | 3612 |
3498 A great way to view and edit properties in an outline tree is | 3613 A great way to view and edit properties in an outline tree is |
3499 @emph{column view}. In column view, each outline item is turned into a | 3614 @emph{column view}. In column view, each outline item is turned into a |
3500 table row. Columns in this table provide access to properties of the | 3615 table row. Columns in this table provide access to properties of the |
3510 queries have collected selected items, possibly from a number of files. | 3625 queries have collected selected items, possibly from a number of files. |
3511 | 3626 |
3512 @menu | 3627 @menu |
3513 * Defining columns:: The COLUMNS format property | 3628 * Defining columns:: The COLUMNS format property |
3514 * Using column view:: How to create and use column view | 3629 * Using column view:: How to create and use column view |
3630 * Capturing Column View:: A dynamic block for column view | |
3515 @end menu | 3631 @end menu |
3516 | 3632 |
3517 @node Defining columns, Using column view, Column view, Column view | 3633 @node Defining columns, Using column view, Column view, Column view |
3518 @subsection Defining Columns | 3634 @subsection Defining Columns |
3519 @cindex column view, for properties | 3635 @cindex column view, for properties |
3534 | 3650 |
3535 @example | 3651 @example |
3536 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO | 3652 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO |
3537 @end example | 3653 @end example |
3538 | 3654 |
3539 To specify a format that only applies to a specific tree, add a COLUMNS | 3655 To specify a format that only applies to a specific tree, add a |
3540 property to the top node of that tree, for example | 3656 @code{:COLUMNS:} property to the top node of that tree, for example: |
3657 | |
3541 @example | 3658 @example |
3542 ** Top node for columns view | 3659 ** Top node for columns view |
3543 :PROPERTIES: | 3660 :PROPERTIES: |
3544 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO | 3661 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO |
3545 :END: | 3662 :END: |
3546 @end example | 3663 @end example |
3547 | 3664 |
3548 If a @code{COLUMNS} property is present in an entry, it defines columns | 3665 If a @code{:COLUMNS:} property is present in an entry, it defines columns |
3549 for the entry itself, and for the entire subtree below it. Since the | 3666 for the entry itself, and for the entire subtree below it. Since the |
3550 column definition is part of the hierarchical structure of the document, | 3667 column definition is part of the hierarchical structure of the document, |
3551 you can define columns on level 1 that are general enough for all | 3668 you can define columns on level 1 that are general enough for all |
3552 sublevels, and more specific columns further down, when you edit a | 3669 sublevels, and more specific columns further down, when you edit a |
3553 deeper part of the tree. | 3670 deeper part of the tree. |
3572 (title) @r{The header text for the column. If omitted, the} | 3689 (title) @r{The header text for the column. If omitted, the} |
3573 @r{property name is used.} | 3690 @r{property name is used.} |
3574 @{summary-type@} @r{The summary type. If specified, the column values for} | 3691 @{summary-type@} @r{The summary type. If specified, the column values for} |
3575 @r{parent nodes are computed from the children.} | 3692 @r{parent nodes are computed from the children.} |
3576 @r{Supported summary types are:} | 3693 @r{Supported summary types are:} |
3577 @{+@} @r{Sum numbers in this column.} | 3694 @{+@} @r{Sum numbers in this column.} |
3578 @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.} | 3695 @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.} |
3579 @{X@} @r{Checkbox status, [X] if all children are [X].} | 3696 @{$@} @r{Currency, short for @samp{+;%.2f}.} |
3697 @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.} | |
3698 @{X@} @r{Checkbox status, [X] if all children are [X].} | |
3580 @end example | 3699 @end example |
3581 | 3700 |
3582 @noindent | 3701 @noindent |
3583 Here is an example for a complete columns definition, along with allowed | 3702 Here is an example for a complete columns definition, along with allowed |
3584 values. | 3703 values. |
3585 | 3704 |
3586 @example | 3705 @example |
3587 :COLUMNS: %20ITEM %9Approved(Approved?)@{X@} %Owner %11Status %10Time_Spent@{:@} | 3706 :COLUMNS: %20ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line - it is wrapped here only because of formatting constraints.} |
3707 %10Time_Estimate@{:@} %CLOCKSUM | |
3588 :Owner_ALL: Tammy Mark Karl Lisa Don | 3708 :Owner_ALL: Tammy Mark Karl Lisa Don |
3589 :Status_ALL: "In progress" "Not started yet" "Finished" "" | 3709 :Status_ALL: "In progress" "Not started yet" "Finished" "" |
3590 :Approved_ALL: "[ ]" "[X]" | 3710 :Approved_ALL: "[ ]" "[X]" |
3591 @end example | 3711 @end example |
3592 | 3712 |
3597 @samp{Status} with four different possible values, and for a checkbox | 3717 @samp{Status} with four different possible values, and for a checkbox |
3598 field @samp{Approved}. When no width is given after the @samp{%} | 3718 field @samp{Approved}. When no width is given after the @samp{%} |
3599 character, the column will be exactly as wide as it needs to be in order | 3719 character, the column will be exactly as wide as it needs to be in order |
3600 to fully display all values. The @samp{Approved} column does have a | 3720 to fully display all values. The @samp{Approved} column does have a |
3601 modified title (@samp{Approved?}, with a question mark). Summaries will | 3721 modified title (@samp{Approved?}, with a question mark). Summaries will |
3602 be created for the @samp{Time_Spent} column by adding time duration | 3722 be created for the @samp{Time_Estimate} column by adding time duration |
3603 expressions like HH:MM, and for the @samp{Approved} column, by providing | 3723 expressions like HH:MM, and for the @samp{Approved} column, by providing |
3604 an @samp{[X]} status if all children have been checked. | 3724 an @samp{[X]} status if all children have been checked. The |
3605 | 3725 @samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals |
3606 @node Using column view, , Defining columns, Column view | 3726 in the subtree. |
3727 | |
3728 @node Using column view, Capturing Column View, Defining columns, Column view | |
3607 @subsection Using Column View | 3729 @subsection Using Column View |
3608 | 3730 |
3609 @table @kbd | 3731 @table @kbd |
3610 @tsubheading{Turning column view on and off} | 3732 @tsubheading{Turning column view on and off} |
3611 @kindex C-c C-x C-c | 3733 @kindex C-c C-x C-c |
3612 @item C-c C-x C-c | 3734 @item C-c C-x C-c |
3613 Create the column view for the local environment. This command searches | 3735 Create the column view for the local environment. This command searches |
3614 the hierarchy, up from point, for a @code{COLUMNS} property that defines | 3736 the hierarchy, up from point, for a @code{:COLUMNS:} property that defines |
3615 a format. When one is found, the column view table is established for | 3737 a format. When one is found, the column view table is established for |
3616 the entire tree, starting from the entry that contains the @code{COLUMNS} | 3738 the entire tree, starting from the entry that contains the @code{:COLUMNS:} |
3617 property. If none is found, the format is taken from the @code{#+COLUMNS} | 3739 property. If none is found, the format is taken from the @code{#+COLUMNS} |
3618 line or from the variable @code{org-columns-default-format}, and column | 3740 line or from the variable @code{org-columns-default-format}, and column |
3619 view is established for the current entry and its subtree. | 3741 view is established for the current entry and its subtree. |
3620 @kindex q | 3742 @kindex q |
3621 @item q | 3743 @item q |
3636 @item e | 3758 @item e |
3637 Edit the property at point. For the special properties, this will | 3759 Edit the property at point. For the special properties, this will |
3638 invoke the same interface that you normally use to change that | 3760 invoke the same interface that you normally use to change that |
3639 property. For example, when editing a TAGS property, the tag completion | 3761 property. For example, when editing a TAGS property, the tag completion |
3640 or fast selection interface will pop up. | 3762 or fast selection interface will pop up. |
3763 @kindex C-c C-c | |
3764 @item C-c C-c | |
3765 When there is a checkbox at point, toggle it. | |
3641 @kindex v | 3766 @kindex v |
3642 @item v | 3767 @item v |
3643 View the full value of this property. This is useful if the width of | 3768 View the full value of this property. This is useful if the width of |
3644 the column is smaller than that of the value. | 3769 the column is smaller than that of the value. |
3645 @kindex a | 3770 @kindex a |
3659 @kindex S-M-@key{left} | 3784 @kindex S-M-@key{left} |
3660 @item S-M-@key{left} | 3785 @item S-M-@key{left} |
3661 Delete the current column. | 3786 Delete the current column. |
3662 @end table | 3787 @end table |
3663 | 3788 |
3789 @node Capturing Column View, , Using column view, Column view | |
3790 @subsection Capturing Column View | |
3791 | |
3792 Since column view is just an overlay over a buffer, it cannot be | |
3793 exported or printed directly. If you want to capture a column view, use | |
3794 the dynamic block (@pxref{Dynamic blocks}). The frame of this block | |
3795 looks like this: | |
3796 | |
3797 @example | |
3798 * The column view | |
3799 #+BEGIN: columnview :hlines 1 :id "label" | |
3800 | |
3801 #+END: | |
3802 @end example | |
3803 | |
3804 @noindent This dynamic block has the following parameters: | |
3805 | |
3806 @table @code | |
3807 @item :id | |
3808 This is most important parameter. Column view is a feature that is | |
3809 often localized to a certain (sub)tree, and the capture block might be | |
3810 in a different location in the file. To identify the tree whose view to | |
3811 capture, you can use 3 values: | |
3812 @example | |
3813 local @r{use the tree in which the capture block is located} | |
3814 global @r{make a global view, including all headings in the file} | |
3815 "label" @r{call column view in the tree that has and @code{:ID:}} | |
3816 @r{property with the value @i{label}} | |
3817 @end example | |
3818 @item :hlines | |
3819 When @code{t}, insert a hline after every line. When a number N, insert | |
3820 a hline before each headline with level @code{<= N}. | |
3821 @item :vlines | |
3822 When set to @code{t}, enforce column groups to get vertical lines. | |
3823 @end table | |
3824 | |
3825 @noindent | |
3826 The following commands insert or update the dynamic block: | |
3827 | |
3828 @table @kbd | |
3829 @kindex C-c C-x r | |
3830 @item C-c C-x r | |
3831 Insert a dynamic block capturing a column view. You will be prompted | |
3832 for the scope or id of the view. | |
3833 @kindex C-c C-c | |
3834 @item C-c C-c | |
3835 @kindex C-c C-x C-u | |
3836 @itemx C-c C-x C-u | |
3837 Update dynamical block at point. The cursor needs to be in the | |
3838 @code{#+BEGIN} line of the dynamic block. | |
3839 @kindex C-u C-c C-x C-u | |
3840 @item C-u C-c C-x C-u | |
3841 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if | |
3842 you have several clocktable blocks in a buffer. | |
3843 @end table | |
3844 | |
3664 @node Property API, , Column view, Properties and columns | 3845 @node Property API, , Column view, Properties and columns |
3665 @section The Property API | 3846 @section The Property API |
3666 @cindex properties, API | 3847 @cindex properties, API |
3667 @cindex API, for properties | 3848 @cindex API, for properties |
3668 | 3849 |
3669 There is a full API for accessing and changing properties. This API can | 3850 There is a full API for accessing and changing properties. This API can |
3670 be used by Emacs Lisp programs to work with properties and to implement | 3851 be used by Emacs Lisp programs to work with properties and to implement |
3671 features based on them. For more information see @ref{Using the | 3852 features based on them. For more information see @ref{Using the |
3672 property API}. | 3853 property API}. |
3673 | 3854 |
3674 @node Timestamps, Agenda views, Properties and columns, Top | 3855 @node Dates and times, Remember, Properties and columns, Top |
3675 @chapter Timestamps | 3856 @chapter Dates and Times |
3857 @cindex dates | |
3858 @cindex times | |
3676 @cindex time stamps | 3859 @cindex time stamps |
3677 @cindex date stamps | 3860 @cindex date stamps |
3678 | 3861 |
3679 Items can be labeled with timestamps to make them useful for project | 3862 To assist project planning, TODO items can be labeled with a date and/or |
3680 planning. | 3863 a time. The specially formatted string carrying the date and time |
3864 information is called a @emph{timestamp} in Org-mode. This may be a | |
3865 little confusing because timestamp is often used as indicating when | |
3866 something was created or last changed. However, in Org-mode this term | |
3867 is used in a much wider sense. | |
3681 | 3868 |
3682 @menu | 3869 @menu |
3683 * Time stamps:: Assigning a time to a tree entry | 3870 * Time stamps:: Assigning a time to a tree entry |
3684 * Creating timestamps:: Commands which insert timestamps | 3871 * Creating timestamps:: Commands which insert timestamps |
3685 * Deadlines and scheduling:: Planning your work | 3872 * Deadlines and scheduling:: Planning your work |
3686 * Progress logging:: Documenting when what work was done. | 3873 * Clocking work time:: |
3687 @end menu | 3874 @end menu |
3688 | 3875 |
3689 | 3876 |
3690 @node Time stamps, Creating timestamps, Timestamps, Timestamps | 3877 @node Time stamps, Creating timestamps, Dates and times, Dates and times |
3691 @section Time stamps, deadlines and scheduling | 3878 @section Time stamps, deadlines and scheduling |
3692 @cindex time stamps | 3879 @cindex time stamps |
3693 @cindex ranges, time | 3880 @cindex ranges, time |
3694 @cindex date stamps | 3881 @cindex date stamps |
3695 @cindex deadlines | 3882 @cindex deadlines |
3696 @cindex scheduling | 3883 @cindex scheduling |
3697 | 3884 |
3698 A time stamp is a specification of a date (possibly with time or a range | 3885 A time stamp is a specification of a date (possibly with time or a range |
3699 of times) in a special format, either @samp{<2003-09-16 Tue>} or | 3886 of times) in a special format, either @samp{<2003-09-16 Tue>} or |
3700 @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue | 3887 @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue |
3701 12:00-12:30>}@footnote{This is the standard ISO date/time format. If | 3888 12:00-12:30>}@footnote{This is the standard ISO date/time format. To |
3702 you cannot get used to these, see @ref{Custom time format}}. A time | 3889 use an alternative format, see @ref{Custom time format}.}. A time stamp |
3703 stamp can appear anywhere in the headline or body of an org-tree entry. | 3890 can appear anywhere in the headline or body of an org-tree entry. Its |
3704 Its presence causes entries to be shown on specific dates in the agenda | 3891 presence causes entries to be shown on specific dates in the agenda |
3705 (@pxref{Weekly/Daily agenda}). We distinguish: | 3892 (@pxref{Weekly/Daily agenda}). We distinguish: |
3706 | 3893 |
3707 @table @var | 3894 @table @var |
3708 @item Plain time stamp | 3895 @item Plain time stamp; Event; Appointment |
3709 @cindex timestamp | 3896 @cindex timestamp |
3710 A simple time stamp just assigns a date/time to an item. This is just | 3897 A simple time stamp just assigns a date/time to an item. This is just |
3711 like writing down an appointment in a paper agenda, or like writing down | 3898 like writing down an appointment or event in a paper agenda. In the |
3712 an event in a diary, when you want to take note of when something | 3899 timeline and agenda displays, the headline of an entry associated with a |
3713 happened. In the timeline and agenda displays, the headline of an entry | 3900 plain time stamp will be shown exactly on that date. |
3714 associated with a plain time stamp will be shown exactly on that date. | |
3715 | 3901 |
3716 @example | 3902 @example |
3717 * Meet Peter at the movies <2006-11-01 Wed 19:15> | 3903 * Meet Peter at the movies <2006-11-01 Wed 19:15> |
3718 * Discussion on climate change <2006-11-02 Thu 20:00-22:00> | 3904 * Discussion on climate change <2006-11-02 Thu 20:00-22:00> |
3719 @end example | 3905 @end example |
3762 * Gillian comes late for the fifth time [2006-11-01 Wed] | 3948 * Gillian comes late for the fifth time [2006-11-01 Wed] |
3763 @end example | 3949 @end example |
3764 | 3950 |
3765 @end table | 3951 @end table |
3766 | 3952 |
3767 @node Creating timestamps, Deadlines and scheduling, Time stamps, Timestamps | 3953 @node Creating timestamps, Deadlines and scheduling, Time stamps, Dates and times |
3768 @section Creating timestamps | 3954 @section Creating timestamps |
3769 @cindex creating timestamps | 3955 @cindex creating timestamps |
3770 @cindex timestamps, creating | 3956 @cindex timestamps, creating |
3771 | 3957 |
3772 For Org-mode to recognize time stamps, they need to be in the specific | 3958 For Org-mode to recognize time stamps, they need to be in the specific |
3840 @node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps | 4026 @node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps |
3841 @subsection The date/time prompt | 4027 @subsection The date/time prompt |
3842 @cindex date, reading in minibuffer | 4028 @cindex date, reading in minibuffer |
3843 @cindex time, reading in minibuffer | 4029 @cindex time, reading in minibuffer |
3844 | 4030 |
3845 When Org-mode prompts for a date/time, the prompt suggests to enter an | 4031 When Org-mode prompts for a date/time, the default is shown as an ISO |
3846 ISO date. But it will in fact accept any string containing some date | 4032 date, and the prompt therefore seems to ask for an ISO date. But it |
3847 and/or time information. You can, for example, use @kbd{C-y} to paste a | 4033 will in fact accept any string containing some date and/or time |
3848 (possibly multi-line) string copied from an email message. Org-mode | 4034 information, and it is really smart about interpreting your input. You |
3849 will find whatever information is in there and will replace anything not | 4035 can, for example, use @kbd{C-y} to paste a (possibly multi-line) string |
3850 specified with the current date and time. For example: | 4036 copied from an email message. Org-mode will find whatever information |
3851 | 4037 is in there and derive anything you have not specified from the |
3852 @example | 4038 @emph{default date and time}. The default is usually the current date |
3853 3-2-5 --> 2003-02-05 | 4039 and time, but when modifying an existing time stamp, or when entering |
3854 feb 15 --> currentyear-02-15 | 4040 the second stamp of a range, it is taken from the stamp in the buffer. |
3855 sep 12 9 --> 2009-09-12 | 4041 When filling in information, Org-mode assumes that most of the time you |
3856 12:45 --> today 12:45 | 4042 will want to enter a date in the future: If you omit the month/year and |
3857 22 sept 0:34 --> currentyear-09-22 0:34 | 4043 the given day/month is @i{before} today, it will assume that you mean a |
3858 12 --> currentyear-currentmonth-12 | 4044 future date@footnote{See the variable |
3859 Fri --> nearest Friday (today or later) | 4045 @code{org-read-date-prefer-future}.}. |
3860 +4 --> 4 days from now (if +N is the only thing given) | 4046 |
4047 For example, lets assume that today is @b{June 13, 2006}. Here is how | |
4048 various inputs will be interpreted, the items filled in by Org-mode are | |
4049 in @b{bold}. | |
4050 | |
4051 @example | |
4052 3-2-5 --> 2003-02-05 | |
4053 14 --> @b{2006}-@b{06}-14 | |
4054 12 --> @b{2006}-@b{07}-12 | |
4055 Fri --> nearest Friday (defaultdate or later) | |
4056 sep 15 --> @b{2006}-11-15 | |
4057 feb 15 --> @b{2007}-02-15 | |
4058 sep 12 9 --> 2009-09-12 | |
4059 12:45 --> @b{2006}-@b{06}-@b{13} 12:45 | |
4060 22 sept 0:34 --> @b{2006}-09-22 0:34 | |
4061 @end example | |
4062 | |
4063 Furthermore you can specify a relative date by giving, as the | |
4064 @emph{first} thing in the input: a plus/minus sign, a number and a | |
4065 letter [dwmy] to indicate change in days weeks, months, years. With a | |
4066 single plus or minus, the date is always relative to today. With a | |
4067 double plus or minus, it is relative to the default date. If instead of | |
4068 a single letter, you use the abbreviation of day name, the date will be | |
4069 the nth such day. E.g. | |
4070 | |
4071 @example | |
4072 +4d --> four days from today | |
4073 +4 --> same as above | |
4074 +2w --> two weeks from today | |
4075 ++5 --> five days from default date | |
4076 +2tue --> second tuesday from now. | |
3861 @end example | 4077 @end example |
3862 | 4078 |
3863 The function understands English month and weekday abbreviations. If | 4079 The function understands English month and weekday abbreviations. If |
3864 you want to use unabbreviated names and/or other languages, configure | 4080 you want to use unabbreviated names and/or other languages, configure |
3865 the variables @code{parse-time-months} and @code{parse-time-weekdays}. | 4081 the variables @code{parse-time-months} and @code{parse-time-weekdays}. |
3871 prompt, either by clicking on a date in the calendar, or by pressing | 4087 prompt, either by clicking on a date in the calendar, or by pressing |
3872 @key{RET}, the date selected in the calendar will be combined with the | 4088 @key{RET}, the date selected in the calendar will be combined with the |
3873 information entered at the prompt. You can control the calendar fully | 4089 information entered at the prompt. You can control the calendar fully |
3874 from the minibuffer: | 4090 from the minibuffer: |
3875 | 4091 |
3876 @table @kbd | |
3877 @kindex < | 4092 @kindex < |
3878 @item < | |
3879 Scroll calendar backwards by one month. | |
3880 @kindex > | 4093 @kindex > |
3881 @item > | |
3882 Scroll calendar forwards by one month. | |
3883 @kindex mouse-1 | 4094 @kindex mouse-1 |
3884 @item mouse-1 | |
3885 Select date by clicking on it. | |
3886 @kindex S-@key{right} | 4095 @kindex S-@key{right} |
3887 @item S-@key{right} | |
3888 One day forward. | |
3889 @kindex S-@key{left} | 4096 @kindex S-@key{left} |
3890 @item S-@key{left} | |
3891 One day back. | |
3892 @kindex S-@key{down} | 4097 @kindex S-@key{down} |
3893 @item S-@key{down} | |
3894 One week forward. | |
3895 @kindex S-@key{up} | 4098 @kindex S-@key{up} |
3896 @item S-@key{up} | |
3897 One week back. | |
3898 @kindex M-S-@key{right} | 4099 @kindex M-S-@key{right} |
3899 @item M-S-@key{right} | |
3900 One month forward. | |
3901 @kindex M-S-@key{left} | 4100 @kindex M-S-@key{left} |
3902 @item M-S-@key{left} | |
3903 One month back. | |
3904 @kindex @key{RET} | 4101 @kindex @key{RET} |
3905 @item @key{RET} | 4102 @example |
3906 Choose date in calendar (only if nothing was typed into minibuffer). | 4103 > / < @r{Scroll calendar forward/backward by one month.} |
3907 @end table | 4104 mouse-1 @r{Select date by clicking on it.} |
4105 S-@key{right}/@key{left} @r{One day forward/backward.} | |
4106 S-@key{down}/@key{up} @r{One week forward/backward.} | |
4107 M-S-@key{right}/@key{left} @r{One month forward/backward.} | |
4108 @key{RET} @r{Choose date in calendar.} | |
4109 @end example | |
4110 | |
4111 The actions of the date/time prompt may seem complex, but I asure you | |
4112 they will grow on you. To help you understand what is going on, the | |
4113 current interpretation of your input will be displayed live in the | |
4114 minibuffer@footnote{If you find this distracting, turn the display of | |
4115 with @code{org-read-date-display-live}.}. | |
3908 | 4116 |
3909 @node Custom time format, , The date/time prompt, Creating timestamps | 4117 @node Custom time format, , The date/time prompt, Creating timestamps |
3910 @subsection Custom time format | 4118 @subsection Custom time format |
3911 @cindex custom date/time format | 4119 @cindex custom date/time format |
3912 @cindex time format, custom | 4120 @cindex time format, custom |
3951 using dates in tables, table alignment will be messed up. If the custom | 4159 using dates in tables, table alignment will be messed up. If the custom |
3952 format is shorter, things do work as expected. | 4160 format is shorter, things do work as expected. |
3953 @end itemize | 4161 @end itemize |
3954 | 4162 |
3955 | 4163 |
3956 @node Deadlines and scheduling, Progress logging, Creating timestamps, Timestamps | 4164 @node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and times |
3957 @section Deadlines and Scheduling | 4165 @section Deadlines and Scheduling |
3958 | 4166 |
3959 A time stamp may be preceded by special keywords to facilitate planning | 4167 A time stamp may be preceded by special keywords to facilitate planning: |
3960 of work: | |
3961 | 4168 |
3962 @table @var | 4169 @table @var |
3963 @item DEADLINE | 4170 @item DEADLINE |
3964 @cindex DEADLINE keyword | 4171 @cindex DEADLINE keyword |
3965 The task (most likely a TODO item) is supposed to be finished on that | 4172 |
3966 date, and it will be listed then. In addition, the compilation for | 4173 Meaning: the task (most likely a TODO item, though not necessarily) is supposed |
3967 @emph{today} will carry a warning about the approaching or missed | 4174 to be finished on that date. |
3968 deadline, starting @code{org-deadline-warning-days} before the due date, | 4175 |
3969 and continuing until the entry is marked DONE. An example: | 4176 On the deadline date, the task will be listed in the agenda. In |
4177 addition, the agenda for @emph{today} will carry a warning about the | |
4178 approaching or missed deadline, starting | |
4179 @code{org-deadline-warning-days} before the due date, and continuing | |
4180 until the entry is marked DONE. An example: | |
3970 | 4181 |
3971 @example | 4182 @example |
3972 *** TODO write article about the Earth for the Guide | 4183 *** TODO write article about the Earth for the Guide |
3973 The editor in charge is [[bbdb:Ford Prefect]] | 4184 The editor in charge is [[bbdb:Ford Prefect]] |
3974 DEADLINE: <2004-02-29 Sun> | 4185 DEADLINE: <2004-02-29 Sun> |
3978 deadlines using the following syntax. Here is an example with a warning | 4189 deadlines using the following syntax. Here is an example with a warning |
3979 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. | 4190 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. |
3980 | 4191 |
3981 @item SCHEDULED | 4192 @item SCHEDULED |
3982 @cindex SCHEDULED keyword | 4193 @cindex SCHEDULED keyword |
3983 You are planning to start working on that task on the given date. The | 4194 |
3984 headline will be listed under the given date@footnote{It will still be | 4195 Meaning: you are planning to start working on that task on the given |
3985 listed on that date after it has been marked DONE. If you don't like | 4196 date. |
4197 | |
4198 The headline will be listed under the given date@footnote{It will still | |
4199 be listed on that date after it has been marked DONE. If you don't like | |
3986 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In | 4200 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In |
3987 addition, a reminder that the scheduled date has passed will be present | 4201 addition, a reminder that the scheduled date has passed will be present |
3988 in the compilation for @emph{today}, until the entry is marked DONE. | 4202 in the compilation for @emph{today}, until the entry is marked DONE. |
3989 I.e., the task will automatically be forwarded until completed. | 4203 I.e., the task will automatically be forwarded until completed. |
3990 | 4204 |
3991 @example | 4205 @example |
3992 *** TODO Call Trillian for a date on New Years Eve. | 4206 *** TODO Call Trillian for a date on New Years Eve. |
3993 SCHEDULED: <2004-12-25 Sat> | 4207 SCHEDULED: <2004-12-25 Sat> |
3994 @end example | 4208 @end example |
4209 | |
4210 @noindent | |
4211 @b{Important:} Scheduling an item in Org-mode should @i{not} be | |
4212 understood in the same way that we understand @i{scheduling a meeting}. | |
4213 Setting a date for a meeting is just a simple appointment, you should | |
4214 mark this entry with a simple plain time stamp, to get this item shown | |
4215 on the date where it applies. This is a frequent mis-understanding from | |
4216 Org-users. In Org-mode, @i{scheduling} means setting a date when you | |
4217 want to start working on an action item. | |
3995 @end table | 4218 @end table |
4219 | |
4220 You may use time stamps with repeaters in scheduling and deadline | |
4221 entries. Org-mode will issue early and late warnings based on the | |
4222 assumption that the time stamp represents the @i{nearest instance} of | |
4223 the repeater. However, the use of diary sexp entries like | |
4224 @c | |
4225 @code{<%%(diary-float t 42)>} | |
4226 @c | |
4227 in scheduling and deadline timestamps is limited. Org-mode does not | |
4228 know enough about the internals of each sexp function to issue early and | |
4229 late warnings. However, it will show the item on each day where the | |
4230 sexp entry matches. | |
3996 | 4231 |
3997 @menu | 4232 @menu |
3998 * Inserting deadline/schedule:: Planning items | 4233 * Inserting deadline/schedule:: Planning items |
3999 * Repeated tasks:: Items that show up again and again | 4234 * Repeated tasks:: Items that show up again and again |
4000 @end menu | 4235 @end menu |
4008 @table @kbd | 4243 @table @kbd |
4009 @c | 4244 @c |
4010 @kindex C-c C-d | 4245 @kindex C-c C-d |
4011 @item C-c C-d | 4246 @item C-c C-d |
4012 Insert @samp{DEADLINE} keyword along with a stamp. The insertion will | 4247 Insert @samp{DEADLINE} keyword along with a stamp. The insertion will |
4013 happen in the line directly following the headline. | 4248 happen in the line directly following the headline. When called with a |
4249 prefix arg, an existing deadline will be removed from the entry. | |
4014 @c FIXME Any CLOSED timestamp will be removed.???????? | 4250 @c FIXME Any CLOSED timestamp will be removed.???????? |
4015 @c | 4251 @c |
4016 @kindex C-c C-w | 4252 @kindex C-c / d |
4017 @cindex sparse tree, for deadlines | 4253 @cindex sparse tree, for deadlines |
4018 @item C-c C-w | 4254 @item C-c / d |
4019 Create a sparse tree with all deadlines that are either past-due, or | 4255 Create a sparse tree with all deadlines that are either past-due, or |
4020 which will become due within @code{org-deadline-warning-days}. | 4256 which will become due within @code{org-deadline-warning-days}. |
4021 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric | 4257 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric |
4022 prefix, check that many days. For example, @kbd{C-1 C-c C-w} shows | 4258 prefix, check that many days. For example, @kbd{C-1 C-c / d} shows |
4023 all deadlines due tomorrow. | 4259 all deadlines due tomorrow. |
4024 @c | 4260 @c |
4025 @kindex C-c C-s | 4261 @kindex C-c C-s |
4026 @item C-c C-s | 4262 @item C-c C-s |
4027 Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will | 4263 Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will |
4028 happen in the line directly following the headline. Any CLOSED | 4264 happen in the line directly following the headline. Any CLOSED |
4029 timestamp will be removed. | 4265 timestamp will be removed. When called with a prefix argument, remove |
4266 the scheduling date from the entry. | |
4030 @end table | 4267 @end table |
4031 | 4268 |
4032 @node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling | 4269 @node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling |
4033 @subsection Repeated Tasks | 4270 @subsection Repeated Tasks |
4034 | 4271 |
4035 Some tasks need to be repeated again and again, and Org-mode therefore | 4272 Some tasks need to be repeated again and again. Org-mode helps to |
4036 allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for | 4273 organize such tasks using a so-called repeater in a DEADLINE or |
4037 example: | 4274 SCHEDULED time stamp. In the following example |
4038 @example | 4275 @example |
4039 ** TODO Pay the rent | 4276 ** TODO Pay the rent |
4040 DEADLINE: <2005-10-01 Sat +1m> | 4277 DEADLINE: <2005-10-01 Sat +1m> |
4041 @end example | 4278 @end example |
4279 the @code{+1m} is a repeater; the intended interpretation is that the | |
4280 task has a deadline on <2005-10-01> and repeats itself every (one) month | |
4281 starting from that time. | |
4042 | 4282 |
4043 Deadlines and scheduled items produce entries in the agenda when they | 4283 Deadlines and scheduled items produce entries in the agenda when they |
4044 are over-due, so it is important to be able to mark such an entry as | 4284 are over-due, so it is important to be able to mark such an entry as |
4045 completed once you have done so. When you mark a DEADLINE or a SCHEDULE | 4285 completed once you have done so. When you mark a DEADLINE or a SCHEDULE |
4046 with the todo keyword DONE, it will no longer produce entries in the | 4286 with the todo keyword DONE, it will no longer produce entries in the |
4055 @example | 4295 @example |
4056 ** TODO Pay the rent | 4296 ** TODO Pay the rent |
4057 DEADLINE: <2005-11-01 Tue +1m> | 4297 DEADLINE: <2005-11-01 Tue +1m> |
4058 @end example | 4298 @end example |
4059 | 4299 |
4060 You will also be prompted for a note that will be put under the DEADLINE | 4300 You will also be prompted for a note@footnote{You can change this using |
4061 line to keep a record that you actually acted on the previous instance | 4301 the option @code{org-log-repeat}, or the @code{#+STARTUP} options |
4062 of this deadline. | 4302 @code{logrepeat} and @code{nologrepeat}.} that will be put under the |
4303 DEADLINE line to keep a record that you actually acted on the previous | |
4304 instance of this deadline. | |
4063 | 4305 |
4064 As a consequence of shifting the base date, this entry will no longer be | 4306 As a consequence of shifting the base date, this entry will no longer be |
4065 visible in the agenda when checking past dates, but all future instances | 4307 visible in the agenda when checking past dates, but all future instances |
4066 will be visible. | 4308 will be visible. |
4067 | 4309 |
4068 You may have both scheduling and deadline information for a specific | 4310 You may have both scheduling and deadline information for a specific |
4069 task - just make sure that the repeater intervals on both are the same. | 4311 task - just make sure that the repeater intervals on both are the same. |
4070 | 4312 |
4071 @node Progress logging, , Deadlines and scheduling, Timestamps | 4313 @node Clocking work time, , Deadlines and scheduling, Dates and times |
4072 @section Progress Logging | 4314 @section Clocking work time |
4073 @cindex progress logging | |
4074 @cindex logging, of progress | |
4075 | |
4076 Org-mode can automatically record a time stamp when you mark a TODO item | |
4077 as DONE, or even each time when you change the state of a TODO item. | |
4078 You can also measure precisely the time you spent on specific items in a | |
4079 project by starting and stopping a clock when you start and stop working | |
4080 on an aspect of a project. | |
4081 | |
4082 @menu | |
4083 * Closing items:: When was this entry marked DONE? | |
4084 * Tracking TODO state changes:: When did the status change? | |
4085 * Clocking work time:: When exactly did you work on this item? | |
4086 @end menu | |
4087 | |
4088 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging | |
4089 @subsection Closing items | |
4090 | |
4091 If you want to keep track of @emph{when} a certain TODO item was | |
4092 finished, turn on logging with@footnote{The corresponding in-buffer | |
4093 setting is: @code{#+STARTUP: logdone}} | |
4094 | |
4095 @lisp | |
4096 (setq org-log-done t) | |
4097 @end lisp | |
4098 | |
4099 @noindent | |
4100 Then each time you turn a TODO entry into DONE using either @kbd{C-c | |
4101 C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line | |
4102 @samp{CLOSED: [timestamp]} will be inserted just after the headline. If | |
4103 you turn the entry back into a TODO item through further state cycling, | |
4104 that line will be removed again. In the timeline (@pxref{Timeline}) and | |
4105 in the agenda (@pxref{Weekly/Daily agenda}), you can then use the | |
4106 @kbd{l} key to display the TODO items closed on each day, giving you an | |
4107 overview of what has been done on a day. If you want to record a note | |
4108 along with the timestamp, use@footnote{The corresponding in-buffer | |
4109 setting is: @code{#+STARTUP: lognotedone}} | |
4110 | |
4111 @lisp | |
4112 (setq org-log-done '(done)) | |
4113 @end lisp | |
4114 | |
4115 @node Tracking TODO state changes, Clocking work time, Closing items, Progress logging | |
4116 @subsection Tracking TODO state changes | |
4117 | |
4118 When TODO keywords are used as workflow states (@pxref{Workflow | |
4119 states}), you might want to keep track of when a state change occurred, | |
4120 and you may even want to attach notes to that state change. With the | |
4121 setting | |
4122 | |
4123 @lisp | |
4124 (setq org-log-done '(state)) | |
4125 @end lisp | |
4126 | |
4127 @noindent | |
4128 each state change will prompt you for a note that will be attached to | |
4129 the current headline. Very likely you do not want this verbose tracking | |
4130 all the time, so it is probably better to configure this behavior with | |
4131 in-buffer options. For example, if you are tracking purchases, put | |
4132 these into a separate file that starts with: | |
4133 | |
4134 @example | |
4135 #+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT | |
4136 #+STARTUP: lognotestate | |
4137 @end example | |
4138 | |
4139 | |
4140 @node Clocking work time, , Tracking TODO state changes, Progress logging | |
4141 @subsection Clocking work time | |
4142 | 4315 |
4143 Org-mode allows you to clock the time you spent on specific tasks in a | 4316 Org-mode allows you to clock the time you spent on specific tasks in a |
4144 project. When you start working on an item, you can start the clock. | 4317 project. When you start working on an item, you can start the clock. |
4145 When you stop working on that task, or when you mark the task done, the | 4318 When you stop working on that task, or when you mark the task done, the |
4146 clock is stopped and the corresponding time interval is recorded. It | 4319 clock is stopped and the corresponding time interval is recorded. It |
4148 | 4321 |
4149 @table @kbd | 4322 @table @kbd |
4150 @kindex C-c C-x C-i | 4323 @kindex C-c C-x C-i |
4151 @item C-c C-x C-i | 4324 @item C-c C-x C-i |
4152 Start the clock on the current item (clock-in). This inserts the CLOCK | 4325 Start the clock on the current item (clock-in). This inserts the CLOCK |
4153 keyword together with a timestamp. | 4326 keyword together with a timestamp. If this is not the first clocking of |
4327 this item, the multiple CLOCK lines will be wrapped into a | |
4328 @code{:CLOCK:} drawer (see also the variable | |
4329 @code{org-clock-into-drawer}. | |
4154 @kindex C-c C-x C-o | 4330 @kindex C-c C-x C-o |
4155 @item C-c C-x C-o | 4331 @item C-c C-x C-o |
4156 Stop the clock (clock-out). The inserts another timestamp at the same | 4332 Stop the clock (clock-out). The inserts another timestamp at the same |
4157 location where the clock was last started. It also directly computes | 4333 location where the clock was last started. It also directly computes |
4158 the resulting time in inserts it after the time range as @samp{=> | 4334 the resulting time in inserts it after the time range as @samp{=> |
4171 if it is running in this same item. | 4347 if it is running in this same item. |
4172 @kindex C-c C-x C-x | 4348 @kindex C-c C-x C-x |
4173 @item C-c C-x C-x | 4349 @item C-c C-x C-x |
4174 Cancel the current clock. This is useful if a clock was started by | 4350 Cancel the current clock. This is useful if a clock was started by |
4175 mistake, or if you ended up working on something else. | 4351 mistake, or if you ended up working on something else. |
4352 @kindex C-c C-x C-j | |
4353 @item C-c C-x C-j | |
4354 Jump to the entry that contains the currently running clock, an another | |
4355 window. | |
4176 @kindex C-c C-x C-d | 4356 @kindex C-c C-x C-d |
4177 @item C-c C-x C-d | 4357 @item C-c C-x C-d |
4178 Display time summaries for each subtree in the current buffer. This | 4358 Display time summaries for each subtree in the current buffer. This |
4179 puts overlays at the end of each headline, showing the total time | 4359 puts overlays at the end of each headline, showing the total time |
4180 recorded under that heading, including the time of any subheadings. You | 4360 recorded under that heading, including the time of any subheadings. You |
4182 when you change the buffer (see variable | 4362 when you change the buffer (see variable |
4183 @code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}. | 4363 @code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}. |
4184 @kindex C-c C-x C-r | 4364 @kindex C-c C-x C-r |
4185 @item C-c C-x C-r | 4365 @item C-c C-x C-r |
4186 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock | 4366 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock |
4187 report as an org-mode table into the current file. | 4367 report as an org-mode table into the current file. When the cursor is |
4188 @example | 4368 at an existing clock table, just update it. When called with a prefix |
4189 #+BEGIN: clocktable :maxlevel 2 :emphasize nil | 4369 argument, jump to the first clock report in the current document and |
4370 update it. | |
4371 @example | |
4372 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file | |
4190 | 4373 |
4191 #+END: clocktable | 4374 #+END: clocktable |
4192 @end example | 4375 @end example |
4193 @noindent | 4376 @noindent |
4194 If such a block already exists, its content is replaced by the new | 4377 If such a block already exists at point, its content is replaced by the |
4195 table. The @samp{BEGIN} line can specify options: | 4378 new table. The @samp{BEGIN} line can specify options: |
4196 @example | 4379 @example |
4197 :maxlevels @r{Maximum level depth to which times are listed in the table.} | 4380 :maxlevel @r{Maximum level depth to which times are listed in the table.} |
4198 :emphasize @r{When @code{t}, emphasize level one and level two items} | 4381 :emphasize @r{When @code{t}, emphasize level one and level two items} |
4382 :scope @r{The scope to consider. This can be any of the following:} | |
4383 nil @r{the current buffer or narrowed region} | |
4384 file @r{the full current buffer} | |
4385 subtree @r{the subtree where the clocktable is located} | |
4386 treeN @r{the surrounding level N tree, for example @code{tree3}} | |
4387 tree @r{the surrounding level 1 tree} | |
4388 agenda @r{all agenda files} | |
4389 ("file"..) @r{scan these files} | |
4199 :block @r{The time block to consider. This block is specified relative} | 4390 :block @r{The time block to consider. This block is specified relative} |
4200 @r{to the current time and may be any of these keywords:} | 4391 @r{to the current time and may be any of these keywords:} |
4201 @r{@code{today}, @code{yesterday}, @code{thisweek}, @code{lastweek},} | 4392 @r{@code{today}, @code{yesterday}, @code{thisweek}, @code{lastweek},} |
4202 @r{@code{thismonth}, @code{lastmonth}, @code{thisyear}, or @code{lastyear}}. | 4393 @r{@code{thismonth}, @code{lastmonth}, @code{thisyear}, or @code{lastyear}}. |
4203 :tstart @r{A time string specifying when to start considering times} | 4394 :tstart @r{A time string specifying when to start considering times} |
4204 :tend @r{A time string specifying when to stop considering times} | 4395 :tend @r{A time string specifying when to stop considering times} |
4205 @end example | 4396 @end example |
4206 So to get a clock summary for the current day, you could write | 4397 So to get a clock summary of the current level 1 tree, for the current |
4207 @example | 4398 day, you could write |
4208 #+BEGIN: clocktable :maxlevel 2 :block today | 4399 @example |
4400 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 | |
4209 | 4401 |
4210 #+END: clocktable | 4402 #+END: clocktable |
4211 @end example | 4403 @end example |
4212 and to use a specific time range you could write@footnote{Note that all | 4404 and to use a specific time range you could write@footnote{Note that all |
4213 parameters must be specified in a single line - the line is broken here | 4405 parameters must be specified in a single line - the line is broken here |
4216 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" | 4408 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" |
4217 :tend "<2006-08-10 Thu 12:00>" | 4409 :tend "<2006-08-10 Thu 12:00>" |
4218 | 4410 |
4219 #+END: clocktable | 4411 #+END: clocktable |
4220 @end example | 4412 @end example |
4413 @kindex C-c C-c | |
4414 @item C-c C-c | |
4415 @kindex C-c C-x C-u | |
4416 @itemx C-c C-x C-u | |
4417 Update dynamical block at point. The cursor needs to be in the | |
4418 @code{#+BEGIN} line of the dynamic block. | |
4221 @kindex C-u C-c C-x C-u | 4419 @kindex C-u C-c C-x C-u |
4222 @item C-u C-c C-x C-u | 4420 @item C-u C-c C-x C-u |
4223 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if | 4421 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if |
4224 you have several clocktable blocks in a buffer. | 4422 you have several clocktable blocks in a buffer. |
4225 @end table | 4423 @end table |
4226 | 4424 |
4227 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in | 4425 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in |
4228 the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been | 4426 the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been |
4229 worked on or closed during a day. | 4427 worked on or closed during a day. |
4230 | 4428 |
4231 @node Agenda views, Embedded LaTeX, Timestamps, Top | 4429 @node Remember, Agenda views, Dates and times, Top |
4430 @chapter Remember | |
4431 @cindex @file{remember.el} | |
4432 | |
4433 The @i{Remember} package by John Wiegley lets you store quick notes with | |
4434 little interruption of your work flow. See | |
4435 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more | |
4436 information. It is an excellent way to add new notes and tasks to | |
4437 Org-mode files. Org-mode significantly expands the possibilities of | |
4438 @i{remember}: You may define templates for different note types, and | |
4439 associate target files and headlines with specific templates. It also | |
4440 allows you to select the location where a note should be stored | |
4441 interactively, on the fly. | |
4442 | |
4443 @menu | |
4444 * Setting up remember:: Some code for .emacs to get things going | |
4445 * Remember templates:: Define the outline of different note types | |
4446 * Storing notes:: Directly get the note to where it belongs | |
4447 * Refiling notes:: Moving a note or task to a project | |
4448 @end menu | |
4449 | |
4450 @node Setting up remember, Remember templates, Remember, Remember | |
4451 @section Setting up remember | |
4452 | |
4453 The following customization will tell @i{remember} to use org files as | |
4454 target, and to create annotations compatible with Org-mode links. | |
4455 | |
4456 @example | |
4457 (org-remember-insinuate) | |
4458 (setq org-directory "~/path/to/my/orgfiles/") | |
4459 (setq org-default-notes-file (concat org-directory "/notes.org")) | |
4460 (define-key global-map "\C-cr" 'org-remember) | |
4461 @end example | |
4462 | |
4463 The last line binds the command @code{org-remember} to a global | |
4464 key@footnote{Please select your own key, @kbd{C-c r} is only a | |
4465 suggestion.}. @code{org-remember} basically just calls @code{remember}, | |
4466 but it makes a few things easier: If there is an active region, it will | |
4467 automatically copy the region into the remember buffer. It also allows | |
4468 to jump to the buffer and location where remember notes are being | |
4469 stored: Just call @code{org-remember} with a prefix argument. | |
4470 | |
4471 @node Remember templates, Storing notes, Setting up remember, Remember | |
4472 @section Remember templates | |
4473 @cindex templates, for remember | |
4474 | |
4475 In combination with Org-mode, you can use templates to generate | |
4476 different types of @i{remember} notes. For example, if you would like | |
4477 to use one template to create general TODO entries, another one for | |
4478 journal entries, and a third one for collecting random ideas, you could | |
4479 use: | |
4480 | |
4481 @example | |
4482 (setq org-remember-templates | |
4483 '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks") | |
4484 ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") | |
4485 ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) | |
4486 @end example | |
4487 | |
4488 @noindent In these entries, the first string is just a name, and the | |
4489 character specifies how to select the template. It is useful if the | |
4490 character is also the first letter of the name. The next string | |
4491 specifies the template. Two more (optional) strings give the file in | |
4492 which, and the headline under which the new note should be stored. The | |
4493 file (if not present or @code{nil}) defaults to | |
4494 @code{org-default-notes-file}, the heading to | |
4495 @code{org-remember-default-headline}. | |
4496 | |
4497 When you call @kbd{M-x remember} (or @kbd{M-x org-remember}) to remember | |
4498 something, org will prompt for a key to select the template (if you have | |
4499 more than one template) and then prepare the buffer like | |
4500 @example | |
4501 * TODO | |
4502 [[file:link to where you called remember]] | |
4503 @end example | |
4504 | |
4505 @noindent | |
4506 During expansion of the template, special @kbd{%}-escapes allow dynamic | |
4507 insertion of content: | |
4508 @example | |
4509 %^@{prompt@} @r{prompt the user for a string and replace this sequence with it.} | |
4510 @r{You may specify a default value and a completion table with} | |
4511 @r{%^@{prompt|default|completion2|completion3...@}} | |
4512 @r{The arrow keys access a prompt-specific history.} | |
4513 %t @r{time stamp, date only} | |
4514 %T @r{time stamp with date and time} | |
4515 %u, %U @r{like the above, but inactive time stamps} | |
4516 %^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}} | |
4517 @r{You may define a prompt like @code{%^@{Birthday@}t}} | |
4518 %n @r{user name (taken from @code{user-full-name})} | |
4519 %a @r{annotation, normally the link created with @code{org-store-link}} | |
4520 %A @r{like @code{%a}, but prompt for the description part} | |
4521 %i @r{initial content, the region when remember is called with C-u.} | |
4522 @r{The entire text will be indented like @code{%i} itself.} | |
4523 %c @r{Content of the clipboard, or current kill ring head.} | |
4524 %^g @r{prompt for tags, with completion on tags in target file.} | |
4525 %^G @r{prompt for tags, with completion all tags in all agenda files.} | |
4526 %:keyword @r{specific information for certain link types, see below} | |
4527 %[pathname] @r{insert the contents of the file given by @code{pathname}} | |
4528 %(sexp) @r{evaluate elisp @code{(sexp)} and replace with the result} | |
4529 %! @r{immediately store note after completing the template} | |
4530 @r{(skipping the @kbd{C-c C-c} that normally triggers storing)} | |
4531 @end example | |
4532 | |
4533 @noindent | |
4534 For specific link types, the following keywords will be | |
4535 defined@footnote{If you define your own link types (@pxref{Adding | |
4536 hyperlink types}), any property you store with | |
4537 @code{org-store-link-props} can be accessed in remember templates in a | |
4538 similar way.}: | |
4539 | |
4540 @example | |
4541 Link type | Available keywords | |
4542 -------------------+---------------------------------------------- | |
4543 bbdb | %:name %:company | |
4544 vm, wl, mh, rmail | %:type %:subject %:message-id | |
4545 | %:from %:fromname %:fromaddress | |
4546 | %:to %:toname %:toaddress | |
4547 | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}} | |
4548 gnus | %:group, @r{for messages also all email fields} | |
4549 w3, w3m | %:url | |
4550 info | %:file %:node | |
4551 calendar | %:date" | |
4552 @end example | |
4553 | |
4554 @noindent | |
4555 To place the cursor after template expansion use: | |
4556 | |
4557 @example | |
4558 %? @r{After completing the template, position cursor here.} | |
4559 @end example | |
4560 | |
4561 @noindent | |
4562 If you change you mind about which template to use, call | |
4563 @code{org-remember} in the remember buffer. You may then select a new | |
4564 template that will be filled with the previous context information. | |
4565 | |
4566 @node Storing notes, Refiling notes, Remember templates, Remember | |
4567 @section Storing notes | |
4568 | |
4569 When you are finished preparing a note with @i{remember}, you have to | |
4570 press @kbd{C-c C-c} to file the note away. The handler will store the | |
4571 note in the file and under the headline specified in the template, or it | |
4572 will use the default file and headlines. The window configuration will | |
4573 be restored, sending you back to the working context before the call to | |
4574 @code{remember}. To re-use the location found during the last call to | |
4575 @code{remember}, exit the remember buffer with @kbd{C-u C-u C-c C-c}, | |
4576 i.e. specify a double prefix argument to @kbd{C-c C-c}. | |
4577 | |
4578 If you want to store the note directly to a different place, use | |
4579 @kbd{C-u C-c C-c} instead to exit remember@footnote{Configure the | |
4580 variable @code{org-remember-store-without-prompt} to make this behavior | |
4581 the default.}. The handler will then first prompt for a target file - | |
4582 if you press @key{RET}, the value specified for the template is used. | |
4583 Then the command offers the headings tree of the selected file, with the | |
4584 cursor position at the default headline (if you had specified one in the | |
4585 template). You can either immediately press @key{RET} to get the note | |
4586 placed there. Or you can use the following keys to find a different | |
4587 location: | |
4588 @example | |
4589 @key{TAB} @r{Cycle visibility.} | |
4590 @key{down} / @key{up} @r{Next/previous visible headline.} | |
4591 n / p @r{Next/previous visible headline.} | |
4592 f / b @r{Next/previous headline same level.} | |
4593 u @r{One level up.} | |
4594 @c 0-9 @r{Digit argument.} | |
4595 @end example | |
4596 @noindent | |
4597 Pressing @key{RET} or @key{left} or @key{right} | |
4598 then leads to the following result. | |
4599 | |
4600 @multitable @columnfractions 0.2 0.15 0.65 | |
4601 @item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted} | |
4602 @item on headline @tab @key{RET} @tab as sublevel of the heading at cursor, first or last | |
4603 @item @tab @tab depending on @code{org-reverse-note-order}. | |
4604 @item @tab @key{left}/@key{right} @tab as same level, before/after current heading | |
4605 @item buffer-start @tab @key{RET} @tab as level 2 heading at end of file or level 1 at beginning | |
4606 @item @tab @tab depending on @code{org-reverse-note-order}. | |
4607 @item not on headline @tab @key{RET} | |
4608 @tab at cursor position, level taken from context. | |
4609 @end multitable | |
4610 | |
4611 Before inserting the text into a tree, the function ensures that the | |
4612 text has a headline, i.e. a first line that starts with a @samp{*}. If | |
4613 not, a headline is constructed from the current date and some additional | |
4614 data. If you have indented the text of the note below the headline, the | |
4615 indentation will be adapted if inserting the note into the tree requires | |
4616 demotion from level 1. | |
4617 | |
4618 @node Refiling notes, , Storing notes, Remember | |
4619 @section Refiling notes | |
4620 @cindex refiling notes | |
4621 | |
4622 Remember is usually used to quickly capture notes and tasks into one or | |
4623 a few capture lists. When reviewing the captured data, you may want to | |
4624 refile some of the entries into a different list, for example into a | |
4625 project. Cutting, finding the right location and then pasting the note | |
4626 is cumbersome. To simplify this process, you can use the following | |
4627 special command: | |
4628 | |
4629 @table @kbd | |
4630 @kindex C-c C-w | |
4631 @item C-c C-w | |
4632 Refile the entry at point. This command offers possible locations for | |
4633 refiling the entry and lets you select one with completion. The item is | |
4634 filed below the target heading as a subitem. Depending on | |
4635 @code{org-reverse-note-order}, it will be either the first of last | |
4636 subitem, and you can toggle the value of this variable for the duration | |
4637 of the command by using a @kbd{C-u} prefix.@* By default, all level 1 | |
4638 headlines in the current buffer are considered to be targets, but you | |
4639 can have more complex definitions across a number of files. See the | |
4640 variable @code{org-refile-targets} for details. The list of targets is | |
4641 compiled upon first use, you can update it by using a double prefix | |
4642 argument (@kbd{C-u C-u}) to this command. | |
4643 @end table | |
4644 | |
4645 @node Agenda views, Embedded LaTeX, Remember, Top | |
4232 @chapter Agenda Views | 4646 @chapter Agenda Views |
4233 @cindex agenda views | 4647 @cindex agenda views |
4234 | 4648 |
4235 Due to the way Org-mode works, TODO items, time-stamped items, and | 4649 Due to the way Org-mode works, TODO items, time-stamped items, and |
4236 tagged headlines can be scattered throughout a file or even a number of | 4650 tagged headlines can be scattered throughout a file or even a number of |
4237 files. To get an overview over open action items, or over events that | 4651 files. To get an overview of open action items, or of events that are |
4238 are important for a particular date, this information must be collected, | 4652 important for a particular date, this information must be collected, |
4239 sorted and displayed in an organized way. | 4653 sorted and displayed in an organized way. |
4240 | 4654 |
4241 Org-mode can select items based on various criteria, and display them | 4655 Org-mode can select items based on various criteria, and display them |
4242 in a separate buffer. Six different view types are provided: | 4656 in a separate buffer. Six different view types are provided: |
4243 | 4657 |
4285 @node Agenda files, Agenda dispatcher, Agenda views, Agenda views | 4699 @node Agenda files, Agenda dispatcher, Agenda views, Agenda views |
4286 @section Agenda files | 4700 @section Agenda files |
4287 @cindex agenda files | 4701 @cindex agenda files |
4288 @cindex files for agenda | 4702 @cindex files for agenda |
4289 | 4703 |
4290 The information to be shown is collected from all @emph{agenda files}, | 4704 The information to be shown is normally collected from all @emph{agenda |
4291 the files listed in the variable @code{org-agenda-files}@footnote{If the | 4705 files}, the files listed in the variable |
4292 value of that variable is not a list, but a single file name, then the | 4706 @code{org-agenda-files}@footnote{If the value of that variable is not a |
4293 list of agenda files will be maintained in that external file.}. Thus even | 4707 list, but a single file name, then the list of agenda files will be |
4294 if you only work with a single Org-mode file, this file should be put | 4708 maintained in that external file.}. If a directory is part of this list, |
4295 into that list@footnote{When using the dispatcher, pressing @kbd{1} | 4709 all files with the extension @file{.org} in this directory will be part |
4296 before selecting a command will actually limit the command to the | 4710 of the list. |
4297 current file, and ignore @code{org-agenda-files} until the next | 4711 |
4712 Thus even if you only work with a single Org-mode file, this file should | |
4713 be put into that list@footnote{When using the dispatcher, pressing | |
4714 @kbd{<} before selecting a command will actually limit the command to | |
4715 the current file, and ignore @code{org-agenda-files} until the next | |
4298 dispatcher command.}. You can customize @code{org-agenda-files}, but | 4716 dispatcher command.}. You can customize @code{org-agenda-files}, but |
4299 the easiest way to maintain it is through the following commands | 4717 the easiest way to maintain it is through the following commands |
4300 | 4718 |
4301 @cindex files, adding to agenda list | 4719 @cindex files, adding to agenda list |
4302 @table @kbd | 4720 @table @kbd |
4316 @end table | 4734 @end table |
4317 | 4735 |
4318 @noindent | 4736 @noindent |
4319 The Org menu contains the current list of files and can be used | 4737 The Org menu contains the current list of files and can be used |
4320 to visit any of them. | 4738 to visit any of them. |
4739 | |
4740 If you would like to focus the agenda temporarily onto a file not in | |
4741 this list, or onto just one file in the list or even only a subtree in a | |
4742 file, this can be done in different ways. For a single agenda command, | |
4743 you may press @kbd{<} once or several times in the dispatcher | |
4744 (@pxref{Agenda dispatcher}). To restrict the agenda scope for an | |
4745 extended period, use the following commands: | |
4746 | |
4747 @table @kbd | |
4748 @kindex C-c C-x < | |
4749 @item C-c C-x < | |
4750 Permanently restrict the agenda to the current subtree. When with a | |
4751 prefix argument, or with the cursor before the first headline in a file, | |
4752 the agenda scope is set to the entire file. This restriction remains in | |
4753 effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<} | |
4754 or @kbd{>} in the agenda dispatcher. If there is a window displaying an | |
4755 agenda view, the new restriction takes effect immediately. | |
4756 @kindex C-c C-x < | |
4757 @item C-c C-x < | |
4758 Remove the permanent restriction created by @kbd{C-c C-x <}. | |
4759 @end table | |
4760 | |
4761 @noindent | |
4762 When working with @file{Speedbar}, you can use the following commands in | |
4763 the speedbar frame: | |
4764 @table @kbd | |
4765 @kindex < | |
4766 @item < @r{in the speedbar frame} | |
4767 Permanently restrict the agenda to the item at the cursor in the | |
4768 speedbar frame, either an Org-mode file or a subtree in such a file. | |
4769 If there is a window displaying an agenda view, the new restriction takes | |
4770 effect immediately. | |
4771 @kindex < | |
4772 @item > @r{in the speedbar frame} | |
4773 Lift the restriction again. | |
4774 @end table | |
4321 | 4775 |
4322 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views | 4776 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views |
4323 @section The agenda dispatcher | 4777 @section The agenda dispatcher |
4324 @cindex agenda dispatcher | 4778 @cindex agenda dispatcher |
4325 @cindex dispatching agenda commands | 4779 @cindex dispatching agenda commands |
4339 tags and properties}). | 4793 tags and properties}). |
4340 @item L | 4794 @item L |
4341 Create the timeline view for the current buffer (@pxref{Timeline}). | 4795 Create the timeline view for the current buffer (@pxref{Timeline}). |
4342 @item # @r{/} ! | 4796 @item # @r{/} ! |
4343 Create a list of stuck projects (@pxref{Stuck projects}). | 4797 Create a list of stuck projects (@pxref{Stuck projects}). |
4344 @item 1 | 4798 @item / |
4345 Restrict an agenda command to the current buffer. After pressing | 4799 Search for a regular expression in all agenda files and additionally in |
4346 @kbd{1}, you still need to press the character selecting the command. | 4800 the files listed in @code{org-agenda-multi-occur-extra-files}. This |
4347 @item 0 | 4801 uses the Emacs command @code{multi-occur}. A prefix argument can be |
4802 used to specify the number of context lines for each match, default is | |
4803 1. | |
4804 @item < | |
4805 Restrict an agenda command to the current buffer@footnote{For backward | |
4806 compatibility, you can also press @kbd{1} to restrict to the current | |
4807 buffer.}. After pressing @kbd{<}, you still need to press the character | |
4808 selecting the command. | |
4809 @item < < | |
4348 If there is an active region, restrict the following agenda command to | 4810 If there is an active region, restrict the following agenda command to |
4349 the region. Otherwise, restrict it to the current subtree. After | 4811 the region. Otherwise, restrict it to the current subtree@footnote{For |
4350 pressing @kbd{0}, you still need to press the character selecting the | 4812 backward compatibility, you can also press @kbd{0} to restrict to the |
4351 command. | 4813 current buffer.}. After pressing @kbd{< <}, you still need to press the |
4814 character selecting the command. | |
4352 @end table | 4815 @end table |
4353 | 4816 |
4354 You can also define custom commands that will be accessible through the | 4817 You can also define custom commands that will be accessible through the |
4355 dispatcher, just like the default commands. This includes the | 4818 dispatcher, just like the default commands. This includes the |
4356 possibility to create extended agenda buffers that contain several | 4819 possibility to create extended agenda buffers that contain several |
4382 @table @kbd | 4845 @table @kbd |
4383 @cindex org-agenda, command | 4846 @cindex org-agenda, command |
4384 @kindex C-c a a | 4847 @kindex C-c a a |
4385 @item C-c a a | 4848 @item C-c a a |
4386 Compile an agenda for the current week from a list of org files. The | 4849 Compile an agenda for the current week from a list of org files. The |
4387 agenda shows the entries for each day. With a @kbd{C-u} prefix (or | 4850 agenda shows the entries for each day. With a numeric |
4388 when the variable @code{org-agenda-include-all-todo} is @code{t}), all | 4851 prefix@footnote{For backward compatibility, the universal prefix |
4389 unfinished TODO items (including those without a date) are also listed at | 4852 @kbd{C-u} causes all TODO entries to be listed before the agenda. This |
4390 the beginning of the buffer, before the first date.@* | 4853 feature is deprecated, use the dedicated TODO list, or a block agenda |
4854 instead.} (like @kbd{C-u 2 1 C-c a a}) you may set the number of days | |
4855 to be displayed (see also the variable @code{org-agenda-ndays}) | |
4391 @end table | 4856 @end table |
4392 | 4857 |
4393 Remote editing from the agenda buffer means, for example, that you can | 4858 Remote editing from the agenda buffer means, for example, that you can |
4394 change the dates of deadlines and appointments from the agenda buffer. | 4859 change the dates of deadlines and appointments from the agenda buffer. |
4395 The commands available in the Agenda buffer are listed in @ref{Agenda | 4860 The commands available in the Agenda buffer are listed in @ref{Agenda |
4440 %%(org-calendar-holiday) ; special function for holiday names | 4905 %%(org-calendar-holiday) ; special function for holiday names |
4441 #+CATEGORY: Ann | 4906 #+CATEGORY: Ann |
4442 %%(diary-anniversary 14 5 1956) Arthur Dent is %d years old | 4907 %%(diary-anniversary 14 5 1956) Arthur Dent is %d years old |
4443 %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old | 4908 %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old |
4444 @end example | 4909 @end example |
4910 | |
4911 @subsubheading Appointment reminders | |
4912 @cindex @file{appt.el} | |
4913 @cindex appointment reminders | |
4914 | |
4915 Org can interact with Emacs appointments notification facility. | |
4916 | |
4917 To add all the appointments of your agenda files, use the command | |
4918 @code{org-agenda-to-appt}. This commands also lets you filter through | |
4919 the list of your appointments and add only those belonging to a specific | |
4920 category or matching a regular expression. See the docstring for | |
4921 details. | |
4445 | 4922 |
4446 @node Global TODO list, Matching tags and properties, Weekly/Daily agenda, Built-in agenda views | 4923 @node Global TODO list, Matching tags and properties, Weekly/Daily agenda, Built-in agenda views |
4447 @subsection The global TODO list | 4924 @subsection The global TODO list |
4448 @cindex global TODO list | 4925 @cindex global TODO list |
4449 @cindex TODO list, global | 4926 @cindex TODO list, global |
4510 @table @kbd | 4987 @table @kbd |
4511 @kindex C-c a m | 4988 @kindex C-c a m |
4512 @item C-c a m | 4989 @item C-c a m |
4513 Produce a list of all headlines that match a given set of tags. The | 4990 Produce a list of all headlines that match a given set of tags. The |
4514 command prompts for a selection criterion, which is a boolean logic | 4991 command prompts for a selection criterion, which is a boolean logic |
4515 expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or | 4992 expression with tags, like @samp{+work+urgent-withboss} or |
4516 @samp{WORK|HOME} (@pxref{Tags}). If you often need a specific search, | 4993 @samp{work|home} (@pxref{Tags}). If you often need a specific search, |
4517 define a custom command for it (@pxref{Agenda dispatcher}). | 4994 define a custom command for it (@pxref{Agenda dispatcher}). |
4518 @kindex C-c a M | 4995 @kindex C-c a M |
4519 @item C-c a M | 4996 @item C-c a M |
4520 Like @kbd{C-c a m}, but only select headlines that are also TODO items | 4997 Like @kbd{C-c a m}, but only select headlines that are also TODO items |
4521 and force checking subitems (see variable | 4998 and force checking subitems (see variable |
4614 @subsection Categories | 5091 @subsection Categories |
4615 | 5092 |
4616 @cindex category | 5093 @cindex category |
4617 The category is a broad label assigned to each agenda item. By default, | 5094 The category is a broad label assigned to each agenda item. By default, |
4618 the category is simply derived from the file name, but you can also | 5095 the category is simply derived from the file name, but you can also |
4619 specify it with a special line in the buffer, like this: | 5096 specify it with a special line in the buffer, like this@footnote{For |
5097 backward compatibility, the following also works: If there are several | |
5098 such lines in a file, each specifies the category for the text below it. | |
5099 The first category also applies to any text before the first CATEGORY | |
5100 line. However, using this method is @emph{strongly} deprecated as it is | |
5101 incompatible with the outline structure of the document. The correct | |
5102 method for setting multiple categories in a buffer is using a | |
5103 property.}: | |
4620 | 5104 |
4621 @example | 5105 @example |
4622 #+CATEGORY: Thesis | 5106 #+CATEGORY: Thesis |
4623 @end example | 5107 @end example |
4624 | 5108 |
4625 If there are several such lines in a file, each specifies the category | 5109 @noindent |
4626 for the text below it (but the first category also applies to any text | 5110 If you would like to have a special CATEGORY for a single entry or a |
4627 before the first CATEGORY line). The display in the agenda buffer looks | 5111 (sub)tree, give the entry a @code{:CATEGORY:} property with the location |
4628 best if the category is not longer than 10 characters. | 5112 as the value (@pxref{Properties and columns}). |
5113 | |
5114 @noindent | |
5115 The display in the agenda buffer looks best if the category is not | |
5116 longer than 10 characters. | |
4629 | 5117 |
4630 @node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting | 5118 @node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting |
4631 @subsection Time-of-Day Specifications | 5119 @subsection Time-of-Day Specifications |
4632 @cindex time-of-day specification | 5120 @cindex time-of-day specification |
4633 | 5121 |
4723 @table @kbd | 5211 @table @kbd |
4724 @tsubheading{Motion} | 5212 @tsubheading{Motion} |
4725 @cindex motion commands in agenda | 5213 @cindex motion commands in agenda |
4726 @kindex n | 5214 @kindex n |
4727 @item n | 5215 @item n |
4728 Next line (same as @key{up}). | 5216 Next line (same as @key{up} and @kbd{C-p}). |
4729 @kindex p | 5217 @kindex p |
4730 @item p | 5218 @item p |
4731 Previous line (same as @key{down}). | 5219 Previous line (same as @key{down} and @kbd{C-n}). |
4732 @tsubheading{View/GoTo org file} | 5220 @tsubheading{View/GoTo org file} |
4733 @kindex mouse-3 | 5221 @kindex mouse-3 |
4734 @kindex @key{SPC} | 5222 @kindex @key{SPC} |
4735 @item mouse-3 | 5223 @item mouse-3 |
4736 @itemx @key{SPC} | 5224 @itemx @key{SPC} |
4805 S-@key{right}. When the buffer is the global todo list, a prefix | 5293 S-@key{right}. When the buffer is the global todo list, a prefix |
4806 argument is interpreted to create a selective list for a specific TODO | 5294 argument is interpreted to create a selective list for a specific TODO |
4807 keyword. | 5295 keyword. |
4808 @c | 5296 @c |
4809 @kindex s | 5297 @kindex s |
5298 @kindex C-x C-s | |
4810 @item s | 5299 @item s |
5300 @itemx C-x C-s | |
4811 Save all Org-mode buffers in the current Emacs session. | 5301 Save all Org-mode buffers in the current Emacs session. |
4812 @c | 5302 @c |
4813 @kindex @key{right} | 5303 @kindex @key{right} |
4814 @item @key{right} | 5304 @item @key{right} |
4815 Display the following @code{org-agenda-ndays} days. For example, if | 5305 Display the following @code{org-agenda-ndays} days. For example, if |
4858 Show all tags associated with the current item. Because of | 5348 Show all tags associated with the current item. Because of |
4859 inheritance, this may be more than the tags listed in the line itself. | 5349 inheritance, this may be more than the tags listed in the line itself. |
4860 @c | 5350 @c |
4861 @kindex : | 5351 @kindex : |
4862 @item : | 5352 @item : |
4863 Set tags for the current headline. | 5353 Set tags for the current headline. If there is an active region in the |
5354 agenda, change a tag for all headings in the region. | |
4864 @c | 5355 @c |
4865 @kindex a | 5356 @kindex a |
4866 @item a | 5357 @item a |
4867 Toggle the ARCHIVE tag for the current headline. | 5358 Toggle the ARCHIVE tag for the current headline. |
4868 @c | 5359 @c |
4929 @c | 5420 @c |
4930 @kindex X | 5421 @kindex X |
4931 @item X | 5422 @item X |
4932 Cancel the currently running clock. | 5423 Cancel the currently running clock. |
4933 | 5424 |
5425 @kindex J | |
5426 @item J | |
5427 Jump to the running clock in another window. | |
5428 | |
4934 @tsubheading{Calendar commands} | 5429 @tsubheading{Calendar commands} |
4935 @cindex calendar commands, from agenda | 5430 @cindex calendar commands, from agenda |
4936 @kindex c | 5431 @kindex c |
4937 @item c | 5432 @item c |
4938 Open the Emacs calendar and move to the date at the agenda cursor. | 5433 Open the Emacs calendar and move to the date at the agenda cursor. |
5033 @lisp | 5528 @lisp |
5034 @group | 5529 @group |
5035 (setq org-agenda-custom-commands | 5530 (setq org-agenda-custom-commands |
5036 '(("w" todo "WAITING") | 5531 '(("w" todo "WAITING") |
5037 ("W" todo-tree "WAITING") | 5532 ("W" todo-tree "WAITING") |
5038 ("u" tags "+BOSS-URGENT") | 5533 ("u" tags "+boss-urgent") |
5039 ("v" tags-todo "+BOSS-URGENT") | 5534 ("v" tags-todo "+boss-urgent") |
5040 ("U" tags-tree "+BOSS-URGENT") | 5535 ("U" tags-tree "+boss-urgent") |
5041 ("f" occur-tree "\\<FIXME\\>"))) | 5536 ("f" occur-tree "\\<FIXME\\>") |
5537 ("h" . "HOME+Name tags searches") ; description for "h" prefix | |
5538 ("hl" tags "+home+Lisa") | |
5539 ("hp" tags "+home+Peter") | |
5540 ("hk" tags "+home+Kim"))) | |
5042 @end group | 5541 @end group |
5043 @end lisp | 5542 @end lisp |
5044 | 5543 |
5045 @noindent | 5544 @noindent |
5046 The initial single-character string in each entry defines the character | 5545 The initial string in each entry defines the keys you have to press |
5047 you have to press after the dispatcher command @kbd{C-c a} in order to | 5546 after the dispatcher command @kbd{C-c a} in order to access the command. |
5048 access the command. The second parameter is the search type, followed | 5547 Usually this will be just a single character, but if you have many |
5049 by the string or regular expression to be used for the matching. The | 5548 similar commands, you can also define two-letter combinations where the |
5050 example above will therefore define: | 5549 first character is the same in several combinations and serves as a |
5550 prefix key@footnote{You can provide a description for a prefix key by | |
5551 inserting a cons cell with the prefix and the description.}. The second | |
5552 parameter is the search type, followed by the string or regular | |
5553 expression to be used for the matching. The example above will | |
5554 therefore define: | |
5051 | 5555 |
5052 @table @kbd | 5556 @table @kbd |
5053 @item C-c a w | 5557 @item C-c a w |
5054 as a global search for TODO entries with @samp{WAITING} as the TODO | 5558 as a global search for TODO entries with @samp{WAITING} as the TODO |
5055 keyword | 5559 keyword |
5056 @item C-c a W | 5560 @item C-c a W |
5057 as the same search, but only in the current buffer and displaying the | 5561 as the same search, but only in the current buffer and displaying the |
5058 results as a sparse tree | 5562 results as a sparse tree |
5059 @item C-c a u | 5563 @item C-c a u |
5060 as a global tags search for headlines marked @samp{:BOSS:} but not | 5564 as a global tags search for headlines marked @samp{:boss:} but not |
5061 @samp{:URGENT:} | 5565 @samp{:urgent:} |
5062 @item C-c a v | 5566 @item C-c a v |
5063 as the same search as @kbd{C-c a u}, but limiting the search to | 5567 as the same search as @kbd{C-c a u}, but limiting the search to |
5064 headlines that are also TODO items | 5568 headlines that are also TODO items |
5065 @item C-c a U | 5569 @item C-c a U |
5066 as the same search as @kbd{C-c a u}, but only in the current buffer and | 5570 as the same search as @kbd{C-c a u}, but only in the current buffer and |
5067 displaying the result as a sparse tree | 5571 displaying the result as a sparse tree |
5068 @item C-c a f | 5572 @item C-c a f |
5069 to create a sparse tree (again: current buffer only) with all entries | 5573 to create a sparse tree (again: current buffer only) with all entries |
5070 containing the word @samp{FIXME}. | 5574 containing the word @samp{FIXME} |
5575 @item C-c a h | |
5576 as a prefix command for a HOME tags search where you have to press an | |
5577 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa, | |
5578 Peter, or Kim) as additional tag to match. | |
5071 @end table | 5579 @end table |
5072 | 5580 |
5073 @node Block agenda, Setting Options, Storing searches, Custom agenda views | 5581 @node Block agenda, Setting Options, Storing searches, Custom agenda views |
5074 @subsection Block agenda | 5582 @subsection Block agenda |
5075 @cindex block agenda | 5583 @cindex block agenda |
5086 @lisp | 5594 @lisp |
5087 @group | 5595 @group |
5088 (setq org-agenda-custom-commands | 5596 (setq org-agenda-custom-commands |
5089 '(("h" "Agenda and Home-related tasks" | 5597 '(("h" "Agenda and Home-related tasks" |
5090 ((agenda) | 5598 ((agenda) |
5091 (tags-todo "HOME") | 5599 (tags-todo "home") |
5092 (tags "GARDEN"))) | 5600 (tags "garden"))) |
5093 ("o" "Agenda and Office-related tasks" | 5601 ("o" "Agenda and Office-related tasks" |
5094 ((agenda) | 5602 ((agenda) |
5095 (tags-todo "WORK") | 5603 (tags-todo "work") |
5096 (tags "OFFICE"))))) | 5604 (tags "office"))))) |
5097 @end group | 5605 @end group |
5098 @end lisp | 5606 @end lisp |
5099 | 5607 |
5100 @noindent | 5608 @noindent |
5101 This will define @kbd{C-c a h} to create a multi-block view for stuff | 5609 This will define @kbd{C-c a h} to create a multi-block view for stuff |
5102 you need to attend to at home. The resulting agenda buffer will contain | 5610 you need to attend to at home. The resulting agenda buffer will contain |
5103 your agenda for the current week, all TODO items that carry the tag | 5611 your agenda for the current week, all TODO items that carry the tag |
5104 @samp{HOME}, and also all lines tagged with @samp{GARDEN}. Finally the | 5612 @samp{home}, and also all lines tagged with @samp{garden}. Finally the |
5105 command @kbd{C-c a o} provides a similar view for office tasks. | 5613 command @kbd{C-c a o} provides a similar view for office tasks. |
5106 | 5614 |
5107 | 5615 |
5108 @node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda views | 5616 @node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda views |
5109 @subsection Setting Options for custom commands | 5617 @subsection Setting Options for custom commands |
5120 @group | 5628 @group |
5121 (setq org-agenda-custom-commands | 5629 (setq org-agenda-custom-commands |
5122 '(("w" todo "WAITING" | 5630 '(("w" todo "WAITING" |
5123 ((org-agenda-sorting-strategy '(priority-down)) | 5631 ((org-agenda-sorting-strategy '(priority-down)) |
5124 (org-agenda-prefix-format " Mixed: "))) | 5632 (org-agenda-prefix-format " Mixed: "))) |
5125 ("U" tags-tree "+BOSS-URGENT" | 5633 ("U" tags-tree "+boss-urgent" |
5126 ((org-show-following-heading nil) | 5634 ((org-show-following-heading nil) |
5127 (org-show-hierarchy-above nil))))) | 5635 (org-show-hierarchy-above nil))))) |
5128 @end group | 5636 @end group |
5129 @end lisp | 5637 @end lisp |
5130 | 5638 |
5131 @noindent | 5639 @noindent |
5132 Now the @kbd{C-c a w} command will sort the collected entries only by | 5640 Now the @kbd{C-c a w} command will sort the collected entries only by |
5133 priority, and the prefix format is modified to just say @samp{ Mixed:} | 5641 priority, and the prefix format is modified to just say @samp{ Mixed: } |
5134 instead of giving the category of the entry. The sparse tags tree of | 5642 instead of giving the category of the entry. The sparse tags tree of |
5135 @kbd{C-c a U} will now turn out ultra-compact, because neither the | 5643 @kbd{C-c a U} will now turn out ultra-compact, because neither the |
5136 headline hierarchy above the match, nor the headline following the match | 5644 headline hierarchy above the match, nor the headline following the match |
5137 will be shown. | 5645 will be shown. |
5138 | 5646 |
5150 @lisp | 5658 @lisp |
5151 @group | 5659 @group |
5152 (setq org-agenda-custom-commands | 5660 (setq org-agenda-custom-commands |
5153 '(("h" "Agenda and Home-related tasks" | 5661 '(("h" "Agenda and Home-related tasks" |
5154 ((agenda) | 5662 ((agenda) |
5155 (tags-todo "HOME") | 5663 (tags-todo "home") |
5156 (tags "GARDEN" | 5664 (tags "garden" |
5157 ((org-agenda-sorting-strategy '(priority-up))))) | 5665 ((org-agenda-sorting-strategy '(priority-up))))) |
5158 ((org-agenda-sorting-strategy '(priority-down)))) | 5666 ((org-agenda-sorting-strategy '(priority-down)))) |
5159 ("o" "Agenda and Office-related tasks" | 5667 ("o" "Agenda and Office-related tasks" |
5160 ((agenda) | 5668 ((agenda) |
5161 (tags-todo "WORK") | 5669 (tags-todo "work") |
5162 (tags "OFFICE"))))) | 5670 (tags "office"))))) |
5163 @end group | 5671 @end group |
5164 @end lisp | 5672 @end lisp |
5165 | 5673 |
5166 As you see, the values and parenthesis setting is a little complex. | 5674 As you see, the values and parenthesis setting is a little complex. |
5167 When in doubt, use the customize interface to set this variable - it | 5675 When in doubt, use the customize interface to set this variable - it |
5216 (setq org-agenda-custom-commands | 5724 (setq org-agenda-custom-commands |
5217 '(("X" agenda "" nil ("agenda.html" "agenda.ps")) | 5725 '(("X" agenda "" nil ("agenda.html" "agenda.ps")) |
5218 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) | 5726 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) |
5219 ("h" "Agenda and Home-related tasks" | 5727 ("h" "Agenda and Home-related tasks" |
5220 ((agenda) | 5728 ((agenda) |
5221 (tags-todo "HOME") | 5729 (tags-todo "home") |
5222 (tags "GARDEN")) | 5730 (tags "garden")) |
5223 nil | 5731 nil |
5224 ("~/views/home.html")) | 5732 ("~/views/home.html")) |
5225 ("o" "Agenda and Office-related tasks" | 5733 ("o" "Agenda and Office-related tasks" |
5226 ((agenda) | 5734 ((agenda) |
5227 (tags-todo "WORK") | 5735 (tags-todo "work") |
5228 (tags "OFFICE")) | 5736 (tags "office")) |
5229 nil | 5737 nil |
5230 ("~/views/office.ps")))) | 5738 ("~/views/office.ps")))) |
5231 @end group | 5739 @end group |
5232 @end lisp | 5740 @end lisp |
5233 | 5741 |
5281 @noindent | 5789 @noindent |
5282 or, if you need to modify some parameters | 5790 or, if you need to modify some parameters |
5283 @example | 5791 @example |
5284 emacs -eval '(org-batch-store-agenda-views \ | 5792 emacs -eval '(org-batch-store-agenda-views \ |
5285 org-agenda-ndays 30 \ | 5793 org-agenda-ndays 30 \ |
5794 org-agenda-start-day "2007-11-01" \ | |
5286 org-agenda-include-diary nil \ | 5795 org-agenda-include-diary nil \ |
5287 org-agenda-files (quote ("~/org/project.org")))' \ | 5796 org-agenda-files (quote ("~/org/project.org")))' \ |
5288 -kill | 5797 -kill |
5289 @end example | 5798 @end example |
5290 @noindent | 5799 @noindent |
5663 Export as ASCII file. For an org file @file{myfile.org}, the ASCII file | 6172 Export as ASCII file. For an org file @file{myfile.org}, the ASCII file |
5664 will be @file{myfile.txt}. The file will be overwritten without | 6173 will be @file{myfile.txt}. The file will be overwritten without |
5665 warning. If there is an active region, only the region will be | 6174 warning. If there is an active region, only the region will be |
5666 exported. If the selected region is a single tree, the tree head will | 6175 exported. If the selected region is a single tree, the tree head will |
5667 become the document title. If the tree head entry has or inherits an | 6176 become the document title. If the tree head entry has or inherits an |
5668 EXPORT_FILE_NAME property, that name will be used for the export. | 6177 @code{:EXPORT_FILE_NAME:} property, that name will be used for the |
6178 export. | |
5669 @kindex C-c C-e v a | 6179 @kindex C-c C-e v a |
5670 @item C-c C-e v a | 6180 @item C-c C-e v a |
5671 Export only the visible part of the document. | 6181 Export only the visible part of the document. |
5672 @end table | 6182 @end table |
5673 | 6183 |
5718 Export as HTML file @file{myfile.html}. For an org file | 6228 Export as HTML file @file{myfile.html}. For an org file |
5719 @file{myfile.org}, the ASCII file will be @file{myfile.html}. The file | 6229 @file{myfile.org}, the ASCII file will be @file{myfile.html}. The file |
5720 will be overwritten without warning. If there is an active region, only | 6230 will be overwritten without warning. If there is an active region, only |
5721 the region will be exported. If the selected region is a single tree, | 6231 the region will be exported. If the selected region is a single tree, |
5722 the tree head will become the document title. If the tree head entry | 6232 the tree head will become the document title. If the tree head entry |
5723 has or inherits an EXPORT_FILE_NAME property, that name will be used for | 6233 has or inherits an @code{:EXPORT_FILE_NAME:} property, that name will be |
5724 the export. | 6234 used for the export. |
5725 @kindex C-c C-e b | 6235 @kindex C-c C-e b |
5726 @item C-c C-e b | 6236 @item C-c C-e b |
5727 Export as HTML file and immediately open it with a browser. | 6237 Export as HTML file and immediately open it with a browser. |
5728 @kindex C-c C-e H | 6238 @kindex C-c C-e H |
5729 @item C-c C-e H | 6239 @item C-c C-e H |
5730 Export to a temporary buffer, do not create a file. | 6240 Export to a temporary buffer, do not create a file. |
5731 @kindex C-c C-e R | 6241 @kindex C-c C-e R |
5732 @item C-c C-e H | 6242 @item C-c C-e R |
5733 Export the active region to a temporary buffer. With prefix arg, do not | 6243 Export the active region to a temporary buffer. With prefix arg, do not |
5734 produce file header and foot, but just the plain HTML section for the | 6244 produce file header and foot, but just the plain HTML section for the |
5735 region. This is good for cut-and-paste operations. | 6245 region. This is good for cut-and-paste operations. |
5736 @kindex C-c C-e v h | 6246 @kindex C-c C-e v h |
5737 @kindex C-c C-e v b | 6247 @kindex C-c C-e v b |
5875 Org-mode contains a La@TeX{} exporter written by Bastien Guerry. | 6385 Org-mode contains a La@TeX{} exporter written by Bastien Guerry. |
5876 | 6386 |
5877 @menu | 6387 @menu |
5878 * LaTeX export commands:: How to invoke LaTeX export | 6388 * LaTeX export commands:: How to invoke LaTeX export |
5879 * Quoting LaTeX code:: Incorporating literal LaTeX code | 6389 * Quoting LaTeX code:: Incorporating literal LaTeX code |
6390 * Sectioning structure:: | |
5880 @end menu | 6391 @end menu |
5881 | 6392 |
5882 @node LaTeX export commands, Quoting LaTeX code, LaTeX export, LaTeX export | 6393 @node LaTeX export commands, Quoting LaTeX code, LaTeX export, LaTeX export |
5883 @subsection LaTeX export commands | 6394 @subsection LaTeX export commands |
5884 | 6395 |
5918 @end example | 6429 @end example |
5919 | 6430 |
5920 @noindent | 6431 @noindent |
5921 creates two levels of headings and does the rest as items. | 6432 creates two levels of headings and does the rest as items. |
5922 | 6433 |
5923 @node Quoting LaTeX code, , LaTeX export commands, LaTeX export | 6434 @node Quoting LaTeX code, Sectioning structure, LaTeX export commands, LaTeX export |
5924 @subsection Quoting LaTeX code | 6435 @subsection Quoting LaTeX code |
5925 | 6436 |
5926 Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly | 6437 Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly |
5927 inserted into the La@TeX{} file. Forthermore, you can add special code | 6438 inserted into the La@TeX{} file. Forthermore, you can add special code |
5928 that should only be present in La@TeX{} export with the following | 6439 that should only be present in La@TeX{} export with the following |
5937 @example | 6448 @example |
5938 #+BEGIN_LaTeX | 6449 #+BEGIN_LaTeX |
5939 All lines between these markers are exported literally | 6450 All lines between these markers are exported literally |
5940 #+END_LaTeX | 6451 #+END_LaTeX |
5941 @end example | 6452 @end example |
6453 | |
6454 | |
6455 | |
6456 @node Sectioning structure, , Quoting LaTeX code, LaTeX export | |
6457 @subsection Sectioning structure | |
6458 @cindex LaTeX class | |
6459 @cindex LaTeX sectioning structure | |
6460 | |
6461 By default, the La@TeX{} output uses the class @code{article}. | |
6462 | |
6463 You can change this globally by setting a different value for | |
6464 @code{org-export-latex-default-class} or locally by adding an option | |
6465 like @code{#+LaTeX_CLASS: myclass} in your file. The class should be | |
6466 listed in @code{org-export-latex-classes}, where you can also define the | |
6467 sectioning structure for each class. | |
6468 | |
6469 | |
5942 @node XOXO export, iCalendar export, LaTeX export, Exporting | 6470 @node XOXO export, iCalendar export, LaTeX export, Exporting |
5943 @section XOXO export | 6471 @section XOXO export |
5944 @cindex XOXO export | 6472 @cindex XOXO export |
5945 | 6473 |
5946 Org-mode contains an exporter that produces XOXO-style output. | 6474 Org-mode contains an exporter that produces XOXO-style output. |
5983 Create a single large iCalendar file from all files in | 6511 Create a single large iCalendar file from all files in |
5984 @code{org-agenda-files} and write it to the file given by | 6512 @code{org-agenda-files} and write it to the file given by |
5985 @code{org-combined-agenda-icalendar-file}. | 6513 @code{org-combined-agenda-icalendar-file}. |
5986 @end table | 6514 @end table |
5987 | 6515 |
6516 The export will honor SUMMARY, DESCRIPTION and LOCATION properties if | |
6517 the selected entries have them. If not, the summary will be derived | |
6518 from the headline, and the description from the body (limited to | |
6519 @code{org-icalendar-include-body} characters). | |
6520 | |
5988 How this calendar is best read and updated, depends on the application | 6521 How this calendar is best read and updated, depends on the application |
5989 you are using. The FAQ covers this issue. | 6522 you are using. The FAQ covers this issue. |
5990 | 6523 |
5991 | 6524 |
5992 @node Text interpretation, , iCalendar export, Exporting | 6525 @node Text interpretation, , iCalendar export, Exporting |
5997 | 6530 |
5998 @menu | 6531 @menu |
5999 * Comment lines:: Some lines will not be exported | 6532 * Comment lines:: Some lines will not be exported |
6000 * Initial text:: Text before the first headline | 6533 * Initial text:: Text before the first headline |
6001 * Footnotes:: Numbers like [1] | 6534 * Footnotes:: Numbers like [1] |
6535 * Quoted examples:: Inserting quoted chnuks of text | |
6002 * Enhancing text:: Subscripts, symbols and more | 6536 * Enhancing text:: Subscripts, symbols and more |
6003 * Export options:: How to influence the export settings | 6537 * Export options:: How to influence the export settings |
6004 @end menu | 6538 @end menu |
6005 | 6539 |
6006 @node Comment lines, Initial text, Text interpretation, Text interpretation | 6540 @node Comment lines, Initial text, Text interpretation, Text interpretation |
6054 #+TEXT: We place the table of contents here: | 6588 #+TEXT: We place the table of contents here: |
6055 #+TEXT: [TABLE-OF-CONTENTS] | 6589 #+TEXT: [TABLE-OF-CONTENTS] |
6056 #+TEXT: This goes between the table of contents and the first headline | 6590 #+TEXT: This goes between the table of contents and the first headline |
6057 @end example | 6591 @end example |
6058 | 6592 |
6059 @node Footnotes, Enhancing text, Initial text, Text interpretation | 6593 @node Footnotes, Quoted examples, Initial text, Text interpretation |
6060 @subsection Footnotes | 6594 @subsection Footnotes |
6061 @cindex footnotes | 6595 @cindex footnotes |
6062 @cindex @file{footnote.el} | 6596 @cindex @file{footnote.el} |
6063 | 6597 |
6064 Numbers in square brackets are treated as footnotes, so that you can use | 6598 Numbers in square brackets are treated as footnotes, so that you can use |
6066 | 6600 |
6067 @example | 6601 @example |
6068 The org-mode homepage[1] clearly needs help from | 6602 The org-mode homepage[1] clearly needs help from |
6069 a good web designer. | 6603 a good web designer. |
6070 | 6604 |
6071 [1] The link is: http://www.astro.uva.nl/~dominik/Tools/org | 6605 [1] The link is: http://orgmode.org |
6072 @end example | 6606 @end example |
6073 | 6607 |
6074 @noindent | 6608 @noindent |
6075 @kindex C-c ! | 6609 @kindex C-c ! |
6076 Note that the @file{footnote} package uses @kbd{C-c !} to invoke its | 6610 Note that the @file{footnote} package uses @kbd{C-c !} to invoke its |
6079 @code{footnote-prefix} to switch footnotes commands to another key. Or, | 6613 @code{footnote-prefix} to switch footnotes commands to another key. Or, |
6080 if you are too used to this binding, you could use | 6614 if you are too used to this binding, you could use |
6081 @code{org-replace-disputed-keys} and @code{org-disputed-keys} to change | 6615 @code{org-replace-disputed-keys} and @code{org-disputed-keys} to change |
6082 the settings in Org-mode. | 6616 the settings in Org-mode. |
6083 | 6617 |
6084 @node Enhancing text, Export options, Footnotes, Text interpretation | 6618 @node Quoted examples, Enhancing text, Footnotes, Text interpretation |
6619 @subsection Quoted examples | |
6620 @cindex quoted examples | |
6621 @cindex examples, quoted | |
6622 @cindex text, fixed width | |
6623 @cindex fixed width text | |
6624 | |
6625 When writing technical documents, you often need to insert examples that | |
6626 are not further interpreted by Org-mode. For historical reasons, there | |
6627 are several ways to do this: | |
6628 | |
6629 @itemize @bullet | |
6630 @item | |
6631 If a headline starts with the word @samp{QUOTE}, the text below the | |
6632 headline will be typeset as fixed-width, to allow quoting of computer | |
6633 codes etc. | |
6634 @item | |
6635 Lines starting with @samp{:} are also typeset in fixed-width font. | |
6636 @table @kbd | |
6637 @kindex C-c : | |
6638 @item C-c : | |
6639 Toggle fixed-width for entry (QUOTE) or region, see below. | |
6640 @end table | |
6641 @item | |
6642 Finally, text between | |
6643 @example | |
6644 #+BEGIN_EXAMPLE | |
6645 quoted text | |
6646 #+END_EXAMPLE | |
6647 @end example | |
6648 will also be exported in this way. | |
6649 @end itemize | |
6650 | |
6651 | |
6652 @node Enhancing text, Export options, Quoted examples, Text interpretation | |
6085 @subsection Enhancing text for export | 6653 @subsection Enhancing text for export |
6086 @cindex enhancing text | 6654 @cindex enhancing text |
6087 @cindex richer text | 6655 @cindex richer text |
6088 | 6656 |
6089 Some of the export backends of Org-mode allow for sophisticated text | 6657 Some of the export backends of Org-mode allow for sophisticated text |
6090 formatting, this is true in particular for the HTML and La@TeX{} | 6658 formatting, this is true in particular for the HTML and La@TeX{} |
6091 backends. Org-mode has a number of typing conventions that allow to | 6659 backends. Org-mode has a number of typing conventions that allow to |
6092 produce a richly formatted output. | 6660 produce a richly formatted output. |
6093 | 6661 |
6094 @itemize @bullet | 6662 @itemize @bullet |
6095 | 6663 |
6096 @cindex hand-formatted lists | 6664 @cindex hand-formatted lists |
6101 backend supports lists. See @xref{Plain lists}. | 6669 backend supports lists. See @xref{Plain lists}. |
6102 | 6670 |
6103 @cindex underlined text | 6671 @cindex underlined text |
6104 @cindex bold text | 6672 @cindex bold text |
6105 @cindex italic text | 6673 @cindex italic text |
6106 @item | 6674 @cindex verbatim text |
6107 You can make words @b{*bold*}, @i{/italic/}, _underlined_, | 6675 @item |
6108 @code{=code=}, and even @samp{+strikethrough+}@footnote{but remember | 6676 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} |
6109 that strikethrough is typographically evil and should @i{never} be | 6677 and @code{~verbatim~}, and, if you must, @samp{+strikethrough+}. Text |
6110 used.}. | 6678 in the code and verbatim string is not processed for org-mode specific |
6679 syntax, it is exported verbatim. | |
6111 | 6680 |
6112 @cindex horizontal rules, in exported files | 6681 @cindex horizontal rules, in exported files |
6113 @item | 6682 @item |
6114 A line consisting of only dashes, and at least 5 of them, will be | 6683 A line consisting of only dashes, and at least 5 of them, will be |
6115 exported as a horizontal line (@samp{<hr/>} in HTML). | 6684 exported as a horizontal line (@samp{<hr/>} in HTML). |
6135 @table @kbd | 6704 @table @kbd |
6136 @kindex C-c : | 6705 @kindex C-c : |
6137 @item C-c : | 6706 @item C-c : |
6138 Toggle fixed-width for entry (QUOTE) or region, see below. | 6707 Toggle fixed-width for entry (QUOTE) or region, see below. |
6139 @end table | 6708 @end table |
6709 Finally, text between | |
6710 @example | |
6711 #+BEGIN_EXAMPLE | |
6712 quoted text | |
6713 #+END_EXAMPLE | |
6714 @end example | |
6715 will also be exported in this way. | |
6140 | 6716 |
6141 @cindex linebreak, forced | 6717 @cindex linebreak, forced |
6142 @item | 6718 @item |
6143 A double backslash @emph{at the end of a line} enforces a line break at | 6719 A double backslash @emph{at the end of a line} enforces a line break at |
6144 this position. | 6720 this position. |
6721 | |
6722 @cindex HTML entities, LaTeX entities | |
6723 @item | |
6724 Strings like @code{\alpha} will be exported as @code{α}, in the | |
6725 HTML output. These strings are exported as @code{$\alpha$} in the | |
6726 La@TeX{} output. Similarly, @code{\nbsp} will become @code{ } in | |
6727 HTML and in La@TeX{}. This applies for a long list of entities, see | |
6728 the variable @code{org-html-entities} for the complete list. | |
6729 @c FIXME | |
6145 @end itemize | 6730 @end itemize |
6146 | 6731 |
6147 If these conversions conflict with your habits of typing ASCII text, | 6732 If these conversions conflict with your habits of typing ASCII text, |
6148 they can all be turned off with corresponding variables. See the | 6733 they can all be turned off with corresponding variables. See the |
6149 customization group @code{org-export-general}, and the following section | 6734 customization group @code{org-export-general}, and the following section |
6170 @end table | 6755 @end table |
6171 | 6756 |
6172 @example | 6757 @example |
6173 #+TITLE: the title to be shown (default is the buffer name) | 6758 #+TITLE: the title to be shown (default is the buffer name) |
6174 #+AUTHOR: the author (default taken from @code{user-full-name}) | 6759 #+AUTHOR: the author (default taken from @code{user-full-name}) |
6760 #+DATE: A date, fixed, of a format string for @code{format-time-string} | |
6175 #+EMAIL: his/her email address (default from @code{user-mail-address}) | 6761 #+EMAIL: his/her email address (default from @code{user-mail-address}) |
6176 #+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language}) | 6762 #+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language}) |
6177 #+TEXT: Some descriptive text to be inserted at the beginning. | 6763 #+TEXT: Some descriptive text to be inserted at the beginning. |
6178 #+TEXT: Several lines may be given. | 6764 #+TEXT: Several lines may be given. |
6179 #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... | 6765 #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... |
6189 @cindex quoted HTML tags | 6775 @cindex quoted HTML tags |
6190 @cindex fixed-width sections | 6776 @cindex fixed-width sections |
6191 @cindex tables | 6777 @cindex tables |
6192 @cindex @TeX{}-like syntax for sub- and superscripts | 6778 @cindex @TeX{}-like syntax for sub- and superscripts |
6193 @cindex footnotes | 6779 @cindex footnotes |
6780 @cindex special strings | |
6194 @cindex emphasized text | 6781 @cindex emphasized text |
6195 @cindex @TeX{} macros | 6782 @cindex @TeX{} macros |
6196 @cindex La@TeX{} fragments | 6783 @cindex La@TeX{} fragments |
6197 @cindex author info, in export | 6784 @cindex author info, in export |
6198 @cindex time info, in export | 6785 @cindex time info, in export |
6205 :: @r{turn on/off fixed-width sections} | 6792 :: @r{turn on/off fixed-width sections} |
6206 |: @r{turn on/off tables} | 6793 |: @r{turn on/off tables} |
6207 ^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} | 6794 ^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} |
6208 @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} | 6795 @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} |
6209 @r{the simple @code{a_b} will be left as it is.} | 6796 @r{the simple @code{a_b} will be left as it is.} |
6797 -: @r{turn on/off conversion of special strings.} | |
6210 f: @r{turn on/off foototes like this[1].} | 6798 f: @r{turn on/off foototes like this[1].} |
6211 *: @r{turn on/off emphasized text (bold, italic, underlined)} | 6799 *: @r{turn on/off emphasized text (bold, italic, underlined)} |
6212 TeX: @r{turn on/off simple @TeX{} macros in plain text} | 6800 TeX: @r{turn on/off simple @TeX{} macros in plain text} |
6213 LaTeX: @r{turn on/off La@TeX{} fragments} | 6801 LaTeX: @r{turn on/off La@TeX{} fragments} |
6214 skip: @r{turn on/off skipping the text before the first heading} | 6802 skip: @r{turn on/off skipping the text before the first heading} |
6215 author: @r{turn on/off inclusion of author name/email into exported file} | 6803 author: @r{turn on/off inclusion of author name/email into exported file} |
6216 timestamp: @r{turn on/off inclusion creation time into exported file} | 6804 timestamp: @r{turn on/off inclusion creation time into exported file} |
6805 d: @r{turn on/off inclusion of drawers} | |
6217 @end example | 6806 @end example |
6218 | 6807 |
6219 These options take effect in both the HTML and La@TeX{} export, except | 6808 These options take effect in both the HTML and La@TeX{} export, except |
6220 for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and | 6809 for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and |
6221 @code{nil} for the La@TeX{} export. | 6810 @code{nil} for the La@TeX{} export. |
6272 one variable, called @code{org-publish-project-alist}. | 6861 one variable, called @code{org-publish-project-alist}. |
6273 Each element of the list configures one project, and may be in one of | 6862 Each element of the list configures one project, and may be in one of |
6274 the two following forms: | 6863 the two following forms: |
6275 | 6864 |
6276 @lisp | 6865 @lisp |
6277 ("project-name" :property value :property value ...) | 6866 ("project-name" :property value :property value ...) |
6278 | 6867 |
6279 @r{or} | 6868 @r{or} |
6280 | 6869 |
6281 ("project-name" :components ("project-name" "project-name" ...)) | 6870 ("project-name" :components ("project-name" "project-name" ...)) |
6282 | 6871 |
6283 @end lisp | 6872 @end lisp |
6284 | 6873 |
6285 In both cases, projects are configured by specifying property values. | 6874 In both cases, projects are configured by specifying property values. |
6286 A project defines the set of files that will be published, as well as | 6875 A project defines the set of files that will be published, as well as |
6376 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers} | 6965 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers} |
6377 @item @code{:table-of-contents} @tab @code{org-export-with-toc} | 6966 @item @code{:table-of-contents} @tab @code{org-export-with-toc} |
6378 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees} | 6967 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees} |
6379 @item @code{:emphasize} @tab @code{org-export-with-emphasize} | 6968 @item @code{:emphasize} @tab @code{org-export-with-emphasize} |
6380 @item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} | 6969 @item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} |
6970 @item @code{:special-strings} @tab @code{org-export-with-special-strings} | |
6381 @item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} | 6971 @item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} |
6382 @item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} | 6972 @item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} |
6383 @item @code{:fixed-width} @tab @code{org-export-with-fixed-width} | 6973 @item @code{:fixed-width} @tab @code{org-export-with-fixed-width} |
6384 @item @code{:timestamps} .@tab @code{org-export-with-timestamps} | 6974 @item @code{:timestamps} .@tab @code{org-export-with-timestamps} |
6385 @item @code{:tags} .@tab @code{org-export-with-tags} | 6975 @item @code{:tags} .@tab @code{org-export-with-tags} |
6397 @item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble} | 6987 @item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble} |
6398 @item @code{:author} @tab @code{user-full-name} | 6988 @item @code{:author} @tab @code{user-full-name} |
6399 @item @code{:email} @tab @code{user-mail-address} | 6989 @item @code{:email} @tab @code{user-mail-address} |
6400 @end multitable | 6990 @end multitable |
6401 | 6991 |
6992 If you use several email addresses, separate them by a semi-column. | |
6993 | |
6402 Most of the @code{org-export-with-*} variables have the same effect in | 6994 Most of the @code{org-export-with-*} variables have the same effect in |
6403 both HTML and La@TeX{} exporters, except for @code{:TeX-macros} and | 6995 both HTML and La@TeX{} exporters, except for @code{:TeX-macros} and |
6404 @code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the | 6996 @code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the |
6405 La@TeX{} export. | 6997 La@TeX{} export. |
6406 | 6998 |
6407 When a property is given a value in org-publish-project-alist, its | 6999 When a property is given a value in @code{org-publish-project-alist}, |
6408 setting overrides the value of the corresponding user variable (if any) | 7000 its setting overrides the value of the corresponding user variable (if |
6409 during publishing. Options set within a file (@pxref{Export | 7001 any) during publishing. Options set within a file (@pxref{Export |
6410 options}), however, override everything. | 7002 options}), however, override everything. |
6411 | 7003 |
6412 @node Publishing links, Project page index, Publishing options, Configuration | 7004 @node Publishing links, Project page index, Publishing options, Configuration |
6413 @subsection Links between published files | 7005 @subsection Links between published files |
6414 @cindex links, publishing | 7006 @cindex links, publishing |
6420 pages of your "org web" project and the links will work as expected when | 7012 pages of your "org web" project and the links will work as expected when |
6421 you publish them to HTML. | 7013 you publish them to HTML. |
6422 | 7014 |
6423 You may also link to related files, such as images. Provided you are | 7015 You may also link to related files, such as images. Provided you are |
6424 careful with relative pathnames, and provided you have also configured | 7016 careful with relative pathnames, and provided you have also configured |
6425 org-publish to upload the related files, these links will work | 7017 @code{org-publish} to upload the related files, these links will work |
6426 too. @ref{Complex example} for an example of this usage. | 7018 too. @ref{Complex example} for an example of this usage. |
6427 | 7019 |
6428 Sometime an Org-mode file to be published may contain links that are | 7020 Sometime an Org-mode file to be published may contain links that are |
6429 only valid in your production environment, but not in the publishing | 7021 only valid in your production environment, but not in the publishing |
6430 location. In this case, use the property | 7022 location. In this case, use the property |
6679 This line sets the category for the agenda file. The category applies | 7271 This line sets the category for the agenda file. The category applies |
6680 for all subsequent lines until the next @samp{#+CATEGORY} line, or the | 7272 for all subsequent lines until the next @samp{#+CATEGORY} line, or the |
6681 end of the file. The first such line also applies to any entries before it. | 7273 end of the file. The first such line also applies to any entries before it. |
6682 @item #+COLUMNS: %25ITEM ..... | 7274 @item #+COLUMNS: %25ITEM ..... |
6683 Set the default format for columns view. This format applies when | 7275 Set the default format for columns view. This format applies when |
6684 columns view is invoked in location where no COLUMNS property applies. | 7276 columns view is invoked in location where no @code{COLUMNS} property |
7277 applies. | |
6685 @item #+CONSTANTS: name1=value1 ... | 7278 @item #+CONSTANTS: name1=value1 ... |
6686 Set file-local values for constants to be used in table formulas. This | 7279 Set file-local values for constants to be used in table formulas. This |
6687 line set the local variable @code{org-table-formula-constants-local}. | 7280 line set the local variable @code{org-table-formula-constants-local}. |
6688 The global version of theis variable is | 7281 The global version of this variable is |
6689 @code{org-table-formula-constants}. | 7282 @code{org-table-formula-constants}. |
6690 corresponding | 7283 @item #+DRAWERS: NAME1 ..... |
7284 Set the file-local set of drawers. The corresponding global variable is | |
7285 @code{org-drawers}. | |
6691 @item #+LINK: linkword replace | 7286 @item #+LINK: linkword replace |
6692 These lines (several are allowed) specify link abbreviations. | 7287 These lines (several are allowed) specify link abbreviations. |
6693 @xref{Link abbreviations}. The corresponding variable is | 7288 @xref{Link abbreviations}. The corresponding variable is |
6694 @code{org-link-abbrev-alist}. | 7289 @code{org-link-abbrev-alist}. |
6695 @item #+PRIORITIES: highest lowest default | 7290 @item #+PRIORITIES: highest lowest default |
6721 @cindex @code{noalign}, STARTUP keyword | 7316 @cindex @code{noalign}, STARTUP keyword |
6722 @example | 7317 @example |
6723 align @r{align all tables} | 7318 align @r{align all tables} |
6724 noalign @r{don't align tables on startup} | 7319 noalign @r{don't align tables on startup} |
6725 @end example | 7320 @end example |
6726 Logging TODO state changes and clock intervals (variable | 7321 Logging TODO state changes and clock intervals (variables |
6727 @code{org-log-done}) can be configured using these options. | 7322 @code{org-log-done} and @code{org-log-repeat}) can be configured using |
7323 these options. | |
6728 @cindex @code{logdone}, STARTUP keyword | 7324 @cindex @code{logdone}, STARTUP keyword |
6729 @cindex @code{nologging}, STARTUP keyword | 7325 @cindex @code{nologging}, STARTUP keyword |
6730 @cindex @code{lognotedone}, STARTUP keyword | 7326 @cindex @code{lognotedone}, STARTUP keyword |
6731 @cindex @code{lognoteclock-out}, STARTUP keyword | 7327 @cindex @code{lognoteclock-out}, STARTUP keyword |
6732 @cindex @code{lognotestate}, STARTUP keyword | 7328 @cindex @code{lognotestate}, STARTUP keyword |
6774 These lines (several such lines are allowed) specify the legal tags in | 7370 These lines (several such lines are allowed) specify the legal tags in |
6775 this file, and (potentially) the corresponding @emph{fast tag selection} | 7371 this file, and (potentially) the corresponding @emph{fast tag selection} |
6776 keys. The corresponding variable is @code{org-tag-alist}. | 7372 keys. The corresponding variable is @code{org-tag-alist}. |
6777 @item #+TBLFM: | 7373 @item #+TBLFM: |
6778 This line contains the formulas for the table directly above the line. | 7374 This line contains the formulas for the table directly above the line. |
6779 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS: | 7375 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS, #+DATE: |
6780 These lines provide settings for exporting files. For more details see | 7376 These lines provide settings for exporting files. For more details see |
6781 @ref{Export options}. | 7377 @ref{Export options}. |
6782 @item #+SEQ_TODO: #+TYP_TODO: | 7378 @item #+SEQ_TODO: #+TYP_TODO: |
6783 These lines set the TODO keywords and their interpretation in the | 7379 These lines set the TODO keywords and their interpretation in the |
6784 current file. The corresponding variables are @code{org-todo-keywords} | 7380 current file. The corresponding variables are @code{org-todo-keywords} |
6828 If the cursor is in a plain list item with a checkbox, toggle the status | 7424 If the cursor is in a plain list item with a checkbox, toggle the status |
6829 of the checkbox. | 7425 of the checkbox. |
6830 @item | 7426 @item |
6831 If the cursor is on a numbered item in a plain list, renumber the | 7427 If the cursor is on a numbered item in a plain list, renumber the |
6832 ordered list. | 7428 ordered list. |
7429 @item | |
7430 If the cursor is on the @code{#+BEGIN} line of a dynamical block, the | |
7431 block is updated. | |
6833 @end itemize | 7432 @end itemize |
6834 | 7433 |
6835 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous | 7434 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous |
6836 @section A cleaner outline view | 7435 @section A cleaner outline view |
6837 @cindex hiding leading stars | 7436 @cindex hiding leading stars |
6935 | 7534 |
6936 @node TTY keys, Interaction, Clean view, Miscellaneous | 7535 @node TTY keys, Interaction, Clean view, Miscellaneous |
6937 @section Using org-mode on a tty | 7536 @section Using org-mode on a tty |
6938 @cindex tty keybindings | 7537 @cindex tty keybindings |
6939 | 7538 |
6940 Org-mode uses a number of keys that are not accessible on a tty. This | 7539 Because Org-mode contains a large number of commands, by default much of |
6941 applies to most special keys like cursor keys, @key{TAB} and | 7540 Org-mode's core commands are bound to keys that are generally not |
6942 @key{RET}, when these are combined with modifier keys like @key{Meta} | 7541 accessible on a tty, such as the cursor keys (@key{left}, @key{right}, |
6943 and/or @key{Shift}. Org-mode uses these bindings because it needs to | 7542 @key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used |
6944 provide keys for a large number of commands, and because these keys | 7543 together with modifiers like @key{Meta} and/or @key{Shift}. To access |
6945 appeared particularly easy to remember. In order to still be able to | 7544 these commands on a tty when special keys are unavailable, the following |
6946 access the core functionality of Org-mode on a tty, alternative | 7545 alternative bindings can be used. The tty bindings below will likely be |
6947 bindings are provided. Here is a complete list of these bindings, | 7546 more cumbersome; you may find for some of the bindings below that a |
6948 which are obviously more cumbersome to use. Note that sometimes a | 7547 customized work-around suits you better. For example, changing a time |
6949 work-around can be better. For example changing a time stamp is | 7548 stamp is really only fun with @kbd{S-@key{cursor}} keys, whereas on a |
6950 really only fun with @kbd{S-@key{cursor}} keys. On a tty you would | 7549 tty you would rather use @kbd{C-c .} to re-insert the timestamp. |
6951 rather use @kbd{C-c .} to re-insert the timestamp. | |
6952 | 7550 |
6953 @multitable @columnfractions 0.15 0.2 0.2 | 7551 @multitable @columnfractions 0.15 0.2 0.2 |
6954 @item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2} | 7552 @item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2} |
6955 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab | 7553 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab |
6956 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}} | 7554 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}} |
7011 @file{constants.el}. | 7609 @file{constants.el}. |
7012 @item @file{cdlatex.el} by Carsten Dominik | 7610 @item @file{cdlatex.el} by Carsten Dominik |
7013 @cindex @file{cdlatex.el} | 7611 @cindex @file{cdlatex.el} |
7014 Org-mode can make use of the cdlatex package to efficiently enter | 7612 Org-mode can make use of the cdlatex package to efficiently enter |
7015 La@TeX{} fragments into Org-mode files. See @ref{CDLaTeX mode}. | 7613 La@TeX{} fragments into Org-mode files. See @ref{CDLaTeX mode}. |
7614 @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg | |
7615 @cindex @file{imenu.el} | |
7616 Imenu allows menu access to an index of items in a file. Org-mode | |
7617 supports imenu - all you need to do to get the index is the following: | |
7618 @lisp | |
7619 (add-hook 'org-mode-hook | |
7620 (lambda () 'imenu-add-to-menubar "Imenu")) | |
7621 @end lisp | |
7622 By default the index is two levels deep - you can modify the depth using | |
7623 the option @code{org-imenu-depth}. | |
7016 @item @file{remember.el} by John Wiegley | 7624 @item @file{remember.el} by John Wiegley |
7017 @cindex @file{remember.el} | 7625 @cindex @file{remember.el} |
7018 Org mode cooperates with remember, see @ref{Remember}. | 7626 Org mode cooperates with remember, see @ref{Remember}. |
7019 @file{Remember.el} is not part of Emacs, find it on the web. | 7627 @file{Remember.el} is not part of Emacs, find it on the web. |
7628 @item @file{speedbar.el} by Eric M. Ludlam | |
7629 @cindex @file{speedbar.el} | |
7630 Speedbar is a package that creates a special frame displaying files and | |
7631 index items in files. Org-mode supports speedbar and allows you to | |
7632 drill into Org-mode files directly from the speedbar. It also allows to | |
7633 restrict the scope of agenda commands to a file or a subtree by using | |
7634 the command @kbd{<} in the speedbar frame. | |
7020 @cindex @file{table.el} | 7635 @cindex @file{table.el} |
7021 @item @file{table.el} by Takaaki Ota | 7636 @item @file{table.el} by Takaaki Ota |
7022 @kindex C-c C-c | 7637 @kindex C-c C-c |
7023 @cindex table editor, @file{table.el} | 7638 @cindex table editor, @file{table.el} |
7024 @cindex @file{table.el} | 7639 @cindex @file{table.el} |
7068 is loaded @emph{before} @file{allout.el}, for example by putting | 7683 is loaded @emph{before} @file{allout.el}, for example by putting |
7069 @code{(require 'org)} early enough into your @file{.emacs} file. | 7684 @code{(require 'org)} early enough into your @file{.emacs} file. |
7070 | 7685 |
7071 @cindex @file{CUA.el} | 7686 @cindex @file{CUA.el} |
7072 @item @file{CUA.el} by Kim. F. Storm | 7687 @item @file{CUA.el} by Kim. F. Storm |
7073 Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys | 7688 Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys used by |
7074 used by CUA-mode (as well as pc-select-mode and s-region-mode) to | 7689 CUA-mode (as well as pc-select-mode and s-region-mode) to select and |
7075 select and extend the region. If you want to use one of these | 7690 extend the region. If you want to use one of these packages along with |
7076 packages along with Org-mode, configure the variable | 7691 Org-mode, configure the variable @code{org-replace-disputed-keys}. When |
7077 @code{org-CUA-compatible}. When set, Org-mode will move the following | 7692 set, Org-mode will move the following keybindings in Org-mode files, and |
7078 keybindings in Org-mode files, and in the agenda buffer (but not | 7693 in the agenda buffer (but not during date selection). |
7079 during date selection). | |
7080 | 7694 |
7081 @example | 7695 @example |
7082 S-UP -> M-p S-DOWN -> M-n | 7696 S-UP -> M-p S-DOWN -> M-n |
7083 S-LEFT -> M-- S-RIGHT -> M-+ | 7697 S-LEFT -> M-- S-RIGHT -> M-+ |
7084 @end example | 7698 @end example |
7195 blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}. | 7809 blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}. |
7196 @cindex @file{org2rem.el} | 7810 @cindex @file{org2rem.el} |
7197 @item @file{org2rem.el} by Bastien Guerry | 7811 @item @file{org2rem.el} by Bastien Guerry |
7198 Translates Org-mode files into something readable by | 7812 Translates Org-mode files into something readable by |
7199 Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. | 7813 Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. |
7814 @item @file{org-toc.el} by Bastien Guerry | |
7815 Produces a simple table of contents of an Org-mode file, for easy | |
7816 navigation. @url{http://www.cognition.ens.fr/~guerry/u/org-registry.el}. | |
7817 @item @file{org-registry.el} by Bastien Guerry | |
7818 Find which Org-file link to a certain document. | |
7819 @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. | |
7200 @end table | 7820 @end table |
7201 | 7821 |
7202 @page | 7822 @page |
7203 | 7823 |
7204 @node Adding hyperlink types, Tables in arbitrary syntax, Extensions, Extensions and Hacking | 7824 @node Adding hyperlink types, Tables in arbitrary syntax, Extensions, Extensions and Hacking |
7297 can also set the @code{:description} property to provide a default for | 7917 can also set the @code{:description} property to provide a default for |
7298 the link description when the link is later inserted into tan Org-mode | 7918 the link description when the link is later inserted into tan Org-mode |
7299 buffer with @kbd{C-c C-l}. | 7919 buffer with @kbd{C-c C-l}. |
7300 | 7920 |
7301 @node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Extensions and Hacking | 7921 @node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Extensions and Hacking |
7302 @section Tables in arbitrary syntax | 7922 @section Tables and Lists in arbitrary syntax |
7303 @cindex tables, in other modes | 7923 @cindex tables, in other modes |
7924 @cindex lists, in other modes | |
7304 @cindex orgtbl-mode | 7925 @cindex orgtbl-mode |
7305 | 7926 |
7306 Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a | 7927 Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a |
7307 frequent feature request has been to make it work with native tables in | 7928 frequent feature request has been to make it work with native tables in |
7308 specific languages, for example La@TeX{}. However, this is extremely hard | 7929 specific languages, for example La@TeX{}. However, this is extremely |
7309 to do in a general way, would lead to a customization nightmare, and | 7930 hard to do in a general way, would lead to a customization nightmare, |
7310 would take away much of the simplicity of the Orgtbl-mode table editor. | 7931 and would take away much of the simplicity of the Orgtbl-mode table |
7932 editor. | |
7933 | |
7311 | 7934 |
7312 This appendix describes a different approach. We keep the Orgtbl-mode | 7935 This appendix describes a different approach. We keep the Orgtbl-mode |
7313 table in its native format (the @i{source table}), and use a custom | 7936 table in its native format (the @i{source table}), and use a custom |
7314 function to @i{translate} the table to the correct syntax, and to | 7937 function to @i{translate} the table to the correct syntax, and to |
7315 @i{install} it in the right location (the @i{target table}). This puts | 7938 @i{install} it in the right location (the @i{target table}). This puts |
7316 the burden of writing conversion functions on the user, but it allows | 7939 the burden of writing conversion functions on the user, but it allows |
7317 for a very flexible system. | 7940 for a very flexible system. |
7318 | 7941 |
7942 Bastien added the ability to do the same with lists. You can use Org's | |
7943 facilities to edit and structure lists by turning @code{orgstruct-mode} | |
7944 on, then locally exporting such lists in another format (HTML, La@TeX{} | |
7945 or TeXInfo.) | |
7946 | |
7947 | |
7319 @menu | 7948 @menu |
7320 * Radio tables:: Sending and receiving | 7949 * Radio tables:: Sending and receiving |
7321 * A LaTeX example:: Step by step, almost a tutorial | 7950 * A LaTeX example:: Step by step, almost a tutorial |
7322 * Translator functions:: Copy and modify | 7951 * Translator functions:: Copy and modify |
7952 * Radio lists:: Doing the same for lists. | |
7323 @end menu | 7953 @end menu |
7324 | 7954 |
7325 @node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax | 7955 @node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax |
7326 @subsection Radio tables | 7956 @subsection Radio tables |
7327 @cindex radio tables | 7957 @cindex radio tables |
7386 make this comment-toggling very easy, in particular if you bind it to a | 8016 make this comment-toggling very easy, in particular if you bind it to a |
7387 key. | 8017 key. |
7388 @end itemize | 8018 @end itemize |
7389 | 8019 |
7390 @node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax | 8020 @node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax |
7391 @subsection A LaTeX example | 8021 @subsection A LaTeX example of radio tables |
7392 @cindex LaTeX, and orgtbl-mode | 8022 @cindex LaTeX, and orgtbl-mode |
7393 | 8023 |
7394 The best way to wrap the source table in La@TeX{} is to use the | 8024 The best way to wrap the source table in La@TeX{} is to use the |
7395 @code{comment} environment provided by @file{comment.sty}. It has to be | 8025 @code{comment} environment provided by @file{comment.sty}. It has to be |
7396 activated by placing @code{\usepackage@{comment@}} into the document | 8026 activated by placing @code{\usepackage@{comment@}} into the document |
7490 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After | 8120 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After |
7491 @code{efmt} has been applied to a value, @code{fmt} will also be | 8121 @code{efmt} has been applied to a value, @code{fmt} will also be |
7492 applied. | 8122 applied. |
7493 @end table | 8123 @end table |
7494 | 8124 |
7495 @node Translator functions, , A LaTeX example, Tables in arbitrary syntax | 8125 @node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax |
7496 @subsection Translator functions | 8126 @subsection Translator functions |
7497 @cindex HTML, and orgtbl-mode | 8127 @cindex HTML, and orgtbl-mode |
7498 @cindex translator function | 8128 @cindex translator function |
7499 | 8129 |
7500 Orgtbl-mode has several translator functions built-in: | 8130 Orgtbl-mode has several translator functions built-in: |
7563 @samp{#+ORGTBL: SEND} line. The function must return a single string | 8193 @samp{#+ORGTBL: SEND} line. The function must return a single string |
7564 containing the formatted table. If you write a generally useful | 8194 containing the formatted table. If you write a generally useful |
7565 translator, please post it on @code{emacs-orgmode@@gnu.org} so that | 8195 translator, please post it on @code{emacs-orgmode@@gnu.org} so that |
7566 others can benefit from your work. | 8196 others can benefit from your work. |
7567 | 8197 |
8198 @node Radio lists, , Translator functions, Tables in arbitrary syntax | |
8199 @subsection Radio lists | |
8200 @cindex radio lists | |
8201 @cindex org-list-insert-radio-list | |
8202 | |
8203 Sending and receiving radio lists works exactly the same way than | |
8204 sending and receiving radio tables (@pxref{Radio tables}) @footnote{You | |
8205 need to load the @code{org-export-latex.el} package to use radio lists | |
8206 since the relevant code is there for now.}. As for radio tables, you | |
8207 can insert radio lists templates in HTML, La@TeX{} and TeXInfo modes by | |
8208 calling @code{org-list-insert-radio-list}. | |
8209 | |
8210 Here are the differences with radio tables: | |
8211 | |
8212 @itemize @minus | |
8213 @item | |
8214 Use @code{ORGLST} instead of @code{ORGTBL}. | |
8215 @item | |
8216 The available translation functions for radio lists don't take | |
8217 parameters. | |
8218 @item | |
8219 `C-c C-c' will work when pressed on the first item of the list. | |
8220 @end itemize | |
8221 | |
8222 Here is a La@TeX{} example. Let's say that you have this in your | |
8223 La@TeX{} file: | |
8224 | |
8225 @example | |
8226 % BEGIN RECEIVE ORGLST to-buy | |
8227 % END RECEIVE ORGLST to-buy | |
8228 \begin@{comment@} | |
8229 #+ORGLIST: SEND to-buy orgtbl-to-latex | |
8230 - a new house | |
8231 - a new computer | |
8232 + a new keyboard | |
8233 + a new mouse | |
8234 - a new life | |
8235 \end@{comment@} | |
8236 @end example | |
8237 | |
8238 Pressing `C-c C-c' on @code{a new house} and will insert the converted | |
8239 La@TeX{} list between the two marker lines. | |
8240 | |
7568 @node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking | 8241 @node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking |
7569 @section Dynamic blocks | 8242 @section Dynamic blocks |
7570 @cindex dynamic blocks | 8243 @cindex dynamic blocks |
7571 | 8244 |
7572 Org-mode documents can contain @emph{dynamic blocks}. These are | 8245 Org-mode documents can contain @emph{dynamic blocks}. These are |
7649 | 8322 |
7650 @lisp | 8323 @lisp |
7651 (defun my-skip-unless-waiting () | 8324 (defun my-skip-unless-waiting () |
7652 "Skip trees that are not waiting" | 8325 "Skip trees that are not waiting" |
7653 (let ((subtree-end (save-excursion (org-end-of-subtree t)))) | 8326 (let ((subtree-end (save-excursion (org-end-of-subtree t)))) |
7654 (if (re-search-forward ":WAITING:" subtree-end t) | 8327 (if (re-search-forward ":waiting:" subtree-end t) |
7655 nil ; tag found, do not skip | 8328 nil ; tag found, do not skip |
7656 subtree-end))) ; tag not found, continue after end of subtree | 8329 subtree-end))) ; tag not found, continue after end of subtree |
7657 @end lisp | 8330 @end lisp |
7658 | 8331 |
7659 Now you may use this function in an agenda custom command, for example | 8332 Now you may use this function in an agenda custom command, for example |
7681 @item '(org-agenda-skip-entry-if 'deadline) | 8354 @item '(org-agenda-skip-entry-if 'deadline) |
7682 Skip current entry if it has a deadline. | 8355 Skip current entry if it has a deadline. |
7683 @item '(org-agenda-skip-entry-if 'scheduled 'deadline) | 8356 @item '(org-agenda-skip-entry-if 'scheduled 'deadline) |
7684 Skip current entry if it has a deadline, or if it is scheduled. | 8357 Skip current entry if it has a deadline, or if it is scheduled. |
7685 @item '(org-agenda-skip-entry 'regexp "regular expression") | 8358 @item '(org-agenda-skip-entry 'regexp "regular expression") |
7686 Skip current entry if the regular expression contained in the variable | 8359 Skip current entry if the regular expression matches in the entry. |
7687 @code{org-agenda-skip-regexp} matches in the entry. | 8360 @item '(org-agenda-skip-entry 'notregexp "regular expression") |
8361 Skip current entry unless the regular expression matches. | |
7688 @item '(org-agenda-skip-subtree-if 'regexp "regular expression") | 8362 @item '(org-agenda-skip-subtree-if 'regexp "regular expression") |
7689 Same as above, but check and skip the entire subtree. | 8363 Same as above, but check and skip the entire subtree. |
7690 @end table | 8364 @end table |
7691 | 8365 |
7692 Therefore we could also have written the search for WAITING projects | 8366 Therefore we could also have written the search for WAITING projects |
7694 | 8368 |
7695 @lisp | 8369 @lisp |
7696 (org-add-agenda-custom-command | 8370 (org-add-agenda-custom-command |
7697 '("b" todo "PROJECT" | 8371 '("b" todo "PROJECT" |
7698 ((org-agenda-skip-function '(org-agenda-skip-subtree-if | 8372 ((org-agenda-skip-function '(org-agenda-skip-subtree-if |
7699 'regexp ":WAITING:")) | 8373 'regexp ":waiting:")) |
7700 (org-agenda-overriding-header "Projects waiting for something: ")))) | 8374 (org-agenda-overriding-header "Projects waiting for something: ")))) |
7701 @end lisp | 8375 @end lisp |
7702 | 8376 |
7703 | 8377 |
7704 @node Using the property API, , Special agenda views, Extensions and Hacking | 8378 @node Using the property API, , Special agenda views, Extensions and Hacking |
7720 `special' or `standard', only get that subclass. | 8394 `special' or `standard', only get that subclass. |
7721 @end defun | 8395 @end defun |
7722 @defun org-entry-get pom property &optional inherit | 8396 @defun org-entry-get pom property &optional inherit |
7723 Get value of PROPERTY for entry at point-or-marker POM. | 8397 Get value of PROPERTY for entry at point-or-marker POM. |
7724 If INHERIT is non-nil and the entry does not have the property, | 8398 If INHERIT is non-nil and the entry does not have the property, |
7725 then also check higher levels of the hierarchy. | 8399 then also check higher levels of the hierarchy. This function ignores |
8400 the value of @code{org-use-property-inheritance} and requires the | |
8401 explicit INHERIT flag. | |
7726 @end defun | 8402 @end defun |
7727 | 8403 |
7728 @defun org-entry-delete pom property | 8404 @defun org-entry-delete pom property |
7729 Delete the property PROPERTY from entry at point-or-marker POM. | 8405 Delete the property PROPERTY from entry at point-or-marker POM. |
7730 @end defun | 8406 @end defun |
7739 | 8415 |
7740 @defun org-insert-property-drawer | 8416 @defun org-insert-property-drawer |
7741 Insert a property drawer at point. | 8417 Insert a property drawer at point. |
7742 @end defun | 8418 @end defun |
7743 | 8419 |
7744 @node History and Acknowledgments, Index, Extensions and Hacking, Top | 8420 @node History and Acknowledgments, Main Index, Extensions and Hacking, Top |
7745 @appendix History and Acknowledgments | 8421 @appendix History and Acknowledgments |
7746 @cindex acknowledgments | 8422 @cindex acknowledgments |
7747 @cindex history | 8423 @cindex history |
7748 @cindex thanks | 8424 @cindex thanks |
7749 | 8425 |
7812 @i{Nic Ferrier} contributed mailcap and XOXO support. | 8488 @i{Nic Ferrier} contributed mailcap and XOXO support. |
7813 @item | 8489 @item |
7814 @i{John Foerch} figured out how to make incremental search show context | 8490 @i{John Foerch} figured out how to make incremental search show context |
7815 around a match in a hidden outline tree. | 8491 around a match in a hidden outline tree. |
7816 @item | 8492 @item |
7817 @i{Niels Giessen} had the idea to automatically archive DONE trees. | 8493 @i{Niels Giesen} had the idea to automatically archive DONE trees. |
7818 @item | 8494 @item |
7819 @i{Bastien Guerry} wrote the La@TeX{} exporter and has been prolific | 8495 @i{Bastien Guerry} wrote the La@TeX{} exporter and has been prolific |
7820 with patches, ideas, and bug reports. | 8496 with patches, ideas, and bug reports. |
7821 to Org-mode. | |
7822 @item | 8497 @item |
7823 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages. | 8498 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages. |
7824 @item | 8499 @item |
7825 @i{Scott Jaderholm} proposed footnotes, control over whitespace between | 8500 @i{Scott Jaderholm} proposed footnotes, control over whitespace between |
7826 folded entries, and column view for properties. | 8501 folded entries, and column view for properties. |
7828 @i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also | 8503 @i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also |
7829 provided frequent feedback and some patches. | 8504 provided frequent feedback and some patches. |
7830 @item | 8505 @item |
7831 @i{Jason F. McBrayer} suggested agenda export to CSV format. | 8506 @i{Jason F. McBrayer} suggested agenda export to CSV format. |
7832 @item | 8507 @item |
8508 @i{Max Mikhanosha} came up with the idea of refiling. | |
8509 @item | |
7833 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file | 8510 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file |
7834 basis. | 8511 basis. |
7835 @item | 8512 @item |
7836 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler | 8513 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler |
7837 happy. | 8514 happy. |
7838 @item | 8515 @item |
7839 @i{Rick Moynihan} proposed to allow multiple TODO sequences in a file. | 8516 @i{Rick Moynihan} proposed to allow multiple TODO sequences in a file |
8517 and to be able to quickly restrict the agenda to a subtree. | |
7840 @item | 8518 @item |
7841 @i{Todd Neal} provided patches for links to Info files and elisp forms. | 8519 @i{Todd Neal} provided patches for links to Info files and elisp forms. |
7842 @item | 8520 @item |
7843 @i{Tim O'Callaghan} suggested in-file links, search options for general | 8521 @i{Tim O'Callaghan} suggested in-file links, search options for general |
7844 file links, and TAGS. | 8522 file links, and TAGS. |
7912 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks | 8590 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks |
7913 and contributed various ideas and code snippets. | 8591 and contributed various ideas and code snippets. |
7914 @end itemize | 8592 @end itemize |
7915 | 8593 |
7916 | 8594 |
7917 @node Index, Key Index, History and Acknowledgments, Top | 8595 @node Main Index, Key Index, History and Acknowledgments, Top |
7918 @unnumbered Index | 8596 @unnumbered The Main Index |
7919 | 8597 |
7920 @printindex cp | 8598 @printindex cp |
7921 | 8599 |
7922 @node Key Index, , Index, Top | 8600 @node Key Index, , Main Index, Top |
7923 @unnumbered Key Index | 8601 @unnumbered Key Index |
7924 | 8602 |
7925 @printindex ky | 8603 @printindex ky |
7926 | 8604 |
7927 @bye | 8605 @bye |