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