org-guide.org (83188B)
1 #+title: Org Mode Compact Guide 2 #+subtitle: Release {{{version}}} 3 #+author: The Org Mode Developers 4 #+language: en 5 6 #+texinfo: @insertcopying 7 8 * Copying 9 :PROPERTIES: 10 :copying: t 11 :END: 12 13 Copyright \copy 2004--2023 Free Software Foundation, Inc. 14 15 #+begin_quote 16 Permission is granted to copy, distribute and/or modify this document 17 under the terms of the GNU Free Documentation License, Version 1.3 or 18 any later version published by the Free Software Foundation; with no 19 Invariant Sections, with the Front-Cover Texts being "A GNU Manual," 20 and with the Back-Cover Texts as in (a) below. A copy of the license 21 is included in the section entitled "GNU Free Documentation License." 22 in the full Org manual, which is distributed together with this 23 compact guide. 24 25 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and 26 modify this GNU manual." 27 #+end_quote 28 29 * Introduction 30 :PROPERTIES: 31 :DESCRIPTION: Welcome! 32 :END: 33 34 Org is a mode for keeping notes, maintaining TODO lists, and doing 35 project planning with a fast and effective plain-text system. It is 36 also an authoring and publishing system, and it supports working with 37 source code for literal programming and reproducible research. 38 39 This document is a much compressed derivative of the [[info:org][comprehensive Org 40 mode manual]]. It contains all basic features and commands, along with 41 important hints for customization. It is intended for beginners who 42 would shy back from a 200 pages manual because of sheer size. 43 44 ** Installation 45 :PROPERTIES: 46 :UNNUMBERED: notoc 47 :END: 48 49 #+attr_texinfo: :tag Important 50 #+begin_quote 51 If you are using a version of Org that is part of the Emacs 52 distribution, please skip this section and go directly to [[*Activation]]. 53 #+end_quote 54 55 If you have downloaded Org from the web, either as a distribution 56 =.zip= or =.tar= file, or as a Git archive, it is best to run it 57 directly from the distribution directory. You need to add the =lisp/= 58 subdirectories to the Emacs load path. To do this, add the following 59 line to your Emacs init file: 60 61 : (add-to-list 'load-path "~/path/to/orgdir/lisp") 62 63 #+texinfo: @noindent 64 If you have been using git or a tar ball to get Org, you need to run 65 the following command to generate autoload information. 66 67 : make autoloads 68 69 ** Activation 70 :PROPERTIES: 71 :UNNUMBERED: notoc 72 :END: 73 74 Add the following lines to your Emacs init file to define /global/ 75 keys for three commands that are useful in any Emacs buffer, not just 76 Org buffers. Please choose suitable keys yourself. 77 78 #+begin_src emacs-lisp 79 (global-set-key (kbd "C-c l") #'org-store-link) 80 (global-set-key (kbd "C-c a") #'org-agenda) 81 (global-set-key (kbd "C-c c") #'org-capture) 82 #+end_src 83 84 Files with extension =.org= will be put into Org mode automatically. 85 86 ** Feedback 87 :PROPERTIES: 88 :UNNUMBERED: notoc 89 :END: 90 91 If you find problems with Org, or if you have questions, remarks, or 92 ideas about it, please mail to the Org mailing list 93 mailto:emacs-orgmode@gnu.org. For information on how to submit bug 94 reports, see the main manual. 95 96 * Document Structure 97 :PROPERTIES: 98 :DESCRIPTION: A tree works like your brain. 99 :END: 100 101 Org is an outliner. Outlines allow a document to be organized in 102 a hierarchical structure, which, least for me, is the best 103 representation of notes and thoughts. An overview of this structure 104 is achieved by folding, i.e., hiding large parts of the document to 105 show only the general document structure and the parts currently being 106 worked on. Org greatly simplifies the use of outlines by compressing 107 the entire show and hide functionalities into a single command, 108 ~org-cycle~, which is bound to the {{{kbd(TAB)}}} key. 109 110 ** Headlines 111 :PROPERTIES: 112 :DESCRIPTION: How to typeset Org tree nodes. 113 :END: 114 115 Headlines define the structure of an outline tree. The headlines in 116 Org start on the left margin[fn:1] with one or more stars followed by 117 a space. For example: 118 119 #+begin_example 120 ,* Top level headline 121 ,** Second level 122 ,*** Third level 123 some text 124 ,*** Third level 125 more text 126 ,* Another top level headline 127 #+end_example 128 129 Note that a headline named after ~org-footnote-section~, which 130 defaults to =Footnotes=, is considered as special. A subtree with 131 this headline will be silently ignored by exporting functions. 132 133 Some people find the many stars too noisy and would prefer an outline 134 that has whitespace followed by a single star as headline starters. 135 See [[*Miscellaneous]] for a setup to realize this. 136 137 ** Visibility Cycling 138 :PROPERTIES: 139 :DESCRIPTION: Show and hide, much simplified. 140 :END: 141 142 Outlines make it possible to hide parts of the text in the buffer. 143 Org uses just two commands, bound to {{{kbd(TAB)}}} and 144 {{{kbd(S-TAB)}}} to change the visibility in the buffer. 145 146 #+attr_texinfo: :sep , 147 - {{{kbd(TAB)}}} :: 148 149 /Subtree cycling/: Rotate current subtree among the states 150 151 : ,-> FOLDED -> CHILDREN -> SUBTREE --. 152 : '-----------------------------------' 153 154 When called with a prefix argument ({{{kbd(C-u TAB)}}}), or with the 155 Shift key, global cycling is invoked. 156 157 - {{{kbd(S-TAB)}}}, {{{kbd(C-u TAB)}}} :: 158 159 /Global cycling/: Rotate the entire buffer among the states 160 161 : ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. 162 : '--------------------------------------' 163 164 - {{{kbd(C-u C-u C-u TAB)}}} :: 165 166 Show all, including drawers. 167 168 When Emacs first visits an Org file, the global state is set to 169 OVERVIEW, i.e., only the top level headlines are visible. This can be 170 configured through the variable ~org-startup-folded~, or on a per-file 171 basis by adding a =STARTUP= keyword to =overview=, =content=, 172 =showall=, =showeverything= or =show<n>levels= (n = 2..5) like this: 173 174 : #+STARTUP: content 175 176 ** Motion 177 :PROPERTIES: 178 :DESCRIPTION: Jumping to other headlines. 179 :END: 180 181 The following commands jump to other headlines in the buffer. 182 183 - {{{kbd(C-c C-n)}}} :: Next heading. 184 185 - {{{kbd(C-c C-p)}}} :: Previous heading. 186 187 - {{{kbd(C-c C-f)}}} :: Next heading same level. 188 189 - {{{kbd(C-c C-b)}}} :: Previous heading same level. 190 191 - {{{kbd(C-c C-u)}}} :: Backward to higher level heading. 192 193 ** Structure Editing 194 :PROPERTIES: 195 :DESCRIPTION: Changing sequence and level of headlines. 196 :END: 197 198 #+attr_texinfo: :sep , 199 - {{{kbd(M-RET)}}} :: 200 201 Insert new heading with same level as current. If point is in 202 a plain list item, a new item is created (see [[Plain Lists]]). When 203 this command is used in the middle of a line, the line is split and 204 the rest of the line becomes the new headline[fn:2]. 205 206 - {{{kbd(M-S-RET)}}} :: 207 208 Insert new TODO entry with same level as current heading. 209 210 - {{{kbd(TAB)}}} in new, empty entry :: 211 212 In a new entry with no text yet, {{{kbd(TAB)}}} cycles through 213 reasonable levels. 214 215 - {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: 216 217 Promote or demote current heading by one level. 218 219 - {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} :: 220 221 Move subtree up or down, i.e., swap with previous or next subtree of 222 same level. 223 224 - {{{kbd(C-c C-w)}}} :: 225 226 Refile entry or region to a different location. See [[*Refile and 227 Copy]]. 228 229 - {{{kbd(C-x n s)}}}, {{{kbd(C-x n w)}}} :: 230 231 Narrow buffer to current subtree and widen it again. 232 233 When there is an active region (Transient Mark mode), promotion and 234 demotion work on all headlines in the region. 235 236 ** Sparse Trees 237 :PROPERTIES: 238 :DESCRIPTION: Matches embedded in context. 239 :END: 240 241 An important feature of Org mode is the ability to construct /sparse 242 trees/ for selected information in an outline tree, so that the entire 243 document is folded as much as possible, but the selected information 244 is made visible along with the headline structure above it[fn:3]. 245 Just try it out and you will see immediately how it works. 246 247 Org mode contains several commands creating such trees, all these 248 commands can be accessed through a dispatcher: 249 250 - {{{kbd(C-c /)}}} :: 251 252 This prompts for an extra key to select a sparse-tree creating 253 command. 254 255 - {{{kbd(C-c / r)}}} :: 256 257 Occur. Prompts for a regexp and shows a sparse tree with all 258 matches. Each match is also highlighted; the highlights disappear 259 by pressing {{{kbd(C-c C-c)}}}. 260 261 The other sparse tree commands select headings based on TODO 262 keywords, tags, or properties and will be discussed later in this 263 manual. 264 265 ** Plain Lists 266 :PROPERTIES: 267 :DESCRIPTION: Additional structure within an entry. 268 :END: 269 270 Within an entry of the outline tree, hand-formatted lists can provide 271 additional structure. They also provide a way to create lists of 272 checkboxes (see [[*Checkboxes]]). Org supports editing such lists, and 273 every exporter (see [[*Exporting]]) can parse and format them. 274 275 Org knows ordered lists, unordered lists, and description lists. 276 277 #+attr_texinfo: :indic @bullet 278 - /Unordered/ list items start with =-=, =+=, or =*= as bullets. 279 280 - /Ordered/ list items start with =1.=, or =1)=. 281 282 - /Description/ list use =::= to separate the /term/ from the 283 description. 284 285 Items belonging to the same list must have the same indentation on the 286 first line. An item ends before the next line that is indented like 287 its bullet/number, or less. A list ends when all items are closed, or 288 before two blank lines. An example: 289 290 #+begin_example 291 ,* Lord of the Rings 292 My favorite scenes are (in this order) 293 1. The attack of the Rohirrim 294 2. Eowyn's fight with the witch king 295 + this was already my favorite scene in the book 296 + I really like Miranda Otto. 297 Important actors in this film are: 298 - Elijah Wood :: He plays Frodo 299 - Sean Astin :: He plays Sam, Frodo's friend. 300 #+end_example 301 302 The following commands act on items when point is in the first line of 303 an item (the line with the bullet or number). 304 305 #+attr_texinfo: :sep , 306 - {{{kbd(TAB)}}} :: 307 308 Items can be folded just like headline levels. 309 310 - {{{kbd(M-RET)}}} :: 311 312 Insert new item at current level. With a prefix argument, force 313 a new heading (see [[*Structure Editing]]). 314 315 - {{{kbd(M-S-RET)}}} :: 316 317 Insert a new item with a checkbox (see [[*Checkboxes]]). 318 319 - {{{kbd(M-S-UP)}}}, {{{kbd(M-S-DOWN)}}} :: 320 321 Move the item including subitems up/down (swap with previous/next 322 item of same indentation). If the list is ordered, renumbering is 323 automatic. 324 325 - {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: 326 327 Decrease/increase the indentation of an item, leaving children 328 alone. 329 330 - {{{kbd(M-S-LEFT)}}}, {{{kbd(M-S-RIGHT)}}} :: 331 332 Decrease/increase the indentation of the item, including subitems. 333 334 - {{{kbd(C-c C-c)}}} :: 335 336 If there is a checkbox (see [[*Checkboxes]]) in the item line, toggle 337 the state of the checkbox. Also verify bullets and indentation 338 consistency in the whole list. 339 340 - {{{kbd(C-c -)}}} :: 341 342 Cycle the entire list level through the different itemize/enumerate 343 bullets (=-=, =+=, =*=, =1.=, =1)=). 344 345 * Tables 346 :PROPERTIES: 347 :DESCRIPTION: Pure magic for quick formatting. 348 :END: 349 350 Org comes with a fast and intuitive table editor. Spreadsheet-like 351 calculations are supported in connection with the Emacs Calc package 352 (see [[info:calc][GNU Emacs Calculator Manual]]). 353 354 Org makes it easy to format tables in plain ASCII. Any line with =|= 355 as the first non-whitespace character is considered part of a table. 356 =|= is also the column separator. A table might look like this: 357 358 #+begin_example 359 | Name | Phone | Age | 360 |-------+-------+-----| 361 | Peter | 1234 | 17 | 362 | Anna | 4321 | 25 | 363 #+end_example 364 365 A table is re-aligned automatically each time you press {{{kbd(TAB)}}} 366 or {{{kbd(RET)}}} or {{{kbd(C-c C-c)}}} inside the table. 367 {{{kbd(TAB)}}} also moves to the next field ({{{kbd(RET)}}} to the 368 next row) and creates new table rows at the end of the table or before 369 horizontal lines. The indentation of the table is set by the first 370 line. Any line starting with =|-= is considered as a horizontal 371 separator line and will be expanded on the next re-align to span the 372 whole table width. So, to create the above table, you would only type 373 374 : |Name|Phone|Age| 375 : |- 376 377 #+texinfo: @noindent 378 and then press {{{kbd(TAB)}}} to align the table and start filling in 379 fields. Even faster would be to type =|Name|Phone|Age= followed by 380 {{{kbd(C-c RET)}}}. 381 382 When typing text into a field, Org treats {{{kbd(DEL)}}}, 383 {{{kbd(Backspace)}}}, and all character keys in a special way, so that 384 inserting and deleting avoids shifting other fields. Also, when 385 typing /immediately after point was moved into a new field with 386 {{{kbd(TAB)}}}, {{{kbd(S-TAB)}}} or {{{kbd(RET)}}}/, the field is 387 automatically made blank. 388 389 ** Creation and conversion 390 :PROPERTIES: 391 :UNNUMBERED: notoc 392 :END: 393 394 - {{{kbd(C-c |)}}} :: 395 396 Convert the active region to table. If every line contains at least 397 one {{{kbd(TAB)}}} character, the function assumes that the material 398 is tab separated. If every line contains a comma, comma-separated 399 values (CSV) are assumed. If not, lines are split at whitespace 400 into fields. 401 402 If there is no active region, this command creates an empty Org 403 table. But it is easier just to start typing, like {{{kbd(| 404 N a m e | P h o n e | A g e RET | - TAB)}}}. 405 406 ** Re-aligning and field motion 407 :PROPERTIES: 408 :UNNUMBERED: notoc 409 :END: 410 411 #+attr_texinfo: :sep , 412 - {{{kbd(C-c C-c)}}} :: 413 414 Re-align the table without moving point. 415 416 - {{{kbd(TAB)}}} :: 417 418 Re-align the table, move to the next field. Creates a new row if 419 necessary. 420 421 - {{{kbd(S-TAB)}}} :: 422 423 Re-align, move to previous field. 424 425 - {{{kbd(RET)}}} :: 426 427 Re-align the table and move down to next row. Creates a new row if 428 necessary. 429 430 - {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}}, {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} :: 431 432 Move a cell up, down, left, and right by swapping with adjacent 433 cell. 434 435 ** Column and row editing 436 :PROPERTIES: 437 :UNNUMBERED: notoc 438 :END: 439 440 - {{{kbd(M-LEFT)}}}, {{{kbd(M-RIGHT)}}} :: 441 442 Move the current column left/right. 443 444 - {{{kbd(M-S-LEFT)}}} :: 445 446 Kill the current column. 447 448 - {{{kbd(M-S-RIGHT)}}} :: 449 450 Insert a new column to the left of point position. 451 452 - {{{kbd(M-UP)}}}, {{{kbd(M-DOWN)}}} :: 453 454 Move the current row up/down. 455 456 - {{{kbd(M-S-UP)}}} :: 457 458 Kill the current row or horizontal line. 459 460 - {{{kbd(M-S-DOWN)}}} :: 461 462 Insert a new row above the current row. With a prefix argument, the 463 line is created below the current one. 464 465 - {{{kbd(C-c -)}}} :: 466 467 Insert a horizontal line below current row. With a prefix argument, 468 the line is created above the current line. 469 470 - {{{kbd(C-c RET)}}} :: 471 472 Insert a horizontal line below current row, and move the point into 473 the row below that line. 474 475 - {{{kbd(C-c ^)}}} :: 476 477 Sort the table lines in the region. The position of point indicates 478 the column to be used for sorting, and the range of lines is the 479 range between the nearest horizontal separator lines, or the entire 480 table. 481 482 * Hyperlinks 483 :PROPERTIES: 484 :DESCRIPTION: Notes in context. 485 :END: 486 487 Like HTML, Org provides links inside a file, external links to other 488 files, Usenet articles, emails, and much more. 489 490 Org recognizes plain URIs, possibly wrapped within angle brackets, and 491 activate them as clickable links. The general link format, however, 492 looks like this: 493 494 : [[LINK][DESCRIPTION]] 495 496 #+texinfo: @noindent 497 or alternatively 498 499 : [[LINK]] 500 501 Once a link in the buffer is complete, with all brackets present, Org 502 changes the display so that =DESCRIPTION= is displayed instead of 503 =[[LINK][DESCRIPTION]]= and =LINK= is displayed instead of =[[LINK]]=. 504 To edit the invisible {{{var(LINK)}}} part, use {{{kbd(C-c C-l)}}} 505 with the point on the link. 506 507 ** Internal links 508 :PROPERTIES: 509 :UNNUMBERED: notoc 510 :END: 511 512 If the link does not look like a URL, it is considered to be internal 513 in the current file. The most important case is a link like 514 =[[#my-custom-id]]= which links to the entry with the =CUSTOM_ID= property 515 =my-custom-id=. 516 517 Links such as =[[My Target]]= or =[[My Target][Find my target]]= lead 518 to a text search in the current file for the corresponding target, 519 which looks like =<<My Target>>=. 520 521 ** External Links 522 :PROPERTIES: 523 :UNNUMBERED: notoc 524 :END: 525 526 Org supports links to files, websites, Usenet and email messages, BBDB 527 database entries and links to both IRC conversations and their logs. 528 External links are URL-like locators. They start with a short 529 identifying string followed by a colon. There can be no space after 530 the colon. Here are some examples: 531 532 | =http://www.astro.uva.nl/=dominik= | on the web | 533 | =file:/home/dominik/images/jupiter.jpg= | file, absolute path | 534 | =/home/dominik/images/jupiter.jpg= | same as above | 535 | =file:papers/last.pdf= | file, relative path | 536 | =./papers/last.pdf= | same as above | 537 | =file:projects.org= | another Org file | 538 | =docview:papers/last.pdf::NNN= | open in DocView mode at page {{{var(NNN)}}} | 539 | =id:B7423F4D-2E8A-471B-8810-C40F074717E9= | link to heading by ID | 540 | =news:comp.emacs= | Usenet link | 541 | =mailto:adent@galaxy.net= | mail link | 542 | =mhe:folder#id= | MH-E message link | 543 | =rmail:folder#id= | Rmail message link | 544 | =gnus:group#id= | Gnus article link | 545 | =bbdb:R.*Stallman= | BBDB link (with regexp) | 546 | =irc:/irc.com/#emacs/bob= | IRC link | 547 | =info:org#Hyperlinks= | Info node link | 548 549 File links can contain additional information to make Emacs jump to 550 a particular location in the file when following a link. This can be 551 a line number or a search option after a double colon. Here are a few 552 examples,, together with an explanation: 553 554 | =file:~/code/main.c::255= | Find line 255 | 555 | =file:~/xx.org::My Target= | Find =<<My Target>>= | 556 | =[[file:~/xx.org::#my-custom-id]]= | Find entry with a custom ID | 557 558 ** Handling Links 559 :PROPERTIES: 560 :UNNUMBERED: notoc 561 :END: 562 563 Org provides methods to create a link in the correct syntax, to insert 564 it into an Org file, and to follow the link. 565 566 The main function is ~org-store-link~, called with {{{kbd(M-x 567 org-store-link)}}}. Because of its importance, we suggest to bind it 568 to a widely available key (see [[*Activation]]). It stores a link to the 569 current location. The link is stored for later insertion into an Org 570 buffer---see below. 571 572 From an Org buffer, the following commands create, navigate or, more 573 generally, act on links. 574 575 #+attr_texinfo: :sep , 576 - {{{kbd(C-c C-l)}}} :: 577 578 Insert a link. This prompts for a link to be inserted into the 579 buffer. You can just type a link, or use history keys {{{kbd(UP)}}} 580 and {{{kbd(DOWN)}}} to access stored links. You will be prompted 581 for the description part of the link. 582 583 When called with a {{{kbd(C-u)}}} prefix argument, file name 584 completion is used to link to a file. 585 586 - {{{kbd(C-c C-l)}}} (with point on existing link) :: 587 588 When point is on an existing link, {{{kbd(C-c C-l)}}} allows you to 589 edit the link and description parts of the link. 590 591 - {{{kbd(C-c C-o)}}} :: 592 593 Open link at point. 594 595 - {{{kbd(C-c &)}}} :: 596 597 Jump back to a recorded position. A position is recorded by the 598 commands following internal links, and by {{{kbd(C-c %)}}}. Using 599 this command several times in direct succession moves through a ring 600 of previously recorded positions. 601 602 * TODO Items 603 :PROPERTIES: 604 :DESCRIPTION: Every tree branch can be a TODO item. 605 :END: 606 607 Org mode does not require TODO lists to live in separate documents. 608 Instead, TODO items are part of a notes file, because TODO items 609 usually come up while taking notes! With Org mode, simply mark any 610 entry in a tree as being a TODO item. In this way, information is not 611 duplicated, and TODO items remain in the context from which they 612 emerged. 613 614 Org mode provides methods to give you an overview of all the things 615 that you have to do, collected from many files. 616 617 ** Basic TODO Functionality 618 :PROPERTIES: 619 :DESCRIPTION: Marking and displaying TODO entries. 620 :ALT_TITLE: TODO Basics 621 :END: 622 623 Any headline becomes a TODO item when it starts with the word =TODO=, 624 for example: 625 626 : *** TODO Write letter to Sam Fortune 627 628 The most important commands to work with TODO entries are: 629 630 #+attr_texinfo: :sep , 631 - {{{kbd(C-c C-t)}}} :: 632 633 Rotate the TODO state of the current item among 634 635 : ,-> (unmarked) -> TODO -> DONE --. 636 : '--------------------------------' 637 638 The same rotation can also be done "remotely" from the agenda buffer 639 with the {{{kbd(t)}}} command key (see [[*Commands in the Agenda 640 Buffer]]). 641 642 - {{{kbd(S-RIGHT)}}}, {{{kbd(S-LEFT)}}} :: 643 644 Select the following/preceding TODO state, similar to cycling. 645 646 - {{{kbd(C-c / t)}}} :: 647 648 View TODO items in a /sparse tree/ (see [[*Sparse Trees]]). Folds the 649 entire buffer, but shows all TODO items---with not-DONE state---and 650 the headings hierarchy above them. 651 652 - {{{kbd(M-x org-agenda t)}}} :: 653 654 Show the global TODO list. Collects the TODO items (with not-DONE 655 states) from all agenda files (see [[*Agenda Views]]) into a single 656 buffer. See [[*The Global TODO List]], for more information. 657 658 - {{{kbd(S-M-RET)}}} :: 659 660 Insert a new TODO entry below the current one. 661 662 Changing a TODO state can also trigger tag changes. See the docstring 663 of the option ~org-todo-state-tags-triggers~ for details. 664 665 ** Multi-state Workflow 666 :PROPERTIES: 667 :DESCRIPTION: More than just on/off. 668 :END: 669 670 You can use TODO keywords to indicate /sequential/ working progress 671 states: 672 673 #+begin_src emacs-lisp 674 (setq org-todo-keywords 675 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) 676 #+end_src 677 678 #+texinfo: @noindent 679 The vertical bar separates the =TODO= keywords (states that /need 680 action/) from the =DONE= states (which need /no further action/). If 681 you do not provide the separator bar, the last state is used as the 682 =DONE= state. With this setup, the command {{{kbd(C-c C-t)}}} cycles 683 an entry from =TODO= to =FEEDBACK=, then to =VERIFY=, and finally to 684 =DONE= and =DELEGATED=. 685 686 Sometimes you may want to use different sets of TODO keywords in 687 parallel. For example, you may want to have the basic =TODO=/=DONE=, 688 but also a workflow for bug fixing. Your setup would then look like 689 this: 690 691 #+begin_src emacs-lisp 692 (setq org-todo-keywords 693 '((sequence "TODO(t)" "|" "DONE(d)") 694 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)"))) 695 #+end_src 696 697 #+texinfo: @noindent 698 The keywords should all be different, this helps Org mode to keep 699 track of which subsequence should be used for a given entry. The 700 example also shows how to define keys for fast access of a particular 701 state, by adding a letter in parenthesis after each keyword---you will 702 be prompted for the key after {{{kbd(C-c C-t)}}}. 703 704 To define TODO keywords that are valid only in a single file, use the 705 following text anywhere in the file. 706 707 #+begin_example 708 ,#+TODO: TODO(t) | DONE(d) 709 ,#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) 710 ,#+TODO: | CANCELED(c) 711 #+end_example 712 713 After changing one of these lines, use {{{kbd(C-c C-c)}}} with the 714 cursor still in the line to make the changes known to Org mode. 715 716 ** Progress Logging 717 :PROPERTIES: 718 :DESCRIPTION: Dates and notes for progress. 719 :END: 720 721 To record a timestamp and a note when changing a TODO state, call the 722 command ~org-todo~ with a prefix argument. 723 724 #+attr_texinfo: :sep , 725 - {{{kbd(C-u C-c C-t)}}} :: 726 Prompt for a note and record a the time of the TODO state change. 727 728 Org mode can also automatically record a timestamp and optionally a 729 note when you mark a TODO item as DONE, or even each time you change 730 the state of a TODO item. This system is highly configurable, 731 settings can be on a per-keyword basis and can be localized to a file 732 or even a subtree. For information on how to clock working time for a 733 task, see [[*Clocking Work Time]]. 734 735 *** Closing items 736 :PROPERTIES: 737 :UNNUMBERED: notoc 738 :END: 739 740 The most basic logging is to keep track of /when/ a certain TODO item 741 was marked as done. This can be achieved with[fn:4] 742 743 #+begin_src emacs-lisp 744 (setq org-log-done 'time) 745 #+end_src 746 747 #+texinfo: @noindent 748 Then each time you turn an entry from a TODO (not-done) state into any 749 of the DONE states, a line =CLOSED: [timestamp]= is inserted just 750 after the headline. 751 752 If you want to record a note along with the timestamp, use[fn:5] 753 754 #+begin_src emacs-lisp 755 (setq org-log-done 'note) 756 #+end_src 757 758 #+texinfo: @noindent 759 You are then be prompted for a note, and that note is stored below the 760 entry with a =Closing Note= heading. 761 762 *** Tracking TODO state changes 763 :PROPERTIES: 764 :UNNUMBERED: notoc 765 :END: 766 767 You might want to keep track of TODO state changes. You can either 768 record just a timestamp, or a time-stamped note for a change. These 769 records are inserted after the headline as an itemized list. When 770 taking a lot of notes, you might want to get the notes out of the way 771 into a drawer. Customize the variable ~org-log-into-drawer~ to get 772 this behavior. 773 774 For state logging, Org mode expects configuration on a per-keyword 775 basis. This is achieved by adding special markers =!= (for 776 a timestamp) and =@= (for a note) in parentheses after each keyword. 777 For example: 778 779 : #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@) 780 781 #+texinfo: @noindent 782 defines TODO keywords and fast access keys, and also request that 783 a time is recorded when the entry is set to =DONE=, and that a note is 784 recorded when switching to =WAIT= or =CANCELED=. The same syntax 785 works also when setting ~org-todo-keywords~. 786 787 ** Priorities 788 :PROPERTIES: 789 :DESCRIPTION: Some things are more important than others. 790 :END: 791 792 If you use Org mode extensively, you may end up with enough TODO items 793 that it starts to make sense to prioritize them. Prioritizing can be 794 done by placing a /priority cookie/ into the headline of a TODO item, 795 like this 796 797 : *** TODO [#A] Write letter to Sam Fortune 798 799 Org mode supports three priorities: =A=, =B=, and =C=. =A= is the 800 highest, =B= the default if none is given. Priorities make 801 a difference only in the agenda. 802 803 #+attr_texinfo: :sep ; 804 - {{{kbd(C-c \,)}}} :: 805 806 Set the priority of the current headline. Press {{{kbd(A)}}}, 807 {{{kbd(B)}}} or {{{kbd(C)}}} to select a priority, or {{{kbd(SPC)}}} 808 to remove the cookie. 809 810 - {{{kbd(S-UP)}}} (~org-priority-up~); {{{kbd(S-DOWN)}}} (~org-priority-down~) :: 811 812 Increase/decrease the priority of the current headline. 813 814 ** Breaking Tasks Down into Subtasks 815 :PROPERTIES: 816 :DESCRIPTION: Splitting a task into manageable pieces. 817 :ALT_TITLE: Breaking Down Tasks 818 :END: 819 820 It is often advisable to break down large tasks into smaller, 821 manageable subtasks. You can do this by creating an outline tree 822 below a TODO item, with detailed subtasks on the tree. To keep an 823 overview of the fraction of subtasks that have already been marked 824 as done, insert either =[/]= or =[%]= anywhere in the headline. These 825 cookies are updated each time the TODO status of a child changes, or 826 when pressing {{{kbd(C-c C-c)}}} on the cookie. For example: 827 828 #+begin_example 829 ,* Organize Party [33%] 830 ,** TODO Call people [1/2] 831 ,*** TODO Peter 832 ,*** DONE Sarah 833 ,** TODO Buy food 834 ,** DONE Talk to neighbor 835 #+end_example 836 837 ** Checkboxes 838 :PROPERTIES: 839 :DESCRIPTION: Tick-off lists. 840 :END: 841 842 Every item in a plain list (see [[*Plain Lists]]) can be made into 843 a checkbox by starting it with the string =[ ]=. Checkboxes are not 844 included into the global TODO list, so they are often great to split 845 a task into a number of simple steps. 846 847 Here is an example of a checkbox list. 848 849 #+begin_example 850 ,* TODO Organize party [2/4] 851 - [-] call people [1/2] 852 - [ ] Peter 853 - [X] Sarah 854 - [X] order food 855 #+end_example 856 857 Checkboxes work hierarchically, so if a checkbox item has children 858 that are checkboxes, toggling one of the children checkboxes makes the 859 parent checkbox reflect if none, some, or all of the children are 860 checked. 861 862 The following commands work with checkboxes: 863 864 - {{{kbd(C-c C-c)}}} :: 865 866 Toggle checkbox status or---with prefix argument---checkbox presence 867 at point. 868 869 - {{{kbd(M-S-RET)}}} :: 870 871 Insert a new item with a checkbox. This works only if point is 872 already in a plain list item (see [[*Plain Lists]]). 873 874 * Tags 875 :PROPERTIES: 876 :DESCRIPTION: Tagging headlines and matching sets of tags. 877 :END: 878 879 An excellent way to implement labels and contexts for 880 cross-correlating information is to assign /tags/ to headlines. Org 881 mode has extensive support for tags. 882 883 Every headline can contain a list of tags; they occur at the end of 884 the headline. Tags are normal words containing letters, numbers, =_=, 885 and =@=. Tags must be preceded and followed by a single colon, e.g., 886 =:work:=. Several tags can be specified, as in =:work:urgent:=. Tags 887 by default are in bold face with the same color as the headline. 888 889 ** Tag inheritance 890 :PROPERTIES: 891 :UNNUMBERED: notoc 892 :END: 893 894 Tags make use of the hierarchical structure of outline trees. If 895 a heading has a certain tag, all subheadings inherit the tag as well. 896 For example, in the list 897 898 #+begin_example 899 ,* Meeting with the French group :work: 900 ,** Summary by Frank :boss:notes: 901 ,*** TODO Prepare slides for him :action: 902 #+end_example 903 904 #+texinfo: @noindent 905 the final heading has the tags =work=, =boss=, =notes=, and =action= 906 even though the final heading is not explicitly marked with those 907 tags. 908 909 You can also set tags that all entries in a file should inherit just 910 as if these tags were defined in a hypothetical level zero that 911 surrounds the entire file. Use a line like this[fn:6]: 912 913 : #+FILETAGS: :Peter:Boss:Secret: 914 915 ** Setting tags 916 :PROPERTIES: 917 :UNNUMBERED: notoc 918 :END: 919 920 Tags can simply be typed into the buffer at the end of a headline. 921 After a colon, {{{kbd(M-TAB)}}} offers completion on tags. There is 922 also a special command for inserting tags: 923 924 - {{{kbd(C-c C-q)}}} :: 925 926 Enter new tags for the current headline. Org mode either offers 927 completion or a special single-key interface for setting tags, see 928 below. 929 930 - {{{kbd(C-c C-c)}}} :: 931 932 When point is in a headline, this does the same as {{{kbd(C-c 933 C-q)}}}. 934 935 Org supports tag insertion based on a /list of tags/. By default this 936 list is constructed dynamically, containing all tags currently used in 937 the buffer. You may also globally specify a hard list of tags with 938 the variable ~org-tag-alist~. Finally you can set the default tags 939 for a given file using the =TAGS= keyword, like 940 941 : #+TAGS: @work @home @tennisclub 942 : #+TAGS: laptop car pc sailboat 943 944 By default Org mode uses the standard minibuffer completion facilities 945 for entering tags. However, it also implements another, quicker, tag 946 selection method called /fast tag selection/. This allows you to 947 select and deselect tags with just a single key press. For this to 948 work well you should assign unique letters to most of your commonly 949 used tags. You can do this globally by configuring the variable 950 ~org-tag-alist~ in your Emacs init file. For example, you may find 951 the need to tag many items in different files with =@home=. In this 952 case you can set something like: 953 954 #+begin_src emacs-lisp 955 (setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l))) 956 #+end_src 957 958 If the tag is only relevant to the file you are working on, then you 959 can instead set the =TAGS= keyword as: 960 961 : #+TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p) 962 963 ** Tag groups 964 :PROPERTIES: 965 :UNNUMBERED: notoc 966 :END: 967 968 A tag can be defined as a /group tag/ for a set of other tags. The 969 group tag can be seen as the "broader term" for its set of tags. 970 971 You can set group tags by using brackets and inserting a colon between 972 the group tag and its related tags: 973 974 : #+TAGS: [ GTD : Control Persp ] 975 976 #+texinfo: @noindent 977 or, if tags in the group should be mutually exclusive: 978 979 : #+TAGS: { Context : @Home @Work } 980 981 When you search for a group tag, it return matches for all members in 982 the group and its subgroups. In an agenda view, filtering by a group 983 tag displays or hide headlines tagged with at least one of the members 984 of the group or any of its subgroups. 985 986 If you want to ignore group tags temporarily, toggle group tags 987 support with ~org-toggle-tags-groups~, bound to {{{kbd(C-c C-x q)}}}. 988 989 ** Tag searches 990 :PROPERTIES: 991 :UNNUMBERED: notoc 992 :END: 993 994 - {{{kbd(C-c / m)}}} or {{{kbd(C-c \)}}} :: 995 996 Create a sparse tree with all headlines matching a tags search. 997 With a {{{kbd(C-u)}}} prefix argument, ignore headlines that are not 998 a TODO line. 999 1000 - {{{kbd(M-x org-agenda m)}}} :: 1001 1002 Create a global list of tag matches from all agenda files. See 1003 [[*Matching Tags and Properties]]. 1004 1005 - {{{kbd(M-x org-agenda M)}}} :: 1006 1007 Create a global list of tag matches from all agenda files, but check 1008 only TODO items and force checking subitems (see the option 1009 ~org-tags-match-list-sublevels~). 1010 1011 These commands all prompt for a match string which allows basic 1012 Boolean logic like =+boss+urgent-project1=, to find entries with tags 1013 =boss= and =urgent=, but not =project1=, or =Kathy|Sally= to find 1014 entries which are tagged, like =Kathy= or =Sally=. The full syntax of 1015 the search string is rich and allows also matching against TODO 1016 keywords, entry levels and properties. For a more detailed description 1017 with many examples, see [[*Matching Tags and Properties]]. 1018 1019 * Properties 1020 :PROPERTIES: 1021 :DESCRIPTION: Storing information about an entry. 1022 :END: 1023 1024 Properties are key-value pairs associated with an entry. They live in 1025 a special drawer with the name =PROPERTIES=. Each property is 1026 specified on a single line, with the key (surrounded by colons) first, 1027 and the value after it: 1028 1029 #+begin_example 1030 ,* CD collection 1031 ,** Classic 1032 ,*** Goldberg Variations 1033 :PROPERTIES: 1034 :Title: Goldberg Variations 1035 :Composer: J.S. Bach 1036 :Publisher: Deutsche Grammophon 1037 :NDisks: 1 1038 :END: 1039 #+end_example 1040 1041 You may define the allowed values for a particular property =Xyz= by 1042 setting a property =Xyz_ALL=. This special property is /inherited/, 1043 so if you set it in a level 1 entry, it applies to the entire tree. 1044 When allowed values are defined, setting the corresponding property 1045 becomes easier and is less prone to typing errors. For the example 1046 with the CD collection, we can pre-define publishers and the number of 1047 disks in a box like this: 1048 1049 #+begin_example 1050 ,* CD collection 1051 :PROPERTIES: 1052 :NDisks_ALL: 1 2 3 4 1053 :Publisher_ALL: "Deutsche Grammophon" Philips EMI 1054 :END: 1055 #+end_example 1056 1057 If you want to set properties that can be inherited by any entry in 1058 a file, use a line like: 1059 1060 : #+PROPERTY: NDisks_ALL 1 2 3 4 1061 1062 The following commands help to work with properties: 1063 1064 - {{{kbd(C-c C-x p)}}} :: 1065 1066 Set a property. This prompts for a property name and a value. 1067 1068 - {{{kbd(C-c C-c d)}}} :: 1069 1070 Remove a property from the current entry. 1071 1072 To create sparse trees and special lists with selection based on 1073 properties, the same commands are used as for tag searches (see 1074 [[*Tags]]). The syntax for the search string is described in [[*Matching 1075 Tags and Properties]]. 1076 1077 * Dates and Times 1078 :PROPERTIES: 1079 :DESCRIPTION: Making items useful for planning. 1080 :END: 1081 1082 To assist project planning, TODO items can be labeled with a date 1083 and/or a time. The specially formatted string carrying the date and 1084 time information is called a /timestamp/ in Org mode. 1085 1086 ** Timestamps 1087 :PROPERTIES: 1088 :DESCRIPTION: Assigning a time to a tree entry. 1089 :END: 1090 1091 A timestamp is a specification of a date---possibly with a time or 1092 a range of times---in a special format, either =<2003-09-16 Tue>= or 1093 =<2003-09-16 Tue 09:39>= or =<2003-09-16 Tue 12:00-12:30>=. 1094 A timestamp can appear anywhere in the headline or body of an Org tree 1095 entry. Its presence causes entries to be shown on specific dates in 1096 the agenda (see [[*The Weekly/Daily Agenda]]). We distinguish: 1097 1098 - Plain timestamp; Event; Appointment :: 1099 1100 A simple timestamp just assigns a date/time to an item. This is 1101 just like writing down an appointment or event in a paper agenda. 1102 1103 #+begin_example 1104 ,* Meet Peter at the movies 1105 <2006-11-01 Wed 19:15> 1106 ,* Discussion on climate change 1107 <2006-11-02 Thu 20:00-22:00> 1108 #+end_example 1109 1110 - Timestamp with repeater interval :: 1111 1112 A timestamp may contain a /repeater interval/, indicating that it 1113 applies not only on the given date, but again and again after 1114 a certain interval of N days (d), weeks (w), months (m), or years 1115 (y). The following shows up in the agenda every Wednesday: 1116 1117 #+begin_example 1118 ,* Pick up Sam at school 1119 <2007-05-16 Wed 12:30 +1w> 1120 #+end_example 1121 1122 - Diary-style expression entries :: 1123 1124 #+cindex: diary style timestamps 1125 #+cindex: sexp timestamps 1126 For more complex date specifications, Org mode supports using the 1127 special expression diary entries implemented in the Emacs Calendar 1128 package. For example, with optional time: 1129 1130 #+begin_example 1131 ,* 22:00-23:00 The nerd meeting on every 2nd Thursday of the month 1132 <%%(diary-float t 4 2)> 1133 #+end_example 1134 1135 - Time/Date range :: 1136 1137 Two timestamps connected by =--= denote a range. 1138 1139 #+begin_example 1140 ,** Meeting in Amsterdam 1141 <2004-08-23 Mon>--<2004-08-26 Thu> 1142 #+end_example 1143 1144 - Inactive timestamp :: 1145 1146 Just like a plain timestamp, but with square brackets instead of 1147 angular ones. These timestamps are inactive in the sense that they 1148 do /not/ trigger an entry to show up in the agenda. 1149 1150 #+begin_example 1151 ,* Gillian comes late for the fifth time 1152 [2006-11-01 Wed] 1153 #+end_example 1154 1155 ** Creating Timestamps 1156 :PROPERTIES: 1157 :DESCRIPTION: Commands that insert timestamps. 1158 :END: 1159 1160 For Org mode to recognize timestamps, they need to be in the specific 1161 format. All commands listed below produce timestamps in the correct 1162 format. 1163 1164 #+attr_texinfo: :sep , 1165 - {{{kbd(C-c .)}}} :: 1166 1167 Prompt for a date and insert a corresponding timestamp. When point 1168 is at an existing timestamp in the buffer, the command is used to 1169 modify this timestamp instead of inserting a new one. When this 1170 command is used twice in succession, a time range is inserted. With 1171 a prefix argument, it also adds the current time. 1172 1173 - {{{kbd(C-c !)}}} :: 1174 1175 Like {{{kbd(C-c .)}}}, but insert an inactive timestamp that does 1176 not cause an agenda entry. 1177 1178 - {{{kbd(S-LEFT)}}}, {{{kbd(S-RIGHT)}}} :: 1179 1180 Change date at point by one day. 1181 1182 - {{{kbd(S-UP)}}}, {{{kbd(S-DOWN)}}} :: 1183 1184 On the beginning or enclosing bracket of a timestamp, change its 1185 type. Within a timestamp, change the item under point. Point can 1186 be on a year, month, day, hour or minute. When the timestamp 1187 contains a time range like =15:30-16:30=, modifying the first time 1188 also shifts the second, shifting the time block with constant 1189 length. To change the length, modify the second time. 1190 1191 1192 When Org mode prompts for a date/time, it accepts any string 1193 containing some date and/or time information, and intelligently 1194 interprets the string, deriving defaults for unspecified information 1195 from the current date and time. You can also select a date in the 1196 pop-up calendar. See the manual for more information on how exactly 1197 the date/time prompt works. 1198 1199 ** Deadlines and Scheduling 1200 :PROPERTIES: 1201 :DESCRIPTION: Planning your work. 1202 :END: 1203 1204 A timestamp may be preceded by special keywords to facilitate 1205 planning: 1206 1207 - {{{kbd(C-c C-d)}}} :: 1208 1209 Insert =DEADLINE= keyword along with a time stamp, in the line 1210 following the headline. 1211 1212 Meaning: the task---most likely a TODO item, though not 1213 necessarily---is supposed to be finished on that date. 1214 1215 On the deadline date, the task is listed in the agenda. In 1216 addition, the agenda for /today/ carries a warning about the 1217 approaching or missed deadline, starting ~org-deadline-warning-days~ 1218 before the due date, and continuing until the entry is marked as 1219 done. An example: 1220 1221 #+begin_example 1222 ,*** TODO write article about the Earth for the Guide 1223 DEADLINE: <2004-02-29 Sun> 1224 The editor in charge is [[bbdb:Ford Prefect]] 1225 #+end_example 1226 1227 - {{{kbd(C-c C-s)}}} :: 1228 1229 Insert =SCHEDULED= keyword along with a stamp, in the line following 1230 the headline. 1231 1232 Meaning: you are planning to start working on that task on the given 1233 date[fn:7]. 1234 1235 The headline is listed under the given date[fn:8]. In addition, 1236 a reminder that the scheduled date has passed is present in the 1237 compilation for /today/, until the entry is marked as done, i.e., 1238 the task is automatically forwarded until completed. 1239 1240 #+begin_example 1241 ,*** TODO Call Trillian for a date on New Years Eve. 1242 SCHEDULED: <2004-12-25 Sat> 1243 #+end_example 1244 1245 Some tasks need to be repeated again and again. Org mode helps to 1246 organize such tasks using a so-called repeater in a =DEADLINE=, 1247 =SCHEDULED=, or plain timestamps. In the following example: 1248 1249 #+begin_example 1250 ,** TODO Pay the rent 1251 DEADLINE: <2005-10-01 Sat +1m> 1252 #+end_example 1253 1254 #+texinfo: @noindent 1255 the =+1m= is a repeater; the intended interpretation is that the task 1256 has a deadline on =<2005-10-01>= and repeats itself every (one) month 1257 starting from that time. 1258 1259 ** Clocking Work Time 1260 :PROPERTIES: 1261 :DESCRIPTION: Tracking how long you spent on a task. 1262 :END: 1263 1264 Org mode allows you to clock the time you spend on specific tasks in 1265 a project. 1266 1267 #+attr_texinfo: :sep , 1268 - {{{kbd(C-c C-x C-i)}}} :: 1269 1270 Start the clock on the current item (clock-in). This inserts the 1271 =CLOCK= keyword together with a timestamp. When called with 1272 a {{{kbd(C-u)}}} prefix argument, select the task from a list of 1273 recently clocked tasks. 1274 1275 - {{{kbd(C-c C-x C-o)}}} :: 1276 1277 Stop the clock (clock-out). This inserts another timestamp at the 1278 same location where the clock was last started. It also directly 1279 computes the resulting time in inserts it after the time range as 1280 ==>HH:MM=. 1281 1282 - {{{kbd(C-c C-x C-e)}}} :: 1283 1284 Update the effort estimate for the current clock task. 1285 1286 - {{{kbd(C-c C-x C-q)}}} :: 1287 1288 Cancel the current clock. This is useful if a clock was started by 1289 mistake, or if you ended up working on something else. 1290 1291 - {{{kbd(C-c C-x C-j)}}} :: 1292 1293 Jump to the headline of the currently clocked in task. With 1294 a {{{kbd(C-u)}}} prefix argument, select the target task from a list 1295 of recently clocked tasks. 1296 1297 The {{{kbd(l)}}} key may be used in the agenda (see [[*The Weekly/Daily 1298 Agenda]]) to show which tasks have been worked on or closed during 1299 a day. 1300 1301 * Capture, Refile, Archive 1302 :PROPERTIES: 1303 :DESCRIPTION: The ins and outs for projects. 1304 :END: 1305 1306 An important part of any organization system is the ability to quickly 1307 capture new ideas and tasks, and to associate reference material with 1308 them. Org does this using a process called /capture/. It also can 1309 store files related to a task (/attachments/) in a special directory. 1310 Once in the system, tasks and projects need to be moved around. 1311 Moving completed project trees to an archive file keeps the system 1312 compact and fast. 1313 1314 ** Capture 1315 :PROPERTIES: 1316 :DESCRIPTION: Capturing new stuff. 1317 :END: 1318 1319 Capture lets you quickly store notes with little interruption of your 1320 work flow. You can define templates for new entries and associate 1321 them with different targets for storing notes. 1322 1323 *** Setting up capture 1324 :PROPERTIES: 1325 :UNNUMBERED: notoc 1326 :END: 1327 1328 The following customization sets a default target[fn:9] file for notes. 1329 1330 #+begin_src emacs-lisp 1331 (setq org-default-notes-file (concat org-directory "/notes.org")) 1332 #+end_src 1333 1334 You may also define a global key for capturing new material (see 1335 [[*Activation]]). 1336 1337 *** Using capture 1338 :PROPERTIES: 1339 :UNNUMBERED: notoc 1340 :END: 1341 1342 - {{{kbd(M-x org-capture)}}} :: 1343 1344 Start a capture process, placing you into a narrowed indirect buffer 1345 to edit. 1346 1347 - {{{kbd(C-c C-c)}}} :: 1348 1349 Once you have finished entering information into the capture buffer, 1350 {{{kbd(C-c C-c)}}} returns you to the window configuration before 1351 the capture process, so that you can resume your work without 1352 further distraction. 1353 1354 - {{{kbd(C-c C-w)}}} :: 1355 1356 Finalize the capture process by refiling the note to a different 1357 place (see [[*Refile and Copy]]). 1358 1359 - {{{kbd(C-c C-k)}}} :: 1360 1361 Abort the capture process and return to the previous state. 1362 1363 *** Capture templates 1364 :PROPERTIES: 1365 :UNNUMBERED: notoc 1366 :END: 1367 1368 You can use templates for different types of capture items, and for 1369 different target locations. Say you would like to use one template to 1370 create general TODO entries, and you want to put these entries under 1371 the heading =Tasks= in your file =~/org/gtd.org=. Also, a date tree 1372 in the file =journal.org= should capture journal entries. A possible 1373 configuration would look like: 1374 1375 #+begin_src emacs-lisp 1376 (setq org-capture-templates 1377 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") 1378 "* TODO %?\n %i\n %a") 1379 ("j" "Journal" entry (file+datetree "~/org/journal.org") 1380 "* %?\nEntered on %U\n %i\n %a"))) 1381 #+end_src 1382 1383 If you then press {{{kbd(t)}}} from the capture menu, Org will prepare 1384 the template for you like this: 1385 1386 : * TODO 1387 : [[file:LINK TO WHERE YOU INITIATED CAPTURE]] 1388 1389 #+texinfo: @noindent 1390 During expansion of the template, special %-escapes[fn:10] allow 1391 dynamic insertion of content. Here is a small selection of the 1392 possibilities, consult the manual for more. 1393 1394 | =%a= | annotation, normally the link created with ~org-store-link~ | 1395 | =%i= | initial content, the region when capture is called with {{{kbd(C-u)}}} | 1396 | =%t=, =%T= | timestamp, date only, or date and time | 1397 | =%u=, =%U= | like above, but inactive timestamps | 1398 | =%?= | after completing the template, position point here | 1399 1400 ** Refile and Copy 1401 :PROPERTIES: 1402 :DESCRIPTION: Moving/copying a tree from one place to another. 1403 :END: 1404 1405 When reviewing the captured data, you may want to refile or to copy 1406 some of the entries into a different list, for example into a project. 1407 Cutting, finding the right location, and then pasting the note is 1408 cumbersome. To simplify this process, you can use the following 1409 special command: 1410 1411 - {{{kbd(C-c C-w)}}} :: 1412 1413 Refile the entry or region at point. This command offers possible 1414 locations for refiling the entry and lets you select one with 1415 completion. The item (or all items in the region) is filed below 1416 the target heading as a subitem. 1417 1418 By default, all level 1 headlines in the current buffer are 1419 considered to be targets, but you can have more complex definitions 1420 across a number of files. See the variable ~org-refile-targets~ for 1421 details. 1422 1423 - {{{kbd(C-u C-c C-w)}}} :: 1424 1425 Use the refile interface to jump to a heading. 1426 1427 - {{{kbd(C-u C-u C-c C-w)}}} :: 1428 1429 Jump to the location where ~org-refile~ last moved a tree to. 1430 1431 - {{{kbd(C-c M-w)}}} :: 1432 1433 Copying works like refiling, except that the original note is not 1434 deleted. 1435 1436 ** Archiving 1437 :PROPERTIES: 1438 :DESCRIPTION: What to do with finished products. 1439 :END: 1440 1441 When a project represented by a (sub)tree is finished, you may want to 1442 move the tree out of the way and to stop it from contributing to the 1443 agenda. Archiving is important to keep your working files compact and 1444 global searches like the construction of agenda views fast. 1445 1446 The most common archiving action is to move a project tree to another 1447 file, the archive file. 1448 1449 - {{{kbd(C-c C-x C-a)}}} :: 1450 1451 Archive the current entry using the command specified in the 1452 variable ~org-archive-default-command~. 1453 1454 - {{{kbd(C-c C-x C-s)}}} or short {{{kbd(C-c $)}}} :: 1455 1456 Archive the subtree starting at point position to the location given 1457 by ~org-archive-location~. 1458 1459 The default archive location is a file in the same directory as the 1460 current file, with the name derived by appending =_archive= to the 1461 current file name. You can also choose what heading to file archived 1462 items under, with the possibility to add them to a datetree in a file. 1463 For information and examples on how to specify the file and the 1464 heading, see the documentation string of the variable 1465 ~org-archive-location~. 1466 1467 There is also an in-buffer option for setting this variable, for 1468 example: 1469 1470 : #+ARCHIVE: %s_done:: 1471 1472 * Agenda Views 1473 :PROPERTIES: 1474 :DESCRIPTION: Collecting information into views. 1475 :END: 1476 1477 Due to the way Org works, TODO items, time-stamped items, and tagged 1478 headlines can be scattered throughout a file or even a number of 1479 files. To get an overview of open action items, or of events that are 1480 important for a particular date, this information must be collected, 1481 sorted and displayed in an organized way. 1482 1483 The extracted information is displayed in a special /agenda buffer/. 1484 This buffer is read-only, but provides commands to visit the 1485 corresponding locations in the original Org files, and even to edit 1486 these files remotely. Remote editing from the agenda buffer means, 1487 for example, that you can change the dates of deadlines and 1488 appointments from the agenda buffer. For commands available in the 1489 Agenda buffer, see [[*Commands in the Agenda Buffer]]. 1490 1491 ** Agenda Files 1492 :PROPERTIES: 1493 :DESCRIPTION: Files being searched for agenda information. 1494 :END: 1495 1496 The information to be shown is normally collected from all /agenda 1497 files/, the files listed in the variable ~org-agenda-files~. 1498 1499 #+attr_texinfo: :sep or 1500 - {{{kbd(C-c [)}}} :: 1501 1502 Add current file to the list of agenda files. The file is added to 1503 the front of the list. If it was already in the list, it is moved 1504 to the front. With a prefix argument, file is added/moved to the 1505 end. 1506 1507 - {{{kbd(C-c ])}}} :: 1508 1509 Remove current file from the list of agenda files. 1510 1511 - {{{kbd(C-')}}} or {{{kbd(C-\,)}}} :: 1512 1513 Cycle through agenda file list, visiting one file after the other. 1514 1515 ** The Agenda Dispatcher 1516 :PROPERTIES: 1517 :DESCRIPTION: Keyboard access to agenda views. 1518 :ALT_TITLE: Agenda Dispatcher 1519 :END: 1520 1521 The views are created through a dispatcher, accessible with {{{kbd(M-x 1522 org-agenda)}}}, or, better, bound to a global key (see [[*Activation]]). 1523 It displays a menu from which an additional letter is required to 1524 execute a command. The dispatcher offers the following default 1525 commands: 1526 1527 #+attr_texinfo: :sep , 1528 - {{{kbd(a)}}} :: 1529 1530 Create the calendar-like agenda (see [[*The Weekly/Daily Agenda]]). 1531 1532 - {{{kbd(t)}}}, {{{kbd(T)}}} :: 1533 1534 Create a list of all TODO items (see [[*The Global TODO List]]). 1535 1536 - {{{kbd(m)}}}, {{{kbd(M)}}} :: 1537 1538 Create a list of headlines matching a given expression (see 1539 [[*Matching Tags and Properties]]). 1540 1541 - {{{kbd(s)}}} :: 1542 1543 #+kindex: s @r{(Agenda dispatcher)} 1544 Create a list of entries selected by a boolean expression of 1545 keywords and/or regular expressions that must or must not occur in 1546 the entry. 1547 1548 ** The Weekly/Daily Agenda 1549 :PROPERTIES: 1550 :DESCRIPTION: What is available out of the box? 1551 :ALT_TITLE: Built-in Agenda Views 1552 :END: 1553 1554 The purpose of the weekly/daily /agenda/ is to act like a page of 1555 a paper agenda, showing all the tasks for the current week or day. 1556 1557 - {{{kbd(M-x org-agenda a)}}} :: 1558 1559 Compile an agenda for the current week from a list of Org files. 1560 The agenda shows the entries for each day. 1561 1562 Org mode understands the syntax of the diary and allows you to use 1563 diary expression entries directly in Org files: 1564 1565 #+begin_example 1566 ,* Holidays 1567 :PROPERTIES: 1568 :CATEGORY: Holiday 1569 :END: 1570 %%(org-calendar-holiday) ; special function for holiday names 1571 1572 ,* Birthdays 1573 :PROPERTIES: 1574 :CATEGORY: Ann 1575 :END: 1576 %%(org-anniversary 1956 5 14) Arthur Dent is %d years old 1577 %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old 1578 #+end_example 1579 1580 Org can interact with Emacs appointments notification facility. To 1581 add the appointments of your agenda files, use the command 1582 ~org-agenda-to-appt~. 1583 1584 ** The Global TODO List 1585 :PROPERTIES: 1586 :DESCRIPTION: All unfinished action items. 1587 :ALT_TITLE: Global TODO List 1588 :END: 1589 1590 The global TODO list contains all unfinished TODO items formatted and 1591 collected into a single place. Remote editing of TODO items lets you 1592 can change the state of a TODO entry with a single key press. For 1593 commands available in the TODO list, see [[*Commands in the Agenda 1594 Buffer]]. 1595 1596 - {{{kbd(M-x org-agenda t)}}} :: 1597 1598 Show the global TODO list. This collects the TODO items from all 1599 agenda files (see [[*Agenda Views]]) into a single buffer. 1600 1601 - {{{kbd(M-x org-agenda T)}}} :: 1602 1603 Like the above, but allows selection of a specific TODO keyword. 1604 1605 ** Matching Tags and Properties 1606 :PROPERTIES: 1607 :DESCRIPTION: Structured information with fine-tuned search. 1608 :END: 1609 1610 If headlines in the agenda files are marked with /tags/ (see [[*Tags]]), 1611 or have properties (see [[*Properties]]), you can select headlines based 1612 on this metadata and collect them into an agenda buffer. The match 1613 syntax described here also applies when creating sparse trees with 1614 {{{kbd(C-c / m)}}}. 1615 1616 - {{{kbd(M-x org-agenda m)}}} :: 1617 1618 Produce a list of all headlines that match a given set of tags. The 1619 command prompts for a selection criterion, which is a boolean logic 1620 expression with tags, like =+work+urgent-withboss= or =work|home= 1621 (see [[*Tags]]). If you often need a specific search, define a custom 1622 command for it (see [[*The Agenda Dispatcher]]). 1623 1624 - {{{kbd(M-x org-agenda M)}}} :: 1625 1626 Like {{{kbd(m)}}}, but only select headlines that are also TODO 1627 items. 1628 1629 A search string can use Boolean operators =&= for AND and =|= for OR. 1630 =&= binds more strongly than =|=. Parentheses are currently not 1631 implemented. Each element in the search is either a tag, a regular 1632 expression matching tags, or an expression like =PROPERTY OPERATOR 1633 VALUE= with a comparison operator, accessing a property value. Each 1634 element may be preceded by =-= to select against it, and =+= is 1635 syntactic sugar for positive selection. The AND operator =&= is 1636 optional when =+= or =-= is present. Here are some examples, using 1637 only tags. 1638 1639 - =+work-boss= :: 1640 1641 Select headlines tagged =work=, but discard those also tagged 1642 =boss=. 1643 1644 - =work|laptop= :: 1645 1646 Selects lines tagged =work= or =laptop=. 1647 1648 - =work|laptop+night= :: 1649 1650 Like before, but require the =laptop= lines to be tagged also 1651 =night=. 1652 1653 You may also test for properties at the same time as matching tags, 1654 see the manual for more information. 1655 1656 ** Search View 1657 :PROPERTIES: 1658 :DESCRIPTION: Find entries by searching for text. 1659 :END: 1660 1661 This agenda view is a general text search facility for Org mode 1662 entries. It is particularly useful to find notes. 1663 1664 - {{{kbd(M-x org-agenda s)}}} (~org-search-view~) :: 1665 1666 #+kindex: s @r{(Agenda dispatcher)} 1667 #+findex: org-search-view 1668 This is a special search that lets you select entries by matching 1669 a substring or specific words using a boolean logic. 1670 1671 For example, the search string =computer equipment= matches entries 1672 that contain =computer equipment= as a substring. 1673 1674 Search view can also search for specific keywords in the entry, using 1675 Boolean logic. The search string =+computer 1676 +wifi -ethernet -{8\.11[bg]}= matches note entries that contain the 1677 keywords =computer= and =wifi=, but not the keyword =ethernet=, and 1678 which are also not matched by the regular expression =8\.11[bg]=, 1679 meaning to exclude both =8.11b= and =8.11g=. 1680 1681 Note that in addition to the agenda files, this command also searches 1682 the files listed in ~org-agenda-text-search-extra-files~. 1683 1684 ** Commands in the Agenda Buffer 1685 :PROPERTIES: 1686 :DESCRIPTION: Remote editing of Org trees. 1687 :ALT_TITLE: Agenda Commands 1688 :END: 1689 1690 Entries in the agenda buffer are linked back to the Org file or diary 1691 file where they originate. You are not allowed to edit the agenda 1692 buffer itself, but commands are provided to show and jump to the 1693 original entry location, and to edit the Org files "remotely" from the 1694 agenda buffer. This is just a selection of the many commands, explore 1695 the agenda menu and the manual for a complete list. 1696 1697 *** Motion 1698 :PROPERTIES: 1699 :UNNUMBERED: notoc 1700 :END: 1701 1702 - {{{kbd(n)}}} :: 1703 1704 Next line (same as {{{kbd(DOWN)}}} and {{{kbd(C-n)}}}). 1705 1706 - {{{kbd(p)}}} :: 1707 1708 Previous line (same as {{{kbd(UP)}}} and {{{kbd(C-p)}}}). 1709 1710 *** View/Go to Org file 1711 :PROPERTIES: 1712 :UNNUMBERED: notoc 1713 :END: 1714 1715 - {{{kbd(SPC)}}} :: 1716 1717 Display the original location of the item in another window. 1718 With a prefix argument, make sure that drawers stay folded. 1719 1720 - {{{kbd(TAB)}}} :: 1721 1722 Go to the original location of the item in another window. 1723 1724 - {{{kbd(RET)}}} :: 1725 1726 Go to the original location of the item and delete other windows. 1727 1728 *** Change display 1729 :PROPERTIES: 1730 :UNNUMBERED: notoc 1731 :END: 1732 #+attr_texinfo: :sep , 1733 - {{{kbd(o)}}} :: 1734 1735 Delete other windows. 1736 1737 - {{{kbd(v d)}}} or short {{{kbd(d)}}} :: 1738 1739 Switch to day view. 1740 1741 - {{{kbd(v w)}}} or short {{{kbd(w)}}} :: 1742 1743 Switch to week view. 1744 1745 - {{{kbd(f)}}} :: 1746 1747 Go forward in time to display the span following the current one. 1748 For example, if the display covers a week, switch to the following 1749 week. 1750 1751 - {{{kbd(b)}}} :: 1752 1753 Go backward in time to display earlier dates. 1754 1755 - {{{kbd(.)}}} :: 1756 1757 Go to today. 1758 1759 - {{{kbd(j)}}} :: 1760 1761 Prompt for a date and go there. 1762 1763 - {{{kbd(v l)}}} or {{{kbd(v L)}}} or short {{{kbd(l)}}} :: 1764 1765 Toggle Logbook mode. In Logbook mode, entries that were marked as 1766 done while logging was on (see the variable ~org-log-done~) are 1767 shown in the agenda, as are entries that have been clocked on that 1768 day. When called with a {{{kbd(C-u)}}} prefix argument, show all 1769 possible logbook entries, including state changes. 1770 1771 - {{{kbd(r)}}}, {{{kbd(g)}}} :: 1772 1773 Recreate the agenda buffer, for example to reflect the changes after 1774 modification of the timestamps of items. 1775 1776 - {{{kbd(s)}}} :: 1777 1778 #+kindex: C-x C-s 1779 #+findex: org-save-all-org-buffers 1780 #+kindex: s 1781 Save all Org buffers in the current Emacs session, and also the 1782 locations of IDs. 1783 1784 *** Remote editing 1785 :PROPERTIES: 1786 :UNNUMBERED: notoc 1787 :END: 1788 1789 - {{{kbd(0--9)}}} :: 1790 1791 Digit argument. 1792 1793 - {{{kbd(t)}}} :: 1794 1795 Change the TODO state of the item, both in the agenda and in the 1796 original Org file. 1797 1798 - {{{kbd(C-k)}}} :: 1799 1800 Delete the current agenda item along with the entire subtree 1801 belonging to it in the original Org file. 1802 1803 - {{{kbd(C-c C-w)}}} :: 1804 1805 Refile the entry at point. 1806 1807 - {{{kbd(a)}}} :: 1808 1809 Archive the subtree corresponding to the entry at point using the 1810 default archiving command set in ~org-archive-default-command~. 1811 1812 - {{{kbd($)}}} :: 1813 1814 Archive the subtree corresponding to the current headline. 1815 1816 - {{{kbd(C-c C-s)}}} :: 1817 1818 Schedule this item. With a prefix argument, remove the 1819 scheduling timestamp 1820 1821 - {{{kbd(C-c C-d)}}} :: 1822 1823 Set a deadline for this item. With a prefix argument, remove the 1824 deadline. 1825 1826 - {{{kbd(S-RIGHT)}}} :: 1827 1828 Change the timestamp associated with the current line by one day 1829 into the future. 1830 1831 - {{{kbd(S-LEFT)}}} :: 1832 1833 Change the timestamp associated with the current line by one day 1834 into the past. 1835 1836 - {{{kbd(I)}}} :: 1837 1838 Start the clock on the current item. 1839 1840 - {{{kbd(O)}}} :: 1841 1842 Stop the previously started clock. 1843 1844 - {{{kbd(X)}}} :: 1845 1846 Cancel the currently running clock. 1847 1848 - {{{kbd(J)}}} :: 1849 1850 Jump to the running clock in another window. 1851 1852 *** Quit and exit 1853 :PROPERTIES: 1854 :UNNUMBERED: notoc 1855 :END: 1856 1857 - {{{kbd(q)}}} :: 1858 1859 Quit agenda, remove the agenda buffer. 1860 1861 - {{{kbd(x)}}} :: 1862 1863 Exit agenda, remove the agenda buffer and all buffers loaded by 1864 Emacs for the compilation of the agenda. 1865 1866 ** Custom Agenda Views 1867 :PROPERTIES: 1868 :DESCRIPTION: Defining special searches and views. 1869 :END: 1870 1871 The first application of custom searches is the definition of keyboard 1872 shortcuts for frequently used searches, either creating an agenda 1873 buffer, or a sparse tree (the latter covering of course only the 1874 current buffer). 1875 1876 Custom commands are configured in the variable 1877 ~org-agenda-custom-commands~. You can customize this variable, for 1878 example by pressing {{{kbd(C)}}} from the agenda dispatcher (see [[*The 1879 Agenda Dispatcher]]). You can also directly set it with Emacs Lisp in 1880 the Emacs init file. The following example contains all valid agenda 1881 views: 1882 1883 #+begin_src emacs-lisp 1884 (setq org-agenda-custom-commands 1885 '(("w" todo "WAITING") 1886 ("u" tags "+boss-urgent") 1887 ("v" tags-todo "+boss-urgent"))) 1888 #+end_src 1889 1890 The initial string in each entry defines the keys you have to press 1891 after the dispatcher command in order to access the command. Usually 1892 this is just a single character. The second parameter is the search 1893 type, followed by the string or regular expression to be used for the 1894 matching. The example above will therefore define: 1895 1896 - {{{kbd(w)}}} :: 1897 1898 as a global search for TODO entries with =WAITING= as the TODO 1899 keyword. 1900 1901 - {{{kbd(u)}}} :: 1902 1903 as a global tags search for headlines tagged =boss= but not 1904 =urgent=. 1905 1906 - {{{kbd(v)}}} :: 1907 1908 The same search, but limiting it to headlines that are also TODO 1909 items. 1910 1911 * Markup for Rich Contents 1912 :PROPERTIES: 1913 :DESCRIPTION: Compose beautiful documents. 1914 :ALT_TITLE: Markup 1915 :END: 1916 1917 Org is primarily about organizing and searching through your 1918 plain-text notes. However, it also provides a lightweight yet robust 1919 markup language for rich text formatting and more. Used in 1920 conjunction with the export framework (see [[*Exporting]]), you can author 1921 beautiful documents in Org. 1922 1923 ** Paragraphs 1924 :PROPERTIES: 1925 :DESCRIPTION: The basic unit of text. 1926 :END: 1927 1928 Paragraphs are separated by at least one empty line. If you need to 1929 enforce a line break within a paragraph, use =\\= at the end of 1930 a line. 1931 1932 To preserve the line breaks, indentation and blank lines in a region, 1933 but otherwise use normal formatting, you can use this construct, which 1934 can also be used to format poetry. 1935 1936 #+begin_example 1937 ,#+BEGIN_VERSE 1938 Great clouds overhead 1939 Tiny black birds rise and fall 1940 Snow covers Emacs 1941 1942 ---AlexSchroeder 1943 ,#+END_VERSE 1944 #+end_example 1945 1946 When quoting a passage from another document, it is customary to 1947 format this as a paragraph that is indented on both the left and the 1948 right margin. You can include quotations in Org documents like this: 1949 1950 #+begin_example 1951 ,#+BEGIN_QUOTE 1952 Everything should be made as simple as possible, 1953 but not any simpler ---Albert Einstein 1954 ,#+END_QUOTE 1955 #+end_example 1956 1957 If you would like to center some text, do it like this: 1958 1959 #+begin_example 1960 ,#+BEGIN_CENTER 1961 Everything should be made as simple as possible, \\ 1962 but not any simpler 1963 ,#+END_CENTER 1964 #+end_example 1965 1966 ** Emphasis and Monospace 1967 :PROPERTIES: 1968 :DESCRIPTION: Bold, italic, etc. 1969 :END: 1970 1971 You can make words =*bold*=, =/italic/=, =_underlined_=, ==verbatim== 1972 and =~code~=, and, if you must, =+strike-through+=. Text in the code 1973 and verbatim string is not processed for Org specific syntax; it is 1974 exported verbatim. 1975 1976 ** Embedded LaTeX 1977 :PROPERTIES: 1978 :DESCRIPTION: LaTeX can be freely used inside Org documents. 1979 :END: 1980 1981 For scientific notes which need to be able to contain mathematical 1982 symbols and the occasional formula, Org mode supports embedding LaTeX 1983 code into its files. You can directly use TeX-like syntax for special 1984 symbols, enter formulas and entire LaTeX environments. 1985 1986 #+begin_example 1987 The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, 1988 the radius of Alpha Centauri is R_{Alpha Centauri} = 1.28 x R_{sun}. 1989 1990 \begin{equation} % arbitrary environments, 1991 x=\sqrt{b} % even tables, figures 1992 \end{equation} % etc 1993 1994 If $a^2=b$ and \( b=2 \), then the solution must be 1995 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \]. 1996 #+end_example 1997 1998 ** Literal examples 1999 :PROPERTIES: 2000 :DESCRIPTION: Source code examples with special formatting. 2001 :END: 2002 2003 You can include literal examples that should not be subjected to 2004 markup. Such examples are typeset in monospace, so this is well 2005 suited for source code and similar examples. 2006 2007 #+begin_example 2008 ,#+BEGIN_EXAMPLE 2009 Some example from a text file. 2010 ,#+END_EXAMPLE 2011 #+end_example 2012 2013 For simplicity when using small examples, you can also start the 2014 example lines with a colon followed by a space. There may also be 2015 additional whitespace before the colon: 2016 2017 #+begin_example 2018 Here is an example 2019 : Some example from a text file. 2020 #+end_example 2021 2022 If the example is source code from a programming language, or any 2023 other text that can be marked up by Font Lock in Emacs, you can ask 2024 for the example to look like the fontified Emacs buffer. 2025 2026 #+begin_example 2027 ,#+BEGIN_SRC emacs-lisp 2028 (defun org-xor (a b) 2029 "Exclusive or." 2030 (if a (not b) b)) 2031 ,#+END_SRC 2032 #+end_example 2033 2034 To edit the example in a special buffer supporting this language, use 2035 {{{kbd(C-c ')}}} to both enter and leave the editing buffer. 2036 2037 ** Images 2038 :PROPERTIES: 2039 :DESCRIPTION: Display an image. 2040 :END: 2041 2042 An image is a link to an image file that does not have a description 2043 part, for example 2044 2045 : ./img/cat.jpg 2046 2047 If you wish to define a caption for the image and maybe a label for 2048 internal cross references (see [[*Hyperlinks]]), make sure that the 2049 link is on a line by itself and precede it with =CAPTION= and =NAME= 2050 keywords as follows: 2051 2052 #+begin_example 2053 ,#+CAPTION: This is the caption for the next figure link (or table) 2054 ,#+NAME: fig:SED-HR4049 2055 [[./img/a.jpg]] 2056 #+end_example 2057 2058 ** Creating Footnotes 2059 :PROPERTIES: 2060 :DESCRIPTION: Edit and read footnotes. 2061 :END: 2062 2063 A footnote is defined in a paragraph that is started by a footnote 2064 marker in square brackets in column 0, no indentation allowed. The 2065 footnote reference is simply the marker in square brackets, inside 2066 text. For example: 2067 2068 #+begin_example 2069 The Org website[fn:1] now looks a lot better than it used to. 2070 ... 2071 [fn:1] The link is: https://orgmode.org 2072 #+end_example 2073 2074 The following commands handle footnotes: 2075 2076 - {{{kbd(C-c C-x f)}}} :: 2077 2078 The footnote action command. When point is on a footnote reference, 2079 jump to the definition. When it is at a definition, jump to the 2080 (first) reference. Otherwise, create a new footnote. When this 2081 command is called with a prefix argument, a menu of additional 2082 options including renumbering is offered. 2083 2084 - {{{kbd(C-c C-c)}}} :: 2085 2086 Jump between definition and reference. 2087 2088 * Exporting 2089 :PROPERTIES: 2090 :DESCRIPTION: Sharing and publishing notes. 2091 :END: 2092 2093 Org can convert and export documents to a variety of other formats 2094 while retaining as much structure (see [[*Document Structure]]) and markup 2095 (see [[*Markup for Rich Contents]]) as possible. 2096 2097 ** The Export Dispatcher 2098 :PROPERTIES: 2099 :DESCRIPTION: The main interface. 2100 :END: 2101 2102 The export dispatcher is the main interface for Org's exports. 2103 A hierarchical menu presents the currently configured export formats. 2104 Options are shown as easy toggle switches on the same screen. 2105 2106 - {{{kbd(C-c C-e)}}} :: 2107 2108 Invokes the export dispatcher interface. 2109 2110 Org exports the entire buffer by default. If the Org buffer has an 2111 active region, then Org exports just that region. 2112 2113 ** Export Settings 2114 :PROPERTIES: 2115 :DESCRIPTION: Common export settings. 2116 :END: 2117 2118 The exporter recognizes special lines in the buffer which provide 2119 additional information. These lines may be put anywhere in the file: 2120 2121 : #+TITLE: I'm in the Mood for Org 2122 2123 Most proeminent export options include: 2124 2125 | =TITLE= | the title to be shown | 2126 | =AUTHOR= | the author (default taken from ~user-full-name~) | 2127 | =DATE= | a date, fixed, or an Org timestamp | 2128 | =EMAIL= | email address (default from ~user-mail-address~) | 2129 | =LANGUAGE= | language code, e.g., =en= | 2130 2131 Option keyword sets can be inserted from the export dispatcher (see 2132 [[*The Export Dispatcher]]) using the =Insert template= command by 2133 pressing {{{kbd(#)}}}. 2134 2135 ** Table of Contents 2136 :PROPERTIES: 2137 :DESCRIPTION: The if and where of the table of contents. 2138 :END: 2139 2140 The table of contents includes all headlines in the document. Its 2141 depth is therefore the same as the headline levels in the file. If 2142 you need to use a different depth, or turn it off entirely, set the 2143 ~org-export-with-toc~ variable accordingly. You can achieve the same 2144 on a per file basis, using the following =toc= item in =OPTIONS= 2145 keyword: 2146 2147 #+begin_example 2148 ,#+OPTIONS: toc:2 (only include two levels in TOC) 2149 ,#+OPTIONS: toc:nil (no default TOC at all) 2150 #+end_example 2151 2152 Org normally inserts the table of contents directly before the first 2153 headline of the file. 2154 2155 ** Include Files 2156 :PROPERTIES: 2157 :DESCRIPTION: Include additional files into a document. 2158 :END: 2159 2160 During export, you can include the content of another file. For 2161 example, to include your =.emacs= file, you could use: 2162 2163 : #+INCLUDE: "~/.emacs" src emacs-lisp 2164 2165 #+texinfo: @noindent 2166 The first parameter is the file name to include. The optional second 2167 parameter specifies the block type: =example=, =export= or =src=. The 2168 optional third parameter specifies the source code language to use for 2169 formatting the contents. This is relevant to both =export= and =src= 2170 block types. 2171 2172 You can visit the included file with {{{kbd(C-c ')}}}. 2173 2174 ** Comment Lines 2175 :PROPERTIES: 2176 :DESCRIPTION: What will not be exported. 2177 :END: 2178 2179 Lines starting with zero or more whitespace characters followed by one 2180 =#= and a whitespace are treated as comments and, as such, are not 2181 exported. 2182 2183 Likewise, regions surrounded by =#+BEGIN_COMMENT= ... =#+END_COMMENT= 2184 are not exported. 2185 2186 Finally, a =COMMENT= keyword at the beginning of an entry, but after 2187 any other keyword or priority cookie, comments out the entire subtree. 2188 The command below helps changing the comment status of a headline. 2189 2190 - {{{kbd(C-c ;)}}} :: 2191 2192 Toggle the =COMMENT= keyword at the beginning of an entry. 2193 2194 ** ASCII/UTF-8 Export 2195 :PROPERTIES: 2196 :DESCRIPTION: Exporting to flat files with encoding. 2197 :END: 2198 2199 ASCII export produces an output file containing only plain ASCII 2200 characters. This is the simplest and most direct text output. It 2201 does not contain any Org markup. UTF-8 export uses additional 2202 characters and symbols available in this encoding standards. 2203 2204 #+attr_texinfo: :sep , 2205 - {{{kbd(C-c C-e t a)}}}, {{{kbd(C-c C-e t u)}}} :: 2206 2207 Export as an ASCII file with a =.txt= extension. For =myfile.org=, 2208 Org exports to =myfile.txt=, overwriting without warning. For 2209 =myfile.txt=, Org exports to =myfile.txt.txt= in order to prevent 2210 data loss. 2211 2212 ** HTML Export 2213 :PROPERTIES: 2214 :DESCRIPTION: Exporting to HTML. 2215 :END: 2216 2217 Org mode contains an HTML exporter with extensive HTML formatting 2218 compatible with XHTML 1.0 strict standard. 2219 2220 - {{{kbd(C-c C-e h h)}}} :: 2221 2222 Export as HTML file with a =.html= extension. For =myfile.org=, Org 2223 exports to =myfile.html=, overwriting without warning. {{{kbd(C-c 2224 C-e h o)}}} exports to HTML and opens it in a web browser. 2225 2226 The HTML export back-end transforms =<= and =>= to =<= and =>=. 2227 To include raw HTML code in the Org file so the HTML export back-end 2228 can insert that HTML code in the output, use this inline syntax: 2229 =@@html:...@@=. For example: 2230 2231 : @@html:<b>@@bold text@@html:</b>@@ 2232 2233 For larger raw HTML code blocks, use these HTML export code blocks: 2234 2235 #+begin_example 2236 ,#+HTML: Literal HTML code for export 2237 2238 ,#+BEGIN_EXPORT html 2239 All lines between these markers are exported literally 2240 ,#+END_EXPORT 2241 #+end_example 2242 2243 ** LaTeX Export 2244 :PROPERTIES: 2245 :DESCRIPTION: Exporting to @LaTeX{} and processing to PDF. 2246 :END: 2247 2248 The LaTeX export back-end can handle complex documents, incorporate 2249 standard or custom LaTeX document classes, generate documents using 2250 alternate LaTeX engines, and produce fully linked PDF files with 2251 indexes, bibliographies, and tables of contents, destined for 2252 interactive online viewing or high-quality print publication. 2253 2254 By default, the LaTeX output uses the /article/ class. You can change 2255 this by adding an option like =#+LATEX_CLASS: myclass= in your file. 2256 The class must be listed in ~org-latex-classes~. 2257 2258 - {{{kbd(C-c C-e l l)}}} :: 2259 2260 Export to a LaTeX file with a =.tex= extension. For =myfile.org=, 2261 Org exports to =myfile.tex=, overwriting without warning. 2262 2263 - {{{kbd(C-c C-e l p)}}} :: 2264 2265 Export as LaTeX file and convert it to PDF file. 2266 2267 - {{{kbd(C-c C-e l o)}}} :: 2268 2269 Export as LaTeX file and convert it to PDF, then open the PDF using 2270 the default viewer. 2271 2272 The LaTeX export back-end can insert any arbitrary LaTeX code, see 2273 [[*Embedded LaTeX]]. There are three ways to embed such code in the Org 2274 file and they all use different quoting syntax. 2275 2276 Inserting in-line quoted with @ symbols: 2277 2278 : Code embedded in-line @@latex:any arbitrary LaTeX code@@ in a paragraph. 2279 2280 Inserting as one or more keyword lines in the Org file: 2281 2282 : #+LATEX: any arbitrary LaTeX code 2283 2284 Inserting as an export block in the Org file, where the back-end 2285 exports any code between begin and end markers: 2286 2287 #+begin_example 2288 ,#+BEGIN_EXPORT latex 2289 any arbitrary LaTeX code 2290 ,#+END_EXPORT 2291 #+end_example 2292 2293 ** iCalendar Export 2294 :PROPERTIES: 2295 :DESCRIPTION: Exporting to iCalendar. 2296 :END: 2297 2298 A large part of Org mode's interoperability success is its ability to 2299 easily export to or import from external applications. The iCalendar 2300 export back-end takes calendar data from Org files and exports to the 2301 standard iCalendar format. 2302 2303 - {{{kbd(C-c C-e c f)}}} :: 2304 2305 Create iCalendar entries from the current Org buffer and store them 2306 in the same directory, using a file extension =.ics=. 2307 2308 - {{{kbd(C-c C-e c c)}}} :: 2309 2310 Create a combined iCalendar file from Org files in 2311 ~org-agenda-files~ and write it to 2312 ~org-icalendar-combined-agenda-file~ file name. 2313 2314 * Publishing 2315 :PROPERTIES: 2316 :DESCRIPTION: Create a web site of linked Org files. 2317 :END: 2318 2319 Org includes a publishing management system that allows you to 2320 configure automatic HTML conversion of /projects/ composed of 2321 interlinked Org files. You can also configure Org to automatically 2322 upload your exported HTML pages and related attachments, such as 2323 images and source code files, to a web server. 2324 2325 You can also use Org to convert files into PDF, or even combine HTML 2326 and PDF conversion so that files are available in both formats on the 2327 server. 2328 2329 For detailed instructions about setup, see the manual. Here is an 2330 example: 2331 2332 #+begin_src emacs-lisp 2333 (setq org-publish-project-alist 2334 '(("org" 2335 :base-directory "~/org/" 2336 :publishing-function org-html-publish-to-html 2337 :publishing-directory "~/public_html" 2338 :section-numbers nil 2339 :with-toc nil 2340 :html-head "<link rel=\"stylesheet\" 2341 href=\"../other/mystyle.css\" 2342 type=\"text/css\"/>"))) 2343 #+end_src 2344 2345 - {{{kbd(C-c C-e P x)}}} :: 2346 2347 Prompt for a specific project and publish all files that belong to 2348 it. 2349 2350 - {{{kbd(C-c C-e P p)}}} :: 2351 2352 Publish the project containing the current file. 2353 2354 - {{{kbd(C-c C-e P f)}}} :: 2355 2356 Publish only the current file. 2357 2358 - {{{kbd(C-c C-e P a)}}} :: 2359 2360 Publish every project. 2361 2362 Org uses timestamps to track when a file has changed. The above 2363 functions normally only publish changed files. You can override this 2364 and force publishing of all files by giving a prefix argument to any 2365 of the commands above. 2366 2367 * Working with Source Code 2368 :PROPERTIES: 2369 :DESCRIPTION: Export, evaluate, and tangle code blocks. 2370 :END: 2371 2372 Org mode provides a number of features for working with source code, 2373 including editing of code blocks in their native major mode, 2374 evaluation of code blocks, tangling of code blocks, and exporting code 2375 blocks and their results in several formats. 2376 2377 A source code block conforms to this structure: 2378 2379 #+begin_example 2380 ,#+NAME: <name> 2381 ,#+BEGIN_SRC <language> <switches> <header arguments> 2382 <body> 2383 ,#+END_SRC 2384 #+end_example 2385 2386 #+texinfo: @noindent 2387 where: 2388 2389 - =<name>= is a string used to uniquely name the code block, 2390 2391 - =<language>= specifies the language of the code block, e.g., 2392 =emacs-lisp=, =shell=, =R=, =python=, etc., 2393 2394 - =<switches>= can be used to control export of the code block, 2395 2396 - =<header arguments>= can be used to control many aspects of code 2397 block behavior as demonstrated below, 2398 2399 - =<body>= contains the actual source code. 2400 2401 Use {{{kbd(C-c ')}}} to edit the current code block. It opens a new 2402 major mode edit buffer containing the body of the source code block, 2403 ready for any edits. Use {{{kbd(C-c ')}}} again to close the buffer 2404 and return to the Org buffer. 2405 2406 ** Using header arguments 2407 :PROPERTIES: 2408 :UNNUMBERED: notoc 2409 :END: 2410 2411 A header argument is specified with an initial colon followed by the 2412 argument's name in lowercase. 2413 2414 Header arguments can be set in several ways; Org prioritizes them in 2415 case of overlaps or conflicts by giving local settings a higher 2416 priority. 2417 2418 - System-wide header arguments :: 2419 2420 Those are specified by customizing ~org-babel-default-header-args~ 2421 variable, or, for a specific language {{{var(LANG)}}} 2422 ~org-babel-default-header-args:LANG~. 2423 2424 - Header arguments in properties :: 2425 2426 You can set them using =header-args= property (see [[*Properties]])---or 2427 =header-args:LANG= for language {{{var(LANG)}}}. Header arguments 2428 set through properties drawers apply at the sub-tree level on down. 2429 2430 - Header arguments in code blocks :: 2431 2432 Header arguments are most commonly set at the source code block 2433 level, on the =BEGIN_SRC= line: 2434 2435 #+begin_example 2436 ,#+NAME: factorial 2437 ,#+BEGIN_SRC haskell :results silent :exports code :var n=0 2438 fac 0 = 1 2439 fac n = n * fac (n-1) 2440 ,#+END_SRC 2441 #+end_example 2442 2443 Code block header arguments can span multiple lines using =HEADER= 2444 keyword on each line. 2445 2446 ** Evaluating code blocks 2447 :PROPERTIES: 2448 :UNNUMBERED: notoc 2449 :END: 2450 2451 Use {{{kbd(C-c C-c)}}} to evaluate the current code block and insert 2452 its results in the Org document. By default, evaluation is only 2453 turned on for =emacs-lisp= code blocks, however support exists for 2454 evaluating blocks in many languages. For a complete list of supported 2455 languages see the manual. The following shows a code block and its 2456 results. 2457 2458 #+begin_example 2459 ,#+BEGIN_SRC emacs-lisp 2460 (+ 1 2 3 4) 2461 ,#+END_SRC 2462 2463 ,#+RESULTS: 2464 : 10 2465 #+end_example 2466 2467 The following syntax is used to pass arguments to code blocks using 2468 the =var= header argument. 2469 2470 : :var NAME=ASSIGN 2471 2472 #+texinfo: @noindent 2473 {{{var(NAME)}}} is the name of the variable bound in the code block 2474 body. {{{var(ASSIGN)}}} is a literal value, such as a string, 2475 a number, a reference to a table, a list, a literal example, another 2476 code block---with or without arguments---or the results of evaluating 2477 a code block. 2478 2479 ** Results of evaluation 2480 :PROPERTIES: 2481 :UNNUMBERED: notoc 2482 :END: 2483 2484 How Org handles results of a code block execution depends on many 2485 header arguments working together. The primary determinant, however, 2486 is the =results= header argument. It controls the /collection/, 2487 /type/, /format/, and /handling/ of code block results. 2488 2489 - Collection :: 2490 2491 How the results should be collected from the code block. You may 2492 choose either =output= or =value= (the default). 2493 2494 - Type :: 2495 2496 What result types to expect from the execution of the code block. 2497 You may choose among =table=, =list=, =scalar=, and =file=. Org 2498 tries to guess it if you do not provide it. 2499 2500 - Format :: 2501 2502 How Org processes results. Some possible values are =code=, 2503 =drawer=, =html=, =latex=, =link=, and =raw=. 2504 2505 - Handling :: 2506 2507 How to insert the results once properly formatted. Allowed values 2508 are =silent=, =replace= (the default), =append=, or =prepend=. 2509 2510 Code blocks which output results to files---e.g.: graphs, diagrams and 2511 figures---can accept a =:file FILENAME= header argument, in which case 2512 the results are saved to the named file, and a link to the file is 2513 inserted into the buffer. 2514 2515 ** Exporting code blocks 2516 :PROPERTIES: 2517 :UNNUMBERED: notoc 2518 :END: 2519 2520 It is possible to export the /code/ of code blocks, the /results/ of 2521 code block evaluation, /both/ the code and the results of code block 2522 evaluation, or /none/. Org defaults to exporting /code/ for most 2523 languages. 2524 2525 The =exports= header argument is to specify if that part of the Org 2526 file is exported to, say, HTML or LaTeX formats. It can be set to 2527 either =code=, =results=, =both= or =none=. 2528 2529 ** Extracting source code 2530 :PROPERTIES: 2531 :UNNUMBERED: notoc 2532 :END: 2533 2534 Use {{{kbd(C-c C-v t)}}} to create pure source code files by 2535 extracting code from source blocks in the current buffer. This is 2536 referred to as "tangling"---a term adopted from the literate 2537 programming community. During tangling of code blocks their bodies 2538 are expanded using ~org-babel-expand-src-block~, which can expand both 2539 variable and "Noweb" style references. In order to tangle a code 2540 block it must have a =tangle= header argument, see the manual for 2541 details. 2542 2543 * Miscellaneous 2544 :PROPERTIES: 2545 :DESCRIPTION: All the rest which did not fit elsewhere. 2546 :END: 2547 2548 ** Completion 2549 :PROPERTIES: 2550 :UNNUMBERED: notoc 2551 :END: 2552 2553 Org has in-buffer completions with {{{kbd(M-TAB)}}}. No minibuffer is 2554 involved. Type one or more letters and invoke the hot key to complete 2555 the text in-place. 2556 2557 For example, this command will complete TeX symbols after =\=, TODO 2558 keywords at the beginning of a headline, and tags after =:= in 2559 a headline. 2560 2561 2562 ** Structure Templates 2563 :PROPERTIES: 2564 :UNNUMBERED: notoc 2565 :END: 2566 2567 To quickly insert empty structural blocks, such as =#+BEGIN_SRC= 2568 ... =#+END_SRC=, or to wrap existing text in such a block, use 2569 2570 - {{{kbd(C-c C-\,)}}} :: 2571 2572 Prompt for a type of block structure, and insert the block at point. 2573 If the region is active, it is wrapped in the block. 2574 2575 ** Clean view 2576 :PROPERTIES: 2577 :UNNUMBERED: notoc 2578 :END: 2579 2580 Org's default outline with stars and no indents can become too 2581 cluttered for short documents. For /book-like/ long documents, the 2582 effect is not as noticeable. Org provides an alternate stars and 2583 indentation scheme, as shown on the right in the following table. It 2584 uses only one star and indents text to line with the heading: 2585 2586 #+begin_example 2587 ,* Top level headline | * Top level headline 2588 ,** Second level | * Second level 2589 ,*** Third level | * Third level 2590 some text | some text 2591 ,*** Third level | * Third level 2592 more text | more text 2593 ,* Another top level headline | * Another top level headline 2594 #+end_example 2595 2596 This kind of view can be achieved dynamically at display time using 2597 Org Indent mode ({{{kbd(M-x org-indent-mode RET)}}}), which prepends 2598 intangible space to each line. You can turn on Org Indent mode for 2599 all files by customizing the variable ~org-startup-indented~, or you 2600 can turn it on for individual files using 2601 2602 : #+STARTUP: indent 2603 2604 If you want the indentation to be hard space characters so that the 2605 plain text file looks as similar as possible to the Emacs display, Org 2606 supports you by helping to indent (with {{{kbd(TAB)}}}) text below 2607 each headline, by hiding leading stars, and by only using levels 1, 3, 2608 etc to get two characters indentation for each level. To get this 2609 support in a file, use 2610 2611 : #+STARTUP: hidestars odd 2612 2613 * Export Setup :noexport: 2614 2615 #+setupfile: doc-setup.org 2616 2617 #+export_file_name: orgguide.texi 2618 2619 #+texinfo_dir_category: Emacs editing modes 2620 #+texinfo_dir_title: Org Guide: (orgguide) 2621 #+texinfo_dir_desc: Abbreviated Org mode manual 2622 2623 * Footnotes 2624 2625 [fn:1] See the variable ~org-special-ctrl-a/e~ to configure special 2626 behavior of {{{kbd(C-a)}}} and {{{kbd(C-e)}}} in headlines. 2627 2628 [fn:2] If you do not want the line to be split, customize the variable 2629 ~org-M-RET-may-split-line~. 2630 2631 [fn:3] See also the variable ~org-show-context-detail~ to decide how 2632 much context is shown around each match. 2633 2634 [fn:4] The corresponding in-buffer setting is =#+STARTUP: logdone=. 2635 2636 [fn:5] The corresponding in-buffer setting is =#+STARTUP: 2637 logenotedone=. 2638 2639 [fn:6] As with all these in-buffer settings, pressing {{{kbd(C-c 2640 C-c)}}} activates any changes in the line. 2641 2642 [fn:7] This is quite different from what is normally understood by 2643 /scheduling a meeting/, which is done in Org by just inserting a time 2644 stamp without keyword. 2645 2646 [fn:8] It will still be listed on that date after it has been marked 2647 as done. If you do not like this, set the variable 2648 ~org-agenda-skip-scheduled-if-done~. 2649 2650 [fn:9] Using capture templates, you get finer control over capture 2651 locations. See [[*Capture templates]]. 2652 2653 [fn:10] If you need one of these sequences literally, escape the =%= 2654 with a backslash.