org.texi (876816B)
1 \input texinfo @c -*- texinfo -*- 2 @c %**start of header 3 @setfilename org.info 4 @settitle The Org Manual 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 This manual is for Org version 9.6. 17 18 Copyright @copyright{} 2004--2023 Free Software Foundation, Inc. 19 20 @quotation 21 Permission is granted to copy, distribute and/or modify this document 22 under the terms of the GNU Free Documentation License, Version 1.3 or 23 any later version published by the Free Software Foundation; with no 24 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' 25 and with the Back-Cover Texts as in (a) below. A copy of the license 26 is included in the section entitled ``GNU Free Documentation License.'' 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 Mode: (org). Outline-based notes management and organizer. 37 @end direntry 38 39 @finalout 40 @titlepage 41 @title The Org Manual 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 The Org Manual 54 55 @insertcopying 56 @end ifnottex 57 58 @menu 59 * Introduction:: Getting started. 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 and Columns:: Storing information about an entry. 66 * Dates and Times:: Making items useful for planning. 67 * Refiling and Archiving:: Moving and copying information with ease. 68 * Capture and Attachments:: Dealing with external data. 69 * Agenda Views:: Collecting information into views. 70 * Markup for Rich Contents:: Compose beautiful documents. 71 * Exporting:: Sharing and publishing notes. 72 * Publishing:: Create a web site of linked Org files. 73 * Citation handling:: create, follow and export citations. 74 * Working with Source Code:: Export, evaluate, and tangle code blocks. 75 * Miscellaneous:: All the rest which did not fit elsewhere. 76 * Hacking:: How to hack your way around. 77 * History and Acknowledgments:: How Org came into being. 78 * GNU Free Documentation License:: The license for this documentation. 79 * Main Index:: An index of Org's concepts and features. 80 * Key Index:: Key bindings and where they are described. 81 * Command and Function Index:: Command names and some internal functions. 82 * Variable Index:: Variables mentioned in the manual. 83 84 @detailmenu 85 --- The Detailed Node Listing --- 86 87 Introduction 88 89 * Summary:: Brief summary of what Org does. 90 * Installation:: Installing Org. 91 * Activation:: How to activate Org for certain buffers. 92 * Feedback:: Bug reports, ideas, patches, etc. 93 * Conventions:: Typesetting conventions used in this manual. 94 95 Document Structure 96 97 * Headlines:: How to typeset Org tree headlines. 98 * Visibility Cycling:: Show and hide, much simplified. 99 * Motion:: Jumping to other headlines. 100 * Structure Editing:: Changing sequence and level of headlines. 101 * Sparse Trees:: Matches embedded in context. 102 * Plain Lists:: Additional structure within an entry. 103 * Drawers:: Tucking stuff away. 104 * Blocks:: Folding blocks. 105 106 Visibility Cycling 107 108 * Global and local cycling:: Cycling through various visibility states. 109 * Initial visibility:: Setting the initial visibility state. 110 * Catching invisible edits:: Preventing mistakes when editing invisible parts. 111 112 Tables 113 114 * Built-in Table Editor:: Simple tables. 115 * Column Width and Alignment:: Overrule the automatic settings. 116 * Column Groups:: Grouping to trigger vertical lines. 117 * Orgtbl Mode:: The table editor as minor mode. 118 * The Spreadsheet:: The table editor has spreadsheet capabilities. 119 * Org Plot:: Plotting from Org tables. 120 121 The Spreadsheet 122 123 * References:: How to refer to another field or range. 124 * Formula syntax for Calc:: Using Calc to compute stuff. 125 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp. 126 * Durations and time values:: How to compute durations and time values. 127 * Field and range formulas:: Formula for specific (ranges of) fields. 128 * Column formulas:: Formulas valid for an entire column. 129 * Lookup functions:: Lookup functions for searching tables. 130 * Editing and debugging formulas:: Fixing formulas. 131 * Updating the table:: Recomputing all dependent fields. 132 * Advanced features:: Field and column names, automatic recalculation... 133 134 Hyperlinks 135 136 * Link Format:: How links in Org are formatted. 137 * Internal Links:: Links to other places in the current file. 138 * Radio Targets:: Make targets trigger links in plain text. 139 * External Links:: URL-like links to the world. 140 * Handling Links:: Creating, inserting and following. 141 * Using Links Outside Org:: Linking from my C source code? 142 * Link Abbreviations:: Shortcuts for writing complex links. 143 * Search Options:: Linking to a specific location. 144 * Custom Searches:: When the default search is not enough. 145 146 TODO Items 147 148 * TODO Basics:: Marking and displaying TODO entries. 149 * TODO Extensions:: Workflow and assignments. 150 * Progress Logging:: Dates and notes for progress. 151 * Priorities:: Some things are more important than others. 152 * Breaking Down Tasks:: Splitting a task into manageable pieces. 153 * Checkboxes:: Tick-off lists. 154 155 TODO Extensions 156 157 * Workflow states:: From TODO to DONE in steps. 158 * TODO types:: I do this, Fred does the rest. 159 * Multiple sets in one file:: Mixing it all, still finding your way. 160 * Fast access to TODO states:: Single letter selection of state. 161 * Per-file keywords:: Different files, different requirements. 162 * Faces for TODO keywords:: Highlighting states. 163 * TODO dependencies:: When one task needs to wait for others. 164 165 Progress Logging 166 167 * Closing items:: When was this entry marked as done? 168 * Tracking TODO state changes:: When did the status change? 169 * Tracking your habits:: How consistent have you been? 170 171 Tags 172 173 * Tag Inheritance:: Tags use the tree structure of an outline. 174 * Setting Tags:: How to assign tags to a headline. 175 * Tag Hierarchy:: Create a hierarchy of tags. 176 * Tag Searches:: Searching for combinations of tags. 177 178 Properties and Columns 179 180 * Property Syntax:: How properties are spelled out. 181 * Special Properties:: Access to other Org mode features. 182 * Property Searches:: Matching property values. 183 * Property Inheritance:: Passing values down a tree. 184 * Column View:: Tabular viewing and editing. 185 186 Column View 187 188 * Defining columns:: The COLUMNS format property. 189 * Using column view:: How to create and use column view. 190 * Capturing column view:: A dynamic block for column view. 191 192 Defining columns 193 194 * Scope of column definitions:: Where defined, where valid? 195 * Column attributes:: Appearance and content of a column. 196 197 Dates and Times 198 199 * Timestamps:: Assigning a time to a tree entry. 200 * Creating Timestamps:: Commands to insert timestamps. 201 * Deadlines and Scheduling:: Planning your work. 202 * Clocking Work Time:: Tracking how long you spend on a task. 203 * Effort Estimates:: Planning work effort in advance. 204 * Timers:: Notes with a running timer. 205 206 Creating Timestamps 207 208 * The date/time prompt:: How Org mode helps you enter dates and times. 209 * Custom time format:: Making dates look different. 210 211 Deadlines and Scheduling 212 213 * Inserting deadline/schedule:: Planning items. 214 * Repeated tasks:: Items that show up again and again. 215 216 Clocking Work Time 217 218 * Clocking commands:: Starting and stopping a clock. 219 * The clock table:: Detailed reports. 220 * Resolving idle time:: Resolving time when you've been idle. 221 222 Refiling and Archiving 223 224 * Refile and Copy:: Moving/copying a tree from one place to another. 225 * Archiving:: What to do with finished products. 226 227 Archiving 228 229 * Moving subtrees:: Moving a tree to an archive file. 230 * Internal archiving:: Switch off a tree but keep it in the file. 231 232 Capture and Attachments 233 234 * Capture:: Capturing new stuff. 235 * Attachments:: Attach files to outlines. 236 * RSS Feeds:: Getting input from RSS feeds. 237 238 Capture 239 240 * Setting up capture:: Where notes will be stored. 241 * Using capture:: Commands to invoke and terminate capture. 242 * Capture templates:: Define the outline of different note types. 243 244 Capture templates 245 246 * Template elements:: What is needed for a complete template entry. 247 * Template expansion:: Filling in information about time and context. 248 * Templates in contexts:: Only show a template in a specific context. 249 250 Attachments 251 252 * Attachment defaults and dispatcher:: How to access attachment commands 253 * Attachment options:: Configuring the attachment system 254 * Attachment links:: Hyperlink access to attachments 255 * Automatic version-control with Git:: Everything safely stored away 256 * Attach from Dired:: Using dired to select an attachment 257 258 Agenda Views 259 260 * Agenda Files:: Files being searched for agenda information. 261 * Agenda Dispatcher:: Keyboard access to agenda views. 262 * Built-in Agenda Views:: What is available out of the box? 263 * Presentation and Sorting:: How agenda items are prepared for display. 264 * Agenda Commands:: Remote editing of Org trees. 265 * Custom Agenda Views:: Defining special searches and views. 266 * Exporting Agenda Views:: Writing a view to a file. 267 * Agenda Column View:: Using column view for collected entries. 268 269 Built-in Agenda Views 270 271 * Weekly/daily agenda:: The calendar page with current tasks. 272 * Global TODO list:: All unfinished action items. 273 * Matching tags and properties:: Structured information with fine-tuned search. 274 * Search view:: Find entries by searching for text. 275 * Stuck projects:: Find projects you need to review. 276 277 Presentation and Sorting 278 279 * Categories:: Not all tasks are equal. 280 * Time-of-day specifications:: How the agenda knows the time. 281 * Sorting of agenda items:: The order of things. 282 * Filtering/limiting agenda items:: Dynamically narrow the agenda. 283 284 Custom Agenda Views 285 286 * Storing searches:: Type once, use often. 287 * Block agenda:: All the stuff you need in a single buffer. 288 * Setting options:: Changing the rules. 289 290 Markup for Rich Contents 291 292 * Paragraphs:: The basic unit of text. 293 * Emphasis and Monospace:: Bold, italic, etc. 294 * Subscripts and Superscripts:: Simple syntax for raising/lowering text. 295 * Special Symbols:: Greek letters and other symbols. 296 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents. 297 * Literal Examples:: Source code examples with special formatting. 298 * Images:: Display an image. 299 * Captions:: Describe tables, images... 300 * Horizontal Rules:: Make a line. 301 * Creating Footnotes:: Edit and read footnotes. 302 303 Embedded @LaTeX{} 304 305 * @LaTeX{} fragments:: Complex formulas made easy. 306 * Previewing @LaTeX{} fragments:: What will this snippet look like? 307 * CD@LaTeX{} mode:: Speed up entering of formulas. 308 309 Exporting 310 311 * The Export Dispatcher:: The main interface. 312 * Export Settings:: Common export settings. 313 * Table of Contents:: The if and where of the table of contents. 314 * Include Files:: Include additional files into a document. 315 * Macro Replacement:: Use macros to create templates. 316 * Comment Lines:: What will not be exported. 317 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding. 318 * Beamer Export:: Producing presentations and slides. 319 * HTML Export:: Exporting to HTML. 320 * @LaTeX{} Export:: Exporting to @LaTeX{} and processing to PDF. 321 * Markdown Export:: Exporting to Markdown. 322 * OpenDocument Text Export:: Exporting to OpenDocument Text. 323 * Org Export:: Exporting to Org. 324 * Texinfo Export:: Exporting to Texinfo. 325 * iCalendar Export:: Exporting to iCalendar. 326 * Other Built-in Back-ends:: Exporting to a man page. 327 * Advanced Export Configuration:: Fine-tuning the export output. 328 * Export in Foreign Buffers:: Author tables and lists in Org syntax. 329 330 Beamer Export 331 332 * Beamer export commands:: For creating Beamer documents. 333 * Beamer specific export settings:: For customizing Beamer export. 334 * Frames and Blocks in Beamer:: For composing Beamer slides. 335 * Beamer specific syntax:: For using in Org documents. 336 * Editing support:: Editing support. 337 * A Beamer example:: A complete presentation. 338 339 HTML Export 340 341 * HTML export commands:: Invoking HTML export. 342 * HTML specific export settings:: Settings for HTML export. 343 * HTML doctypes:: Exporting various (X)HTML flavors. 344 * HTML preamble and postamble:: Inserting preamble and postamble. 345 * Quoting HTML tags:: Using direct HTML in Org files. 346 * Headlines in HTML export:: Formatting headlines. 347 * Links in HTML export:: Inserting and formatting links. 348 * Tables in HTML export:: How to modify the formatting of tables. 349 * Images in HTML export:: How to insert figures into HTML output. 350 * Math formatting in HTML export:: Beautiful math also on the web. 351 * Text areas in HTML export:: An alternate way to show an example. 352 * CSS support:: Changing the appearance of the output. 353 * JavaScript support:: Info and folding in a web browser. 354 355 @LaTeX{} Export 356 357 * @LaTeX{}/PDF export commands:: For producing @LaTeX{} and PDF documents. 358 * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end. 359 * @LaTeX{} header and sectioning:: Setting up the export file structure. 360 * Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code. 361 * Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{}. 362 * Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output. 363 * Plain lists in @LaTeX{} export:: Attributes specific to lists. 364 * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks. 365 * Example blocks in @LaTeX{} export:: Attributes specific to example blocks. 366 * Special blocks in @LaTeX{} export:: Attributes specific to special blocks. 367 * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules. 368 * Verse blocks in @LaTeX{} export:: Attributes specific to special blocks. 369 * Quote blocks in @LaTeX{} export:: Attributes specific to quote blocks. 370 371 OpenDocument Text Export 372 373 * Pre-requisites for ODT export:: Required packages. 374 * ODT export commands:: Invoking export. 375 * ODT specific export settings:: Configuration options. 376 * Extending ODT export:: Producing DOC, PDF files. 377 * Applying custom styles:: Styling the output. 378 * Links in ODT export:: Handling and formatting links. 379 * Tables in ODT export:: Org tables conversions. 380 * Images in ODT export:: Inserting images. 381 * Math formatting in ODT export:: Formatting @LaTeX{} fragments. 382 * Labels and captions in ODT export:: Rendering objects. 383 * Literal examples in ODT export:: For source code and example blocks. 384 * Advanced topics in ODT export:: For power users. 385 386 Math formatting in ODT export 387 388 * @LaTeX{} math snippets:: Embedding in @LaTeX{} format. 389 * MathML and OpenDocument formula files:: Embedding in native format. 390 391 Texinfo Export 392 393 * Texinfo export commands:: Invoking commands. 394 * Texinfo specific export settings:: Setting the environment. 395 * Texinfo file header:: Generating the header. 396 * Texinfo title and copyright page:: Creating preamble pages. 397 * Info directory file:: Installing a manual in Info file hierarchy. 398 * Headings and sectioning structure:: Building document structure. 399 * Indices:: Creating indices. 400 * Quoting Texinfo code:: Incorporating literal Texinfo code. 401 * Plain lists in Texinfo export:: List attributes. 402 * Tables in Texinfo export:: Table attributes. 403 * Images in Texinfo export:: Image attributes. 404 * Quotations in Texinfo export:: Quote block attributes. 405 * Key bindings in Texinfo export:: @@kbd Texinfo command. 406 * Special blocks in Texinfo export:: Special block attributes. 407 * A Texinfo example:: Processing Org to Texinfo. 408 409 Export in Foreign Buffers 410 411 * Bare HTML:: Exporting HTML without CSS, Javascript, etc. 412 413 Publishing 414 415 * Configuration:: Defining projects. 416 * Uploading Files:: How to get files up on the server. 417 * Sample Configuration:: Example projects. 418 * Triggering Publication:: Publication commands. 419 420 Configuration 421 422 * Project alist:: The central configuration variable. 423 * Sources and destinations:: From here to there. 424 * Selecting files:: What files are part of the project? 425 * Publishing action:: Setting the function doing the publishing. 426 * Publishing options:: Tweaking HTML/@LaTeX{} export. 427 * Publishing links:: Which links keep working after publishing? 428 * Site map:: Generating a list of all pages. 429 * Generating an index:: An index that reaches across pages. 430 431 Sample Configuration 432 433 * Simple example:: One-component publishing. 434 * Complex example:: A multi-component publishing example. 435 436 Citation handling 437 438 * Citations:: 439 * Citation export processors:: 440 * Bibliography printing:: 441 442 Bibliography printing 443 444 * Bibliography options in the ``biblatex'' and ``csl'' export processors:: 445 446 Working with Source Code 447 448 * Features Overview:: Enjoy the versatility of source blocks. 449 * Structure of Code Blocks:: Code block syntax described. 450 * Using Header Arguments:: Different ways to set header arguments. 451 * Environment of a Code Block:: Arguments, sessions, working directory... 452 * Evaluating Code Blocks:: Place results of evaluation in the Org buffer. 453 * Results of Evaluation:: Choosing a results type, post-processing... 454 * Exporting Code Blocks:: Export contents and/or results. 455 * Extracting Source Code:: Create pure source code files. 456 * Languages:: List of supported code block languages. 457 * Editing Source Code:: Language major-mode editing. 458 * Noweb Reference Syntax:: Literate programming in Org mode. 459 * Library of Babel:: Use and contribute to a library of useful code blocks. 460 * Key bindings and Useful Functions:: Work quickly with code blocks. 461 * Batch Execution:: Call functions from the command line. 462 463 Miscellaneous 464 465 * Completion:: @kbd{M-@key{TAB}} guesses completions. 466 * Structure Templates:: Quick insertion of structural elements. 467 * Speed Keys:: Electric commands at the beginning of a headline. 468 * Clean View:: Getting rid of leading stars in the outline. 469 * Execute commands in the active region:: Execute commands on multiple items in Org or agenda view. 470 * Dynamic Headline Numbering:: Display and update outline numbering. 471 * The Very Busy @kbd{C-c C-c} Key:: When in doubt, press @kbd{C-c C-c}. 472 * In-buffer Settings:: Overview of keywords. 473 * Regular Expressions:: Elisp regular expressions. 474 * Org Syntax:: Formal description of Org's syntax. 475 * Documentation Access:: Read documentation about current syntax. 476 * Escape Character:: Prevent Org from interpreting your writing. 477 * Code Evaluation Security:: Org files evaluate in-line code. 478 * Interaction:: With other Emacs packages. 479 * TTY Keys:: Using Org on a tty. 480 * Protocols:: External access to Emacs and Org. 481 * Org Crypt:: Encrypting Org files. 482 * Org Mobile:: Viewing and capture on a mobile device. 483 484 Clean View 485 486 * Org Indent Mode:: 487 * Hard indentation:: 488 489 Interaction 490 491 * Cooperation:: Packages Org cooperates with. 492 * Conflicts:: Packages that lead to conflicts. 493 494 Protocols 495 496 * The @code{store-link} protocol:: Store a link, push URL to kill-ring. 497 * The @code{capture} protocol:: Fill a buffer with external information. 498 * The @code{open-source} protocol:: Edit published contents. 499 500 Org Mobile 501 502 * Setting up the staging area:: For the mobile device. 503 * Pushing to the mobile application:: Uploading Org files and agendas. 504 * Pulling from the mobile application:: Integrating captured and flagged items. 505 506 Hacking 507 508 * Hooks:: How to reach into Org's internals. 509 * Add-on Packages:: Available extensions. 510 * Adding Hyperlink Types:: New custom link types. 511 * Adding Export Back-ends:: How to write new export back-ends. 512 * Tables in Arbitrary Syntax:: Orgtbl for LaTeX and other programs. 513 * Dynamic Blocks:: Automatically filled blocks. 514 * Special Agenda Views:: Customized views. 515 * Speeding Up Your Agendas:: Tips on how to speed up your agendas. 516 * Extracting Agenda Information:: Post-processing agenda information. 517 * Using the Property API:: Writing programs that use entry properties. 518 * Using the Mapping API:: Mapping over all or selected entries. 519 520 Tables in Arbitrary Syntax 521 522 * Radio tables:: Sending and receiving radio tables. 523 * A @LaTeX{} example:: Step by step, almost a tutorial. 524 * Translator functions:: Copy and modify. 525 526 @end detailmenu 527 @end menu 528 529 @node Introduction 530 @chapter Introduction 531 532 @cindex introduction 533 534 @menu 535 * Summary:: Brief summary of what Org does. 536 * Installation:: Installing Org. 537 * Activation:: How to activate Org for certain buffers. 538 * Feedback:: Bug reports, ideas, patches, etc. 539 * Conventions:: Typesetting conventions used in this manual. 540 @end menu 541 542 @node Summary 543 @section Summary 544 545 @cindex summary 546 547 Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. 548 It relies on a lightweight plain-text markup language used in files 549 with the @samp{.org} extension. 550 551 As an authoring tool, Org helps you write structured documents and 552 provides exporting facilities. Org files can also be used for literate 553 programming and reproducible research. As a TODO lists manager, Org 554 helps you organize your tasks in a flexible way, from daily needs to 555 detailed project-planning, allowing logging, multiple views on your 556 tasks, exporting your agendas, etc. 557 558 Org mode is implemented on top of Outline mode, which makes it 559 possible to keep the content of large files well structured. 560 Visibility cycling and structure editing help to work with the tree. 561 Tables are easily created with a built-in table editor. Plain text 562 URL-like links connect to websites, emails, Usenet messages, BBDB 563 entries, and any files related to the projects. 564 565 Org develops organizational tasks around notes files that contain 566 lists or information about projects as plain text. Project planning 567 and task management make use of metadata which is part of an outline 568 node. Based on this data, specific entries can be extracted in 569 queries and create dynamic @emph{agenda views} that also integrate the Emacs 570 calendar and diary. Org can be used to implement many different 571 project planning schemes, such as David Allen's GTD system. 572 573 Org files can serve as a single source authoring system with export to 574 many different formats such as HTML, @LaTeX{}, Open Document, and 575 Markdown. New export backends can be derived from existing ones, or 576 defined from scratch. 577 578 Org files can include source code blocks, which makes Org uniquely 579 suited for authoring technical documents with code examples. Org 580 source code blocks are fully functional; they can be evaluated in 581 place and their results can be captured in the file. This makes it 582 possible to create a single file reproducible research compendium. 583 584 Org keeps simple things simple. When first fired up, it should feel 585 like a straightforward, easy to use outliner. Complexity is not 586 imposed, but a large amount of functionality is available when needed. 587 Org is a toolbox. Many users actually run only a---very 588 personal---fraction of Org's capabilities, and know that there is more 589 whenever they need it. 590 591 All of this is achieved with strictly plain text files, the most 592 portable and future-proof file format. Org runs in Emacs. Emacs is 593 one of the most widely ported programs, so that Org mode is available 594 on every major platform. 595 596 @cindex FAQ 597 There is a website for Org which provides links to the newest version 598 of Org, as well as additional information, frequently asked questions 599 (FAQ), links to tutorials, etc. This page is located at 600 @uref{https://orgmode.org}. 601 602 @cindex print edition 603 An earlier version (7.3) of this manual was available as a paperback 604 book from the Network Theory Ltd. publishing company, closed in 2009. 605 606 @node Installation 607 @section Installation 608 609 @cindex installation 610 611 Org is included in distributions of GNU Emacs, you probably do not 612 need to install it. Most users will simply activate Org and begin 613 exploring its features. 614 615 If, for one reason or another, you want to install Org on top of this 616 pre-packaged version, you can use the Emacs package system or clone 617 Org's git repository. We @strong{strongly recommend} sticking to a single 618 installation method. 619 620 When installing Org on top of the pre-packaged version, please note 621 that Org stable versions are meant to be fully compatible with the 622 last three stable versions of Emacs but not with older Emacsen. 623 624 @anchor{Using Emacs packaging system} 625 @subheading Using Emacs packaging system 626 627 Recent Emacs distributions include a packaging system which lets you 628 install Elisp libraries. You can install Org from the ``package menu'', 629 with @kbd{M-x list-packages}. See @ref{Package Menu,Package Menu,,emacs,}. 630 631 @quotation Important 632 You need to do this in a session where no @samp{.org} file has been 633 visited, i.e., where no Org built-in function have been loaded. 634 Otherwise autoload Org functions will mess up the installation. 635 636 @end quotation 637 638 @anchor{Using Org's git repository} 639 @subheading Using Org's git repository 640 641 You can clone Org's repository and install Org like this: 642 643 @example 644 $ cd ~/src/ 645 $ git clone https://git.savannah.gnu.org/git/emacs/org-mode.git 646 $ cd org-mode/ 647 $ make autoloads 648 @end example 649 650 Note that in this case, @samp{make autoloads} is mandatory: it defines 651 Org's version in @samp{org-version.el} and Org's autoloads in 652 @samp{org-loaddefs.el}. 653 654 Make sure you set the load path correctly in your Emacs init file: 655 656 @lisp 657 (add-to-list 'load-path "~/src/org-mode/lisp") 658 @end lisp 659 660 You can also compile with @samp{make}, generate the documentation with 661 @samp{make doc}, create a local configuration with @samp{make config} and 662 install Org with @samp{make install}. Please run @samp{make help} to get the 663 list of compilation/installation options. 664 665 For more detailed explanations on Org's build system, please check the 666 Org Build System page on @uref{https://orgmode.org/worg/dev/org-build-system.html, Worg}. 667 668 @anchor{Installing Org's contributed packages} 669 @subheading Installing Org's contributed packages 670 671 Org's repository used to contain @samp{contrib/} directory for add-ons 672 contributed by others. As of Org 9.5, the directory has been moved to 673 the dedicated org-contrib @uref{https://git.sr.ht/~bzg/org-contrib, repository}, which you can install 674 separately as a @uref{https://elpa.nongnu.org/nongnu/org-contrib.html, package} from NonGNU ELPA@. 675 676 There are enough valuable packages maintained outside of the Org repository. 677 Worg has a list of @uref{https://orgmode.org/worg/org-contrib/index.html, org-contrib and external packages}, certainly it is not 678 exhaustive. 679 680 @node Activation 681 @section Activation 682 683 @cindex activation 684 @cindex autoload 685 @cindex ELPA 686 @cindex global key bindings 687 @cindex key bindings, global 688 689 Org mode buffers need Font Lock to be turned on: this is the default 690 in Emacs@footnote{ If you do not use Font Lock globally turn it on in Org 691 buffer with @samp{(add-hook 'org-mode-hook #'turn-on-font-lock)}.}. 692 693 There are compatibility issues between Org mode and some other Elisp 694 packages (see @ref{Conflicts}). Please take the 695 time to check the list. 696 697 @findex org-agenda 698 @findex org-capture 699 @findex org-store-link 700 For a better experience, the three Org commands @code{org-store-link}, 701 @code{org-capture} and @code{org-agenda} ought to be accessible anywhere in 702 Emacs, not just in Org buffers. To that effect, you need to bind them 703 to globally available keys, like the ones reserved for users (see 704 @ref{Key Binding Conventions,,,elisp,}). Here are suggested bindings, 705 please modify the keys to your own liking. 706 707 @lisp 708 (global-set-key (kbd "C-c l") #'org-store-link) 709 (global-set-key (kbd "C-c a") #'org-agenda) 710 (global-set-key (kbd "C-c c") #'org-capture) 711 @end lisp 712 713 @cindex Org mode, turning on 714 Files with the @samp{.org} extension use Org mode by default. To turn on 715 Org mode in a file that does not have the extension @samp{.org}, make the 716 first line of a file look like this: 717 718 @example 719 MY PROJECTS -*- mode: org; -*- 720 @end example 721 722 723 @vindex org-insert-mode-line-in-empty-file 724 @noindent 725 which selects Org mode for this buffer no matter what the file's name 726 is. See also the variable @code{org-insert-mode-line-in-empty-file}. 727 728 Many commands in Org work on the region if the region is @emph{active}. To 729 make use of this, you need to have Transient Mark mode turned on, 730 which is the default. If you do not like it, you can create an active 731 region by using the mouse to select a region, or pressing 732 @kbd{C-@key{SPC}} twice before moving point. 733 734 @node Feedback 735 @section Feedback 736 737 @cindex feedback 738 @cindex bug reports 739 @cindex reporting a bug 740 @cindex maintainer 741 @cindex author 742 743 If you find problems with Org, or if you have questions, remarks, or 744 ideas about it, please send an email to the Org mailing list 745 @email{emacs-orgmode@@gnu.org}. You can subscribe to the list 746 @uref{https://lists.gnu.org/mailman/listinfo/emacs-orgmode, from this web 747 page}. If you are not a member of the mailing list, your mail will 748 be passed to the list after a moderator has approved it@footnote{ Please 749 consider subscribing to the mailing list in order to minimize the work 750 the mailing list moderators have to do.}. We ask you to read and 751 respect the 752 @uref{https://www.gnu.org/philosophy/kind-communication.html, GNU Kind 753 Communications Guidelines} when sending messages on this mailing 754 list. Please allow up to one month for the response and followup if 755 no response is received on the bug report. 756 757 @findex org-version 758 @findex org-submit-bug-report 759 For bug reports, please first try to reproduce the bug with the latest 760 version of Org available---if you are running an outdated version, it 761 is quite possible that the bug has been fixed already. If the bug 762 persists, prepare a report and provide as much information as 763 possible, including the version information of Emacs (@kbd{M-x emacs-version}) and Org (@kbd{M-x org-version}), as well as 764 the Org related setup in the Emacs init file. The easiest way to do 765 this is to use the command 766 767 @example 768 M-x org-submit-bug-report <RET> 769 @end example 770 771 772 @noindent 773 which puts all this information into an Emacs mail buffer so that you 774 only need to add your description. If you are not sending the Email 775 from within Emacs, please copy and paste the content into your Email 776 program. 777 778 Sometimes you might face a problem due to an error in your Emacs or 779 Org mode setup. Before reporting a bug, it is very helpful to start 780 Emacs with minimal customizations and reproduce the problem. Doing so 781 often helps you determine if the problem is with your customization or 782 with Org mode itself. You can start a typical minimal session with 783 a command like the example below. 784 785 @example 786 $ emacs -Q -l /path/to/minimal-org.el 787 @end example 788 789 790 However if you are using Org mode as distributed with Emacs, a minimal 791 setup is not necessary. In that case it is sufficient to start Emacs 792 as @samp{emacs -Q}. The @samp{minimal-org.el} setup file can have contents as 793 shown below. 794 795 @lisp 796 ;;; Minimal setup to load latest `org-mode'. 797 798 ;; Activate debugging. 799 (setq debug-on-error t 800 debug-on-signal nil 801 debug-on-quit nil) 802 803 ;; Add latest Org mode to load path. 804 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) 805 @end lisp 806 807 If you are using Org mode version from Git repository, you can start 808 minimal session using make. 809 810 @example 811 # Bare Emacs 812 make repro 813 # or pass extra arguments 814 make repro REPRO_ARGS="-l /path/to/minimal/config.el /tmp/bug.org" 815 @end example 816 817 818 If an error occurs, a ``backtrace'' can be very useful---see below on 819 how to create one. Often a small example file helps, along with clear 820 information about: 821 822 @enumerate 823 @item 824 What exactly did you do? 825 @item 826 What did you expect to happen? 827 @item 828 What happened instead? 829 @end enumerate 830 831 Thank you for helping to improve this program. 832 833 @anchor{How to create a useful backtrace} 834 @subheading How to create a useful backtrace 835 836 @cindex backtrace of an error 837 If working with Org produces an error with a message you do not 838 understand, you may have hit a bug. The best way to report this is by 839 providing, in addition to what was mentioned above, a backtrace. This 840 is information from the built-in debugger about where and how the 841 error occurred. Here is how to produce a useful backtrace: 842 843 @enumerate 844 @item 845 Reload uncompiled versions of all Org mode Lisp files. The 846 backtrace contains much more information if it is produced with 847 uncompiled code. To do this, use 848 849 @example 850 C-u M-x org-reload <RET> 851 @end example 852 853 854 @noindent 855 or, from the menu: Org @arrow{} Refresh/Reload @arrow{} Reload Org uncompiled. 856 857 @item 858 Then, activate the debugger: 859 860 @example 861 M-x toggle-debug-on-error <RET> 862 @end example 863 864 865 @noindent 866 or, from the menu: Options @arrow{} Enter Debugger on Error. 867 868 @item 869 Do whatever you have to do to hit the error. Do not forget to 870 document the steps you take. 871 872 @item 873 When you hit the error, a @samp{*Backtrace*} buffer appears on the 874 screen. Save this buffer to a file---for example using @kbd{C-x C-w}---and attach it to your bug report. 875 @end enumerate 876 877 @node Conventions 878 @section Typesetting Conventions Used in this Manual 879 880 881 882 @anchor{TODO keywords tags properties etc} 883 @subheading TODO keywords, tags, properties, etc. 884 885 Org uses various syntactical elements: TODO keywords, tags, property 886 names, keywords, blocks, etc. In this manual we use the following 887 conventions: 888 889 @table @asis 890 @item @samp{TODO} 891 @itemx @samp{WAITING} 892 TODO keywords are written with all capitals, even if they are 893 user-defined. 894 895 @item @samp{boss} 896 @itemx @samp{ARCHIVE} 897 Tags are case-sensitive. User-defined tags are usually written in 898 lowercase; built-in tags with special meaning are written as they 899 should appear in the document, usually with all capitals. 900 901 @item @samp{Release} 902 @itemx @samp{PRIORITY} 903 User-defined properties are capitalized; built-in properties with 904 special meaning are written with all capitals. 905 906 @item @samp{TITLE} 907 @itemx @samp{BEGIN} @dots{} @samp{END} 908 Keywords and blocks are written in uppercase to enhance their 909 readability, but you can use lowercase in your Org files. 910 @end table 911 912 @anchor{Key bindings and commands} 913 @subheading Key bindings and commands 914 915 The manual lists both the keys and the corresponding commands for 916 accessing a functionality. Org mode often uses the same key for 917 different functions, depending on context. The command that is bound 918 to such keys has a generic name, like @code{org-metaright}. In the manual 919 we will, wherever possible, give the function that is internally 920 called by the generic command. For example, in the chapter on 921 document structure, @kbd{M-@key{RIGHT}} will be listed to call 922 @code{org-do-demote}, while in the chapter on tables, it will be listed to 923 call @code{org-table-move-column-right}. 924 925 @node Document Structure 926 @chapter Document Structure 927 928 @cindex document structure 929 @cindex structure of document 930 Org is an outliner. Outlines allow a document to be organized in 931 a hierarchical structure, which, least for me, is the best 932 representation of notes and thoughts. An overview of this structure 933 is achieved by folding, i.e., hiding large parts of the document to 934 show only the general document structure and the parts currently being 935 worked on. Org greatly simplifies the use of outlines by compressing 936 the entire show and hide functionalities into a single command, 937 @code{org-cycle}, which is bound to the @kbd{@key{TAB}} key. 938 939 @menu 940 * Headlines:: How to typeset Org tree headlines. 941 * Visibility Cycling:: Show and hide, much simplified. 942 * Motion:: Jumping to other headlines. 943 * Structure Editing:: Changing sequence and level of headlines. 944 * Sparse Trees:: Matches embedded in context. 945 * Plain Lists:: Additional structure within an entry. 946 * Drawers:: Tucking stuff away. 947 * Blocks:: Folding blocks. 948 @end menu 949 950 @node Headlines 951 @section Headlines 952 953 @cindex headlines 954 @cindex outline tree 955 @vindex org-special-ctrl-a/e 956 @vindex org-special-ctrl-k 957 @vindex org-ctrl-k-protect-subtree 958 959 Headlines define the structure of an outline tree. Org headlines 960 start on the left margin@footnote{See the variables @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, 961 and @code{org-ctrl-k-protect-subtree} to configure special behavior of 962 @kbd{C-a}, @kbd{C-e}, and @kbd{C-k} in headlines. Note 963 also that clocking only works with headings indented less than 30 964 stars.} with one or more stars followed by 965 a space. For example: 966 967 @example 968 * Top level headline 969 ** Second level 970 *** Third level 971 some text 972 *** Third level 973 more text 974 * Another top level headline 975 @end example 976 977 @vindex org-footnote-section 978 The name defined in @code{org-footnote-section} is reserved. Do not use it 979 as a title for your own headings. 980 981 Some people find the many stars too noisy and would prefer an outline 982 that has whitespace followed by a single star as headline starters. 983 This can be achieved using a Org Indent minor mode. See @ref{Clean View} for more information. 984 985 Headlines are not numbered. However, you may want to dynamically 986 number some, or all, of them. See @ref{Dynamic Headline Numbering}. 987 988 @vindex org-cycle-separator-lines 989 An empty line after the end of a subtree is considered part of it and 990 is hidden when the subtree is folded. However, if you leave at least 991 two empty lines, one empty line remains visible after folding the 992 subtree, in order to structure the collapsed view. See the variable 993 @code{org-cycle-separator-lines} to modify this behavior. 994 995 @node Visibility Cycling 996 @section Visibility Cycling 997 998 @cindex cycling, visibility 999 @cindex visibility cycling 1000 @cindex trees, visibility 1001 @cindex show hidden text 1002 @cindex hide text 1003 1004 @menu 1005 * Global and local cycling:: Cycling through various visibility states. 1006 * Initial visibility:: Setting the initial visibility state. 1007 * Catching invisible edits:: Preventing mistakes when editing invisible parts. 1008 @end menu 1009 1010 @node Global and local cycling 1011 @subsection Global and local cycling 1012 1013 @cindex subtree visibility states 1014 @cindex subtree cycling 1015 @cindex folded, subtree visibility state 1016 @cindex children, subtree visibility state 1017 @cindex subtree, subtree visibility state 1018 1019 Outlines make it possible to hide parts of the text in the buffer. 1020 Org uses just two commands, bound to @kbd{@key{TAB}} and 1021 @kbd{S-@key{TAB}} to change the visibility in the buffer. 1022 1023 @table @asis 1024 @item @kbd{@key{TAB}} (@code{org-cycle}) 1025 @kindex TAB 1026 @findex org-cycle 1027 @emph{Subtree cycling}: Rotate current subtree among the states 1028 1029 @example 1030 ,-> FOLDED -> CHILDREN -> SUBTREE --. 1031 '-----------------------------------' 1032 @end example 1033 1034 @vindex org-cycle-emulate-tab 1035 Point must be on a headline for this to work@footnote{ See, however, the 1036 option @code{org-cycle-emulate-tab}.}. 1037 1038 @item @kbd{S-@key{TAB}} (@code{org-global-cycle}) 1039 @itemx @kbd{C-u @key{TAB}} 1040 @cindex global visibility states 1041 @cindex global cycling 1042 @cindex overview, global visibility state 1043 @cindex contents, global visibility state 1044 @cindex show all, global visibility state 1045 @kindex C-u TAB 1046 @kindex S-TAB 1047 @findex org-global-cycle 1048 @emph{Global cycling}: Rotate the entire buffer among the states 1049 1050 @example 1051 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. 1052 '--------------------------------------' 1053 @end example 1054 1055 When @kbd{S-@key{TAB}} is called with a numeric prefix argument 1056 @var{N}, view contents only up to headlines of level 1057 @var{N}. 1058 1059 Note that inside tables (see @ref{Tables}), @kbd{S-@key{TAB}} jumps to the 1060 previous field instead. 1061 1062 @vindex org-cycle-global-at-bob 1063 You can run global cycling using @kbd{@key{TAB}} only if point is at 1064 the very beginning of the buffer, but not on a headline, and 1065 @code{org-cycle-global-at-bob} is set to a non-@code{nil} value. 1066 1067 @item @kbd{C-u C-u @key{TAB}} (@code{org-set-startup-visibility}) 1068 @cindex startup visibility 1069 @kindex C-u C-u TAB 1070 @findex org-set-startup-visibility 1071 Switch back to the startup visibility of the buffer (see @ref{Initial visibility}). 1072 1073 @item @kbd{C-u C-u C-u @key{TAB}} (@code{org-show-all}) 1074 @cindex show all, command 1075 @kindex C-u C-u C-u TAB 1076 @findex org-show-all 1077 Show all, including drawers. 1078 1079 @item @kbd{C-c C-r} (@code{org-reveal}) 1080 @cindex revealing context 1081 @kindex C-c C-r 1082 @findex org-reveal 1083 Reveal context around point, showing the current entry, the 1084 following heading and the hierarchy above. It is useful for working 1085 near a location that has been exposed by a sparse tree command (see 1086 @ref{Sparse Trees}) or an agenda command (see @ref{Agenda Commands}). With a prefix argument, show, on each level, all sibling 1087 headings. With a double prefix argument, also show the entire 1088 subtree of the parent. 1089 1090 @item @kbd{C-c C-k} (@code{org-show-branches}) 1091 @cindex show branches, command 1092 @kindex C-c C-k 1093 @findex org-show-branches 1094 Expose all the headings of the subtree, but not their bodies. 1095 1096 @item @kbd{C-c @key{TAB}} (@code{org-show-children}) 1097 @cindex show children, command 1098 @kindex C-c TAB 1099 @findex org-show-children 1100 Expose all direct children of the subtree. With a numeric prefix 1101 argument @var{N}, expose all children down to level 1102 @var{N}. 1103 1104 @item @kbd{C-c C-x b} (@code{org-tree-to-indirect-buffer}) 1105 @kindex C-c C-x b 1106 @findex org-tree-to-indirect-buffer 1107 Show the current subtree in an indirect buffer@footnote{The indirect buffer contains the entire buffer, but is narrowed 1108 to the current tree. Editing the indirect buffer also changes the 1109 original buffer, but without affecting visibility in that buffer. For 1110 more information about indirect buffers, see @ref{Indirect Buffers,GNU Emacs Manual,,emacs,}.}. With 1111 a numeric prefix argument @var{N}, go up to level @var{N} 1112 and then take that tree. If @var{N} is negative then go up 1113 that many levels. With a @kbd{C-u} prefix, do not remove the 1114 previously used indirect buffer. 1115 1116 @item @kbd{C-c C-x v} (@code{org-copy-visible}) 1117 @kindex C-c C-x v 1118 @findex org-copy-visible 1119 Copy the @emph{visible} text in the region into the kill ring. 1120 @end table 1121 1122 @node Initial visibility 1123 @subsection Initial visibility 1124 1125 @vindex org-startup-folded 1126 When Emacs first visits an Org file, the global state is set to 1127 @code{showeverything}, i.e., all file content is visible@footnote{ When 1128 @code{org-agenda-inhibit-startup} is non-@code{nil}, Org does not honor the 1129 default visibility state when first opening a file for the agenda (see 1130 @ref{Speeding Up Your Agendas}).}. This can be configured through the 1131 variable @code{org-startup-folded}, or on a per-file basis by adding one of 1132 the following lines anywhere in the buffer: 1133 1134 @cindex @samp{STARTUP}, keyword 1135 @example 1136 #+STARTUP: overview 1137 #+STARTUP: content 1138 #+STARTUP: showall 1139 #+STARTUP: show2levels 1140 #+STARTUP: show3levels 1141 #+STARTUP: show4levels 1142 #+STARTUP: show5levels 1143 #+STARTUP: showeverything 1144 @end example 1145 1146 @cindex @samp{VISIBILITY}, property 1147 Furthermore, any entries with a @samp{VISIBILITY} property (see @ref{Properties and Columns}) get their visibility adapted accordingly. Allowed values 1148 for this property are @samp{folded}, @samp{children}, @samp{content}, and @samp{all}. 1149 1150 @table @asis 1151 @item @kbd{C-u C-u @key{TAB}} (@code{org-set-startup-visibility}) 1152 @kindex C-u C-u TAB 1153 @findex org-set-startup-visibility 1154 Switch back to the startup visibility of the buffer, i.e., whatever 1155 is requested by startup options and @samp{VISIBILITY} properties in 1156 individual entries. 1157 @end table 1158 1159 @node Catching invisible edits 1160 @subsection Catching invisible edits 1161 1162 @cindex edits, catching invisible 1163 1164 @vindex org-fold-catch-invisible-edits 1165 Sometimes you may inadvertently edit an invisible part of the buffer 1166 and be confused on what has been edited and how to undo the mistake. 1167 Setting @code{org-fold-catch-invisible-edits} to non-@code{nil} helps preventing 1168 this. See the docstring of this option on how Org should catch 1169 invisible edits and process them. 1170 1171 @node Motion 1172 @section Motion 1173 1174 @cindex motion, between headlines 1175 @cindex jumping, to headlines 1176 @cindex headline navigation 1177 1178 The following commands jump to other headlines in the buffer. 1179 1180 @table @asis 1181 @item @kbd{C-c C-n} (@code{org-next-visible-heading}) 1182 @kindex C-c C-n 1183 @findex org-next-visible-heading 1184 Next heading. 1185 1186 @item @kbd{C-c C-p} (@code{org-previous-visible-heading}) 1187 @kindex C-c C-p 1188 @findex org-previous-visible-heading 1189 Previous heading. 1190 1191 @item @kbd{C-c C-f} (@code{org-forward-heading-same-level}) 1192 @kindex C-c C-f 1193 @findex org-forward-heading-same-level 1194 Next heading same level. 1195 1196 @item @kbd{C-c C-b} (@code{org-backward-heading-same-level}) 1197 @kindex C-c C-b 1198 @findex org-backward-heading-same-level 1199 Previous heading same level. 1200 1201 @item @kbd{C-c C-u} (@code{outline-up-heading}) 1202 @kindex C-c C-u 1203 @findex outline-up-heading 1204 Backward to higher level heading. 1205 1206 @item @kbd{C-c C-j} (@code{org-goto}) 1207 @kindex C-c C-j 1208 @findex org-goto 1209 @vindex org-goto-auto-isearch 1210 Jump to a different place without changing the current outline 1211 visibility. Shows the document structure in a temporary buffer, 1212 where you can use the following keys to find your destination: 1213 1214 @multitable @columnfractions 0.3 0.7 1215 @item @kbd{@key{TAB}} 1216 @tab Cycle visibility. 1217 @item @kbd{@key{DOWN}} / @kbd{@key{UP}} 1218 @tab Next/previous visible headline. 1219 @item @kbd{@key{RET}} 1220 @tab Select this location. 1221 @item @kbd{/} 1222 @tab Do a Sparse-tree search 1223 @end multitable 1224 1225 @noindent 1226 The following keys work if you turn off @code{org-goto-auto-isearch} 1227 1228 @multitable @columnfractions 0.3 0.7 1229 @item @kbd{n} / @kbd{p} 1230 @tab Next/previous visible headline. 1231 @item @kbd{f} / @kbd{b} 1232 @tab Next/previous headline same level. 1233 @item @kbd{u} 1234 @tab One level up. 1235 @item @kbd{0} @dots{} @kbd{9} 1236 @tab Digit argument. 1237 @item @kbd{q} 1238 @tab Quit. 1239 @end multitable 1240 1241 @vindex org-goto-interface 1242 @noindent 1243 See also the variable @code{org-goto-interface}. 1244 @end table 1245 1246 @node Structure Editing 1247 @section Structure Editing 1248 1249 @cindex structure editing 1250 @cindex headline, promotion and demotion 1251 @cindex promotion, of subtrees 1252 @cindex demotion, of subtrees 1253 @cindex subtree, cut and paste 1254 @cindex pasting, of subtrees 1255 @cindex cutting, of subtrees 1256 @cindex copying, of subtrees 1257 @cindex sorting, of subtrees 1258 @cindex subtrees, cut and paste 1259 1260 @table @asis 1261 @item @kbd{M-@key{RET}} (@code{org-meta-return}) 1262 @kindex M-RET 1263 @findex org-meta-return 1264 @vindex org-M-RET-may-split-line 1265 Insert a new heading, item or row. 1266 1267 If the command is used at the @emph{beginning} of a line, and if there is 1268 a heading or a plain list item (see @ref{Plain Lists}) at point, the new 1269 heading/item is created @emph{before} the current line. When used at the 1270 beginning of a regular line of text, turn that line into a heading. 1271 1272 When this command is used in the middle of a line, the line is split 1273 and the rest of the line becomes the new item or headline. If you 1274 do not want the line to be split, customize 1275 @code{org-M-RET-may-split-line}. 1276 1277 Calling the command with a @kbd{C-u} prefix unconditionally 1278 inserts a new heading at the end of the current subtree, thus 1279 preserving its contents. With a double @kbd{C-u C-u} prefix, 1280 the new heading is created at the end of the parent subtree instead. 1281 1282 @item @kbd{C-@key{RET}} (@code{org-insert-heading-respect-content}) 1283 @kindex C-RET 1284 @findex org-insert-heading-respect-content 1285 Insert a new heading at the end of the current subtree. 1286 1287 @item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading}) 1288 @kindex M-S-RET 1289 @findex org-insert-todo-heading 1290 @vindex org-treat-insert-todo-heading-as-state-change 1291 Insert new TODO entry with same level as current heading. See also 1292 the variable @code{org-treat-insert-todo-heading-as-state-change}. 1293 1294 @item @kbd{C-S-@key{RET}} (@code{org-insert-todo-heading-respect-content}) 1295 @kindex C-S-RET 1296 @findex org-insert-todo-heading-respect-content 1297 Insert new TODO entry with same level as current heading. Like 1298 @kbd{C-@key{RET}}, the new headline is inserted after the current 1299 subtree. 1300 1301 @item @kbd{@key{TAB}} (@code{org-cycle}) 1302 @kindex TAB 1303 @findex org-cycle 1304 In a new entry with no text yet, the first @kbd{@key{TAB}} demotes 1305 the entry to become a child of the previous one. The next 1306 @kbd{@key{TAB}} makes it a parent, and so on, all the way to top 1307 level. Yet another @kbd{@key{TAB}}, and you are back to the initial 1308 level. 1309 1310 @item @kbd{M-@key{LEFT}} (@code{org-do-promote}) 1311 @itemx @kbd{M-@key{RIGHT}} (@code{org-do-demote}) 1312 @kindex M-LEFT 1313 @findex org-do-promote 1314 @kindex M-RIGHT 1315 @findex org-do-demote 1316 Promote or demote current heading by one level. 1317 1318 @cindex region, active 1319 @cindex active region 1320 @cindex transient mark mode 1321 When there is an active region---i.e., when Transient Mark mode is 1322 active---promotion and demotion work on all headlines in the region. 1323 To select a region of headlines, it is best to place both point and 1324 mark at the beginning of a line, mark at the beginning of the first 1325 headline, and point at the line just after the last headline to 1326 change. 1327 1328 @item @kbd{M-S-@key{LEFT}} (@code{org-promote-subtree}) 1329 @kindex M-S-LEFT 1330 @findex org-promote-subtree 1331 Promote the current subtree by one level. 1332 1333 @item @kbd{M-S-@key{RIGHT}} (@code{org-demote-subtree}) 1334 @kindex M-S-RIGHT 1335 @findex org-demote-subtree 1336 Demote the current subtree by one level. 1337 1338 @item @kbd{M-@key{UP}} (@code{org-move-subtree-up}) 1339 @kindex M-UP 1340 @findex org-move-subtree-up 1341 Move subtree up, i.e., swap with previous subtree of same level. 1342 1343 @item @kbd{M-@key{DOWN}} (@code{org-move-subtree-down}) 1344 @kindex M-DOWN 1345 @findex org-move-subtree-down 1346 Move subtree down, i.e., swap with next subtree of same level. 1347 1348 @item @kbd{C-c @@} (@code{org-mark-subtree}) 1349 @kindex C-c @@ 1350 @findex org-mark-subtree 1351 Mark the subtree at point. Hitting repeatedly marks subsequent 1352 subtrees of the same level as the marked subtree. 1353 1354 @item @kbd{C-c C-x C-w} (@code{org-cut-subtree}) 1355 @kindex C-c C-x C-w 1356 @findex org-cut-subtree 1357 Kill subtree, i.e., remove it from buffer but save in kill ring. 1358 With a numeric prefix argument N, kill N sequential subtrees. 1359 1360 @item @kbd{C-c C-x M-w} (@code{org-copy-subtree}) 1361 @kindex C-c C-x M-w 1362 @findex org-copy-subtree 1363 Copy subtree to kill ring. With a numeric prefix argument N, copy 1364 the N sequential subtrees. 1365 1366 @item @kbd{C-c C-x C-y} (@code{org-paste-subtree}) 1367 @kindex C-c C-x C-y 1368 @findex org-paste-subtree 1369 Yank subtree from kill ring. This does modify the level of the 1370 subtree to make sure the tree fits in nicely at the yank position. 1371 The yank level can also be specified with a numeric prefix argument, 1372 or by yanking after a headline marker like @samp{****}. 1373 1374 @item @kbd{C-y} (@code{org-yank}) 1375 @kindex C-y 1376 @findex org-yank 1377 @vindex org-yank-adjusted-subtrees 1378 @vindex org-yank-folded-subtrees 1379 Depending on the variables @code{org-yank-adjusted-subtrees} and 1380 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command pastes 1381 subtrees folded and in a clever way, using the same command as 1382 @kbd{C-c C-x C-y}. With the default settings, no level 1383 adjustment takes place, but the yanked tree is folded unless doing 1384 so would swallow text previously visible. Any prefix argument to 1385 this command forces a normal @code{yank} to be executed, with the prefix 1386 passed along. A good way to force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a yank, it yanks previous kill 1387 items plainly, without adjustment and folding. 1388 1389 @item @kbd{C-c C-x c} (@code{org-clone-subtree-with-time-shift}) 1390 @kindex C-c C-x c 1391 @findex org-clone-subtree-with-time-shift 1392 Clone a subtree by making a number of sibling copies of it. You are 1393 prompted for the number of copies to make, and you can also specify 1394 if any timestamps in the entry should be shifted. This can be 1395 useful, for example, to create a number of tasks related to a series 1396 of lectures to prepare. For more details, see the docstring of the 1397 command @code{org-clone-subtree-with-time-shift}. 1398 1399 @item @kbd{C-c C-w} (@code{org-refile}) 1400 @kindex C-c C-w 1401 @findex org-refile 1402 Refile entry or region to a different location. See @ref{Refile and Copy}. 1403 1404 @item @kbd{C-c ^} (@code{org-sort}) 1405 @kindex C-c ^ 1406 @findex org-sort 1407 Sort same-level entries. When there is an active region, all 1408 entries in the region are sorted. Otherwise the children of the 1409 current headline are sorted. The command prompts for the sorting 1410 method, which can be alphabetically, numerically, by time---first 1411 timestamp with active preferred, creation time, scheduled time, 1412 deadline time---by priority, by TODO keyword---in the sequence the 1413 keywords have been defined in the setup---or by the value of 1414 a property. Reverse sorting is possible as well. You can also 1415 supply your own function to extract the sorting key. With 1416 a @kbd{C-u} prefix, sorting is case-sensitive. 1417 1418 @item @kbd{C-x n s} (@code{org-narrow-to-subtree}) 1419 @kindex C-x n s 1420 @findex org-narrow-to-subtree 1421 Narrow buffer to current subtree. 1422 1423 @item @kbd{C-x n b} (@code{org-narrow-to-block}) 1424 @kindex C-x n b 1425 @findex org-narrow-to-block 1426 Narrow buffer to current block. 1427 1428 @item @kbd{C-x n w} (@code{widen}) 1429 @kindex C-x n w 1430 @findex widen 1431 Widen buffer to remove narrowing. 1432 1433 @item @kbd{C-c *} (@code{org-toggle-heading}) 1434 @kindex C-c * 1435 @findex org-toggle-heading 1436 Turn a normal line or plain list item into a headline---so that it 1437 becomes a subheading at its location. Also turn a headline into 1438 a normal line by removing the stars. If there is an active region, 1439 turn all lines in the region into headlines. If the first line in 1440 the region was an item, turn only the item lines into headlines. 1441 Finally, if the first line is a headline, remove the stars from all 1442 headlines in the region. 1443 @end table 1444 1445 Note that when point is inside a table (see @ref{Tables}), the Meta-Cursor 1446 keys have different functionality. 1447 1448 @node Sparse Trees 1449 @section Sparse Trees 1450 1451 @cindex sparse trees 1452 @cindex trees, sparse 1453 @cindex folding, sparse trees 1454 @cindex occur, command 1455 1456 @vindex org-show-context-detail 1457 An important feature of Org mode is the ability to construct @emph{sparse 1458 trees} for selected information in an outline tree, so that the entire 1459 document is folded as much as possible, but the selected information 1460 is made visible along with the headline structure above it@footnote{ See 1461 also the variable @code{org-show-context-detail} to decide how much context 1462 is shown around each match.}. Just try it out and you will see 1463 immediately how it works. 1464 1465 Org mode contains several commands creating such trees, all these 1466 commands can be accessed through a dispatcher: 1467 1468 @table @asis 1469 @item @kbd{C-c /} (@code{org-sparse-tree}) 1470 @kindex C-c / 1471 @findex org-sparse-tree 1472 This prompts for an extra key to select a sparse-tree creating 1473 command. 1474 1475 @item @kbd{C-c / r} or @kbd{C-c / /} (@code{org-occur}) 1476 @kindex C-c / r 1477 @kindex C-c / / 1478 @findex org-occur 1479 @vindex org-remove-highlights-with-change 1480 Prompts for a regexp (see @ref{Regular Expressions}) and shows a 1481 sparse tree with all matches. If the match is in a headline, the 1482 headline is made visible. If the match is in the body of an entry, 1483 headline and body are made visible. In order to provide minimal 1484 context, also the full hierarchy of headlines above the match is 1485 shown, as well as the headline following the match. Each match is 1486 also highlighted; the highlights disappear when the buffer is 1487 changed by an editing command, or by pressing @kbd{C-c C-c}@footnote{ This depends on the option 1488 @code{org-remove-highlights-with-change}.}. When called with a 1489 @kbd{C-u} prefix argument, previous highlights are kept, so 1490 several calls to this command can be stacked. 1491 1492 @item @kbd{M-g n} or @kbd{M-g M-n} (@code{next-error}) 1493 @kindex M-g n 1494 @kindex M-g M-n 1495 @findex next-error 1496 Jump to the next sparse tree match in this buffer. 1497 1498 @item @kbd{M-g p} or @kbd{M-g M-p} (@code{previous-error}) 1499 @kindex M-g p 1500 @kindex M-g M-p 1501 @findex previous-error 1502 Jump to the previous sparse tree match in this buffer. 1503 @end table 1504 1505 @vindex org-agenda-custom-commands 1506 For frequently used sparse trees of specific search strings, you can 1507 use the variable @code{org-agenda-custom-commands} to define fast keyboard 1508 access to specific sparse trees. These commands will then be 1509 accessible through the agenda dispatcher (see @ref{Agenda Dispatcher}). 1510 For example: 1511 1512 @lisp 1513 (setq org-agenda-custom-commands 1514 '(("f" occur-tree "FIXME"))) 1515 @end lisp 1516 1517 @noindent 1518 defines the key @kbd{f} as a shortcut for creating a sparse tree 1519 matching the string @samp{FIXME}. 1520 1521 The other sparse tree commands select headings based on TODO keywords, 1522 tags, or properties and are discussed later in this manual. 1523 1524 @kindex C-c C-e C-v 1525 @cindex printing sparse trees 1526 @cindex visible text, printing 1527 To print a sparse tree, you can use the Emacs command 1528 @code{ps-print-buffer-with-faces} which does not print invisible parts of 1529 the document. Or you can use the command @kbd{C-c C-e C-v} to 1530 export only the visible part of the document and print the resulting 1531 file. 1532 1533 @node Plain Lists 1534 @section Plain Lists 1535 1536 @cindex plain lists 1537 @cindex lists, plain 1538 @cindex lists, ordered 1539 @cindex ordered lists 1540 1541 Within an entry of the outline tree, hand-formatted lists can provide 1542 additional structure. They also provide a way to create lists of 1543 checkboxes (see @ref{Checkboxes}). Org supports editing such lists, and 1544 every exporter (see @ref{Exporting}) can parse and format them. 1545 1546 Org knows ordered lists, unordered lists, and description lists. 1547 1548 @itemize 1549 @item 1550 @emph{Unordered} list items start with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented so that they 1551 are not interpreted as headlines. Also, when you are hiding leading 1552 stars to get a clean outline view, plain list items starting with 1553 a star may be hard to distinguish from true headlines. In short: even 1554 though @samp{*} is supported, it may be better to not use it for plain list 1555 items.} as bullets. 1556 1557 @item 1558 @vindex org-plain-list-ordered-item-terminator 1559 @vindex org-alphabetical-lists 1560 @emph{Ordered} list items start with a numeral followed by either a 1561 period or a right parenthesis@footnote{ You can filter out any of them by 1562 configuring @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} 1563 or @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and @samp{A)} by configuring 1564 @code{org-list-allow-alphabetical}. To minimize confusion with normal 1565 text, those are limited to one character only. Beyond that limit, 1566 bullets automatically become numbers.} If you want a list to start with a different 1567 value---e.g., 20---start the text of the item with @samp{[@@20]}@footnote{If there's a checkbox in the item, the cookie must be put 1568 @emph{before} the checkbox. If you have activated alphabetical lists, you 1569 can also use counters like @samp{[@@b]}.}. 1570 Those constructs can be used in any item of the list in order to 1571 enforce a particular numbering. 1572 1573 @item 1574 @emph{Description} list items are unordered list items, and contain the 1575 separator @samp{::} to distinguish the description @emph{term} from the 1576 description. 1577 @end itemize 1578 1579 Items belonging to the same list must have the same indentation on the 1580 first line. In particular, if an ordered list reaches number @samp{10.}, 1581 then the 2-digit numbers must be written left-aligned with the other 1582 numbers in the list. An item ends before the next line that is less 1583 or equally indented than its bullet/number. 1584 1585 A list ends whenever every item has ended, which means before any line 1586 less or equally indented than items at top level. It also ends before 1587 two blank lines. In that case, all items are closed. Here is an 1588 example: 1589 1590 @example 1591 * Lord of the Rings 1592 My favorite scenes are (in this order) 1593 1. The attack of the Rohirrim 1594 2. Eowyn's fight with the witch king 1595 + this was already my favorite scene in the book 1596 + I really like Miranda Otto. 1597 3. Peter Jackson being shot by Legolas 1598 - on DVD only 1599 He makes a really funny face when it happens. 1600 But in the end, no individual scenes matter but the film as a whole. 1601 Important actors in this film are: 1602 - Elijah Wood :: He plays Frodo 1603 - Sean Astin :: He plays Sam, Frodo's friend. I still remember him 1604 very well from his role as Mikey Walsh in /The Goonies/. 1605 @end example 1606 1607 Org supports these lists by tuning filling and wrapping commands to 1608 deal with them correctly, and by exporting them properly (see 1609 @ref{Exporting}). Since indentation is what governs the structure of these 1610 lists, many structural constructs like @samp{#+BEGIN_} blocks can be 1611 indented to signal that they belong to a particular item. 1612 1613 @vindex org-list-demote-modify-bullet 1614 @vindex org-list-indent-offset 1615 If you find that using a different bullet for a sub-list---than that 1616 used for the current list-level---improves readability, customize the 1617 variable @code{org-list-demote-modify-bullet}. To get a greater difference 1618 of indentation between items and theirs sub-items, customize 1619 @code{org-list-indent-offset}. 1620 1621 @vindex org-list-automatic-rules 1622 The following commands act on items when point is in the first line of 1623 an item---the line with the bullet or number. Some of them imply the 1624 application of automatic rules to keep list structure intact. If some 1625 of these actions get in your way, configure @code{org-list-automatic-rules} 1626 to disable them individually. 1627 1628 @table @asis 1629 @item @kbd{@key{TAB}} (@code{org-cycle}) 1630 @cindex cycling, in plain lists 1631 @kindex TAB 1632 @findex org-cycle 1633 @vindex org-cycle-include-plain-lists 1634 Items can be folded just like headline levels. Normally this works 1635 only if point is on a plain list item. For more details, see the 1636 variable @code{org-cycle-include-plain-lists}. If this variable is set 1637 to @code{integrate}, plain list items are treated like low-level 1638 headlines. The level of an item is then given by the indentation of 1639 the bullet/number. Items are always subordinate to real headlines, 1640 however; the hierarchies remain completely separated. In a new item 1641 with no text yet, the first @kbd{@key{TAB}} demotes the item to 1642 become a child of the previous one. Subsequent @kbd{@key{TAB}}s move 1643 the item to meaningful levels in the list and eventually get it back 1644 to its initial position. 1645 1646 @item @kbd{M-@key{RET}} (@code{org-insert-heading}) 1647 @kindex M-RET 1648 @findex org-insert-heading 1649 @vindex org-M-RET-may-split-line 1650 Insert new item at current level. With a prefix argument, force a 1651 new heading (see @ref{Structure Editing}). If this command is used 1652 in the middle of an item, that item is @emph{split} in two, and the 1653 second part becomes the new item@footnote{ If you do not want the item to 1654 be split, customize the variable @code{org-M-RET-may-split-line}.}. If 1655 this command is executed @emph{before item's body}, the new item is 1656 created @emph{before} the current one. 1657 1658 @item @kbd{M-S-@key{RET}} 1659 @kindex M-S-RET 1660 Insert a new item with a checkbox (see @ref{Checkboxes}). 1661 1662 @item @kbd{S-@key{UP}} 1663 @itemx @kbd{S-@key{DOWN}} 1664 @kindex S-UP 1665 @kindex S-DOWN 1666 @cindex shift-selection-mode 1667 @vindex org-support-shift-select 1668 @vindex org-list-use-circular-motion 1669 Jump to the previous/next item in the current list, but only if 1670 @code{org-support-shift-select} is off@footnote{ If you want to cycle around 1671 items that way, you may customize @code{org-list-use-circular-motion}.}. 1672 If not, you can still use paragraph jumping commands like 1673 @kbd{C-@key{UP}} and @kbd{C-@key{DOWN}} to quite similar effect. 1674 1675 @item @kbd{M-@key{UP}} 1676 @itemx @kbd{M-@key{DOWN}} 1677 @kindex M-UP 1678 @kindex M-DOWN 1679 Move the item including subitems up/down@footnote{ See 1680 @code{org-list-use-circular-motion} for a cyclic behavior.}, i.e., swap 1681 with previous/next item of same indentation. If the list is 1682 ordered, renumbering is automatic. 1683 1684 @item @kbd{M-@key{LEFT}} 1685 @itemx @kbd{M-@key{RIGHT}} 1686 @kindex M-LEFT 1687 @kindex M-RIGHT 1688 Decrease/increase the indentation of an item, leaving children 1689 alone. 1690 1691 @item @kbd{M-S-@key{LEFT}} 1692 @itemx @kbd{M-S-@key{RIGHT}} 1693 @kindex M-S-LEFT 1694 @kindex M-S-RIGHT 1695 Decrease/increase the indentation of the item, including subitems. 1696 Initially, the item tree is selected based on current indentation. 1697 When these commands are executed several times in direct succession, 1698 the initially selected region is used, even if the new indentation 1699 would imply a different hierarchy. To use the new hierarchy, break 1700 the command chain by moving point. 1701 1702 As a special case, using this command on the very first item of 1703 a list moves the whole list. This behavior can be disabled by 1704 configuring @code{org-list-automatic-rules}. The global indentation of 1705 a list has no influence on the text @emph{after} the list. 1706 1707 @item @kbd{C-c C-c} 1708 @kindex C-c C-c 1709 If there is a checkbox (see @ref{Checkboxes}) in the item line, toggle 1710 the state of the checkbox. In any case, verify bullets and 1711 indentation consistency in the whole list. 1712 1713 @item @kbd{C-c -} 1714 @kindex C-c - 1715 @vindex org-plain-list-ordered-item-terminator 1716 Cycle the entire list level through the different itemize/enumerate 1717 bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them, depending 1718 on @code{org-plain-list-ordered-item-terminator}, the type of list, and 1719 its indentation. With a numeric prefix argument N, select the Nth 1720 bullet from this list. If there is an active region when calling 1721 this, all lines are converted to list items. With a prefix 1722 argument, the selected text is changed into a single item. If the 1723 first line already was a list item, any item marker is removed from 1724 the list. Finally, even without an active region, a normal line is 1725 converted into a list item. 1726 1727 @item @kbd{C-c *} 1728 @kindex C-c * 1729 Turn a plain list item into a headline---so that it becomes 1730 a subheading at its location. See @ref{Structure Editing}, for 1731 a detailed explanation. 1732 1733 @item @kbd{C-c C-*} 1734 @kindex C-c C-* 1735 Turn the whole plain list into a subtree of the current heading. 1736 Checkboxes (see @ref{Checkboxes}) become @samp{TODO}, respectively @samp{DONE}, 1737 keywords when unchecked, respectively checked. 1738 1739 @item @kbd{S-@key{LEFT}} 1740 @itemx @kbd{S-@key{RIGHT}} 1741 @vindex org-support-shift-select 1742 @kindex S-LEFT 1743 @kindex S-RIGHT 1744 This command also cycles bullet styles when point is in on the 1745 bullet or anywhere in an item line, details depending on 1746 @code{org-support-shift-select}. 1747 1748 @item @kbd{C-c ^} 1749 @kindex C-c ^ 1750 @cindex sorting, of plain list 1751 Sort the plain list. Prompt for the sorting method: numerically, 1752 alphabetically, by time, or by custom function. 1753 @end table 1754 1755 @node Drawers 1756 @section Drawers 1757 1758 @cindex drawers 1759 @cindex visibility cycling, drawers 1760 1761 Sometimes you want to keep information associated with an entry, but 1762 you normally do not want to see it. For this, Org mode has @emph{drawers}. 1763 They can contain anything but a headline and another drawer. Drawers 1764 look like this: 1765 1766 @example 1767 ** This is a headline 1768 Still outside the drawer 1769 :DRAWERNAME: 1770 This is inside the drawer. 1771 :END: 1772 After the drawer. 1773 @end example 1774 1775 @kindex C-c C-x d 1776 @findex org-insert-drawer 1777 You can interactively insert a drawer at point by calling 1778 @code{org-insert-drawer}, which is bound to @kbd{C-c C-x d}. With an 1779 active region, this command puts the region inside the drawer. With a 1780 prefix argument, this command calls non-interactive function 1781 @code{org-insert-property-drawer}, which creates a @samp{PROPERTIES} drawer 1782 right below the current headline. Org mode uses this special drawer 1783 for storing properties (see @ref{Properties and Columns}). You cannot use 1784 it for anything else. 1785 1786 Completion over drawer keywords is also possible using 1787 @kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-@key{TAB}} to switch windows. 1788 Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead.}. 1789 1790 Visibility cycling (see @ref{Visibility Cycling}) on the headline hides and 1791 shows the entry, but keep the drawer collapsed to a single line. In 1792 order to look inside the drawer, you need to move point to the drawer 1793 line and press @kbd{@key{TAB}} there. 1794 1795 You can also arrange for state change notes (see @ref{Tracking TODO state changes}) and clock times (see @ref{Clocking Work Time}) to be stored in 1796 a @samp{LOGBOOK} drawer. If you want to store a quick note there, in 1797 a similar way to state changes, use 1798 1799 @table @asis 1800 @item @kbd{C-c C-z} 1801 @kindex C-c C-z 1802 Add a time-stamped note to the @samp{LOGBOOK} drawer. 1803 @end table 1804 1805 @node Blocks 1806 @section Blocks 1807 1808 @vindex org-hide-block-startup 1809 @cindex blocks, folding 1810 1811 Org mode uses @samp{#+BEGIN} @dots{} @samp{#+END} blocks for various purposes from 1812 including source code examples (see @ref{Literal Examples}) to capturing 1813 time logging information (see @ref{Clocking Work Time}). These blocks can 1814 be folded and unfolded by pressing @kbd{@key{TAB}} in the @samp{#+BEGIN} 1815 line. You can also get all blocks folded at startup by configuring 1816 the variable @code{org-hide-block-startup} or on a per-file basis by using 1817 1818 @cindex STARTUP, keyword 1819 @example 1820 #+STARTUP: hideblocks 1821 #+STARTUP: nohideblocks 1822 @end example 1823 1824 @node Tables 1825 @chapter Tables 1826 1827 @cindex tables 1828 @cindex editing tables 1829 1830 Org comes with a fast and intuitive table editor. Spreadsheet-like 1831 calculations are supported using the Emacs Calc package (see @ref{Top,GNU Emacs 1832 Calculator Manual,,calc,}). 1833 1834 @menu 1835 * Built-in Table Editor:: Simple tables. 1836 * Column Width and Alignment:: Overrule the automatic settings. 1837 * Column Groups:: Grouping to trigger vertical lines. 1838 * Orgtbl Mode:: The table editor as minor mode. 1839 * The Spreadsheet:: The table editor has spreadsheet capabilities. 1840 * Org Plot:: Plotting from Org tables. 1841 @end menu 1842 1843 @node Built-in Table Editor 1844 @section Built-in Table Editor 1845 1846 @cindex table editor, built-in 1847 1848 @cindex header lines, in tables 1849 @cindex horizontal rule, in tables 1850 @cindex row separator, in tables 1851 @cindex table syntax 1852 Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} 1853 as the first non-whitespace character is considered part of a table. 1854 @samp{|} is also the column separator@footnote{ To insert a vertical bar into a 1855 table field, use @samp{\vert} or, inside a word @samp{abc\vert@{@}def}.}. 1856 Moreover, a line starting with @samp{|-} is a horizontal rule. It 1857 separates rows explicitly. Rows before the first horizontal rule are 1858 header lines. A table might look like this: 1859 1860 @example 1861 | Name | Phone | Age | 1862 |-------+-------+-----| 1863 | Peter | 1234 | 17 | 1864 | Anna | 4321 | 25 | 1865 @end example 1866 1867 A table is re-aligned automatically each time you press 1868 @kbd{@key{TAB}}, @kbd{@key{RET}} or @kbd{C-c C-c} inside the table. 1869 @kbd{@key{TAB}} also moves to the next field---@kbd{@key{RET}} to the 1870 next row---and creates new table rows at the end of the table or 1871 before horizontal lines. The indentation of the table is set by the 1872 first line. Horizontal rules are automatically expanded on every 1873 re-align to span the whole table width. So, to create the above 1874 table, you would only type 1875 1876 @example 1877 |Name|Phone|Age| 1878 |- 1879 @end example 1880 1881 @noindent 1882 and then press @kbd{@key{TAB}} to align the table and start filling in 1883 fields. Even faster would be to type @samp{|Name|Phone|Age} followed by 1884 @kbd{C-c @key{RET}}. 1885 1886 When typing text into a field, Org treats @kbd{@key{DEL}}, 1887 @kbd{Backspace}, and all character keys in a special way, so that 1888 inserting and deleting avoids shifting other fields. Also, when 1889 typing @emph{immediately} after point was moved into a new field with 1890 @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}, the field is 1891 automatically made blank. If this behavior is too unpredictable for 1892 you, configure the option @code{org-table-auto-blank-field}. 1893 1894 @anchor{Creation and conversion} 1895 @subheading Creation and conversion 1896 1897 @table @asis 1898 @item @kbd{C-c |} (@code{org-table-create-or-convert-from-region}) 1899 @kindex C-c | 1900 @findex org-table-create-or-convert-from-region 1901 Convert the active region to table. If every line contains at least 1902 one @kbd{@key{TAB}} character, the function assumes that the material 1903 is tab separated. If every line contains a comma, comma-separated 1904 values (CSV) are assumed. If not, lines are split at whitespace 1905 into fields. You can use a prefix argument to force a specific 1906 separator: @kbd{C-u} forces CSV, @kbd{C-u C-u} forces 1907 @kbd{@key{TAB}}, @kbd{C-u C-u C-u} prompts for a regular 1908 expression to match the separator, and a numeric argument 1909 N indicates that at least N consecutive spaces, or alternatively 1910 a @kbd{@key{TAB}} will be the separator. 1911 1912 If there is no active region, this command creates an empty Org 1913 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}}. 1914 @end table 1915 1916 @anchor{Re-aligning and field motion} 1917 @subheading Re-aligning and field motion 1918 1919 @table @asis 1920 @item @kbd{C-c C-c} (@code{org-table-align}) 1921 @kindex C-c C-c 1922 @findex org-table-align 1923 Re-align the table without moving point. 1924 1925 @item @kbd{@key{TAB}} (@code{org-table-next-field}) 1926 @kindex TAB 1927 @findex org-table-next-field 1928 Re-align the table, move to the next field. Creates a new row if 1929 necessary. 1930 1931 @item @kbd{M-x org-table-blank-field} 1932 @findex org-table-blank-field 1933 Blank the current table field or active region. 1934 1935 @item @kbd{S-@key{TAB}} (@code{org-table-previous-field}) 1936 @kindex S-TAB 1937 @findex org-table-previous-field 1938 Re-align, move to previous field. 1939 1940 @item @kbd{@key{RET}} (@code{org-table-next-row}) 1941 @kindex RET 1942 @findex org-table-next-row 1943 Re-align the table and move down to next row. Creates a new row if 1944 necessary. At the beginning or end of a line, @kbd{@key{RET}} still 1945 inserts a new line, so it can be used to split a table. 1946 1947 @item @kbd{M-a} (@code{org-table-beginning-of-field}) 1948 @kindex M-a 1949 @findex org-table-beginning-of-field 1950 Move to beginning of the current table field, or on to the previous 1951 field. 1952 1953 @item @kbd{M-e} (@code{org-table-end-of-field}) 1954 @kindex M-e 1955 @findex org-table-end-of-field 1956 Move to end of the current table field, or on to the next field. 1957 @end table 1958 1959 @anchor{Column and row editing} 1960 @subheading Column and row editing 1961 1962 @table @asis 1963 @item @kbd{M-@key{LEFT}} (@code{org-table-move-column-left}) 1964 @kindex M-LEFT 1965 @findex org-table-move-column-left 1966 Move the current column left. 1967 1968 @item @kbd{M-@key{RIGHT}} (@code{org-table-move-column-right}) 1969 @kindex M-RIGHT 1970 @findex org-table-move-column-right 1971 Move the current column right. 1972 1973 @item @kbd{M-S-@key{LEFT}} (@code{org-table-delete-column}) 1974 @kindex M-S-LEFT 1975 @findex org-table-delete-column 1976 Kill the current column. 1977 1978 @item @kbd{M-S-@key{RIGHT}} (@code{org-table-insert-column}) 1979 @kindex M-S-RIGHT 1980 @findex org-table-insert-column 1981 Insert a new column at point position. Move the recent column and 1982 all cells to the right of this column to the right. 1983 1984 @item @kbd{M-@key{UP}} (@code{org-table-move-row-up}) 1985 @kindex M-UP 1986 @findex org-table-move-row-up 1987 Move the current row up. 1988 1989 @item @kbd{M-@key{DOWN}} (@code{org-table-move-row-down}) 1990 @kindex M-DOWN 1991 @findex org-table-move-row-down 1992 Move the current row down. 1993 1994 @item @kbd{M-S-@key{UP}} (@code{org-table-kill-row}) 1995 @kindex M-S-UP 1996 @findex org-table-kill-row 1997 Kill the current row or horizontal line. 1998 1999 @item @kbd{S-@key{UP}} (@code{org-table-move-cell-up}) 2000 @kindex S-UP 2001 @findex org-table-move-cell-up 2002 Move cell up by swapping with adjacent cell. 2003 2004 @item @kbd{S-@key{DOWN}} (@code{org-table-move-cell-down}) 2005 @kindex S-DOWN 2006 @findex org-table-move-cell-down 2007 Move cell down by swapping with adjacent cell. 2008 2009 @item @kbd{S-@key{LEFT}} (@code{org-table-move-cell-left}) 2010 @kindex S-LEFT 2011 @findex org-table-move-cell-left 2012 Move cell left by swapping with adjacent cell. 2013 2014 @item @kbd{S-@key{RIGHT}} (@code{org-table-move-cell-right}) 2015 @kindex S-RIGHT 2016 @findex org-table-move-cell-right 2017 Move cell right by swapping with adjacent cell. 2018 2019 @item @kbd{M-S-@key{DOWN}} (@code{org-table-insert-row}) 2020 @kindex M-S-DOWN 2021 @findex org-table-insert-row 2022 Insert a new row above the current row. With a prefix argument, the 2023 line is created below the current one. 2024 2025 @item @kbd{C-c -} (@code{org-table-insert-hline}) 2026 @kindex C-c - 2027 @findex org-table-insert-hline 2028 Insert a horizontal line below current row. With a prefix argument, 2029 the line is created above the current line. 2030 2031 @item @kbd{C-c @key{RET}} (@code{org-table-hline-and-move}) 2032 @kindex C-c RET 2033 @findex org-table-hline-and-move 2034 Insert a horizontal line below current row, and move point into the 2035 row below that line. 2036 2037 @item @kbd{C-c ^} (@code{org-table-sort-lines}) 2038 @kindex C-c ^ 2039 @findex org-table-sort-lines 2040 Sort the table lines in the region. The position of point indicates 2041 the column to be used for sorting, and the range of lines is the 2042 range between the nearest horizontal separator lines, or the entire 2043 table. If point is before the first column, you are prompted for 2044 the sorting column. If there is an active region, the mark 2045 specifies the first line and the sorting column, while point should 2046 be in the last line to be included into the sorting. The command 2047 prompts for the sorting type, alphabetically, numerically, or by 2048 time. You can sort in normal or reverse order. You can also supply 2049 your own key extraction and comparison functions. When called with 2050 a prefix argument, alphabetic sorting is case-sensitive. 2051 @end table 2052 2053 @anchor{Regions} 2054 @subheading Regions 2055 2056 @table @asis 2057 @item @kbd{C-c C-x M-w} (@code{org-table-copy-region}) 2058 @kindex C-c C-x M-w 2059 @findex org-table-copy-region 2060 Copy a rectangular region from a table to a special clipboard. 2061 Point and mark determine edge fields of the rectangle. If there is 2062 no active region, copy just the current field. The process ignores 2063 horizontal separator lines. 2064 2065 @item @kbd{C-c C-x C-w} (@code{org-table-cut-region}) 2066 @kindex C-c C-x C-w 2067 @findex org-table-cut-region 2068 Copy a rectangular region from a table to a special clipboard, and 2069 blank all fields in the rectangle. So this is the ``cut'' operation. 2070 2071 @item @kbd{C-c C-x C-y} (@code{org-table-paste-rectangle}) 2072 @kindex C-c C-x C-y 2073 @findex org-table-paste-rectangle 2074 Paste a rectangular region into a table. The upper left corner ends 2075 up in the current field. All involved fields are overwritten. If 2076 the rectangle does not fit into the present table, the table is 2077 enlarged as needed. The process ignores horizontal separator lines. 2078 2079 @item @kbd{M-@key{RET}} (@code{org-table-wrap-region}) 2080 @kindex M-RET 2081 @findex org-table-wrap-region 2082 Split the current field at point position and move the rest to the 2083 line below. If there is an active region, and both point and mark 2084 are in the same column, the text in the column is wrapped to minimum 2085 width for the given number of lines. A numeric prefix argument may 2086 be used to change the number of desired lines. If there is no 2087 region, but you specify a prefix argument, the current field is made 2088 blank, and the content is appended to the field above. 2089 @end table 2090 2091 @anchor{Calculations} 2092 @subheading Calculations 2093 2094 @cindex formula, in tables 2095 @cindex calculations, in tables 2096 2097 @table @asis 2098 @item @kbd{C-c +} (@code{org-table-sum}) 2099 @kindex C-c + 2100 @findex org-table-sum 2101 Sum the numbers in the current column, or in the rectangle defined 2102 by the active region. The result is shown in the echo area and can 2103 be inserted with @kbd{C-y}. 2104 2105 @item @kbd{S-@key{RET}} (@code{org-table-copy-down}) 2106 @kindex S-RET 2107 @findex org-table-copy-down 2108 @vindex org-table-copy-increment 2109 When current field is empty, copy from first non-empty field above. 2110 When not empty, copy current field down to next row and move point 2111 along with it. 2112 2113 Depending on the variable @code{org-table-copy-increment}, integer and 2114 time stamp field values, and fields prefixed or suffixed with 2115 a whole number, can be incremented during copy. Also, a @code{0} prefix 2116 argument temporarily disables the increment. 2117 2118 This key is also used by shift-selection and related modes (see 2119 @ref{Conflicts}). 2120 @end table 2121 2122 @anchor{Miscellaneous (1)} 2123 @subheading Miscellaneous 2124 2125 @table @asis 2126 @item @kbd{C-c `} (@code{org-table-edit-field}) 2127 @kindex C-c ` 2128 @findex org-table-edit-field 2129 Edit the current field in a separate window. This is useful for 2130 fields that are not fully visible (see @ref{Column Width and Alignment}). 2131 When called with a @kbd{C-u} prefix, just make the full field 2132 visible, so that it can be edited in place. When called with two 2133 @kbd{C-u} prefixes, make the editor window follow point through 2134 the table and always show the current field. The follow mode exits 2135 automatically when point leaves the table, or when you repeat this 2136 command with @kbd{C-u C-u C-c `}. 2137 2138 @item @kbd{M-x org-table-import} 2139 @findex org-table-import 2140 Import a file as a table. The table should be TAB or whitespace 2141 separated. Use, for example, to import a spreadsheet table or data 2142 from a database, because these programs generally can write 2143 TAB-separated text files. This command works by inserting the file 2144 into the buffer and then converting the region to a table. Any 2145 prefix argument is passed on to the converter, which uses it to 2146 determine the separator. 2147 2148 @item @kbd{C-c |} (@code{org-table-create-or-convert-from-region}) 2149 @kindex C-c | 2150 @findex org-table-create-or-convert-from-region 2151 Tables can also be imported by pasting tabular text into the Org 2152 buffer, selecting the pasted text with @kbd{C-x C-x} and then 2153 using the @kbd{C-c |} command (see @ref{Creation and conversion}). 2154 2155 @item @kbd{M-x org-table-export} 2156 @findex org-table-export 2157 @vindex org-table-export-default-format 2158 Export the table, by default as a TAB-separated file. Use for data 2159 exchange with, for example, spreadsheet or database programs. The 2160 format used to export the file can be configured in the variable 2161 @code{org-table-export-default-format}. You may also use properties 2162 @samp{TABLE_EXPORT_FILE} and @samp{TABLE_EXPORT_FORMAT} to specify the file 2163 name and the format for table export in a subtree. Org supports 2164 quite general formats for exported tables. The exporter format is 2165 the same as the format used by Orgtbl radio tables, see @ref{Translator functions}, for a detailed description. 2166 2167 @item @kbd{M-x org-table-header-line-mode} 2168 @findex org-table-header-line-mode 2169 @vindex org-table-header-line-p 2170 Turn on the display of the first data row of the table at point in 2171 the window header line when this first row is not visible anymore in 2172 the buffer. You can activate this minor mode by default by setting 2173 the option @code{org-table-header-line-p} to @code{t}. 2174 2175 @item @kbd{M-x org-table-transpose-table-at-point} 2176 @findex org-table-transpose-table-at-point 2177 Transpose the table at point and eliminate hlines. 2178 @end table 2179 2180 @node Column Width and Alignment 2181 @section Column Width and Alignment 2182 2183 @cindex narrow columns in tables 2184 @cindex alignment in tables 2185 2186 The width of columns is automatically determined by the table editor. 2187 The alignment of a column is determined automatically from the 2188 fraction of number-like versus non-number fields in the column. 2189 2190 @vindex org-table-automatic-realign 2191 Editing a field may modify alignment of the table. Moving 2192 a contiguous row or column---i.e., using @kbd{@key{TAB}} or 2193 @kbd{@key{RET}}---automatically re-aligns it. If you want to disable 2194 this behavior, set @code{org-table-automatic-realign} to @code{nil}. In any 2195 case, you can always align manually a table: 2196 2197 @table @asis 2198 @item @kbd{C-c C-c} (@code{org-table-align}) 2199 @kindex C-c C-c 2200 @findex org-table-align 2201 Align the current table. 2202 @end table 2203 2204 @vindex org-startup-align-all-tables 2205 Setting the option @code{org-startup-align-all-tables} re-aligns all tables 2206 in a file upon visiting it. You can also set this option on 2207 a per-file basis with: 2208 2209 @example 2210 #+STARTUP: align 2211 #+STARTUP: noalign 2212 @end example 2213 2214 Sometimes a single field or a few fields need to carry more text, 2215 leading to inconveniently wide columns. Maybe you want to hide away 2216 several columns or display them with a fixed width, regardless of 2217 content, as shown in the following example. 2218 2219 @example 2220 |---+---------------------+--------| |---+-------…+…| 2221 | | <6> | | | | <6> …|…| 2222 | 1 | one | some | ----\ | 1 | one …|…| 2223 | 2 | two | boring | ----/ | 2 | two …|…| 2224 | 3 | This is a long text | column | | 3 | This i…|…| 2225 |---+---------------------+--------| |---+-------…+…| 2226 @end example 2227 2228 To set the width of a column, one field anywhere in the column may 2229 contain just the string @samp{<N>} where @var{N} specifies the width 2230 as a number of characters. You control displayed width of columns 2231 with the following tools: 2232 2233 @table @asis 2234 @item @kbd{C-c @key{TAB}} (@code{org-table-toggle-column-width}) 2235 @kindex C-c TAB 2236 @findex org-table-toggle-column-width 2237 Shrink or expand current column. 2238 2239 If a width cookie specifies a width W for the column, shrinking it 2240 displays the first W visible characters only. Otherwise, the column 2241 is shrunk to a single character. 2242 2243 When called before the first column or after the last one, ask for 2244 a list of column ranges to operate on. 2245 2246 @item @kbd{C-u C-c @key{TAB}} (@code{org-table-shrink}) 2247 @kindex C-u C-c TAB 2248 @findex org-table-shrink 2249 Shrink all columns with a column width. Expand the others. 2250 2251 @item @kbd{C-u C-u C-c @key{TAB}} (@code{org-table-expand}) 2252 @kindex C-u C-u C-c TAB 2253 @findex org-table-expand 2254 Expand all columns. 2255 @end table 2256 2257 To see the full text of a shrunk field, hold the mouse over it: 2258 a tool-tip window then shows the full contents of the field. 2259 Alternatively, @kbd{C-h .} (@code{display-local-help}) reveals them, 2260 too. For convenience, any change near the shrunk part of a column 2261 expands it. 2262 2263 @vindex org-startup-shrink-all-tables 2264 Setting the option @code{org-startup-shrink-all-tables} shrinks all columns 2265 containing a width cookie in a file the moment it is visited. You can 2266 also set this option on a per-file basis with: 2267 2268 @example 2269 #+STARTUP: shrink 2270 @end example 2271 2272 2273 If you would like to overrule the automatic alignment of number-rich 2274 columns to the right and of string-rich columns to the left, you can 2275 use @samp{<r>}, @samp{<c>} or @samp{<l>} in a similar fashion. You may also combine 2276 alignment and field width like this: @samp{<r10>}. 2277 2278 Lines which only contain these formatting cookies are removed 2279 automatically upon exporting the document. 2280 2281 @node Column Groups 2282 @section Column Groups 2283 2284 @cindex grouping columns in tables 2285 2286 When Org exports tables, it does so by default without vertical lines 2287 because that is visually more satisfying in general. Occasionally 2288 however, vertical lines can be useful to structure a table into groups 2289 of columns, much like horizontal lines can do for groups of rows. In 2290 order to specify column groups, you can use a special row where the 2291 first field contains only @samp{/}. The further fields can either contain 2292 @samp{<} to indicate that this column should start a group, @samp{>} to indicate 2293 the end of a column, or @samp{<>} (no space between @samp{<} and @samp{>}) to make 2294 a column a group of its own. Upon export, boundaries between column 2295 groups are marked with vertical lines. Here is an example: 2296 2297 @example 2298 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | 2299 |---+-----+-----+-----+---------+------------| 2300 | / | < | | > | < | > | 2301 | 1 | 1 | 1 | 1 | 1 | 1 | 2302 | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 | 2303 | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 | 2304 |---+-----+-----+-----+---------+------------| 2305 #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1))) 2306 @end example 2307 2308 It is also sufficient to just insert the column group starters after 2309 every vertical line you would like to have: 2310 2311 @example 2312 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | 2313 |---+-----+-----+-----+---------+------------| 2314 | / | < | | | < | | 2315 @end example 2316 2317 @node Orgtbl Mode 2318 @section The Orgtbl Minor Mode 2319 2320 @cindex Orgtbl mode 2321 @cindex minor mode for tables 2322 2323 @findex orgtbl-mode 2324 If you like the intuitive way the Org table editor works, you might 2325 also want to use it in other modes like Text mode or Mail mode. The 2326 minor mode Orgtbl mode makes this possible. You can always toggle the 2327 mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for 2328 example in Message mode, use 2329 2330 @lisp 2331 (add-hook 'message-mode-hook #'turn-on-orgtbl) 2332 @end lisp 2333 2334 Furthermore, with some special setup, it is possible to maintain 2335 tables in arbitrary syntax with Orgtbl mode. For example, it is 2336 possible to construct @LaTeX{} tables with the underlying ease and power 2337 of Orgtbl mode, including spreadsheet capabilities. For details, see 2338 @ref{Tables in Arbitrary Syntax}. 2339 2340 @node The Spreadsheet 2341 @section The Spreadsheet 2342 2343 @cindex calculations, in tables 2344 @cindex spreadsheet capabilities 2345 @cindex Calc package 2346 2347 The table editor makes use of the Emacs Calc package to implement 2348 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms 2349 to derive fields from other fields. While fully featured, Org's 2350 implementation is not identical to other spreadsheets. For example, 2351 Org knows the concept of a @emph{column formula} that will be applied to 2352 all non-header fields in a column without having to copy the formula 2353 to each relevant field. There is also a formula debugger, and a 2354 formula editor with features for highlighting fields in the table 2355 corresponding to the references at point in the formula, moving these 2356 references by arrow keys. 2357 2358 @menu 2359 * References:: How to refer to another field or range. 2360 * Formula syntax for Calc:: Using Calc to compute stuff. 2361 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp. 2362 * Durations and time values:: How to compute durations and time values. 2363 * Field and range formulas:: Formula for specific (ranges of) fields. 2364 * Column formulas:: Formulas valid for an entire column. 2365 * Lookup functions:: Lookup functions for searching tables. 2366 * Editing and debugging formulas:: Fixing formulas. 2367 * Updating the table:: Recomputing all dependent fields. 2368 * Advanced features:: Field and column names, automatic recalculation... 2369 @end menu 2370 2371 @node References 2372 @subsection References 2373 2374 @cindex references 2375 2376 To compute fields in the table from other fields, formulas must 2377 reference other fields or ranges. In Org, fields can be referenced by 2378 name, by absolute coordinates, and by relative coordinates. To find 2379 out what the coordinates of a field are, press @kbd{C-c ?} in 2380 that field, or press @kbd{C-c @}} to toggle the display of a grid. 2381 2382 @anchor{Field references} 2383 @subsubheading Field references 2384 2385 @cindex field references 2386 @cindex references, to fields 2387 Formulas can reference the value of another field in two ways. Like 2388 in any other spreadsheet, you may reference fields with 2389 a letter/number combination like @samp{B3}, meaning the second field in the 2390 third row. However, Org prefers to use another, more general 2391 representation that looks like this:@footnote{Org understands references typed by the user as @samp{B4}, but it 2392 does not use this syntax when offering a formula for editing. You can 2393 customize this behavior using the variable 2394 @code{org-table-use-standard-references}.} 2395 2396 @example 2397 @@ROW$COLUMN 2398 @end example 2399 2400 2401 Column specifications can be absolute like @samp{$1}, @samp{$2}, @dots{}, @samp{$N}, or 2402 relative to the current column, i.e., the column of the field which is 2403 being computed, like @samp{$+1} or @samp{$-2}. @samp{$<} and @samp{$>} are immutable 2404 references to the first and last column, respectively, and you can use 2405 @samp{$>>>} to indicate the third column from the right. 2406 2407 The row specification only counts data lines and ignores horizontal 2408 separator lines, or ``hlines''. Like with columns, you can use absolute 2409 row numbers @samp{@@1}, @samp{@@2}, @dots{}, @samp{@@N}, and row numbers relative to the 2410 current row like @samp{@@+3} or @samp{@@-1}. @samp{@@<} and @samp{@@>} are immutable 2411 references the first and last row in the table, respectively. You may 2412 also specify the row relative to one of the hlines: @samp{@@I} refers to the 2413 first hline, @samp{@@II} to the second, etc. @samp{@@-I} refers to the first such 2414 line above the current line, @samp{@@+I} to the first such line below the 2415 current line. You can also write @samp{@@III+2} which is the second data 2416 line after the third hline in the table. 2417 2418 @samp{@@0} and @samp{$0} refer to the current row and column, respectively, i.e., 2419 to the row/column for the field being computed. Also, if you omit 2420 either the column or the row part of the reference, the current 2421 row/column is implied. 2422 2423 Org's references with @emph{unsigned} numbers are fixed references in the 2424 sense that if you use the same reference in the formula for two 2425 different fields, the same field is referenced each time. Org's 2426 references with @emph{signed} numbers are floating references because the 2427 same reference operator can reference different fields depending on 2428 the field being calculated by the formula. 2429 2430 Here are a few examples: 2431 2432 @multitable @columnfractions 0.2 0.8 2433 @item @samp{@@2$3} 2434 @tab 2nd row, 3rd column (same as @samp{C2}) 2435 @item @samp{$5} 2436 @tab column 5 in the current row (same as @samp{E&}) 2437 @item @samp{@@2} 2438 @tab current column, row 2 2439 @item @samp{@@-1$-3} 2440 @tab field one row up, three columns to the left 2441 @item @samp{@@-I$2} 2442 @tab field just under hline above current row, column 2 2443 @item @samp{@@>$5} 2444 @tab field in the last row, in column 5 2445 @end multitable 2446 2447 @anchor{Range references} 2448 @subsubheading Range references 2449 2450 @cindex range references 2451 @cindex references, to ranges 2452 You may reference a rectangular range of fields by specifying two 2453 field references connected by two dots @samp{..}. The ends are included in 2454 the range. If both fields are in the current row, you may simply use 2455 @samp{$2..$7}, but if at least one field is in a different row, you need to 2456 use the general @samp{@@ROW$COLUMN} format at least for the first field, 2457 i.e., the reference must start with @samp{@@} in order to be interpreted 2458 correctly. Examples: 2459 2460 @multitable @columnfractions 0.2 0.8 2461 @item @samp{$1..$3} 2462 @tab first three fields in the current row 2463 @item @samp{$P..$Q} 2464 @tab range, using column names (see @ref{Advanced features}) 2465 @item @samp{$<<<..$>>} 2466 @tab start in third column, continue to the last but one 2467 @item @samp{@@2$1..@@4$3} 2468 @tab nine fields between these two fields (same as @samp{A2..C4}) 2469 @item @samp{@@-1$-2..@@-1} 2470 @tab 3 fields in the row above, starting from 2 columns on the left 2471 @item @samp{@@I..II} 2472 @tab between first and second hline, short for @samp{@@I..@@II} 2473 @end multitable 2474 2475 @noindent 2476 Range references return a vector of values that can be fed into Calc 2477 vector functions. Empty fields in ranges are normally suppressed, so 2478 that the vector contains only the non-empty fields. For other options 2479 with the mode switches @samp{E}, @samp{N} and examples, see @ref{Formula syntax for Calc}. 2480 2481 @anchor{Field coordinates in formulas} 2482 @subsubheading Field coordinates in formulas 2483 2484 @cindex field coordinates 2485 @cindex coordinates, of field 2486 @cindex row, of field coordinates 2487 @cindex column, of field coordinates 2488 @vindex org-table-current-column 2489 @vindex org-table-current-dline 2490 One of the very first actions during evaluation of Calc formulas and 2491 Lisp formulas is to substitute @samp{@@#} and @samp{$#} in the formula with the 2492 row or column number of the field where the current result will go to. 2493 The traditional Lisp formula equivalents are @code{org-table-current-dline} 2494 and @code{org-table-current-column}. Examples: 2495 2496 @table @asis 2497 @item @samp{if(@@# % 2, $#, string(""))} 2498 Insert column number on odd rows, set field to empty on even rows. 2499 2500 @item @samp{$2 = '(identity remote(FOO, @@@@#$1))} 2501 Copy text or values of each row of column 1 of the table named 2502 @var{FOO} into column 2 of the current table. 2503 2504 @item @samp{@@3 = 2 * remote(FOO, @@1$$#)} 2505 Insert the doubled value of each column of row 1 of the table 2506 named @var{FOO} into row 3 of the current table. 2507 @end table 2508 2509 @noindent 2510 For the second and third examples, table @var{FOO} must have at 2511 least as many rows or columns as the current table. Note that this is 2512 inefficient@footnote{ The computation time scales as O(N^2) because table 2513 @var{FOO} is parsed for each field to be copied.} for large 2514 number of rows. 2515 2516 @anchor{Named references} 2517 @subsubheading Named references 2518 2519 @cindex named references 2520 @cindex references, named 2521 @cindex name, of column or field 2522 @cindex constants, in calculations 2523 @cindex @samp{CONSTANTS}, keyword 2524 @vindex org-table-formula-constants 2525 2526 @samp{$name} is interpreted as the name of a column, parameter or constant. 2527 Constants are defined globally through the variable 2528 @code{org-table-formula-constants}, and locally---for the file---through 2529 a line like this example: 2530 2531 @example 2532 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 2533 @end example 2534 2535 2536 @vindex constants-unit-system 2537 @pindex constants.el 2538 Also, properties (see @ref{Properties and Columns}) can be used as 2539 constants in table formulas: for a property @samp{Xyz} use the name 2540 @samp{$PROP_Xyz}, and the property will be searched in the current outline 2541 entry and in the hierarchy above it. If you have the @samp{constants.el} 2542 package, it will also be used to resolve constants, including natural 2543 constants like @samp{$h} for Planck's constant, and units like @samp{$km} for 2544 kilometers@footnote{The file @samp{constants.el} can supply the values of constants in 2545 two different unit systems, @samp{SI} and @samp{cgs}. Which one is used depends 2546 on the value of the variable @code{constants-unit-system}. You can use the 2547 @samp{STARTUP} options @samp{constSI} and @samp{constcgs} to set this value for the 2548 current buffer.}. Column names and parameters can be specified in 2549 special table lines. These are described below, see @ref{Advanced features}. All names must start with a letter, and further consist 2550 of letters and numbers. 2551 2552 @anchor{Remote references} 2553 @subsubheading Remote references 2554 2555 @cindex remote references 2556 @cindex references, remote 2557 @cindex references, to a different table 2558 @cindex name, of column or field 2559 @cindex @samp{NAME}, keyword 2560 You may also reference constants, fields and ranges from a different 2561 table, either in the current file or even in a different file. The 2562 syntax is 2563 2564 @example 2565 remote(NAME,REF) 2566 @end example 2567 2568 2569 @noindent 2570 where @var{NAME} can be the name of a table in the current file 2571 as set by a @samp{#+NAME:} line before the table. It can also be the ID of 2572 an entry, even in a different file, and the reference then refers to 2573 the first table in that entry. @var{REF} is an absolute field or 2574 range reference as described above for example @samp{@@3$3} or @samp{$somename}, 2575 valid in the referenced table. 2576 2577 @cindex table indirection 2578 When @var{NAME} has the format @samp{@@ROW$COLUMN}, it is substituted 2579 with the name or ID found in this field of the current table. For 2580 example @samp{remote($1, @@@@>$2)} @result{} @samp{remote(year_2013, @@@@>$1)}. The format 2581 @samp{B3} is not supported because it can not be distinguished from a plain 2582 table name or ID@. 2583 2584 @node Formula syntax for Calc 2585 @subsection Formula syntax for Calc 2586 2587 @cindex formula syntax, Calc 2588 @cindex syntax, of formulas 2589 2590 A formula can be any algebraic expression understood by the Emacs Calc 2591 package. Note that Calc has the non-standard convention that @samp{/} has 2592 lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as 2593 @samp{(a/(b*c))}. Before evaluation by @code{calc-eval} (see @ref{Calling Calc from Your Programs,Calling Calc from 2594 Your Lisp Programs,,calc,}), variable substitution takes place according to 2595 the rules described above. 2596 2597 @cindex vectors, in table calculations 2598 The range vectors can be directly fed into the Calc vector functions 2599 like @code{vmean} and @code{vsum}. 2600 2601 @cindex format specifier, in spreadsheet 2602 @cindex mode, for Calc 2603 @vindex org-calc-default-modes 2604 A formula can contain an optional mode string after a semicolon. This 2605 string consists of flags to influence Calc and other modes during 2606 execution. By default, Org uses the standard Calc modes (precision 2607 12, angular units degrees, fraction and symbolic modes off). The 2608 display format, however, has been changed to @samp{(float 8)} to keep 2609 tables compact. The default settings can be configured using the 2610 variable @code{org-calc-default-modes}. 2611 2612 @table @asis 2613 @item @samp{p20} 2614 Set the internal Calc calculation precision to 20 digits. 2615 2616 @item @samp{n3}, @samp{s3}, @samp{e2}, @samp{f4} 2617 Normal, scientific, engineering or fixed format of the result of 2618 Calc passed back to Org. Calc formatting is unlimited in precision 2619 as long as the Calc calculation precision is greater. 2620 2621 @item @samp{D}, @samp{R} 2622 Degree and radian angle modes of Calc. 2623 2624 @item @samp{F}, @samp{S} 2625 Fraction and symbolic modes of Calc. 2626 2627 @item @samp{u} 2628 Units simplification mode of Calc. Calc is also a symbolic 2629 calculator and is capable of working with values having a unit, 2630 represented with numerals followed by a unit string in Org table 2631 cells. This mode instructs Calc to simplify the units in the 2632 computed expression before returning the result. 2633 2634 @item @samp{T}, @samp{t}, @samp{U} 2635 Duration computations in Calc or Lisp, @ref{Durations and time values}. 2636 2637 @item @samp{E} 2638 If and how to consider empty fields. Without @samp{E} empty fields in 2639 range references are suppressed so that the Calc vector or Lisp list 2640 contains only the non-empty fields. With @samp{E} the empty fields are 2641 kept. For empty fields in ranges or empty field references the 2642 value @samp{nan} (not a number) is used in Calc formulas and the empty 2643 string is used for Lisp formulas. Add @samp{N} to use 0 instead for both 2644 formula types. For the value of a field the mode @samp{N} has higher 2645 precedence than @samp{E}. 2646 2647 @item @samp{N} 2648 Interpret all fields as numbers, use 0 for non-numbers. See the 2649 next section to see how this is essential for computations with Lisp 2650 formulas. In Calc formulas it is used only occasionally because 2651 there number strings are already interpreted as numbers without @samp{N}. 2652 2653 @item @samp{L} 2654 Literal, for Lisp formulas only. See the next section. 2655 @end table 2656 2657 Unless you use large integer numbers or high-precision calculation and 2658 display for floating point numbers you may alternatively provide 2659 a @code{printf} format specifier to reformat the Calc result after it has 2660 been passed back to Org instead of letting Calc already do the 2661 formatting@footnote{The printf reformatting is limited in precision because the 2662 value passed to it is converted into an ``integer'' or ``double''. The 2663 ``integer'' is limited in size by truncating the signed value to 32 2664 bits. The ``double'' is limited in precision to 64 bits overall which 2665 leaves approximately 16 significant decimal digits.}. A few examples: 2666 2667 @multitable {aaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 2668 @item @samp{$1+$2} 2669 @tab Sum of first and second field 2670 @item @samp{$1+$2;%.2f} 2671 @tab Same, format result to two decimals 2672 @item @samp{exp($2)+exp($1)} 2673 @tab Math functions can be used 2674 @item @samp{$0;%.1f} 2675 @tab Reformat current cell to 1 decimal 2676 @item @samp{($3-32)*5/9} 2677 @tab Degrees F @arrow{} C conversion 2678 @item @samp{$c/$1/$cm} 2679 @tab Hz @arrow{} cm conversion, using @samp{constants.el} 2680 @item @samp{tan($1);Dp3s1} 2681 @tab Compute in degrees, precision 3, display SCI 1 2682 @item @samp{sin($1);Dp3%.1e} 2683 @tab Same, but use @code{printf} specifier for display 2684 @item @samp{vmean($2..$7)} 2685 @tab Compute column range mean, using vector function 2686 @item @samp{vmean($2..$7);EN} 2687 @tab Same, but treat empty fields as 0 2688 @item @samp{taylor($3,x=7,2)} 2689 @tab Taylor series of $3, at x=7, second degree 2690 @end multitable 2691 2692 Calc also contains a complete set of logical operations (see @ref{Logical Operations,Logical 2693 Operations,,calc,}). For example 2694 2695 @table @asis 2696 @item @samp{if($1 < 20, teen, string(""))} 2697 @samp{"teen"} if age @samp{$1} is less than 20, else the Org table result 2698 field is set to empty with the empty string. 2699 2700 @item @samp{if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1} 2701 Sum of the first two columns. When at least one of the input fields 2702 is empty the Org table result field is set to empty. @samp{E} is 2703 required to not convert empty fields to 0. @samp{f-1} is an optional 2704 Calc format string similar to @samp{%.1f} but leaves empty results empty. 2705 2706 @item @samp{if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7)); E} 2707 Mean value of a range unless there is any empty field. Every field 2708 in the range that is empty is replaced by @samp{nan} which lets @samp{vmean} 2709 result in @samp{nan}. Then @samp{typeof =} 12= detects the @samp{nan} from @code{vmean} 2710 and the Org table result field is set to empty. Use this when the 2711 sample set is expected to never have missing values. 2712 2713 @item @samp{if("$1..$7" == "[]", string(""), vmean($1..$7))} 2714 Mean value of a range with empty fields skipped. Every field in the 2715 range that is empty is skipped. When all fields in the range are 2716 empty the mean value is not defined and the Org table result field 2717 is set to empty. Use this when the sample set can have a variable 2718 size. 2719 2720 @item @samp{vmean($1..$7); EN} 2721 To complete the example before: Mean value of a range with empty 2722 fields counting as samples with value 0. Use this only when 2723 incomplete sample sets should be padded with 0 to the full size. 2724 @end table 2725 2726 You can add your own Calc functions defined in Emacs Lisp with 2727 @code{defmath} and use them in formula syntax for Calc. 2728 2729 @node Formula syntax for Lisp 2730 @subsection Emacs Lisp forms as formulas 2731 2732 @cindex Lisp forms, as table formulas 2733 2734 It is also possible to write a formula in Emacs Lisp. This can be 2735 useful for string manipulation and control structures, if Calc's 2736 functionality is not enough. 2737 2738 A formula is evaluated as a Lisp form when it starts with a 2739 single-quote followed by an opening parenthesis. Cell table 2740 references are interpolated into the Lisp form before execution. The 2741 evaluation should return either a string or a number. Evaluation 2742 modes and a @code{printf} format used to render the returned values can be 2743 specified after a semicolon. 2744 2745 By default, references are interpolated as literal Lisp strings: the 2746 field content is replaced in the Lisp form stripped of leading and 2747 trailing white space and surrounded in double-quotes. For example: 2748 2749 @example 2750 '(concat $1 $2) 2751 @end example 2752 2753 2754 @noindent 2755 concatenates the content of columns 1 and column 2. 2756 2757 When the @samp{N} flag is used, all referenced elements are parsed as 2758 numbers and interpolated as Lisp numbers, without quotes. Fields that 2759 cannot be parsed as numbers are interpolated as zeros. For example: 2760 2761 @example 2762 '(+ $1 $2);N 2763 @end example 2764 2765 2766 @noindent 2767 adds columns 1 and 2, equivalent to Calc's @samp{$1+$2}. Ranges are 2768 inserted as space-separated fields, so they can be embedded in list or 2769 vector syntax. For example: 2770 2771 @example 2772 '(apply '+ '($1..$4));N 2773 @end example 2774 2775 2776 @noindent 2777 computes the sum of columns 1 to 4, like Calc's @samp{vsum($1..$4)}. 2778 2779 When the @samp{L} flag is used, all fields are interpolated literally: the 2780 cell content is replaced in the Lisp form stripped of leading and 2781 trailing white space and without quotes. If a reference is intended 2782 to be interpreted as a string by the Lisp form, the reference operator 2783 itself should be enclosed in double-quotes, like @samp{"$3"}. The @samp{L} flag 2784 is useful when strings and numbers are used in the same Lisp form. For 2785 example: 2786 2787 @example 2788 '(substring "$1" $2 $3);L 2789 @end example 2790 2791 2792 @noindent 2793 extracts the part of the string in column 1 between the character 2794 positions specified in the integers in column 2 and 3 and it is easier 2795 to read than the equivalent: 2796 2797 @example 2798 '(substring $1 (string-to-number $2) (string-to-number $3)) 2799 @end example 2800 2801 @node Durations and time values 2802 @subsection Durations and time values 2803 2804 @cindex duration, computing 2805 @cindex time, computing 2806 @vindex org-table-duration-custom-format 2807 2808 If you want to compute time values use the @samp{T}, @samp{t}, or @samp{U} flag, 2809 either in Calc formulas or Elisp formulas: 2810 2811 @example 2812 | Task 1 | Task 2 | Total | 2813 |---------+----------+----------| 2814 | 2:12 | 1:47 | 03:59:00 | 2815 | 2:12 | 1:47 | 03:59 | 2816 | 3:02:20 | -2:07:00 | 0.92 | 2817 #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;U::@@4$3=$1+$2;t 2818 @end example 2819 2820 Input duration values must be of the form @samp{HH:MM[:SS]}, where seconds 2821 are optional. With the @samp{T} flag, computed durations are displayed as 2822 @samp{HH:MM:SS} (see the first formula above). With the @samp{U} flag, seconds 2823 are omitted so that the result is only @samp{HH:MM} (see second formula 2824 above). Zero-padding of the hours field depends upon the value of the 2825 variable @code{org-table-duration-hour-zero-padding}. 2826 2827 With the @samp{t} flag, computed durations are displayed according to the 2828 value of the option @code{org-table-duration-custom-format}, which defaults 2829 to @code{hours} and displays the result as a fraction of hours (see the 2830 third formula in the example above). 2831 2832 Negative duration values can be manipulated as well, and integers are 2833 considered as seconds in addition and subtraction. 2834 2835 @node Field and range formulas 2836 @subsection Field and range formulas 2837 2838 @cindex field formula 2839 @cindex range formula 2840 @cindex formula, for individual table field 2841 @cindex formula, for range of fields 2842 2843 To assign a formula to a particular field, type it directly into the 2844 field, preceded by @samp{:=}, for example @samp{vsum(@@II..III)}. When you press 2845 @kbd{@key{TAB}} or @kbd{@key{RET}} or @kbd{C-c C-c} with point 2846 still in the field, the formula is stored as the formula for this 2847 field, evaluated, and the current field is replaced with the result. 2848 2849 @cindex @samp{TBLFM}, keyword 2850 Formulas are stored in a special @samp{TBLFM} keyword located directly 2851 below the table. If you type the equation in the fourth field of the 2852 third data line in the table, the formula looks like @samp{@@3$4=$1+$2}. 2853 When inserting/deleting/swapping column and rows with the appropriate 2854 commands, @emph{absolute references} (but not relative ones) in stored 2855 formulas are modified in order to still reference the same field. To 2856 avoid this from happening, in particular in range references, anchor 2857 ranges at the table borders (using @samp{@@<}, @samp{@@>}, @samp{$<}, @samp{$>}), or at 2858 hlines using the @samp{@@I} notation. Automatic adaptation of field 2859 references does not happen if you edit the table structure with normal 2860 editing commands---you must fix the formulas yourself. 2861 2862 Instead of typing an equation into the field, you may also use the 2863 following command 2864 2865 @table @asis 2866 @item @kbd{C-u C-c =} (@code{org-table-eval-formula}) 2867 @kindex C-u C-c = 2868 @findex org-table-eval-formula 2869 Install a new formula for the current field. The command prompts 2870 for a formula with default taken from the @samp{TBLFM} keyword, 2871 applies it to the current field, and stores it. 2872 @end table 2873 2874 The left-hand side of a formula can also be a special expression in 2875 order to assign the formula to a number of different fields. There is 2876 no keyboard shortcut to enter such range formulas. To add them, use 2877 the formula editor (see @ref{Editing and debugging formulas}) or edit 2878 the @samp{TBLFM} keyword directly. 2879 2880 @table @asis 2881 @item @samp{$2=} 2882 Column formula, valid for the entire column. This is so common that 2883 Org treats these formulas in a special way, see @ref{Column formulas}. 2884 2885 @item @samp{@@3=} 2886 Row formula, applies to all fields in the specified row. @samp{@@>=} 2887 means the last row. 2888 2889 @item @samp{@@1$2..@@4$3=} 2890 Range formula, applies to all fields in the given rectangular range. 2891 This can also be used to assign a formula to some but not all fields 2892 in a row. 2893 2894 @item @samp{$NAME=} 2895 Named field, see @ref{Advanced features}. 2896 @end table 2897 2898 @node Column formulas 2899 @subsection Column formulas 2900 2901 @cindex column formula 2902 @cindex formula, for table column 2903 2904 When you assign a formula to a simple column reference like @samp{$3=}, the 2905 same formula is used in all fields of that column, with the following 2906 very convenient exceptions: (i) If the table contains horizontal 2907 separator hlines with rows above and below, everything before the 2908 first such hline is considered part of the table @emph{header} and is not 2909 modified by column formulas. Therefore a header is mandatory when you 2910 use column formulas and want to add hlines to group rows, like for 2911 example to separate a total row at the bottom from the summand rows 2912 above. (ii) Fields that already get a value from a field/range 2913 formula are left alone by column formulas. These conditions make 2914 column formulas very easy to use. 2915 2916 To assign a formula to a column, type it directly into any field in 2917 the column, preceded by an equal sign, like @samp{=$1+$2}. When you press 2918 @kbd{@key{TAB}} or @kbd{@key{RET}} or @kbd{C-c C-c} with point 2919 still in the field, the formula is stored as the formula for the 2920 current column, evaluated and the current field replaced with the 2921 result. If the field contains only @samp{=}, the previously stored formula 2922 for this column is used. For each column, Org only remembers the most 2923 recently used formula. In the @samp{TBLFM} keyword, column formulas look 2924 like @samp{$4=$1+$2}. The left-hand side of a column formula can not be 2925 the name of column, it must be the numeric column reference or @samp{$>}. 2926 2927 Instead of typing an equation into the field, you may also use the 2928 following command: 2929 2930 @table @asis 2931 @item @kbd{C-c =} (@code{org-table-eval-formula}) 2932 @kindex C-c = 2933 @findex org-table-eval-formula 2934 Install a new formula for the current column and replace current 2935 field with the result of the formula. The command prompts for 2936 a formula, with default taken from the @samp{TBLFM} keyword, applies it 2937 to the current field and stores it. With a numeric prefix argument, 2938 e.g., @kbd{C-5 C-c =}, the command applies it to that many 2939 consecutive fields in the current column. 2940 @end table 2941 2942 @node Lookup functions 2943 @subsection Lookup functions 2944 2945 @cindex lookup functions in tables 2946 @cindex table lookup functions 2947 2948 Org has three predefined Emacs Lisp functions for lookups in tables. 2949 2950 @table @asis 2951 @item @samp{(org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)} 2952 @findex org-lookup-first 2953 Searches for the first element @var{S} in list 2954 @var{S-LIST} for which 2955 @lisp 2956 (PREDICATE VAL S) 2957 @end lisp 2958 is non-@code{nil}; returns the value from the corresponding position in 2959 list @var{R-LIST}. The default @var{PREDICATE} is 2960 @code{equal}. Note that the parameters @var{VAL} and @var{S} 2961 are passed to @var{PREDICATE} in the same order as the 2962 corresponding parameters are in the call to @code{org-lookup-first}, 2963 where @var{VAL} precedes @var{S-LIST}. If 2964 @var{R-LIST} is @code{nil}, the matching element @var{S} of 2965 @var{S-LIST} is returned. 2966 2967 @item @samp{(org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)} 2968 @findex org-lookup-last 2969 Similar to @code{org-lookup-first} above, but searches for the @emph{last} 2970 element for which @var{PREDICATE} is non-@code{nil}. 2971 2972 @item @samp{(org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)} 2973 @findex org-lookup-all 2974 Similar to @code{org-lookup-first}, but searches for @emph{all} elements for 2975 which @var{PREDICATE} is non-@code{nil}, and returns @emph{all} 2976 corresponding values. This function can not be used by itself in 2977 a formula, because it returns a list of values. However, powerful 2978 lookups can be built when this function is combined with other Emacs 2979 Lisp functions. 2980 @end table 2981 2982 If the ranges used in these functions contain empty fields, the @samp{E} 2983 mode for the formula should usually be specified: otherwise empty 2984 fields are not included in @var{S-LIST} and/or @var{R-LIST} 2985 which can, for example, result in an incorrect mapping from an element 2986 of @var{S-LIST} to the corresponding element of 2987 @var{R-LIST}. 2988 2989 These three functions can be used to implement associative arrays, 2990 count matching cells, rank results, group data, etc. For practical 2991 examples see @uref{https://orgmode.org/worg/org-tutorials/org-lookups.html, this tutorial on Worg}. 2992 2993 @node Editing and debugging formulas 2994 @subsection Editing and debugging formulas 2995 2996 @cindex formula editing 2997 @cindex editing, of table formulas 2998 2999 @vindex org-table-use-standard-references 3000 You can edit individual formulas in the minibuffer or directly in the 3001 field. Org can also prepare a special buffer with all active formulas 3002 of a table. When offering a formula for editing, Org converts 3003 references to the standard format (like @samp{B3} or @samp{D&}) if possible. If 3004 you prefer to only work with the internal format (like @samp{@@3$2} or 3005 @samp{$4}), configure the variable @code{org-table-use-standard-references}. 3006 3007 @table @asis 3008 @item @kbd{C-c =} or @kbd{C-u C-c =} (@code{org-table-eval-formula}) 3009 @kindex C-c = 3010 @kindex C-u C-c = 3011 @findex org-table-eval-formula 3012 Edit the formula associated with the current column/field in the 3013 minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}. 3014 3015 @item @kbd{C-u C-u C-c =} (@code{org-table-eval-formula}) 3016 @kindex C-u C-u C-c = 3017 @findex org-table-eval-formula 3018 Re-insert the active formula (either a field formula, or a column 3019 formula) into the current field, so that you can edit it directly in 3020 the field. The advantage over editing in the minibuffer is that you 3021 can use the command @kbd{C-c ?}. 3022 3023 @item @kbd{C-c ?} (@code{org-table-field-info}) 3024 @kindex C-c ? 3025 @findex org-table-field-info 3026 While editing a formula in a table field, highlight the field(s) 3027 referenced by the reference at point position in the formula. 3028 3029 @item @kbd{C-c @}} (@code{org-table-toggle-coordinate-overlays}) 3030 @kindex C-c @} 3031 @findex org-table-toggle-coordinate-overlays 3032 Toggle the display of row and column numbers for a table, using 3033 overlays. These are updated each time the table is aligned; you can 3034 force it with @kbd{C-c C-c}. 3035 3036 @item @kbd{C-c @{} (@code{org-table-toggle-formula-debugger}) 3037 @kindex C-c @{ 3038 @findex org-table-toggle-formula-debugger 3039 Toggle the formula debugger on and off. See below. 3040 3041 @item @kbd{C-c '} (@code{org-table-edit-formulas}) 3042 @kindex C-c ' 3043 @findex org-table-edit-formulas 3044 Edit all formulas for the current table in a special buffer, where 3045 the formulas are displayed one per line. If the current field has 3046 an active formula, point in the formula editor marks it. While 3047 inside the special buffer, Org automatically highlights any field or 3048 range reference at point position. You may edit, remove and add 3049 formulas, and use the following commands: 3050 3051 @table @asis 3052 @item @kbd{C-c C-c} or @kbd{C-x C-s} (@code{org-table-fedit-finish}) 3053 @kindex C-x C-s 3054 @kindex C-c C-c 3055 @findex org-table-fedit-finish 3056 Exit the formula editor and store the modified formulas. With 3057 @kbd{C-u} prefix, also apply the new formulas to the 3058 entire table. 3059 3060 @item @kbd{C-c C-q} (@code{org-table-fedit-abort}) 3061 @kindex C-c C-q 3062 @findex org-table-fedit-abort 3063 Exit the formula editor without installing changes. 3064 3065 @item @kbd{C-c C-r} (@code{org-table-fedit-toggle-ref-type}) 3066 @kindex C-c C-r 3067 @findex org-table-fedit-toggle-ref-type 3068 Toggle all references in the formula editor between standard (like 3069 @samp{B3}) and internal (like @samp{@@3$2}). 3070 3071 @item @kbd{@key{TAB}} (@code{org-table-fedit-lisp-indent}) 3072 @kindex TAB 3073 @findex org-table-fedit-lisp-indent 3074 Pretty-print or indent Lisp formula at point. When in a line 3075 containing a Lisp formula, format the formula according to Emacs 3076 Lisp rules. Another @kbd{@key{TAB}} collapses the formula back 3077 again. In the open formula, @kbd{@key{TAB}} re-indents just like 3078 in Emacs Lisp mode. 3079 3080 @item @kbd{M-@key{TAB}} (@code{lisp-complete-symbol}) 3081 @kindex M-TAB 3082 @findex lisp-complete-symbol 3083 Complete Lisp symbols, just like in Emacs Lisp mode. 3084 3085 @item @kbd{S-@key{UP}}, @kbd{S-@key{DOWN}}, @kbd{S-@key{LEFT}}, @kbd{S-@key{RIGHT}} 3086 @kindex S-UP 3087 @kindex S-DOWN 3088 @kindex S-LEFT 3089 @kindex S-RIGHT 3090 @findex org-table-fedit-ref-up 3091 @findex org-table-fedit-ref-down 3092 @findex org-table-fedit-ref-left 3093 @findex org-table-fedit-ref-right 3094 Shift the reference at point. For example, if the reference is 3095 @samp{B3} and you press @kbd{S-@key{RIGHT}}, it becomes @samp{C3}. This also 3096 works for relative references and for hline references. 3097 3098 @item @kbd{M-S-@key{UP}} (@code{org-table-fedit-line-up}) 3099 @kindex M-S-UP 3100 @findex org-table-fedit-line-up 3101 Move the test line for column formulas up in the Org buffer. 3102 3103 @item @kbd{M-S-@key{DOWN}} (@code{org-table-fedit-line-down}) 3104 @kindex M-S-DOWN 3105 @findex org-table-fedit-line-down 3106 Move the test line for column formulas down in the Org buffer. 3107 3108 @item @kbd{M-@key{UP}} (@code{org-table-fedit-scroll-up}) 3109 @kindex M-UP 3110 @findex org-table-fedit-scroll-up 3111 Scroll up the window displaying the table. 3112 3113 @item @kbd{M-@key{DOWN}} (@code{org-table-fedit-scroll-down}) 3114 @kindex M-DOWN 3115 @findex org-table-fedit-scroll-down 3116 Scroll down the window displaying the table. 3117 3118 @item @kbd{C-c @}} 3119 @kindex C-c @} 3120 @findex org-table-toggle-coordinate-overlays 3121 Turn the coordinate grid in the table on and off. 3122 @end table 3123 @end table 3124 3125 Making a table field blank does not remove the formula associated with 3126 the field, because that is stored in a different line---the @samp{TBLFM} 3127 keyword line. During the next recalculation, the field will be filled 3128 again. To remove a formula from a field, you have to give an empty 3129 reply when prompted for the formula, or to edit the @samp{TBLFM} keyword. 3130 3131 @kindex C-c C-c 3132 You may edit the @samp{TBLFM} keyword directly and re-apply the changed 3133 equations with @kbd{C-c C-c} in that line or with the normal 3134 recalculation commands in the table. 3135 3136 @anchor{Using multiple @samp{TBLFM} lines} 3137 @subsubheading Using multiple @samp{TBLFM} lines 3138 3139 @cindex multiple formula lines 3140 @cindex @samp{TBLFM} keywords, multiple 3141 @cindex @samp{TBLFM}, switching 3142 3143 @kindex C-c C-c 3144 You may apply the formula temporarily. This is useful when you want 3145 to switch the formula applied to the table. Place multiple @samp{TBLFM} 3146 keywords right after the table, and then press @kbd{C-c C-c} on 3147 the formula to apply. Here is an example: 3148 3149 @example 3150 | x | y | 3151 |---+---| 3152 | 1 | | 3153 | 2 | | 3154 #+TBLFM: $2=$1*1 3155 #+TBLFM: $2=$1*2 3156 @end example 3157 3158 @noindent 3159 Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields: 3160 3161 @example 3162 | x | y | 3163 |---+---| 3164 | 1 | 2 | 3165 | 2 | 4 | 3166 #+TBLFM: $2=$1*1 3167 #+TBLFM: $2=$1*2 3168 @end example 3169 3170 @noindent 3171 If you recalculate this table, with @kbd{C-u C-c *}, for example, 3172 you get the following result from applying only the first @samp{TBLFM} 3173 keyword. 3174 3175 @example 3176 | x | y | 3177 |---+---| 3178 | 1 | 1 | 3179 | 2 | 2 | 3180 #+TBLFM: $2=$1*1 3181 #+TBLFM: $2=$1*2 3182 @end example 3183 3184 @anchor{Debugging formulas} 3185 @subsubheading Debugging formulas 3186 3187 @cindex formula debugging 3188 @cindex debugging, of table formulas 3189 3190 When the evaluation of a formula leads to an error, the field content 3191 becomes the string @samp{#ERROR}. If you want to see what is going on 3192 during variable substitution and calculation in order to find a bug, 3193 turn on formula debugging in the Tbl menu and repeat the calculation, 3194 for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a field. 3195 Detailed information are displayed. 3196 3197 @node Updating the table 3198 @subsection Updating the table 3199 3200 @cindex recomputing table fields 3201 @cindex updating, table 3202 3203 Recalculation of a table is normally not automatic, but needs to be 3204 triggered by a command. To make recalculation at least 3205 semi-automatic, see @ref{Advanced features}. 3206 3207 In order to recalculate a line of a table or the entire table, use the 3208 following commands: 3209 3210 @table @asis 3211 @item @kbd{C-c *} (@code{org-table-recalculate}) 3212 @kindex C-c * 3213 @findex org-table-recalculate 3214 Recalculate the current row by first applying the stored column 3215 formulas from left to right, and all field/range formulas in the 3216 current row. 3217 3218 @item @kbd{C-u C-c *} or @kbd{C-u C-c C-c} 3219 @kindex C-u C-c * 3220 @kindex C-u C-c C-c 3221 Recompute the entire table, line by line. Any lines before the 3222 first hline are left alone, assuming that these are part of the 3223 table header. 3224 3225 @item @kbd{C-u C-u C-c *} or @kbd{C-u C-u C-c C-c} (@code{org-table-iterate}) 3226 @kindex C-u C-u C-c * 3227 @kindex C-u C-u C-c C-c 3228 @findex org-table-iterate 3229 Iterate the table by recomputing it until no further changes occur. 3230 This may be necessary if some computed fields use the value of other 3231 fields that are computed @emph{later} in the calculation sequence. 3232 3233 @item @kbd{M-x org-table-recalculate-buffer-tables} 3234 @findex org-table-recalculate-buffer-tables 3235 Recompute all tables in the current buffer. 3236 3237 @item @kbd{M-x org-table-iterate-buffer-tables} 3238 @findex org-table-iterate-buffer-tables 3239 Iterate all tables in the current buffer, in order to converge 3240 table-to-table dependencies. 3241 @end table 3242 3243 @node Advanced features 3244 @subsection Advanced features 3245 3246 If you want the recalculation of fields to happen automatically, or if 3247 you want to be able to assign @emph{names}@footnote{ Such names must start with 3248 an alphabetic character and use only alphanumeric/underscore 3249 characters.} to fields and columns, you need to reserve the first 3250 column of the table for special marking characters. 3251 3252 @table @asis 3253 @item @kbd{C-#} (@code{org-table-rotate-recalc-marks}) 3254 @kindex C-# 3255 @findex org-table-rotate-recalc-marks 3256 Rotate the calculation mark in first column through the states @samp{#}, 3257 @samp{*}, @samp{!}, @samp{$}. When there is an active region, change all marks in 3258 the region. 3259 @end table 3260 3261 Here is an example of a table that collects exam results of students 3262 and makes use of these features: 3263 3264 @example 3265 |---+---------+--------+--------+--------+-------+------| 3266 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | 3267 |---+---------+--------+--------+--------+-------+------| 3268 | ! | | P1 | P2 | P3 | Tot | | 3269 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 | 3270 | ^ | | m1 | m2 | m3 | mt | | 3271 |---+---------+--------+--------+--------+-------+------| 3272 | # | Peter | 10 | 8 | 23 | 41 | 8.2 | 3273 | # | Sam | 2 | 4 | 3 | 9 | 1.8 | 3274 |---+---------+--------+--------+--------+-------+------| 3275 | | Average | | | | 25.0 | | 3276 | ^ | | | | | at | | 3277 | $ | max=50 | | | | | | 3278 |---+---------+--------+--------+--------+-------+------| 3279 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f 3280 @end example 3281 3282 @quotation Important 3283 Please note that for these special tables, recalculating the table 3284 with @kbd{C-u C-c *} only affects rows that are marked @samp{#} or 3285 @samp{*}, and fields that have a formula assigned to the field itself. The 3286 column formulas are not applied in rows with empty first field. 3287 3288 @end quotation 3289 3290 @cindex marking characters, tables 3291 The marking characters have the following meaning: 3292 3293 @table @asis 3294 @item @samp{!} 3295 The fields in this line define names for the columns, so that you 3296 may refer to a column as @samp{$Tot} instead of @samp{$6}. 3297 3298 @item @samp{^} 3299 This row defines names for the fields @emph{above} the row. With such 3300 a definition, any formula in the table may use @samp{$m1} to refer to the 3301 value @samp{10}. Also, if you assign a formula to a names field, it is 3302 stored as @samp{$name = ...}. 3303 3304 @item @samp{_} 3305 Similar to @samp{^}, but defines names for the fields in the row @emph{below}. 3306 3307 @item @samp{$} 3308 Fields in this row can define @emph{parameters} for formulas. For 3309 example, if a field in a @samp{$} row contains @samp{max=50}, then formulas in 3310 this table can refer to the value 50 using @samp{$max}. Parameters work 3311 exactly like constants, only that they can be defined on a per-table 3312 basis. 3313 3314 @item @samp{#} 3315 Fields in this row are automatically recalculated when pressing 3316 @kbd{@key{TAB}} or @kbd{@key{RET}} or @kbd{S-@key{TAB}} in this row. 3317 Also, this row is selected for a global recalculation with 3318 @kbd{C-u C-c *}. Unmarked lines are left alone by this 3319 command. 3320 3321 @item @samp{*} 3322 Selects this line for global recalculation with @kbd{C-u C-c *}, but not for automatic recalculation. Use this when automatic 3323 recalculation slows down editing too much. 3324 3325 @item @samp{/} 3326 Do not export this line. Useful for lines that contain the 3327 narrowing @samp{<N>} markers or column group markers. 3328 @end table 3329 3330 Finally, just to whet your appetite for what can be done with the 3331 fantastic Calc package, here is a table that computes the Taylor 3332 series of degree n at location x for a couple of functions. 3333 3334 @example 3335 |---+-------------+---+-----+--------------------------------------| 3336 | | Func | n | x | Result | 3337 |---+-------------+---+-----+--------------------------------------| 3338 | # | exp(x) | 1 | x | 1 + x | 3339 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 | 3340 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 | 3341 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 | 3342 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 | 3343 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 | 3344 |---+-------------+---+-----+--------------------------------------| 3345 #+TBLFM: $5=taylor($2,$4,$3);n3 3346 @end example 3347 3348 @node Org Plot 3349 @section Org Plot 3350 3351 @cindex graph, in tables 3352 @cindex plot tables using Gnuplot 3353 3354 Org Plot can produce graphs of information stored in Org tables, 3355 either graphically or in ASCII art. 3356 3357 @anchor{Graphical plots using Gnuplot} 3358 @subheading Graphical plots using Gnuplot 3359 3360 @cindex @samp{PLOT}, keyword 3361 Org Plot can produce 2D and 3D graphs of information stored in Org 3362 tables using @uref{https://www.gnuplot.info/, Gnuplot} and @uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html, Gnuplot mode}. To see this in action, ensure 3363 that you have both Gnuplot and Gnuplot mode installed on your system, 3364 then call @kbd{C-c " g} or @kbd{M-x org-plot/gnuplot} on the 3365 following table. 3366 3367 @example 3368 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" 3369 | Sede | Max cites | H-index | 3370 |-----------+-----------+---------| 3371 | Chile | 257.72 | 21.39 | 3372 | Leeds | 165.77 | 19.68 | 3373 | Sao Paolo | 71.00 | 11.50 | 3374 | Stockholm | 134.19 | 14.33 | 3375 | Morelia | 257.56 | 17.67 | 3376 @end example 3377 3378 Org Plot supports a range of plot types, and provides the ability to add more. 3379 For example, a radar plot can be generated like so: 3380 @example 3381 #+PLOT: title:"An evaluation of plaintext document formats" transpose:yes type:radar min:0 max:4 3382 | Format | Fine-grained-control | Initial Effort | Syntax simplicity | Editor Support | Integrations | Ease-of-referencing | Versatility | 3383 |-------------------+----------------------+----------------+-------------------+----------------+--------------+---------------------+-------------| 3384 | Word | 2 | 4 | 4 | 2 | 3 | 2 | 2 | 3385 | LaTeX | 4 | 1 | 1 | 3 | 2 | 4 | 3 | 3386 | Org Mode | 4 | 2 | 3.5 | 1 | 4 | 4 | 4 | 3387 | Markdown | 1 | 3 | 3 | 4 | 3 | 3 | 1 | 3388 | Markdown + Pandoc | 2.5 | 2.5 | 2.5 | 3 | 3 | 3 | 2 | 3389 @end example 3390 3391 Notice that Org Plot is smart enough to apply the table's headers as 3392 labels. Further control over the labels, type, content, and 3393 appearance of plots can be exercised through the @samp{PLOT} keyword 3394 preceding a table. See below for a complete list of Org Plot options. 3395 For more information and examples see the @uref{https://orgmode.org/worg/org-tutorials/org-plot.html, Org Plot tutorial}. 3396 3397 @anchor{Plot options} 3398 @subsubheading Plot options 3399 3400 @table @asis 3401 @item @samp{set} 3402 Specify any Gnuplot option to be set when graphing. 3403 3404 @item @samp{title} 3405 Specify the title of the plot. 3406 3407 @item @samp{ind} 3408 Specify which column of the table to use as the @samp{x} axis. 3409 3410 @item @samp{deps} 3411 Specify the columns to graph as a Lisp style list, surrounded by 3412 parentheses and separated by spaces for example @samp{dep:(3 4)} to graph 3413 the third and fourth columns. Defaults to graphing all other 3414 columns aside from the @samp{ind} column. 3415 3416 @item transpose 3417 When @samp{y}, @samp{yes}, or @samp{t} attempt to transpose the table data before 3418 plotting. Also recognizes the shorthand option @samp{trans}. 3419 3420 @item @samp{type} 3421 Specify the type of the plot, by default one of @samp{2d}, @samp{3d}, @samp{radar}, or @samp{grid}. 3422 Available types can be customized with @code{org-plot/preset-plot-types}. 3423 3424 @item @samp{with} 3425 Specify a @samp{with} option to be inserted for every column being 3426 plotted, e.g., @samp{lines}, @samp{points}, @samp{boxes}, @samp{impulses}. Defaults to 3427 @samp{lines}. 3428 3429 @item @samp{file} 3430 If you want to plot to a file, specify 3431 @samp{"path/to/desired/output-file"}. 3432 3433 @item @samp{labels} 3434 List of labels to be used for the @samp{deps}. Defaults to the column 3435 headers if they exist. 3436 3437 @item @samp{line} 3438 Specify an entire line to be inserted in the Gnuplot script. 3439 3440 @item @samp{map} 3441 When plotting @samp{3d} or @samp{grid} types, set this to @samp{t} to graph a flat 3442 mapping rather than a @samp{3d} slope. 3443 3444 @item min 3445 Provides a minimum axis value that may be used by a plot type. 3446 Implicitly assumes the @samp{y} axis is being referred to. Can 3447 explicitly provide a value for a either the @samp{x} or @samp{y} axis with 3448 @samp{xmin} and @samp{ymin}. 3449 3450 @item max 3451 Provides a maximum axis value that may be used by a plot type. 3452 Implicitly assumes the @samp{y} axis is being referred to. Can 3453 explicitly provide a value for a either the @samp{x} or @samp{y} axis with 3454 @samp{xmax} and @samp{ymax}. 3455 3456 @item ticks 3457 Provides a desired number of axis ticks to display, that may be used 3458 by a plot type. If none is given a plot type that requires ticks 3459 will use @code{org--plot/sensible-tick-num} to try to determine a good 3460 value. 3461 3462 @item @samp{timefmt} 3463 Specify format of Org mode timestamps as they will be parsed by 3464 Gnuplot. Defaults to @samp{%Y-%m-%d-%H:%M:%S}. 3465 3466 @item @samp{script} 3467 If you want total control, you can specify a script file---place the 3468 file name between double-quotes---which will be used to plot. 3469 Before plotting, every instance of @samp{$datafile} in the specified 3470 script will be replaced with the path to the generated data file. 3471 Note: even if you set this option, you may still want to specify the 3472 plot type, as that can impact the content of the data file. 3473 @end table 3474 3475 @anchor{ASCII bar plots} 3476 @subheading ASCII bar plots 3477 3478 While point is on a column, typing @kbd{C-c `` a} or @kbd{M-x orgtbl-ascii-plot} create a new column containing an ASCII-art bars 3479 plot. The plot is implemented through a regular column formula. When 3480 the source column changes, the bar plot may be updated by refreshing 3481 the table, for example typing @kbd{C-u C-c *}. 3482 3483 @example 3484 | Sede | Max cites | | 3485 |---------------+-----------+--------------| 3486 | Chile | 257.72 | WWWWWWWWWWWW | 3487 | Leeds | 165.77 | WWWWWWWh | 3488 | Sao Paolo | 71.00 | WWW; | 3489 | Stockholm | 134.19 | WWWWWW: | 3490 | Morelia | 257.56 | WWWWWWWWWWWH | 3491 | Rochefourchat | 0.00 | | 3492 #+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12) 3493 @end example 3494 3495 The formula is an Elisp call. 3496 3497 @defun orgtbl-ascii-draw value min max &optional width 3498 Draw an ASCII bar in a table. 3499 3500 @var{VALUE} is the value to plot. 3501 3502 @var{MIN} is the value displayed as an empty bar. @var{MAX} 3503 is the value filling all the @var{WIDTH}. Sources values outside 3504 this range are displayed as @samp{too small} or @samp{too large}. 3505 3506 @var{WIDTH} is the number of characters of the bar plot. It 3507 defaults to @samp{12}. 3508 @end defun 3509 3510 @node Hyperlinks 3511 @chapter Hyperlinks 3512 3513 @cindex hyperlinks 3514 3515 Like HTML, Org provides support for links inside a file, external 3516 links to other files, Usenet articles, emails, and much more. 3517 3518 @menu 3519 * Link Format:: How links in Org are formatted. 3520 * Internal Links:: Links to other places in the current file. 3521 * Radio Targets:: Make targets trigger links in plain text. 3522 * External Links:: URL-like links to the world. 3523 * Handling Links:: Creating, inserting and following. 3524 * Using Links Outside Org:: Linking from my C source code? 3525 * Link Abbreviations:: Shortcuts for writing complex links. 3526 * Search Options:: Linking to a specific location. 3527 * Custom Searches:: When the default search is not enough. 3528 @end menu 3529 3530 @node Link Format 3531 @section Link Format 3532 3533 @cindex link format 3534 @cindex format, of links 3535 3536 @cindex angle bracket links 3537 @cindex plain links 3538 Org recognizes plain URIs, possibly wrapped within angle 3539 brackets@footnote{Plain URIs are recognized only for a well-defined set of 3540 schemes. See @ref{External Links}. Unlike URI syntax, they cannot contain 3541 parenthesis or white spaces, either. URIs within angle brackets have 3542 no such limitation.}, and activate them as clickable links. 3543 3544 @cindex bracket links 3545 The general link format, however, looks like this: 3546 3547 @example 3548 [[LINK][DESCRIPTION]] 3549 @end example 3550 3551 3552 @noindent 3553 or alternatively 3554 3555 @example 3556 [[LINK]] 3557 @end example 3558 3559 3560 @cindex escape syntax, for links 3561 @cindex backslashes, in links 3562 Some @samp{\}, @samp{[} and @samp{]} characters in the @var{LINK} part need to 3563 be ``escaped'', i.e., preceded by another @samp{\} character. More 3564 specifically, the following characters, and only them, must be 3565 escaped: 3566 3567 @enumerate 3568 @item 3569 all @samp{[} and @samp{]} characters, 3570 @item 3571 every @samp{\} character preceding either @samp{]} or @samp{[}, 3572 @item 3573 every @samp{\} character at the end of the link. 3574 @end enumerate 3575 3576 @findex org-link-escape 3577 Functions inserting links (see @ref{Handling Links}) properly escape 3578 ambiguous characters. You only need to bother about the rules above 3579 when inserting directly, or yanking, a URI within square brackets. 3580 When in doubt, you may use the function @code{org-link-escape}, which turns 3581 a link string into its escaped form. 3582 3583 Once a link in the buffer is complete, with all brackets present, Org 3584 changes the display so that @samp{DESCRIPTION} is displayed instead of 3585 @samp{[[LINK][DESCRIPTION]]} and @samp{LINK} is displayed instead of @samp{[[LINK]]}. 3586 Links are highlighted in the @code{org-link} face, which, by default, is an 3587 underlined face. 3588 3589 You can directly edit the visible part of a link. This can be either 3590 the @var{LINK} part, if there is no description, or the 3591 @var{DESCRIPTION} part otherwise. To also edit the invisible 3592 @var{LINK} part, use @kbd{C-c C-l} with point on the link 3593 (see @ref{Handling Links}). 3594 3595 If you place point at the beginning or just behind the end of the 3596 displayed text and press @kbd{@key{BS}}, you remove 3597 the---invisible---bracket at that location@footnote{ More accurately, the 3598 precise behavior depends on how point arrived there---see 3599 @ref{Invisible Text,Invisible Text,,elisp,}.}. This makes the link 3600 incomplete and the internals are again displayed as plain text. 3601 Inserting the missing bracket hides the link internals again. To show 3602 the internal structure of all links, use the menu: Org @arrow{} 3603 Hyperlinks @arrow{} Literal links. 3604 3605 @node Internal Links 3606 @section Internal Links 3607 3608 @cindex internal links 3609 @cindex links, internal 3610 3611 A link that does not look like a URL---i.e., does not start with 3612 a known scheme or a file name---refers to the current document. You 3613 can follow it with @kbd{C-c C-o} when point is on the link, or 3614 with a mouse click (see @ref{Handling Links}). 3615 3616 @cindex @samp{CUSTOM_ID}, property 3617 Org provides several refinements to internal navigation within 3618 a document. Most notably, a construct like @samp{[[#my-custom-id]]} 3619 specifically targets the entry with the @samp{CUSTOM_ID} property set to 3620 @samp{my-custom-id}. Also, an internal link looking like @samp{[[*Some 3621 section]]} points to a headline with the name @samp{Some section}@footnote{To insert a link targeting a headline, in-buffer completion 3622 can be used. Just type a star followed by a few optional letters into 3623 the buffer and press @kbd{M-@key{TAB}}. All headlines in the current 3624 buffer are offered as completions.}. 3625 3626 @cindex targets, for links 3627 When the link does not belong to any of the cases above, Org looks for 3628 a @emph{dedicated target}: the same string in double angular brackets, like 3629 @samp{<<My Target>>}. 3630 3631 @cindex @samp{NAME}, keyword 3632 If no dedicated target exists, the link tries to match the exact name 3633 of an element within the buffer. Naming is done, unsurprisingly, with 3634 the @samp{NAME} keyword, which has to be put in the line before the element 3635 it refers to, as in the following example 3636 3637 @example 3638 #+NAME: My Target 3639 | a | table | 3640 |----+------------| 3641 | of | four cells | 3642 @end example 3643 3644 @vindex org-link-search-must-match-exact-headline 3645 Ultimately, if none of the above succeeds, Org searches for a headline 3646 that is exactly the link text but may also include a TODO keyword and 3647 tags, or initiates a plain text search, according to the value of 3648 @code{org-link-search-must-match-exact-headline}. 3649 3650 Note that you must make sure custom IDs, dedicated targets, and names 3651 are unique throughout the document. Org provides a linter to assist 3652 you in the process, if needed. See @ref{Org Syntax}. 3653 3654 During export, internal links are used to mark objects and assign them 3655 a number. Marked objects are then referenced by links pointing to 3656 them. In particular, links without a description appear as the number 3657 assigned to the marked object@footnote{ When targeting a @samp{NAME} keyword, 3658 the @samp{CAPTION} keyword is mandatory in order to get proper numbering 3659 (see @ref{Captions}).}. In the following excerpt from an Org buffer 3660 3661 @example 3662 1. one item 3663 2. <<target>>another item 3664 Here we refer to item [[target]]. 3665 @end example 3666 3667 @noindent 3668 The last sentence will appear as @samp{Here we refer to item 2} when 3669 exported. 3670 3671 In non-Org files, the search looks for the words in the link text. In 3672 the above example the search would be for @samp{target}. 3673 3674 Following a link pushes a mark onto Org's own mark ring. You can 3675 return to the previous position with @kbd{C-c &}. Using this 3676 command several times in direct succession goes back to positions 3677 recorded earlier. 3678 3679 @node Radio Targets 3680 @section Radio Targets 3681 3682 @cindex radio targets 3683 @cindex targets, radio 3684 @cindex links, radio targets 3685 3686 Org can automatically turn any occurrences of certain target names in 3687 normal text into a link. So without explicitly creating a link, the 3688 text connects to the target radioing its position. Radio targets are 3689 enclosed by triple angular brackets. For example, a target @samp{<<<My 3690 Target>>>} causes each occurrence of @samp{my target} in normal text to 3691 become activated as a link. The Org file is scanned automatically for 3692 radio targets only when the file is first loaded into Emacs. To 3693 update the target list during editing, press @kbd{C-c C-c} with 3694 point on or at a target. 3695 3696 @node External Links 3697 @section External Links 3698 3699 @cindex links, external 3700 @cindex external links 3701 @cindex attachment links 3702 @cindex BBDB links 3703 @cindex Elisp links 3704 @cindex file links 3705 @cindex Gnus links 3706 @cindex Help links 3707 @cindex IRC links 3708 @cindex Info links 3709 @cindex MH-E links 3710 @cindex Rmail links 3711 @cindex shell links 3712 @cindex URL links 3713 @cindex Usenet links 3714 3715 Org supports links to files, websites, Usenet and email messages, BBDB 3716 database entries and links to both IRC conversations and their logs. 3717 External links are URL-like locators. They start with a short 3718 identifying string followed by a colon. There can be no space after 3719 the colon. 3720 3721 Here is the full set of built-in link types: 3722 3723 @table @asis 3724 @item @samp{file} 3725 File links. File name may be remote, absolute, or relative. 3726 3727 Additionally, you can specify a line number, or a text search. 3728 In Org files, you may link to a headline name, a custom ID, or a 3729 code reference instead. 3730 3731 As a special case, ``file'' prefix may be omitted if the file name 3732 is complete, e.g., it starts with @samp{./}, or @samp{/}. 3733 3734 @item @samp{attachment} 3735 Same as file links but for files and folders attached to the current 3736 node (see @ref{Attachments}). Attachment links are intended to behave 3737 exactly as file links but for files relative to the attachment 3738 directory. 3739 3740 @item @samp{bbdb} 3741 Link to a BBDB record, with possible regexp completion. 3742 3743 @item @samp{docview} 3744 Link to a document opened with DocView mode. You may specify a page 3745 number. 3746 3747 @item @samp{doi} 3748 Link to an electronic resource, through its handle. 3749 3750 @item @samp{elisp} 3751 Execute an Elisp command upon activation. 3752 3753 @item @samp{gnus}, @samp{rmail}, @samp{mhe} 3754 Link to messages or folders from a given Emacs' MUA@. 3755 3756 @item @samp{help} 3757 Display documentation of a symbol in @samp{*Help*} buffer. 3758 3759 @item @samp{http}, @samp{https} 3760 Web links. 3761 3762 @item @samp{id} 3763 Link to a specific headline by its ID property, in an Org file. 3764 3765 @item @samp{info} 3766 Link to an Info manual, or to a specific node. 3767 3768 @item @samp{irc} 3769 Link to an IRC channel. 3770 3771 @item @samp{mailto} 3772 Link to message composition. 3773 3774 @item @samp{news} 3775 Usenet links. 3776 3777 @item @samp{shell} 3778 Execute a shell command upon activation. 3779 @end table 3780 3781 The following table illustrates the link types above, along with their 3782 options: 3783 3784 @multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 3785 @headitem Link Type 3786 @tab Example 3787 @item http 3788 @tab @samp{http://staff.science.uva.nl/c.dominik/} 3789 @item https 3790 @tab @samp{https://orgmode.org/} 3791 @item doi 3792 @tab @samp{doi:10.1000/182} 3793 @item file 3794 @tab @samp{file:/home/dominik/images/jupiter.jpg} 3795 @item 3796 @tab @samp{/home/dominik/images/jupiter.jpg} (same as above) 3797 @item 3798 @tab @samp{file:papers/last.pdf} 3799 @item 3800 @tab @samp{./papers/last.pdf} (same as above) 3801 @item 3802 @tab @samp{file:/ssh:me@@some.where:papers/last.pdf} (remote) 3803 @item 3804 @tab @samp{/ssh:me@@some.where:papers/last.pdf} (same as above) 3805 @item 3806 @tab @samp{file:sometextfile::NNN} (jump to line number) 3807 @item 3808 @tab @samp{file:projects.org} 3809 @item 3810 @tab @samp{file:projects.org::some words} (text search)@footnote{The actual behavior of the search depends on the value of the 3811 variable @code{org-link-search-must-match-exact-headline}. If its value is 3812 @code{nil}, then a fuzzy text search is done. If it is @code{t}, then only the 3813 exact headline is matched, ignoring spaces and statistic cookies. If 3814 the value is @code{query-to-create}, then an exact headline is searched; if 3815 it is not found, then the user is queried to create it.} 3816 @item 3817 @tab @samp{file:projects.org::*task title} (headline search) 3818 @item 3819 @tab @samp{file:projects.org::#custom-id} (headline search) 3820 @item attachment 3821 @tab @samp{attachment:projects.org} 3822 @item 3823 @tab @samp{attachment:projects.org::some words} (text search) 3824 @item docview 3825 @tab @samp{docview:papers/last.pdf::NNN} 3826 @item id 3827 @tab @samp{id:B7423F4D-2E8A-471B-8810-C40F074717E9} 3828 @item news 3829 @tab @samp{news:comp.emacs} 3830 @item mailto 3831 @tab @samp{mailto:adent@@galaxy.net} 3832 @item mhe 3833 @tab @samp{mhe:folder} (folder link) 3834 @item 3835 @tab @samp{mhe:folder#id} (message link) 3836 @item rmail 3837 @tab @samp{rmail:folder} (folder link) 3838 @item 3839 @tab @samp{rmail:folder#id} (message link) 3840 @item gnus 3841 @tab @samp{gnus:group} (group link) 3842 @item 3843 @tab @samp{gnus:group#id} (article link) 3844 @item bbdb 3845 @tab @samp{bbdb:R.*Stallman} (record with regexp) 3846 @item irc 3847 @tab @samp{irc:/irc.com/#emacs/bob} 3848 @item help 3849 @tab @samp{help:org-store-link} 3850 @item info 3851 @tab @samp{info:org#External links} 3852 @item shell 3853 @tab @samp{shell:ls *.org} 3854 @item elisp 3855 @tab @samp{elisp:(find-file "Elisp.org")} (Elisp form to evaluate) 3856 @item 3857 @tab @samp{elisp:org-agenda} (interactive Elisp command) 3858 @end multitable 3859 3860 @cindex VM links 3861 @cindex Wanderlust links 3862 On top of these built-in link types, additional ones are available 3863 through the @samp{org-contrib} repository (see @ref{Installation}). For 3864 example, these links to VM or Wanderlust messages are available when 3865 you load the corresponding libraries from the @samp{org-contrib} 3866 repository: 3867 3868 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaa} 3869 @item @samp{vm:folder} 3870 @tab VM folder link 3871 @item @samp{vm:folder#id} 3872 @tab VM message link 3873 @item @samp{vm://myself@@some.where.org/folder#id} 3874 @tab VM on remote machine 3875 @item @samp{vm-imap:account:folder} 3876 @tab VM IMAP folder link 3877 @item @samp{vm-imap:account:folder#id} 3878 @tab VM IMAP message link 3879 @item @samp{wl:folder} 3880 @tab Wanderlust folder link 3881 @item @samp{wl:folder#id} 3882 @tab Wanderlust message link 3883 @end multitable 3884 3885 For information on customizing Org to add new link types, see @ref{Adding Hyperlink Types}. 3886 3887 A link should be enclosed in double brackets and may contain 3888 descriptive text to be displayed instead of the URL (see @ref{Link Format}), for example: 3889 3890 @example 3891 [[https://www.gnu.org/software/emacs/][GNU Emacs]] 3892 @end example 3893 3894 3895 If the description is a file name or URL that points to an image, HTML 3896 export (see @ref{HTML Export}) inlines the image as a clickable button. If 3897 there is no description at all and the link points to an image, that 3898 image is inlined into the exported HTML file. 3899 3900 @cindex square brackets, around links 3901 @cindex angular brackets, around links 3902 @cindex plain text external links 3903 Org also recognizes external links amid normal text and activates them 3904 as links. If spaces must be part of the link (for example in 3905 @samp{bbdb:R.*Stallman}), or if you need to remove ambiguities about the 3906 end of the link, enclose the link in square or angular brackets. 3907 3908 @node Handling Links 3909 @section Handling Links 3910 3911 @cindex links, handling 3912 3913 Org provides methods to create a link in the correct syntax, to insert 3914 it into an Org file, and to follow the link. 3915 3916 @findex org-store-link 3917 @cindex storing links 3918 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 3919 to a widely available key (see @ref{Activation}). It stores a link to the 3920 current location. The link is stored for later insertion into an Org 3921 buffer---see below. The kind of link that is created depends on the 3922 current buffer: 3923 3924 @table @asis 3925 @item @emph{Org mode buffers} 3926 For Org files, if there is a @samp{<<target>>} at point, the link points 3927 to the target. Otherwise it points to the current headline, which 3928 is also the description. 3929 3930 @vindex org-id-link-to-org-use-id 3931 @cindex @samp{CUSTOM_ID}, property 3932 @cindex @samp{ID}, property 3933 If the headline has a @samp{CUSTOM_ID} property, store a link to this 3934 custom ID@. In addition or alternatively, depending on the value of 3935 @code{org-id-link-to-org-use-id}, create and/or use a globally unique 3936 @samp{ID} property for the link@footnote{ The Org Id library must first be 3937 loaded, either through @code{org-customize}, by enabling @code{id} in 3938 @code{org-modules}, or by adding @samp{(require 'org-id)} in your Emacs init 3939 file.}. So using this command in Org buffers potentially creates 3940 two links: a human-readable link from the custom ID, and one that is 3941 globally unique and works even if the entry is moved from file to 3942 file. The @samp{ID} property can be either a UUID (default) or a 3943 timestamp, depending on @code{org-id-method}. Later, when inserting the 3944 link, you need to decide which one to use. 3945 3946 @item @emph{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus} 3947 @vindex org-link-email-description-format 3948 Pretty much all Emacs mail clients are supported. The link points 3949 to the current article, or, in some Gnus buffers, to the group. The 3950 description is constructed according to the variable 3951 @code{org-link-email-description-format}. By default, it refers to the 3952 addressee and the subject. 3953 3954 @item @emph{Web browsers: W3M and EWW} 3955 Here the link is the current URL, with the page title as the 3956 description. 3957 3958 @item @emph{Contacts: BBDB} 3959 Links created in a BBDB buffer point to the current entry. 3960 3961 @item @emph{Chat: IRC} 3962 @vindex org-irc-links-to-logs 3963 For IRC links, if the variable @code{org-irc-link-to-logs} is non-@code{nil}, 3964 create a @samp{file} style link to the relevant point in the logs for the 3965 current conversation. Otherwise store an @samp{irc} style link to the 3966 user/channel/server under the point. 3967 3968 @item @emph{Other files} 3969 For any other file, the link points to the file, with a search 3970 string (see @ref{Search Options}) pointing to the contents 3971 of the current line. If there is an active region, the selected 3972 words form the basis of the search string. You can write custom Lisp 3973 functions to select the search string and perform the search for 3974 particular file types (see @ref{Custom Searches}). 3975 3976 You can also define dedicated links to other files. See @ref{Adding Hyperlink Types}. 3977 3978 @item @emph{Agenda view} 3979 When point is in an agenda view, the created link points to the 3980 entry referenced by the current line. 3981 @end table 3982 3983 From an Org buffer, the following commands create, navigate or, more 3984 generally, act on links. 3985 3986 @table @asis 3987 @item @kbd{C-c C-l} (@code{org-insert-link}) 3988 @kindex C-c C-l 3989 @findex org-insert-link 3990 @cindex link completion 3991 @cindex completion, of links 3992 @cindex inserting links 3993 @vindex org-link-keep-stored-after-insertion 3994 Insert a link@footnote{Note that you do not have to use this command to insert 3995 a link. Links in Org are plain text, and you can type or paste them 3996 straight into the buffer. By using this command, the links are 3997 automatically enclosed in double brackets, and you will be asked for 3998 the optional descriptive text.}. This prompts for a link to be inserted into 3999 the buffer. You can just type a link, using text for an internal 4000 link, or one of the link type prefixes mentioned in the examples 4001 above. The link is inserted into the buffer, along with 4002 a descriptive text@footnote{After insertion of a stored link, the link will be removed 4003 from the list of stored links. To keep it in the list for later use, 4004 use a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or 4005 configure the option @code{org-link-keep-stored-after-insertion}.}. If some text was selected at this time, 4006 it becomes the default description. 4007 4008 @table @asis 4009 @item @emph{Inserting stored links} 4010 All links stored during the current session are part of the 4011 history for this prompt, so you can access them with @kbd{@key{UP}} 4012 and @kbd{@key{DOWN}} (or @kbd{M-p}, @kbd{M-n}). 4013 4014 @item @emph{Completion support} 4015 Completion with @kbd{@key{TAB}} helps you to insert valid link 4016 prefixes like @samp{http} or @samp{ftp}, including the prefixes defined 4017 through link abbreviations (see @ref{Link Abbreviations}). If you 4018 press @kbd{@key{RET}} after inserting only the prefix, Org offers 4019 specific completion support for some link types@footnote{ This works if 4020 a function has been defined in the @code{:complete} property of a link 4021 in @code{org-link-parameters}.}. For example, if you type @kbd{f i l e @key{RET}}---alternative access: @kbd{C-u C-c C-l}, see 4022 below---Org offers file name completion, and after @kbd{b b d b @key{RET}} you can complete contact names. 4023 @end table 4024 4025 @item @kbd{C-u C-c C-l} 4026 @cindex file name completion 4027 @cindex completion, of file names 4028 @kindex C-u C-c C-l 4029 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix 4030 argument, insert a link to a file. You may use file name completion 4031 to select the name of the file. The path to the file is inserted 4032 relative to the directory of the current Org file, if the linked 4033 file is in the current directory or in a sub-directory of it, or if 4034 the path is written relative to the current directory using @samp{../}. 4035 Otherwise an absolute path is used, if possible with @samp{~/} for your 4036 home directory. You can force an absolute path with two 4037 @kbd{C-u} prefixes. 4038 4039 @item @kbd{C-c C-l} (with point on existing link) 4040 @cindex following links 4041 When point is on an existing link, @kbd{C-c C-l} allows you to 4042 edit the link and description parts of the link. 4043 4044 @item @kbd{C-c C-o} (@code{org-open-at-point}) 4045 @kindex C-c C-o 4046 @findex org-open-at-point 4047 @vindex org-file-apps 4048 Open link at point. This launches a web browser for URL (using 4049 @code{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for 4050 the corresponding links, and execute the command in a shell link. 4051 When point is on an internal link, this command runs the 4052 corresponding search. When point is on the tags part of a headline, 4053 it creates the corresponding tags view (see @ref{Matching tags and properties}). If point is on a timestamp, it compiles the agenda for 4054 that date. Furthermore, it visits text and remote files in @samp{file} 4055 links with Emacs and select a suitable application for local 4056 non-text files. Classification of files is based on file extension 4057 only. See option @code{org-file-apps}. If you want to override the 4058 default application and visit the file with Emacs, use 4059 a @kbd{C-u} prefix. If you want to avoid opening in Emacs, use 4060 a @kbd{C-u C-u} prefix. 4061 4062 @vindex org-link-frame-setup 4063 If point is on a headline, but not on a link, offer all links in the 4064 headline and entry text. If you want to setup the frame 4065 configuration for following links, customize @code{org-link-frame-setup}. 4066 4067 @item @kbd{@key{RET}} 4068 @vindex org-return-follows-link 4069 @kindex RET 4070 When @code{org-return-follows-link} is set, @kbd{@key{RET}} also follows 4071 the link at point. 4072 4073 @item @kbd{mouse-2} or @kbd{mouse-1} 4074 @kindex mouse-2 4075 @kindex mouse-1 4076 On links, @kbd{mouse-1} and @kbd{mouse-2} opens the link 4077 just as @kbd{C-c C-o} does. 4078 4079 @item @kbd{mouse-3} 4080 @vindex org-link-use-indirect-buffer-for-internals 4081 @kindex mouse-3 4082 Like @kbd{mouse-2}, but force file links to be opened with 4083 Emacs, and internal links to be displayed in another window@footnote{ See 4084 the variable @code{org-link-use-indirect-buffer-for-internals}.}. 4085 4086 @item @kbd{C-c %} (@code{org-mark-ring-push}) 4087 @kindex C-c % 4088 @findex org-mark-ring-push 4089 @cindex mark ring 4090 Push the current position onto the Org mark ring, to be able to 4091 return easily. Commands following an internal link do this 4092 automatically. 4093 4094 @item @kbd{C-c &} (@code{org-mark-ring-goto}) 4095 @kindex C-c & 4096 @findex org-mark-ring-goto 4097 @cindex links, returning to 4098 Jump back to a recorded position. A position is recorded by the 4099 commands following internal links, and by @kbd{C-c %}. Using 4100 this command several times in direct succession moves through a ring 4101 of previously recorded positions. 4102 4103 @item @kbd{C-c C-x C-n} (@code{org-next-link}) 4104 @itemx @kbd{C-c C-x C-p} (@code{org-previous-link}) 4105 @kindex C-c C-x C-p 4106 @findex org-previous-link 4107 @kindex C-c C-x C-n 4108 @findex org-next-link 4109 @cindex links, finding next/previous 4110 Move forward/backward to the next link in the buffer. At the limit 4111 of the buffer, the search fails once, and then wraps around. The 4112 key bindings for this are really too long; you might want to bind 4113 this also to @kbd{M-n} and @kbd{M-p}. 4114 4115 @lisp 4116 (with-eval-after-load 'org 4117 (define-key org-mode-map (kbd "M-n") #'org-next-link) 4118 (define-key org-mode-map (kbd "M-p") #'org-previous-link)) 4119 @end lisp 4120 @end table 4121 4122 @node Using Links Outside Org 4123 @section Using Links Outside Org 4124 4125 @findex org-insert-link-global 4126 @findex org-open-at-point-global 4127 You can insert and follow links that have Org syntax not only in Org, 4128 but in any Emacs buffer. For this, Org provides two functions: 4129 @code{org-insert-link-global} and @code{org-open-at-point-global}. 4130 4131 You might want to bind them to globally available keys. See 4132 @ref{Activation} for some advice. 4133 4134 @node Link Abbreviations 4135 @section Link Abbreviations 4136 4137 @cindex link abbreviations 4138 @cindex abbreviation, links 4139 4140 Long URL can be cumbersome to type, and often many similar links are 4141 needed in a document. For this you can use link abbreviations. An 4142 abbreviated link looks like this 4143 4144 @example 4145 [[linkword:tag][description]] 4146 @end example 4147 4148 4149 @noindent 4150 @vindex org-link-abbrev-alist 4151 where the tag is optional. The @emph{linkword} must be a word, starting 4152 with a letter, followed by letters, numbers, @samp{-}, and @samp{_}. 4153 Abbreviations are resolved according to the information in the 4154 variable @code{org-link-abbrev-alist} that relates the linkwords to 4155 replacement text. Here is an example: 4156 4157 @lisp 4158 (setq org-link-abbrev-alist 4159 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") 4160 ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") 4161 ("duckduckgo" . "https://duckduckgo.com/?q=%s") 4162 ("omap" . "https://nominatim.openstreetmap.org/search?q=%s&polygon=1") 4163 ("ads" . "https://ui.adsabs.harvard.edu/search/q=%20author%3A\"%s\""))) 4164 @end lisp 4165 4166 If the replacement text contains the string @samp{%s}, it is replaced with 4167 the tag. Using @samp{%h} instead of @samp{%s} percent-encodes the tag (see the 4168 example above, where we need to encode the URL parameter). Using 4169 @samp{%(my-function)} passes the tag to a custom Lisp function, and replace 4170 it by the resulting string. 4171 4172 If the replacement text do not contain any specifier, it is simply 4173 appended to the string in order to create the link. 4174 4175 Instead of a string, you may also specify a Lisp function to create 4176 the link. Such a function will be called with the tag as the only 4177 argument. 4178 4179 With the above setting, you could link to a specific bug with 4180 @samp{[[bugzilla:129]]}, search the web for @samp{OrgMode} with @samp{[[duckduckgo:OrgMode]]}, 4181 show the map location of the Free Software Foundation @samp{[[gmap:51 4182 Franklin Street, Boston]]} or of Carsten office @samp{[[omap:Science Park 904, 4183 Amsterdam, The Netherlands]]} and find out what the Org author is doing 4184 besides Emacs hacking with @samp{[[ads:Dominik,C]]}. 4185 4186 If you need special abbreviations just for a single Org buffer, you 4187 can define them in the file with 4188 4189 @cindex @samp{LINK}, keyword 4190 @example 4191 #+LINK: bugzilla https://10.1.2.9/bugzilla/show_bug.cgi?id= 4192 #+LINK: duckduckgo https://duckduckgo.com/?q=%s 4193 #+LINK: "Nu Html Checker" https://validator.w3.org/nu/?doc=%h 4194 @end example 4195 4196 The abbreviations containing spaces must be quoted. 4197 4198 In-buffer completion (see @ref{Completion}) can be used after @samp{[} to 4199 complete link abbreviations. You may also define a Lisp function that 4200 implements special (e.g., completion) support for inserting such a 4201 link with @kbd{C-c C-l}. Such a function should not accept any 4202 arguments, and should return the full link with a prefix. You can set 4203 the link completion function like this: 4204 4205 @lisp 4206 (org-link-set-parameter "type" :complete #'some-completion-function) 4207 @end lisp 4208 4209 @node Search Options 4210 @section Search Options in File Links 4211 4212 @cindex search option in file links 4213 @cindex file links, searching 4214 @cindex attachment links, searching 4215 4216 File links can contain additional information to make Emacs jump to a 4217 particular location in the file when following a link. This can be a 4218 line number or a search option after a double colon@footnote{ For backward 4219 compatibility, line numbers can also follow a single colon.}. For 4220 example, when the command @code{org-store-link} creates a link (see 4221 @ref{Handling Links}) to a file, it encodes the words in the current 4222 line as a search string that can be used to find this line back later 4223 when following the link with @kbd{C-c C-o}. 4224 4225 Note that all search options apply for Attachment links in the same 4226 way that they apply for File links. 4227 4228 Here is the syntax of the different ways to attach a search to a file 4229 link, together with explanations for each: 4230 4231 @example 4232 [[file:~/code/main.c::255]] 4233 [[file:~/xx.org::My Target]] 4234 [[file:~/xx.org::*My Target]] 4235 [[file:~/xx.org::#my-custom-id]] 4236 [[file:~/xx.org::/regexp/]] 4237 [[attachment:main.c::255]] 4238 @end example 4239 4240 @table @asis 4241 @item @samp{255} 4242 Jump to line 255. 4243 4244 @item @samp{My Target} 4245 Search for a link target @samp{<<My Target>>}, or do a text search for 4246 @samp{my target}, similar to the search in internal links, see @ref{Internal Links}. In HTML export (see @ref{HTML Export}), such a file link becomes 4247 a HTML reference to the corresponding named anchor in the linked 4248 file. 4249 4250 @item @samp{*My Target} 4251 In an Org file, restrict search to headlines. 4252 4253 @item @samp{#my-custom-id} 4254 Link to a heading with a @samp{CUSTOM_ID} property 4255 4256 @item @samp{/REGEXP/} 4257 Do a regular expression search for @var{REGEXP} (see @ref{Regular Expressions}). This uses the Emacs command @code{occur} to list all 4258 matches in a separate window. If the target file is in Org mode, 4259 @code{org-occur} is used to create a sparse tree with the matches. 4260 @end table 4261 4262 As a degenerate case, a file link with an empty file name can be used 4263 to search the current file. For example, @samp{[[file:::find me]]} does 4264 a search for @samp{find me} in the current file, just as @samp{[[find me]]} 4265 would. 4266 4267 @node Custom Searches 4268 @section Custom Searches 4269 4270 @cindex custom search strings 4271 @cindex search strings, custom 4272 4273 The default mechanism for creating search strings and for doing the 4274 actual search related to a file link may not work correctly in all 4275 cases. For example, Bib@TeX{} database files have many entries like 4276 @code{year="1993"} which would not result in good search strings, because 4277 the only unique identification for a Bib@TeX{} entry is the citation key. 4278 4279 @vindex org-create-file-search-functions 4280 @vindex org-execute-file-search-functions 4281 If you come across such a problem, you can write custom functions to 4282 set the right search string for a particular file type, and to do the 4283 search for the string in the file. Using @code{add-hook}, these functions 4284 need to be added to the hook variables 4285 @code{org-create-file-search-functions} and 4286 @code{org-execute-file-search-functions}. See the docstring for these 4287 variables for more information. Org actually uses this mechanism for 4288 Bib@TeX{} database files, and you can use the corresponding code as an 4289 implementation example. See the file @samp{ol-bibtex.el}. 4290 4291 @node TODO Items 4292 @chapter TODO Items 4293 4294 @cindex TODO items 4295 4296 Org mode does not maintain TODO lists as separate documents@footnote{ Of 4297 course, you can make a document that contains only long lists of TODO 4298 items, but this is not required.}. Instead, TODO items are an 4299 integral part of the notes file, because TODO items usually come up 4300 while taking notes! With Org mode, simply mark any entry in a tree as 4301 being a TODO item. In this way, information is not duplicated, and 4302 the entire context from which the TODO item emerged is always present. 4303 4304 Of course, this technique for managing TODO items scatters them 4305 throughout your notes file. Org mode compensates for this by 4306 providing methods to give you an overview of all the things that you 4307 have to do. 4308 4309 @menu 4310 * TODO Basics:: Marking and displaying TODO entries. 4311 * TODO Extensions:: Workflow and assignments. 4312 * Progress Logging:: Dates and notes for progress. 4313 * Priorities:: Some things are more important than others. 4314 * Breaking Down Tasks:: Splitting a task into manageable pieces. 4315 * Checkboxes:: Tick-off lists. 4316 @end menu 4317 4318 @node TODO Basics 4319 @section Basic TODO Functionality 4320 4321 Any headline becomes a TODO item when it starts with the word @samp{TODO}, 4322 for example: 4323 4324 @example 4325 *** TODO Write letter to Sam Fortune 4326 @end example 4327 4328 4329 The most important commands to work with TODO entries are: 4330 4331 @table @asis 4332 @item @kbd{C-c C-t} (@code{org-todo}) 4333 @kindex C-c C-t 4334 @cindex cycling, of TODO states 4335 Rotate the TODO state of the current item among 4336 4337 @example 4338 ,-> (unmarked) -> TODO -> DONE --. 4339 '--------------------------------' 4340 @end example 4341 4342 If TODO keywords have fast access keys (see @ref{Fast access to TODO states}), prompt for a TODO keyword through the fast selection 4343 interface; this is the default behavior when 4344 @code{org-use-fast-todo-selection} is non-@code{nil}. 4345 4346 The same state changing can also be done ``remotely'' from the agenda 4347 buffer with the @kbd{t} command key (see @ref{Agenda Commands}). 4348 4349 @item @kbd{S-@key{RIGHT}} @kbd{S-@key{LEFT}} 4350 @kindex S-RIGHT 4351 @kindex S-LEFT 4352 @vindex org-treat-S-cursor-todo-selection-as-state-change 4353 Select the following/preceding TODO state, similar to cycling. 4354 Useful mostly if more than two TODO states are possible (see 4355 @ref{TODO Extensions}). See also @ref{Conflicts}, for a discussion of the interaction with 4356 shift-selection. See also the variable 4357 @code{org-treat-S-cursor-todo-selection-as-state-change}. 4358 4359 @item @kbd{C-c / t} (@code{org-show-todo-tree}) 4360 @kindex C-c / t 4361 @cindex sparse tree, for TODO 4362 @vindex org-todo-keywords 4363 @findex org-show-todo-tree 4364 View TODO items in a @emph{sparse tree} (see @ref{Sparse Trees}). Folds the 4365 entire buffer, but shows all TODO items---with not-DONE state---and 4366 the headings hierarchy above them. With a prefix argument, or by 4367 using @kbd{C-c / T}, search for a specific TODO@. You are 4368 prompted for the keyword, and you can also give a list of keywords 4369 like @samp{KWD1|KWD2|...} to list entries that match any one of these 4370 keywords. With a numeric prefix argument N, show the tree for the 4371 Nth keyword in the variable @code{org-todo-keywords}. With two prefix 4372 arguments, find all TODO states, both un-done and done. 4373 4374 @item @kbd{M-x org-agenda t} (@code{org-todo-list}) 4375 @kindex t @r{(Agenda dispatcher)} 4376 Show the global TODO list. Collects the TODO items (with not-DONE 4377 states) from all agenda files (see @ref{Agenda Views}) into a single 4378 buffer. The new buffer is in Org Agenda mode, which provides 4379 commands to examine and manipulate the TODO entries from the new 4380 buffer (see @ref{Agenda Commands}). See @ref{Global TODO list}, for more information. 4381 4382 @item @kbd{S-M-@key{RET}} (@code{org-insert-todo-heading}) 4383 @kindex S-M-RET 4384 @findex org-insert-todo-heading 4385 Insert a new TODO entry below the current one. 4386 @end table 4387 4388 @vindex org-todo-state-tags-triggers 4389 Changing a TODO state can also trigger tag changes. See the docstring 4390 of the option @code{org-todo-state-tags-triggers} for details. 4391 4392 @node TODO Extensions 4393 @section Extended Use of TODO Keywords 4394 4395 @cindex extended TODO keywords 4396 4397 @vindex org-todo-keywords 4398 By default, marked TODO entries have one of only two states: TODO and 4399 DONE@. Org mode allows you to classify TODO items in more complex ways 4400 with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With special 4401 setup, the TODO keyword system can work differently in different 4402 files. 4403 4404 Note that @emph{tags} are another way to classify headlines in general and 4405 TODO items in particular (see @ref{Tags}). 4406 4407 @menu 4408 * Workflow states:: From TODO to DONE in steps. 4409 * TODO types:: I do this, Fred does the rest. 4410 * Multiple sets in one file:: Mixing it all, still finding your way. 4411 * Fast access to TODO states:: Single letter selection of state. 4412 * Per-file keywords:: Different files, different requirements. 4413 * Faces for TODO keywords:: Highlighting states. 4414 * TODO dependencies:: When one task needs to wait for others. 4415 @end menu 4416 4417 @node Workflow states 4418 @subsection TODO keywords as workflow states 4419 4420 @cindex TODO workflow 4421 @cindex workflow states as TODO keywords 4422 4423 You can use TODO keywords to indicate different, possibly @emph{sequential} 4424 states in the process of working on an item, for example@footnote{ Changing 4425 the variable @code{org-todo-keywords} only becomes effective after 4426 restarting Org mode in a buffer.}: 4427 4428 @lisp 4429 (setq org-todo-keywords 4430 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) 4431 @end lisp 4432 4433 The vertical bar separates the TODO keywords (states that @emph{need 4434 action}) from the DONE states (which need @emph{no further action}). If 4435 you do not provide the separator bar, the last state is used as the 4436 DONE state. 4437 4438 @cindex completion, of TODO keywords 4439 With this setup, the command @kbd{C-c C-t} cycles an entry from 4440 @samp{TODO} to @samp{FEEDBACK}, then to @samp{VERIFY}, and finally to @samp{DONE} and 4441 @samp{DELEGATED}. You may also use a numeric prefix argument to quickly 4442 select a specific state. For example @kbd{C-3 C-c C-t} changes 4443 the state immediately to @samp{VERIFY}. Or you can use @kbd{S-@key{RIGHT}} 4444 and @kbd{S-@key{LEFT}} to go forward and backward through the states. 4445 If you define many keywords, you can use in-buffer completion (see 4446 @ref{Completion}) or a special one-key selection scheme (see @ref{Fast access to TODO states}) to insert these words into the buffer. 4447 Changing a TODO state can be logged with a timestamp, see @ref{Tracking TODO state changes}, for more information. 4448 4449 @node TODO types 4450 @subsection TODO keywords as types 4451 4452 @cindex TODO types 4453 @cindex names as TODO keywords 4454 @cindex types as TODO keywords 4455 4456 The second possibility is to use TODO keywords to indicate different 4457 @emph{types} of action items. For example, you might want to indicate that 4458 items are for ``work'' or ``home''. Or, when you work with several people 4459 on a single project, you might want to assign action items directly to 4460 persons, by using their names as TODO keywords. This type of 4461 functionality is actually much better served by using tags (see 4462 @ref{Tags}), so the TODO implementation is kept just for backward 4463 compatibility. 4464 4465 Using TODO types, it would be set up like this: 4466 4467 @lisp 4468 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) 4469 @end lisp 4470 4471 In this case, different keywords do not indicate states, but rather 4472 different types. So the normal work flow would be to assign a task to 4473 a person, and later to mark it DONE@. Org mode supports this style by 4474 adapting the workings of the command @kbd{C-c C-t}@footnote{ This is 4475 also true for the @kbd{t} command in the agenda buffer.}. When 4476 used several times in succession, it still cycles through all names, 4477 in order to first select the right type for a task. But when you 4478 return to the item after some time and execute @kbd{C-c C-t} 4479 again, it will switch from any name directly to @samp{DONE}. Use prefix 4480 arguments or completion to quickly select a specific name. You can 4481 also review the items of a specific TODO type in a sparse tree by 4482 using a numeric prefix to @kbd{C-c / t}. For example, to see all 4483 things Lucy has to do, you would use @kbd{C-3 C-c / t}. To 4484 collect Lucy's items from all agenda files into a single buffer, you 4485 would use the numeric prefix argument as well when creating the global 4486 TODO list: @kbd{C-3 M-x org-agenda t}. 4487 4488 @node Multiple sets in one file 4489 @subsection Multiple keyword sets in one file 4490 4491 @cindex TODO keyword sets 4492 4493 Sometimes you may want to use different sets of TODO keywords in 4494 parallel. For example, you may want to have the basic TODO/DONE, but 4495 also a workflow for bug fixing, and a separate state indicating that 4496 an item has been canceled---so it is not DONE, but also does not 4497 require action. Your setup would then look like this: 4498 4499 @lisp 4500 (setq org-todo-keywords 4501 '((sequence "TODO" "|" "DONE") 4502 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") 4503 (sequence "|" "CANCELED"))) 4504 @end lisp 4505 4506 The keywords should all be different, this helps Org mode keep track 4507 of which subsequence should be used for a given entry. In this setup, 4508 @kbd{C-c C-t} only operates within a sub-sequence, so it switches 4509 from @samp{DONE} to (nothing) to @samp{TODO}, and from @samp{FIXED} to (nothing) to 4510 @samp{REPORT}. Therefore you need a mechanism to initially select the 4511 correct sequence. In addition to typing a keyword or using completion 4512 (see @ref{Completion}), you may also apply the following commands: 4513 4514 @table @asis 4515 @item @kbd{C-u C-u C-c C-t} 4516 @itemx @kbd{C-S-@key{RIGHT}} 4517 @itemx @kbd{C-S-@key{LEFT}} 4518 @kindex C-S-RIGHT 4519 @kindex C-S-LEFT 4520 @kindex C-u C-u C-c C-t 4521 These keys jump from one TODO sub-sequence to the next. In the 4522 above example, @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{RIGHT}} 4523 would jump from @samp{TODO} or @samp{DONE} to @samp{REPORT}, and any of the words 4524 in the second row to @samp{CANCELED}. Note that the @kbd{C-S-} key 4525 binding conflict with shift-selection (see @ref{Conflicts}). 4526 4527 @item @kbd{S-@key{RIGHT}} 4528 @itemx @kbd{S-@key{LEFT}} 4529 @kindex S-RIGHT 4530 @kindex S-LEFT 4531 @kbd{S-@key{LEFT}} and @kbd{S-@key{RIGHT}} walk through @emph{all} keywords 4532 from all sub-sequences, so for example @kbd{S-@key{RIGHT}} would 4533 switch from @samp{DONE} to @samp{REPORT} in the example above. For 4534 a discussion of the interaction with shift-selection, see @ref{Conflicts}. 4535 @end table 4536 4537 @node Fast access to TODO states 4538 @subsection Fast access to TODO states 4539 4540 If you would like to quickly change an entry to an arbitrary TODO 4541 state instead of cycling through the states, you can set up keys for 4542 single-letter access to the states. This is done by adding the 4543 selection character after each keyword, in parentheses@footnote{ All 4544 characters are allowed except @samp{@@}, @samp{^} and @samp{!}, which have a special 4545 meaning here.}. For example: 4546 4547 @lisp 4548 (setq org-todo-keywords 4549 '((sequence "TODO(t)" "|" "DONE(d)") 4550 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") 4551 (sequence "|" "CANCELED(c)"))) 4552 @end lisp 4553 4554 @vindex org-fast-tag-selection-include-todo 4555 If you then press @kbd{C-c C-t} followed by the selection key, 4556 the entry is switched to this state. @kbd{@key{SPC}} can be used to 4557 remove any TODO keyword from an entry@footnote{Check also the variable @code{org-fast-tag-selection-include-todo}, 4558 it allows you to change the TODO state through the tags interface (see 4559 @ref{Setting Tags}), in case you like to mingle the two concepts. Note 4560 that this means you need to come up with unique keys across both sets 4561 of keywords.}. 4562 4563 @node Per-file keywords 4564 @subsection Setting up keywords for individual files 4565 4566 @cindex keyword options 4567 @cindex per-file keywords 4568 @cindex @samp{TODO}, keyword 4569 @cindex @samp{TYP_TODO}, keyword 4570 @cindex @samp{SEQ_TODO}, keyword 4571 4572 It can be very useful to use different aspects of the TODO mechanism 4573 in different files. For file-local settings, you need to add special 4574 lines to the file which set the keywords and interpretation for that 4575 file only. For example, to set one of the two examples discussed 4576 above, you need one of the following lines, starting in column zero 4577 anywhere in the file: 4578 4579 @example 4580 #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED 4581 @end example 4582 4583 4584 You may also write @samp{#+SEQ_TODO} to be explicit about the 4585 interpretation, but it means the same as @samp{#+TODO}, or 4586 4587 @example 4588 #+TYP_TODO: Fred Sara Lucy Mike | DONE 4589 @end example 4590 4591 4592 A setup for using several sets in parallel would be: 4593 4594 @example 4595 #+TODO: TODO(t) | DONE(d) 4596 #+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) 4597 #+TODO: | CANCELED(c) 4598 @end example 4599 4600 @cindex completion, of option keywords 4601 @kindex M-TAB 4602 To make sure you are using the correct keyword, type @samp{#+} into the 4603 buffer and then use @kbd{M-@key{TAB}} to complete it (see @ref{Completion}). 4604 4605 @cindex DONE, final TODO keyword 4606 Remember that the keywords after the vertical bar---or the last 4607 keyword if no bar is there---must always mean that the item is DONE, 4608 although you may use a different word. After changing one of these 4609 lines, use @kbd{C-c C-c} with point still in the line to make the 4610 changes known to Org mode@footnote{ Org mode parses these lines only when 4611 Org mode is activated after visiting a file. @kbd{C-c C-c} with 4612 point in a line starting with @samp{#+} is simply restarting Org mode for 4613 the current buffer.}. 4614 4615 @node Faces for TODO keywords 4616 @subsection Faces for TODO keywords 4617 4618 @cindex faces, for TODO keywords 4619 4620 @vindex org-todo, face 4621 @vindex org-done, face 4622 @vindex org-todo-keyword-faces 4623 Org mode highlights TODO keywords with special faces: @code{org-todo} for 4624 keywords indicating that an item still has to be acted upon, and 4625 @code{org-done} for keywords indicating that an item is finished. If you 4626 are using more than two different states, you might want to use 4627 special faces for some of them. This can be done using the variable 4628 @code{org-todo-keyword-faces}. For example: 4629 4630 @lisp 4631 (setq org-todo-keyword-faces 4632 '(("TODO" . org-warning) ("STARTED" . "yellow") 4633 ("CANCELED" . (:foreground "blue" :weight bold)))) 4634 @end lisp 4635 4636 @vindex org-faces-easy-properties 4637 While using a list with face properties as shown for @samp{CANCELED} 4638 @emph{should} work, this does not always seem to be the case. If 4639 necessary, define a special face and use that. A string is 4640 interpreted as a color. The variable @code{org-faces-easy-properties} 4641 determines if that color is interpreted as a foreground or 4642 a background color. 4643 4644 @node TODO dependencies 4645 @subsection TODO dependencies 4646 4647 @cindex TODO dependencies 4648 @cindex dependencies, of TODO states 4649 4650 @vindex org-enforce-todo-dependencies 4651 @cindex @samp{ORDERED}, property 4652 The structure of Org files---hierarchy and lists---makes it easy to 4653 define TODO dependencies. Usually, a parent TODO task should not be 4654 marked as done until all TODO subtasks, or children tasks, are marked 4655 as done. Sometimes there is a logical sequence to (sub)tasks, so that 4656 one subtask cannot be acted upon before all siblings above it have 4657 been marked as done. If you customize the variable 4658 @code{org-enforce-todo-dependencies}, Org blocks entries from changing 4659 state to DONE while they have TODO children that are not DONE@. 4660 Furthermore, if an entry has a property @samp{ORDERED}, each of its TODO 4661 children is blocked until all earlier siblings are marked as done. 4662 Here is an example: 4663 4664 @example 4665 * TODO Blocked until (two) is done 4666 ** DONE one 4667 ** TODO two 4668 4669 * Parent 4670 :PROPERTIES: 4671 :ORDERED: t 4672 :END: 4673 ** TODO a 4674 ** TODO b, needs to wait for (a) 4675 ** TODO c, needs to wait for (a) and (b) 4676 @end example 4677 4678 @cindex TODO dependencies, @samp{NOBLOCKING} 4679 @cindex @samp{NOBLOCKING}, property 4680 You can ensure an entry is never blocked by using the @samp{NOBLOCKING} 4681 property (see @ref{Properties and Columns}): 4682 4683 @example 4684 * This entry is never blocked 4685 :PROPERTIES: 4686 :NOBLOCKING: t 4687 :END: 4688 @end example 4689 4690 @table @asis 4691 @item @kbd{C-c C-x o} (@code{org-toggle-ordered-property}) 4692 @kindex C-c C-x o 4693 @findex org-toggle-ordered-property 4694 @vindex org-track-ordered-property-with-tag 4695 Toggle the @samp{ORDERED} property of the current entry. A property is 4696 used for this behavior because this should be local to the current 4697 entry, not inherited from entries above like a tag (see @ref{Tags}). 4698 However, if you would like to @emph{track} the value of this property 4699 with a tag for better visibility, customize the variable 4700 @code{org-track-ordered-property-with-tag}. 4701 4702 @item @kbd{C-u C-u C-u C-c C-t} 4703 @kindex C-u C-u C-u C-u C-c C-t 4704 Change TODO state, regardless of any state blocking. 4705 @end table 4706 4707 @vindex org-agenda-dim-blocked-tasks 4708 If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries 4709 that cannot be marked as done because of unmarked children are shown 4710 in a dimmed font or even made invisible in agenda views (see @ref{Agenda Views}). 4711 4712 @cindex checkboxes and TODO dependencies 4713 @vindex org-enforce-todo-dependencies 4714 You can also block changes of TODO states by using checkboxes (see 4715 @ref{Checkboxes}). If you set the variable 4716 @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked 4717 checkboxes is blocked from switching to DONE@. 4718 4719 If you need more complex dependency structures, for example 4720 dependencies between entries in different trees or files, check out 4721 the module @samp{org-depend.el} in the @samp{org-contrib} repository. 4722 4723 @node Progress Logging 4724 @section Progress Logging 4725 4726 @cindex progress logging 4727 @cindex logging, of progress 4728 4729 To record a timestamp and a note when changing a TODO state, call the 4730 command @code{org-todo} with a prefix argument. 4731 4732 @table @asis 4733 @item @kbd{C-u C-c C-t} (@code{org-todo}) 4734 @kindex C-u C-c C-t 4735 Prompt for a note and record a the time of the TODO state change. 4736 The note is inserted as a list item below the headline, but can also 4737 be placed into a drawer, see @ref{Tracking TODO state changes}. 4738 @end table 4739 4740 If you want to be more systematic, Org mode can automatically record a 4741 timestamp and optionally a note when you mark a TODO item as DONE, or 4742 even each time you change the state of a TODO item. This system is 4743 highly configurable, settings can be on a per-keyword basis and can be 4744 localized to a file or even a subtree. For information on how to 4745 clock working time for a task, see @ref{Clocking Work Time}. 4746 4747 @menu 4748 * Closing items:: When was this entry marked as done? 4749 * Tracking TODO state changes:: When did the status change? 4750 * Tracking your habits:: How consistent have you been? 4751 @end menu 4752 4753 @node Closing items 4754 @subsection Closing items 4755 4756 The most basic automatic logging is to keep track of @emph{when} a certain 4757 TODO item was marked as done. This can be achieved with@footnote{ The 4758 corresponding in-buffer setting is: @samp{#+STARTUP: logdone}.} 4759 4760 @lisp 4761 (setq org-log-done 'time) 4762 @end lisp 4763 4764 @vindex org-closed-keep-when-no-todo 4765 @noindent 4766 Then each time you turn an entry from a TODO (not-done) state into any 4767 of the DONE states, a line @samp{CLOSED: [timestamp]} is inserted just 4768 after the headline. If you turn the entry back into a TODO item 4769 through further state cycling, that line is removed again. If you 4770 turn the entry back to a non-TODO state (by pressing @kbd{C-c C-t @key{SPC}} for example), that line is also removed, unless you set 4771 @code{org-closed-keep-when-no-todo} to non-@code{nil}. If you want to record a 4772 note along with the timestamp, use@footnote{ The corresponding in-buffer 4773 setting is: @samp{#+STARTUP: lognotedone}.} 4774 4775 @lisp 4776 (setq org-log-done 'note) 4777 @end lisp 4778 4779 @noindent 4780 You are then prompted for a note, and that note is stored below the 4781 entry with a @samp{Closing Note} heading. 4782 4783 @node Tracking TODO state changes 4784 @subsection Tracking TODO state changes 4785 4786 @cindex drawer, for state change recording 4787 4788 @vindex org-log-states-order-reversed 4789 @vindex org-log-into-drawer 4790 @cindex @samp{LOG_INTO_DRAWER}, property 4791 You might want to automatically keep track of when a state change 4792 occurred and maybe take a note about this change. You can either 4793 record just a timestamp, or a time-stamped note. These records are 4794 inserted after the headline as an itemized list, newest first@footnote{ See 4795 the variable @code{org-log-states-order-reversed}.}. When taking a lot of 4796 notes, you might want to get the notes out of the way into a drawer 4797 (see @ref{Drawers}). Customize the variable @code{org-log-into-drawer} to 4798 get this behavior---the recommended drawer for this is called 4799 @samp{LOGBOOK}@footnote{ Note that the @samp{LOGBOOK} drawer is unfolded when 4800 pressing @kbd{@key{SPC}} in the agenda to show an entry---use 4801 @kbd{C-u @key{SPC}} to keep it folded here.}. You can also overrule 4802 the setting of this variable for a subtree by setting a 4803 @samp{LOG_INTO_DRAWER} property. 4804 4805 Since it is normally too much to record a note for every state, Org 4806 mode expects configuration on a per-keyword basis for this. This is 4807 achieved by adding special markers @samp{!} (for a timestamp) or @samp{@@} (for 4808 a note with timestamp) in parentheses after each keyword. For 4809 example, with the setting 4810 4811 @lisp 4812 (setq org-todo-keywords 4813 '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)"))) 4814 @end lisp 4815 4816 @vindex org-log-done 4817 You not only define global TODO keywords and fast access keys, but 4818 also request that a time is recorded when the entry is set to @samp{DONE}, 4819 and that a note is recorded when switching to @samp{WAIT} or 4820 @samp{CANCELED}@footnote{It is possible that Org mode records two timestamps when you 4821 are using both @code{org-log-done} and state change logging. However, it 4822 never prompts for two notes: if you have configured both, the state 4823 change recording note takes precedence and cancel the closing note.}. The setting for @samp{WAIT} is even more special: the 4824 @samp{!} after the slash means that in addition to the note taken when 4825 entering the state, a timestamp should be recorded when @emph{leaving} the 4826 @samp{WAIT} state, if and only if the @emph{target} state does not configure 4827 logging for entering it. So it has no effect when switching from 4828 @samp{WAIT} to @samp{DONE}, because @samp{DONE} is configured to record a timestamp 4829 only. But when switching from @samp{WAIT} back to @samp{TODO}, the @samp{/!} in the 4830 @samp{WAIT} setting now triggers a timestamp even though @samp{TODO} has no 4831 logging configured. 4832 4833 You can use the exact same syntax for setting logging preferences local 4834 to a buffer: 4835 4836 @example 4837 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) 4838 @end example 4839 4840 4841 To record a timestamp without a note for TODO keywords configured with 4842 @samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted. 4843 4844 @cindex @samp{LOGGING}, property 4845 In order to define logging settings that are local to a subtree or 4846 a single item, define a @samp{LOGGING} property in this entry. Any 4847 non-empty @samp{LOGGING} property resets all logging settings to @code{nil}. 4848 You may then turn on logging for this specific tree using @samp{STARTUP} 4849 keywords like @samp{lognotedone} or @samp{logrepeat}, as well as adding state 4850 specific settings like @samp{TODO(!)}. For example: 4851 4852 @example 4853 * TODO Log each state with only a time 4854 :PROPERTIES: 4855 :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!) 4856 :END: 4857 * TODO Only log when switching to WAIT, and when repeating 4858 :PROPERTIES: 4859 :LOGGING: WAIT(@@) logrepeat 4860 :END: 4861 * TODO No logging at all 4862 :PROPERTIES: 4863 :LOGGING: nil 4864 :END: 4865 @end example 4866 4867 @node Tracking your habits 4868 @subsection Tracking your habits 4869 4870 @cindex habits 4871 @cindex @samp{STYLE}, property 4872 4873 Org has the ability to track the consistency of a special category of 4874 TODO, called ``habits.'' To use habits, you have to enable the @code{habit} 4875 module by customizing the variable @code{org-modules}. 4876 4877 A habit has the following properties: 4878 4879 @enumerate 4880 @item 4881 The habit is a TODO item, with a TODO keyword representing an open 4882 state. 4883 4884 @item 4885 The property @samp{STYLE} is set to the value @samp{habit} (see @ref{Properties and Columns}). 4886 4887 @item 4888 The TODO has a scheduled date, usually with a @samp{.+} style repeat 4889 interval. A @samp{++} style may be appropriate for habits with time 4890 constraints, e.g., must be done on weekends, or a @samp{+} style for an 4891 unusual habit that can have a backlog, e.g., weekly reports. 4892 4893 @item 4894 The TODO may also have minimum and maximum ranges specified by 4895 using the syntax @samp{.+2d/3d}, which says that you want to do the task 4896 at least every three days, but at most every two days. 4897 4898 @item 4899 State logging for the DONE state is enabled (see @ref{Tracking TODO state changes}), in order for historical data to be represented in 4900 the consistency graph. If it is not enabled it is not an error, 4901 but the consistency graphs are largely meaningless. 4902 @end enumerate 4903 4904 To give you an idea of what the above rules look like in action, here's an 4905 actual habit with some history: 4906 4907 @example 4908 ** TODO Shave 4909 SCHEDULED: <2009-10-17 Sat .+2d/4d> 4910 :PROPERTIES: 4911 :STYLE: habit 4912 :LAST_REPEAT: [2009-10-19 Mon 00:36] 4913 :END: 4914 - State "DONE" from "TODO" [2009-10-15 Thu] 4915 - State "DONE" from "TODO" [2009-10-12 Mon] 4916 - State "DONE" from "TODO" [2009-10-10 Sat] 4917 - State "DONE" from "TODO" [2009-10-04 Sun] 4918 - State "DONE" from "TODO" [2009-10-02 Fri] 4919 - State "DONE" from "TODO" [2009-09-29 Tue] 4920 - State "DONE" from "TODO" [2009-09-25 Fri] 4921 - State "DONE" from "TODO" [2009-09-19 Sat] 4922 - State "DONE" from "TODO" [2009-09-16 Wed] 4923 - State "DONE" from "TODO" [2009-09-12 Sat] 4924 @end example 4925 4926 What this habit says is: I want to shave at most every 2 days---given 4927 by the @samp{SCHEDULED} date and repeat interval---and at least every 4928 4 days. If today is the 15th, then the habit first appears in the 4929 agenda (see @ref{Agenda Views}) on Oct 17, after the minimum of 2 days has 4930 elapsed, and will appear overdue on Oct 19, after four days have 4931 elapsed. 4932 4933 What's really useful about habits is that they are displayed along 4934 with a consistency graph, to show how consistent you've been at 4935 getting that task done in the past. This graph shows every day that 4936 the task was done over the past three weeks, with colors for each day. 4937 The colors used are: 4938 4939 @table @asis 4940 @item Blue 4941 If the task was not to be done yet on that day. 4942 @item Green 4943 If the task could have been done on that day. 4944 @item Yellow 4945 If the task was going to be overdue the next day. 4946 @item Red 4947 If the task was overdue on that day. 4948 @end table 4949 4950 In addition to coloring each day, the day is also marked with an 4951 asterisk if the task was actually done that day, and an exclamation 4952 mark to show where the current day falls in the graph. 4953 4954 There are several configuration variables that can be used to change 4955 the way habits are displayed in the agenda. 4956 4957 @table @asis 4958 @item @code{org-habit-graph-column} 4959 @vindex org-habit-graph-column 4960 The buffer column at which the consistency graph should be drawn. 4961 This overwrites any text in that column, so it is a good idea to 4962 keep your habits' titles brief and to the point. 4963 4964 @item @code{org-habit-preceding-days} 4965 @vindex org-habit-preceding-days 4966 The amount of history, in days before today, to appear in 4967 consistency graphs. 4968 4969 @item @code{org-habit-following-days} 4970 @vindex org-habit-following-days 4971 The number of days after today that appear in consistency graphs. 4972 4973 @item @code{org-habit-show-habits-only-for-today} 4974 @vindex org-habit-show-habits-only-for-today 4975 If non-@code{nil}, only show habits in today's agenda view. The default 4976 value is @code{t}. Pressing @kbd{C-u K} in the agenda toggles this 4977 variable. 4978 @end table 4979 4980 Lastly, pressing @kbd{K} in the agenda buffer causes habits to 4981 temporarily be disabled and do not appear at all. Press @kbd{K} 4982 again to bring them back. They are also subject to tag filtering, if 4983 you have habits which should only be done in certain contexts, for 4984 example. 4985 4986 @node Priorities 4987 @section Priorities 4988 4989 @cindex priorities 4990 @cindex priority cookie 4991 4992 If you use Org mode extensively, you may end up with enough TODO items 4993 that it starts to make sense to prioritize them. Prioritizing can be 4994 done by placing a @emph{priority cookie} into the headline of a TODO item 4995 right after the TODO keyword, like this: 4996 4997 @example 4998 *** TODO [#A] Write letter to Sam Fortune 4999 @end example 5000 5001 5002 @vindex org-priority-faces 5003 By default, Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. 5004 @samp{A} is the highest priority. An entry without a cookie is treated as 5005 equivalent if it had priority @samp{B}. Priorities make a difference only 5006 for sorting in the agenda (see @ref{Weekly/daily agenda}). Outside the 5007 agenda, they have no inherent meaning to Org mode. The cookies are 5008 displayed with the face defined by the variable @code{org-priority-faces}, 5009 which can be customized. 5010 5011 You can also use numeric values for priorities, such as 5012 5013 @example 5014 *** TODO [#1] Write letter to Sam Fortune 5015 @end example 5016 5017 5018 When using numeric priorities, you need to set @code{org-priority-highest}, 5019 @code{org-priority-lowest} and @code{org-priority-default} to integers, which 5020 must all be strictly inferior to 65. 5021 5022 Priorities can be attached to any outline node; they do not need to be 5023 TODO items. 5024 5025 @table @asis 5026 @item @kbd{C-c ,} (@code{org-priority}) 5027 @kindex C-c , 5028 @findex org-priority 5029 Set the priority of the current headline. The command prompts for 5030 a priority character @samp{A}, @samp{B} or @samp{C}. When you press @kbd{@key{SPC}} 5031 instead, the priority cookie, if one is set, is removed from the 5032 headline. The priorities can also be changed ``remotely'' from the 5033 agenda buffer with the @kbd{,} command (see @ref{Agenda Commands}). 5034 5035 @item @kbd{S-@key{UP}} (@code{org-priority-up}) 5036 @itemx @kbd{S-@key{DOWN}} (@code{org-priority-down}) 5037 @kindex S-UP 5038 @kindex S-DOWN 5039 @findex org-priority-up 5040 @findex org-priority-down 5041 @vindex org-priority-start-cycle-with-default 5042 Increase/decrease the priority of the current headline@footnote{ See also 5043 the option @code{org-priority-start-cycle-with-default}.}. Note that 5044 these keys are also used to modify timestamps (see @ref{Creating Timestamps}). See also @ref{Conflicts}, 5045 for a discussion of the interaction with shift-selection. 5046 @end table 5047 5048 @vindex org-priority-highest 5049 @vindex org-priority-lowest 5050 @vindex org-priority-default 5051 You can change the range of allowed priorities by setting the 5052 variables @code{org-priority-highest}, @code{org-priority-lowest}, and 5053 @code{org-priority-default}. For an individual buffer, you may set these 5054 values (highest, lowest, default) like this (please make sure that the 5055 highest priority is earlier in the alphabet than the lowest priority): 5056 5057 @cindex @samp{PRIORITIES}, keyword 5058 @example 5059 #+PRIORITIES: A C B 5060 @end example 5061 5062 5063 Or, using numeric values: 5064 5065 @example 5066 #+PRIORITIES: 1 10 5 5067 @end example 5068 5069 @node Breaking Down Tasks 5070 @section Breaking Down Tasks into Subtasks 5071 5072 @cindex tasks, breaking down 5073 @cindex statistics, for TODO items 5074 5075 @vindex org-agenda-todo-list-sublevels 5076 It is often advisable to break down large tasks into smaller, 5077 manageable subtasks. You can do this by creating an outline tree 5078 below a TODO item, with detailed subtasks on the tree@footnote{ To keep 5079 subtasks out of the global TODO list, see the option 5080 @code{org-agenda-todo-list-sublevels}.}. To keep an overview of the 5081 fraction of subtasks that have already been marked as done, insert 5082 either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies are 5083 updated each time the TODO status of a child changes, or when pressing 5084 @kbd{C-c C-c} on the cookie. For example: 5085 5086 @example 5087 * Organize Party [33%] 5088 ** TODO Call people [1/2] 5089 *** TODO Peter 5090 *** DONE Sarah 5091 ** TODO Buy food 5092 ** DONE Talk to neighbor 5093 @end example 5094 5095 @cindex @samp{COOKIE_DATA}, property 5096 If a heading has both checkboxes and TODO children below it, the 5097 meaning of the statistics cookie become ambiguous. Set the property 5098 @samp{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve this issue. 5099 5100 @vindex org-hierarchical-todo-statistics 5101 If you would like to have the statistics cookie count any TODO entries 5102 in the subtree (not just direct children), configure the variable 5103 @code{org-hierarchical-todo-statistics}. To do this for a single subtree, 5104 include the word @samp{recursive} into the value of the @samp{COOKIE_DATA} 5105 property. 5106 5107 @example 5108 * Parent capturing statistics [2/20] 5109 :PROPERTIES: 5110 :COOKIE_DATA: todo recursive 5111 :END: 5112 @end example 5113 5114 If you would like a TODO entry to automatically change to DONE when 5115 all children are done, you can use the following setup: 5116 5117 @lisp 5118 (defun org-summary-todo (n-done n-not-done) 5119 "Switch entry to DONE when all subentries are done, to TODO otherwise." 5120 (let (org-log-done org-log-states) ; turn off logging 5121 (org-todo (if (= n-not-done 0) "DONE" "TODO")))) 5122 5123 (add-hook 'org-after-todo-statistics-hook #'org-summary-todo) 5124 @end lisp 5125 5126 Another possibility is the use of checkboxes to identify (a hierarchy 5127 of) a large number of subtasks (see @ref{Checkboxes}). 5128 5129 @node Checkboxes 5130 @section Checkboxes 5131 5132 @cindex checkboxes 5133 5134 @vindex org-list-automatic-rules 5135 Every item in a plain list@footnote{With the exception of description lists. But you can allow it 5136 by modifying @code{org-list-automatic-rules} accordingly.} (see @ref{Plain Lists}) can be made into 5137 a checkbox by starting it with the string @samp{[ ]}. This feature is 5138 similar to TODO items (see @ref{TODO Items}), but is more lightweight. 5139 Checkboxes are not included into the global TODO list, so they are 5140 often great to split a task into a number of simple steps. Or you can 5141 use them in a shopping list. 5142 5143 Here is an example of a checkbox list. 5144 5145 @example 5146 * TODO Organize party [2/4] 5147 - [-] call people [1/3] 5148 - [ ] Peter 5149 - [X] Sarah 5150 - [ ] Sam 5151 - [X] order food 5152 - [ ] think about what music to play 5153 - [X] talk to the neighbors 5154 @end example 5155 5156 Checkboxes work hierarchically, so if a checkbox item has children 5157 that are checkboxes, toggling one of the children checkboxes makes the 5158 parent checkbox reflect if none, some, or all of the children are 5159 checked. 5160 5161 @cindex statistics, for checkboxes 5162 @cindex checkbox statistics 5163 @cindex @samp{COOKIE_DATA}, property 5164 @vindex org-hierarchical-checkbox-statistics 5165 The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies 5166 indicating how many checkboxes present in this entry have been checked 5167 off, and the total number of checkboxes present. This can give you an 5168 idea on how many checkboxes remain, even without opening a folded 5169 entry. The cookies can be placed into a headline or into (the first 5170 line of) a plain list item. Each cookie covers checkboxes of direct 5171 children structurally below the headline/item on which the cookie 5172 appears@footnote{ Set the variable @code{org-hierarchical-checkbox-statistics} 5173 if you want such cookies to count all checkboxes below the cookie, not 5174 just those belonging to direct children.}. You have to insert the 5175 cookie yourself by typing either @samp{[/]} or @samp{[%]}. With @samp{[/]} you get 5176 an @samp{n out of m} result, as in the examples above. With @samp{[%]} you get 5177 information about the percentage of checkboxes checked (in the above 5178 example, this would be @samp{[50%]} and @samp{[33%]}, respectively). In a 5179 headline, a cookie can count either checkboxes below the heading or 5180 TODO states of children, and it displays whatever was changed last. 5181 Set the property @samp{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to 5182 resolve this issue. 5183 5184 @cindex blocking, of checkboxes 5185 @cindex checkbox blocking 5186 @cindex @samp{ORDERED}, property 5187 If the current outline node has an @samp{ORDERED} property, checkboxes must 5188 be checked off in sequence, and an error is thrown if you try to check 5189 off a box while there are unchecked boxes above it. 5190 5191 The following commands work with checkboxes: 5192 5193 @table @asis 5194 @item @kbd{C-c C-c} (@code{org-toggle-checkbox}) 5195 @kindex C-c C-c 5196 @findex org-toggle-checkbox 5197 Toggle checkbox status or---with prefix argument---checkbox presence 5198 at point. With a single prefix argument, add an empty checkbox or 5199 remove the current one@footnote{ @kbd{C-u C-c C-c} on the @emph{first} 5200 item of a list with no checkbox adds checkboxes to the rest of the 5201 list.}. With a double prefix argument, set it to @samp{[-]}, which is 5202 considered to be an intermediate state. 5203 5204 @item @kbd{C-c C-x C-b} (@code{org-toggle-checkbox}) 5205 @kindex C-c C-x C-b 5206 Toggle checkbox status or---with prefix argument---checkbox presence 5207 at point. With double prefix argument, set it to @samp{[-]}, which is 5208 considered to be an intermediate state. 5209 5210 @itemize 5211 @item 5212 If there is an active region, toggle the first checkbox in the 5213 region and set all remaining boxes to the same status as the 5214 first. With a prefix argument, add or remove the checkbox for all 5215 items in the region. 5216 5217 @item 5218 If point is in a headline, toggle checkboxes in the region between 5219 this headline and the next---so @emph{not} the entire subtree. 5220 5221 @item 5222 If there is no active region, just toggle the checkbox at point. 5223 @end itemize 5224 5225 @item @kbd{C-c C-x C-r} (@code{org-toggle-radio-button}) 5226 @kindex C-c C-x C-r 5227 @findex org-toggle-radio-button 5228 @cindex radio button, checkbox as 5229 Toggle checkbox status by using the checkbox of the item at point as 5230 a radio button: when the checkbox is turned on, all other checkboxes 5231 on the same level will be turned off. With a universal prefix 5232 argument, toggle the presence of the checkbox. With a double prefix 5233 argument, set it to @samp{[-]}. 5234 5235 @findex org-list-checkbox-radio-mode 5236 @kbd{C-c C-c} can be told to consider checkboxes as radio buttons by 5237 setting @samp{#+ATTR_ORG: :radio t} right before the list or by calling 5238 @kbd{M-x org-list-checkbox-radio-mode} to activate this minor mode. 5239 5240 @item @kbd{M-S-@key{RET}} (@code{org-insert-todo-heading}) 5241 @kindex M-S-RET 5242 @findex org-insert-todo-heading 5243 Insert a new item with a checkbox. This works only if point is 5244 already in a plain list item (see @ref{Plain Lists}). 5245 5246 @item @kbd{C-c C-x o} (@code{org-toggle-ordered-property}) 5247 @kindex C-c C-x o 5248 @findex org-toggle-ordered-property 5249 @vindex org-track-ordered-property-with-tag 5250 Toggle the @samp{ORDERED} property of the entry, to toggle if checkboxes 5251 must be checked off in sequence. A property is used for this 5252 behavior because this should be local to the current entry, not 5253 inherited like a tag. However, if you would like to @emph{track} the 5254 value of this property with a tag for better visibility, customize 5255 @code{org-track-ordered-property-with-tag}. 5256 5257 @item @kbd{C-c #} (@code{org-update-statistics-cookies}) 5258 @kindex C-c # 5259 @findex org-update-statistics-cookies 5260 Update the statistics cookie in the current outline entry. When 5261 called with a @kbd{C-u} prefix, update the entire file. 5262 Checkbox statistic cookies are updated automatically if you toggle 5263 checkboxes with @kbd{C-c C-c} and make new ones with 5264 @kbd{M-S-@key{RET}}. TODO statistics cookies update when changing 5265 TODO states. If you delete boxes/entries or add/change them by 5266 hand, use this command to get things back into sync. 5267 @end table 5268 5269 @node Tags 5270 @chapter Tags 5271 5272 @cindex tags 5273 @cindex headline tagging 5274 @cindex matching, tags 5275 @cindex sparse tree, tag based 5276 5277 An excellent way to implement labels and contexts for 5278 cross-correlating information is to assign @emph{tags} to headlines. Org 5279 mode has extensive support for tags. 5280 5281 @vindex org-tag-faces 5282 Every headline can contain a list of tags; they occur at the end of 5283 the headline. Tags are normal words containing letters, numbers, @samp{_}, 5284 and @samp{@@}. Tags must be preceded and followed by a single colon, e.g., 5285 @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. Tags 5286 by default are in bold face with the same color as the headline. You 5287 may specify special faces for specific tags using the variable 5288 @code{org-tag-faces}, in much the same way as you can for TODO keywords 5289 (see @ref{Faces for TODO keywords}). 5290 5291 @menu 5292 * Tag Inheritance:: Tags use the tree structure of an outline. 5293 * Setting Tags:: How to assign tags to a headline. 5294 * Tag Hierarchy:: Create a hierarchy of tags. 5295 * Tag Searches:: Searching for combinations of tags. 5296 @end menu 5297 5298 @node Tag Inheritance 5299 @section Tag Inheritance 5300 5301 @cindex tag inheritance 5302 @cindex inheritance, of tags 5303 @cindex sublevels, inclusion into tags match 5304 5305 @emph{Tags} make use of the hierarchical structure of outline trees. If 5306 a heading has a certain tag, all subheadings inherit the tag as well. 5307 For example, in the list 5308 5309 @example 5310 * Meeting with the French group :work: 5311 ** Summary by Frank :boss:notes: 5312 *** TODO Prepare slides for him :action: 5313 @end example 5314 5315 @noindent 5316 the final heading has the tags @samp{work}, @samp{boss}, @samp{notes}, and @samp{action} 5317 even though the final heading is not explicitly marked with those 5318 tags. You can also set tags that all entries in a file should inherit 5319 just as if these tags were defined in a hypothetical level zero that 5320 surrounds the entire file. Use a line like this@footnote{ As with all 5321 these in-buffer settings, pressing @kbd{C-c C-c} activates any 5322 changes in the line.} 5323 5324 @cindex @samp{FILETAGS}, keyword 5325 @example 5326 #+FILETAGS: :Peter:Boss:Secret: 5327 @end example 5328 5329 5330 @vindex org-use-tag-inheritance 5331 @vindex org-tags-exclude-from-inheritance 5332 To limit tag inheritance to specific tags, or to turn it off entirely, 5333 use the variables @code{org-use-tag-inheritance} and 5334 @code{org-tags-exclude-from-inheritance}. 5335 5336 @vindex org-tags-match-list-sublevels 5337 When a headline matches during a tags search while tag inheritance is 5338 turned on, all the sublevels in the same tree---for a simple match 5339 form---match as well@footnote{ This is only true if the search does not 5340 involve more complex tests including properties (see @ref{Property Searches}).}. The list of matches may then become very long. If you 5341 only want to see the first tags match in a subtree, configure the 5342 variable @code{org-tags-match-list-sublevels} (not recommended). 5343 5344 @vindex org-agenda-use-tag-inheritance 5345 Tag inheritance is relevant when the agenda search tries to match 5346 a tag, either in the @code{tags} or @code{tags-todo} agenda types. In other 5347 agenda types, @code{org-use-tag-inheritance} has no effect. Still, you may 5348 want to have your tags correctly set in the agenda, so that tag 5349 filtering works fine, with inherited tags. Set 5350 @code{org-agenda-use-tag-inheritance} to control this: the default value 5351 includes all agenda types, but setting this to @code{nil} can really speed 5352 up agenda generation. 5353 5354 @node Setting Tags 5355 @section Setting Tags 5356 5357 @cindex setting tags 5358 @cindex tags, setting 5359 5360 @kindex M-TAB 5361 Tags can simply be typed into the buffer at the end of a headline. 5362 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is 5363 also a special command for inserting tags: 5364 5365 @table @asis 5366 @item @kbd{C-c C-q} (@code{org-set-tags-command}) 5367 @kindex C-c C-q 5368 @findex org-set-tags-command 5369 @cindex completion, of tags 5370 @vindex org-tags-column 5371 Enter new tags for the current headline. Org mode either offers 5372 completion or a special single-key interface for setting tags, see 5373 below. After pressing @kbd{@key{RET}}, the tags are inserted and 5374 aligned to @code{org-tags-column}. When called with a @kbd{C-u} 5375 prefix, all tags in the current buffer are aligned to that column, 5376 just to make things look nice. Tags are automatically realigned 5377 after promotion, demotion, and TODO state changes (see @ref{TODO Basics}). 5378 5379 @item @kbd{C-c C-c} (@code{org-set-tags-command}) 5380 @kindex C-c C-c 5381 When point is in a headline, this does the same as @kbd{C-c C-q}. 5382 @end table 5383 5384 @vindex org-complete-tags-always-offer-all-agenda-tags 5385 @vindex org-tag-alist 5386 @cindex @samp{TAGS}, keyword 5387 Org supports tag insertion based on a @emph{list of tags}. By default this 5388 list is constructed dynamically, containing all tags currently used in 5389 the buffer@footnote{ To extend this default list to all tags used in all 5390 agenda files (see @ref{Agenda Views}), customize the variable 5391 @code{org-complete-tags-always-offer-all-agenda-tags}.}. You may also 5392 globally specify a hard list of tags with the variable 5393 @code{org-tag-alist}. Finally you can set the default tags for a given 5394 file using the @samp{TAGS} keyword, like 5395 5396 @example 5397 #+TAGS: @@work @@home @@tennisclub 5398 #+TAGS: laptop car pc sailboat 5399 @end example 5400 5401 If you have globally defined your preferred set of tags using the 5402 variable @code{org-tag-alist}, but would like to use a dynamic tag list in 5403 a specific file, add an empty @samp{TAGS} keyword to that file: 5404 5405 @example 5406 #+TAGS: 5407 @end example 5408 5409 5410 @vindex org-tag-persistent-alist 5411 If you have a preferred set of tags that you would like to use in 5412 every file, in addition to those defined on a per-file basis by @samp{TAGS} 5413 keyword, then you may specify a list of tags with the variable 5414 @code{org-tag-persistent-alist}. You may turn this off on a per-file basis 5415 by adding a @samp{STARTUP} keyword to that file: 5416 5417 @example 5418 #+STARTUP: noptag 5419 @end example 5420 5421 5422 By default Org mode uses the standard minibuffer completion facilities 5423 for entering tags. However, it also implements another, quicker, tag 5424 selection method called @emph{fast tag selection}. This allows you to 5425 select and deselect tags with just a single key press. For this to 5426 work well you should assign unique letters to most of your commonly 5427 used tags. You can do this globally by configuring the variable 5428 @code{org-tag-alist} in your Emacs init file. For example, you may find 5429 the need to tag many items in different files with @samp{@@home}. In this 5430 case you can set something like: 5431 5432 @lisp 5433 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) 5434 @end lisp 5435 5436 If the tag is only relevant to the file you are working on, then you 5437 can instead set the @samp{TAGS} keyword as: 5438 5439 @example 5440 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) 5441 @end example 5442 5443 5444 The tags interface shows the available tags in a splash window. If 5445 you want to start a new line after a specific tag, insert @samp{\n} into 5446 the tag list 5447 5448 @example 5449 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p) 5450 @end example 5451 5452 5453 @noindent 5454 or write them in two lines: 5455 5456 @example 5457 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) 5458 #+TAGS: laptop(l) pc(p) 5459 @end example 5460 5461 You can also group together tags that are mutually exclusive by using 5462 braces, as in: 5463 5464 @example 5465 #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p) 5466 @end example 5467 5468 5469 @noindent 5470 you indicate that at most one of @samp{@@work}, @samp{@@home}, and @samp{@@tennisclub} 5471 should be selected. Multiple such groups are allowed. 5472 5473 Do not forget to press @kbd{C-c C-c} with point in one of these 5474 lines to activate any changes. 5475 5476 To set these mutually exclusive groups in the variable 5477 @code{org-tags-alist}, you must use the dummy tags @code{:startgroup} and 5478 @code{:endgroup} instead of the braces. Similarly, you can use @code{:newline} 5479 to indicate a line break. The previous example would be set globally 5480 by the following configuration: 5481 5482 @lisp 5483 (setq org-tag-alist '((:startgroup . nil) 5484 ("@@work" . ?w) ("@@home" . ?h) 5485 ("@@tennisclub" . ?t) 5486 (:endgroup . nil) 5487 ("laptop" . ?l) ("pc" . ?p))) 5488 @end lisp 5489 5490 If at least one tag has a selection key then pressing @kbd{C-c C-c} automatically presents you with a special interface, listing 5491 inherited tags, the tags of the current headline, and a list of all 5492 valid tags with corresponding keys@footnote{ Keys are automatically 5493 assigned to tags that have no configured keys.}. 5494 5495 Pressing keys assigned to tags adds or removes them from the list of 5496 tags in the current line. Selecting a tag in a group of mutually 5497 exclusive tags turns off any other tag from that group. 5498 5499 In this interface, you can also use the following special keys: 5500 5501 @table @asis 5502 @item @kbd{@key{TAB}} 5503 @kindex TAB 5504 Enter a tag in the minibuffer, even if the tag is not in the 5505 predefined list. You can complete on all tags present in the buffer 5506 and globally pre-defined tags from @code{org-tag-alist} and 5507 @code{org-tag-persistent-alist}. You can also add several tags: just 5508 separate them with a comma. 5509 5510 @item @kbd{@key{SPC}} 5511 @kindex SPC 5512 Clear all tags for this line. 5513 5514 @item @kbd{@key{RET}} 5515 @kindex RET 5516 Accept the modified set. 5517 5518 @item @kbd{C-g} 5519 @kindex C-g 5520 Abort without installing changes. 5521 5522 @item @kbd{q} 5523 @kindex q 5524 If @kbd{q} is not assigned to a tag, it aborts like 5525 @kbd{C-g}. 5526 5527 @item @kbd{!} 5528 @kindex ! 5529 Turn off groups of mutually exclusive tags. Use this to (as an 5530 exception) assign several tags from such a group. 5531 5532 @item @kbd{C-c} 5533 @kindex C-c C-c 5534 Toggle auto-exit after the next change (see below). If you are 5535 using expert mode, the first @kbd{C-c} displays the selection 5536 window. 5537 @end table 5538 5539 This method lets you assign tags to a headline with very few keys. 5540 With the above setup, you could clear the current tags and set 5541 @samp{@@home}, @samp{laptop} and @samp{pc} tags with just the following keys: 5542 @kbd{C-c C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to @samp{@@work} 5543 would be done with @kbd{C-c C-c w @key{RET}} or alternatively with 5544 @kbd{C-c C-c C-c w}. Adding the non-predefined tag @samp{sarah} could 5545 be done with @kbd{C-c C-c @key{TAB} s a r a h @key{RET}}. 5546 5547 @vindex org-fast-tag-selection-single-key 5548 If you find that most of the time you need only a single key press to 5549 modify your list of tags, set the variable 5550 @code{org-fast-tag-selection-single-key}. Then you no longer have to press 5551 @kbd{@key{RET}} to exit fast tag selection---it exits after the first 5552 change. If you then occasionally need more keys, press @kbd{C-c} 5553 to turn off auto-exit for the current tag selection process (in 5554 effect: start selection with @kbd{C-c C-c C-c} instead of 5555 @kbd{C-c C-c}). If you set the variable to the value @code{expert}, 5556 the special window is not even shown for single-key tag selection, it 5557 comes up only when you press an extra @kbd{C-c}. 5558 5559 @node Tag Hierarchy 5560 @section Tag Hierarchy 5561 5562 @cindex group tags 5563 @cindex tags, groups 5564 @cindex tags hierarchy 5565 5566 Tags can be defined in hierarchies. A tag can be defined as a @emph{group 5567 tag} for a set of other tags. The group tag can be seen as the 5568 ``broader term'' for its set of tags. Defining multiple group tags and 5569 nesting them creates a tag hierarchy. 5570 5571 One use-case is to create a taxonomy of terms (tags) that can be used 5572 to classify nodes in a document or set of documents. 5573 5574 When you search for a group tag, it return matches for all members in 5575 the group and its subgroups. In an agenda view, filtering by a group 5576 tag displays or hide headlines tagged with at least one of the members 5577 of the group or any of its subgroups. This makes tag searches and 5578 filters even more flexible. 5579 5580 You can set group tags by using brackets and inserting a colon between 5581 the group tag and its related tags---beware that all whitespaces are 5582 mandatory so that Org can parse this line correctly: 5583 5584 @example 5585 #+TAGS: [ GTD : Control Persp ] 5586 @end example 5587 5588 5589 In this example, @samp{GTD} is the group tag and it is related to two other 5590 tags: @samp{Control}, @samp{Persp}. Defining @samp{Control} and @samp{Persp} as group 5591 tags creates a hierarchy of tags: 5592 5593 @example 5594 #+TAGS: [ Control : Context Task ] 5595 #+TAGS: [ Persp : Vision Goal AOF Project ] 5596 @end example 5597 5598 That can conceptually be seen as a hierarchy of tags: 5599 5600 @itemize 5601 @item 5602 @samp{GTD} 5603 @itemize 5604 @item 5605 @samp{Persp} 5606 @itemize 5607 @item 5608 @samp{Vision} 5609 @item 5610 @samp{Goal} 5611 @item 5612 @samp{AOF} 5613 @item 5614 @samp{Project} 5615 @end itemize 5616 @item 5617 @samp{Control} 5618 @itemize 5619 @item 5620 @samp{Context} 5621 @item 5622 @samp{Task} 5623 @end itemize 5624 @end itemize 5625 @end itemize 5626 5627 You can use the @code{:startgrouptag}, @code{:grouptags} and @code{:endgrouptag} 5628 keyword directly when setting @code{org-tag-alist} directly: 5629 5630 @lisp 5631 (setq org-tag-alist '((:startgrouptag) 5632 ("GTD") 5633 (:grouptags) 5634 ("Control") 5635 ("Persp") 5636 (:endgrouptag) 5637 (:startgrouptag) 5638 ("Control") 5639 (:grouptags) 5640 ("Context") 5641 ("Task") 5642 (:endgrouptag))) 5643 @end lisp 5644 5645 The tags in a group can be mutually exclusive if using the same group 5646 syntax as is used for grouping mutually exclusive tags together; using 5647 curly brackets. 5648 5649 @example 5650 #+TAGS: @{ Context : @@Home @@Work @@Call @} 5651 @end example 5652 5653 5654 When setting @code{org-tag-alist} you can use @code{:startgroup} and @code{:endgroup} 5655 instead of @code{:startgrouptag} and @code{:endgrouptag} to make the tags 5656 mutually exclusive. 5657 5658 Furthermore, the members of a group tag can also be regular 5659 expressions, creating the possibility of a more dynamic and rule-based 5660 tag structure (see @ref{Regular Expressions}). The regular expressions in 5661 the group must be specified within curly brackets. Here is an 5662 expanded example: 5663 5664 @example 5665 #+TAGS: [ Vision : @{V@@.+@} ] 5666 #+TAGS: [ Goal : @{G@@.+@} ] 5667 #+TAGS: [ AOF : @{AOF@@.+@} ] 5668 #+TAGS: [ Project : @{P@@.+@} ] 5669 @end example 5670 5671 Searching for the tag @samp{Project} now lists all tags also including 5672 regular expression matches for @samp{P@@.+}, and similarly for tag searches 5673 on @samp{Vision}, @samp{Goal} and @samp{AOF}. For example, this would work well for 5674 a project tagged with a common project-identifier, e.g., 5675 @samp{P@@2014_OrgTags}. 5676 5677 @kindex C-c C-x q 5678 @findex org-toggle-tags-groups 5679 @vindex org-group-tags 5680 If you want to ignore group tags temporarily, toggle group tags 5681 support with @code{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. 5682 If you want to disable tag groups completely, set @code{org-group-tags} to 5683 @code{nil}. 5684 5685 @node Tag Searches 5686 @section Tag Searches 5687 5688 @cindex tag searches 5689 @cindex searching for tags 5690 5691 Once a system of tags has been set up, it can be used to collect 5692 related information into special lists. 5693 5694 @table @asis 5695 @item @kbd{C-c / m} or @kbd{C-c \} (@code{org-match-sparse-tree}) 5696 @kindex C-c / m 5697 @kindex C-c \ 5698 @findex org-match-sparse-tree 5699 Create a sparse tree with all headlines matching a tags search. 5700 With a @kbd{C-u} prefix argument, ignore headlines that are not 5701 a TODO line. 5702 5703 @item @kbd{M-x org-agenda m} (@code{org-tags-view}) 5704 @kindex m @r{(Agenda dispatcher)} 5705 @findex org-tags-view 5706 Create a global list of tag matches from all agenda files. See 5707 @ref{Matching tags and properties}. 5708 5709 @item @kbd{M-x org-agenda M} (@code{org-tags-view}) 5710 @kindex M @r{(Agenda dispatcher)} 5711 @vindex org-tags-match-list-sublevels 5712 Create a global list of tag matches from all agenda files, but check 5713 only TODO items and force checking subitems (see the option 5714 @code{org-tags-match-list-sublevels}). 5715 @end table 5716 5717 These commands all prompt for a match string which allows basic 5718 Boolean logic like @samp{+boss+urgent-project1}, to find entries with tags 5719 @samp{boss} and @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find 5720 entries which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of 5721 the search string is rich and allows also matching against TODO 5722 keywords, entry levels and properties. For a complete description 5723 with many examples, see @ref{Matching tags and properties}. 5724 5725 @node Properties and Columns 5726 @chapter Properties and Columns 5727 5728 @cindex properties 5729 5730 A property is a key-value pair associated with an entry. Properties 5731 can be set so they are associated with a single entry, with every 5732 entry in a tree, or with the whole buffer. 5733 5734 There are two main applications for properties in Org mode. First, 5735 properties are like tags, but with a value. Imagine maintaining 5736 a file where you document bugs and plan releases for a piece of 5737 software. Instead of using tags like @samp{release_1}, @samp{release_2}, you 5738 can use a property, say @samp{Release}, that in different subtrees has 5739 different values, such as @samp{1.0} or @samp{2.0}. Second, you can use 5740 properties to implement (very basic) database capabilities in an Org 5741 buffer. Imagine keeping track of your music CDs, where properties 5742 could be things such as the album, artist, date of release, number of 5743 tracks, and so on. 5744 5745 Properties can be conveniently edited and viewed in column view (see 5746 @ref{Column View}). 5747 5748 @menu 5749 * Property Syntax:: How properties are spelled out. 5750 * Special Properties:: Access to other Org mode features. 5751 * Property Searches:: Matching property values. 5752 * Property Inheritance:: Passing values down a tree. 5753 * Column View:: Tabular viewing and editing. 5754 @end menu 5755 5756 @node Property Syntax 5757 @section Property Syntax 5758 5759 @cindex property syntax 5760 @cindex drawer, for properties 5761 5762 Properties are key--value pairs. When they are associated with 5763 a single entry or with a tree they need to be inserted into a special 5764 drawer (see @ref{Drawers}) with the name @samp{PROPERTIES}, which has to be 5765 located right below a headline, and its planning line (see @ref{Deadlines and Scheduling}) when applicable. Each property is specified on 5766 a single line, with the key---surrounded by colons---first, and the 5767 value after it. Keys are case-insensitive. Here is an example: 5768 5769 @example 5770 * CD collection 5771 ** Classic 5772 *** Goldberg Variations 5773 :PROPERTIES: 5774 :Title: Goldberg Variations 5775 :Composer: J.S. Bach 5776 :Artist: Glenn Gould 5777 :Publisher: Deutsche Grammophon 5778 :NDisks: 1 5779 :END: 5780 @end example 5781 5782 Depending on the value of @code{org-use-property-inheritance}, a property 5783 set this way is associated either with a single entry, or with the 5784 subtree defined by the entry, see @ref{Property Inheritance}. 5785 5786 You may define the allowed values for a particular property @samp{Xyz} by 5787 setting a property @samp{Xyz_ALL}. This special property is @emph{inherited}, 5788 so if you set it in a level 1 entry, it applies to the entire tree. 5789 When allowed values are defined, setting the corresponding property 5790 becomes easier and is less prone to typing errors. For the example 5791 with the CD collection, we can pre-define publishers and the number of 5792 disks in a box like this: 5793 5794 @example 5795 * CD collection 5796 :PROPERTIES: 5797 :NDisks_ALL: 1 2 3 4 5798 :Publisher_ALL: "Deutsche Grammophon" Philips EMI 5799 :END: 5800 @end example 5801 5802 Properties can be inserted on buffer level. That means they apply 5803 before the first headline and can be inherited by all entries in a 5804 file. Property blocks defined before first headline needs to be 5805 located at the top of the buffer, allowing only comments above. 5806 5807 Properties can also be defined using lines like: 5808 5809 @cindex @samp{_ALL} suffix, in properties 5810 @cindex @samp{PROPERTY}, keyword 5811 @example 5812 #+PROPERTY: NDisks_ALL 1 2 3 4 5813 @end example 5814 5815 5816 @cindex @samp{+} suffix, in properties 5817 If you want to add to the value of an existing property, append a @samp{+} 5818 to the property name. The following results in the property @samp{var} 5819 having the value @samp{foo=1 bar=2}. 5820 5821 @example 5822 #+PROPERTY: var foo=1 5823 #+PROPERTY: var+ bar=2 5824 @end example 5825 5826 It is also possible to add to the values of inherited properties. The 5827 following results in the @samp{Genres} property having the value @samp{Classic 5828 Baroque} under the @samp{Goldberg Variations} subtree. 5829 5830 @example 5831 * CD collection 5832 ** Classic 5833 :PROPERTIES: 5834 :Genres: Classic 5835 :END: 5836 *** Goldberg Variations 5837 :PROPERTIES: 5838 :Title: Goldberg Variations 5839 :Composer: J.S. Bach 5840 :Artist: Glenn Gould 5841 :Publisher: Deutsche Grammophon 5842 :NDisks: 1 5843 :Genres+: Baroque 5844 :END: 5845 @end example 5846 5847 Note that a property can only have one entry per drawer. 5848 5849 @vindex org-global-properties 5850 Property values set with the global variable @code{org-global-properties} 5851 can be inherited by all entries in all Org files. 5852 5853 The following commands help to work with properties: 5854 5855 @table @asis 5856 @item @kbd{M-@key{TAB}} (@code{pcomplete}) 5857 @kindex M-TAB 5858 @findex pcomplete 5859 After an initial colon in a line, complete property keys. All keys 5860 used in the current file are offered as possible completions. 5861 5862 @item @kbd{C-c C-x p} (@code{org-set-property}) 5863 @kindex C-c C-x p 5864 @findex org-set-property 5865 Set a property. This prompts for a property name and a value. If 5866 necessary, the property drawer is created as well. 5867 5868 @item @kbd{C-u M-x org-insert-drawer} 5869 @findex org-insert-drawer 5870 Insert a property drawer into the current entry. The drawer is 5871 inserted early in the entry, but after the lines with planning 5872 information like deadlines. If before first headline the drawer is 5873 inserted at the top of the drawer after any potential comments. 5874 5875 @item @kbd{C-c C-c} (@code{org-property-action}) 5876 @kindex C-c C-c 5877 @findex org-property-action 5878 With point in a property drawer, this executes property commands. 5879 5880 @item @kbd{C-c C-c s} (@code{org-set-property}) 5881 @kindex C-c C-c s 5882 @findex org-set-property 5883 Set a property in the current entry. Both the property and the 5884 value can be inserted using completion. 5885 5886 @item @kbd{S-@key{RIGHT}} (@code{org-property-next-allowed-values}) 5887 @itemx @kbd{S-@key{LEFT}} (@code{org-property-previous-allowed-value}) 5888 @kindex S-RIGHT 5889 @kindex S-LEFT 5890 Switch property at point to the next/previous allowed value. 5891 5892 @item @kbd{C-c C-c d} (@code{org-delete-property}) 5893 @kindex C-c C-c d 5894 @findex org-delete-property 5895 Remove a property from the current entry. 5896 5897 @item @kbd{C-c C-c D} (@code{org-delete-property-globally}) 5898 @kindex C-c C-c D 5899 @findex org-delete-property-globally 5900 Globally remove a property, from all entries in the current file. 5901 5902 @item @kbd{C-c C-c c} (@code{org-compute-property-at-point}) 5903 @kindex C-c C-c c 5904 @findex org-compute-property-at-point 5905 Compute the property at point, using the operator and scope from the 5906 nearest column format definition. 5907 @end table 5908 5909 @node Special Properties 5910 @section Special Properties 5911 5912 @cindex properties, special 5913 5914 Special properties provide an alternative access method to Org mode 5915 features, like the TODO state or the priority of an entry, discussed 5916 in the previous chapters. This interface exists so that you can 5917 include these states in a column view (see @ref{Column View}), or to use 5918 them in queries. The following property names are special and should 5919 not be used as keys in the properties drawer: 5920 5921 @cindex @samp{ALLTAGS}, special property 5922 @cindex @samp{BLOCKED}, special property 5923 @cindex @samp{CLOCKSUM}, special property 5924 @cindex @samp{CLOCKSUM_T}, special property 5925 @cindex @samp{CLOSED}, special property 5926 @cindex @samp{DEADLINE}, special property 5927 @cindex @samp{FILE}, special property 5928 @cindex @samp{ITEM}, special property 5929 @cindex @samp{PRIORITY}, special property 5930 @cindex @samp{SCHEDULED}, special property 5931 @cindex @samp{TAGS}, special property 5932 @cindex @samp{TIMESTAMP}, special property 5933 @cindex @samp{TIMESTAMP_IA}, special property 5934 @cindex @samp{TODO}, special property 5935 @multitable {aaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 5936 @item @samp{ALLTAGS} 5937 @tab All tags, including inherited ones. 5938 @item @samp{BLOCKED} 5939 @tab @code{t} if task is currently blocked by children or siblings. 5940 @item @samp{CATEGORY} 5941 @tab The category of an entry. 5942 @item @samp{CLOCKSUM} 5943 @tab The sum of CLOCK intervals in the subtree. @code{org-clock-sum} 5944 @item 5945 @tab must be run first to compute the values in the current buffer. 5946 @item @samp{CLOCKSUM_T} 5947 @tab The sum of CLOCK intervals in the subtree for today. 5948 @item 5949 @tab @code{org-clock-sum-today} must be run first to compute the 5950 @item 5951 @tab values in the current buffer. 5952 @item @samp{CLOSED} 5953 @tab When was this entry closed? 5954 @item @samp{DEADLINE} 5955 @tab The deadline timestamp. 5956 @item @samp{FILE} 5957 @tab The filename the entry is located in. 5958 @item @samp{ITEM} 5959 @tab The headline of the entry. 5960 @item @samp{PRIORITY} 5961 @tab The priority of the entry, a string with a single letter. 5962 @item @samp{SCHEDULED} 5963 @tab The scheduling timestamp. 5964 @item @samp{TAGS} 5965 @tab The tags defined directly in the headline. 5966 @item @samp{TIMESTAMP} 5967 @tab The first keyword-less timestamp in the entry. 5968 @item @samp{TIMESTAMP_IA} 5969 @tab The first inactive timestamp in the entry. 5970 @item @samp{TODO} 5971 @tab The TODO keyword of the entry. 5972 @end multitable 5973 5974 @node Property Searches 5975 @section Property Searches 5976 5977 @cindex properties, searching 5978 @cindex searching, of properties 5979 5980 To create sparse trees and special lists with selection based on 5981 properties, the same commands are used as for tag searches (see @ref{Tag Searches}). 5982 5983 @table @asis 5984 @item @kbd{C-c / m} or @kbd{C-c \} (@code{org-match-sparse-tree}) 5985 @kindex C-c / m 5986 @kindex C-c \ 5987 @findex org-match-sparse-tree 5988 Create a sparse tree with all matching entries. With 5989 a @kbd{C-u} prefix argument, ignore headlines that are not 5990 a TODO line. 5991 5992 @item @kbd{M-x org-agenda m} (@code{org-tags-view}) 5993 @kindex m @r{(Agenda dispatcher)} 5994 @findex org-tags-view 5995 Create a global list of tag/property matches from all agenda files. 5996 5997 @item @kbd{M-x org-agenda M} (@code{org-tags-view}) 5998 @kindex M @r{(Agenda dispatcher)} 5999 @vindex org-tags-match-list-sublevels 6000 Create a global list of tag matches from all agenda files, but check 6001 only TODO items and force checking of subitems (see the option 6002 @code{org-tags-match-list-sublevels}). 6003 @end table 6004 6005 The syntax for the search string is described in @ref{Matching tags and properties}. 6006 6007 There is also a special command for creating sparse trees based on a 6008 single property: 6009 6010 @table @asis 6011 @item @kbd{C-c / p} 6012 @kindex C-c / p 6013 Create a sparse tree based on the value of a property. This first 6014 prompts for the name of a property, and then for a value. A sparse 6015 tree is created with all entries that define this property with the 6016 given value. If you enclose the value in curly braces, it is 6017 interpreted as a regular expression and matched against the property 6018 values (see @ref{Regular Expressions}). 6019 @end table 6020 6021 @node Property Inheritance 6022 @section Property Inheritance 6023 6024 @cindex properties, inheritance 6025 @cindex inheritance, of properties 6026 6027 @vindex org-use-property-inheritance 6028 The outline structure of Org documents lends itself to an inheritance 6029 model of properties: if the parent in a tree has a certain property, 6030 the children can inherit this property. Org mode does not turn this 6031 on by default, because it can slow down property searches 6032 significantly and is often not needed. However, if you find 6033 inheritance useful, you can turn it on by setting the variable 6034 @code{org-use-property-inheritance}. It may be set to @code{t} to make all 6035 properties inherited from the parent, to a list of properties that 6036 should be inherited, or to a regular expression that matches inherited 6037 properties. If a property has the value @code{nil}, this is interpreted as 6038 an explicit un-define of the property, so that inheritance search 6039 stops at this value and returns @code{nil}. 6040 6041 Org mode has a few properties for which inheritance is hard-coded, at 6042 least for the special applications for which they are used: 6043 6044 @table @asis 6045 @item @code{COLUMNS} 6046 @cindex @samp{COLUMNS}, property 6047 The @samp{COLUMNS} property defines the format of column view (see 6048 @ref{Column View}). It is inherited in the sense that the level where 6049 a @samp{COLUMNS} property is defined is used as the starting point for 6050 a column view table, independently of the location in the subtree 6051 from where columns view is turned on. 6052 6053 @item @code{CATEGORY} 6054 @cindex @samp{CATEGORY}, property 6055 For agenda view, a category set through a @samp{CATEGORY} property 6056 applies to the entire subtree. 6057 6058 @item @code{ARCHIVE} 6059 @cindex @samp{ARCHIVE}, property 6060 For archiving, the @samp{ARCHIVE} property may define the archive 6061 location for the entire subtree (see @ref{Moving subtrees}). 6062 6063 @item @code{LOGGING} 6064 @cindex @samp{LOGGING}, property 6065 The @samp{LOGGING} property may define logging settings for an entry or 6066 a subtree (see @ref{Tracking TODO state changes}). 6067 @end table 6068 6069 @node Column View 6070 @section Column View 6071 6072 A great way to view and edit properties in an outline tree is @emph{column 6073 view}. In column view, each outline node is turned into a table row. 6074 Columns in this table provide access to properties of the entries. 6075 Org mode implements columns by overlaying a tabular structure over the 6076 headline of each item. While the headlines have been turned into 6077 a table row, you can still change the visibility of the outline tree. 6078 For example, you get a compact table by switching to ``contents'' 6079 view---@kbd{S-@key{TAB}} @kbd{S-@key{TAB}}, or simply @kbd{c} 6080 while column view is active---but you can still open, read, and edit 6081 the entry below each headline. Or, you can switch to column view 6082 after executing a sparse tree command and in this way get a table only 6083 for the selected items. Column view also works in agenda buffers (see 6084 @ref{Agenda Views}) where queries have collected selected items, possibly 6085 from a number of files. 6086 6087 @menu 6088 * Defining columns:: The COLUMNS format property. 6089 * Using column view:: How to create and use column view. 6090 * Capturing column view:: A dynamic block for column view. 6091 @end menu 6092 6093 @node Defining columns 6094 @subsection Defining columns 6095 6096 @cindex column view, for properties 6097 @cindex properties, column view 6098 6099 Setting up a column view first requires defining the columns. This is 6100 done by defining a column format line. 6101 6102 @menu 6103 * Scope of column definitions:: Where defined, where valid? 6104 * Column attributes:: Appearance and content of a column. 6105 @end menu 6106 6107 @node Scope of column definitions 6108 @subsubsection Scope of column definitions 6109 6110 To specify a format that only applies to a specific tree, add 6111 a @samp{COLUMNS} property to the top node of that tree, for example: 6112 6113 @example 6114 ** Top node for columns view 6115 :PROPERTIES: 6116 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO 6117 :END: 6118 @end example 6119 6120 A @samp{COLUMNS} property within a property drawer before first headline 6121 will apply to the entire file. As an addition to property drawers, 6122 keywords can also be defined for an entire file using a line like: 6123 6124 @cindex @samp{COLUMNS}, keyword 6125 @example 6126 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO 6127 @end example 6128 6129 6130 If a @samp{COLUMNS} property is present in an entry, it defines columns for 6131 the entry itself, and for the entire subtree below it. Since the 6132 column definition is part of the hierarchical structure of the 6133 document, you can define columns on level 1 that are general enough 6134 for all sublevels, and more specific columns further down, when you 6135 edit a deeper part of the tree. 6136 6137 @node Column attributes 6138 @subsubsection Column attributes 6139 6140 A column definition sets the attributes of a column. The general 6141 definition looks like this: 6142 6143 @example 6144 %[WIDTH]PROPERTY[(TITLE)][@{SUMMARY-TYPE@}] 6145 @end example 6146 6147 6148 @noindent 6149 Except for the percent sign and the property name, all items are 6150 optional. The individual parts have the following meaning: 6151 6152 @table @asis 6153 @item @var{WIDTH} 6154 An integer specifying the width of the column in characters. If 6155 omitted, the width is determined automatically. 6156 6157 @item @var{PROPERTY} 6158 The property that should be edited in this column. Special 6159 properties representing meta data are allowed here as well (see 6160 @ref{Special Properties}). 6161 6162 @item @var{TITLE} 6163 The header text for the column. If omitted, the property name is 6164 used. 6165 6166 @item @var{SUMMARY-TYPE} 6167 The summary type. If specified, the column values for parent nodes 6168 are computed from the children@footnote{ If more than one summary type 6169 applies to the same property, the parent values are computed 6170 according to the first of them.}. 6171 6172 Supported summary types are: 6173 6174 @multitable {aaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 6175 @item @samp{+} 6176 @tab Sum numbers in this column. 6177 @item @samp{+;%.1f} 6178 @tab Like @samp{+}, but format result with @samp{%.1f}. 6179 @item @samp{$} 6180 @tab Currency, short for @samp{+;%.2f}. 6181 @item @samp{min} 6182 @tab Smallest number in column. 6183 @item @samp{max} 6184 @tab Largest number. 6185 @item @samp{mean} 6186 @tab Arithmetic mean of numbers. 6187 @item @samp{X} 6188 @tab Checkbox status, @samp{[X]} if all children are @samp{[X]}. 6189 @item @samp{X/} 6190 @tab Checkbox status, @samp{[n/m]}. 6191 @item @samp{X%} 6192 @tab Checkbox status, @samp{[n%]}. 6193 @item @samp{:} 6194 @tab Sum times, HH:MM, plain numbers are minutes. 6195 @item @samp{:min} 6196 @tab Smallest time value in column. 6197 @item @samp{:max} 6198 @tab Largest time value. 6199 @item @samp{:mean} 6200 @tab Arithmetic mean of time values. 6201 @item @samp{@@min} 6202 @tab Minimum age@footnote{An age can be defined as a duration, using units defined in 6203 @code{org-duration-units}, e.g., @samp{3d 1h}. If any value in the column is as 6204 such, the summary is also expressed as a duration.} (in days/hours/mins/seconds). 6205 @item @samp{@@max} 6206 @tab Maximum age (in days/hours/mins/seconds). 6207 @item @samp{@@mean} 6208 @tab Arithmetic mean of ages (in days/hours/mins/seconds). 6209 @item @samp{est+} 6210 @tab Add low-high estimates. 6211 @end multitable 6212 6213 @vindex org-columns-summary-types 6214 You can also define custom summary types by setting 6215 @code{org-columns-summary-types}. 6216 @end table 6217 6218 The @samp{est+} summary type requires further explanation. It is used for 6219 combining estimates, expressed as low-high ranges. For example, 6220 instead of estimating a particular task will take 5 days, you might 6221 estimate it as 5--6 days if you're fairly confident you know how much 6222 work is required, or 1--10 days if you do not really know what needs 6223 to be done. Both ranges average at 5.5 days, but the first represents 6224 a more predictable delivery. 6225 6226 When combining a set of such estimates, simply adding the lows and 6227 highs produces an unrealistically wide result. Instead, @samp{est+} adds 6228 the statistical mean and variance of the subtasks, generating a final 6229 estimate from the sum. For example, suppose you had ten tasks, each 6230 of which was estimated at 0.5 to 2 days of work. Straight addition 6231 produces an estimate of 5 to 20 days, representing what to expect if 6232 everything goes either extremely well or extremely poorly. In 6233 contrast, @samp{est+} estimates the full job more realistically, at 10--15 6234 days. 6235 6236 Here is an example for a complete columns definition, along with 6237 allowed values@footnote{ Please note that the @samp{COLUMNS} definition must be 6238 on a single line; it is wrapped here only because of formatting 6239 constraints.}. 6240 6241 @example 6242 :COLUMNS: %25ITEM %9Approved(Approved?)@{X@} %Owner %11Status \ 6243 %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T 6244 :Owner_ALL: Tammy Mark Karl Lisa Don 6245 :Status_ALL: "In progress" "Not started yet" "Finished" "" 6246 :Approved_ALL: "[ ]" "[X]" 6247 @end example 6248 6249 @noindent 6250 The first column, @samp{%25ITEM}, means the first 25 characters of the item 6251 itself, i.e., of the headline. You probably always should start the 6252 column definition with the @samp{ITEM} specifier. The other specifiers 6253 create columns @samp{Owner} with a list of names as allowed values, for 6254 @samp{Status} with four different possible values, and for a checkbox field 6255 @samp{Approved}. When no width is given after the @samp{%} character, the 6256 column is exactly as wide as it needs to be in order to fully display 6257 all values. The @samp{Approved} column does have a modified title 6258 (@samp{Approved?}, with a question mark). Summaries are created for the 6259 @samp{Time_Estimate} column by adding time duration expressions like HH:MM, 6260 and for the @samp{Approved} column, by providing an @samp{[X]} status if all 6261 children have been checked. The @samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns 6262 are special, they lists the sums of CLOCK intervals in the subtree, 6263 either for all clocks or just for today. 6264 6265 @node Using column view 6266 @subsection Using column view 6267 6268 6269 6270 @anchor{Turning column view on or off} 6271 @subsubheading Turning column view on or off 6272 6273 @table @asis 6274 @item @kbd{C-c C-x C-c} (@code{org-columns}) 6275 @kindex C-c C-x C-c 6276 @vindex org-columns 6277 @vindex org-columns-default-format 6278 Turn on column view. If point is before the first headline in the 6279 file, column view is turned on for the entire file, using the 6280 @samp{#+COLUMNS} definition. If point is somewhere inside the outline, 6281 this command searches the hierarchy, up from point, for a @samp{COLUMNS} 6282 property that defines a format. When one is found, the column view 6283 table is established for the tree starting at the entry that 6284 contains the @samp{COLUMNS} property. If no such property is found, the 6285 format is taken from the @samp{#+COLUMNS} line or from the variable 6286 @code{org-columns-default-format}, and column view is established for the 6287 current entry and its subtree. 6288 6289 @item @kbd{r} or @kbd{g} on a columns view line (@code{org-columns-redo}) 6290 @kindex r 6291 @kindex g 6292 @findex org-columns-redo 6293 Recreate the column view, to include recent changes made in the 6294 buffer. 6295 6296 @item @kbd{C-c C-c} or @kbd{q} on a columns view line (@code{org-columns-quit}) 6297 @kindex q 6298 @kindex C-c C-c 6299 @findex org-columns-quit 6300 Exit column view. 6301 @end table 6302 6303 @anchor{Editing values} 6304 @subsubheading Editing values 6305 6306 @table @asis 6307 @item @kbd{@key{LEFT}}, @kbd{@key{RIGHT}}, @kbd{@key{UP}}, @kbd{@key{DOWN}} 6308 Move through the column view from field to field. 6309 6310 @item @kbd{1..9,0} 6311 @kindex 1..9,0 6312 Directly select the Nth allowed value, @kbd{0} selects the 6313 10th value. 6314 6315 @item @kbd{n} or @kbd{S-@key{RIGHT}} (@code{org-columns-next-allowed-value}) 6316 @itemx @kbd{p} or @kbd{S-@key{LEFT}} (@code{org-columns-previous-allowed-value}) 6317 @kindex n 6318 @kindex S-RIGHT 6319 @kindex p 6320 @kindex S-LEFT 6321 @findex org-columns-next-allowed-value 6322 @findex org-columns-previous-allowed-value 6323 Switch to the next/previous allowed value of the field. For this, 6324 you have to have specified allowed values for a property. 6325 6326 @item @kbd{e} (@code{org-columns-edit-value}) 6327 @kindex e 6328 @findex org-columns-edit-value 6329 Edit the property at point. For the special properties, this 6330 invokes the same interface that you normally use to change that 6331 property. For example, the tag completion or fast selection 6332 interface pops up when editing a @samp{TAGS} property. 6333 6334 @item @kbd{C-c C-c} (@code{org-columns-toggle-or-columns-quit}) 6335 @kindex C-c C-c 6336 @findex org-columns-toggle-or-columns-quit 6337 When there is a checkbox at point, toggle it. Else exit column 6338 view. 6339 6340 @item @kbd{v} (@code{org-columns-show-value}) 6341 @kindex v 6342 @findex org-columns-show-value 6343 View the full value of this property. This is useful if the width 6344 of the column is smaller than that of the value. 6345 6346 @item @kbd{a} (@code{org-columns-edit-allowed}) 6347 @kindex a 6348 @findex org-columns-edit-allowed 6349 Edit the list of allowed values for this property. If the list is 6350 found in the hierarchy, the modified values is stored there. If no 6351 list is found, the new value is stored in the first entry that is 6352 part of the current column view. 6353 @end table 6354 6355 @anchor{Modifying column view on-the-fly} 6356 @subsubheading Modifying column view on-the-fly 6357 6358 @table @asis 6359 @item @kbd{<} (@code{org-columns-narrow}) 6360 @itemx @kbd{>} (@code{org-columns-widen}) 6361 @kindex < 6362 @kindex > 6363 @findex org-columns-narrow 6364 @findex org-columns-widen 6365 Make the column narrower/wider by one character. 6366 6367 @item @kbd{S-M-@key{RIGHT}} (@code{org-columns-new}) 6368 @kindex S-M-RIGHT 6369 @findex org-columns-new 6370 Insert a new column, to the left of the current column. 6371 6372 @item @kbd{S-M-@key{LEFT}} (@code{org-columns-delete}) 6373 @kindex S-M-LEFT 6374 @findex org-columns-delete 6375 Delete the current column. 6376 @end table 6377 6378 @node Capturing column view 6379 @subsection Capturing column view 6380 6381 Since column view is just an overlay over a buffer, it cannot be 6382 exported or printed directly. If you want to capture a column view, 6383 use a @samp{columnview} dynamic block (see @ref{Dynamic Blocks}). The frame of 6384 this block looks like this: 6385 6386 @cindex @samp{BEGIN columnview} 6387 @example 6388 * The column view 6389 #+BEGIN: columnview :hlines 1 :id "label" 6390 6391 #+END: 6392 @end example 6393 6394 This dynamic block has the following parameters: 6395 6396 @table @asis 6397 @item @samp{:id} 6398 This is the most important parameter. Column view is a feature that 6399 is often localized to a certain (sub)tree, and the capture block 6400 might be at a different location in the file. To identify the tree 6401 whose view to capture, you can use four values: 6402 6403 @table @asis 6404 @item @samp{local} 6405 Use the tree in which the capture block is located. 6406 6407 @item @samp{global} 6408 Make a global view, including all headings in the file. 6409 6410 @item @samp{file:FILENAME} 6411 Run column view at the top of the @var{FILENAME} file. 6412 6413 @item @samp{LABEL} 6414 @cindex @samp{ID}, property 6415 Call column view in the tree that has an @samp{ID} property with the 6416 value @var{LABEL}. You can use @kbd{M-x org-id-copy} to 6417 create a globally unique ID for the current entry and copy it to 6418 the kill-ring. 6419 @end table 6420 6421 @item @samp{:match} 6422 When set to a string, use this as a tags/property match filter to 6423 select only a subset of the headlines in the scope set by the @code{:id} 6424 parameter. 6425 @end table 6426 6427 6428 @table @asis 6429 @item @samp{:hlines} 6430 When @code{t}, insert an hline after every line. When a number N, insert 6431 an hline before each headline with level @code{<= N}. 6432 6433 @item @samp{:vlines} 6434 When non-@code{nil}, force column groups to get vertical lines. 6435 6436 @item @samp{:maxlevel} 6437 When set to a number, do not capture entries below this level. 6438 6439 @item @samp{:skip-empty-rows} 6440 When non-@code{nil}, skip rows where the only non-empty specifier of 6441 the column view is @samp{ITEM}. 6442 6443 @item @samp{:exclude-tags} 6444 List of tags to exclude from column view table: entries with these 6445 tags will be excluded from the column view. 6446 6447 @item @samp{:indent} 6448 When non-@code{nil}, indent each @samp{ITEM} field according to its level. 6449 6450 @item @samp{:format} 6451 Specify a column attribute (see @ref{Column attributes}) for the dynamic 6452 block. 6453 @end table 6454 6455 The following commands insert or update the dynamic block: 6456 6457 @table @asis 6458 @item @code{org-columns-insert-dblock} 6459 @kindex C-c C-x x 6460 @findex org-columns-insert-dblock 6461 Insert a dynamic block capturing a column view. Prompt for the 6462 scope or ID of the view. 6463 6464 This command can be invoked by calling 6465 @code{org-dynamic-block-insert-dblock} (@kbd{C-c C-x x}) and 6466 selecting ``columnview'' (see @ref{Dynamic Blocks}). 6467 6468 @item @kbd{C-c C-c} @kbd{C-c C-x C-u} (@code{org-dblock-update}) 6469 @kindex C-c C-c 6470 @kindex C-c C-x C-u 6471 @findex org-dblock-update 6472 Update dynamic block at point. point needs to be in the @samp{#+BEGIN} 6473 line of the dynamic block. 6474 6475 @item @kbd{C-u C-c C-x C-u} (@code{org-update-all-dblocks}) 6476 @kindex C-u C-c C-x C-u 6477 Update all dynamic blocks (see @ref{Dynamic Blocks}). This is useful if 6478 you have several clock table blocks, column-capturing blocks or 6479 other dynamic blocks in a buffer. 6480 @end table 6481 6482 You can add formulas to the column view table and you may add plotting 6483 instructions in front of the table---these survive an update of the 6484 block. If there is a @samp{TBLFM} keyword after the table, the table is 6485 recalculated automatically after an update. 6486 6487 An alternative way to capture and process property values into a table 6488 is provided by Eric Schulte's @samp{org-collector.el}, which is a package 6489 in @samp{org-contrib}@footnote{ Contributed packages are not part of Emacs, but 6490 are distributed with the main distribution of Org---visit 6491 @uref{https://orgmode.org}.}. It provides a general API to collect 6492 properties from entries in a certain scope, and arbitrary Lisp 6493 expressions to process these values before inserting them into a table 6494 or a dynamic block. 6495 6496 @node Dates and Times 6497 @chapter Dates and Times 6498 6499 @cindex dates 6500 @cindex times 6501 @cindex timestamp 6502 @cindex date stamp 6503 6504 To assist project planning, TODO items can be labeled with a date 6505 and/or a time. The specially formatted string carrying the date and 6506 time information is called a @emph{timestamp} in Org mode. This may be 6507 a little confusing because timestamp is often used as indicating when 6508 something was created or last changed. However, in Org mode this term 6509 is used in a much wider sense. 6510 6511 @menu 6512 * Timestamps:: Assigning a time to a tree entry. 6513 * Creating Timestamps:: Commands to insert timestamps. 6514 * Deadlines and Scheduling:: Planning your work. 6515 * Clocking Work Time:: Tracking how long you spend on a task. 6516 * Effort Estimates:: Planning work effort in advance. 6517 * Timers:: Notes with a running timer. 6518 @end menu 6519 6520 @node Timestamps 6521 @section Timestamps 6522 6523 @cindex timestamps 6524 @cindex ranges, time 6525 @cindex date stamps 6526 @cindex deadlines 6527 @cindex scheduling 6528 6529 A timestamp is a specification of a date (possibly with a time or 6530 a range of times) in a special format, either @samp{<2003-09-16 Tue>} or 6531 @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue 12:00-12:30>}@footnote{The Org date format is inspired by the standard ISO 8601 6532 date/time format. To use an alternative format, see @ref{Custom time format}. The day name is optional when you type the date yourself. 6533 However, any date inserted or modified by Org adds that day name, for 6534 reading convenience.}. 6535 A timestamp can appear anywhere in the headline or body of an Org tree 6536 entry. Its presence causes entries to be shown on specific dates in 6537 the agenda (see @ref{Weekly/daily agenda}). We distinguish: 6538 6539 @table @asis 6540 @item Plain timestamp; Event; Appointment 6541 @cindex timestamp 6542 @cindex appointment 6543 A simple timestamp just assigns a date/time to an item. This is 6544 just like writing down an appointment or event in a paper agenda. 6545 In the agenda display, the headline of an entry associated with 6546 a plain timestamp is shown exactly on that date. 6547 6548 @example 6549 * Meet Peter at the movies 6550 <2006-11-01 Wed 19:15> 6551 * Discussion on climate change 6552 <2006-11-02 Thu 20:00-22:00> 6553 @end example 6554 6555 @item Timestamp with repeater interval 6556 @cindex timestamp, with repeater interval 6557 A timestamp may contain a @emph{repeater interval}, indicating that it 6558 applies not only on the given date, but again and again after 6559 a certain interval of N hours (h), days (d), weeks (w), months (m), 6560 or years (y). The following shows up in the agenda every Wednesday: 6561 6562 @example 6563 * Pick up Sam at school 6564 <2007-05-16 Wed 12:30 +1w> 6565 @end example 6566 6567 @item Diary-style expression entries 6568 @cindex diary style timestamps 6569 @cindex sexp timestamps 6570 6571 @findex org-date 6572 @findex org-anniversary 6573 @findex org-cyclic 6574 @findex org-block 6575 6576 For more complex date specifications, Org mode supports using the 6577 special expression diary entries implemented in the Emacs Calendar 6578 package@footnote{When working with the standard diary expression functions, you 6579 need to be very careful with the order of the arguments. That order 6580 depends evilly on the variable @code{calendar-date-style}. For example, to 6581 specify a date December 1, 2005, the call might look like 6582 @samp{(diary-date 12 1 2005)} or @samp{(diary-date 1 12 2005)} or @samp{(diary-date 6583 2005 12 1)}, depending on the settings. This has been the source of 6584 much confusion. Org mode users can resort to special versions of 6585 these functions, namely @code{org-date}, @code{org-anniversary}, @code{org-cyclic, and 6586 ~org-block}. These work just like the corresponding @code{diary-} 6587 functions, but with stable ISO order of arguments (year, month, day) 6588 wherever applicable, independent of the value of 6589 @code{calendar-date-style}.}. For example, with optional time: 6590 6591 @example 6592 * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month 6593 <%%(diary-float t 4 2)> 6594 @end example 6595 6596 @item Time/Date range 6597 @cindex timerange 6598 @cindex date range 6599 Two timestamps connected by @samp{--} denote a range. The headline is 6600 shown on the first and last day of the range, and on any dates that 6601 are displayed and fall in the range. Here is an example: 6602 6603 @example 6604 ** Meeting in Amsterdam 6605 <2004-08-23 Mon>--<2004-08-26 Thu> 6606 @end example 6607 6608 @item Inactive timestamp 6609 @cindex timestamp, inactive 6610 @cindex inactive timestamp 6611 Just like a plain timestamp, but with square brackets instead of 6612 angular ones. These timestamps are inactive in the sense that they 6613 do @emph{not} trigger an entry to show up in the agenda. 6614 6615 @example 6616 * Gillian comes late for the fifth time 6617 [2006-11-01 Wed] 6618 @end example 6619 @end table 6620 6621 @node Creating Timestamps 6622 @section Creating Timestamps 6623 6624 For Org mode to recognize timestamps, they need to be in the specific 6625 format. All commands listed below produce timestamps in the correct 6626 format. 6627 6628 @table @asis 6629 @item @kbd{C-c .} (@code{org-time-stamp}) 6630 @kindex C-c . 6631 @findex org-time-stamp 6632 Prompt for a date and insert a corresponding timestamp. When point 6633 is at an existing timestamp in the buffer, the command is used to 6634 modify this timestamp instead of inserting a new one. When this 6635 command is used twice in succession, a time range is inserted. 6636 6637 @kindex C-u C-c . 6638 @vindex org-time-stamp-rounding-minutes 6639 When called with a prefix argument, use the alternative format which 6640 contains date and time. The default time can be rounded to 6641 multiples of 5 minutes. See the option 6642 @code{org-time-stamp-rounding-minutes}. 6643 6644 @kindex C-u C-u C-c . 6645 With two prefix arguments, insert an active timestamp with the 6646 current time without prompting. 6647 6648 @item @kbd{C-c !} (@code{org-time-stamp-inactive}) 6649 @kindex C-c ! 6650 @kindex C-u C-c ! 6651 @kindex C-u C-u C-c ! 6652 @findex org-time-stamp-inactive 6653 Like @kbd{C-c .}, but insert an inactive timestamp that does 6654 not cause an agenda entry. 6655 6656 @item @kbd{C-c C-c} 6657 @kindex C-c C-c 6658 Normalize timestamp, insert or fix day name if missing or wrong. 6659 6660 @item @kbd{C-c <} (@code{org-date-from-calendar}) 6661 @kindex C-c < 6662 @findex org-date-from-calendar 6663 Insert a timestamp corresponding to point date in the calendar. 6664 6665 @item @kbd{C-c >} (@code{org-goto-calendar}) 6666 @kindex C-c > 6667 @findex org-goto-calendar 6668 Access the Emacs calendar for the current date. If there is 6669 a timestamp in the current line, go to the corresponding date 6670 instead. 6671 6672 @item @kbd{C-c C-o} (@code{org-open-at-point}) 6673 @kindex C-c C-o 6674 @findex org-open-at-point 6675 Access the agenda for the date given by the timestamp or -range at 6676 point (see @ref{Weekly/daily agenda}). 6677 6678 @item @kbd{S-@key{LEFT}} (@code{org-timestamp-down-day}) 6679 @itemx @kbd{S-@key{RIGHT}} (@code{org-timestamp-up-day}) 6680 @kindex S-LEFT 6681 @kindex S-RIGHT 6682 @findex org-timestamp-down-day 6683 @findex org-timestamp-up-day 6684 Change date at point by one day. These key bindings conflict with 6685 shift-selection and related modes (see @ref{Conflicts}). 6686 6687 @item @kbd{S-@key{UP}} (@code{org-timestamp-up}) 6688 @itemx @kbd{S-@key{DOWN}} (@code{org-timestamp-down}) 6689 @kindex S-UP 6690 @kindex S-DOWN 6691 On the beginning or enclosing bracket of a timestamp, change its 6692 type. Within a timestamp, change the item under point. Point can 6693 be on a year, month, day, hour or minute. When the timestamp 6694 contains a time range like @samp{15:30-16:30}, modifying the first time 6695 also shifts the second, shifting the time block with constant 6696 length. To change the length, modify the second time. Note that if 6697 point is in a headline and not at a timestamp, these same keys 6698 modify the priority of an item (see @ref{Priorities}). The key bindings 6699 also conflict with shift-selection and related modes (see @ref{Conflicts}). 6700 6701 @item @kbd{C-c C-y} (@code{org-evaluate-time-range}) 6702 @kindex C-c C-y 6703 @findex org-evaluate-time-range 6704 @cindex evaluate time range 6705 Evaluate a time range by computing the difference between start and 6706 end. With a prefix argument, insert result after the time range (in 6707 a table: into the following column). 6708 @end table 6709 6710 @menu 6711 * The date/time prompt:: How Org mode helps you enter dates and times. 6712 * Custom time format:: Making dates look different. 6713 @end menu 6714 6715 @node The date/time prompt 6716 @subsection The date/time prompt 6717 6718 @cindex date, reading in minibuffer 6719 @cindex time, reading in minibuffer 6720 6721 @vindex org-read-date-prefer-future 6722 When Org mode prompts for a date/time, the default is shown in default 6723 date/time format, and the prompt therefore seems to ask for a specific 6724 format. But it in fact accepts date/time information in a variety of 6725 formats. Generally, the information should start at the beginning of 6726 the string. Org mode finds whatever information is in there and 6727 derives anything you have not specified from the @emph{default date and 6728 time}. The default is usually the current date and time, but when 6729 modifying an existing timestamp, or when entering the second stamp of 6730 a range, it is taken from the stamp in the buffer. When filling in 6731 information, Org mode assumes that most of the time you want to enter 6732 a date in the future: if you omit the month/year and the given 6733 day/month is @emph{before} today, it assumes that you mean a future 6734 date@footnote{See the variable @code{org-read-date-prefer-future}. You may set 6735 that variable to the symbol @code{time} to even make a time before now 6736 shift the date to tomorrow.}. If the date has been automatically shifted into the 6737 future, the time prompt shows this with @samp{(=>F)}. 6738 6739 For example, let's assume that today is @strong{June 13, 2006}. Here is how 6740 various inputs are interpreted, the items filled in by Org mode are in 6741 @strong{bold}. 6742 6743 @multitable {aaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 6744 @item @samp{3-2-5} 6745 @tab @result{} 2003-02-05 6746 @item @samp{2/5/3} 6747 @tab @result{} 2003-02-05 6748 @item @samp{14} 6749 @tab @result{} @strong{2006}-@strong{06}-14 6750 @item @samp{12} 6751 @tab @result{} @strong{2006}-@strong{07}-12 6752 @item @samp{2/5} 6753 @tab @result{} @strong{2007}-02-05 6754 @item @samp{Fri} 6755 @tab @result{} nearest Friday (default date or later) 6756 @item @samp{sep 15} 6757 @tab @result{} @strong{2006}-09-15 6758 @item @samp{feb 15} 6759 @tab @result{} @strong{2007}-02-15 6760 @item @samp{sep 12 9} 6761 @tab @result{} 2009-09-12 6762 @item @samp{12:45} 6763 @tab @result{} @strong{2006}-@strong{06}-@strong{13} 12:45 6764 @item @samp{22 sept 0:34} 6765 @tab @result{} @strong{2006}-09-22 0:34 6766 @item @samp{w4} 6767 @tab @result{} ISO week for of the current year @strong{2006} 6768 @item @samp{2012 w4 fri} 6769 @tab @result{} Friday of ISO week 4 in 2012 6770 @item @samp{2012-w04-5} 6771 @tab @result{} Same as above 6772 @end multitable 6773 6774 Furthermore you can specify a relative date by giving, as the @emph{first} 6775 thing in the input: a plus/minus sign, a number and a letter---@samp{h}, 6776 @samp{d}, @samp{w}, @samp{m} or @samp{y}---to indicate a change in hours, days, weeks, 6777 months, or years. With @samp{h} the date is relative to the current time, 6778 with the other letters and a single plus or minus, the date is 6779 relative to today at 00:00. With a double plus or minus, it is 6780 relative to the default date. If instead of a single letter, you use 6781 the abbreviation of day name, the date is the Nth such day, e.g.: 6782 6783 @multitable {aaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 6784 @item @samp{+0} 6785 @tab @result{} today 6786 @item @samp{.} 6787 @tab @result{} today 6788 @item @samp{+2h} 6789 @tab @result{} two hours from now 6790 @item @samp{+4d} 6791 @tab @result{} four days from today 6792 @item @samp{+4} 6793 @tab @result{} same as +4d 6794 @item @samp{+2w} 6795 @tab @result{} two weeks from today 6796 @item @samp{++5} 6797 @tab @result{} five days from default date 6798 @item @samp{+2tue} 6799 @tab @result{} second Tuesday from now 6800 @end multitable 6801 6802 @vindex parse-time-months 6803 @vindex parse-time-weekdays 6804 The function understands English month and weekday abbreviations. If 6805 you want to use un-abbreviated names and/or other languages, configure 6806 the variables @code{parse-time-months} and @code{parse-time-weekdays}. 6807 6808 @vindex org-read-date-force-compatible-dates 6809 Not all dates can be represented in a given Emacs implementation. By 6810 default Org mode forces dates into the compatibility range 1970--2037 6811 which works on all Emacs implementations. If you want to use dates 6812 outside of this range, read the docstring of the variable 6813 @code{org-read-date-force-compatible-dates}. 6814 6815 You can specify a time range by giving start and end times or by 6816 giving a start time and a duration (in HH:MM format). Use one or two 6817 dash(es) as the separator in the former case and use @samp{+} as the 6818 separator in the latter case, e.g.: 6819 6820 @multitable {aaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaa} 6821 @item @samp{11am-1:15pm} 6822 @tab @result{} 11:00-13:15 6823 @item @samp{11h-13h15} 6824 @tab @result{} same as above 6825 @item @samp{11am--1:15pm} 6826 @tab @result{} same as above 6827 @item @samp{11am+2:15} 6828 @tab @result{} same as above 6829 @end multitable 6830 6831 @cindex calendar, for selecting date 6832 @vindex org-popup-calendar-for-date-prompt 6833 Parallel to the minibuffer prompt, a calendar is popped up@footnote{ If you 6834 do not need/want the calendar, configure the variable 6835 @code{org-popup-calendar-for-date-prompt}.}. When you exit the date 6836 prompt, either by clicking on a date in the calendar, or by pressing 6837 @kbd{@key{RET}}, the date selected in the calendar is combined with the 6838 information entered at the prompt. You can control the calendar fully 6839 from the minibuffer: 6840 6841 @kindex < 6842 @kindex > 6843 @kindex M-v 6844 @kindex C-v 6845 @kindex mouse-1 6846 @kindex S-RIGHT 6847 @kindex S-LEFT 6848 @kindex S-DOWN 6849 @kindex S-UP 6850 @kindex M-S-RIGHT 6851 @kindex M-S-LEFT 6852 @kindex RET 6853 @kindex . 6854 @kindex C-. 6855 @multitable @columnfractions 0.25 0.55 6856 @item @kbd{@key{RET}} 6857 @tab Choose date at point in calendar. 6858 @item @kbd{mouse-1} 6859 @tab Select date by clicking on it. 6860 @item @kbd{S-@key{RIGHT}} 6861 @tab One day forward. 6862 @item @kbd{S-@key{LEFT}} 6863 @tab One day backward. 6864 @item @kbd{S-@key{DOWN}} 6865 @tab One week forward. 6866 @item @kbd{S-@key{UP}} 6867 @tab One week backward. 6868 @item @kbd{M-S-@key{RIGHT}} 6869 @tab One month forward. 6870 @item @kbd{M-S-@key{LEFT}} 6871 @tab One month backward. 6872 @item @kbd{>} 6873 @tab Scroll calendar forward by one month. 6874 @item @kbd{<} 6875 @tab Scroll calendar backward by one month. 6876 @item @kbd{M-v} 6877 @tab Scroll calendar forward by 3 months. 6878 @item @kbd{C-v} 6879 @tab Scroll calendar backward by 3 months. 6880 @item @kbd{C-.} 6881 @tab Select today's date@footnote{You can also use the calendar command @kbd{.} to jump to 6882 today's date, but if you are inserting an hour specification for your 6883 timestamp, @kbd{.} will then insert a dot after the hour. By contrast, 6884 @kbd{C-.} will always jump to today's date.} 6885 @end multitable 6886 6887 @vindex org-read-date-display-live 6888 The actions of the date/time prompt may seem complex, but I assure you 6889 they will grow on you, and you will start getting annoyed by pretty 6890 much any other way of entering a date/time out there. To help you 6891 understand what is going on, the current interpretation of your input 6892 is displayed live in the minibuffer@footnote{ If you find this distracting, 6893 turn off the display with @code{org-read-date-display-live}.}. 6894 6895 @node Custom time format 6896 @subsection Custom time format 6897 6898 @cindex custom date/time format 6899 @cindex time format, custom 6900 @cindex date format, custom 6901 6902 @vindex org-display-custom-times 6903 @vindex org-time-stamp-custom-formats 6904 Org mode uses the standard ISO notation for dates and times as it is 6905 defined in ISO 8601. If you cannot get used to this and require 6906 another representation of date and time to keep you happy, you can get 6907 it by customizing the variables @code{org-display-custom-times} and 6908 @code{org-time-stamp-custom-formats}. 6909 6910 @table @asis 6911 @item @kbd{C-c C-x C-t} (@code{org-toggle-time-stamp-overlays}) 6912 @kindex C-c C-x C-t 6913 @findex org-toggle-time-stamp-overlays 6914 Toggle the display of custom formats for dates and times. 6915 @end table 6916 6917 Org mode needs the default format for scanning, so the custom 6918 date/time format does not @emph{replace} the default format. Instead, it 6919 is put @emph{over} the default format using text properties. This has the 6920 following consequences: 6921 6922 @itemize 6923 @item 6924 You cannot place point onto a timestamp anymore, only before or 6925 after. 6926 6927 @item 6928 The @kbd{S-@key{UP}} and @kbd{S-@key{DOWN}} keys can no longer be used 6929 to adjust each component of a timestamp. If point is at the 6930 beginning of the stamp, @kbd{S-@key{UP}} and @kbd{S-@key{DOWN}} change 6931 the stamp by one day, just like @kbd{S-@key{LEFT}} 6932 @kbd{S-@key{RIGHT}}. At the end of the stamp, change the time by one 6933 minute. 6934 6935 @item 6936 If the timestamp contains a range of clock times or a repeater, 6937 these are not overlaid, but remain in the buffer as they were. 6938 6939 @item 6940 When you delete a timestamp character-by-character, it only 6941 disappears from the buffer after @emph{all} (invisible) characters 6942 belonging to the ISO timestamp have been removed. 6943 6944 @item 6945 If the custom timestamp format is longer than the default and you 6946 are using dates in tables, table alignment will be messed up. If 6947 the custom format is shorter, things do work as expected. 6948 @end itemize 6949 6950 @node Deadlines and Scheduling 6951 @section Deadlines and Scheduling 6952 6953 A timestamp may be preceded by special keywords to facilitate 6954 planning. Both the timestamp and the keyword have to be positioned 6955 immediately after the task they refer to. 6956 6957 @table @asis 6958 @item @samp{DEADLINE} 6959 @cindex @samp{DEADLINE} marker 6960 Meaning: the task---most likely a TODO item, though not 6961 necessarily---is supposed to be finished on that date. 6962 6963 @vindex org-deadline-warning-days 6964 On the deadline date, the task is listed in the agenda. In 6965 addition, the agenda for @emph{today} carries a warning about the 6966 approaching or missed deadline, starting @code{org-deadline-warning-days} 6967 before the due date, and continuing until the entry is marked as 6968 done. An example: 6969 6970 @example 6971 *** TODO write article about the Earth for the Guide 6972 DEADLINE: <2004-02-29 Sun> 6973 The editor in charge is [[bbdb:Ford Prefect]] 6974 @end example 6975 6976 @vindex org-agenda-skip-deadline-prewarning-if-scheduled 6977 You can specify a different lead time for warnings for a specific 6978 deadlines using the following syntax. Here is an example with 6979 a warning period of 5 days @samp{DEADLINE: <2004-02-29 Sun -5d>}. This 6980 warning is deactivated if the task gets scheduled and you set 6981 @code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}. 6982 6983 @item @samp{SCHEDULED} 6984 @cindex @samp{SCHEDULED} marker 6985 Meaning: you are planning to start working on that task on the given 6986 date. 6987 6988 @vindex org-agenda-skip-scheduled-if-done 6989 The headline is listed under the given date@footnote{It will still be listed on that date after it has been marked 6990 as done. If you do not like this, set the variable 6991 @code{org-agenda-skip-scheduled-if-done}.}. In addition, 6992 a reminder that the scheduled date has passed is present in the 6993 compilation for @emph{today}, until the entry is marked as done, i.e., 6994 the task is automatically forwarded until completed. 6995 6996 @example 6997 *** TODO Call Trillian for a date on New Years Eve. 6998 SCHEDULED: <2004-12-25 Sat> 6999 @end example 7000 7001 @vindex org-scheduled-delay-days 7002 @vindex org-agenda-skip-scheduled-delay-if-deadline 7003 If you want to @emph{delay} the display of this task in the agenda, use 7004 @samp{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on 7005 the 25th but will appear two days later. In case the task contains 7006 a repeater, the delay is considered to affect all occurrences; if 7007 you want the delay to only affect the first scheduled occurrence of 7008 the task, use @samp{--2d} instead. See @code{org-scheduled-delay-days} and 7009 @code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to 7010 control this globally or per agenda. 7011 7012 @quotation Important 7013 Scheduling an item in Org mode should @emph{not} be understood in the 7014 same way that we understand @emph{scheduling a meeting}. Setting a date 7015 for a meeting is just a simple appointment, you should mark this 7016 entry with a simple plain timestamp, to get this item shown on the 7017 date where it applies. This is a frequent misunderstanding by Org 7018 users. In Org mode, @emph{scheduling} means setting a date when you want 7019 to start working on an action item. 7020 7021 @end quotation 7022 @end table 7023 7024 You may use timestamps with repeaters in scheduling and deadline 7025 entries. Org mode issues early and late warnings based on the 7026 assumption that the timestamp represents the @emph{nearest instance} of the 7027 repeater. However, the use of diary expression entries like 7028 7029 @example 7030 <%%(diary-float t 42)> 7031 @end example 7032 7033 7034 @noindent 7035 in scheduling and deadline timestamps is limited. Org mode does not 7036 know enough about the internals of each function to issue early and 7037 late warnings. However, it shows the item on each day where the 7038 expression entry matches. 7039 7040 @menu 7041 * Inserting deadline/schedule:: Planning items. 7042 * Repeated tasks:: Items that show up again and again. 7043 @end menu 7044 7045 @node Inserting deadline/schedule 7046 @subsection Inserting deadlines or schedules 7047 7048 The following commands allow you to quickly insert a deadline or to 7049 schedule an item:@footnote{The @samp{SCHEDULED} and @samp{DEADLINE} dates are inserted on the line 7050 right below the headline. Do not put any text between this line and 7051 the headline.} 7052 7053 @table @asis 7054 @item @kbd{C-c C-d} (@code{org-deadline}) 7055 @kindex C-c C-d 7056 @findex org-deadline 7057 @vindex org-log-redeadline 7058 Insert @samp{DEADLINE} keyword along with a stamp. The insertion happens 7059 in the line directly following the headline. Remove any @samp{CLOSED} 7060 timestamp . When called with a prefix argument, also remove any 7061 existing deadline from the entry. Depending on the variable 7062 @code{org-log-redeadline}, take a note when changing an existing 7063 deadline@footnote{ Note the corresponding @samp{STARTUP} options 7064 @samp{logredeadline}, @samp{lognoteredeadline}, and @samp{nologredeadline}.}. 7065 7066 @item @kbd{C-c C-s} (@code{org-schedule}) 7067 @kindex C-c C-s 7068 @findex org-schedule 7069 @vindex org-log-reschedule 7070 Insert @samp{SCHEDULED} keyword along with a stamp. The insertion 7071 happens in the line directly following the headline. Remove any 7072 @samp{CLOSED} timestamp. When called with a prefix argument, also remove 7073 the scheduling date from the entry. Depending on the variable 7074 @code{org-log-reschedule}, take a note when changing an existing 7075 scheduling time@footnote{ Note the corresponding @samp{STARTUP} options 7076 @samp{logreschedule}, @samp{lognotereschedule}, and @samp{nologreschedule}.}. 7077 7078 @item @kbd{C-c / d} (@code{org-check-deadlines}) 7079 @kindex C-c / d 7080 @findex org-check-deadlines 7081 @cindex sparse tree, for deadlines 7082 @vindex org-deadline-warning-days 7083 Create a sparse tree with all deadlines that are either past-due, or 7084 which will become due within @code{org-deadline-warning-days}. With 7085 @kbd{C-u} prefix, show all deadlines in the file. With 7086 a numeric prefix, check that many days. For example, @kbd{C-1 C-c / d} shows all deadlines due tomorrow. 7087 7088 @item @kbd{C-c / b} (@code{org-check-before-date}) 7089 @kindex C-c / b 7090 @findex org-check-before-date 7091 Sparse tree for deadlines and scheduled items before a given date. 7092 7093 @item @kbd{C-c / a} (@code{org-check-after-date}) 7094 @kindex C-c / a 7095 @findex org-check-after-date 7096 Sparse tree for deadlines and scheduled items after a given date. 7097 @end table 7098 7099 Note that @code{org-schedule} and @code{org-deadline} supports setting the date 7100 by indicating a relative time e.g., @samp{+1d} sets the date to the next 7101 day after today, and @samp{--1w} sets the date to the previous week before 7102 any current timestamp. 7103 7104 @node Repeated tasks 7105 @subsection Repeated tasks 7106 7107 @cindex tasks, repeated 7108 @cindex repeated tasks 7109 7110 Some tasks need to be repeated again and again. Org mode helps to 7111 organize such tasks using a so-called repeater in a @samp{DEADLINE}, 7112 @samp{SCHEDULED}, or plain timestamps@footnote{Org does not repeat inactive timestamps, however. See 7113 @ref{Timestamps}.}. In the following example: 7114 7115 @example 7116 ** TODO Pay the rent 7117 DEADLINE: <2005-10-01 Sat +1m> 7118 @end example 7119 7120 @noindent 7121 the @samp{+1m} is a repeater; the intended interpretation is that the task 7122 has a deadline on @samp{<2005-10-01>} and repeats itself every (one) month 7123 starting from that time. You can use yearly, monthly, weekly, daily 7124 and hourly repeat cookies by using the @samp{y}, @samp{m}, @samp{w}, @samp{d} and @samp{h} 7125 letters. If you need both a repeater and a special warning period in 7126 a deadline entry, the repeater should come first and the warning 7127 period last 7128 7129 @example 7130 DEADLINE: <2005-10-01 Sat +1m -3d> 7131 @end example 7132 7133 7134 @vindex org-todo-repeat-to-state 7135 Deadlines and scheduled items produce entries in the agenda when they 7136 are over-due, so it is important to be able to mark such an entry as 7137 done once you have done so. When you mark a @samp{DEADLINE} or a 7138 @samp{SCHEDULED} with the TODO keyword @samp{DONE}, it no longer produces 7139 entries in the agenda. The problem with this is, however, is that 7140 then also the @emph{next} instance of the repeated entry will not be 7141 active. Org mode deals with this in the following way: when you try 7142 to mark such an entry as done, using @kbd{C-c C-t}, it shifts the 7143 base date of the repeating timestamp by the repeater interval, and 7144 immediately sets the entry state back to TODO@footnote{ In fact, the target 7145 state is taken from, in this sequence, the @samp{REPEAT_TO_STATE} property, 7146 the variable @code{org-todo-repeat-to-state} if it is a string, the 7147 previous TODO state if @code{org-todo-repeat-to-state} is @code{t}, or the first 7148 state of the TODO state sequence.}. In the example above, setting the 7149 state to @samp{DONE} would actually switch the date like this: 7150 7151 @example 7152 ** TODO Pay the rent 7153 DEADLINE: <2005-11-01 Tue +1m> 7154 @end example 7155 7156 To mark a task with a repeater as DONE, use @kbd{C-- 1 C-c C-t}, 7157 i.e., @code{org-todo} with a numeric prefix argument of @samp{-1}. 7158 7159 @vindex org-log-repeat 7160 A timestamp@footnote{You can change this using the option @code{org-log-repeat}, or the 7161 @samp{STARTUP} options @samp{logrepeat}, @samp{lognoterepeat}, and @samp{nologrepeat}. 7162 With @samp{lognoterepeat}, you will also be prompted for a note.} is added under the deadline, to keep a record that 7163 you actually acted on the previous instance of this deadline. 7164 7165 As a consequence of shifting the base date, this entry is no longer 7166 visible in the agenda when checking past dates, but all future 7167 instances will be visible. 7168 7169 With the @samp{+1m} cookie, the date shift is always exactly one month. So 7170 if you have not paid the rent for three months, marking this entry 7171 DONE still keeps it as an overdue deadline. Depending on the task, 7172 this may not be the best way to handle it. For example, if you forgot 7173 to call your father for 3 weeks, it does not make sense to call him 7174 3 times in a single day to make up for it. Finally, there are tasks, 7175 like changing batteries, which should always repeat a certain time 7176 @emph{after} the last time you did it. For these tasks, Org mode has 7177 special repeaters @samp{++} and @samp{.+}. For example: 7178 7179 @example 7180 ** TODO Call Father 7181 DEADLINE: <2008-02-10 Sun ++1w> 7182 Marking this DONE shifts the date by at least one week, but also 7183 by as many weeks as it takes to get this date into the future. 7184 However, it stays on a Sunday, even if you called and marked it 7185 done on Saturday. 7186 7187 ** TODO Empty kitchen trash 7188 DEADLINE: <2008-02-08 Fri 20:00 ++1d> 7189 Marking this DONE shifts the date by at least one day, and also 7190 by as many days as it takes to get the timestamp into the future. 7191 Since there is a time in the timestamp, the next deadline in the 7192 future will be on today's date if you complete the task before 7193 20:00. 7194 7195 ** TODO Check the batteries in the smoke detectors 7196 DEADLINE: <2005-11-01 Tue .+1m> 7197 Marking this DONE shifts the date to one month after today. 7198 7199 ** TODO Wash my hands 7200 DEADLINE: <2019-04-05 08:00 Fri .+1h> 7201 Marking this DONE shifts the date to exactly one hour from now. 7202 @end example 7203 7204 @vindex org-agenda-skip-scheduled-if-deadline-is-shown 7205 You may have both scheduling and deadline information for a specific 7206 task. If the repeater is set for the scheduling information only, you 7207 probably want the repeater to be ignored after the deadline. If so, 7208 set the variable @code{org-agenda-skip-scheduled-if-deadline-is-shown} to 7209 @code{repeated-after-deadline}. However, any scheduling information 7210 without a repeater is no longer relevant once the task is done, and 7211 thus, removed upon repeating the task. If you want both scheduling 7212 and deadline information to repeat after the same interval, set the 7213 same repeater for both timestamps. 7214 7215 An alternative to using a repeater is to create a number of copies of 7216 a task subtree, with dates shifted in each copy. The command 7217 @kbd{C-c C-x c} was created for this purpose; it is described in 7218 @ref{Structure Editing}. 7219 7220 @node Clocking Work Time 7221 @section Clocking Work Time 7222 7223 @cindex clocking time 7224 @cindex time clocking 7225 7226 Org mode allows you to clock the time you spend on specific tasks in 7227 a project. When you start working on an item, you can start the 7228 clock. When you stop working on that task, or when you mark the task 7229 done, the clock is stopped and the corresponding time interval is 7230 recorded. It also computes the total time spent on each 7231 subtree@footnote{Clocking only works if all headings are indented with less 7232 than 30 stars. This is a hard-coded limitation of @code{lmax} in 7233 @code{org-clock-sum}.} of a project. And it remembers a history or tasks 7234 recently clocked, so that you can jump quickly between a number of 7235 tasks absorbing your time. 7236 7237 To save the clock history across Emacs sessions, use: 7238 7239 @lisp 7240 (setq org-clock-persist 'history) 7241 (org-clock-persistence-insinuate) 7242 @end lisp 7243 7244 @vindex org-clock-persist 7245 When you clock into a new task after resuming Emacs, the incomplete 7246 clock@footnote{ To resume the clock under the assumption that you have 7247 worked on this task while outside Emacs, use @samp{(setq org-clock-persist 7248 t)}.} is retrieved (see @ref{Resolving idle time (1)}) and you are prompted 7249 about what to do with it. 7250 7251 @menu 7252 * Clocking commands:: Starting and stopping a clock. 7253 * The clock table:: Detailed reports. 7254 * Resolving idle time:: Resolving time when you've been idle. 7255 @end menu 7256 7257 @node Clocking commands 7258 @subsection Clocking commands 7259 7260 @table @asis 7261 @item @kbd{C-c C-x C-i} (@code{org-clock-in}) 7262 @kindex C-c C-x C-i 7263 @findex org-clock-in 7264 @vindex org-clock-into-drawer 7265 @vindex org-clock-continuously 7266 @cindex @samp{LOG_INTO_DRAWER}, property 7267 Start the clock on the current item (clock-in). This inserts the 7268 @samp{CLOCK} keyword together with a timestamp. If this is not the first 7269 clocking of this item, the multiple @samp{CLOCK} lines are wrapped into 7270 a @samp{LOGBOOK} drawer (see also the variable @code{org-clock-into-drawer}). 7271 You can also overrule the setting of this variable for a subtree by 7272 setting a @samp{CLOCK_INTO_DRAWER} or @samp{LOG_INTO_DRAWER} property. When 7273 called with a @kbd{C-u} prefix argument, select the task from 7274 a list of recently clocked tasks. With two @kbd{C-u C-u} 7275 prefixes, clock into the task at point and mark it as the default 7276 task; the default task is always be available with letter 7277 @kbd{d} when selecting a clocking task. With three @kbd{C-u C-u C-u} prefixes, force continuous clocking by starting the 7278 clock when the last clock stopped. 7279 7280 @cindex @samp{CLOCK_MODELINE_TOTAL}, property 7281 @cindex @samp{LAST_REPEAT}, property 7282 @vindex org-clock-mode-line-total 7283 @vindex org-clock-in-prepare-hook 7284 While the clock is running, Org shows the current clocking time in 7285 the mode line, along with the title of the task. The clock time 7286 shown is all time ever clocked for this task and its children. If 7287 the task has an effort estimate (see @ref{Effort Estimates}), the 7288 mode line displays the current clocking time against it@footnote{ To add 7289 an effort estimate ``on the fly'', hook a function doing this to 7290 @code{org-clock-in-prepare-hook}.}. If the task is a repeating one (see 7291 @ref{Repeated tasks}), show only the time since the last reset of the 7292 task@footnote{ The last reset of the task is recorded by the 7293 @samp{LAST_REPEAT} property.}. You can exercise more control over show 7294 time with the @samp{CLOCK_MODELINE_TOTAL} property. It may have the 7295 values @samp{current} to show only the current clocking instance, @samp{today} 7296 to show all time clocked on this tasks today---see also the variable 7297 @code{org-extend-today-until}, @code{all} to include all time, or @code{auto} which 7298 is the default@footnote{ See also the variable 7299 @code{org-clock-mode-line-total}.}. Clicking with @kbd{mouse-1} 7300 onto the mode line entry pops up a menu with clocking options. 7301 7302 @item @kbd{C-c C-x C-o} (@code{org-clock-out}) 7303 @kindex C-c C-x C-o 7304 @findex org-clock-out 7305 @vindex org-log-note-clock-out 7306 Stop the clock (clock-out). This inserts another timestamp at the 7307 same location where the clock was last started. It also directly 7308 computes the resulting time in inserts it after the time range as 7309 @samp{=>HH:MM}. See the variable @code{org-log-note-clock-out} for the 7310 possibility to record an additional note together with the clock-out 7311 timestamp@footnote{ The corresponding in-buffer setting is: @samp{#+STARTUP: 7312 lognoteclock-out}.}. 7313 7314 @item @kbd{C-c C-x C-x} (@code{org-clock-in-last}) 7315 @kindex C-c C-x C-x 7316 @findex org-clock-in-last 7317 @vindex org-clock-continuously 7318 Re-clock the last clocked task. With one @kbd{C-u} prefix 7319 argument, select the task from the clock history. With two 7320 @kbd{C-u} prefixes, force continuous clocking by starting the 7321 clock when the last clock stopped. 7322 7323 @item @kbd{C-c C-x C-e} (@code{org-clock-modify-effort-estimate}) 7324 @kindex C-c C-x C-e 7325 @findex org-clock-modify-effort-estimate 7326 Update the effort estimate for the current clock task. 7327 7328 @item @kbd{C-c C-c} or @kbd{C-c C-y} (@code{org-evaluate-time-range}) 7329 @kindex C-c C-c 7330 @kindex C-c C-y 7331 @findex org-evaluate-time-range 7332 Recompute the time interval after changing one of the timestamps. 7333 This is only necessary if you edit the timestamps directly. If you 7334 change them with @kbd{S-<cursor>} keys, the update is 7335 automatic. 7336 7337 @item @kbd{C-S-@key{UP}} (@code{org-clock-timestamps-up}) 7338 @itemx @kbd{C-S-@key{DOWN}} (@code{org-clock-timestamps-down}) 7339 @kindex C-S-UP 7340 @findex org-clock-timestamps-up 7341 @kindex C-S-DOWN 7342 @findex org-clock-timestamps-down 7343 On CLOCK log lines, increase/decrease both timestamps so that the 7344 clock duration keeps the same value. 7345 7346 @item @kbd{S-M-@key{UP}} (@code{org-timestamp-up}) 7347 @itemx @kbd{S-M-@key{DOWN}} (@code{org-timestamp-down}) 7348 @kindex S-M-UP 7349 @findex org-clock-timestamp-up 7350 @kindex S-M-DOWN 7351 @findex org-clock-timestamp-down 7352 On @samp{CLOCK} log lines, increase/decrease the timestamp at point and 7353 the one of the previous, or the next, clock timestamp by the same 7354 duration. For example, if you hit @kbd{S-M-@key{UP}} to increase 7355 a clocked-out timestamp by five minutes, then the clocked-in 7356 timestamp of the next clock is increased by five minutes. 7357 7358 @item @kbd{C-c C-t} (@code{org-todo}) 7359 @kindex C-c C-t 7360 @findex org-todo 7361 Changing the TODO state of an item to DONE automatically stops the 7362 clock if it is running in this same item. 7363 7364 @item @kbd{C-c C-x C-q} (@code{org-clock-cancel}) 7365 @kindex C-c C-x C-q 7366 @findex org-clock-cancel 7367 Cancel the current clock. This is useful if a clock was started by 7368 mistake, or if you ended up working on something else. 7369 7370 @item @kbd{C-c C-x C-j} (@code{org-clock-goto}) 7371 @kindex C-c C-x C-j 7372 @findex or-clock-goto 7373 Jump to the headline of the currently clocked in task. With 7374 a @kbd{C-u} prefix argument, select the target task from a list 7375 of recently clocked tasks. 7376 7377 @item @kbd{C-c C-x C-d} (@code{org-clock-display}) 7378 @kindex C-c C-x C-d 7379 @findex org-clock-display 7380 @vindex org-remove-highlights-with-change 7381 Display time summaries for each subtree in the current buffer. This 7382 puts overlays at the end of each headline, showing the total time 7383 recorded under that heading, including the time of any subheadings. 7384 You can use visibility cycling to study the tree, but the overlays 7385 disappear when you change the buffer (see variable 7386 @code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}. 7387 @end table 7388 7389 The @kbd{l} key may be used in the agenda (see @ref{Weekly/daily agenda}) to show which tasks have been worked on or closed during 7390 a day. 7391 7392 @strong{Important:} note that both @code{org-clock-out} and @code{org-clock-in-last} 7393 can have a global keybinding and do not modify the window disposition. 7394 7395 @node The clock table 7396 @subsection The clock table 7397 7398 @cindex clocktable, dynamic block 7399 @cindex report, of clocked time 7400 7401 Org mode can produce quite complex reports based on the time clocking 7402 information. Such a report is called a @emph{clock table}, because it is 7403 formatted as one or several Org tables. 7404 7405 @table @asis 7406 @item @code{org-clock-report} 7407 @kindex C-c C-x x 7408 @findex org-clock-report 7409 Insert or update a clock table. When called with a prefix argument, 7410 jump to the first clock table in the current document and update it. 7411 The clock table includes archived trees. 7412 7413 This command can be invoked by calling 7414 @code{org-dynamic-block-insert-dblock} (@kbd{C-c C-x x}) and 7415 selecting ``clocktable'' (see @ref{Dynamic Blocks}). 7416 7417 @item @kbd{C-c C-c} or @kbd{C-c C-x C-u} (@code{org-dblock-update}) 7418 @kindex C-c C-c 7419 @kindex C-c C-x C-u 7420 @findex org-dblock-update 7421 Update dynamic block at point. Point needs to be in the @samp{BEGIN} 7422 line of the dynamic block. 7423 7424 @item @kbd{C-u C-c C-x C-u} 7425 @kindex C-u C-c C-x C-u 7426 Update all dynamic blocks (see @ref{Dynamic Blocks}). This is useful if 7427 you have several clock table blocks in a buffer. 7428 7429 @item @kbd{S-@key{LEFT}} 7430 @itemx @kbd{S-@key{RIGHT}} (@code{org-clocktable-try-shift}) 7431 @kindex S-LEFT 7432 @kindex S-RIGHT 7433 @findex org-clocktable-try-shift 7434 Shift the current @samp{:block} interval and update the table. Point 7435 needs to be in the @samp{#+BEGIN: clocktable} line for this command. If 7436 @samp{:block} is @samp{today}, it is shifted to @samp{today-1}, etc. 7437 @end table 7438 7439 Here is an example of the frame for a clock table as it is inserted 7440 into the buffer by @code{org-clock-report}: 7441 7442 @cindex @samp{BEGIN clocktable} 7443 @example 7444 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file 7445 #+END: 7446 @end example 7447 7448 @vindex org-clocktable-defaults 7449 The @samp{#+BEGIN} line contains options to define the scope, structure, 7450 and formatting of the report. Defaults for all these options can be 7451 configured in the variable @code{org-clocktable-defaults}. 7452 7453 First there are options that determine which clock entries are to 7454 be selected: 7455 7456 @table @asis 7457 @item @samp{:maxlevel} 7458 Maximum level depth to which times are listed in the table. Clocks 7459 at deeper levels are summed into the upper level. 7460 7461 @item @samp{:scope} 7462 The scope to consider. This can be any of the following: 7463 7464 @multitable {aaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 7465 @item @samp{nil} 7466 @tab the current buffer or narrowed region 7467 @item @samp{file} 7468 @tab the full current buffer 7469 @item @samp{subtree} 7470 @tab the subtree where the clocktable is located 7471 @item @samp{treeN} 7472 @tab the surrounding level N tree, for example @samp{tree3} 7473 @item @samp{tree} 7474 @tab the surrounding level 1 tree 7475 @item @samp{agenda} 7476 @tab all agenda files 7477 @item @samp{("file" ...)} 7478 @tab scan these files 7479 @item @samp{FUNCTION} 7480 @tab scan files returned by calling @var{FUNCTION} with no argument 7481 @item @samp{file-with-archives} 7482 @tab current file and its archives 7483 @item @samp{agenda-with-archives} 7484 @tab all agenda files, including archives 7485 @end multitable 7486 7487 @item @samp{:block} 7488 The time block to consider. This block is specified either 7489 absolutely, or relative to the current time and may be any of these 7490 formats: 7491 7492 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaa} 7493 @item @samp{2007-12-31} 7494 @tab New year eve 2007 7495 @item @samp{2007-12} 7496 @tab December 2007 7497 @item @samp{2007-W50} 7498 @tab ISO-week 50 in 2007 7499 @item @samp{2007-Q2} 7500 @tab 2nd quarter in 2007 7501 @item @samp{2007} 7502 @tab the year 2007 7503 @item @samp{today}, @samp{yesterday}, @samp{today-N} 7504 @tab a relative day 7505 @item @samp{thisweek}, @samp{lastweek}, @samp{thisweek-N} 7506 @tab a relative week 7507 @item @samp{thismonth}, @samp{lastmonth}, @samp{thismonth-N} 7508 @tab a relative month 7509 @item @samp{thisyear}, @samp{lastyear}, @samp{thisyear-N} 7510 @tab a relative year 7511 @item @samp{untilnow}@footnote{ When using @code{:step}, @code{untilnow} starts from the beginning of 2003, not the beginning of time.} 7512 @tab all clocked time ever 7513 @end multitable 7514 7515 @vindex org-clock-display-default-range 7516 When this option is not set, Org falls back to the value in 7517 @code{org-clock-display-default-range}, which defaults to the current 7518 year. 7519 7520 Use @kbd{S-@key{LEFT}} or @kbd{S-@key{RIGHT}} to shift the time 7521 interval. 7522 7523 @item @samp{:tstart} 7524 A time string specifying when to start considering times. Relative 7525 times like @samp{"<-2w>"} can also be used. See @ref{Matching tags and properties} for relative time syntax. 7526 7527 @item @samp{:tend} 7528 A time string specifying when to stop considering times. Relative 7529 times like @samp{"<now>"} can also be used. See @ref{Matching tags and properties} for relative time syntax. 7530 7531 @item @samp{:wstart} 7532 The starting day of the week. The default is 1 for Monday. 7533 7534 @item @samp{:mstart} 7535 The starting day of the month. The default is 1 for the first. 7536 7537 @item @samp{:step} 7538 Set to @samp{day}, @samp{week}, @samp{semimonth}, @samp{month}, @samp{quarter}, or @samp{year} to split the 7539 table into chunks. To use this, either @samp{:block}, or @samp{:tstart} and 7540 @samp{:tend} are required. 7541 7542 @item @samp{:stepskip0} 7543 When non-@code{nil}, do not show steps that have zero time. 7544 7545 @item @samp{:fileskip0} 7546 When non-@code{nil}, do not show table sections from files which did not 7547 contribute. 7548 7549 @item @samp{:match} 7550 A tags match to select entries that should contribute. See 7551 @ref{Matching tags and properties} for the match syntax. 7552 @end table 7553 7554 @findex org-clocktable-write-default 7555 Then there are options that determine the formatting of the table. 7556 There options are interpreted by the function 7557 @code{org-clocktable-write-default}, but you can specify your own function 7558 using the @samp{:formatter} parameter. 7559 7560 @table @asis 7561 @item @samp{:emphasize} 7562 When non-@code{nil}, emphasize level one and level two items. 7563 7564 @item @samp{:lang} 7565 Language@footnote{ Language terms can be set through the variable 7566 @code{org-clock-clocktable-language-setup}.} to use for descriptive cells 7567 like ``Task''. 7568 7569 @item @samp{:link} 7570 Link the item headlines in the table to their origins. 7571 7572 @item @samp{:narrow} 7573 An integer to limit the width of the headline column in the Org 7574 table. If you write it like @samp{50!}, then the headline is also 7575 shortened in export. 7576 7577 @item @samp{:indent} 7578 Indent each headline field according to its level. 7579 7580 @item @samp{:filetitle} 7581 Show title in the file column if the file has a @samp{#+title}. 7582 7583 @item @samp{:hidefiles} 7584 Hide the file column when multiple files are used to produce the 7585 table. 7586 7587 @item @samp{:tcolumns} 7588 Number of columns to be used for times. If this is smaller than 7589 @samp{:maxlevel}, lower levels are lumped into one column. 7590 7591 @item @samp{:level} 7592 Should a level number column be included? 7593 7594 @item @samp{:sort} 7595 A cons cell containing the column to sort and a sorting type. E.g., 7596 @samp{:sort (1 . ?a)} sorts the first column alphabetically. 7597 7598 @item @samp{:compact} 7599 Abbreviation for @samp{:level nil :indent t :narrow 40! :tcolumns 1}. 7600 All are overwritten except if there is an explicit @samp{:narrow}. 7601 7602 @item @samp{:timestamp} 7603 A timestamp for the entry, when available. Look for @samp{SCHEDULED}, 7604 @samp{DEADLINE}, @samp{TIMESTAMP} and @samp{TIMESTAMP_IA} special properties (see 7605 @ref{Special Properties}), in this order. 7606 7607 @item @samp{:tags} 7608 When this flag is non-@code{nil}, show the headline's tags. 7609 7610 @item @samp{:properties} 7611 List of properties shown in the table. Each property gets its own 7612 column. 7613 7614 @item @samp{:inherit-props} 7615 When this flag is non-@code{nil}, the values for @samp{:properties} are 7616 inherited. 7617 7618 @item @samp{:formula} 7619 Content of a @samp{TBLFM} keyword to be added and evaluated. As 7620 a special case, @samp{:formula %} adds a column with % time. If you do 7621 not specify a formula here, any existing formula below the clock 7622 table survives updates and is evaluated. 7623 7624 @item @samp{:formatter} 7625 A function to format clock data and insert it into the buffer. 7626 @end table 7627 7628 To get a clock summary of the current level 1 tree, for the current 7629 day, you could write: 7630 7631 @example 7632 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t 7633 #+END: 7634 @end example 7635 7636 @noindent 7637 To use a specific time range you could write@footnote{ Note that all 7638 parameters must be specified in a single line---the line is broken 7639 here only to fit it into the manual.} 7640 7641 @example 7642 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" 7643 :tend "<2006-08-10 Thu 12:00>" 7644 #+END: 7645 @end example 7646 7647 @noindent 7648 A range starting a week ago and ending right now could be written as 7649 7650 @example 7651 #+BEGIN: clocktable :tstart "<-1w>" :tend "<now>" 7652 #+END: 7653 @end example 7654 7655 @noindent 7656 A summary of the current subtree with % times would be 7657 7658 @example 7659 #+BEGIN: clocktable :scope subtree :link t :formula % 7660 #+END: 7661 @end example 7662 7663 @noindent 7664 A horizontally compact representation of everything clocked during 7665 last week would be 7666 7667 @example 7668 #+BEGIN: clocktable :scope agenda :block lastweek :compact t 7669 #+END: 7670 @end example 7671 7672 @node Resolving idle time 7673 @subsection Resolving idle time and continuous clocking 7674 7675 7676 7677 @anchor{Resolving idle time (1)} 7678 @subsubheading Resolving idle time 7679 7680 @cindex resolve idle time 7681 @cindex idle, resolve, dangling 7682 7683 If you clock in on a work item, and then walk away from your 7684 computer---perhaps to take a phone call---you often need to 7685 ``resolve'' the time you were away by either subtracting it from the 7686 current clock, or applying it to another one. 7687 7688 @vindex org-clock-idle-time 7689 @vindex org-clock-x11idle-program-name 7690 By customizing the variable @code{org-clock-idle-time} to some integer, 7691 such as 10 or 15, Emacs can alert you when you get back to your 7692 computer after being idle for that many minutes@footnote{On computers using macOS, idleness is based on actual user 7693 idleness, not just Emacs' idle time. For X11, you can install a 7694 utility program @samp{x11idle.c}, available in the @samp{org-contrib/} 7695 repository, or install the xprintidle package and set it to the 7696 variable @code{org-clock-x11idle-program-name} if you are running Debian, 7697 to get the same general treatment of idleness. On other systems, idle 7698 time refers to Emacs idle time only.}, and ask what 7699 you want to do with the idle time. There will be a question waiting 7700 for you when you get back, indicating how much idle time has passed 7701 constantly updated with the current amount, as well as a set of 7702 choices to correct the discrepancy: 7703 7704 @table @asis 7705 @item @kbd{k} 7706 @kindex k 7707 To keep some or all of the minutes and stay clocked in, press 7708 @kbd{k}. Org asks how many of the minutes to keep. Press 7709 @kbd{@key{RET}} to keep them all, effectively changing nothing, or 7710 enter a number to keep that many minutes. 7711 7712 @item @kbd{K} 7713 @kindex K 7714 If you use the shift key and press @kbd{K}, it keeps however 7715 many minutes you request and then immediately clock out of that 7716 task. If you keep all of the minutes, this is the same as just 7717 clocking out of the current task. 7718 7719 @item @kbd{s} 7720 @kindex s 7721 To keep none of the minutes, use @kbd{s} to subtract all the 7722 away time from the clock, and then check back in from the moment you 7723 returned. 7724 7725 @item @kbd{S} 7726 @kindex S 7727 To keep none of the minutes and just clock out at the start of the 7728 away time, use the shift key and press @kbd{S}. Remember that 7729 using shift always leave you clocked out, no matter which option you 7730 choose. 7731 7732 @item @kbd{C} 7733 @kindex C 7734 To cancel the clock altogether, use @kbd{C}. Note that if 7735 instead of canceling you subtract the away time, and the resulting 7736 clock amount is less than a minute, the clock is still canceled 7737 rather than cluttering up the log with an empty entry. 7738 @end table 7739 7740 What if you subtracted those away minutes from the current clock, and 7741 now want to apply them to a new clock? Simply clock in to any task 7742 immediately after the subtraction. Org will notice that you have 7743 subtracted time ``on the books'', so to speak, and will ask if you want 7744 to apply those minutes to the next task you clock in on. 7745 7746 There is one other instance when this clock resolution magic occurs. 7747 Say you were clocked in and hacking away, and suddenly your cat chased 7748 a mouse who scared a hamster that crashed into your UPS's power 7749 button! You suddenly lose all your buffers, but thanks to auto-save 7750 you still have your recent Org mode changes, including your last clock 7751 in. 7752 7753 If you restart Emacs and clock into any task, Org will notice that you 7754 have a dangling clock which was never clocked out from your last 7755 session. Using that clock's starting time as the beginning of the 7756 unaccounted-for period, Org will ask how you want to resolve that 7757 time. The logic and behavior is identical to dealing with away time 7758 due to idleness; it is just happening due to a recovery event rather 7759 than a set amount of idle time. 7760 7761 You can also check all the files visited by your Org agenda for 7762 dangling clocks at any time using @kbd{M-x org-resolve-clocks @key{RET}} (or @kbd{C-c C-x C-z}). 7763 7764 @anchor{Continuous clocking} 7765 @subsubheading Continuous clocking 7766 7767 @cindex continuous clocking 7768 7769 @vindex org-clock-continuously 7770 You may want to start clocking from the time when you clocked out the 7771 previous task. To enable this systematically, set 7772 @code{org-clock-continuously} to non-@code{nil}. Each time you clock in, Org 7773 retrieves the clock-out time of the last clocked entry for this 7774 session, and start the new clock from there. 7775 7776 If you only want this from time to time, use three universal prefix 7777 arguments with @code{org-clock-in} and two @kbd{C-u C-u} with 7778 @code{org-clock-in-last}. 7779 7780 @anchor{Clocking out automatically after some idle time} 7781 @subsubheading Clocking out automatically after some idle time 7782 7783 @cindex auto clocking out after idle time 7784 7785 @vindex org-clock-auto-clockout-timer 7786 When you often forget to clock out before being idle and you don't 7787 want to manually set the clocking time to take into account, you can 7788 set @code{org-clock-auto-clockout-timer} to a number of seconds and add 7789 @samp{(org-clock-auto-clockout-insinuate)} to your @samp{.emacs} file. 7790 7791 When the clock is running and Emacs is idle for more than this number 7792 of seconds, the clock will be clocked out automatically. 7793 7794 Use @samp{M-x org-clock-toggle-auto-clockout RET} to temporarily turn this 7795 on or off. 7796 7797 @node Effort Estimates 7798 @section Effort Estimates 7799 7800 @cindex effort estimates 7801 @cindex @samp{EFFORT}, property 7802 @vindex org-effort-property 7803 7804 If you want to plan your work in a very detailed way, or if you need 7805 to produce offers with quotations of the estimated work effort, you 7806 may want to assign effort estimates to entries. If you are also 7807 clocking your work, you may later want to compare the planned effort 7808 with the actual working time, a great way to improve planning 7809 estimates. 7810 7811 Effort estimates are stored in a special property @samp{EFFORT}. Multiple 7812 formats are supported, such as @samp{3:12}, @samp{1:23:45}, or @samp{1d3h5min}; see 7813 the file @samp{org-duration.el} for more detailed information about the 7814 format. 7815 7816 You can set the effort for an entry with the following commands: 7817 7818 @table @asis 7819 @item @kbd{C-c C-x e} (@code{org-set-effort}) 7820 @kindex C-c C-x e 7821 @findex org-set-effort 7822 Set the effort estimate for the current entry. With a prefix 7823 argument, set it to the next allowed value---see below. This 7824 command is also accessible from the agenda with the @kbd{e} 7825 key. 7826 7827 @item @kbd{C-c C-x C-e} (@code{org-clock-modify-effort-estimate}) 7828 @kindex C-c C-x C-e 7829 @findex org-clock-modify-effort-estimate 7830 Modify the effort estimate of the item currently being clocked. 7831 @end table 7832 7833 Clearly the best way to work with effort estimates is through column 7834 view (see @ref{Column View}). You should start by setting up discrete 7835 values for effort estimates, and a @samp{COLUMNS} format that displays 7836 these values together with clock sums---if you want to clock your 7837 time. For a specific buffer you can use: 7838 7839 @example 7840 #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 7841 #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM 7842 @end example 7843 7844 @noindent 7845 @vindex org-global-properties 7846 @vindex org-columns-default-format 7847 or, even better, you can set up these values globally by customizing 7848 the variables @code{org-global-properties} and 7849 @code{org-columns-default-format}. In particular if you want to use this 7850 setup also in the agenda, a global setup may be advised. 7851 7852 The way to assign estimates to individual items is then to switch to 7853 column mode, and to use @kbd{S-@key{RIGHT}} and @kbd{S-@key{LEFT}} to 7854 change the value. The values you enter are immediately summed up in 7855 the hierarchy. In the column next to it, any clocked time is 7856 displayed. 7857 7858 @vindex org-agenda-columns-add-appointments-to-effort-sum 7859 If you switch to column view in the daily/weekly agenda, the effort 7860 column summarizes the estimated work effort for each day@footnote{ Please 7861 note the pitfalls of summing hierarchical data in a flat list (see 7862 @ref{Agenda Column View}).}, and you can use this to find 7863 space in your schedule. To get an overview of the entire part of the 7864 day that is committed, you can set the option 7865 @code{org-agenda-columns-add-appointments-to-effort-sum}. The appointments 7866 on a day that take place over a specified time interval are then also 7867 added to the load estimate of the day. 7868 7869 Effort estimates can be used in secondary agenda filtering that is 7870 triggered with the @kbd{/} key in the agenda (see @ref{Agenda Commands}). If you have these estimates defined consistently, 7871 two or three key presses narrow down the list to stuff that fits into 7872 an available time slot. 7873 7874 @node Timers 7875 @section Taking Notes with a Relative Timer 7876 7877 @cindex relative timer 7878 @cindex countdown timer 7879 7880 Org provides two types of timers. There is a relative timer that 7881 counts up, which can be useful when taking notes during, for example, 7882 a meeting or a video viewing. There is also a countdown timer. 7883 7884 The relative and countdown are started with separate commands. 7885 7886 @table @asis 7887 @item @kbd{C-c C-x 0} (@code{org-timer-start}) 7888 @kindex C-c C-x 0 7889 @findex org-timer-start 7890 Start or reset the relative timer. By default, the timer is set 7891 to 0. When called with a @kbd{C-u} prefix, prompt the user for 7892 a starting offset. The prompt will default to a timer string at 7893 point (if any), providing a convenient way to restart taking notes 7894 after a break in the process. When called with a double prefix 7895 argument @kbd{C-u C-u}, change all timer strings in the active 7896 region by a certain amount. This can be used to fix timer strings 7897 if the timer was not started at exactly the right moment. 7898 7899 @item @kbd{C-c C-x ;} (@code{org-timer-set-timer}) 7900 @kindex C-c C-x ; 7901 @findex org-timer-set-timer 7902 @vindex org-timer-default-timer 7903 Start a countdown timer. The user is prompted for a duration. 7904 @code{org-timer-default-timer} sets the default countdown value. Giving 7905 a numeric prefix argument overrides this default value. This 7906 command is available as @kbd{;} in agenda buffers. 7907 @end table 7908 7909 Once started, relative and countdown timers are controlled with the 7910 same commands. 7911 7912 @table @asis 7913 @item @kbd{C-c C-x .} (@code{org-timer}) 7914 @kindex C-c C-x . 7915 @findex org-timer 7916 Insert a relative time into the buffer. The first time you use 7917 this, the timer starts. Using a prefix argument restarts it. 7918 7919 @item @kbd{C-c C-x -} (@code{org-timer-item}) 7920 @kindex C-c C-x - 7921 @findex org-timer-item 7922 Insert a description list item with the current relative time. With 7923 a prefix argument, first reset the timer to 0. 7924 7925 @item @kbd{M-@key{RET}} (@code{org-insert-heading}) 7926 @kindex M-RET 7927 @findex org-insert-heading 7928 Once the timer list is started, you can also use @kbd{M-@key{RET}} to 7929 insert new timer items. 7930 7931 @item @kbd{C-c C-x ,} (@code{org-timer-pause-or-continue}) 7932 @kindex C-c C-x , 7933 @findex org-timer-pause-or-continue 7934 Pause the timer, or continue it if it is already paused. 7935 7936 @item @kbd{C-c C-x _} (@code{org-timer-stop}) 7937 @kindex C-c C-x _ 7938 @findex org-timer-stop 7939 Stop the timer. After this, you can only start a new timer, not 7940 continue the old one. This command also removes the timer from the 7941 mode line. 7942 @end table 7943 7944 @node Refiling and Archiving 7945 @chapter Refiling and Archiving 7946 7947 @cindex refiling notes 7948 @cindex copying notes 7949 @cindex archiving 7950 7951 Once information is in the system, it may need to be moved around. 7952 Org provides Refile, Copy and Archive commands for this. Refile and 7953 Copy helps with moving and copying outlines. Archiving helps to keep 7954 the system compact and fast. 7955 7956 @menu 7957 * Refile and Copy:: Moving/copying a tree from one place to another. 7958 * Archiving:: What to do with finished products. 7959 @end menu 7960 7961 @node Refile and Copy 7962 @section Refile and Copy 7963 7964 @cindex refiling notes 7965 @cindex copying notes 7966 7967 When reviewing the captured data, you may want to refile or to copy 7968 some of the entries into a different list, for example into a project. 7969 Cutting, finding the right location, and then pasting the note is 7970 cumbersome. To simplify this process, you can use the following 7971 special command: 7972 7973 @table @asis 7974 @item @kbd{C-c C-w} (@code{org-refile}) 7975 @kindex C-c C-w 7976 @findex org-refile 7977 @vindex org-reverse-note-order 7978 @vindex org-refile-targets 7979 @vindex org-refile-use-outline-path 7980 @vindex org-outline-path-complete-in-steps 7981 @vindex org-refile-allow-creating-parent-nodes 7982 @vindex org-log-refile 7983 Refile the entry or region at point. This command offers possible 7984 locations for refiling the entry and lets you select one with 7985 completion. The item (or all items in the region) is filed below 7986 the target heading as a subitem. Depending on 7987 @code{org-reverse-note-order}, it is either the first or last subitem. 7988 7989 By default, all level 1 headlines in the current buffer are 7990 considered to be targets, but you can have more complex definitions 7991 across a number of files. See the variable @code{org-refile-targets} for 7992 details. If you would like to select a location via a 7993 file-path-like completion along the outline path, see the variables 7994 @code{org-refile-use-outline-path} and 7995 @code{org-outline-path-complete-in-steps}. If you would like to be able 7996 to create new nodes as new parents for refiling on the fly, check 7997 the variable @code{org-refile-allow-creating-parent-nodes}. When the 7998 variable @code{org-log-refile}@footnote{ Note the corresponding @samp{STARTUP} 7999 options @samp{logrefile}, @samp{lognoterefile}, and @samp{nologrefile}.} is set, a 8000 timestamp or a note is recorded whenever an entry is refiled. 8001 8002 @item @kbd{C-u C-c C-w} 8003 @kindex C-u C-c C-w 8004 Use the refile interface to jump to a heading. 8005 8006 @item @kbd{C-u C-u C-c C-w} (@code{org-refile-goto-last-stored}) 8007 @kindex C-u C-u C-c C-w 8008 @findex org-refile-goto-last-stored 8009 Jump to the location where @code{org-refile} last moved a tree to. 8010 8011 @item @kbd{C-2 C-c C-w} 8012 @kindex C-2 C-c C-w 8013 Refile as the child of the item currently being clocked. 8014 8015 @item @kbd{C-3 C-c C-w} 8016 @kindex C-3 C-c C-w 8017 @vindex org-refile-keep 8018 Refile and keep the entry in place. Also see @code{org-refile-keep} to 8019 make this the default behavior, and beware that this may result in 8020 duplicated @samp{ID} properties. 8021 8022 @item @kbd{C-0 C-c C-w} or @kbd{C-u C-u C-u C-c C-w} (@code{org-refile-cache-clear}) 8023 @kindex C-u C-u C-u C-c C-w 8024 @kindex C-0 C-c C-w 8025 @findex org-refile-cache-clear 8026 @vindex org-refile-use-cache 8027 Clear the target cache. Caching of refile targets can be turned on 8028 by setting @code{org-refile-use-cache}. To make the command see new 8029 possible targets, you have to clear the cache with this command. 8030 8031 @item @kbd{C-c M-w} (@code{org-refile-copy}) 8032 @kindex C-c M-w 8033 @findex org-refile-copy 8034 Copying works like refiling, except that the original note is not 8035 deleted. 8036 8037 @item @kbd{C-c C-M-w} (@code{org-refile-reverse}) 8038 @kindex C-c C-M-w 8039 @findex org-refile-reverse 8040 Works like refiling, except that it temporarily toggles how the 8041 value of @code{org-reverse-note-order} applies to the current buffer. So 8042 if @code{org-refile} would append the entry as the last entry under the 8043 target header, @code{org-refile-reverse} will prepend it as the first 8044 entry, and vice-versa. 8045 @end table 8046 8047 @node Archiving 8048 @section Archiving 8049 8050 @cindex archiving 8051 8052 When a project represented by a (sub)tree is finished, you may want to 8053 move the tree out of the way and to stop it from contributing to the 8054 agenda. Archiving is important to keep your working files compact and 8055 global searches like the construction of agenda views fast. 8056 8057 @table @asis 8058 @item @kbd{C-c C-x C-a} (@code{org-archive-subtree-default}) 8059 @kindex C-c C-x C-a 8060 @findex org-archive-subtree-default 8061 @vindex org-archive-default-command 8062 Archive the current entry using the command specified in the 8063 variable @code{org-archive-default-command}. 8064 @end table 8065 8066 @menu 8067 * Moving subtrees:: Moving a tree to an archive file. 8068 * Internal archiving:: Switch off a tree but keep it in the file. 8069 @end menu 8070 8071 @node Moving subtrees 8072 @subsection Moving a tree to an archive file 8073 8074 @cindex external archiving 8075 8076 The most common archiving action is to move a project tree to another 8077 file, the archive file. 8078 8079 @table @asis 8080 @item @kbd{C-c C-x C-s} or short @kbd{C-c $} (@code{org-archive-subtree}) 8081 @kindex C-c C-x C-s 8082 @kindex C-c $ 8083 @findex org-archive-subtree 8084 @vindex org-archive-location 8085 Archive the subtree starting at point position to the location given 8086 by @code{org-archive-location}. 8087 8088 @item @kbd{C-u C-c C-x C-s} 8089 @kindex C-u C-c C-x C-s 8090 Check if any direct children of the current headline could be moved 8091 to the archive. To do this, check each subtree for open TODO 8092 entries. If none is found, the command offers to move it to the 8093 archive location. If point is @emph{not} on a headline when this command 8094 is invoked, check level 1 trees. 8095 8096 @item @kbd{C-u C-u C-c C-x C-s} 8097 @kindex C-u C-u C-c C-x C-s 8098 As above, but check subtree for timestamps instead of TODO entries. 8099 The command offers to archive the subtree if it @emph{does} contain 8100 a timestamp, and that timestamp is in the past. 8101 @end table 8102 8103 @cindex archive locations 8104 The default archive location is a file in the same directory as the 8105 current file, with the name derived by appending @samp{_archive} to the 8106 current file name. You can also choose what heading to file archived 8107 items under, with the possibility to add them to a datetree in a file. 8108 For information and examples on how to specify the file and the 8109 heading, see the documentation string of the variable 8110 @code{org-archive-location}. 8111 8112 There is also an in-buffer option for setting this variable, for 8113 example: 8114 8115 @cindex @samp{ARCHIVE}, keyword 8116 @example 8117 #+ARCHIVE: %s_done:: 8118 @end example 8119 8120 8121 @cindex ARCHIVE, property 8122 If you would like to have a special archive location for a single 8123 entry or a (sub)tree, give the entry an @samp{ARCHIVE} property with the 8124 location as the value (see @ref{Properties and Columns}). 8125 8126 @vindex org-archive-save-context-info 8127 When a subtree is moved, it receives a number of special properties 8128 that record context information like the file from where the entry 8129 came, its outline path the archiving time etc. Configure the variable 8130 @code{org-archive-save-context-info} to adjust the amount of information 8131 added. 8132 8133 @vindex org-archive-subtree-save-file-p 8134 When @code{org-archive-subtree-save-file-p} is non-@code{nil}, save the target 8135 archive buffer. 8136 8137 @node Internal archiving 8138 @subsection Internal archiving 8139 8140 @cindex @samp{ARCHIVE}, tag 8141 If you want to just switch off---for agenda views---certain subtrees 8142 without moving them to a different file, you can use the @samp{ARCHIVE} 8143 tag. 8144 8145 A headline that is marked with the @samp{ARCHIVE} tag (see @ref{Tags}) stays at 8146 its location in the outline tree, but behaves in the following way: 8147 8148 @itemize 8149 @item 8150 @vindex org-cycle-open-archived-trees 8151 It does not open when you attempt to do so with a visibility cycling 8152 command (see @ref{Visibility Cycling}). You can force cycling archived 8153 subtrees with @kbd{C-c C-@key{TAB}}, or by setting the option 8154 @code{org-cycle-open-archived-trees}. Also normal outline commands, like 8155 @code{org-show-all}, open archived subtrees. 8156 8157 @item 8158 @vindex org-sparse-tree-open-archived-trees 8159 During sparse tree construction (see @ref{Sparse Trees}), matches in 8160 archived subtrees are not exposed, unless you configure the option 8161 @code{org-sparse-tree-open-archived-trees}. 8162 8163 @item 8164 @vindex org-agenda-skip-archived-trees 8165 During agenda view construction (see @ref{Agenda Views}), the content of 8166 archived trees is ignored unless you configure the option 8167 @code{org-agenda-skip-archived-trees}, in which case these trees are 8168 always included. In the agenda you can press @kbd{v a} to get 8169 archives temporarily included. 8170 8171 @item 8172 @vindex org-export-with-archived-trees 8173 Archived trees are not exported (see @ref{Exporting}), only the headline 8174 is. Configure the details using the variable 8175 @code{org-export-with-archived-trees}. 8176 8177 @item 8178 @vindex org-columns-skip-archived-trees 8179 Archived trees are excluded from column view unless the variable 8180 @code{org-columns-skip-archived-trees} is configured to @code{nil}. 8181 @end itemize 8182 8183 The following commands help manage the @samp{ARCHIVE} tag: 8184 8185 @table @asis 8186 @item @kbd{C-c C-x a} (@code{org-toggle-archive-tag}) 8187 @kindex C-c C-x a 8188 @findex org-toggle-archive-tag 8189 Toggle the archive tag for the current headline. When the tag is 8190 set, the headline changes to a shadowed face, and the subtree below 8191 it is hidden. 8192 8193 @item @kbd{C-u C-c C-x a} 8194 @kindex C-u C-c C-x a 8195 Check if any direct children of the current headline should be 8196 archived. To do this, check each subtree for open TODO entries. If 8197 none is found, the command offers to set the @samp{ARCHIVE} tag for the 8198 child. If point is @emph{not} on a headline when this command is 8199 invoked, check the level 1 trees. 8200 8201 @item @kbd{C-c C-@key{TAB}} (@code{org-cycle-force-archived}) 8202 @kindex C-c C-TAB 8203 Cycle a tree even if it is tagged with @samp{ARCHIVE}. 8204 8205 @item @kbd{C-c C-x A} (@code{org-archive-to-archive-sibling}) 8206 @kindex C-c C-x A 8207 @findex org-archive-to-archive-sibling 8208 Move the current entry to the @emph{Archive Sibling}. This is a sibling 8209 of the entry with the heading @samp{Archive} and the archive tag. The 8210 entry becomes a child of that sibling and in this way retains a lot 8211 of its original context, including inherited tags and approximate 8212 position in the outline. 8213 @end table 8214 8215 @node Capture and Attachments 8216 @chapter Capture and Attachments 8217 8218 @cindex capture 8219 @cindex attachments 8220 @cindex RSS feeds 8221 @cindex Atom feeds 8222 @cindex protocols, for external access 8223 8224 An important part of any organization system is the ability to quickly 8225 capture new ideas and tasks, and to associate reference material with 8226 them. Org does this using a process called @emph{capture}. It also can 8227 store files related to a task (@emph{attachments}) in a special directory. 8228 Finally, it can parse RSS feeds for information. To learn how to let 8229 external programs (for example a web browser) trigger Org to capture 8230 material, see @ref{Protocols}. 8231 8232 @menu 8233 * Capture:: Capturing new stuff. 8234 * Attachments:: Attach files to outlines. 8235 * RSS Feeds:: Getting input from RSS feeds. 8236 @end menu 8237 8238 @node Capture 8239 @section Capture 8240 8241 @cindex capture 8242 8243 Capture lets you quickly store notes with little interruption of your 8244 work flow. Org's method for capturing new items is heavily inspired 8245 by John Wiegley's excellent Remember package. 8246 8247 @menu 8248 * Setting up capture:: Where notes will be stored. 8249 * Using capture:: Commands to invoke and terminate capture. 8250 * Capture templates:: Define the outline of different note types. 8251 @end menu 8252 8253 @node Setting up capture 8254 @subsection Setting up capture 8255 8256 The following customization sets a default target file for notes. 8257 8258 @vindex org-default-notes-file 8259 @lisp 8260 (setq org-default-notes-file (concat org-directory "/notes.org")) 8261 @end lisp 8262 8263 You may also define a global key for capturing new material (see 8264 @ref{Activation}). 8265 8266 @node Using capture 8267 @subsection Using capture 8268 8269 @table @asis 8270 @item @kbd{M-x org-capture} (@code{org-capture}) 8271 @findex org-capture 8272 Display the capture templates menu. If you have templates defined 8273 (see @ref{Capture templates}), it offers these templates for selection or 8274 use a new Org outline node as the default template. It inserts the 8275 template into the target file and switch to an indirect buffer 8276 narrowed to this new node. You may then insert the information you 8277 want. 8278 8279 @item @kbd{C-c C-c} (@code{org-capture-finalize}) 8280 @kindex C-c C-c @r{(Capture buffer)} 8281 @findex org-capture-finalize 8282 Once you have finished entering information into the capture buffer, 8283 @kbd{C-c C-c} returns you to the window configuration before 8284 the capture process, so that you can resume your work without 8285 further distraction. When called with a prefix argument, finalize 8286 and then jump to the captured item. 8287 8288 @item @kbd{C-c C-w} (@code{org-capture-refile}) 8289 @kindex C-c C-w @r{(Capture buffer)} 8290 @findex org-capture-refile 8291 Finalize the capture process by refiling the note to a different 8292 place (see @ref{Refile and Copy}). Please realize that this is a normal 8293 refiling command that will be executed---so point position at the 8294 moment you run this command is important. If you have inserted 8295 a tree with a parent and children, first move point back to the 8296 parent. Any prefix argument given to this command is passed on to 8297 the @code{org-refile} command. 8298 8299 @item @kbd{C-c C-k} (@code{org-capture-kill}) 8300 @kindex C-c C-k @r{(Capture buffer)} 8301 @findex org-capture-kill 8302 Abort the capture process and return to the previous state. 8303 @end table 8304 8305 @kindex k c @r{(Agenda)} 8306 You can also call @code{org-capture} in a special way from the agenda, 8307 using the @kbd{k c} key combination. With this access, any 8308 timestamps inserted by the selected capture template defaults to the 8309 date at point in the agenda, rather than to the current date. 8310 8311 To find the locations of the last stored capture, use @code{org-capture} 8312 with prefix commands: 8313 8314 @table @asis 8315 @item @kbd{C-u M-x org-capture} 8316 Visit the target location of a capture template. You get to select 8317 the template in the usual way. 8318 8319 @item @kbd{C-u C-u M-x org-capture} 8320 Visit the last stored capture item in its buffer. 8321 @end table 8322 8323 @vindex org-capture-bookmark 8324 @vindex org-capture-last-stored 8325 You can also jump to the bookmark @code{org-capture-last-stored}, which is 8326 automatically created unless you set @code{org-capture-bookmark} to @code{nil}. 8327 8328 To insert the capture at point in an Org buffer, call @code{org-capture} 8329 with a @kbd{C-0} prefix argument. 8330 8331 @node Capture templates 8332 @subsection Capture templates 8333 8334 @cindex templates, for Capture 8335 8336 You can use templates for different types of capture items, and for 8337 different target locations. The easiest way to create such templates 8338 is through the customize interface. 8339 8340 @table @asis 8341 @item @kbd{C} 8342 @kindex C @r{(Capture menu} 8343 @vindex org-capture-templates 8344 Customize the variable @code{org-capture-templates}. 8345 @end table 8346 8347 Before we give the formal description of template definitions, let's 8348 look at an example. Say you would like to use one template to create 8349 general TODO entries, and you want to put these entries under the 8350 heading @samp{Tasks} in your file @samp{~/org/gtd.org}. Also, a date tree in 8351 the file @samp{journal.org} should capture journal entries. A possible 8352 configuration would look like: 8353 8354 @lisp 8355 (setq org-capture-templates 8356 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") 8357 "* TODO %?\n %i\n %a") 8358 ("j" "Journal" entry (file+datetree "~/org/journal.org") 8359 "* %?\nEntered on %U\n %i\n %a"))) 8360 @end lisp 8361 8362 If you then press @kbd{t} from the capture menu, Org will prepare 8363 the template for you like this: 8364 8365 @example 8366 * TODO 8367 [[file:LINK TO WHERE YOU INITIATED CAPTURE]] 8368 @end example 8369 8370 @noindent 8371 During expansion of the template, @samp{%a} has been replaced by a link to 8372 the location from where you called the capture command. This can be 8373 extremely useful for deriving tasks from emails, for example. You 8374 fill in the task definition, press @kbd{C-c C-c} and Org returns 8375 you to the same place where you started the capture process. 8376 8377 To define special keys to capture to a particular template without 8378 going through the interactive template selection, you can create your 8379 key binding like this: 8380 8381 @lisp 8382 (define-key global-map (kbd "C-c x") 8383 (lambda () (interactive) (org-capture nil "x"))) 8384 @end lisp 8385 8386 @menu 8387 * Template elements:: What is needed for a complete template entry. 8388 * Template expansion:: Filling in information about time and context. 8389 * Templates in contexts:: Only show a template in a specific context. 8390 @end menu 8391 8392 @node Template elements 8393 @subsubsection Template elements 8394 8395 Now lets look at the elements of a template definition. Each entry in 8396 @code{org-capture-templates} is a list with the following items: 8397 8398 @table @asis 8399 @item keys 8400 The keys that selects the template, as a string, characters only, 8401 for example @samp{"a"}, for a template to be selected with a single key, 8402 or @samp{"bt"} for selection with two keys. When using several keys, 8403 keys using the same prefix key must be sequential in the list and 8404 preceded by a 2-element entry explaining the prefix key, for 8405 example: 8406 8407 @lisp 8408 ("b" "Templates for marking stuff to buy") 8409 @end lisp 8410 8411 If you do not define a template for the @kbd{C} key, this key 8412 opens the Customize buffer for this complex variable. 8413 8414 @item description 8415 A short string describing the template, shown during selection. 8416 8417 @item type 8418 The type of entry, a symbol. Valid values are: 8419 8420 @table @asis 8421 @item @code{entry} 8422 An Org mode node, with a headline. Will be filed as the child of 8423 the target entry or as a top-level entry. The target file should 8424 be an Org file. 8425 8426 @item @code{item} 8427 A plain list item, placed in the first plain list at the target 8428 location. Again the target file should be an Org file. 8429 8430 @item @code{checkitem} 8431 A checkbox item. This only differs from the plain list item by 8432 the default template. 8433 8434 @item @code{table-line} 8435 A new line in the first table at the target location. Where 8436 exactly the line will be inserted depends on the properties 8437 @code{:prepend} and @code{:table-line-pos} (see below). 8438 8439 @item @code{plain} 8440 Text to be inserted as it is. 8441 @end table 8442 8443 @item target 8444 @vindex org-default-notes-file 8445 @vindex org-directory 8446 @cindex date tree 8447 Specification of where the captured item should be placed. In Org 8448 files, targets usually define a node. Entries will become children 8449 of this node. Other types will be added to the table or list in the 8450 body of this node. Most target specifications contain a file name. 8451 If that file name is the empty string, it defaults to 8452 @code{org-default-notes-file}. A file can also be given as a variable or 8453 as a function called with no argument. When an absolute path is not 8454 specified for a target, it is taken as relative to @code{org-directory}. 8455 8456 Valid values are: 8457 8458 @table @asis 8459 @item @samp{(file "path/to/file")} 8460 Text will be placed at the beginning or end of that file. 8461 8462 @item @samp{(id "id of existing org entry")} 8463 Filing as child of this entry, or in the body of the entry. 8464 8465 @item @samp{(file+headline "filename" "node headline")} 8466 Fast configuration if the target heading is unique in the file. 8467 8468 @item @samp{(file+olp "filename" "Level 1 heading" "Level 2" ...)} 8469 For non-unique headings, the full path is safer. 8470 8471 @item @samp{(file+regexp "filename" "regexp to find location")} 8472 Use a regular expression to position point. 8473 8474 @item @samp{(file+olp+datetree "filename" [ "Level 1 heading" ...])} 8475 This target@footnote{Org used to offer four different targets for date/week tree 8476 capture. Now, Org automatically translates these to use 8477 @code{file+olp+datetree}, applying the @code{:time-prompt} and @code{:tree-type} 8478 properties. Please rewrite your date/week-tree targets using 8479 @code{file+olp+datetree} since the older targets are now deprecated.} creates a heading in a date tree@footnote{A date tree is an outline structure with years on the highest 8480 level, months or ISO weeks as sublevels and then dates on the lowest 8481 level. 8482 8483 @example 8484 * 2022 8485 ** 2022-10 October 8486 *** 2022-10-07 Friday 8487 *** 2022-10-08 Saturday 8488 @end example 8489 8490 Tags are allowed in the tree structure.} for 8491 today's date. If the optional outline path is given, the tree 8492 will be built under the node it is pointing to, instead of at top 8493 level. Check out the @code{:time-prompt} and @code{:tree-type} properties 8494 below for additional options. 8495 8496 @item @samp{(file+function "filename" function-finding-location)} 8497 A function to find the right location in the file. 8498 8499 @item @samp{(clock)} 8500 File to the entry that is currently being clocked. 8501 8502 @item @samp{(function function-finding-location)} 8503 Most general way: write your own function which both visits the 8504 file and moves point to the right location. 8505 @end table 8506 8507 @item template 8508 The template for creating the capture item. If you leave this 8509 empty, an appropriate default template will be used. Otherwise this 8510 is a string with escape codes, which will be replaced depending on 8511 time and context of the capture call. You may also get this 8512 template string from a file@footnote{ When the file name is not absolute, 8513 Org assumes it is relative to @code{org-directory}.}, or dynamically, 8514 from a function using either syntax: 8515 8516 @example 8517 (file "/path/to/template-file") 8518 (function FUNCTION-RETURNING-THE-TEMPLATE) 8519 @end example 8520 8521 @item properties 8522 The rest of the entry is a property list of additional options. 8523 Recognized properties are: 8524 8525 @table @asis 8526 @item @code{:prepend} 8527 Normally new captured information will be appended at the target 8528 location (last child, last table line, last list item, @dots{}). 8529 Setting this property changes that. 8530 8531 @item @code{:immediate-finish} 8532 When set, do not offer to edit the information, just file it away 8533 immediately. This makes sense if the template only needs 8534 information that can be added automatically. 8535 8536 @item @code{:jump-to-captured} 8537 When set, jump to the captured entry when finished. 8538 8539 @item @code{:empty-lines} 8540 Set this to the number of lines to insert before and after the new 8541 item. Default 0, and the only other common value is 1. 8542 8543 @item @code{:empty-lines-after} 8544 Set this to the number of lines that should be inserted after the 8545 new item. Overrides @code{:empty-lines} for the number of lines 8546 inserted after. 8547 8548 @item @code{:empty-lines-before} 8549 Set this to the number of lines that should be inserted before the 8550 new item. Overrides @code{:empty-lines} for the number lines inserted 8551 before. 8552 8553 @item @code{:clock-in} 8554 Start the clock in this item. 8555 8556 @item @code{:clock-keep} 8557 Keep the clock running when filing the captured entry. 8558 8559 @item @code{:clock-resume} 8560 If starting the capture interrupted a clock, restart that clock 8561 when finished with the capture. Note that @code{:clock-keep} has 8562 precedence over @code{:clock-resume}. When setting both to non-@code{nil}, 8563 the current clock will run and the previous one will not be 8564 resumed. 8565 8566 @item @code{:time-prompt} 8567 Prompt for a date/time to be used for date/week trees and when 8568 filling the template. Without this property, capture uses the 8569 current date and time. Even if this property has not been set, 8570 you can force the same behavior by calling @code{org-capture} with 8571 a @kbd{C-1} prefix argument. 8572 8573 @item @code{:tree-type} 8574 Use @code{week} to make a week tree instead of the month-day tree, 8575 i.e., place the headings for each day under a heading with the 8576 current ISO week. Use @code{month} to group entries by month 8577 only. Default is to group entries by day. 8578 8579 @item @code{:unnarrowed} 8580 Do not narrow the target buffer, simply show the full buffer. 8581 Default is to narrow it so that you only see the new material. 8582 8583 @item @code{:table-line-pos} 8584 Specification of the location in the table where the new line 8585 should be inserted. It should be a string like @samp{II-3} meaning 8586 that the new line should become the third line before the second 8587 horizontal separator line. 8588 8589 @item @code{:kill-buffer} 8590 If the target file was not yet visited when capture was invoked, 8591 kill the buffer again after capture is completed. 8592 8593 @item @code{:no-save} 8594 Do not save the target file after finishing the capture. 8595 8596 @item @code{:refile-targets} 8597 Temporarily set @code{org-refile-targets} to the 8598 value of this property. 8599 8600 @item @code{:hook} 8601 A nullary function or list of nullary functions run before 8602 @code{org-capture-mode-hook} when the template is selected. 8603 @end table 8604 @table @asis 8605 @item @code{:prepare-finalize} 8606 A nullary function or list of nullary functions run before 8607 @code{org-capture-prepare-finalize-hook} when the template is selected. 8608 8609 @item @code{:before-finalize} 8610 A nullary function or list of nullary functions run before 8611 @code{org-capture-before-finalize-hook} when the template is selected. 8612 8613 @item @code{:after-finalize} 8614 A nullary function or list of nullary functions run before 8615 @code{org-capture-after-finalize-hook} when the template is selected. 8616 @end table 8617 @end table 8618 8619 @node Template expansion 8620 @subsubsection Template expansion 8621 8622 In the template itself, special ``%-escapes''@footnote{ If you need one of 8623 these sequences literally, escape the @samp{%} with a backslash.} allow 8624 dynamic insertion of content. The templates are expanded in the order 8625 given here: 8626 8627 @table @asis 8628 @item @samp{%[FILE]} 8629 Insert the contents of the file given by @var{FILE}. 8630 8631 @item @samp{%(EXP)} 8632 Evaluate Elisp expression @var{EXP} and replace it with the 8633 result. The @var{EXP} form must return a string. Only 8634 placeholders pre-existing within the template, or introduced with 8635 @samp{%[file]}, are expanded this way. Since this happens after 8636 expanding non-interactive ``%-escapes'', those can be used to fill the 8637 expression. 8638 8639 @item @samp{%<FORMAT>} 8640 The result of format-time-string on the @var{FORMAT} 8641 specification. 8642 8643 @item @samp{%t} 8644 Timestamp, date only. 8645 8646 @item @samp{%T} 8647 Timestamp, with date and time. 8648 8649 @item @samp{%u}, @samp{%U} 8650 Like @samp{%t}, @samp{%T} above, but inactive timestamps. 8651 8652 @item @samp{%i} 8653 Initial content, the region when capture is called while the region 8654 is active. If there is text before @samp{%i} on the same line, such as 8655 indentation, and @samp{%i} is not inside a @samp{%(exp)} form, that prefix is 8656 added before every line in the inserted text. 8657 8658 @item @samp{%a} 8659 Annotation, normally the link created with @code{org-store-link}. 8660 8661 @item @samp{%A} 8662 Like @samp{%a}, but prompt for the description part. 8663 8664 @item @samp{%l} 8665 Like @samp{%a}, but only insert the literal link. 8666 8667 @item @samp{%L} 8668 Like @samp{%l}, but without brackets (the link content itself). 8669 8670 @item @samp{%c} 8671 Current kill ring head. 8672 8673 @item @samp{%x} 8674 Content of the X clipboard. 8675 8676 @item @samp{%k} 8677 Title of the currently clocked task. 8678 8679 @item @samp{%K} 8680 Link to the currently clocked task. 8681 8682 @item @samp{%n} 8683 User name (taken from @code{user-full-name}). 8684 8685 @item @samp{%f} 8686 File visited by current buffer when org-capture was called. 8687 8688 @item @samp{%F} 8689 Full path of the file or directory visited by current buffer. 8690 8691 @item @samp{%:keyword} 8692 Specific information for certain link types, see below. 8693 8694 @item @samp{%^g} 8695 Prompt for tags, with completion on tags in target file. 8696 8697 @item @samp{%^G} 8698 Prompt for tags, with completion all tags in all agenda files. 8699 8700 @item @samp{%^t} 8701 Like @samp{%t}, but prompt for date. Similarly @samp{%^T}, @samp{%^u}, @samp{%^U}. You 8702 may define a prompt like @samp{%^@{Birthday@}t}. 8703 8704 @item @samp{%^C} 8705 Interactive selection of which kill or clip to use. 8706 8707 @item @samp{%^L} 8708 Like @samp{%^C}, but insert as link. 8709 8710 @item @samp{%^@{PROP@}p} 8711 Prompt the user for a value for property @var{PROP}. You may 8712 specify a default value with @samp{%^@{PROP|default@}}. 8713 8714 @item @samp{%^@{PROMPT@}} 8715 Prompt the user for a string and replace this sequence with it. You 8716 may specify a default value and a completion table with 8717 @samp{%^@{prompt|default|completion2|completion3...@}}. The arrow keys 8718 access a prompt-specific history. 8719 8720 @item @samp{%\N} 8721 Insert the text entered at the @var{N}th @samp{%^@{PROMPT@}}, where 8722 @var{N} is a number, starting from 1. 8723 8724 @item @samp{%?} 8725 After completing the template, position point here. 8726 @end table 8727 8728 @vindex org-store-link-props 8729 For specific link types, the following keywords are defined@footnote{ If 8730 you define your own link types (see @ref{Adding Hyperlink Types}), any 8731 property you store with @code{org-store-link-props} can be accessed in 8732 capture templates in a similar way.}: 8733 8734 @vindex org-link-from-user-regexp 8735 @multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 8736 @headitem Link type 8737 @tab Available keywords 8738 @item bbdb 8739 @tab @samp{%:name}, @samp{%:company} 8740 @item irc 8741 @tab @samp{%:server}, @samp{%:port}, @samp{%:nick} 8742 @item mh, rmail 8743 @tab @samp{%:type}, @samp{%:subject}, @samp{%:message-id} 8744 @item 8745 @tab @samp{%:from}, @samp{%:fromname}, @samp{%:fromaddress} 8746 @item 8747 @tab @samp{%:to}, @samp{%:toname}, @samp{%:toaddress} 8748 @item 8749 @tab @samp{%:date} (message date header field) 8750 @item 8751 @tab @samp{%:date-timestamp} (date as active timestamp) 8752 @item 8753 @tab @samp{%:date-timestamp-inactive} (date as inactive timestamp) 8754 @item 8755 @tab @samp{%:fromto} (either ``to NAME'' or ``from NAME'')@footnote{This is always the other, not the user. See the variable 8756 @code{org-link-from-user-regexp}.} 8757 @item gnus 8758 @tab @samp{%:group}, for messages also all email fields 8759 @item w3, w3m 8760 @tab @samp{%:url} 8761 @item info 8762 @tab @samp{%:file}, @samp{%:node} 8763 @item calendar 8764 @tab @samp{%:date} 8765 @item org-protocol 8766 @tab @samp{%:link}, @samp{%:description}, @samp{%:annotation} 8767 @end multitable 8768 8769 @node Templates in contexts 8770 @subsubsection Templates in contexts 8771 8772 @vindex org-capture-templates-contexts 8773 To control whether a capture template should be accessible from 8774 a specific context, you can customize 8775 @code{org-capture-templates-contexts}. Let's say, for example, that you 8776 have a capture template ``p'' for storing Gnus emails containing 8777 patches. Then you would configure this option like this: 8778 8779 @lisp 8780 (setq org-capture-templates-contexts 8781 '(("p" ((in-mode . "message-mode"))))) 8782 @end lisp 8783 8784 You can also tell that the command key @kbd{p} should refer to 8785 another template. In that case, add this command key like this: 8786 8787 @lisp 8788 (setq org-capture-templates-contexts 8789 '(("p" "q" ((in-mode . "message-mode"))))) 8790 @end lisp 8791 8792 See the docstring of the variable for more information. 8793 8794 @node Attachments 8795 @section Attachments 8796 8797 @cindex attachments 8798 8799 It is often useful to associate reference material with an outline 8800 node. Small chunks of plain text can simply be stored in the subtree 8801 of a project. Hyperlinks (see @ref{Hyperlinks}) can establish associations 8802 with files that live elsewhere on a local, or even remote, computer, 8803 like emails or source code files belonging to a project. 8804 8805 Another method is @emph{attachments}, which are files located in a 8806 directory belonging to an outline node. Org uses directories either 8807 named by a unique ID of each entry, or by a @samp{DIR} property. 8808 8809 @menu 8810 * Attachment defaults and dispatcher:: How to access attachment commands 8811 * Attachment options:: Configuring the attachment system 8812 * Attachment links:: Hyperlink access to attachments 8813 * Automatic version-control with Git:: Everything safely stored away 8814 * Attach from Dired:: Using dired to select an attachment 8815 @end menu 8816 8817 @node Attachment defaults and dispatcher 8818 @subsection Attachment defaults and dispatcher 8819 8820 By default, Org attach uses ID properties when adding attachments to 8821 outline nodes. This makes working with attachments fully automated. 8822 There is no decision needed for folder-name or location. ID-based 8823 directories are by default located in the @samp{data/} directory, which 8824 lives in the same directory where your Org file lives@footnote{ If you move 8825 entries or Org files from one directory to another, you may want to 8826 configure @code{org-attach-id-dir} to contain an absolute path.}. 8827 8828 When attachments are made using @code{org-attach} a default tag @samp{ATTACH} is 8829 added to the node that gets the attachments. 8830 8831 For more control over the setup, see @ref{Attachment options}. 8832 8833 The following commands deal with attachments: 8834 8835 @table @asis 8836 @item @kbd{C-c C-a} (@code{org-attach}) 8837 @kindex C-c C-a 8838 @findex org-attach 8839 The dispatcher for commands related to the attachment system. After 8840 these keys, a list of commands is displayed and you must press an 8841 additional key to select a command: 8842 8843 @table @asis 8844 @item @kbd{a} (@code{org-attach-attach}) 8845 @kindex C-c C-a a 8846 @findex org-attach-attach 8847 @vindex org-attach-method 8848 Select a file and move it into the task's attachment directory. 8849 The file is copied, moved, or linked, depending on 8850 @code{org-attach-method}. Note that hard links are not supported on 8851 all systems. 8852 8853 @item @kbd{c}/@kbd{m}/@kbd{l} 8854 @kindex C-c C-a c 8855 @kindex C-c C-a m 8856 @kindex C-c C-a l 8857 Attach a file using the copy/move/link method. Note that hard 8858 links are not supported on all systems. 8859 8860 @item @kbd{b} (@code{org-attach-buffer}) 8861 @kindex C-c C-a b 8862 @findex org-attach-buffer 8863 Select a buffer and save it as a file in the task's attachment 8864 directory. 8865 8866 @item @kbd{n} (@code{org-attach-new}) 8867 @kindex C-c C-a n 8868 @findex org-attach-new 8869 Create a new attachment as an Emacs buffer. 8870 8871 @item @kbd{z} (@code{org-attach-sync}) 8872 @kindex C-c C-a z 8873 @findex org-attach-sync 8874 Synchronize the current task with its attachment directory, in 8875 case you added attachments yourself. 8876 8877 @item @kbd{o} (@code{org-attach-open}) 8878 @kindex C-c C-a o 8879 @findex org-attach-open 8880 @vindex org-file-apps 8881 Open current task's attachment. If there is more than one, prompt 8882 for a file name first. Opening follows the rules set by 8883 @code{org-file-apps}. For more details, see the information on 8884 following hyperlinks (see @ref{Handling Links}). 8885 8886 @item @kbd{O} (@code{org-attach-open-in-emacs}) 8887 @kindex C-c C-a O 8888 @findex org-attach-open-in-emacs 8889 Also open the attachment, but force opening the file in Emacs. 8890 8891 @item @kbd{f} (@code{org-attach-reveal}) 8892 @kindex C-c C-a f 8893 @findex org-attach-reveal 8894 Open the current task's attachment directory. 8895 8896 @item @kbd{F} (@code{org-attach-reveal-in-emacs}) 8897 @kindex C-c C-a F 8898 @findex org-attach-reveal-in-emacs 8899 Also open the directory, but force using Dired in Emacs. 8900 8901 @item @kbd{d} (@code{org-attach-delete-one}) 8902 @kindex C-c C-a d 8903 Select and delete a single attachment. 8904 8905 @item @kbd{D} (@code{org-attach-delete-all}) 8906 @kindex C-c C-a D 8907 Delete all of a task's attachments. A safer way is to open the 8908 directory in Dired and delete from there. 8909 8910 @item @kbd{s} (@code{org-attach-set-directory}) 8911 @kindex C-c C-a s 8912 @cindex @samp{DIR}, property 8913 Set a specific directory as the entry's attachment directory. 8914 This works by putting the directory path into the @samp{DIR} 8915 property. 8916 8917 @item @kbd{S} (@code{org-attach-unset-directory}) 8918 @kindex C-c C-a S 8919 @cindex @samp{DIR}, property 8920 Remove the attachment directory. This command removes the @samp{DIR} 8921 property and asks the user to either move content inside that 8922 folder, if an @samp{ID} property is set, delete the content, or to 8923 leave the attachment directory as is but no longer attached to the 8924 outline node. 8925 @end table 8926 @end table 8927 8928 @node Attachment options 8929 @subsection Attachment options 8930 8931 There are a couple of options for attachments that are worth 8932 mentioning. 8933 8934 @table @asis 8935 @item @code{org-attach-id-dir} 8936 @vindex org-attach-id-dir 8937 The directory where attachments are stored when @samp{ID} is used as 8938 method. 8939 8940 @item @code{org-attach-dir-relative} 8941 @vindex org-attach-dir-relative 8942 When setting the @samp{DIR} property on a node using @kbd{C-c C-a s} 8943 (@code{org-attach-set-directory}), absolute links are entered by default. 8944 This option changes that to relative links. 8945 8946 @item @code{org-attach-use-inheritance} 8947 @vindex org-attach-use-inheritance 8948 By default folders attached to an outline node are inherited from 8949 parents according to @code{org-use-property-inheritance}. If one instead 8950 want to set inheritance specifically for Org attach that can be done 8951 using @code{org-attach-use-inheritance}. Inheriting documents through 8952 the node hierarchy makes a lot of sense in most cases. Especially 8953 when using attachment links (see @ref{Attachment links}). The following 8954 example shows one use case for attachment inheritance: 8955 8956 @example 8957 * Chapter A ... 8958 :PROPERTIES: 8959 :DIR: Chapter A/ 8960 :END: 8961 ** Introduction 8962 Some text 8963 8964 #+NAME: Image 1 8965 [[attachment:image 1.jpg]] 8966 @end example 8967 8968 Without inheritance one would not be able to resolve the link to 8969 @samp{image 1.jpg}, since the link is inside a sub-heading to @samp{Chapter 8970 A}. 8971 8972 Inheritance works the same way for both @samp{ID} and @samp{DIR} property. If 8973 both properties are defined on the same headline then @samp{DIR} takes 8974 precedence. This is also true if inheritance is enabled. If @samp{DIR} 8975 is inherited from a parent node in the outline, that property still 8976 takes precedence over an @samp{ID} property defined on the node itself. 8977 8978 @item @code{org-attach-method} 8979 @vindex org-attach-method 8980 When attaching files using the dispatcher @kbd{C-c C-a} it 8981 defaults to copying files. The behavior can be changed by 8982 customizing @code{org-attach-method}. Options are Copy, Move/Rename, 8983 Hard link or Symbolic link. 8984 8985 @item @code{org-attach-preferred-new-method} 8986 @vindex org-attach-preferred-new-method 8987 This customization lets you choose the default way to attach to 8988 nodes without existing @samp{ID} and @samp{DIR} property. It defaults to @code{id} 8989 but can also be set to @code{dir}, @code{ask} or @code{nil}. 8990 8991 @item @code{org-attach-archive-delete} 8992 @vindex org-attach-archive-delete 8993 Configure this to determine if attachments should be deleted or not 8994 when a subtree that has attachments is archived. 8995 8996 @item @code{org-attach-auto-tag} 8997 @vindex org-attach-auto-tag 8998 When attaching files to a heading it will be assigned a tag 8999 according to what is set here. 9000 9001 @item @code{org-attach-id-to-path-function-list} 9002 @vindex org-attach-id-to-path-function-list 9003 When @samp{ID} is used for attachments, the ID is parsed into a part of a 9004 directory-path. See @code{org-attach-id-uuid-folder-format} for the 9005 default function. Define a new one and add it as first element in 9006 @code{org-attach-id-to-path-function-list} if you want the folder 9007 structure in any other way. All functions in this list will be 9008 tried when resolving existing ID's into paths, to maintain backward 9009 compatibility with existing folders in your system. 9010 9011 @item @code{org-attach-store-link-p} 9012 @vindex org-attach-store-link-p 9013 Stores a link to the file that is being attached. The link is 9014 stored in @code{org-stored-links} for later insertion with @kbd{C-c C-l} (see @ref{Handling Links}). Depending on what option is set in 9015 @code{org-attach-store-link-p}, the link is stored to either the original 9016 location as a file link, the attachment location as an attachment 9017 link or to the attachment location as a file link. 9018 9019 @item @code{org-attach-commands} 9020 @vindex org-attach-commands 9021 List of all commands used in the attach dispatcher. 9022 9023 @item @code{org-attach-expert} 9024 @vindex org-attach-expert 9025 Do not show the splash buffer with the attach dispatcher when 9026 @code{org-attach-expert} is set to non-@code{nil}. 9027 @end table 9028 9029 See customization group @samp{Org Attach} if you want to change the 9030 default settings. 9031 9032 @node Attachment links 9033 @subsection Attachment links 9034 9035 Attached files and folders can be referenced using attachment links. 9036 This makes it easy to refer to the material added to an outline node. 9037 Especially if it was attached using the unique ID of the entry! 9038 9039 @example 9040 * TODO Some task 9041 :PROPERTIES: 9042 :ID: 95d50008-c12e-479f-a4f2-cc0238205319 9043 :END: 9044 See attached document for more information: [[attachment:info.org]] 9045 @end example 9046 9047 See @ref{External Links} for more information about these links. 9048 9049 @node Automatic version-control with Git 9050 @subsection Automatic version-control with Git 9051 9052 If the directory attached to an outline node is a Git repository, Org 9053 can be configured to automatically commit changes to that repository 9054 when it sees them. 9055 9056 To make Org mode take care of versioning of attachments for you, add 9057 the following to your Emacs config: 9058 9059 @lisp 9060 (require 'org-attach-git) 9061 @end lisp 9062 9063 @node Attach from Dired 9064 @subsection Attach from Dired 9065 9066 @cindex attach from Dired 9067 @findex org-attach-dired-to-subtree 9068 9069 It is possible to attach files to a subtree from a Dired buffer. To 9070 use this feature, have one window in Dired mode containing the file(s) 9071 to be attached and another window with point in the subtree that shall 9072 get the attachments. In the Dired window, with point on a file, 9073 @kbd{M-x org-attach-dired-to-subtree} attaches the file to the 9074 subtree using the attachment method set by variable 9075 @code{org-attach-method}. When files are marked in the Dired window then 9076 all marked files get attached. 9077 9078 Add the following lines to the Emacs init file to have @kbd{C-c C-x a} attach files in Dired buffers. 9079 9080 @lisp 9081 (add-hook 'dired-mode-hook 9082 (lambda () 9083 (define-key dired-mode-map 9084 (kbd "C-c C-x a") 9085 #'org-attach-dired-to-subtree))) 9086 @end lisp 9087 9088 The following code shows how to bind the previous command with 9089 a specific attachment method. 9090 9091 @lisp 9092 (add-hook 'dired-mode-hook 9093 (lambda () 9094 (define-key dired-mode-map (kbd "C-c C-x c") 9095 (lambda () 9096 (interactive) 9097 (let ((org-attach-method 'cp)) 9098 (call-interactively #'org-attach-dired-to-subtree)))))) 9099 @end lisp 9100 9101 @node RSS Feeds 9102 @section RSS Feeds 9103 9104 @cindex RSS feeds 9105 @cindex Atom feeds 9106 9107 Org can add and change entries based on information found in RSS feeds 9108 and Atom feeds. You could use this to make a task out of each new 9109 podcast in a podcast feed. Or you could use a phone-based 9110 note-creating service on the web to import tasks into Org. To access 9111 feeds, configure the variable @code{org-feed-alist}. The docstring of this 9112 variable has detailed information. With the following 9113 9114 @lisp 9115 (setq org-feed-alist 9116 '(("Slashdot" 9117 "https://rss.slashdot.org/Slashdot/slashdot" 9118 "~/txt/org/feeds.org" "Slashdot Entries"))) 9119 @end lisp 9120 9121 @noindent 9122 new items from the feed provided by @samp{rss.slashdot.org} result in new 9123 entries in the file @samp{~/org/feeds.org} under the heading @samp{Slashdot 9124 Entries}, whenever the following command is used: 9125 9126 @table @asis 9127 @item @kbd{C-c C-x g} (@code{org-feed-update-all}) 9128 @kindex C-c C-x g 9129 Collect items from the feeds configured in @code{org-feed-alist} and act 9130 upon them. 9131 9132 @item @kbd{C-c C-x G} (@code{org-feed-goto-inbox}) 9133 @kindex C-c C-x G 9134 Prompt for a feed name and go to the inbox configured for this feed. 9135 @end table 9136 9137 Under the same headline, Org creates a drawer @samp{FEEDSTATUS} in which it 9138 stores information about the status of items in the feed, to avoid 9139 adding the same item several times. 9140 9141 For more information, including how to read atom feeds, see 9142 @samp{org-feed.el} and the docstring of @code{org-feed-alist}. 9143 9144 @node Agenda Views 9145 @chapter Agenda Views 9146 9147 @cindex agenda views 9148 9149 Due to the way Org works, TODO items, time-stamped items, and tagged 9150 headlines can be scattered throughout a file or even a number of 9151 files. To get an overview of open action items, or of events that are 9152 important for a particular date, this information must be collected, 9153 sorted and displayed in an organized way. 9154 9155 Org can select items based on various criteria and display them in 9156 a separate buffer. Six different view types are provided: 9157 9158 @itemize 9159 @item 9160 an @emph{agenda} that is like a calendar and shows information for 9161 specific dates, 9162 9163 @item 9164 a @emph{TODO list} that covers all unfinished action items, 9165 9166 @item 9167 a @emph{match view}, showings headlines based on the tags, properties, 9168 and TODO state associated with them, 9169 9170 @item 9171 a @emph{text search view} that shows all entries from multiple files that 9172 contain specified keywords, 9173 9174 @item 9175 a @emph{stuck projects view} showing projects that currently do not move 9176 along, and 9177 9178 @item 9179 @emph{custom views} that are special searches and combinations of 9180 different views. 9181 @end itemize 9182 9183 The extracted information is displayed in a special @emph{agenda buffer}. 9184 This buffer is read-only, but provides commands to visit the 9185 corresponding locations in the original Org files, and even to edit 9186 these files remotely. 9187 9188 @vindex org-agenda-skip-comment-trees 9189 @vindex org-agenda-skip-archived-trees 9190 @cindex commented entries, in agenda views 9191 @cindex archived entries, in agenda views 9192 By default, the report ignores commented (see @ref{Comment Lines}) and 9193 archived (see @ref{Internal archiving}) entries. You can override this by 9194 setting @code{org-agenda-skip-comment-trees} and 9195 @code{org-agenda-skip-archived-trees} to @code{nil}. 9196 9197 @vindex org-agenda-window-setup 9198 @vindex org-agenda-restore-windows-after-quit 9199 Two variables control how the agenda buffer is displayed and whether 9200 the window configuration is restored when the agenda exits: 9201 @code{org-agenda-window-setup} and @code{org-agenda-restore-windows-after-quit}. 9202 9203 @menu 9204 * Agenda Files:: Files being searched for agenda information. 9205 * Agenda Dispatcher:: Keyboard access to agenda views. 9206 * Built-in Agenda Views:: What is available out of the box? 9207 * Presentation and Sorting:: How agenda items are prepared for display. 9208 * Agenda Commands:: Remote editing of Org trees. 9209 * Custom Agenda Views:: Defining special searches and views. 9210 * Exporting Agenda Views:: Writing a view to a file. 9211 * Agenda Column View:: Using column view for collected entries. 9212 @end menu 9213 9214 @node Agenda Files 9215 @section Agenda Files 9216 9217 @cindex agenda files 9218 @cindex files for agenda 9219 9220 @vindex org-agenda-files 9221 The information to be shown is normally collected from all @emph{agenda 9222 files}, the files listed in the variable @code{org-agenda-files}@footnote{ If 9223 the value of that variable is not a list, but a single file name, then 9224 the list of agenda files in maintained in that external file.}. If a 9225 directory is part of this list, all files with the extension @samp{.org} in 9226 this directory are part of the list. 9227 9228 Thus, even if you only work with a single Org file, that file should 9229 be put into the list@footnote{ When using the dispatcher, pressing 9230 @kbd{<} before selecting a command actually limits the command to 9231 the current file, and ignores @code{org-agenda-files} until the next 9232 dispatcher command.}. You can customize @code{org-agenda-files}, but the 9233 easiest way to maintain it is through the following commands 9234 9235 @table @asis 9236 @item @kbd{C-c [} (@code{org-agenda-file-to-front}) 9237 @kindex C-c [ 9238 @findex org-agenda-file-to-front 9239 @cindex files, adding to agenda list 9240 Add current file to the list of agenda files. The file is added to 9241 the front of the list. If it was already in the list, it is moved 9242 to the front. With a prefix argument, file is added/moved to the 9243 end. 9244 9245 @item @kbd{C-c ]} (@code{org-remove-file}) 9246 @kindex C-c ] 9247 @findex org-remove-file 9248 Remove current file from the list of agenda files. 9249 9250 @item @kbd{C-'} 9251 @itemx @kbd{C-,} (@code{org-cycle-agenda-files}) 9252 @kindex C-' 9253 @kindex C-, 9254 @findex org-cycle-agenda-files 9255 @cindex cycling, of agenda files 9256 Cycle through agenda file list, visiting one file after the other. 9257 9258 @item @kbd{M-x org-switchb} 9259 @findex org-switchb 9260 Command to use an Iswitchb-like interface to switch to and between 9261 Org buffers. 9262 @end table 9263 9264 @noindent 9265 The Org menu contains the current list of files and can be used to 9266 visit any of them. 9267 9268 If you would like to focus the agenda temporarily on a file not in 9269 this list, or on just one file in the list, or even on only a subtree 9270 in a file, then this can be done in different ways. For a single 9271 agenda command, you may press @kbd{<} once or several times in 9272 the dispatcher (see @ref{Agenda Dispatcher}). To restrict the agenda 9273 scope for an extended period, use the following commands: 9274 9275 @table @asis 9276 @item @kbd{C-c C-x <} (@code{org-agenda-set-restriction-lock}) 9277 @kindex C-c C-x < 9278 @findex org-agenda-set-restriction-lock 9279 Restrict the agenda to the current subtree. If there already is 9280 a restriction at point, remove it. When called with a universal 9281 prefix argument or with point before the first headline in a file, 9282 set the agenda scope to the entire file. This restriction remains 9283 in effect until removed with @kbd{C-c C-x >}, or by typing 9284 either @kbd{<} or @kbd{>} in the agenda dispatcher. If 9285 there is a window displaying an agenda view, the new restriction 9286 takes effect immediately. 9287 9288 @item @kbd{C-c C-x >} (@code{org-agenda-remove-restriction-lock}) 9289 @kindex C-c C-x > 9290 @findex org-agenda-remove-restriction-lock 9291 Remove the restriction created by @kbd{C-c C-x <}. 9292 @end table 9293 9294 When working with Speedbar, you can use the following commands in the 9295 Speedbar frame: 9296 9297 @table @asis 9298 @item @kbd{<} (@code{org-speedbar-set-agenda-restriction}) 9299 @findex org-speedbar-set-agenda-restriction 9300 Restrict the agenda to the item---either an Org file or a subtree in 9301 such a file---at point in the Speedbar frame. If agenda is already 9302 restricted there, remove the restriction. If there is a window 9303 displaying an agenda view, the new restriction takes effect 9304 immediately. 9305 9306 @item @kbd{>} (@code{org-agenda-remove-restriction-lock}) 9307 @findex org-agenda-remove-restriction-lock 9308 Remove the restriction. 9309 @end table 9310 9311 @node Agenda Dispatcher 9312 @section The Agenda Dispatcher 9313 9314 @cindex agenda dispatcher 9315 @cindex dispatching agenda commands 9316 9317 The views are created through a dispatcher, accessible with @kbd{M-x org-agenda}, or, better, bound to a global key (see @ref{Activation}). 9318 It displays a menu from which an additional letter is required to 9319 execute a command. The dispatcher offers the following default 9320 commands: 9321 9322 @table @asis 9323 @item @kbd{a} 9324 Create the calendar-like agenda (see @ref{Weekly/daily agenda}). 9325 9326 @item @kbd{t} 9327 @itemx @kbd{T} 9328 Create a list of all TODO items (see @ref{Global TODO list}). 9329 9330 @item @kbd{m} 9331 @itemx @kbd{M} 9332 Create a list of headlines matching a given expression (see 9333 @ref{Matching tags and properties}). 9334 9335 @item @kbd{s} 9336 @kindex s @r{(Agenda dispatcher)} 9337 Create a list of entries selected by a boolean expression of 9338 keywords and/or regular expressions that must or must not occur in 9339 the entry. 9340 9341 @item @kbd{/} 9342 @kindex / @r{(Agenda dispatcher)} 9343 @vindex org-agenda-text-search-extra-files 9344 Search for a regular expression in all agenda files and additionally 9345 in the files listed in @code{org-agenda-text-search-extra-files}. This 9346 uses the Emacs command @code{multi-occur}. A prefix argument can be used 9347 to specify the number of context lines for each match, the default 9348 is 1. 9349 9350 @item @kbd{#} 9351 Create a list of stuck projects (see @ref{Stuck projects}). 9352 9353 @item @kbd{!} 9354 Configure the list of stuck projects (see @ref{Stuck projects}). 9355 9356 @item @kbd{<} 9357 @kindex < @r{(Agenda dispatcher)} 9358 Restrict an agenda command to the current buffer@footnote{ For backward 9359 compatibility, you can also press @kbd{1} to restrict to the 9360 current buffer.}. If narrowing is in effect restrict to the 9361 narrowed part of the buffer. After pressing @kbd{<}, you still 9362 need to press the character selecting the command. 9363 9364 @item @kbd{< <} 9365 @kindex < < @r{(Agenda dispatcher)} 9366 If there is an active region, restrict the following agenda command 9367 to the region. Otherwise, restrict it to the current subtree@footnote{ 9368 For backward compatibility, you can also press @kbd{0} to 9369 restrict to the current region/subtree.}. After pressing @kbd{< <}, you still need to press the character selecting the command. 9370 9371 @item @kbd{*} 9372 @kindex * @r{(Agenda dispatcher)} 9373 @vindex org-agenda-sticky 9374 @findex org-toggle-sticky-agenda 9375 Toggle sticky agenda views. By default, Org maintains only a single 9376 agenda buffer and rebuilds it each time you change the view, to make 9377 sure everything is always up to date. If you switch between views 9378 often and the build time bothers you, you can turn on sticky agenda 9379 buffers (make this the default by customizing the variable 9380 @code{org-agenda-sticky}). With sticky agendas, the dispatcher only 9381 switches to the selected view, you need to update it by hand with 9382 @kbd{r} or @kbd{g}. You can toggle sticky agenda view any 9383 time with @code{org-toggle-sticky-agenda}. 9384 @end table 9385 9386 You can also define custom commands that are accessible through the 9387 dispatcher, just like the default commands. This includes the 9388 possibility to create extended agenda buffers that contain several 9389 blocks together, for example the weekly agenda, the global TODO list 9390 and a number of special tags matches. See @ref{Custom Agenda Views}. 9391 9392 @node Built-in Agenda Views 9393 @section The Built-in Agenda Views 9394 9395 In this section we describe the built-in views. 9396 9397 @menu 9398 * Weekly/daily agenda:: The calendar page with current tasks. 9399 * Global TODO list:: All unfinished action items. 9400 * Matching tags and properties:: Structured information with fine-tuned search. 9401 * Search view:: Find entries by searching for text. 9402 * Stuck projects:: Find projects you need to review. 9403 @end menu 9404 9405 @node Weekly/daily agenda 9406 @subsection Weekly/daily agenda 9407 9408 @cindex agenda 9409 @cindex weekly agenda 9410 @cindex daily agenda 9411 9412 The purpose of the weekly/daily @emph{agenda} is to act like a page of 9413 a paper agenda, showing all the tasks for the current week or day. 9414 9415 @table @asis 9416 @item @kbd{M-x org-agenda a} (@code{org-agenda-list}) 9417 @kindex a @r{(Agenda dispatcher)} 9418 @findex org-agenda-list 9419 @cindex org-agenda, command 9420 Compile an agenda for the current week from a list of Org files. 9421 The agenda shows the entries for each day. With a numeric prefix 9422 argument@footnote{For backward compatibility, the universal prefix argument 9423 @kbd{C-u} causes all TODO entries to be listed before the agenda. 9424 This feature is deprecated, use the dedicated TODO list, or a block 9425 agenda instead (see @ref{Block agenda}).}---like @kbd{C-u 2 1 M-x org-agenda a}---you may 9426 set the number of days to be displayed. 9427 @end table 9428 9429 @vindex org-agenda-span 9430 @vindex org-agenda-start-day 9431 @vindex org-agenda-start-on-weekday 9432 The default number of days displayed in the agenda is set by the 9433 variable @code{org-agenda-span}. This variable can be set to any number of 9434 days you want to see by default in the agenda, or to a span name, such 9435 a @code{day}, @code{week}, @code{month} or @code{year}. For weekly agendas, the default 9436 is to start on the previous Monday (see 9437 @code{org-agenda-start-on-weekday}). You can also set the start date using 9438 a date shift: @samp{(setq org-agenda-start-day "+10d")} starts the agenda 9439 ten days from today in the future. 9440 9441 Remote editing from the agenda buffer means, for example, that you can 9442 change the dates of deadlines and appointments from the agenda buffer. 9443 The commands available in the Agenda buffer are listed in @ref{Agenda Commands}. 9444 9445 @anchor{Calendar/Diary integration} 9446 @subsubheading Calendar/Diary integration 9447 9448 @cindex calendar integration 9449 @cindex diary integration 9450 9451 Emacs contains the calendar and diary by Edward@tie{}M@.@tie{}Reingold. The 9452 calendar displays a three-month calendar with holidays from different 9453 countries and cultures. The diary allows you to keep track of 9454 anniversaries, lunar phases, sunrise/set, recurrent appointments 9455 (weekly, monthly) and more. In this way, it is quite complementary to 9456 Org. It can be very useful to combine output from Org with the diary. 9457 9458 In order to include entries from the Emacs diary into Org mode's 9459 agenda, you only need to customize the variable 9460 9461 @lisp 9462 (setq org-agenda-include-diary t) 9463 @end lisp 9464 9465 @noindent 9466 After that, everything happens automatically. All diary entries 9467 including holidays, anniversaries, etc., are included in the agenda 9468 buffer created by Org mode. @kbd{@key{SPC}}, @kbd{@key{TAB}}, and 9469 @kbd{@key{RET}} can be used from the agenda buffer to jump to the diary 9470 file in order to edit existing diary entries. The @kbd{i} 9471 command to insert new entries for the current date works in the agenda 9472 buffer, as well as the commands @kbd{S}, @kbd{M}, and 9473 @kbd{C} to display Sunrise/Sunset times, show lunar phases and to 9474 convert to other calendars, respectively. @kbd{c} can be used to 9475 switch back and forth between calendar and agenda. 9476 9477 If you are using the diary only for expression entries and holidays, 9478 it is faster to not use the above setting, but instead to copy or even 9479 move the entries into an Org file. Org mode evaluates diary-style 9480 expression entries, and does it faster because there is no overhead 9481 for first creating the diary display. Note that the expression 9482 entries must start at the left margin, no whitespace is allowed before 9483 them, as seen in the following segment of an Org file:@footnote{ The 9484 variable @code{org-anniversary} used in the example is just like 9485 @code{diary-anniversary}, but the argument order is always according to ISO 9486 and therefore independent of the value of @code{calendar-date-style}.} 9487 9488 @example 9489 * Holidays 9490 :PROPERTIES: 9491 :CATEGORY: Holiday 9492 :END: 9493 %%(org-calendar-holiday) ; special function for holiday names 9494 9495 * Birthdays 9496 :PROPERTIES: 9497 :CATEGORY: Ann 9498 :END: 9499 %%(org-anniversary 1956 5 14) Arthur Dent is %d years old 9500 %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old 9501 @end example 9502 9503 @anchor{Anniversaries from BBDB} 9504 @subsubheading Anniversaries from BBDB 9505 9506 @cindex BBDB, anniversaries 9507 @cindex anniversaries, from BBDB 9508 9509 @findex org-bbdb-anniversaries 9510 If you are using the Insidious Big Brother Database to store your 9511 contacts, you very likely prefer to store anniversaries in BBDB rather 9512 than in a separate Org or diary file. Org supports this and can show 9513 BBDB anniversaries as part of the agenda. All you need to do is to 9514 add the following to one of your agenda files: 9515 9516 @example 9517 * Anniversaries 9518 :PROPERTIES: 9519 :CATEGORY: Anniv 9520 :END: 9521 %%(org-bbdb-anniversaries) 9522 @end example 9523 9524 You can then go ahead and define anniversaries for a BBDB record. 9525 Basically, you need a field named @samp{anniversary} for the BBDB record 9526 which contains the date in the format @samp{YYYY-MM-DD} or @samp{MM-DD}, 9527 followed by a space and the class of the anniversary (@samp{birthday}, 9528 @samp{wedding}, or a format string). If you omit the class, it defaults to 9529 @samp{birthday}. Here are a few examples, the header for the file 9530 @samp{ol-bbdb.el} contains more detailed information. 9531 9532 @example 9533 1973-06-22 9534 06-22 9535 1955-08-02 wedding 9536 2008-04-14 %s released version 6.01 of Org mode, %d years ago 9537 @end example 9538 9539 After a change to BBDB, or for the first agenda display during an 9540 Emacs session, the agenda display suffers a short delay as Org updates 9541 its hash with anniversaries. However, from then on things will be 9542 very fast, much faster in fact than a long list of 9543 @samp{%%(diary-anniversary)} entries in an Org or Diary file. 9544 9545 @findex org-bbdb-anniversaries-future 9546 If you would like to see upcoming anniversaries with a bit of 9547 forewarning, you can use the following instead: 9548 9549 @example 9550 * Anniversaries 9551 :PROPERTIES: 9552 :CATEGORY: Anniv 9553 :END: 9554 %%(org-bbdb-anniversaries-future 3) 9555 @end example 9556 9557 That will give you three days' warning: on the anniversary date itself 9558 and the two days prior. The argument is optional: if omitted, it 9559 defaults to 7. 9560 9561 @anchor{Appointment reminders} 9562 @subsubheading Appointment reminders 9563 9564 @cindex @file{appt.el} 9565 @cindex appointment reminders 9566 @cindex appointment 9567 @cindex reminders 9568 9569 @cindex APPT_WARNTIME, keyword 9570 Org can interact with Emacs appointments notification facility. To 9571 add the appointments of your agenda files, use the command 9572 @code{org-agenda-to-appt}. This command lets you filter through the list 9573 of your appointments and add only those belonging to a specific 9574 category or matching a regular expression. It also reads 9575 a @samp{APPT_WARNTIME} property which overrides the value of 9576 @code{appt-message-warning-time} for this appointment. See the docstring 9577 for details. 9578 9579 @node Global TODO list 9580 @subsection The global TODO list 9581 9582 @cindex global TODO list 9583 @cindex TODO list, global 9584 9585 The global TODO list contains all unfinished TODO items formatted and 9586 collected into a single place. 9587 9588 @table @asis 9589 @item @kbd{M-x org-agenda t} (@code{org-todo-list}) 9590 @kindex t @r{(Agenda dispatcher)} 9591 @findex org-todo-list 9592 Show the global TODO list. This collects the TODO items from all 9593 agenda files (see @ref{Agenda Views}) into a single buffer. By default, 9594 this lists items with a state that is not a DONE state. The buffer 9595 is in Agenda mode, so there are commands to examine and manipulate 9596 the TODO entries directly from that buffer (see @ref{Agenda Commands}). 9597 9598 @item @kbd{M-x org-agenda T} (@code{org-todo-list}) 9599 @kindex T @r{(Agenda dispatcher)} 9600 @findex org-todo-list 9601 @cindex TODO keyword matching 9602 @vindex org-todo-keywords 9603 Like the above, but allows selection of a specific TODO keyword. 9604 You can also do this by specifying a prefix argument to 9605 @kbd{t}. You are prompted for a keyword, and you may also 9606 specify several keywords by separating them with @samp{|} as the boolean 9607 OR operator. With a numeric prefix, the Nth keyword in 9608 @code{org-todo-keywords} is selected. 9609 9610 @kindex r 9611 The @kbd{r} key in the agenda buffer regenerates it, and you 9612 can give a prefix argument to this command to change the selected 9613 TODO keyword, for example @kbd{3 r}. If you often need 9614 a search for a specific keyword, define a custom command for it (see 9615 @ref{Agenda Dispatcher}). 9616 9617 Matching specific TODO keywords can also be done as part of a tags 9618 search (see @ref{Tag Searches}). 9619 @end table 9620 9621 Remote editing of TODO items means that you can change the state of 9622 a TODO entry with a single key press. The commands available in the 9623 TODO list are described in @ref{Agenda Commands}. 9624 9625 @cindex sublevels, inclusion into TODO list 9626 Normally the global TODO list simply shows all headlines with TODO 9627 keywords. This list can become very long. There are two ways to keep 9628 it more compact: 9629 9630 @itemize 9631 @item 9632 @vindex org-agenda-todo-ignore-scheduled 9633 @vindex org-agenda-todo-ignore-deadlines 9634 @vindex org-agenda-todo-ignore-timestamp 9635 @vindex org-agenda-todo-ignore-with-date 9636 Some people view a TODO item that has been @emph{scheduled} for execution 9637 or have a @emph{deadline} (see @ref{Timestamps}) as no longer @emph{open}. 9638 Configure the variables @code{org-agenda-todo-ignore-scheduled} to 9639 exclude some or all scheduled items from the global TODO list, 9640 @code{org-agenda-todo-ignore-deadlines} to exclude some or all items with 9641 a deadline set, @code{org-agenda-todo-ignore-timestamp} to exclude some 9642 or all items with an active timestamp other than a DEADLINE or 9643 a SCHEDULED timestamp and/or @code{org-agenda-todo-ignore-with-date} to 9644 exclude items with at least one active timestamp. 9645 9646 @item 9647 @vindex org-agenda-todo-list-sublevels 9648 TODO items may have sublevels to break up the task into subtasks. 9649 In such cases it may be enough to list only the highest level TODO 9650 headline and omit the sublevels from the global list. Configure the 9651 variable @code{org-agenda-todo-list-sublevels} to get this behavior. 9652 @end itemize 9653 9654 @node Matching tags and properties 9655 @subsection Matching tags and properties 9656 9657 @cindex matching, of tags 9658 @cindex matching, of properties 9659 @cindex tags view 9660 @cindex match view 9661 9662 If headlines in the agenda files are marked with @emph{tags} (see @ref{Tags}), 9663 or have properties (see @ref{Properties and Columns}), you can select 9664 headlines based on this metadata and collect them into an agenda 9665 buffer. The match syntax described here also applies when creating 9666 sparse trees with @kbd{C-c / m}. 9667 9668 @table @asis 9669 @item @kbd{M-x org-agenda m} (@code{org-tags-view}) 9670 @kindex m @r{(Agenda dispatcher)} 9671 @findex org-tags-view 9672 Produce a list of all headlines that match a given set of tags. The 9673 command prompts for a selection criterion, which is a boolean logic 9674 expression with tags, like @samp{+work+urgent-withboss} or @samp{work|home} 9675 (see @ref{Tags}). If you often need a specific search, define a custom 9676 command for it (see @ref{Agenda Dispatcher}). 9677 9678 @item @kbd{M-x org-agenda M} (@code{org-tags-view}) 9679 @kindex M @r{(Agenda dispatcher)} 9680 @findex org-tags-view 9681 @vindex org-tags-match-list-sublevels 9682 @vindex org-agenda-tags-todo-honor-ignore-options 9683 Like @kbd{m}, but only select headlines that are also TODO 9684 items and force checking subitems (see the variable 9685 @code{org-tags-match-list-sublevels}). To exclude scheduled/deadline 9686 items, see the variable @code{org-agenda-tags-todo-honor-ignore-options}. 9687 Matching specific TODO keywords together with a tags match is also 9688 possible, see @ref{Tag Searches}. 9689 @end table 9690 9691 The commands available in the tags list are described in @ref{Agenda Commands}. 9692 9693 @cindex boolean logic, for agenda searches 9694 A search string can use Boolean operators @samp{&} for AND and @samp{|} for OR@. 9695 @samp{&} binds more strongly than @samp{|}. Parentheses are currently not 9696 implemented. Each element in the search is either a tag, a regular 9697 expression matching tags, or an expression like @samp{PROPERTY OPERATOR 9698 VALUE} with a comparison operator, accessing a property value. Each 9699 element may be preceded by @samp{-} to select against it, and @samp{+} is 9700 syntactic sugar for positive selection. The AND operator @samp{&} is 9701 optional when @samp{+} or @samp{-} is present. Here are some examples, using 9702 only tags. 9703 9704 @table @asis 9705 @item @samp{+work-boss} 9706 Select headlines tagged @samp{work}, but discard those also tagged 9707 @samp{boss}. 9708 9709 @item @samp{work|laptop} 9710 Selects lines tagged @samp{work} or @samp{laptop}. 9711 9712 @item @samp{work|laptop+night} 9713 Like before, but require the @samp{laptop} lines to be tagged also 9714 @samp{night}. 9715 @end table 9716 9717 @cindex regular expressions, with tags search 9718 Instead of a tag, you may also specify a regular expression enclosed 9719 in curly braces (see @ref{Regular Expressions}). For example, 9720 @samp{work+@{^boss.*@}} matches headlines that contain the tag @samp{:work:} and 9721 any tag @emph{starting} with @samp{boss}. 9722 9723 @cindex group tags, as regular expressions 9724 Group tags (see @ref{Tag Hierarchy}) are expanded as regular expressions. 9725 E.g., if @samp{work} is a group tag for the group @samp{:work:lab:conf:}, then 9726 searching for @samp{work} also searches for @samp{@{\(?:work\|lab\|conf\)@}} and 9727 searching for @samp{-work} searches for all headlines but those with one of 9728 the tags in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}). 9729 9730 @cindex TODO keyword matching, with tags search 9731 @cindex level, for tags/property match 9732 @cindex category, for tags/property match 9733 @vindex org-odd-levels-only 9734 You may also test for properties (see @ref{Properties and Columns}) at the 9735 same time as matching tags. The properties may be real properties, or 9736 special properties that represent other metadata (see @ref{Special Properties}). For example, the property @samp{TODO} represents the TODO 9737 keyword of the entry. Or, the property @samp{LEVEL} represents the level 9738 of an entry. So searching @samp{+LEVEL=3+boss-TODO="DONE"} lists all level 9739 three headlines that have the tag @samp{boss} and are @emph{not} marked with the 9740 TODO keyword @samp{DONE}. In buffers with @code{org-odd-levels-only} set, 9741 @samp{LEVEL} does not count the number of stars, but @samp{LEVEL=2} corresponds 9742 to 3 stars etc. 9743 9744 Here are more examples: 9745 9746 @table @asis 9747 @item @samp{work+TODO="WAITING"} 9748 Select @samp{work}-tagged TODO lines with the specific TODO keyword 9749 @samp{WAITING}. 9750 9751 @item @samp{work+TODO="WAITING"|home+TODO="WAITING"} 9752 Waiting tasks both at work and at home. 9753 @end table 9754 9755 When matching properties, a number of different operators can be used 9756 to test the value of a property. Here is a complex example: 9757 9758 @example 9759 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 9760 +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>" 9761 @end example 9762 9763 @noindent 9764 The type of comparison depends on how the comparison value is written: 9765 9766 @itemize 9767 @item 9768 If the comparison value is a plain number, a numerical comparison is 9769 done, and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=}, @samp{>=}, and 9770 @samp{<>}. 9771 9772 @item 9773 If the comparison value is enclosed in double-quotes, a string 9774 comparison is done, and the same operators are allowed. 9775 9776 @item 9777 If the comparison value is enclosed in double-quotes @emph{and} angular 9778 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are 9779 assumed to be date/time specifications in the standard Org way, and 9780 the comparison is done accordingly. Valid values also include 9781 @samp{"<now>"} for now (including time), @samp{"<today>"}, and @samp{"<tomorrow>"} 9782 for these days at 0:00 hours, i.e., without a time specification. 9783 You can also use strings like @samp{"<+5d>"} or @samp{"<-2m>"} with units @samp{d}, 9784 @samp{w}, @samp{m}, and @samp{y} for day, week, month, and year, respectively. 9785 9786 @item 9787 If the comparison value is enclosed in curly braces, a regexp match 9788 is performed, with @samp{=} meaning that the regexp matches the property 9789 value, and @samp{<>} meaning that it does not match. 9790 @end itemize 9791 9792 So the search string in the example finds entries tagged @samp{work} but 9793 not @samp{boss}, which also have a priority value @samp{A}, a @samp{Coffee} property 9794 with the value @samp{unlimited}, an @samp{EFFORT} property that is numerically 9795 smaller than 2, a @samp{With} property that is matched by the regular 9796 expression @samp{Sarah\|Denny}, and that are scheduled on or after October 9797 11, 2008. 9798 9799 You can configure Org mode to use property inheritance during 9800 a search, but beware that this can slow down searches considerably. 9801 See @ref{Property Inheritance}, for details. 9802 9803 For backward compatibility, and also for typing speed, there is also 9804 a different way to test TODO states in a search. For this, terminate 9805 the tags/property part of the search string (which may include several 9806 terms connected with @samp{|}) with a @samp{/} and then specify a Boolean 9807 expression just for TODO keywords. The syntax is then similar to that 9808 for tags, but should be applied with care: for example, a positive 9809 selection on several TODO keywords cannot meaningfully be combined 9810 with boolean AND@. However, @emph{negative selection} combined with AND can 9811 be meaningful. To make sure that only lines are checked that actually 9812 have any TODO keyword (resulting in a speed-up), use @kbd{M-x org-agenda M}, or equivalently start the TODO part after the slash 9813 with @samp{!}. Using @kbd{M-x org-agenda M} or @samp{/!} does not match 9814 TODO keywords in a DONE state. Examples: 9815 9816 @table @asis 9817 @item @samp{work/WAITING} 9818 Same as @samp{work+TODO="WAITING"}. 9819 9820 @item @samp{work/!-WAITING-NEXT} 9821 Select @samp{work}-tagged TODO lines that are neither @samp{WAITING} nor 9822 @samp{NEXT}. 9823 9824 @item @samp{work/!+WAITING|+NEXT} 9825 Select @samp{work}-tagged TODO lines that are either @samp{WAITING} or @samp{NEXT}. 9826 @end table 9827 9828 @node Search view 9829 @subsection Search view 9830 9831 @cindex search view 9832 @cindex text search 9833 @cindex searching, for text 9834 9835 This agenda view is a general text search facility for Org mode 9836 entries. It is particularly useful to find notes. 9837 9838 @table @asis 9839 @item @kbd{M-x org-agenda s} (@code{org-search-view}) 9840 @kindex s @r{(Agenda dispatcher)} 9841 @findex org-search-view 9842 This is a special search that lets you select entries by matching 9843 a substring or specific words using a boolean logic. 9844 @end table 9845 9846 For example, the search string @samp{computer equipment} matches entries 9847 that contain @samp{computer equipment} as a substring, even if the two 9848 words are separated by more space or a line break. 9849 9850 Search view can also search for specific keywords in the entry, using 9851 Boolean logic. The search string @samp{+computer 9852 +wifi -ethernet -@{8\.11[bg]@}} matches note entries that contain the 9853 keywords @samp{computer} and @samp{wifi}, but not the keyword @samp{ethernet}, and 9854 which are also not matched by the regular expression @samp{8\.11[bg]}, 9855 meaning to exclude both @samp{8.11b} and @samp{8.11g}. The first @samp{+} is 9856 necessary to turn on boolean search, other @samp{+} characters are 9857 optional. For more details, see the docstring of the command 9858 @code{org-search-view}. 9859 9860 You can incrementally and conveniently adjust a boolean search from 9861 the agenda search view with the following keys 9862 9863 @multitable @columnfractions 0.1 0.6 9864 @item @kbd{[} 9865 @tab Add a positive search word 9866 @item @kbd{]} 9867 @tab Add a negative search word 9868 @item @kbd{@{} 9869 @tab Add a positive regular expression 9870 @item @kbd{@}} 9871 @tab Add a negative regular expression 9872 @end multitable 9873 9874 @vindex org-agenda-text-search-extra-files 9875 Note that in addition to the agenda files, this command also searches 9876 the files listed in @code{org-agenda-text-search-extra-files}. 9877 9878 @node Stuck projects 9879 @subsection Stuck projects 9880 9881 @pindex GTD, Getting Things Done 9882 9883 If you are following a system like David Allen's GTD to organize your 9884 work, one of the ``duties'' you have is a regular review to make sure 9885 that all projects move along. A @emph{stuck} project is a project that has 9886 no defined next actions, so it never shows up in the TODO lists Org 9887 mode produces. During the review, you need to identify such projects 9888 and define next actions for them. 9889 9890 @table @asis 9891 @item @kbd{M-x org-agenda #} (@code{org-agenda-list-stuck-projects}) 9892 @kindex # @r{(Agenda dispatcher)} 9893 @findex org-agenda-list-stuck-projects 9894 List projects that are stuck. 9895 9896 @item @kbd{M-x org-agenda !} 9897 @kindex ! @r{(Agenda dispatcher)} 9898 @vindex org-stuck-projects 9899 Customize the variable @code{org-stuck-projects} to define what a stuck 9900 project is and how to find it. 9901 @end table 9902 9903 You almost certainly need to configure this view before it works for 9904 you. The built-in default assumes that all your projects are level-2 9905 headlines, and that a project is not stuck if it has at least one 9906 entry marked with a TODO keyword @samp{TODO} or @samp{NEXT} or @samp{NEXTACTION}. 9907 9908 Let's assume that you, in your own way of using Org mode, identify 9909 projects with a tag @samp{:PROJECT:}, and that you use a TODO keyword 9910 @samp{MAYBE} to indicate a project that should not be considered yet. 9911 Let's further assume that the TODO keyword @samp{DONE} marks finished 9912 projects, and that @samp{NEXT} and @samp{TODO} indicate next actions. The tag 9913 @samp{:@@shop:} indicates shopping and is a next action even without the 9914 NEXT tag. Finally, if the project contains the special word @samp{IGNORE} 9915 anywhere, it should not be listed either. In this case you would 9916 start by identifying eligible projects with a tags/TODO match (see 9917 @ref{Tag Searches}) @samp{+PROJECT/-MAYBE-DONE}, and then check for @samp{TODO}, 9918 @samp{NEXT}, @samp{@@shop}, and @samp{IGNORE} in the subtree to identify projects that 9919 are not stuck. The correct customization for this is: 9920 9921 @lisp 9922 (setq org-stuck-projects 9923 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@shop") 9924 "\\<IGNORE\\>")) 9925 @end lisp 9926 9927 Note that if a project is identified as non-stuck, the subtree of this 9928 entry is searched for stuck projects. 9929 9930 @node Presentation and Sorting 9931 @section Presentation and Sorting 9932 9933 @cindex presentation, of agenda items 9934 9935 @vindex org-agenda-prefix-format 9936 @vindex org-agenda-tags-column 9937 Before displaying items in an agenda view, Org mode visually prepares 9938 the items and sorts them. Each item occupies a single line. The line 9939 starts with a @emph{prefix} that contains the @emph{category} (see @ref{Categories}) 9940 of the item and other important information. You can customize in 9941 which column tags are displayed through @code{org-agenda-tags-column}. You 9942 can also customize the prefix using the option 9943 @code{org-agenda-prefix-format}. This prefix is followed by a cleaned-up 9944 version of the outline headline associated with the item. 9945 9946 @menu 9947 * Categories:: Not all tasks are equal. 9948 * Time-of-day specifications:: How the agenda knows the time. 9949 * Sorting of agenda items:: The order of things. 9950 * Filtering/limiting agenda items:: Dynamically narrow the agenda. 9951 @end menu 9952 9953 @node Categories 9954 @subsection Categories 9955 9956 @cindex category 9957 @cindex @samp{CATEGORY}, keyword 9958 9959 The category is a broad label assigned to each agenda item. By 9960 default, the category is simply derived from the file name, but you 9961 can also specify it with a special line in the buffer, like 9962 this: 9963 9964 @example 9965 #+CATEGORY: Thesis 9966 @end example 9967 9968 9969 @cindex @samp{CATEGORY}, property 9970 If you would like to have a special category for a single entry or 9971 a (sub)tree, give the entry a @samp{CATEGORY} property with the special 9972 category you want to apply as the value. 9973 9974 @vindex org-agenda-category-icon-alist 9975 The display in the agenda buffer looks best if the category is not 9976 longer than 10 characters. You can set up icons for category by 9977 customizing the @code{org-agenda-category-icon-alist} variable. 9978 9979 @node Time-of-day specifications 9980 @subsection Time-of-day specifications 9981 9982 @cindex time-of-day specification 9983 9984 Org mode checks each agenda item for a time-of-day specification. The 9985 time can be part of the timestamp that triggered inclusion into the 9986 agenda, for example 9987 9988 @example 9989 <2005-05-10 Tue 19:00> 9990 @end example 9991 9992 9993 @noindent 9994 Time ranges can be specified with two timestamps: 9995 9996 @example 9997 <2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15> 9998 @end example 9999 10000 10001 @vindex org-agenda-search-headline-for-time 10002 In the headline of the entry itself, a time(range)---like @samp{12:45} or a 10003 @samp{8:30-1pm}---may also appear as plain text@footnote{ You can, however, 10004 disable this by setting @code{org-agenda-search-headline-for-time} variable 10005 to a @code{nil} value.}. 10006 10007 If the agenda integrates the Emacs diary (see @ref{Weekly/daily agenda}), 10008 time specifications in diary entries are recognized as well. 10009 10010 For agenda display, Org mode extracts the time and displays it in 10011 a standard 24 hour format as part of the prefix. The example times in 10012 the previous paragraphs would end up in the agenda like this: 10013 10014 @example 10015 8:30-13:00 Arthur Dent lies in front of the bulldozer 10016 12:45...... Ford Prefect arrives and takes Arthur to the pub 10017 19:00...... The Vogon reads his poem 10018 20:30-22:15 Marvin escorts the Hitchhikers to the bridge 10019 @end example 10020 10021 @cindex time grid 10022 If the agenda is in single-day mode, or for the display of today, the 10023 timed entries are embedded in a time grid, like 10024 10025 @example 10026 8:00...... ------------------ 10027 8:30-13:00 Arthur Dent lies in front of the bulldozer 10028 10:00...... ------------------ 10029 12:00...... ------------------ 10030 12:45...... Ford Prefect arrives and takes Arthur to the pub 10031 14:00...... ------------------ 10032 16:00...... ------------------ 10033 18:00...... ------------------ 10034 19:00...... The Vogon reads his poem 10035 20:00...... ------------------ 10036 20:30-22:15 Marvin escorts the Hitchhikers to the bridge 10037 @end example 10038 10039 @vindex org-agenda-use-time-grid 10040 @vindex org-agenda-time-grid 10041 The time grid can be turned on and off with the variable 10042 @code{org-agenda-use-time-grid}, and can be configured with 10043 @code{org-agenda-time-grid}. 10044 10045 @node Sorting of agenda items 10046 @subsection Sorting of agenda items 10047 10048 @cindex sorting, of agenda items 10049 @cindex priorities, of agenda items 10050 10051 Before being inserted into a view, the items are sorted. How this is 10052 done depends on the type of view. 10053 10054 @itemize 10055 @item 10056 @vindex org-agenda-files 10057 For the daily/weekly agenda, the items for each day are sorted. The 10058 default order is to first collect all items containing an explicit 10059 time-of-day specification. These entries are shown at the beginning 10060 of the list, as a @emph{schedule} for the day. After that, items remain 10061 grouped in categories, in the sequence given by @code{org-agenda-files}. 10062 Within each category, items are sorted by priority (see 10063 @ref{Priorities}), which is composed of the base priority (2000 for 10064 priority @samp{A}, 1000 for @samp{B}, and 0 for @samp{C}), plus additional 10065 increments for overdue scheduled or deadline items. 10066 10067 @item 10068 For the TODO list, items remain in the order of categories, but 10069 within each category, sorting takes place according to priority (see 10070 @ref{Priorities}). The priority used for sorting derives from the 10071 priority cookie, with additions depending on how close an item is to 10072 its due or scheduled date. 10073 10074 @item 10075 For tags matches, items are not sorted at all, but just appear in 10076 the sequence in which they are found in the agenda files. 10077 @end itemize 10078 10079 @vindex org-agenda-sorting-strategy 10080 Sorting can be customized using the variable 10081 @code{org-agenda-sorting-strategy}, and may also include criteria based on 10082 the estimated effort of an entry (see @ref{Effort Estimates}). 10083 10084 @node Filtering/limiting agenda items 10085 @subsection Filtering/limiting agenda items 10086 10087 @vindex org-agenda-category-filter-preset 10088 @vindex org-agenda-tag-filter-preset 10089 @vindex org-agenda-effort-filter-preset 10090 @vindex org-agenda-regexp-filter-preset 10091 Agenda built-in or custom commands are statically defined. Agenda 10092 filters and limits allow to flexibly narrow down the list of agenda 10093 entries. 10094 10095 @emph{Filters} only change the visibility of items, are very fast and are 10096 mostly used interactively@footnote{Custom agenda commands can preset a filter by binding one of 10097 the variables @code{org-agenda-tag-filter-preset}, 10098 @code{org-agenda-category-filter-preset}, @code{org-agenda-effort-filter-preset} 10099 or @code{org-agenda-regexp-filter-preset} as an option. This filter is 10100 then applied to the view and persists as a basic filter through 10101 refreshes and more secondary filtering. The filter is a global 10102 property of the entire agenda view---in a block agenda, you should 10103 only set this in the global options section, not in the section of an 10104 individual block.}. You can switch quickly between 10105 different filters without having to recreate the agenda. @emph{Limits} on 10106 the other hand take effect before the agenda buffer is populated, so 10107 they are mostly useful when defined as local variables within custom 10108 agenda commands. 10109 10110 @anchor{Filtering in the agenda} 10111 @subsubheading Filtering in the agenda 10112 10113 @cindex agenda filtering 10114 @cindex filtering entries, in agenda 10115 @cindex tag filtering, in agenda 10116 @cindex category filtering, in agenda 10117 @cindex top headline filtering, in agenda 10118 @cindex effort filtering, in agenda 10119 @cindex query editing, in agenda 10120 10121 The general filtering command is @code{org-agenda-filter}, bound to 10122 @kbd{/}. Before we introduce it, we describe commands for 10123 individual filter types. All filtering commands handle prefix 10124 arguments in the same way: A single @kbd{C-u} prefix negates the 10125 filter, so it removes lines selected by the filter. A double prefix 10126 adds the new filter condition to the one(s) already in place, so 10127 filter elements are accumulated. 10128 10129 @table @asis 10130 @item @kbd{\} (@code{org-agenda-filter-by-tag}) 10131 @findex org-agenda-filter-by-tag 10132 Filter the agenda view with respect to a tag. You are prompted for 10133 a tag selection letter; @kbd{@key{SPC}} means any tag at all. 10134 Pressing @kbd{@key{TAB}} at that prompt offers completion to select a 10135 tag, including any tags that do not have a selection character. The 10136 command then hides all entries that do not contain or inherit this 10137 tag. Pressing @kbd{+} or @kbd{-} at the prompt switches 10138 between filtering for and against the next tag. To clear the 10139 filter, press @kbd{\} twice (once to call the command again, 10140 and once at the prompt). 10141 10142 @item @kbd{<} (@code{org-agenda-filter-by-category}) 10143 @findex org-agenda-filter-by-category 10144 Filter by category of the line at point, and show only entries with 10145 this category. When called with a prefix argument, hide all entries 10146 with the category at point. To clear the filter, call this command 10147 again by pressing @kbd{<}. 10148 10149 @item @kbd{=} (@code{org-agenda-filter-by-regexp}) 10150 @findex org-agenda-filter-by-regexp 10151 Filter the agenda view by a regular expression: only show agenda 10152 entries matching the regular expression the user entered. To clear 10153 the filter, call the command again by pressing @kbd{=}. 10154 10155 @item @kbd{_} (@code{org-agenda-filter-by-effort}) 10156 @findex org-agenda-filter-by-effort 10157 Filter the agenda view with respect to effort estimates, so select 10158 tasks that take the right amount of time. You first need to set up 10159 a list of efforts globally, for example 10160 10161 @lisp 10162 (setq org-global-properties 10163 '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) 10164 @end lisp 10165 10166 @vindex org-sort-agenda-noeffort-is-high 10167 You can then filter for an effort by first typing an operator, one 10168 of @kbd{<}, @kbd{>} and @kbd{=}, and then the 10169 one-digit index of an effort estimate in your array of allowed 10170 values, where @kbd{0} means the 10th value. The filter then 10171 restricts to entries with effort smaller-or-equal, equal, or 10172 larger-or-equal than the selected value. For application of the 10173 operator, entries without a defined effort are treated according to 10174 the value of @code{org-sort-agenda-noeffort-is-high}. To clear the 10175 filter, press @kbd{_} twice (once to call the command again, 10176 and once at the first prompt). 10177 10178 @item @kbd{^} (@code{org-agenda-filter-by-top-headline}) 10179 @findex org-agenda-filter-by-top-headline 10180 Filter the current agenda view and only display items that fall 10181 under the same top-level headline as the current entry. To clear 10182 the filter, call this command again by pressing @kbd{^}. 10183 10184 @item @kbd{/} (@code{org-agenda-filter}) 10185 @findex org-agenda-filter 10186 This is the unified interface to four of the five filter methods 10187 described above. At the prompt, specify different filter elements 10188 in a single string, with full completion support. For example, 10189 10190 @example 10191 +work-John+<0:10-/plot/ 10192 @end example 10193 10194 10195 selects entries with category @samp{work} and effort estimates below 10 10196 minutes, and deselects entries with tag @samp{John} or matching the 10197 regexp @samp{plot} (see @ref{Regular Expressions}). You can leave @samp{+} out if 10198 that does not lead to ambiguities. The sequence of elements is 10199 arbitrary. The filter syntax assumes that there is no overlap 10200 between categories and tags. Otherwise, tags take priority. If you 10201 reply to the prompt with the empty string, all filtering is removed. 10202 If a filter is specified, it replaces all current filters. But if 10203 you call the command with a double prefix argument, or if you add an 10204 additional @samp{+} (e.g., @samp{++work}) to the front of the string, the new 10205 filter elements are added to the active ones. A single prefix 10206 argument applies the entire filter in a negative sense. 10207 10208 @item @kbd{|} (@code{org-agenda-filter-remove-all}) 10209 Remove all filters in the current agenda view. 10210 @end table 10211 10212 @anchor{Computed tag filtering} 10213 @subsubheading Computed tag filtering 10214 10215 @vindex org-agenda-auto-exclude-function 10216 If the variable @code{org-agenda-auto-exclude-function} is set to 10217 a user-defined function, that function can select tags that should be 10218 used as a tag filter when requested. The function will be called with 10219 lower-case versions of all tags represented in the current view. The 10220 function should return @samp{"-tag"} if the filter should remove 10221 entries with that tag, @samp{"+tag"} if only entries with this tag should 10222 be kept, or @samp{nil} if that tag is irrelevant. For example, let's say 10223 you use a @samp{Net} tag to identify tasks which need network access, an 10224 @samp{Errand} tag for errands in town, and a @samp{Call} tag for making phone 10225 calls. You could auto-exclude these tags based on the availability of 10226 the Internet, and outside of business hours, with something like this: 10227 10228 @lisp 10229 (defun my-auto-exclude-fn (tag) 10230 (when (cond ((string= tag "net") 10231 (/= 0 (call-process "/sbin/ping" nil nil nil 10232 "-c1" "-q" "-t1" "mail.gnu.org"))) 10233 ((member tag '("errand" "call")) 10234 (let ((hr (nth 2 (decode-time)))) 10235 (or (< hr 8) (> hr 21))))) 10236 (concat "-" tag))) 10237 10238 (setq org-agenda-auto-exclude-function #'my-auto-exclude-fn) 10239 @end lisp 10240 10241 You can apply this self-adapting filter by using a triple prefix 10242 argument to @code{org-agenda-filter}, i.e.@tie{}press @kbd{C-u C-u C-u /}, 10243 or by pressing @kbd{@key{RET}} in @code{org-agenda-filter-by-tag}. 10244 10245 @anchor{Setting limits for the agenda} 10246 @subsubheading Setting limits for the agenda 10247 10248 @cindex limits, in agenda 10249 10250 Here is a list of options that you can set, either globally, or 10251 locally in your custom agenda views (see @ref{Custom Agenda Views}). 10252 10253 @table @asis 10254 @item @code{org-agenda-max-entries} 10255 @vindex org-agenda-max-entries 10256 Limit the number of entries. 10257 10258 @item @code{org-agenda-max-effort} 10259 @vindex org-agenda-max-effort 10260 Limit the duration of accumulated efforts (as minutes). 10261 10262 @item @code{org-agenda-max-todos} 10263 @vindex org-agenda-max-todos 10264 Limit the number of entries with TODO keywords. 10265 10266 @item @code{org-agenda-max-tags} 10267 @vindex org-agenda-max-tags 10268 Limit the number of tagged entries. 10269 @end table 10270 10271 When set to a positive integer, each option excludes entries from 10272 other categories: for example, @samp{(setq org-agenda-max-effort 100)} 10273 limits the agenda to 100 minutes of effort and exclude any entry that 10274 has no effort property. If you want to include entries with no effort 10275 property, use a negative value for @code{org-agenda-max-effort}. One 10276 useful setup is to use @code{org-agenda-max-entries} locally in a custom 10277 command. For example, this custom command displays the next five 10278 entries with a @samp{NEXT} TODO keyword. 10279 10280 @lisp 10281 (setq org-agenda-custom-commands 10282 '(("n" todo "NEXT" 10283 ((org-agenda-max-entries 5))))) 10284 @end lisp 10285 10286 Once you mark one of these five entry as DONE, rebuilding the agenda 10287 will again the next five entries again, including the first entry that 10288 was excluded so far. 10289 10290 You can also dynamically set temporary limits, which are lost when 10291 rebuilding the agenda: 10292 10293 @table @asis 10294 @item @kbd{~} (@code{org-agenda-limit-interactively}) 10295 @findex org-agenda-limit-interactively 10296 This prompts for the type of limit to apply and its value. 10297 @end table 10298 10299 @node Agenda Commands 10300 @section Commands in the Agenda Buffer 10301 10302 @cindex commands, in agenda buffer 10303 10304 Entries in the agenda buffer are linked back to the Org file or diary 10305 file where they originate. You are not allowed to edit the agenda 10306 buffer itself, but commands are provided to show and jump to the 10307 original entry location, and to edit the Org files ``remotely'' from the 10308 agenda buffer. In this way, all information is stored only once, 10309 removing the risk that your agenda and note files may diverge. 10310 10311 Some commands can be executed with mouse clicks on agenda lines. For 10312 the other commands, point needs to be in the desired line. 10313 10314 @anchor{Motion (1)} 10315 @subheading Motion 10316 10317 @cindex motion commands in agenda 10318 10319 @table @asis 10320 @item @kbd{n} (@code{org-agenda-next-line}) 10321 @kindex n 10322 @findex org-agenda-next-line 10323 Next line (same as @kbd{@key{DOWN}} and @kbd{C-n}). 10324 10325 @item @kbd{p} (@code{org-agenda-previous-line}) 10326 @kindex p 10327 @findex org-agenda-previous-line 10328 Previous line (same as @kbd{@key{UP}} and @kbd{C-p}). 10329 @end table 10330 10331 @anchor{View/Go to Org file} 10332 @subheading View/Go to Org file 10333 10334 @cindex view file commands in agenda 10335 10336 @table @asis 10337 @item @kbd{@key{SPC}} or @kbd{mouse-3} (@code{org-agenda-show-and-scroll-up}) 10338 @kindex SPC 10339 @kindex mouse-3 10340 @findex org-agenda-show-and-scroll-up 10341 Display the original location of the item in another window. 10342 With a prefix argument, make sure that drawers stay folded. 10343 10344 @item @kbd{L} (@code{org-agenda-recenter}) 10345 @findex org-agenda-recenter 10346 Display original location and recenter that window. 10347 10348 @item @kbd{@key{TAB}} or @kbd{mouse-2} (@code{org-agenda-goto}) 10349 @kindex TAB 10350 @kindex mouse-2 10351 @findex org-agenda-goto 10352 Go to the original location of the item in another window. 10353 10354 @item @kbd{@key{RET}} (@code{org-agenda-switch-to}) 10355 @kindex RET 10356 @findex org-agenda-switch-to 10357 Go to the original location of the item and delete other windows. 10358 10359 @item @kbd{F} (@code{org-agenda-follow-mode}) 10360 @kindex F 10361 @findex org-agenda-follow-mode 10362 @vindex org-agenda-start-with-follow-mode 10363 Toggle Follow mode. In Follow mode, as you move point through the 10364 agenda buffer, the other window always shows the corresponding 10365 location in the Org file. The initial setting for this mode in new 10366 agenda buffers can be set with the variable 10367 @code{org-agenda-start-with-follow-mode}. 10368 10369 @item @kbd{C-c C-x b} (@code{org-agenda-tree-to-indirect-buffer}) 10370 @kindex C-c C-x b 10371 @findex org-agenda-tree-to-indirect-buffer 10372 Display the entire subtree of the current item in an indirect 10373 buffer. With a numeric prefix argument N, go up to level N and then 10374 take that tree. If N is negative, go up that many levels. With 10375 a @kbd{C-u} prefix, do not remove the previously used indirect 10376 buffer. 10377 10378 @item @kbd{C-c C-o} (@code{org-agenda-open-link}) 10379 @kindex C-c C-o 10380 @findex org-agenda-open-link 10381 Follow a link in the entry. This offers a selection of any links in 10382 the text belonging to the referenced Org node. If there is only one 10383 link, follow it without a selection prompt. 10384 @end table 10385 10386 @anchor{Change display} 10387 @subheading Change display 10388 10389 @cindex change agenda display 10390 @cindex display changing, in agenda 10391 10392 @table @asis 10393 @item @kbd{A} 10394 @kindex A 10395 Interactively select another agenda view and append it to the 10396 current view. 10397 10398 @item @kbd{o} 10399 @kindex o 10400 Delete other windows. 10401 10402 @item @kbd{v d} or short @kbd{d} (@code{org-agenda-day-view}) 10403 @kindex v d 10404 @kindex d 10405 @findex org-agenda-day-view 10406 Switch to day view. When switching to day view, this setting 10407 becomes the default for subsequent agenda refreshes. A numeric 10408 prefix argument may be used to jump directly to a specific day of 10409 the year. For example, @kbd{32 d} jumps to February 1st. When 10410 setting day view, a year may be encoded in the prefix argument as 10411 well. For example, @kbd{200712 d} jumps to January 12, 2007. 10412 If such a year specification has only one or two digits, it is 10413 expanded into one of the 30 next years or the last 69 years. 10414 10415 @item @kbd{v w} or short @kbd{w} (@code{org-agenda-week-view}) 10416 @kindex v w 10417 @kindex w 10418 @findex org-agenda-week-view 10419 Switch to week view. When switching week view, this setting becomes 10420 the default for subsequent agenda refreshes. A numeric prefix 10421 argument may be used to jump directly to a specific day of the ISO 10422 week. For example @kbd{9 w} to ISO week number 9. When 10423 setting week view, a year may be encoded in the prefix argument as 10424 well. For example, @kbd{200712 w} jumps to week 12 in 2007. 10425 If such a year specification has only one or two digits, it is 10426 expanded into one of the 30 next years or the last 69 years. 10427 10428 @item @kbd{v m} (@code{org-agenda-month-view}) 10429 @kindex v m 10430 @findex org-agenda-month-view 10431 Switch to month view. Because month views are slow to create, they 10432 do not become the default for subsequent agenda refreshes. 10433 A numeric prefix argument may be used to jump directly to a specific 10434 day of the month. When setting month view, a year may be encoded in 10435 the prefix argument as well. For example, @kbd{200712 m} jumps 10436 to December, 2007. If such a year specification has only one or two 10437 digits, it is expanded into one of the 30 next years or the last 69 10438 years. 10439 10440 @item @kbd{v y} (@code{org-agenda-year-view}) 10441 @kindex v y 10442 @findex org-agenda-year-view 10443 Switch to year view. Because year views are slow to create, they do 10444 not become the default for subsequent agenda refreshes. A numeric 10445 prefix argument may be used to jump directly to a specific day of 10446 the year. 10447 10448 @item @kbd{v @key{SPC}} (@code{org-agenda-reset-view}) 10449 @kindex v SPC 10450 @findex org-agenda-reset-view 10451 @vindex org-agenda-span 10452 Reset the current view to @code{org-agenda-span}. 10453 10454 @item @kbd{f} (@code{org-agenda-later}) 10455 @kindex f 10456 @findex org-agenda-later 10457 Go forward in time to display the span following the current one. 10458 For example, if the display covers a week, switch to the following 10459 week. With a prefix argument, repeat that many times. 10460 10461 @item @kbd{b} (@code{org-agenda-earlier}) 10462 @kindex b 10463 @findex org-agenda-earlier 10464 Go backward in time to display earlier dates. 10465 10466 @item @kbd{.} (@code{org-agenda-goto-today}) 10467 @kindex . 10468 @findex org-agenda-goto-today 10469 Go to today. 10470 10471 @item @kbd{j} (@code{org-agenda-goto-date}) 10472 @kindex j 10473 @findex org-agenda-goto-date 10474 Prompt for a date and go there. 10475 10476 @item @kbd{J} (@code{org-agenda-clock-goto}) 10477 @kindex J 10478 @findex org-agenda-clock-goto 10479 Go to the currently clocked-in task @emph{in the agenda buffer}. 10480 10481 @item @kbd{D} (@code{org-agenda-toggle-diary}) 10482 @kindex D 10483 @findex org-agenda-toggle-diary 10484 Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}. 10485 10486 @item @kbd{v l} or @kbd{v L} or short @kbd{l} (@code{org-agenda-log-mode}) 10487 @kindex v l 10488 @kindex l 10489 @kindex v L 10490 @findex org-agenda-log-mode 10491 @vindex org-log-done 10492 @vindex org-agenda-log-mode-items 10493 Toggle Logbook mode. In Logbook mode, entries that were marked as 10494 done while logging was on (see the variable @code{org-log-done}) are 10495 shown in the agenda, as are entries that have been clocked on that 10496 day. You can configure the entry types that should be included in 10497 log mode using the variable @code{org-agenda-log-mode-items}. When 10498 called with a @kbd{C-u} prefix argument, show all possible 10499 logbook entries, including state changes. When called with two 10500 prefix arguments @kbd{C-u C-u}, show only logging information, 10501 nothing else. @kbd{v L} is equivalent to @kbd{C-u v l}. 10502 10503 @item @kbd{v [} or short @kbd{[} (@code{org-agenda-manipulate-query-add}) 10504 @kindex v [ 10505 @kindex [ 10506 @findex org-agenda-manipulate-query-add 10507 Include inactive timestamps into the current view. Only for 10508 weekly/daily agenda. 10509 10510 @item @kbd{v a} (@code{org-agenda-archives-mode}) 10511 @kindex v a 10512 @findex org-agenda-archives-mode 10513 Toggle Archives mode. In Archives mode, trees that are archived 10514 (see @ref{Internal archiving}) are also scanned when producing the 10515 agenda. To exit archives mode, press @kbd{v a} again. 10516 10517 @item @kbd{v A} 10518 @kindex v A 10519 Toggle Archives mode. Include all archive files as well. 10520 10521 @item @kbd{v R} or short @kbd{R} (@code{org-agenda-clockreport-mode}) 10522 @kindex v R 10523 @kindex R 10524 @findex org-agenda-clockreport-mode 10525 @vindex org-agenda-start-with-clockreport-mode 10526 @vindex org-clock-report-include-clocking-task 10527 Toggle Clockreport mode. In Clockreport mode, the daily/weekly 10528 agenda always shows a table with the clocked times for the time span 10529 and file scope covered by the current agenda view. The initial 10530 setting for this mode in new agenda buffers can be set with the 10531 variable @code{org-agenda-start-with-clockreport-mode}. By using a 10532 prefix argument when toggling this mode (i.e., @kbd{C-u R}), 10533 the clock table does not show contributions from entries that are 10534 hidden by agenda filtering@footnote{ Only tags filtering is respected 10535 here, effort filtering is ignored.}. See also the variables 10536 @code{org-clock-report-include-clocking-task} and 10537 @code{org-agenda-clock-report-header}. 10538 10539 @item @kbd{v c} 10540 @kindex v c 10541 @vindex org-agenda-clock-consistency-checks 10542 Show overlapping clock entries, clocking gaps, and other clocking 10543 problems in the current agenda range. You can then visit clocking 10544 lines and fix them manually. See the variable 10545 @code{org-agenda-clock-consistency-checks} for information on how to 10546 customize the definition of what constituted a clocking problem. To 10547 return to normal agenda display, press @kbd{l} to exit Logbook 10548 mode. 10549 10550 @item @kbd{v E} or short @kbd{E} (@code{org-agenda-entry-text-mode}) 10551 @kindex v E 10552 @kindex E 10553 @findex org-agenda-entry-text-mode 10554 @vindex org-agenda-start-with-entry-text-mode 10555 @vindex org-agenda-entry-text-maxlines 10556 Toggle entry text mode. In entry text mode, a number of lines from 10557 the Org outline node referenced by an agenda line are displayed 10558 below the line. The maximum number of lines is given by the 10559 variable @code{org-agenda-entry-text-maxlines}. Calling this command 10560 with a numeric prefix argument temporarily modifies that number to 10561 the prefix value. 10562 10563 @item @kbd{G} (@code{org-agenda-toggle-time-grid}) 10564 @kindex G 10565 @vindex org-agenda-use-time-grid 10566 @vindex org-agenda-time-grid 10567 Toggle the time grid on and off. See also the variables 10568 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}. 10569 10570 @item @kbd{r} (@code{org-agenda-redo}) 10571 @itemx @kbd{g} 10572 @kindex r 10573 @kindex g 10574 @findex org-agenda-redo 10575 Recreate the agenda buffer, for example to reflect the changes after 10576 modification of the timestamps of items with @kbd{S-@key{LEFT}} and 10577 @kbd{S-@key{RIGHT}}. When the buffer is the global TODO list, 10578 a prefix argument is interpreted to create a selective list for 10579 a specific TODO keyword. 10580 10581 @item @kbd{C-x C-s} or short @kbd{s} (@code{org-save-all-org-buffers}) 10582 @kindex C-x C-s 10583 @findex org-save-all-org-buffers 10584 @kindex s 10585 Save all Org buffers in the current Emacs session, and also the 10586 locations of IDs. 10587 10588 @item @kbd{C-c C-x C-c} (@code{org-agenda-columns}) 10589 @kindex C-c C-x C-c 10590 @findex org-agenda-columns 10591 @vindex org-columns-default-format 10592 Invoke column view (see @ref{Column View}) in the agenda buffer. The 10593 column view format is taken from the entry at point, or, if there is 10594 no entry at point, from the first entry in the agenda view. So 10595 whatever the format for that entry would be in the original buffer 10596 (taken from a property, from a @samp{COLUMNS} keyword, or from the 10597 default variable @code{org-columns-default-format}) is used in the 10598 agenda. 10599 10600 @item @kbd{C-c C-x >} (@code{org-agenda-remove-restriction-lock}) 10601 @kindex C-c C-x > 10602 @findex org-agenda-remove-restriction-lock 10603 Remove the restriction lock on the agenda, if it is currently 10604 restricted to a file or subtree (see @ref{Agenda Files}). 10605 10606 @item @kbd{M-@key{UP}} (@code{org-agenda-drag-line-backward}) 10607 @kindex M-UP 10608 @findex org-agenda-drag-line-backward 10609 Drag the line at point backward one line. With a numeric prefix 10610 argument, drag backward by that many lines. 10611 10612 Moving agenda lines does not persist after an agenda refresh and 10613 does not modify the contributing Org files. 10614 10615 @item @kbd{M-@key{DOWN}} (@code{org-agenda-drag-line-forward}) 10616 @kindex M-DOWN 10617 @findex org-agenda-drag-line-forward 10618 Drag the line at point forward one line. With a numeric prefix 10619 argument, drag forward by that many lines. 10620 @end table 10621 10622 @anchor{Remote editing} 10623 @subheading Remote editing 10624 10625 @cindex remote editing, from agenda 10626 10627 @table @asis 10628 @item @kbd{0--9} 10629 Digit argument. 10630 10631 @item @kbd{C-_} (@code{org-agenda-undo}) 10632 @kindex C-_ 10633 @findex org-agenda-undo 10634 @cindex undoing remote-editing events 10635 @cindex remote editing, undo 10636 Undo a change due to a remote editing command. The change is undone 10637 both in the agenda buffer and in the remote buffer. 10638 10639 @item @kbd{t} (@code{org-agenda-todo}) 10640 @kindex t 10641 @findex org-agenda-todo 10642 Change the TODO state of the item, both in the agenda and in the 10643 original Org file. A prefix arg is passed through to the @code{org-todo} 10644 command, so for example a @kbd{C-u} prefix are will trigger 10645 taking a note to document the state change. 10646 10647 @item @kbd{C-S-@key{RIGHT}} (@code{org-agenda-todo-nextset}) 10648 @kindex C-S-RIGHT 10649 @findex org-agenda-todo-nextset 10650 Switch to the next set of TODO keywords. 10651 10652 @item @kbd{C-S-@key{LEFT}}, @code{org-agenda-todo-previousset} 10653 @kindex C-S-LEFT 10654 Switch to the previous set of TODO keywords. 10655 10656 @item @kbd{C-k} (@code{org-agenda-kill}) 10657 @kindex C-k 10658 @findex org-agenda-kill 10659 @vindex org-agenda-confirm-kill 10660 Delete the current agenda item along with the entire subtree 10661 belonging to it in the original Org file. If the text to be deleted 10662 remotely is longer than one line, the kill needs to be confirmed by 10663 the user. See variable @code{org-agenda-confirm-kill}. 10664 10665 @item @kbd{C-c C-w} (@code{org-agenda-refile}) 10666 @kindex C-c C-w 10667 @findex org-agenda-refile 10668 Refile the entry at point. 10669 10670 @item @kbd{C-c C-x C-a} or short @kbd{a} (@code{org-agenda-archive-default-with-confirmation}) 10671 @kindex C-c C-x C-a 10672 @kindex a 10673 @findex org-agenda-archive-default-with-confirmation 10674 @vindex org-archive-default-command 10675 Archive the subtree corresponding to the entry at point using the 10676 default archiving command set in @code{org-archive-default-command}. 10677 When using the @kbd{a} key, confirmation is required. 10678 10679 @item @kbd{C-c C-x a} (@code{org-agenda-toggle-archive-tag}) 10680 @kindex C-c C-x a 10681 @findex org-agenda-toggle-archive-tag 10682 Toggle the archive tag (see @ref{Internal archiving}) for the current 10683 headline. 10684 10685 @item @kbd{C-c C-x A} (@code{org-agenda-archive-to-archive-sibling}) 10686 @kindex C-c C-x A 10687 @findex org-agenda-archive-to-archive-sibling 10688 Move the subtree corresponding to the current entry to its @emph{archive 10689 sibling}. 10690 10691 @item @kbd{C-c C-x C-s} or short @kbd{$} (@code{org-agenda-archive}) 10692 @kindex C-c C-x C-s 10693 @kindex $ 10694 @findex org-agenda-archive 10695 Archive the subtree corresponding to the current headline. This 10696 means the entry is moved to the configured archive location, most 10697 likely a different file. 10698 10699 @item @kbd{T} (@code{org-agenda-show-tags}) 10700 @kindex T 10701 @findex org-agenda-show-tags 10702 @vindex org-agenda-show-inherited-tags 10703 Show all tags associated with the current item. This is useful if 10704 you have turned off @code{org-agenda-show-inherited-tags}, but still want 10705 to see all tags of a headline occasionally. 10706 10707 @item @kbd{:} (@code{org-agenda-set-tags}) 10708 @kindex : 10709 @findex org-agenda-set-tags 10710 Set tags for the current headline. If there is an active region in 10711 the agenda, change a tag for all headings in the region. 10712 10713 @item @kbd{,} (@code{org-agenda-priority}) 10714 @kindex , 10715 @findex org-agenda-priority 10716 Set the priority for the current item. Org mode prompts for the 10717 priority character. If you reply with @kbd{@key{SPC}}, the priority 10718 cookie is removed from the entry. 10719 10720 @item @kbd{+} or @kbd{S-@key{UP}} (@code{org-agenda-priority-up}) 10721 @kindex + 10722 @kindex S-UP 10723 @findex org-agenda-priority-up 10724 Increase the priority of the current item. The priority is changed 10725 in the original buffer, but the agenda is not resorted. Use the 10726 @kbd{r} key for this. 10727 10728 @item @kbd{-} or @kbd{S-@key{DOWN}} (@code{org-agenda-priority-down}) 10729 @kindex - 10730 @kindex S-DOWN 10731 @findex org-agenda-priority-down 10732 Decrease the priority of the current item. 10733 10734 @item @kbd{C-c C-x e} or short @kbd{e} (@code{org-agenda-set-effort}) 10735 @kindex e 10736 @kindex C-c C-x e 10737 @findex org-agenda-set-effort 10738 Set the effort property for the current item. 10739 10740 @item @kbd{C-c C-z} or short @kbd{z} (@code{org-agenda-add-note}) 10741 @kindex z 10742 @kindex C-c C-z 10743 @findex org-agenda-add-note 10744 @vindex org-log-into-drawer 10745 Add a note to the entry. This note is recorded, and then filed to 10746 the same location where state change notes are put. Depending on 10747 @code{org-log-into-drawer}, this may be inside a drawer. 10748 10749 @item @kbd{C-c C-a} (@code{org-attach}) 10750 @kindex C-c C-a 10751 @findex org-attach 10752 Dispatcher for all command related to attachments. 10753 10754 @item @kbd{C-c C-s} (@code{org-agenda-schedule}) 10755 @kindex C-c C-s 10756 @findex org-agenda-schedule 10757 Schedule this item. With a prefix argument, remove the 10758 scheduling timestamp 10759 10760 @item @kbd{C-c C-d} (@code{org-agenda-deadline}) 10761 @kindex C-c C-d 10762 @findex org-agenda-deadline 10763 Set a deadline for this item. With a prefix argument, remove the 10764 deadline. 10765 10766 @item @kbd{S-@key{RIGHT}} (@code{org-agenda-do-date-later}) 10767 @kindex S-RIGHT 10768 @findex org-agenda-do-date-later 10769 Change the timestamp associated with the current line by one day 10770 into the future. If the date is in the past, the first call to this 10771 command moves it to today. With a numeric prefix argument, change 10772 it by that many days. For example, @kbd{3 6 5 S-@key{RIGHT}} changes 10773 it by a year. With a @kbd{C-u} prefix, change the time by one 10774 hour. If you immediately repeat the command, it will continue to 10775 change hours even without the prefix argument. With a double 10776 @kbd{C-u C-u} prefix, do the same for changing minutes. The 10777 stamp is changed in the original Org file, but the change is not 10778 directly reflected in the agenda buffer. Use @kbd{r} or 10779 @kbd{g} to update the buffer. 10780 10781 @item @kbd{S-@key{LEFT}} (@code{org-agenda-do-date-earlier}) 10782 @kindex S-LEFT 10783 @findex org-agenda-do-date-earlier 10784 Change the timestamp associated with the current line by one day 10785 into the past. 10786 10787 @item @kbd{>} (@code{org-agenda-date-prompt}) 10788 @kindex > 10789 @findex org-agenda-date-prompt 10790 Change the timestamp associated with the current line. The key 10791 @kbd{>} has been chosen, because it is the same as 10792 @kbd{S-.} on my keyboard. 10793 10794 @item @kbd{I} (@code{org-agenda-clock-in}) 10795 @kindex I 10796 @findex org-agenda-clock-in 10797 Start the clock on the current item. If a clock is running already, 10798 it is stopped first. 10799 10800 @item @kbd{O} (@code{org-agenda-clock-out}) 10801 @kindex O 10802 @findex org-agenda-clock-out 10803 Stop the previously started clock. 10804 10805 @item @kbd{X} (@code{org-agenda-clock-cancel}) 10806 @kindex X 10807 @findex org-agenda-clock-cancel 10808 Cancel the currently running clock. 10809 10810 @item @kbd{J} (@code{org-agenda-clock-goto}) 10811 @kindex J 10812 @findex org-agenda-clock-goto 10813 Jump to the running clock in another window. 10814 10815 @item @kbd{k} (@code{org-agenda-capture}) 10816 @kindex k 10817 @findex org-agenda-capture 10818 @cindex capturing, from agenda 10819 @vindex org-capture-use-agenda-date 10820 Like @code{org-capture}, but use the date at point as the default date 10821 for the capture template. See @code{org-capture-use-agenda-date} to make 10822 this the default behavior of @code{org-capture}. 10823 @end table 10824 10825 @anchor{Bulk remote editing selected entries} 10826 @subheading Bulk remote editing selected entries 10827 10828 @cindex remote editing, bulk, from agenda 10829 @vindex org-agenda-bulk-custom-functions 10830 10831 @table @asis 10832 @item @kbd{m} (@code{org-agenda-bulk-mark}) 10833 @kindex m 10834 @findex org-agenda-bulk-mark 10835 10836 Mark the entry at point for bulk action. If there is an active 10837 region in the agenda, mark the entries in the region. With numeric 10838 prefix argument, mark that many successive entries. 10839 10840 @item @kbd{*} (@code{org-agenda-bulk-mark-all}) 10841 @kindex * 10842 @findex org-agenda-bulk-mark-all 10843 10844 Mark all visible agenda entries for bulk action. 10845 10846 @item @kbd{u} (@code{org-agenda-bulk-unmark}) 10847 @kindex u 10848 @findex org-agenda-bulk-unmark 10849 10850 Unmark entry for bulk action. 10851 10852 @item @kbd{U} (@code{org-agenda-bulk-remove-all-marks}) 10853 @kindex U 10854 @findex org-agenda-bulk-remove-all-marks 10855 10856 Unmark all marked entries for bulk action. 10857 10858 @item @kbd{M-m} (@code{org-agenda-bulk-toggle}) 10859 @kindex M-m 10860 @findex org-agenda-bulk-toggle 10861 10862 Toggle mark of the entry at point for bulk action. 10863 10864 @item @kbd{M-*} (@code{org-agenda-bulk-toggle-all}) 10865 @kindex M-* 10866 @findex org-agenda-bulk-toggle-all 10867 10868 Toggle mark of every entry for bulk action. 10869 10870 @item @kbd{%} (@code{org-agenda-bulk-mark-regexp}) 10871 @kindex % 10872 @findex org-agenda-bulk-mark-regexp 10873 10874 Mark entries matching a regular expression for bulk action. 10875 10876 @item @kbd{B} (@code{org-agenda-bulk-action}) 10877 @kindex B 10878 @findex org-agenda-bulk-action 10879 @vindex org-agenda-bulk-persistent-marks 10880 10881 Bulk action: act on all marked entries in the agenda. This prompts 10882 for another key to select the action to be applied. The prefix 10883 argument to @kbd{B} is passed through to the @kbd{s} and 10884 @kbd{d} commands, to bulk-remove these special timestamps. By 10885 default, marks are removed after the bulk. If you want them to 10886 persist, set @code{org-agenda-bulk-persistent-marks} to @code{t} or hit 10887 @kbd{p} at the prompt. 10888 10889 @table @asis 10890 @item @kbd{p} 10891 Toggle persistent marks. 10892 10893 @item @kbd{$} 10894 Archive all selected entries. 10895 10896 @item @kbd{A} 10897 Archive entries by moving them to their respective archive 10898 siblings. 10899 10900 @item @kbd{t} 10901 Change TODO state. This prompts for a single TODO keyword and 10902 changes the state of all selected entries, bypassing blocking and 10903 suppressing logging notes---but not timestamps. 10904 10905 @item @kbd{+} 10906 Add a tag to all selected entries. 10907 10908 @item @kbd{-} 10909 Remove a tag from all selected entries. 10910 10911 @item @kbd{s} 10912 Schedule all items to a new date. To shift existing schedule 10913 dates by a fixed number of days, use something starting with 10914 double plus at the prompt, for example @samp{++8d} or @samp{++2w}. 10915 10916 @item @kbd{d} 10917 Set deadline to a specific date. 10918 10919 @item @kbd{r} 10920 Prompt for a single refile target and move all entries. The 10921 entries are no longer in the agenda; refresh (@kbd{g}) to 10922 bring them back. 10923 10924 @item @kbd{S} 10925 Reschedule randomly into the coming N days. N is prompted for. 10926 With a prefix argument (@kbd{C-u B S}), scatter only across 10927 weekdays. 10928 10929 @item @kbd{f} 10930 @vindex org-agenda-bulk-custom-functions 10931 Apply a function@footnote{ You can also create persistent custom 10932 functions through @code{org-agenda-bulk-custom-functions}.} to marked 10933 entries. For example, the function below sets the @samp{CATEGORY} 10934 property of the entries to @samp{web}. 10935 10936 @lisp 10937 (defun set-category () 10938 (interactive "P") 10939 (let ((marker (or (org-get-at-bol 'org-hd-marker) 10940 (org-agenda-error)))) 10941 (org-with-point-at marker 10942 (org-back-to-heading t) 10943 (org-set-property "CATEGORY" "web")))) 10944 @end lisp 10945 @end table 10946 @end table 10947 10948 @anchor{Calendar commands} 10949 @subheading Calendar commands 10950 10951 @cindex calendar commands, from agenda 10952 10953 @table @asis 10954 @item @kbd{c} (@code{org-agenda-goto-calendar}) 10955 @kindex c 10956 @findex org-agenda-goto-calendar 10957 Open the Emacs calendar and go to the date at point in the agenda. 10958 10959 @item @kbd{c} (@code{org-calendar-goto-agenda}) 10960 @kindex c 10961 @findex org-calendar-goto-agenda 10962 When in the calendar, compute and show the Org agenda for the date 10963 at point. 10964 10965 @item @kbd{i} (@code{org-agenda-diary-entry}) 10966 @kindex i 10967 @findex org-agenda-diary-entry 10968 10969 @cindex diary entries, creating from agenda 10970 Insert a new entry into the diary, using the date at point and (for 10971 block entries) the date at the mark. This adds to the Emacs diary 10972 file@footnote{ This file is parsed for the agenda when 10973 @code{org-agenda-include-diary} is set.}, in a way similar to the 10974 @kbd{i} command in the calendar. The diary file pops up in 10975 another window, where you can add the entry. 10976 10977 @vindex org-agenda-diary-file 10978 If you configure @code{org-agenda-diary-file} to point to an Org file, 10979 Org creates entries in that file instead. Most entries are stored 10980 in a date-based outline tree that will later make it easy to archive 10981 appointments from previous months/years. The tree is built under an 10982 entry with a @samp{DATE_TREE} property, or else with years as top-level 10983 entries. Emacs prompts you for the entry text---if you specify it, 10984 the entry is created in @code{org-agenda-diary-file} without further 10985 interaction. If you directly press @kbd{@key{RET}} at the prompt 10986 without typing text, the target file is shown in another window for 10987 you to finish the entry there. See also the @kbd{k r} command. 10988 10989 @item @kbd{M} (@code{org-agenda-phases-of-moon}) 10990 @kindex M 10991 @findex org-agenda-phases-of-moon 10992 Show the phases of the moon for the three months around current 10993 date. 10994 10995 @item @kbd{S} (@code{org-agenda-sunrise-sunset}) 10996 @kindex S 10997 @findex org-agenda-sunrise-sunset 10998 Show sunrise and sunset times. The geographical location must be 10999 set with calendar variables, see the documentation for the Emacs 11000 calendar. 11001 11002 @item @kbd{C} (@code{org-agenda-convert-date}) 11003 @kindex C 11004 @findex org-agenda-convert-date 11005 Convert the date at point into many other cultural and historic 11006 calendars. 11007 11008 @item @kbd{H} (@code{org-agenda-holidays}) 11009 @kindex H 11010 @findex org-agenda-holidays 11011 Show holidays for three months around point date. 11012 @end table 11013 11014 @anchor{Quit and exit} 11015 @subheading Quit and exit 11016 11017 @table @asis 11018 @item @kbd{q} (@code{org-agenda-quit}) 11019 @kindex q 11020 @findex org-agenda-quit 11021 11022 Quit agenda, remove the agenda buffer. 11023 11024 @item @kbd{x} (@code{org-agenda-exit}) 11025 @kindex x 11026 @findex org-agenda-exit 11027 11028 @cindex agenda files, removing buffers 11029 Exit agenda, remove the agenda buffer and all buffers loaded by 11030 Emacs for the compilation of the agenda. Buffers created by the 11031 user to visit Org files are not removed. 11032 @end table 11033 11034 @node Custom Agenda Views 11035 @section Custom Agenda Views 11036 11037 @cindex custom agenda views 11038 @cindex agenda views, custom 11039 11040 Custom agenda commands serve two purposes: to store and quickly access 11041 frequently used TODO and tags searches, and to create special 11042 composite agenda buffers. Custom agenda commands are accessible 11043 through the dispatcher (see @ref{Agenda Dispatcher}), just like the 11044 default commands. 11045 11046 @menu 11047 * Storing searches:: Type once, use often. 11048 * Block agenda:: All the stuff you need in a single buffer. 11049 * Setting options:: Changing the rules. 11050 @end menu 11051 11052 @node Storing searches 11053 @subsection Storing searches 11054 11055 The first application of custom searches is the definition of keyboard 11056 shortcuts for frequently used searches, either creating an agenda 11057 buffer, or a sparse tree (the latter covering of course only the 11058 current buffer). 11059 11060 @kindex C @r{(Agenda dispatcher)} 11061 @vindex org-agenda-custom-commands 11062 @cindex agenda views, main example 11063 @cindex agenda, as an agenda views 11064 @cindex agenda*, as an agenda views 11065 @cindex tags, as an agenda view 11066 @cindex todo, as an agenda view 11067 @cindex tags-todo 11068 @cindex todo-tree 11069 @cindex occur-tree 11070 @cindex tags-tree 11071 Custom commands are configured in the variable 11072 @code{org-agenda-custom-commands}. You can customize this variable, for 11073 example by pressing @kbd{C} from the agenda dispatcher (see @ref{Agenda Dispatcher}). You can also directly set it with Emacs Lisp in 11074 the Emacs init file. The following example contains all valid agenda 11075 views: 11076 11077 @lisp 11078 (setq org-agenda-custom-commands 11079 '(("x" agenda) 11080 ("y" agenda*) 11081 ("w" todo "WAITING") 11082 ("W" todo-tree "WAITING") 11083 ("u" tags "+boss-urgent") 11084 ("v" tags-todo "+boss-urgent") 11085 ("U" tags-tree "+boss-urgent") 11086 ("f" occur-tree "\\<FIXME\\>") 11087 ("h" . "HOME+Name tags searches") ;description for "h" prefix 11088 ("hl" tags "+home+Lisa") 11089 ("hp" tags "+home+Peter") 11090 ("hk" tags "+home+Kim"))) 11091 @end lisp 11092 11093 The initial string in each entry defines the keys you have to press 11094 after the dispatcher command in order to access the command. Usually 11095 this is just a single character, but if you have many similar 11096 commands, you can also define two-letter combinations where the first 11097 character is the same in several combinations and serves as a prefix 11098 key@footnote{ You can provide a description for a prefix key by inserting a 11099 cons cell with the prefix and the description.}. The second parameter 11100 is the search type, followed by the string or regular expression to be 11101 used for the matching. The example above will therefore define: 11102 11103 @table @asis 11104 @item @kbd{x} 11105 as a global search for agenda entries planned@footnote{@emph{Planned} means here that these entries have some planning 11106 information attached to them, like a time-stamp, a scheduled or 11107 a deadline string. See @code{org-agenda-entry-types} on how to set what 11108 planning information is taken into account.} this week/day. 11109 11110 @item @kbd{y} 11111 as the same search, but only for entries with an hour specification 11112 like @samp{[h]h:mm}---think of them as appointments. 11113 11114 @item @kbd{w} 11115 as a global search for TODO entries with @samp{WAITING} as the TODO 11116 keyword. 11117 11118 @item @kbd{W} 11119 as the same search, but only in the current buffer and displaying 11120 the results as a sparse tree. 11121 11122 @item @kbd{u} 11123 as a global tags search for headlines tagged @samp{boss} but not 11124 @samp{urgent}. 11125 11126 @item @kbd{v} 11127 The same search, but limiting it to headlines that are also TODO 11128 items. 11129 11130 @item @kbd{U} 11131 as the same search, but only in the current buffer and displaying 11132 the result as a sparse tree. 11133 11134 @item @kbd{f} 11135 to create a sparse tree (again, current buffer only) with all 11136 entries containing the word @samp{FIXME}. 11137 11138 @item @kbd{h} 11139 as a prefix command for a @samp{HOME} tags search where you have to press 11140 an additional key (@kbd{l}, @kbd{p} or @kbd{k}) to 11141 select a name (Lisa, Peter, or Kim) as additional tag to match. 11142 @end table 11143 11144 Note that @code{*-tree} agenda views need to be called from an Org buffer 11145 as they operate on the current buffer only. 11146 11147 @node Block agenda 11148 @subsection Block agenda 11149 11150 @cindex block agenda 11151 @cindex agenda, with block views 11152 11153 Another possibility is the construction of agenda views that comprise 11154 the results of @emph{several} commands, each of which creates a block in 11155 the agenda buffer. The available commands include @code{agenda} for the 11156 daily or weekly agenda (as created with @kbd{a}) , @code{alltodo} for 11157 the global TODO list (as constructed with @kbd{t}), @code{stuck} for 11158 the list of stuck projects (as obtained with @kbd{#}) and the 11159 matching commands discussed above: @code{todo}, @code{tags}, and @code{tags-todo}. 11160 11161 Here are two examples: 11162 11163 @lisp 11164 (setq org-agenda-custom-commands 11165 '(("h" "Agenda and Home-related tasks" 11166 ((agenda "") 11167 (tags-todo "home") 11168 (tags "garden"))) 11169 ("o" "Agenda and Office-related tasks" 11170 ((agenda "") 11171 (tags-todo "work") 11172 (tags "office"))))) 11173 @end lisp 11174 11175 @noindent 11176 This defines @kbd{h} to create a multi-block view for stuff you 11177 need to attend to at home. The resulting agenda buffer contains your 11178 agenda for the current week, all TODO items that carry the tag @samp{home}, 11179 and also all lines tagged with @samp{garden}. Finally the command 11180 @kbd{o} provides a similar view for office tasks. 11181 11182 @node Setting options 11183 @subsection Setting options for custom commands 11184 11185 @cindex options, for custom agenda views 11186 11187 @vindex org-agenda-custom-commands 11188 Org mode contains a number of variables regulating agenda construction 11189 and display. The global variables define the behavior for all agenda 11190 commands, including the custom commands. However, if you want to 11191 change some settings just for a single custom view, you can do so. 11192 Setting options requires inserting a list of variable names and values 11193 at the right spot in @code{org-agenda-custom-commands}. For example: 11194 11195 @lisp 11196 (setq org-agenda-custom-commands 11197 '(("w" todo "WAITING" 11198 ((org-agenda-sorting-strategy '(priority-down)) 11199 (org-agenda-prefix-format " Mixed: "))) 11200 ("U" tags-tree "+boss-urgent" 11201 ((org-show-context-detail 'minimal))) 11202 ("N" search "" 11203 ((org-agenda-files '("~org/notes.org")) 11204 (org-agenda-text-search-extra-files nil))))) 11205 @end lisp 11206 11207 @noindent 11208 Now the @kbd{w} command sorts the collected entries only by 11209 priority, and the prefix format is modified to just say @samp{Mixed:} 11210 instead of giving the category of the entry. The sparse tags tree of 11211 @kbd{U} now turns out ultra-compact, because neither the headline 11212 hierarchy above the match, nor the headline following the match are 11213 shown. The command @kbd{N} does a text search limited to only 11214 a single file. 11215 11216 For command sets creating a block agenda, @code{org-agenda-custom-commands} 11217 has two separate spots for setting options. You can add options that 11218 should be valid for just a single command in the set, and options that 11219 should be valid for all commands in the set. The former are just 11220 added to the command entry; the latter must come after the list of 11221 command entries. Going back to the block agenda example (see @ref{Block agenda}), let's change the sorting strategy for the @kbd{h} 11222 commands to @code{priority-down}, but let's sort the results for @samp{garden} 11223 tags query in the opposite order, @code{priority-up}. This would look like 11224 this: 11225 11226 @lisp 11227 (setq org-agenda-custom-commands 11228 '(("h" "Agenda and Home-related tasks" 11229 ((agenda) 11230 (tags-todo "home") 11231 (tags "garden" 11232 ((org-agenda-sorting-strategy '(priority-up))))) 11233 ((org-agenda-sorting-strategy '(priority-down)))) 11234 ("o" "Agenda and Office-related tasks" 11235 ((agenda) 11236 (tags-todo "work") 11237 (tags "office"))))) 11238 @end lisp 11239 11240 As you see, the values and parentheses setting is a little complex. 11241 When in doubt, use the customize interface to set this variable---it 11242 fully supports its structure. Just one caveat: when setting options 11243 in this interface, the @emph{values} are just Lisp expressions. So if the 11244 value is a string, you need to add the double-quotes around the value 11245 yourself. 11246 11247 @vindex org-agenda-custom-commands-contexts 11248 To control whether an agenda command should be accessible from 11249 a specific context, you can customize 11250 @code{org-agenda-custom-commands-contexts}. Let's say for example that you 11251 have an agenda command @kbd{o} displaying a view that you only 11252 need when reading emails. Then you would configure this option like 11253 this: 11254 11255 @lisp 11256 (setq org-agenda-custom-commands-contexts 11257 '(("o" (in-mode . "message-mode")))) 11258 @end lisp 11259 11260 You can also tell that the command key @kbd{o} should refer to 11261 another command key @kbd{r}. In that case, add this command key 11262 like this: 11263 11264 @lisp 11265 (setq org-agenda-custom-commands-contexts 11266 '(("o" "r" (in-mode . "message-mode")))) 11267 @end lisp 11268 11269 See the docstring of the variable for more information. 11270 11271 @node Exporting Agenda Views 11272 @section Exporting Agenda Views 11273 11274 @cindex agenda views, exporting 11275 11276 If you are away from your computer, it can be very useful to have a 11277 printed version of some agenda views to carry around. Org mode can 11278 export custom agenda views as plain text, HTML@footnote{ For HTML you need 11279 to install Hrvoje Nikšić's @samp{htmlize.el} as an Emacs package from 11280 @uref{https://elpa.nongnu.org/, NonGNU ELPA} or from 11281 @uref{https://github.com/hniksic/emacs-htmlize, Hrvoje Nikšić's repository}.}, 11282 Postscript, PDF@footnote{To create PDF output, the Ghostscript ps2pdf utility must be 11283 installed on the system. Selecting a PDF file also creates the 11284 postscript file.}, and iCalendar files. If you 11285 want to do this only occasionally, use the following command: 11286 11287 @table @asis 11288 @item @kbd{C-x C-w} (@code{org-agenda-write}) 11289 @kindex C-x C-w 11290 @findex org-agenda-write 11291 @cindex exporting agenda views 11292 @cindex agenda views, exporting 11293 11294 @vindex org-agenda-exporter-settings 11295 Write the agenda view to a file. 11296 @end table 11297 11298 If you need to export certain agenda views frequently, you can 11299 associate any custom agenda command with a list of output file 11300 names@footnote{ If you want to store standard views like the weekly agenda 11301 or the global TODO list as well, you need to define custom commands 11302 for them in order to be able to specify file names.}. Here is an 11303 example that first defines custom commands for the agenda and the 11304 global TODO list, together with a number of files to which to export 11305 them. Then we define two block agenda commands and specify file names 11306 for them as well. File names can be relative to the current working 11307 directory, or absolute. 11308 11309 @lisp 11310 (setq org-agenda-custom-commands 11311 '(("X" agenda "" nil ("agenda.html" "agenda.ps")) 11312 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) 11313 ("h" "Agenda and Home-related tasks" 11314 ((agenda "") 11315 (tags-todo "home") 11316 (tags "garden")) 11317 nil 11318 ("~/views/home.html")) 11319 ("o" "Agenda and Office-related tasks" 11320 ((agenda) 11321 (tags-todo "work") 11322 (tags "office")) 11323 nil 11324 ("~/views/office.ps" "~/calendars/office.ics")))) 11325 @end lisp 11326 11327 The extension of the file name determines the type of export. If it 11328 is @samp{.html}, Org mode uses the htmlize package to convert the buffer to 11329 HTML and save it to this file name. If the extension is @samp{.ps}, 11330 @code{ps-print-buffer-with-faces} is used to produce Postscript output. If 11331 the extension is @samp{.ics}, iCalendar export is run export over all files 11332 that were used to construct the agenda, and limit the export to 11333 entries listed in the agenda. Any other extension produces a plain 11334 ASCII file. 11335 11336 The export files are @emph{not} created when you use one of those 11337 commands interactively because this might use too much overhead. 11338 Instead, there is a special command to produce @emph{all} specified 11339 files in one step: 11340 11341 @table @asis 11342 @item @kbd{e} (@code{org-store-agenda-views}) 11343 @kindex e @r{(Agenda dispatcher)} 11344 @findex org-store-agenda-views 11345 Export all agenda views that have export file names associated with 11346 them. 11347 @end table 11348 11349 You can use the options section of the custom agenda commands to also 11350 set options for the export commands. For example: 11351 11352 @lisp 11353 (setq org-agenda-custom-commands 11354 '(("X" agenda "" 11355 ((ps-number-of-columns 2) 11356 (ps-landscape-mode t) 11357 (org-agenda-prefix-format " [ ] ") 11358 (org-agenda-with-colors nil) 11359 (org-agenda-remove-tags t)) 11360 ("theagenda.ps")))) 11361 @end lisp 11362 11363 @noindent 11364 @vindex org-agenda-exporter-settings 11365 This command sets two options for the Postscript exporter, to make it 11366 print in two columns in landscape format---the resulting page can be 11367 cut in two and then used in a paper agenda. The remaining settings 11368 modify the agenda prefix to omit category and scheduling information, 11369 and instead include a checkbox to check off items. We also remove the 11370 tags to make the lines compact, and we do not want to use colors for 11371 the black-and-white printer. Settings specified in 11372 @code{org-agenda-exporter-settings} also apply, e.g., 11373 11374 @lisp 11375 (setq org-agenda-exporter-settings 11376 '((ps-number-of-columns 2) 11377 (ps-landscape-mode t) 11378 (org-agenda-add-entry-text-maxlines 5) 11379 (htmlize-output-type 'css))) 11380 @end lisp 11381 11382 @noindent 11383 but the settings in @code{org-agenda-custom-commands} take precedence. 11384 11385 From the command line you may also use: 11386 11387 @example 11388 emacs -eval (org-batch-store-agenda-views) -kill 11389 @end example 11390 11391 @noindent 11392 or, if you need to modify some parameters@footnote{ Quoting depends on the 11393 system you use, please check the FAQ for examples.} 11394 11395 @example 11396 emacs -eval '(org-batch-store-agenda-views \ 11397 org-agenda-span (quote month) \ 11398 org-agenda-start-day "2007-11-01" \ 11399 org-agenda-include-diary nil \ 11400 org-agenda-files (quote ("~/org/project.org")))' \ 11401 -kill 11402 @end example 11403 11404 @noindent 11405 which creates the agenda views restricted to the file 11406 @samp{~/org/project.org}, without diary entries and with a 30-day extent. 11407 11408 You can also extract agenda information in a way that allows further 11409 processing by other programs. See @ref{Extracting Agenda Information}, for 11410 more information. 11411 11412 @node Agenda Column View 11413 @section Using Column View in the Agenda 11414 11415 @cindex column view, in agenda 11416 @cindex agenda, column view 11417 11418 Column view (see @ref{Column View}) is normally used to view and edit 11419 properties embedded in the hierarchical structure of an Org file. It 11420 can be quite useful to use column view also from the agenda, where 11421 entries are collected by certain criteria. 11422 11423 @table @asis 11424 @item @kbd{C-c C-x C-c} (@code{org-agenda-columns}) 11425 @kindex C-c C-x C-c 11426 @findex org-agenda-columns 11427 11428 Turn on column view in the agenda. 11429 @end table 11430 11431 To understand how to use this properly, it is important to realize 11432 that the entries in the agenda are no longer in their proper outline 11433 environment. This causes the following issues: 11434 11435 @enumerate 11436 @item 11437 @vindex org-columns-default-format-for-agenda 11438 @vindex org-columns-default-format 11439 Org needs to make a decision which columns format to use. Since 11440 the entries in the agenda are collected from different files, and 11441 different files may have different columns formats, this is a 11442 non-trivial problem. Org first checks if 11443 @code{org-overriding-columns-format} is currently set, and if so, takes 11444 the format from there. You should set this variable only in the 11445 @emph{local settings section} of a custom agenda command (see @ref{Custom Agenda Views}) to make it valid for that specific agenda view. If 11446 no such binding exists, it checks, in sequence, 11447 @code{org-columns-default-format-for-agenda}, the format associated with 11448 the first item in the agenda (through a property or a @samp{#+COLUMNS} 11449 setting in that buffer) and finally @code{org-columns-default-format}. 11450 11451 @item 11452 @cindex @samp{CLOCKSUM}, special property 11453 If any of the columns has a summary type defined (see @ref{Column attributes}), turning on column view in the agenda visits all 11454 relevant agenda files and make sure that the computations of this 11455 property are up to date. This is also true for the special 11456 @samp{CLOCKSUM} property. Org then sums the values displayed in the 11457 agenda. In the daily/weekly agenda, the sums cover a single day; 11458 in all other views they cover the entire block. 11459 11460 It is important to realize that the agenda may show the same entry 11461 @emph{twice}---for example as scheduled and as a deadline---and it may 11462 show two entries from the same hierarchy (for example a @emph{parent} 11463 and its @emph{child}). In these cases, the summation in the agenda 11464 leads to incorrect results because some values count double. 11465 11466 @item 11467 When the column view in the agenda shows the @samp{CLOCKSUM} property, 11468 that is always the entire clocked time for this item. So even in 11469 the daily/weekly agenda, the clocksum listed in column view may 11470 originate from times outside the current view. This has the 11471 advantage that you can compare these values with a column listing 11472 the planned total effort for a task---one of the major 11473 applications for column view in the agenda. If you want 11474 information about clocked time in the displayed period use clock 11475 table mode (press @kbd{R} in the agenda). 11476 11477 @item 11478 @cindex @samp{CLOCKSUM_T}, special property 11479 When the column view in the agenda shows the @samp{CLOCKSUM_T} property, 11480 that is always today's clocked time for this item. So even in the 11481 weekly agenda, the clocksum listed in column view only originates 11482 from today. This lets you compare the time you spent on a task for 11483 today, with the time already spent---via @samp{CLOCKSUM}---and with 11484 the planned total effort for it. 11485 @end enumerate 11486 11487 @node Markup for Rich Contents 11488 @chapter Markup for Rich Contents 11489 11490 Org is primarily about organizing and searching through your 11491 plain-text notes. However, it also provides a lightweight yet robust 11492 markup language for rich text formatting and more. For instance, you 11493 may want to center or emphasize text. Or you may need to insert 11494 a formula or image in your writing. Org offers syntax for all of this 11495 and more. Used in conjunction with the export framework (see 11496 @ref{Exporting}), you can author beautiful documents in Org---like the fine 11497 manual you are currently reading. 11498 11499 @menu 11500 * Paragraphs:: The basic unit of text. 11501 * Emphasis and Monospace:: Bold, italic, etc. 11502 * Subscripts and Superscripts:: Simple syntax for raising/lowering text. 11503 * Special Symbols:: Greek letters and other symbols. 11504 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents. 11505 * Literal Examples:: Source code examples with special formatting. 11506 * Images:: Display an image. 11507 * Captions:: Describe tables, images... 11508 * Horizontal Rules:: Make a line. 11509 * Creating Footnotes:: Edit and read footnotes. 11510 @end menu 11511 11512 @node Paragraphs 11513 @section Paragraphs 11514 11515 @cindex paragraphs, markup rules 11516 Paragraphs are separated by at least one empty line. If you need to 11517 enforce a line break within a paragraph, use @samp{\\} at the end of 11518 a line. 11519 11520 @cindex line breaks, markup rules 11521 To preserve the line breaks, indentation and blank lines in a region, 11522 but otherwise use normal formatting, you can use this construct, which 11523 can also be used to format poetry. 11524 11525 @cindex @samp{BEGIN_VERSE} 11526 @cindex verse blocks 11527 @example 11528 #+BEGIN_VERSE 11529 Great clouds overhead 11530 Tiny black birds rise and fall 11531 Snow covers Emacs 11532 11533 ---AlexSchroeder 11534 #+END_VERSE 11535 @end example 11536 11537 When quoting a passage from another document, it is customary to 11538 format this as a paragraph that is indented on both the left and the 11539 right margin. You can include quotations in Org documents like this: 11540 11541 @cindex @samp{BEGIN_QUOTE} 11542 @cindex quote blocks 11543 @example 11544 #+BEGIN_QUOTE 11545 Everything should be made as simple as possible, 11546 but not any simpler ---Albert Einstein 11547 #+END_QUOTE 11548 @end example 11549 11550 If you would like to center some text, do it like this: 11551 11552 @cindex @samp{BEGIN_CENTER} 11553 @cindex center blocks 11554 @example 11555 #+BEGIN_CENTER 11556 Everything should be made as simple as possible, \\ 11557 but not any simpler 11558 #+END_CENTER 11559 @end example 11560 11561 @node Emphasis and Monospace 11562 @section Emphasis and Monospace 11563 11564 @cindex underlined text, markup rules 11565 @cindex bold text, markup rules 11566 @cindex italic text, markup rules 11567 @cindex verbatim text, markup rules 11568 @cindex code text, markup rules 11569 @cindex strike-through text, markup rules 11570 11571 You can make words @samp{*bold*}, @samp{/italic/}, @samp{_underlined_}, @samp{=verbatim=} 11572 and @samp{~code~}, and, if you must, @samp{+strike-through+}. Text in the code 11573 and verbatim string is not processed for Org specific syntax; it is 11574 exported verbatim. 11575 11576 @vindex org-fontify-emphasized-text 11577 To turn off fontification for marked up text, you can set 11578 @code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of 11579 available markup syntax, you can customize @code{org-emphasis-alist}. 11580 11581 Sometimes, when marked text also contains the marker character itself, 11582 the result may be unsettling. For example, 11583 11584 @example 11585 /One may expect this whole sentence to be italicized, but the 11586 following ~user/?variable~ contains =/= character, which effectively 11587 stops emphasis there./ 11588 @end example 11589 11590 You can use zero width space to help Org sorting out the ambiguity. 11591 See @ref{Escape Character} for more details. 11592 11593 @node Subscripts and Superscripts 11594 @section Subscripts and Superscripts 11595 11596 @cindex subscript 11597 @cindex superscript 11598 11599 @samp{^} and @samp{_} are used to indicate super- and subscripts. To increase 11600 the readability of ASCII text, it is not necessary, but OK, to 11601 surround multi-character sub- and superscripts with curly braces. For 11602 example 11603 11604 @example 11605 The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, 11606 the radius of Alpha Centauri is R_@{Alpha Centauri@} = 1.28 x R_@{sun@}. 11607 @end example 11608 11609 @vindex org-use-sub-superscripts 11610 If you write a text where the underscore is often used in a different 11611 context, Org's convention to always interpret these as subscripts can 11612 get in your way. Configure the variable @code{org-use-sub-superscripts} to 11613 change this convention. For example, when setting this variable to 11614 @code{@{@}}, @samp{a_b} is not interpreted as a subscript, but @samp{a_@{b@}} is. 11615 11616 You can set @code{org-use-sub-superscripts} in a file using the export 11617 option @samp{^:} (see @ref{Export Settings}). For example, @samp{#+OPTIONS: ^:@{@}} 11618 sets @code{org-use-sub-superscripts} to @code{@{@}} and limits super- and 11619 subscripts to the curly bracket notation. 11620 11621 You can also toggle the visual display of super- and subscripts: 11622 11623 @table @asis 11624 @item @kbd{C-c C-x \} (@code{org-toggle-pretty-entities}) 11625 @kindex C-c C-x \ 11626 @findex org-toggle-pretty-entities 11627 This command formats sub- and superscripts in a WYSIWYM way. 11628 @end table 11629 11630 @vindex org-pretty-entities 11631 @vindex org-pretty-entities-include-sub-superscripts 11632 Set both @code{org-pretty-entities} and 11633 @code{org-pretty-entities-include-sub-superscripts} to @code{t} to start with 11634 super- and subscripts @emph{visually} interpreted as specified by the 11635 option @code{org-use-sub-superscripts}. 11636 11637 @node Special Symbols 11638 @section Special Symbols 11639 11640 @cindex math symbols 11641 @cindex special symbols 11642 @cindex entities 11643 11644 You can use @LaTeX{}-like syntax to insert special symbols---named 11645 entities---like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to indicate 11646 an arrow. Completion for these symbols is available, just type @samp{\} 11647 and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible 11648 completions. If you need such a symbol inside a word, terminate it 11649 with a pair of curly brackets. For example 11650 11651 @example 11652 Pro tip: Given a circle \Gamma of diameter d, the length of its 11653 circumference is \pi@{@}d. 11654 @end example 11655 11656 @findex org-entities-help 11657 @vindex org-entities-user 11658 A large number of entities is provided, with names taken from both 11659 HTML and @LaTeX{}; you can comfortably browse the complete list from 11660 a dedicated buffer using the command @code{org-entities-help}. It is also 11661 possible to provide your own special symbols in the variable 11662 @code{org-entities-user}. 11663 11664 During export, these symbols are transformed into the native format of 11665 the exporter back-end. Strings like @samp{\alpha} are exported as @samp{α} in 11666 the HTML output, and as @samp{\(\alpha\)} in the @LaTeX{} output. Similarly, @samp{\nbsp} 11667 becomes @samp{ } in HTML and @samp{~} in @LaTeX{}. 11668 11669 @cindex special symbols, in-buffer display 11670 If you would like to see entities displayed as UTF-8 characters, use 11671 the following command@footnote{ You can turn this on by default by setting 11672 the variable @code{org-pretty-entities}, or on a per-file base with the 11673 @samp{STARTUP} option @samp{entitiespretty}.}: 11674 11675 @table @asis 11676 @item @kbd{C-c C-x \} (@code{org-toggle-pretty-entities}) 11677 @kindex C-c C-x \ 11678 @findex org-toggle-pretty-entities 11679 11680 Toggle display of entities as UTF-8 characters. This does not 11681 change the buffer content which remains plain ASCII, but it overlays 11682 the UTF-8 character for display purposes only. 11683 @end table 11684 11685 @cindex shy hyphen, special symbol 11686 @cindex dash, special symbol 11687 @cindex ellipsis, special symbol 11688 In addition to regular entities defined above, Org exports in a 11689 special way@footnote{ This behavior can be disabled with @samp{-} export setting 11690 (see @ref{Export Settings}).} the following commonly used character 11691 combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---} are 11692 converted into dashes, and @samp{...} becomes a compact set of dots. 11693 11694 @node Embedded @LaTeX{} 11695 @section Embedded @LaTeX{} 11696 11697 @cindex @TeX{} interpretation 11698 @cindex @LaTeX{} interpretation 11699 11700 Plain ASCII is normally sufficient for almost all note taking. 11701 Exceptions include scientific notes, which often require mathematical 11702 symbols and the occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on Donald@tie{}E@.@tie{}Knuth's @TeX{} 11703 system. Many of the features described here as ``@LaTeX{}'' are really 11704 from @TeX{}, but for simplicity I am blurring this distinction.} is widely used to 11705 typeset scientific documents. Org mode supports embedding @LaTeX{} code 11706 into its files, because many academics are used to writing and reading 11707 @LaTeX{} source code, and because it can be readily processed to produce 11708 pretty output for a number of export back-ends. 11709 11710 @menu 11711 * @LaTeX{} fragments:: Complex formulas made easy. 11712 * Previewing @LaTeX{} fragments:: What will this snippet look like? 11713 * CD@LaTeX{} mode:: Speed up entering of formulas. 11714 @end menu 11715 11716 @node @LaTeX{} fragments 11717 @subsection @LaTeX{} fragments 11718 11719 @cindex @LaTeX{} fragments 11720 11721 @vindex org-format-latex-header 11722 Org mode can contain @LaTeX{} math fragments, and it supports ways to 11723 process these for several export back-ends. When exporting to @LaTeX{}, 11724 the code is left as it is. When exporting to HTML, Org can use either 11725 @uref{https://www.mathjax.org, MathJax} (see @ref{Math formatting in HTML export}) or transcode the math 11726 into images (see @ref{Previewing @LaTeX{} fragments}). 11727 11728 @LaTeX{} fragments do not need any special marking at all. The following 11729 snippets are identified as @LaTeX{} source code: 11730 11731 @itemize 11732 @item 11733 Environments of any kind@footnote{When MathJax is used, only the environments recognized by 11734 MathJax are processed. When dvipng, dvisvgm, or ImageMagick suite is 11735 used to create images, any @LaTeX{} environment is handled.}. The only requirement is that the 11736 @samp{\begin} statement appears on a new line, preceded by only 11737 whitespace. 11738 11739 @item 11740 Text within the usual @LaTeX{} math delimiters. To avoid conflicts 11741 with currency specifications, single @samp{$} characters are only 11742 recognized as math delimiters if the enclosed text contains at most 11743 two line breaks, is directly attached to the @samp{$} characters with no 11744 whitespace in between, and if the closing @samp{$} is followed by 11745 whitespace, punctuation or a dash. For the other delimiters, there 11746 is no such restriction, so when in doubt, use @samp{\(...\)} as inline 11747 math delimiters. 11748 @end itemize 11749 11750 @noindent 11751 For example: 11752 11753 @example 11754 \begin@{equation@} % arbitrary environments, 11755 x=\sqrt@{b@} % even tables, figures 11756 \end@{equation@} % etc 11757 11758 If $a^2=b$ and \( b=2 \), then the solution must be 11759 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. 11760 @end example 11761 11762 @vindex org-export-with-latex 11763 @LaTeX{} processing can be configured with the variable 11764 @code{org-export-with-latex}. The default setting is @code{t} which means 11765 MathJax for HTML, and no processing for ASCII and @LaTeX{} back-ends. 11766 You can also set this variable on a per-file basis using one of these 11767 lines: 11768 11769 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 11770 @item @samp{#+OPTIONS: tex:t} 11771 @tab Do the right thing automatically (MathJax) 11772 @item @samp{#+OPTIONS: tex:nil} 11773 @tab Do not process @LaTeX{} fragments at all 11774 @item @samp{#+OPTIONS: tex:verbatim} 11775 @tab Verbatim export, for jsMath or so 11776 @end multitable 11777 11778 @node Previewing @LaTeX{} fragments 11779 @subsection Previewing @LaTeX{} fragments 11780 11781 @cindex @LaTeX{} fragments, preview 11782 11783 @vindex org-preview-latex-default-process 11784 If you have a working @LaTeX{} installation and @samp{dvipng}, @samp{dvisvgm} or 11785 @samp{convert} installed@footnote{These are respectively available at 11786 @uref{https://sourceforge.net/projects/dvipng/}, @uref{http://dvisvgm.bplaced.net/} 11787 and from the ImageMagick suite. Choose the converter by setting the 11788 variable @code{org-preview-latex-default-process} accordingly.}, @LaTeX{} fragments can be processed to 11789 produce images of the typeset expressions to be used for inclusion 11790 while exporting to HTML (see @ref{@LaTeX{} fragments}), or for inline 11791 previewing within Org mode. 11792 11793 @vindex org-format-latex-options 11794 @vindex org-format-latex-header 11795 You can customize the variables @code{org-format-latex-options} and 11796 @code{org-format-latex-header} to influence some aspects of the preview. 11797 In particular, the @code{:scale} (and for HTML export, @code{:html-scale}) 11798 property of the former can be used to adjust the size of the preview 11799 images. 11800 11801 @table @asis 11802 @item @kbd{C-c C-x C-l} (@code{org-latex-preview}) 11803 @kindex C-c C-x C-l 11804 @findex org-latex-preview 11805 11806 Produce a preview image of the @LaTeX{} fragment at point and overlay 11807 it over the source code. If there is no fragment at point, process 11808 all fragments in the current entry---between two headlines. 11809 11810 When called with a single prefix argument, clear all images in the 11811 current entry. Two prefix arguments produce a preview image for all 11812 fragments in the buffer, while three of them clear all the images in 11813 that buffer. 11814 @end table 11815 11816 @vindex org-startup-with-latex-preview 11817 You can turn on the previewing of all @LaTeX{} fragments in a file with 11818 11819 @example 11820 #+STARTUP: latexpreview 11821 @end example 11822 11823 11824 To disable it, simply use 11825 11826 @example 11827 #+STARTUP: nolatexpreview 11828 @end example 11829 11830 @node CD@LaTeX{} mode 11831 @subsection Using CD@LaTeX{} to enter math 11832 11833 @cindex CD@LaTeX{} 11834 11835 CD@LaTeX{} mode is a minor mode that is normally used in combination with 11836 a major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of 11837 environments and math templates. Inside Org mode, you can make use of 11838 some of the features of CD@LaTeX{} mode. You need to install 11839 @samp{cdlatex.el} and @samp{texmathp.el} (the latter comes also with AUC@TeX{}) 11840 from @uref{https://elpa.nongnu.org/, NonGNU ELPA} with the @uref{https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html, Emacs packaging system} or alternatively from 11841 @uref{https://staff.fnwi.uva.nl/c.dominik/Tools/cdlatex/}. Do not use 11842 CD@LaTeX{} mode itself under Org mode, but use the special version Org 11843 CD@LaTeX{} minor mode that comes as part of Org. Turn it on for the 11844 current buffer with @kbd{M-x org-cdlatex-mode}, or for all Org 11845 files with 11846 11847 @lisp 11848 (add-hook 'org-mode-hook #'turn-on-org-cdlatex) 11849 @end lisp 11850 11851 When this mode is enabled, the following features are present (for 11852 more details see the documentation of CD@LaTeX{} mode): 11853 11854 @table @asis 11855 @item @kbd{C-c @{} 11856 @kindex C-c @{ 11857 11858 Insert an environment template. 11859 11860 @item @kbd{@key{TAB}} 11861 @kindex TAB 11862 11863 The @kbd{@key{TAB}} key expands the template if point is inside a 11864 @LaTeX{} fragment@footnote{ Org mode has a method to test if point is inside 11865 such a fragment, see the documentation of the function 11866 @code{org-inside-LaTeX-fragment-p}.}. For example, @kbd{@key{TAB}} 11867 expands @samp{fr} to @samp{\frac@{@}@{@}} and position point correctly inside the 11868 first brace. Another @kbd{@key{TAB}} gets you into the second brace. 11869 11870 Even outside fragments, @kbd{@key{TAB}} expands environment 11871 abbreviations at the beginning of a line. For example, if you write 11872 @samp{equ} at the beginning of a line and press @kbd{@key{TAB}}, this 11873 abbreviation is expanded to an @samp{equation} environment. To get 11874 a list of all abbreviations, type @kbd{M-x cdlatex-command-help}. 11875 11876 @item @kbd{^} 11877 @itemx @kbd{_} 11878 @kindex _ 11879 @kindex ^ 11880 @vindex cdlatex-simplify-sub-super-scripts 11881 11882 Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment 11883 inserts these characters together with a pair of braces. If you use 11884 @kbd{@key{TAB}} to move out of the braces, and if the braces surround 11885 only a single character or macro, they are removed again (depending 11886 on the variable @code{cdlatex-simplify-sub-super-scripts}). 11887 11888 @item @kbd{`} 11889 @kindex ` 11890 11891 Pressing the backquote followed by a character inserts math macros, 11892 also outside @LaTeX{} fragments. If you wait more than 1.5 seconds 11893 after the backquote, a help window pops up. 11894 11895 @item @kbd{'} 11896 @kindex ' 11897 11898 Pressing the single-quote followed by another character modifies the 11899 @LaTeX{} symbol before point with an accent or a font. If you wait 11900 more than 1.5 seconds after the single-quote, a help window pops up. 11901 Character modification works only inside @LaTeX{} fragments; outside 11902 the quote is normal. 11903 @end table 11904 11905 @node Literal Examples 11906 @section Literal Examples 11907 11908 @cindex literal examples, markup rules 11909 @cindex code line references, markup rules 11910 11911 You can include literal examples that should not be subjected to 11912 markup. Such examples are typeset in monospace, so this is well 11913 suited for source code and similar examples. 11914 11915 @cindex @samp{BEGIN_EXAMPLE} 11916 @cindex example block 11917 @example 11918 #+BEGIN_EXAMPLE 11919 Some example from a text file. 11920 #+END_EXAMPLE 11921 @end example 11922 11923 @cindex comma escape, in literal examples 11924 There is one limitation, however. You must insert a comma right 11925 before lines starting with either @samp{*}, @samp{,*}, @samp{#+} or @samp{,#+}, as those 11926 may be interpreted as outlines nodes or some other special syntax. 11927 Org transparently strips these additional commas whenever it accesses 11928 the contents of the block. 11929 11930 @example 11931 #+BEGIN_EXAMPLE 11932 ,* I am no real headline 11933 #+END_EXAMPLE 11934 @end example 11935 11936 For simplicity when using small examples, you can also start the 11937 example lines with a colon followed by a space. There may also be 11938 additional whitespace before the colon: 11939 11940 @example 11941 Here is an example 11942 : Some example from a text file. 11943 @end example 11944 11945 @cindex formatting source code, markup rules 11946 @vindex org-latex-src-block-backend 11947 If the example is source code from a programming language, or any 11948 other text that can be marked up by Font Lock in Emacs, you can ask 11949 for the example to look like the fontified Emacs buffer@footnote{This works automatically for the HTML backend (it requires 11950 version 1.34 of the @samp{htmlize.el} package, which you need to install). 11951 Fontified code chunks in @LaTeX{} can be achieved using either the 11952 @uref{https://www.ctan.org/pkg/listings, listings} @LaTeX{} package, @uref{https://www.ctan.org/pkg/minted, minted} @LaTeX{} package, or by using 11953 @uref{https://elpa.gnu.org/packages/engrave-faces.html, engrave-faces} . Refer to @code{org-latex-src-block-backend} for details.}. This 11954 is done with the code block, where you also need to specify the name 11955 of the major mode that should be used to fontify the example@footnote{Source code in code blocks may also be evaluated either 11956 interactively or on export. See @ref{Working with Source Code} for more 11957 information on evaluating code blocks.}, 11958 see @ref{Structure Templates} for shortcuts to easily insert code blocks. 11959 11960 @cindex @samp{BEGIN_SRC} 11961 @cindex source block 11962 @example 11963 #+BEGIN_SRC emacs-lisp 11964 (defun org-xor (a b) 11965 "Exclusive or." 11966 (if a (not b) b)) 11967 #+END_SRC 11968 @end example 11969 11970 Both in @samp{example} and in @samp{src} snippets, you can add a @samp{-n} switch to 11971 the end of the @samp{#+BEGIN} line, to get the lines of the example 11972 numbered. The @samp{-n} takes an optional numeric argument specifying the 11973 starting line number of the block. If you use a @samp{+n} switch, the 11974 numbering from the previous numbered snippet is continued in the 11975 current one. The @samp{+n} switch can also take a numeric argument. This 11976 adds the value of the argument to the last line of the previous block 11977 to determine the starting line number. 11978 11979 @example 11980 #+BEGIN_SRC emacs-lisp -n 20 11981 ;; This exports with line number 20. 11982 (message "This is line 21") 11983 #+END_SRC 11984 11985 #+BEGIN_SRC emacs-lisp +n 10 11986 ;; This is listed as line 31. 11987 (message "This is line 32") 11988 #+END_SRC 11989 @end example 11990 11991 In literal examples, Org interprets strings like @samp{(ref:name)} as 11992 labels, and use them as targets for special hyperlinks like 11993 @samp{[[(name)]]}---i.e., the reference name enclosed in single parenthesis. 11994 In HTML, hovering the mouse over such a link remote-highlights the 11995 corresponding code line, which is kind of cool. 11996 11997 You can also add a @samp{-r} switch which @emph{removes} the labels from the 11998 source code@footnote{ Adding @samp{-k} to @samp{-n -r} @emph{keeps} the labels in the 11999 source code while using line numbers for the links, which might be 12000 useful to explain those in an Org mode example code.}. With the @samp{-n} 12001 switch, links to these references are labeled by the line numbers from 12002 the code listing. Otherwise links use the labels with no parentheses. 12003 Here is an example: 12004 12005 @example 12006 #+BEGIN_SRC emacs-lisp -n -r 12007 (save-excursion (ref:sc) 12008 (goto-char (point-min)) (ref:jump) 12009 #+END_SRC 12010 In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]] 12011 jumps to point-min. 12012 @end example 12013 12014 @cindex indentation, in source blocks 12015 Source code and examples may be @emph{indented} in order to align nicely 12016 with the surrounding text, and in particular with plain list structure 12017 (see @ref{Plain Lists}). By default, Org only retains the relative 12018 indentation between lines, e.g., when exporting the contents of the 12019 block. However, you can use the @samp{-i} switch to also preserve the 12020 global indentation, if it does matter. See @ref{Editing Source Code}. 12021 12022 @vindex org-coderef-label-format 12023 If the syntax for the label format conflicts with the language syntax, 12024 use a @samp{-l} switch to change the format, for example 12025 12026 @example 12027 #+BEGIN_SRC pascal -n -r -l "((%s))" 12028 @end example 12029 12030 12031 @noindent 12032 See also the variable @code{org-coderef-label-format}. 12033 12034 HTML export also allows examples to be published as text areas (see 12035 @ref{Text areas in HTML export}). 12036 12037 Because the @samp{#+BEGIN} @dots{} @samp{#+END} patterns need to be added so often, 12038 a shortcut is provided (see @ref{Structure Templates}). 12039 12040 @table @asis 12041 @item @kbd{C-c '} (@code{org-edit-special}) 12042 @kindex C-c ' 12043 @findex org-edit-special 12044 Edit the source code example at point in its native mode. This 12045 works by switching to a temporary buffer with the source code. You 12046 need to exit by pressing @kbd{C-c '} again. The edited version 12047 then replaces the old version in the Org buffer. Fixed-width 12048 regions---where each line starts with a colon followed by a 12049 space---are edited using Artist mode@footnote{ You may select a different 12050 mode with the variable @code{org-edit-fixed-width-region-mode}.} to allow 12051 creating ASCII drawings easily. Using this command in an empty line 12052 creates a new fixed-width region. 12053 @end table 12054 12055 @cindex storing link, in a source code buffer 12056 Calling @code{org-store-link} (see @ref{Handling Links}) while editing a source 12057 code example in a temporary buffer created with @kbd{C-c '} 12058 prompts for a label. Make sure that it is unique in the current 12059 buffer, and insert it with the proper formatting like @samp{(ref:label)} at 12060 the end of the current line. Then the label is stored as a link 12061 @samp{(label)}, for retrieval with @kbd{C-c C-l}. 12062 12063 @node Images 12064 @section Images 12065 12066 @cindex inlining images 12067 @cindex images, markup rules 12068 An image is a link to an image file@footnote{ What Emacs considers to be an 12069 image depends on @code{image-file-name-extensions} and 12070 @code{image-file-name-regexps}.} that does not have a description part, for 12071 example 12072 12073 @example 12074 ./img/cat.jpg 12075 @end example 12076 12077 12078 If you wish to define a caption for the image (see @ref{Captions}) and 12079 maybe a label for internal cross references (see @ref{Internal Links}), 12080 make sure that the link is on a line by itself and precede it with 12081 @samp{CAPTION} and @samp{NAME} keywords as follows: 12082 12083 @example 12084 #+CAPTION: This is the caption for the next figure link (or table) 12085 #+NAME: fig:SED-HR4049 12086 [[./img/a.jpg]] 12087 @end example 12088 12089 Such images can be displayed within the buffer with the following 12090 command: 12091 12092 @table @asis 12093 @item @kbd{C-c C-x C-v} (@code{org-toggle-inline-images}) 12094 @kindex C-c C-x C-v 12095 @findex org-toggle-inline-images 12096 @vindex org-startup-with-inline-images 12097 Toggle the inline display of linked images. When called with a 12098 prefix argument, also display images that do have a link 12099 description. You can ask for inline images to be displayed at 12100 startup by configuring the variable 12101 @code{org-startup-with-inline-images}@footnote{ The variable 12102 @code{org-startup-with-inline-images} can be set within a buffer with the 12103 @samp{STARTUP} options @samp{inlineimages} and @samp{noinlineimages}.}. 12104 @end table 12105 12106 12107 @vindex org-image-actual-width 12108 @cindex @samp{ORG-IMAGE-ACTUAL-WIDTH}, property 12109 By default, Org mode displays inline images according to their 12110 actual width. You can customize the displayed image width using 12111 @code{org-image-actual-width} variable (globally) or 12112 @samp{ORG-IMAGE-ACTUAL-WIDTH} property (subtree-level)@footnote{ The width can 12113 be customized in Emacs >= 24.1, built with imagemagick support.}. 12114 Their value can be the following: 12115 @itemize 12116 @item 12117 (default) Non-nil, use the actual width of images when inlining them. 12118 @item 12119 When set to a number, use imagemagick (when available) to set the 12120 image's width to this value. 12121 @item 12122 When set to a number in a list, try to get the width from any 12123 @samp{#+ATTR.*} keyword if it matches a width specification like: 12124 @example 12125 #+ATTR_HTML: :width 300px 12126 @end example 12127 and fall back on that number if none is found. 12128 @item 12129 When set to nil, try to get the width from an @samp{#+ATTR.*} keyword 12130 and fall back on the original width if none is found. 12131 @end itemize 12132 12133 12134 @vindex org-cycle-inline-images-display 12135 Inline images can also be displayed when cycling the folding state. 12136 When custom option @code{org-cycle-inline-images-display} is set, the 12137 visible inline images under subtree will be displayed automatically. 12138 12139 @node Captions 12140 @section Captions 12141 12142 @cindex captions, markup rules 12143 @cindex @samp{CAPTION}, keyword 12144 12145 You can assign a caption to a specific part of a document by inserting 12146 a @samp{CAPTION} keyword immediately before it: 12147 12148 @example 12149 #+CAPTION: This is the caption for the next table (or link) 12150 | ... | ... | 12151 |-----+-----| 12152 @end example 12153 12154 Optionally, the caption can take the form: 12155 12156 @example 12157 #+CAPTION[Short caption]: Longer caption. 12158 @end example 12159 12160 12161 Even though images and tables are prominent examples of captioned 12162 structures, the same caption mechanism can apply to many 12163 others---e.g., @LaTeX{} equations, source code blocks. Depending on the 12164 export back-end, those may or may not be handled. 12165 12166 @node Horizontal Rules 12167 @section Horizontal Rules 12168 12169 @cindex horizontal rules, markup rules 12170 A line consisting of only dashes, and at least 5 of them, is exported 12171 as a horizontal line. 12172 12173 @node Creating Footnotes 12174 @section Creating Footnotes 12175 12176 @cindex footnotes 12177 12178 A footnote is started by a footnote marker in square brackets in 12179 column 0, no indentation allowed. It ends at the next footnote 12180 definition, headline, or after two consecutive empty lines. The 12181 footnote reference is simply the marker in square brackets, inside 12182 text. Markers always start with @samp{fn:}. For example: 12183 12184 @example 12185 The Org website[fn:1] now looks a lot better than it used to. 12186 ... 12187 [fn:55] The link is: https://orgmode.org 12188 @end example 12189 12190 Org mode extends the number-based syntax to @emph{named} footnotes and 12191 optional inline definition. Here are the valid references: 12192 12193 @table @asis 12194 @item @samp{[fn:NAME]} 12195 A named footnote reference, where @var{NAME} is a unique 12196 label word, or, for simplicity of automatic creation, a number. 12197 12198 @item @samp{[fn:: This is the inline definition of this footnote]} 12199 An anonymous footnote where the definition is given directly at the 12200 reference point. 12201 12202 @item @samp{[fn:NAME: a definition]} 12203 An inline definition of a footnote, which also specifies a name for 12204 the note. Since Org allows multiple references to the same note, 12205 you can then use @samp{[fn:NAME]} to create additional references. 12206 @end table 12207 12208 @vindex org-footnote-auto-label 12209 Footnote labels can be created automatically, or you can create names 12210 yourself. This is handled by the variable @code{org-footnote-auto-label} 12211 and its corresponding @samp{STARTUP} keywords. See the docstring of that 12212 variable for details. 12213 12214 The following command handles footnotes: 12215 12216 @table @asis 12217 @item @kbd{C-c C-x f} 12218 The footnote action command. 12219 12220 @kindex C-c C-x f 12221 When point is on a footnote reference, jump to the definition. When 12222 it is at a definition, jump to the---first---reference. 12223 12224 @vindex org-footnote-define-inline 12225 @vindex org-footnote-section 12226 Otherwise, create a new footnote. Depending on the variable 12227 @code{org-footnote-define-inline}@footnote{ The corresponding in-buffer 12228 setting is: @samp{#+STARTUP: fninline} or @samp{#+STARTUP: nofninline}.}, the 12229 definition is placed right into the text as part of the reference, 12230 or separately into the location determined by the variable 12231 @code{org-footnote-section}. 12232 12233 When this command is called with a prefix argument, a menu of 12234 additional options is offered: 12235 12236 @multitable @columnfractions 0.1 0.9 12237 @item @kbd{s} 12238 @tab Sort the footnote definitions by reference sequence. 12239 @item @kbd{r} 12240 @tab Renumber the simple @samp{fn:N} footnotes. 12241 @item @kbd{S} 12242 @tab Short for first @kbd{r}, then @kbd{s} action. 12243 @item @kbd{n} 12244 @tab Rename all footnotes into a @samp{fn:1} @dots{} @samp{fn:n} sequence. 12245 @item @kbd{d} 12246 @tab Delete the footnote at point, including definition and references. 12247 @end multitable 12248 12249 @vindex org-footnote-auto-adjust 12250 Depending on the variable @code{org-footnote-auto-adjust}@footnote{ The 12251 corresponding in-buffer options are @samp{#+STARTUP: fnadjust} and 12252 @samp{#+STARTUP: nofnadjust}.}, renumbering and sorting footnotes can be 12253 automatic after each insertion or deletion. 12254 12255 @item @kbd{C-c C-c} 12256 @kindex C-c C-c 12257 If point is on a footnote reference, jump to the definition. If it 12258 is at the definition, jump back to the reference. When called at 12259 a footnote location with a prefix argument, offer the same menu as 12260 @kbd{C-c C-x f}. 12261 12262 @item @kbd{C-c C-o} or @kbd{mouse-1/2} 12263 @kindex C-c C-o 12264 @kindex mouse-1 12265 @kindex mouse-2 12266 Footnote labels are also links to the corresponding definition or 12267 reference, and you can use the usual commands to follow these links. 12268 @end table 12269 12270 @node Exporting 12271 @chapter Exporting 12272 12273 @cindex exporting 12274 12275 At some point you might want to print your notes, publish them on the 12276 web, or share them with people not using Org. Org can convert and 12277 export documents to a variety of other formats while retaining as much 12278 structure (see @ref{Document Structure}) and markup (see @ref{Markup for Rich Contents}) as possible. 12279 12280 @cindex export back-end 12281 The libraries responsible for translating Org files to other formats 12282 are called @emph{back-ends}. Org ships with support for the following 12283 back-ends: 12284 12285 @itemize 12286 @item 12287 @emph{ascii} (ASCII format) 12288 @item 12289 @emph{beamer} (@LaTeX{} Beamer format) 12290 @item 12291 @emph{html} (HTML format) 12292 @item 12293 @emph{icalendar} (iCalendar format) 12294 @item 12295 @emph{latex} (@LaTeX{} format) 12296 @item 12297 @emph{md} (Markdown format) 12298 @item 12299 @emph{odt} (OpenDocument Text format) 12300 @item 12301 @emph{org} (Org format) 12302 @item 12303 @emph{texinfo} (Texinfo format) 12304 @item 12305 @emph{man} (Man page format) 12306 @end itemize 12307 12308 Users can install libraries for additional formats from the Emacs 12309 packaging system. For easy discovery, these packages have a common 12310 naming scheme: @code{ox-NAME}, where @var{NAME} is a format. For 12311 example, @code{ox-koma-letter} for @emph{koma-letter} back-end. More libraries 12312 can be found in the @samp{org-contrib} repository (see @ref{Installation}). 12313 12314 @vindex org-export-backends 12315 Org only loads back-ends for the following formats by default: ASCII, 12316 HTML, iCalendar, @LaTeX{}, and ODT@. Additional back-ends can be loaded 12317 in either of two ways: by configuring the @code{org-export-backends} 12318 variable, or by requiring libraries in the Emacs init file. For 12319 example, to load the Markdown back-end, add this to your Emacs config: 12320 12321 @lisp 12322 (require 'ox-md) 12323 @end lisp 12324 12325 @menu 12326 * The Export Dispatcher:: The main interface. 12327 * Export Settings:: Common export settings. 12328 * Table of Contents:: The if and where of the table of contents. 12329 * Include Files:: Include additional files into a document. 12330 * Macro Replacement:: Use macros to create templates. 12331 * Comment Lines:: What will not be exported. 12332 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding. 12333 * Beamer Export:: Producing presentations and slides. 12334 * HTML Export:: Exporting to HTML. 12335 * @LaTeX{} Export:: Exporting to @LaTeX{} and processing to PDF. 12336 * Markdown Export:: Exporting to Markdown. 12337 * OpenDocument Text Export:: Exporting to OpenDocument Text. 12338 * Org Export:: Exporting to Org. 12339 * Texinfo Export:: Exporting to Texinfo. 12340 * iCalendar Export:: Exporting to iCalendar. 12341 * Other Built-in Back-ends:: Exporting to a man page. 12342 * Advanced Export Configuration:: Fine-tuning the export output. 12343 * Export in Foreign Buffers:: Author tables and lists in Org syntax. 12344 @end menu 12345 12346 @node The Export Dispatcher 12347 @section The Export Dispatcher 12348 12349 @cindex dispatcher, for export commands 12350 @cindex export, dispatcher 12351 12352 The export dispatcher is the main interface for Org's exports. 12353 A hierarchical menu presents the currently configured export formats. 12354 Options are shown as easy toggle switches on the same screen. 12355 12356 @vindex org-export-dispatch-use-expert-ui 12357 Org also has a minimal prompt interface for the export dispatcher. 12358 When the variable @code{org-export-dispatch-use-expert-ui} is set to 12359 a non-@code{nil} value, Org prompts in the minibuffer. To switch back to 12360 the hierarchical menu, press @kbd{?}. 12361 12362 @table @asis 12363 @item @kbd{C-c C-e} (@code{org-export}) 12364 @kindex C-c C-e 12365 @findex org-export 12366 12367 Invokes the export dispatcher interface. The options show default 12368 settings. The @kbd{C-u} prefix argument preserves options from 12369 the previous export, including any subtree selections. 12370 @end table 12371 12372 Org exports the entire buffer by default. If the Org buffer has an 12373 active region, then Org exports just that region. 12374 12375 Within the dispatcher interface, the following key combinations can 12376 further alter what is exported, and how. 12377 12378 @table @asis 12379 @item @kbd{C-a} 12380 @kindex C-c C-e C-a 12381 12382 Toggle asynchronous export. Asynchronous export uses an external 12383 Emacs process with a specially configured initialization file to 12384 complete the exporting process in the background, without tying-up 12385 Emacs. This is particularly useful when exporting long documents. 12386 12387 Output from an asynchronous export is saved on the @emph{export stack}. 12388 To view this stack, call the export dispatcher with a double 12389 @kbd{C-u} prefix argument. If already in the export dispatcher 12390 menu, @kbd{&} displays the stack. 12391 12392 @vindex org-export-in-background 12393 You can make asynchronous export the default by setting 12394 @code{org-export-in-background}. 12395 12396 @vindex org-export-async-init-file 12397 You can set the initialization file used by the background process 12398 by setting @code{org-export-async-init-file}. 12399 12400 @item @kbd{C-b} 12401 @kindex C-c C-e C-b 12402 12403 Toggle body-only export. Useful for excluding headers and footers 12404 in the export. Affects only those back-end formats that have 12405 sections like @samp{<head>...</head>} in HTML@. 12406 12407 @item @kbd{C-s} 12408 @kindex C-c C-e C-s 12409 12410 Toggle subtree export. When turned on, Org exports only the 12411 subtree starting from point position at the time the export 12412 dispatcher was invoked. Org uses the top heading of this subtree 12413 as the document's title. If point is not on a heading, Org uses the 12414 nearest enclosing header. If point is in the document preamble, Org 12415 signals an error and aborts export. 12416 12417 @vindex org-export-initial-scope 12418 To make subtree export the default, customize the variable 12419 @code{org-export-initial-scope}. 12420 12421 @item @kbd{C-v} 12422 @kindex C-c C-e C-v 12423 12424 Toggle visible-only export. This is useful for exporting only 12425 certain parts of an Org document by adjusting the visibility of 12426 particular headings. See also @ref{Sparse Trees}. 12427 @end table 12428 12429 @node Export Settings 12430 @section Export Settings 12431 12432 @cindex options, for export 12433 @cindex Export, settings 12434 12435 @cindex @samp{OPTIONS}, keyword 12436 Export options can be set: globally with variables; for an individual 12437 file by making variables buffer-local with in-buffer settings (see 12438 @ref{In-buffer Settings}); by setting individual keywords or 12439 specifying them in compact form with the @samp{OPTIONS} keyword; or for 12440 a tree by setting properties (see @ref{Properties and Columns}). Options 12441 set at a specific level override options set at a more general level. 12442 12443 @cindex @samp{SETUPFILE}, keyword 12444 In-buffer settings may appear anywhere in the file, either directly or 12445 indirectly through a file included using @samp{#+SETUPFILE: filename or 12446 URL} syntax. Option keyword sets tailored to a particular back-end 12447 can be inserted from the export dispatcher (see @ref{The Export Dispatcher}) using the @samp{Insert template} command by pressing 12448 @kbd{#}. To insert keywords individually, a good way to make 12449 sure the keyword is correct is to type @samp{#+} and then to use 12450 @kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-@key{TAB}} to switch windows. 12451 Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead.} for completion. 12452 12453 The export keywords available for every back-end, and their equivalent 12454 global variables, include: 12455 12456 @table @asis 12457 @item @samp{AUTHOR} 12458 @cindex @samp{AUTHOR}, keyword 12459 @vindex user-full-name 12460 The document author (@code{user-full-name}). 12461 12462 @item @samp{CREATOR} 12463 @cindex @samp{CREATOR}, keyword 12464 @vindex org-expot-creator-string 12465 Entity responsible for output generation 12466 (@code{org-export-creator-string}). 12467 12468 @item @samp{DATE} 12469 @cindex @samp{DATE}, keyword 12470 @vindex org-export-date-timestamp-format 12471 A date or a time-stamp@footnote{ The variable 12472 @code{org-export-date-timestamp-format} defines how this timestamp are 12473 exported.}. 12474 12475 @item @samp{EMAIL} 12476 @cindex @samp{EMAIL}, keyword 12477 @vindex user-mail-address 12478 The email address (@code{user-mail-address}). 12479 12480 @item @samp{LANGUAGE} 12481 @cindex @samp{LANGUAGE}, keyword 12482 @vindex org-export-default-language 12483 Language to use for translating certain strings 12484 (@code{org-export-default-language}). With @samp{#+LANGUAGE: fr}, for 12485 example, Org translates @samp{Table of contents} to the French @samp{Table des 12486 matières}@footnote{For export to @LaTeX{} format---or @LaTeX{}-related formats such as 12487 Beamer---, the @samp{org-latex-package-alist} variable needs further 12488 configuration. See @ref{@LaTeX{} specific export settings}.}. 12489 12490 @item @samp{SELECT_TAGS} 12491 @cindex @samp{SELECT_TAGS}, keyword 12492 @vindex org-export-select-tags 12493 The default value is @samp{("export")}. When a tree is tagged with 12494 @samp{export} (@code{org-export-select-tags}), Org selects that tree and its 12495 subtrees for export. Org excludes trees with @samp{noexport} tags, see 12496 below. When selectively exporting files with @samp{export} tags set, Org 12497 does not export any text that appears before the first headline. 12498 12499 @item @samp{EXCLUDE_TAGS} 12500 @cindex @samp{EXCLUDE_TAGS}, keyword 12501 @vindex org-export-exclude-tags 12502 The default value is @samp{("noexport")}. When a tree is tagged with 12503 @samp{noexport} (@code{org-export-exclude-tags}), Org excludes that tree and 12504 its subtrees from export. Entries tagged with @samp{noexport} are 12505 unconditionally excluded from the export, even if they have an 12506 @samp{export} tag. Even if a subtree is not exported, Org executes any 12507 code blocks contained there. 12508 12509 @item @samp{TITLE} 12510 @cindex @samp{TITLE}, keyword 12511 @cindex document title 12512 Org displays this title. For long titles, use multiple @samp{#+TITLE} 12513 lines. 12514 12515 @item @samp{EXPORT_FILE_NAME} 12516 @cindex @samp{EXPORT_FILE_NAME}, keyword 12517 The name of the output file to be generated. Otherwise, Org 12518 generates the file name based on the buffer name and the extension 12519 based on the back-end format. 12520 @end table 12521 12522 The @samp{OPTIONS} keyword is a compact form. To configure multiple 12523 options, use several @samp{OPTIONS} lines. @samp{OPTIONS} recognizes the 12524 following arguments. 12525 12526 @table @asis 12527 @item @code{'} 12528 @vindex org-export-with-smart-quotes 12529 Toggle smart quotes (@code{org-export-with-smart-quotes}). Depending on 12530 the language used, when activated, Org treats pairs of double quotes 12531 as primary quotes, pairs of single quotes as secondary quotes, and 12532 single quote marks as apostrophes. 12533 12534 @item @code{*} 12535 @vindex org-export-with-emphasize 12536 Toggle emphasized text (@code{org-export-with-emphasize}). 12537 12538 @item @code{-} 12539 @vindex org-export-with-special-strings 12540 Toggle conversion of special strings 12541 (@code{org-export-with-special-strings}). 12542 12543 @item @code{:} 12544 @vindex org-export-with-fixed-width 12545 Toggle fixed-width sections (@code{org-export-with-fixed-width}). 12546 12547 @item @code{<} 12548 @vindex org-export-with-timestamps 12549 Toggle inclusion of time/date active/inactive stamps 12550 (@code{org-export-with-timestamps}). 12551 12552 @item @code{\n} 12553 @vindex org-export-preserve-breaks 12554 Toggles whether to preserve line breaks 12555 (@code{org-export-preserve-breaks}). 12556 12557 @item @code{^} 12558 @vindex org-export-with-sub-superscripts 12559 Toggle @TeX{}-like syntax for sub- and superscripts. If you write 12560 @samp{^:@{@}}, @samp{a_@{b@}} is interpreted, but the simple @samp{a_b} is left as it 12561 is (@code{org-export-with-sub-superscripts}). 12562 12563 @item @code{arch} 12564 @vindex org-export-with-archived-trees 12565 Configure how archived trees are exported. When set to @code{headline}, 12566 the export process skips the contents and processes only the 12567 headlines (@code{org-export-with-archived-trees}). 12568 12569 @item @code{author} 12570 @vindex org-export-with-author 12571 Toggle inclusion of author name into exported file 12572 (@code{org-export-with-author}). 12573 12574 @item @code{broken-links} 12575 @vindex org-export-with-broken-links 12576 Toggles if Org should continue exporting upon finding a broken 12577 internal link. When set to @code{mark}, Org clearly marks the problem 12578 link in the output (@code{org-export-with-broken-links}). 12579 12580 @item @code{c} 12581 @vindex org-export-with-clocks 12582 Toggle inclusion of @samp{CLOCK} keywords (@code{org-export-with-clocks}). 12583 12584 @item @code{creator} 12585 @vindex org-export-with-creator 12586 Toggle inclusion of creator information in the exported file 12587 (@code{org-export-with-creator}). 12588 12589 @item @code{d} 12590 @vindex org-export-with-drawers 12591 Toggles inclusion of drawers, or list of drawers to include, or list 12592 of drawers to exclude (@code{org-export-with-drawers}). 12593 12594 @item @code{date} 12595 @vindex org-export-with-date 12596 Toggle inclusion of a date into exported file 12597 (@code{org-export-with-date}). 12598 12599 @item @code{e} 12600 @vindex org-export-with-entities 12601 Toggle inclusion of entities (@code{org-export-with-entities}). 12602 12603 @item @code{email} 12604 @vindex org-export-with-email 12605 Toggle inclusion of the author's e-mail into exported file 12606 (@code{org-export-with-email}). 12607 12608 @item @code{f} 12609 @vindex org-export-with-footnotes 12610 Toggle the inclusion of footnotes (@code{org-export-with-footnotes}). 12611 12612 @item @code{H} 12613 @vindex org-export-headline-levels 12614 Set the number of headline levels for export 12615 (@code{org-export-headline-levels}). Below that level, headlines are 12616 treated differently. In most back-ends, they become list items. 12617 12618 @item @code{inline} 12619 @vindex org-export-with-inlinetasks 12620 Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}). 12621 12622 @item @code{num} 12623 @vindex org-export-with-section-numbers 12624 @cindex @samp{UNNUMBERED}, property 12625 Toggle section-numbers (@code{org-export-with-section-numbers}). When 12626 set to number N, Org numbers only those headlines at level N or 12627 above. Set @samp{UNNUMBERED} property to non-@code{nil} to disable numbering 12628 of heading and subheadings entirely. Moreover, when the value is 12629 @samp{notoc} the headline, and all its children, do not appear in the 12630 table of contents either (see @ref{Table of Contents}). 12631 12632 @item @code{p} 12633 @vindex org-export-with-planning 12634 Toggle export of planning information (@code{org-export-with-planning}). 12635 ``Planning information'' comes from lines located right after the 12636 headline and contain any combination of these cookies: @samp{SCHEDULED}, 12637 @samp{DEADLINE}, or @samp{CLOSED}. 12638 12639 @item @code{pri} 12640 @vindex org-export-with-priority 12641 Toggle inclusion of priority cookies 12642 (@code{org-export-with-priority}). 12643 12644 @item @code{prop} 12645 @vindex org-export-with-properties 12646 Toggle inclusion of property drawers, or list the properties to 12647 include (@code{org-export-with-properties}). 12648 12649 @item @code{stat} 12650 @vindex org-export-with-statistics-cookies 12651 Toggle inclusion of statistics cookies 12652 (@code{org-export-with-statistics-cookies}). 12653 12654 @item @code{tags} 12655 @vindex org-export-with-tags 12656 Toggle inclusion of tags, may also be @code{not-in-toc} 12657 (@code{org-export-with-tags}). 12658 12659 @item @code{tasks} 12660 @vindex org-export-with-tasks 12661 Toggle inclusion of tasks (TODO items); or @code{nil} to remove all 12662 tasks; or @code{todo} to remove done tasks; or list the keywords to keep 12663 (@code{org-export-with-tasks}). 12664 12665 @item @code{tex} 12666 @vindex org-export-with-latex 12667 @code{nil} does not export; @code{t} exports; @code{verbatim} keeps everything in 12668 verbatim (@code{org-export-with-latex}). 12669 12670 @item @code{timestamp} 12671 @vindex org-export-time-stamp-file 12672 Toggle inclusion of the creation time in the exported file 12673 (@code{org-export-time-stamp-file}). 12674 12675 @item @code{title} 12676 @vindex org-export-with-title 12677 Toggle inclusion of title (@code{org-export-with-title}). 12678 12679 @item @code{toc} 12680 @vindex org-export-with-toc 12681 Toggle inclusion of the table of contents, or set the level limit 12682 (@code{org-export-with-toc}). 12683 12684 @item @code{todo} 12685 @vindex org-export-with-todo-keywords 12686 Toggle inclusion of TODO keywords into exported text 12687 (@code{org-export-with-todo-keywords}). 12688 12689 @item @code{|} 12690 @vindex org-export-with-tables 12691 Toggle inclusion of tables (@code{org-export-with-tables}). 12692 @end table 12693 12694 When exporting subtrees, special node properties can override the 12695 above keywords. These properties have an @samp{EXPORT_} prefix. For 12696 example, @samp{DATE} becomes, @samp{EXPORT_DATE} when used for a specific 12697 subtree. Except for @samp{SETUPFILE}, all other keywords listed above 12698 have an @samp{EXPORT_} equivalent. 12699 12700 @cindex @samp{BIND}, keyword 12701 @vindex org-export-allow-bind-keywords 12702 If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables can 12703 become buffer-local during export by using the @samp{BIND} keyword. Its 12704 syntax is @samp{#+BIND: variable value}. This is particularly useful for 12705 in-buffer settings that cannot be changed using keywords. 12706 12707 @node Table of Contents 12708 @section Table of Contents 12709 12710 @cindex table of contents 12711 @cindex list of tables 12712 @cindex list of listings 12713 12714 @cindex @samp{toc}, in @samp{OPTIONS} keyword 12715 @vindex org-export-with-toc 12716 The table of contents includes all headlines in the document. Its 12717 depth is therefore the same as the headline levels in the file. If 12718 you need to use a different depth, or turn it off entirely, set the 12719 @code{org-export-with-toc} variable accordingly. You can achieve the same 12720 on a per file basis, using the following @samp{toc} item in @samp{OPTIONS} 12721 keyword: 12722 12723 @example 12724 #+OPTIONS: toc:2 (only include two levels in TOC) 12725 #+OPTIONS: toc:nil (no default TOC at all) 12726 @end example 12727 12728 @cindex excluding entries from table of contents 12729 @cindex table of contents, exclude entries 12730 Org includes both numbered and unnumbered headlines in the table of 12731 contents@footnote{At the moment, some export back-ends do not obey this 12732 specification. For example, @LaTeX{} export excludes every unnumbered 12733 headline from the table of contents.}. If you need to exclude an unnumbered headline, 12734 along with all its children, set the @samp{UNNUMBERED} property to @samp{notoc} 12735 value. 12736 12737 @example 12738 * Subtree not numbered, not in table of contents either 12739 :PROPERTIES: 12740 :UNNUMBERED: notoc 12741 :END: 12742 @end example 12743 12744 @cindex @samp{TOC}, keyword 12745 Org normally inserts the table of contents directly before the first 12746 headline of the file. To move the table of contents to a different 12747 location, first turn off the default with @code{org-export-with-toc} 12748 variable or with @samp{#+OPTIONS: toc:nil}. Then insert @samp{#+TOC: headlines 12749 N} at the desired location(s). 12750 12751 @example 12752 #+OPTIONS: toc:nil 12753 ... 12754 #+TOC: headlines 2 12755 @end example 12756 12757 To adjust the table of contents depth for a specific section of the 12758 Org document, append an additional @samp{local} parameter. This parameter 12759 becomes a relative depth for the current level. The following example 12760 inserts a local table of contents, with direct children only. 12761 12762 @example 12763 * Section 12764 #+TOC: headlines 1 local 12765 @end example 12766 12767 Note that for this feature to work properly in @LaTeX{} export, the Org 12768 file requires the inclusion of the titletoc package. Because of 12769 compatibility issues, titletoc has to be loaded @emph{before} hyperref. 12770 Customize the @code{org-latex-default-packages-alist} variable. 12771 12772 The following example inserts a table of contents that links to the 12773 children of the specified target. 12774 12775 @example 12776 * Target 12777 :PROPERTIES: 12778 :CUSTOM_ID: TargetSection 12779 :END: 12780 ** Heading A 12781 ** Heading B 12782 * Another section 12783 #+TOC: headlines 1 :target #TargetSection 12784 @end example 12785 12786 The @samp{:target} attribute is supported in HTML, Markdown, ODT, and ASCII export. 12787 12788 Use the @samp{TOC} keyword to generate list of tables---respectively, all 12789 listings---with captions. 12790 12791 @example 12792 #+TOC: listings 12793 #+TOC: tables 12794 @end example 12795 12796 @cindex @samp{ALT_TITLE}, property 12797 Normally Org uses the headline for its entry in the table of contents. 12798 But with @samp{ALT_TITLE} property, a different entry can be specified for 12799 the table of contents. 12800 12801 @node Include Files 12802 @section Include Files 12803 12804 @cindex include files, during export 12805 @cindex export, include files 12806 @cindex @samp{INCLUDE}, keyword 12807 12808 During export, you can include the content of another file. For 12809 example, to include your @samp{.emacs} file, you could use: 12810 12811 @example 12812 #+INCLUDE: "~/.emacs" src emacs-lisp 12813 @end example 12814 12815 12816 @noindent 12817 The first parameter is the file name to include. The optional second 12818 parameter specifies the block type: @samp{example}, @samp{export} or @samp{src}. The 12819 optional third parameter specifies the source code language to use for 12820 formatting the contents. This is relevant to both @samp{export} and @samp{src} 12821 block types. 12822 12823 If an included file is specified as having a markup language, Org 12824 neither checks for valid syntax nor changes the contents in any way. 12825 For example and source blocks, Org code-escapes the contents before 12826 inclusion. 12827 12828 @cindex @samp{minlevel}, include 12829 If an included file is not specified as having any markup language, 12830 Org assumes it be in Org format and proceeds as usual with a few 12831 exceptions. Org makes the footnote labels (see @ref{Creating Footnotes}) 12832 in the included file local to that file. The contents of the included 12833 file belong to the same structure---headline, item---containing the 12834 @samp{INCLUDE} keyword. In particular, headlines within the file become 12835 children of the current section. That behavior can be changed by 12836 providing an additional keyword parameter, @samp{:minlevel}. It shifts the 12837 headlines in the included file to become the lowest level. For 12838 example, this syntax makes the included file a sibling of the current 12839 top-level headline: 12840 12841 @example 12842 #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1 12843 @end example 12844 12845 12846 @cindex @samp{lines}, include 12847 Inclusion of only portions of files are specified using ranges 12848 parameter with @samp{:lines} keyword. The line at the upper end of the 12849 range will not be included. The start and/or the end of the range may 12850 be omitted to use the obvious defaults. 12851 12852 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 12853 @item @samp{#+INCLUDE: "~/.emacs" :lines "5-10"} 12854 @tab Include lines 5 to 10, 10 excluded 12855 @item @samp{#+INCLUDE: "~/.emacs" :lines "-10"} 12856 @tab Include lines 1 to 10, 10 excluded 12857 @item @samp{#+INCLUDE: "~/.emacs" :lines "10-"} 12858 @tab Include lines from 10 to EOF 12859 @end multitable 12860 12861 Inclusions may specify a file-link to extract an object matched by 12862 @code{org-link-search}@footnote{Note that @code{org-link-search-must-match-exact-headline} is 12863 locally bound to non-@code{nil}. Therefore, @code{org-link-search} only matches 12864 headlines and named elements.} (see @ref{Search Options}). The 12865 ranges for @samp{:lines} keyword are relative to the requested element. 12866 Therefore, 12867 12868 @example 12869 #+INCLUDE: "./paper.org::*conclusion" :lines 1-20 12870 @end example 12871 12872 12873 @noindent 12874 includes the first 20 lines of the headline named @samp{conclusion}. 12875 12876 @cindex @samp{only-contents}, include 12877 To extract only the contents of the matched object, set 12878 @samp{:only-contents} property to non-@code{nil}. This omits any planning lines 12879 or property drawers. For example, to include the body of the heading 12880 with the custom ID @samp{theory}, you can use 12881 12882 @example 12883 #+INCLUDE: "./paper.org::#theory" :only-contents t 12884 @end example 12885 12886 12887 The following command allows navigating to the included document: 12888 12889 @table @asis 12890 @item @kbd{C-c '} (@code{org-edit~special}) 12891 @kindex C-c ' 12892 @findex org-edit-special 12893 12894 Visit the included file at point. 12895 @end table 12896 12897 @node Macro Replacement 12898 @section Macro Replacement 12899 12900 @cindex macro replacement, during export 12901 @cindex @samp{MACRO}, keyword 12902 12903 @vindex org-export-global-macros 12904 Macros replace text snippets during export. Macros are defined 12905 globally in @code{org-export-global-macros}, or document-wise with the 12906 following syntax: 12907 12908 @example 12909 #+MACRO: name replacement text; $1, $2 are arguments 12910 @end example 12911 12912 12913 @noindent 12914 which can be referenced using @samp{@{@{@{name(arg1, arg2)@}@}@}}@footnote{Since commas separate the arguments, commas within arguments 12915 have to be escaped with the backslash character. So only those 12916 backslash characters before a comma need escaping with another 12917 backslash character.}. For 12918 example 12919 12920 @example 12921 #+MACRO: poem Rose is $1, violet's $2. Life's ordered: Org assists you. 12922 @{@{@{poem(red,blue)@}@}@} 12923 @end example 12924 12925 @noindent 12926 becomes 12927 12928 @example 12929 Rose is red, violet's blue. Life's ordered: Org assists you. 12930 @end example 12931 12932 12933 As a special case, Org parses any replacement text starting with 12934 @samp{(eval} as an Emacs Lisp expression and evaluates it accordingly. 12935 Within such templates, arguments become strings. Thus, the following 12936 macro 12937 12938 @example 12939 #+MACRO: gnustamp (eval (concat "GNU/" (capitalize $1))) 12940 @end example 12941 12942 12943 @noindent 12944 turns @samp{@{@{@{gnustamp(linux)@}@}@}} into @samp{GNU/Linux} during export. 12945 12946 Org recognizes macro references in following Org markup areas: 12947 paragraphs, headlines, verse blocks, tables cells and lists. Org also 12948 recognizes macro references in keywords, such as @samp{CAPTION}, @samp{TITLE}, 12949 @samp{AUTHOR}, @samp{DATE}, and for some back-end specific export options. 12950 12951 Org comes with following pre-defined macros: 12952 12953 @table @asis 12954 @item @samp{@{@{@{keyword(NAME)@}@}@}} 12955 @itemx @samp{@{@{@{title@}@}@}} 12956 @itemx @samp{@{@{@{author@}@}@}} 12957 @itemx @samp{@{@{@{email@}@}@}} 12958 @cindex @samp{keyword}, macro 12959 @cindex @samp{title}, macro 12960 @cindex @samp{author}, macro 12961 @cindex @samp{email}, macro 12962 The @samp{keyword} macro collects all values from @var{NAME} 12963 keywords throughout the buffer, separated with white space. 12964 @samp{title}, @samp{author} and @samp{email} macros are shortcuts for, 12965 respectively, @samp{@{@{@{keyword(TITLE)@}@}@}}, @samp{@{@{@{keyword(AUTHOR)@}@}@}} and 12966 @samp{@{@{@{keyword(EMAIL)@}@}@}}. 12967 12968 @item @samp{@{@{@{date@}@}@}} 12969 @itemx @samp{@{@{@{date(FORMAT)@}@}@}} 12970 @cindex @samp{date}, macro 12971 This macro refers to the @samp{DATE} keyword. @var{FORMAT} is an 12972 optional argument to the @samp{date} macro that is used only if @samp{DATE} is 12973 a single timestamp. @var{FORMAT} should be a format string 12974 understood by @code{format-time-string}. 12975 12976 @item @samp{@{@{@{time(FORMAT)@}@}@}} 12977 @itemx @samp{@{@{@{modification-time(FORMAT, VC)@}@}@}} 12978 @cindex @samp{time}, macro 12979 @cindex @samp{modification-time}, macro 12980 These macros refer to the document's date and time of export and 12981 date and time of modification. @var{FORMAT} is a string 12982 understood by @code{format-time-string}. If the second argument to the 12983 @code{modification-time} macro is non-@code{nil}, Org uses @samp{vc.el} to retrieve 12984 the document's modification time from the version control system. 12985 Otherwise Org reads the file attributes. 12986 12987 @item @samp{@{@{@{input-file@}@}@}} 12988 @cindex @samp{input-file}, macro 12989 This macro refers to the filename of the exported file. 12990 12991 @item @samp{@{@{@{property(PROPERTY-NAME)@}@}@}} 12992 @itemx @samp{@{@{@{property(PROPERTY-NAME, SEARCH OPTION)@}@}@}} 12993 @cindex @samp{property}, macro 12994 This macro returns the value of property @var{PROPERTY-NAME} in 12995 the current entry. If @var{SEARCH-OPTION} (see @ref{Search Options}) refers to a remote entry, use it instead. 12996 12997 @item @samp{@{@{@{n@}@}@}} 12998 @itemx @samp{@{@{@{n(NAME)@}@}@}} 12999 @itemx @samp{@{@{@{n(NAME, ACTION)@}@}@}} 13000 @cindex @samp{n}, macro 13001 @cindex counter, macro 13002 This macro implements custom counters by returning the number of 13003 times the macro has been expanded so far while exporting the buffer. 13004 You can create more than one counter using different @var{NAME} 13005 values. If @var{ACTION} is @samp{-}, previous value of the counter 13006 is held, i.e., the specified counter is not incremented. If the 13007 value is a number, the specified counter is set to that value. If 13008 it is any other non-empty string, the specified counter is reset 13009 to 1. You may leave @var{NAME} empty to reset the default 13010 counter. 13011 @end table 13012 13013 @cindex @samp{results}, macro 13014 Moreover, inline source blocks (see @ref{Structure of Code Blocks}) use the 13015 special @samp{results} macro to mark their output. As such, you are 13016 advised against re-defining it, unless you know what you are doing. 13017 13018 @vindex org-hide-macro-markers 13019 The surrounding brackets can be made invisible by setting 13020 @code{org-hide-macro-markers} to a non-@code{nil} value. 13021 13022 Org expands macros at the very beginning of the export process. 13023 13024 @node Comment Lines 13025 @section Comment Lines 13026 13027 @cindex exporting, not 13028 13029 @cindex comment lines 13030 Lines starting with zero or more whitespace characters followed by one 13031 @samp{#} and a whitespace are treated as comments and, as such, are not 13032 exported. 13033 13034 @cindex @samp{BEGIN_COMMENT} 13035 @cindex comment block 13036 Likewise, regions surrounded by @samp{#+BEGIN_COMMENT} @dots{} @samp{#+END_COMMENT} 13037 are not exported. 13038 13039 @cindex comment trees 13040 Finally, a @samp{COMMENT} keyword at the beginning of an entry, but after 13041 any other keyword or priority cookie, comments out the entire subtree. 13042 In this case, the subtree is not exported and no code block within it 13043 is executed either@footnote{ For a less drastic behavior, consider using a 13044 select tag (see @ref{Export Settings}) instead.}. The command below 13045 helps changing the comment status of a headline. 13046 13047 @table @asis 13048 @item @kbd{C-c ;} (@code{org-toggle-comment}) 13049 @kindex C-c ; 13050 @findex org-toggle-comment 13051 13052 Toggle the @samp{COMMENT} keyword at the beginning of an entry. 13053 @end table 13054 13055 @node ASCII/Latin-1/UTF-8 export 13056 @section ASCII/Latin-1/UTF-8 export 13057 13058 @cindex ASCII export 13059 @cindex Latin-1 export 13060 @cindex UTF-8 export 13061 13062 ASCII export produces an output file containing only plain ASCII 13063 characters. This is the simplest and most direct text output. It 13064 does not contain any Org markup. Latin-1 and UTF-8 export use 13065 additional characters and symbols available in these encoding 13066 standards. All three of these export formats offer the most basic of 13067 text output for maximum portability. 13068 13069 @vindex org-ascii-text-width 13070 On export, Org fills and justifies text according to the text width 13071 set in @code{org-ascii-text-width}. 13072 13073 @vindex org-ascii-links-to-notes 13074 Org exports links using a footnote-like style where the descriptive 13075 part is in the text and the link is in a note before the next heading. 13076 See the variable @code{org-ascii-links-to-notes} for details. 13077 13078 @anchor{ASCII export commands} 13079 @subheading ASCII export commands 13080 13081 @table @asis 13082 @item @kbd{C-c C-e t a} (@code{org-ascii-export-to-ascii}) 13083 @itemx @kbd{C-c C-e t l} 13084 @itemx @kbd{C-c C-e t u} 13085 @kindex C-c C-e t a 13086 @kindex C-c C-e t l 13087 @kindex C-c C-e t u 13088 @findex org-ascii-export-to-ascii 13089 13090 Export as an ASCII file with a @samp{.txt} extension. For @samp{myfile.org}, 13091 Org exports to @samp{myfile.txt}, overwriting without warning. For 13092 @samp{myfile.txt}, Org exports to @samp{myfile.txt.txt} in order to prevent 13093 data loss. 13094 13095 @item @kbd{C-c C-e t A} (@code{org-ascii-export-to-ascii}) 13096 @itemx @kbd{C-c C-e t L} 13097 @itemx @kbd{C-c C-e t U} 13098 @kindex C-c C-e t A 13099 @kindex C-c C-e t L 13100 @kindex C-c C-e t U 13101 @findex org-ascii-export-as-ascii 13102 13103 Export to a temporary buffer. Does not create a file. 13104 @end table 13105 13106 @anchor{ASCII specific export settings} 13107 @subheading ASCII specific export settings 13108 13109 The ASCII export back-end has one extra keyword for customizing ASCII 13110 output. Setting this keyword works similar to the general options 13111 (see @ref{Export Settings}). 13112 13113 @table @asis 13114 @item @samp{SUBTITLE} 13115 @cindex @samp{SUBTITLE}, keyword 13116 The document subtitle. For long subtitles, use multiple 13117 @samp{#+SUBTITLE} lines in the Org file. Org prints them on one 13118 continuous line, wrapping into multiple lines if necessary. 13119 @end table 13120 13121 @anchor{Header and sectioning structure} 13122 @subheading Header and sectioning structure 13123 13124 Org converts the first three outline levels into headlines for ASCII 13125 export. The remaining levels are turned into lists. To change this 13126 cut-off point where levels become lists, see @ref{Export Settings}. 13127 13128 @anchor{Quoting ASCII text} 13129 @subheading Quoting ASCII text 13130 13131 To insert text within the Org file by the ASCII back-end, use one the 13132 following constructs, inline, keyword, or export block: 13133 13134 @cindex @samp{ASCII}, keyword 13135 @cindex @samp{BEGIN_EXPORT ascii} 13136 @example 13137 Inline text @@@@ascii:and additional text@@@@ within a paragraph. 13138 13139 #+ASCII: Some text 13140 13141 #+BEGIN_EXPORT ascii 13142 Org exports text in this block only when using ASCII back-end. 13143 #+END_EXPORT 13144 @end example 13145 13146 @anchor{ASCII specific attributes} 13147 @subheading ASCII specific attributes 13148 13149 @cindex @samp{ATTR_ASCII}, keyword 13150 @cindex horizontal rules, in ASCII export 13151 13152 ASCII back-end recognizes only one attribute, @samp{:width}, which 13153 specifies the width of a horizontal rule in number of characters. The 13154 keyword and syntax for specifying widths is: 13155 13156 @example 13157 #+ATTR_ASCII: :width 10 13158 ----- 13159 @end example 13160 13161 @anchor{ASCII special blocks} 13162 @subheading ASCII special blocks 13163 13164 @cindex special blocks, in ASCII export 13165 @cindex @samp{BEGIN_JUSTIFYLEFT} 13166 @cindex @samp{BEGIN_JUSTIFYRIGHT} 13167 13168 Besides @samp{#+BEGIN_CENTER} blocks (see @ref{Paragraphs}), ASCII back-end has 13169 these two left and right justification blocks: 13170 13171 @example 13172 #+BEGIN_JUSTIFYLEFT 13173 It's just a jump to the left... 13174 #+END_JUSTIFYLEFT 13175 13176 #+BEGIN_JUSTIFYRIGHT 13177 ...and then a step to the right. 13178 #+END_JUSTIFYRIGHT 13179 @end example 13180 13181 @node Beamer Export 13182 @section Beamer Export 13183 13184 @cindex Beamer export 13185 13186 Org uses Beamer export to convert an Org file tree structure into 13187 high-quality interactive slides for presentations. Beamer is a @LaTeX{} 13188 document class for creating presentations in PDF, HTML, and other 13189 popular display formats. 13190 13191 @menu 13192 * Beamer export commands:: For creating Beamer documents. 13193 * Beamer specific export settings:: For customizing Beamer export. 13194 * Frames and Blocks in Beamer:: For composing Beamer slides. 13195 * Beamer specific syntax:: For using in Org documents. 13196 * Editing support:: Editing support. 13197 * A Beamer example:: A complete presentation. 13198 @end menu 13199 13200 @node Beamer export commands 13201 @subsection Beamer export commands 13202 13203 @table @asis 13204 @item @kbd{C-c C-e l b} (@code{org-beamer-export-to-latex}) 13205 @kindex C-c C-e l b 13206 @findex org-beamer-export-to-latex 13207 13208 Export as @LaTeX{} file with a @samp{.tex} extension. For @samp{myfile.org}, Org 13209 exports to @samp{myfile.tex}, overwriting without warning. 13210 13211 @item @kbd{C-c C-e l B} (@code{org-beamer-export-as-latex}) 13212 @kindex C-c C-e l B 13213 @findex org-beamer-export-as-latex 13214 13215 Export to a temporary buffer. Does not create a file. 13216 13217 @item @kbd{C-c C-e l P} (@code{org-beamer-export-to-pdf}) 13218 @kindex C-c C-e l P 13219 @findex org-beamer-export-to-pdf 13220 13221 Export as @LaTeX{} file and then convert it to PDF format. 13222 13223 @item @kbd{C-c C-e l O} 13224 @kindex C-c C-e l O 13225 13226 Export as @LaTeX{} file, convert it to PDF format, and then open the 13227 PDF file. 13228 @end table 13229 13230 @node Beamer specific export settings 13231 @subsection Beamer specific export settings 13232 13233 Beamer export back-end has several additional keywords for customizing 13234 Beamer output. These keywords work similar to the general options 13235 settings (see @ref{Export Settings}). 13236 13237 @table @asis 13238 @item @samp{BEAMER_THEME} 13239 @cindex @samp{BEAMER_THEME}, keyword 13240 @vindex org-beamer-theme 13241 The Beamer layout theme (@code{org-beamer-theme}). Use square brackets 13242 for options. For example: 13243 13244 @example 13245 #+BEAMER_THEME: Rochester [height=20pt] 13246 @end example 13247 13248 @item @samp{BEAMER_FONT_THEME} 13249 @cindex @samp{BEAMER_FONT_THEME}, keyword 13250 The Beamer font theme. 13251 13252 @item @samp{BEAMER_INNER_THEME} 13253 @cindex @samp{BEAMER_INNER_THEME}, keyword 13254 The Beamer inner theme. 13255 13256 @item @samp{BEAMER_OUTER_THEME} 13257 @cindex @samp{BEAMER_OUTER_THEME}, keyword 13258 The Beamer outer theme. 13259 13260 @item @samp{BEAMER_HEADER} 13261 @cindex @samp{BEAMER_HEADER}, keyword 13262 Arbitrary lines inserted in the preamble, just before the @samp{hyperref} 13263 settings. 13264 13265 @item @samp{DESCRIPTION} 13266 @cindex @samp{DESCRIPTION}, keyword 13267 The document description. For long descriptions, use multiple 13268 @samp{DESCRIPTION} keywords. By default, @samp{hyperref} inserts 13269 @samp{DESCRIPTION} as metadata. Use @code{org-latex-hyperref-template} to 13270 configure document metadata. Use @code{org-latex-title-command} to 13271 configure typesetting of description as part of front matter. 13272 13273 @item @samp{KEYWORDS} 13274 @cindex @samp{KEYWORDS}, keyword 13275 The keywords for defining the contents of the document. Use 13276 multiple @samp{KEYWORDS} lines if necessary. By default, @samp{hyperref} 13277 inserts @samp{KEYWORDS} as metadata. Use @code{org-latex-hyperref-template} 13278 to configure document metadata. Use @code{org-latex-title-command} to 13279 configure typesetting of keywords as part of front matter. 13280 13281 @item @samp{SUBTITLE} 13282 @cindex @samp{SUBTITLE}, keyword 13283 Document's subtitle. For typesetting, use 13284 @code{org-beamer-subtitle-format} string. Use 13285 @code{org-latex-hyperref-template} to configure document metadata. Use 13286 @code{org-latex-title-command} to configure typesetting of subtitle as 13287 part of front matter. 13288 @end table 13289 13290 @node Frames and Blocks in Beamer 13291 @subsection Frames and Blocks in Beamer 13292 13293 Org transforms heading levels into Beamer's sectioning elements, 13294 frames and blocks. Any Org tree with a not-too-deep-level nesting 13295 should in principle be exportable as a Beamer presentation. 13296 13297 @itemize 13298 @item 13299 @vindex org-beamer-frame-level 13300 Org headlines become Beamer frames when the heading level in Org is 13301 equal to @code{org-beamer-frame-level} or @samp{H} value in a @samp{OPTIONS} line 13302 (see @ref{Export Settings}). 13303 13304 @cindex @samp{BEAMER_ENV}, property 13305 Org overrides headlines to frames conversion for the current tree of 13306 an Org file if it encounters the @samp{BEAMER_ENV} property set to 13307 @samp{frame} or @samp{fullframe}. Org ignores whatever 13308 @code{org-beamer-frame-level} happens to be for that headline level in 13309 the Org tree. In Beamer terminology, a full frame is a frame 13310 without its title. 13311 13312 @item 13313 Org exports a Beamer frame's objects as block environments. Org can 13314 enforce wrapping in special block types when @samp{BEAMER_ENV} property 13315 is set@footnote{If @samp{BEAMER_ENV} is set, Org export adds @samp{B_environment} tag 13316 to make it visible. The tag serves as a visual aid and has no 13317 semantic relevance.}. For valid values see 13318 @code{org-beamer-environments-default}. To add more values, see 13319 @code{org-beamer-environments-extra}. 13320 @vindex org-beamer-environments-default 13321 @vindex org-beamer-environments-extra 13322 13323 @item 13324 @cindex @samp{BEAMER_REF}, property 13325 If @samp{BEAMER_ENV} is set to @samp{appendix}, Org exports the entry as an 13326 appendix. When set to @samp{note}, Org exports the entry as a note 13327 within the frame or between frames, depending on the entry's heading 13328 level. When set to @samp{noteNH}, Org exports the entry as a note 13329 without its title. When set to @samp{againframe}, Org exports the entry 13330 with @samp{\againframe} command, which makes setting the @samp{BEAMER_REF} 13331 property mandatory because @samp{\againframe} needs frame to resume. 13332 13333 When @samp{ignoreheading} is set, Org export ignores the entry's headline 13334 but not its content. This is useful for inserting content between 13335 frames. It is also useful for properly closing a @samp{column} 13336 environment. 13337 13338 @cindex @samp{BEAMER_ACT}, property 13339 @cindex @samp{BEAMER_OPT}, property 13340 When @samp{BEAMER_ACT} is set for a headline, Org export translates that 13341 headline as an overlay or action specification. When enclosed in 13342 square brackets, Org export makes the overlay specification 13343 a default. Use @samp{BEAMER_OPT} to set any options applicable to the 13344 current Beamer frame or block. The Beamer export back-end wraps 13345 with appropriate angular or square brackets. It also adds the 13346 @samp{fragile} option for any code that may require a verbatim block. 13347 13348 @cindex @samp{BEAMER_COL}, property 13349 To create a column on the Beamer slide, use the @samp{BEAMER_COL} 13350 property for its headline in the Org file. Set the value of 13351 @samp{BEAMER_COL} to a decimal number representing the fraction of the 13352 total text width. Beamer export uses this value to set the column's 13353 width and fills the column with the contents of the Org entry. If 13354 the Org entry has no specific environment defined, Beamer export 13355 ignores the heading. If the Org entry has a defined environment, 13356 Beamer export uses the heading as title. Behind the scenes, Beamer 13357 export automatically handles @LaTeX{} column separations for contiguous 13358 headlines. To manually adjust them for any unique configurations 13359 needs, use the @samp{BEAMER_ENV} property. 13360 @end itemize 13361 13362 @node Beamer specific syntax 13363 @subsection Beamer specific syntax 13364 13365 Since Org's Beamer export back-end is an extension of the @LaTeX{} 13366 back-end, it recognizes other @LaTeX{} specific syntax---for example, 13367 @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}. See @ref{@LaTeX{} Export}, for details. 13368 13369 Beamer export wraps the table of contents generated with @samp{toc:t} 13370 @samp{OPTION} keyword in a @samp{frame} environment. Beamer export does not 13371 wrap the table of contents generated with @samp{TOC} keyword (see @ref{Table of Contents}). Use square brackets for specifying options. 13372 13373 @example 13374 #+TOC: headlines [currentsection] 13375 @end example 13376 13377 13378 Insert Beamer-specific code using the following constructs: 13379 13380 @cindex @samp{BEAMER}, keyword 13381 @cindex @samp{BEGIN_EXPORT beamer} 13382 @example 13383 #+BEAMER: \pause 13384 13385 #+BEGIN_EXPORT beamer 13386 Only Beamer export back-end exports this. 13387 #+END_EXPORT 13388 13389 Text @@@@beamer:some code@@@@ within a paragraph. 13390 @end example 13391 13392 Inline constructs, such as the last one above, are useful for adding 13393 overlay specifications to objects with @code{bold}, @code{item}, @code{link}, 13394 @code{radio-target} and @code{target} types. Enclose the value in angular 13395 brackets and place the specification at the beginning of the object as 13396 shown in this example: 13397 13398 @example 13399 A *@@@@beamer:<2->@@@@useful* feature 13400 @end example 13401 13402 13403 @cindex @samp{ATTR_BEAMER}, keyword 13404 Beamer export recognizes the @samp{ATTR_BEAMER} keyword with the following 13405 attributes from Beamer configurations: @samp{:environment} for changing 13406 local Beamer environment, @samp{:overlay} for specifying Beamer overlays in 13407 angular or square brackets, and @samp{:options} for inserting optional 13408 arguments. 13409 13410 @example 13411 #+ATTR_BEAMER: :environment nonindentlist 13412 - item 1, not indented 13413 - item 2, not indented 13414 - item 3, not indented 13415 @end example 13416 13417 @example 13418 #+ATTR_BEAMER: :overlay <+-> 13419 - item 1 13420 - item 2 13421 @end example 13422 13423 @example 13424 #+ATTR_BEAMER: :options [Lagrange] 13425 Let $G$ be a finite group, and let $H$ be 13426 a subgroup of $G$. Then the order of $H$ divides the order of $G$. 13427 @end example 13428 13429 @node Editing support 13430 @subsection Editing support 13431 13432 Org Beamer mode is a special minor mode for faster editing of Beamer 13433 documents. 13434 13435 @example 13436 #+STARTUP: beamer 13437 @end example 13438 13439 13440 @table @asis 13441 @item @kbd{C-c C-b} (@code{org-beamer-select-environment}) 13442 @kindex C-c C-b 13443 @findex org-beamer-select-environment 13444 13445 Org Beamer mode provides this key for quicker selections in Beamer 13446 normal environments, and for selecting the @samp{BEAMER_COL} property. 13447 @end table 13448 13449 @node A Beamer example 13450 @subsection A Beamer example 13451 13452 Here is an example of an Org document ready for Beamer export. 13453 13454 @example 13455 #+TITLE: Example Presentation 13456 #+AUTHOR: Carsten Dominik 13457 #+OPTIONS: H:2 toc:t num:t 13458 #+LATEX_CLASS: beamer 13459 #+LATEX_CLASS_OPTIONS: [presentation] 13460 #+BEAMER_THEME: Madrid 13461 #+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) 13462 13463 * This is the first structural section 13464 13465 ** Frame 1 13466 *** Thanks to Eric Fraga :B_block: 13467 :PROPERTIES: 13468 :BEAMER_COL: 0.48 13469 :BEAMER_ENV: block 13470 :END: 13471 for the first viable Beamer setup in Org 13472 *** Thanks to everyone else :B_block: 13473 :PROPERTIES: 13474 :BEAMER_COL: 0.48 13475 :BEAMER_ACT: <2-> 13476 :BEAMER_ENV: block 13477 :END: 13478 for contributing to the discussion 13479 **** This will be formatted as a beamer note :B_note: 13480 :PROPERTIES: 13481 :BEAMER_env: note 13482 :END: 13483 ** Frame 2 (where we will not use columns) 13484 *** Request 13485 Please test this stuff! 13486 @end example 13487 13488 @node HTML Export 13489 @section HTML Export 13490 13491 @cindex HTML export 13492 13493 Org mode contains an HTML exporter with extensive HTML formatting 13494 compatible with XHTML 1.0 strict standard. 13495 13496 @menu 13497 * HTML export commands:: Invoking HTML export. 13498 * HTML specific export settings:: Settings for HTML export. 13499 * HTML doctypes:: Exporting various (X)HTML flavors. 13500 * HTML preamble and postamble:: Inserting preamble and postamble. 13501 * Quoting HTML tags:: Using direct HTML in Org files. 13502 * Headlines in HTML export:: Formatting headlines. 13503 * Links in HTML export:: Inserting and formatting links. 13504 * Tables in HTML export:: How to modify the formatting of tables. 13505 * Images in HTML export:: How to insert figures into HTML output. 13506 * Math formatting in HTML export:: Beautiful math also on the web. 13507 * Text areas in HTML export:: An alternate way to show an example. 13508 * CSS support:: Changing the appearance of the output. 13509 * JavaScript support:: Info and folding in a web browser. 13510 @end menu 13511 13512 @node HTML export commands 13513 @subsection HTML export commands 13514 13515 @table @asis 13516 @item @kbd{C-c C-e h h} (@code{org-html-export-to-html}) 13517 @kindex C-c C-e h h 13518 @kindex C-c C-e h o 13519 @findex org-html-export-to-html 13520 13521 Export as HTML file with a @samp{.html} extension. For @samp{myfile.org}, Org 13522 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. 13523 13524 @item @kbd{C-c C-e h H} (@code{org-html-export-as-html}) 13525 @kindex C-c C-e h H 13526 @findex org-html-export-as-html 13527 13528 Exports to a temporary buffer. Does not create a file. 13529 @end table 13530 13531 @node HTML specific export settings 13532 @subsection HTML specific export settings 13533 13534 HTML export has a number of keywords, similar to the general options 13535 settings described in @ref{Export Settings}. 13536 13537 @table @asis 13538 @item @samp{DESCRIPTION} 13539 @cindex @samp{DESCRIPTION}, keyword 13540 This is the document's description, which the HTML exporter inserts 13541 it as a HTML meta tag in the HTML file. For long descriptions, use 13542 multiple @samp{DESCRIPTION} lines. The exporter takes care of wrapping 13543 the lines properly. 13544 13545 The exporter includes a number of other meta tags, which can be customized 13546 by modifying @code{org-html-meta-tags}. 13547 13548 @item @samp{HTML_DOCTYPE} 13549 @cindex @samp{HTML_DOCTYPE}, keyword 13550 @vindex org-html-doctype 13551 Specify the document type, for example: HTML5 (@code{org-html-doctype}). 13552 13553 @item @samp{HTML_CONTAINER} 13554 @cindex @samp{HTML_CONTAINER}, keyword 13555 @vindex org-html-container-element 13556 Specify the HTML container, such as @samp{div}, for wrapping sections and 13557 elements (@code{org-html-container-element}). 13558 13559 @item @samp{HTML_LINK_HOME} 13560 @cindex @samp{HTML_LINK_HOME}, keyword 13561 @vindex org-html-link-home 13562 The URL for home link (@code{org-html-link-home}). 13563 13564 @item @samp{HTML_LINK_UP} 13565 @cindex @samp{HTML_LINK_UP}, keyword 13566 @vindex org-html-link-up 13567 The URL for the up link of exported HTML pages (@code{org-html-link-up}). 13568 13569 @item @samp{HTML_MATHJAX} 13570 @cindex @samp{HTML_MATHJAX}, keyword 13571 @vindex org-html-mathjax-options 13572 Options for MathJax (@code{org-html-mathjax-options}). MathJax is used 13573 to typeset @LaTeX{} math in HTML documents. See @ref{Math formatting in HTML export}, for an example. 13574 13575 @item @samp{HTML_HEAD} 13576 @cindex @samp{HTML_HEAD}, keyword 13577 @vindex org-html-head 13578 Arbitrary lines for appending to the HTML document's head 13579 (@code{org-html-head}). 13580 13581 @item @samp{HTML_HEAD_EXTRA} 13582 @cindex @samp{HTML_HEAD_EXTRA}, keyword 13583 @vindex org-html-head-extra 13584 More arbitrary lines for appending to the HTML document's head 13585 (@code{org-html-head-extra}). 13586 13587 @item @samp{KEYWORDS} 13588 @cindex @samp{KEYWORDS}, keyword 13589 Keywords to describe the document's content. HTML exporter inserts 13590 these keywords as HTML meta tags. For long keywords, use multiple 13591 @samp{KEYWORDS} lines. 13592 13593 @item @samp{LATEX_HEADER} 13594 @cindex @samp{LATEX_HEADER}, keyword 13595 Arbitrary lines for appending to the preamble; HTML exporter appends 13596 when transcoding @LaTeX{} fragments to images (see @ref{Math formatting in HTML export}). 13597 13598 @item @samp{SUBTITLE} 13599 @cindex @samp{SUBTITLE}, keyword 13600 The document's subtitle. HTML exporter formats subtitle if document 13601 type is @samp{HTML5} and the CSS has a @samp{subtitle} class. 13602 @end table 13603 13604 Some of these keywords are explained in more detail in the following 13605 sections of the manual. 13606 13607 @node HTML doctypes 13608 @subsection HTML doctypes 13609 13610 Org can export to various (X)HTML flavors. 13611 13612 @vindex org-html-doctype 13613 @vindex org-html-doctype-alist 13614 Set the @code{org-html-doctype} variable for different (X)HTML variants. 13615 Depending on the variant, the HTML exporter adjusts the syntax of HTML 13616 conversion accordingly. Org includes the following ready-made 13617 variants: 13618 13619 @itemize 13620 @item 13621 @code{"html4-strict"} 13622 @item 13623 @code{"html4-transitional"} 13624 @item 13625 @code{"html4-frameset"} 13626 @item 13627 @code{"xhtml-strict"} 13628 @item 13629 @code{"xhtml-transitional"} 13630 @item 13631 @code{"xhtml-frameset"} 13632 @item 13633 @code{"xhtml-11"} 13634 @item 13635 @code{"html5"} 13636 @item 13637 @code{"xhtml5"} 13638 @end itemize 13639 13640 @noindent 13641 See the variable @code{org-html-doctype-alist} for details. The default is 13642 @code{"xhtml-strict"}. 13643 13644 @vindex org-html-html5-fancy 13645 @cindex @samp{HTML5}, export new elements 13646 Org's HTML exporter does not by default enable new block elements 13647 introduced with the HTML5 standard. To enable them, set 13648 @code{org-html-html5-fancy} to non-@code{nil}. Or use an @samp{OPTIONS} line in the 13649 file to set @samp{html5-fancy}. 13650 13651 HTML5 documents can now have arbitrary @samp{#+BEGIN} @dots{} @samp{#+END} blocks. 13652 For example: 13653 13654 @example 13655 #+BEGIN_aside 13656 Lorem ipsum 13657 #+END_aside 13658 @end example 13659 13660 @noindent 13661 exports to: 13662 13663 @example 13664 <aside> 13665 <p>Lorem ipsum</p> 13666 </aside> 13667 @end example 13668 13669 @noindent 13670 while this: 13671 13672 @example 13673 #+ATTR_HTML: :controls controls :width 350 13674 #+BEGIN_video 13675 #+HTML: <source src="movie.mp4" type="video/mp4"> 13676 #+HTML: <source src="movie.ogg" type="video/ogg"> 13677 Your browser does not support the video tag. 13678 #+END_video 13679 @end example 13680 13681 @noindent 13682 exports to: 13683 13684 @example 13685 <video controls="controls" width="350"> 13686 <source src="movie.mp4" type="video/mp4"> 13687 <source src="movie.ogg" type="video/ogg"> 13688 <p>Your browser does not support the video tag.</p> 13689 </video> 13690 @end example 13691 13692 @vindex org-html-html5-elements 13693 When special blocks do not have a corresponding HTML5 element, the 13694 HTML exporter reverts to standard translation (see 13695 @code{org-html-html5-elements}). For example, @samp{#+BEGIN_lederhosen} exports 13696 to @code{<div class="lederhosen">}. 13697 13698 Special blocks cannot have headlines. For the HTML exporter to wrap 13699 the headline and its contents in @code{<section>} or @code{<article>} tags, set 13700 the @samp{HTML_CONTAINER} property for the headline. 13701 13702 @node HTML preamble and postamble 13703 @subsection HTML preamble and postamble 13704 13705 @vindex org-html-preamble 13706 @vindex org-html-postamble 13707 @vindex org-html-preamble-format 13708 @vindex org-html-postamble-format 13709 @vindex org-html-validation-link 13710 @vindex org-export-creator-string 13711 @vindex org-export-time-stamp-file 13712 13713 The HTML exporter has delineations for preamble and postamble. The 13714 default value for @code{org-html-preamble} is @code{t}, which makes the HTML 13715 exporter insert the preamble. See the variable 13716 @code{org-html-preamble-format} for the format string. 13717 13718 Set @code{org-html-preamble} to a string to override the default format 13719 string. If set to a function, the HTML exporter expects the function 13720 to return a string upon execution. The HTML exporter inserts this 13721 string in the preamble. The HTML exporter does not insert a preamble 13722 if @code{org-html-preamble} is set @code{nil}. 13723 13724 The above also applies to @code{org-html-postamble} and 13725 @code{org-html-postamble-format}. In addition, @code{org-html-postamble} can be 13726 set to @code{auto} (its default value), which makes the HTML exporter build 13727 a postamble from looking up author's name, email address, creator's 13728 name, and date. 13729 13730 @node Quoting HTML tags 13731 @subsection Quoting HTML tags 13732 13733 The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and @samp{>}. 13734 To include raw HTML code in the Org file so the HTML export back-end 13735 can insert that HTML code in the output, use this inline syntax: 13736 @samp{@@@@html:...@@@@}. For example: 13737 13738 @example 13739 @@@@html:<b>@@@@bold text@@@@html:</b>@@@@ 13740 @end example 13741 13742 13743 @cindex @samp{HTML}, keyword 13744 @cindex @samp{BEGIN_EXPORT html} 13745 For larger raw HTML code blocks, use these HTML export code blocks: 13746 13747 @example 13748 #+HTML: Literal HTML code for export 13749 13750 #+BEGIN_EXPORT html 13751 All lines between these markers are exported literally 13752 #+END_EXPORT 13753 @end example 13754 13755 @node Headlines in HTML export 13756 @subsection Headlines in HTML export 13757 13758 @cindex headlines, in HTML export 13759 13760 Headlines are exported to @samp{<h1>}, @samp{<h2>}, etc. Each headline gets the 13761 @samp{id} attribute from @samp{CUSTOM_ID} property, or a unique generated value, 13762 see @ref{Internal Links}. 13763 13764 @vindex org-html-self-link-headlines 13765 When @code{org-html-self-link-headlines} is set to a non-@code{nil} value, the 13766 text of the headlines is also wrapped in @samp{<a>} tags. These tags have 13767 a @samp{href} attribute making the headlines link to themselves. 13768 13769 @node Links in HTML export 13770 @subsection Links in HTML export 13771 13772 @cindex links, in HTML export 13773 @cindex internal links, in HTML export 13774 @cindex external links, in HTML export 13775 13776 The HTML export back-end transforms Org's internal links (see 13777 @ref{Internal Links}) to equivalent HTML links in the output. The back-end 13778 similarly handles Org's automatic links created by radio targets (see 13779 @ref{Radio Targets}) similarly. For Org links to external files, the 13780 back-end transforms the links to @emph{relative} paths. 13781 13782 @vindex org-html-link-org-files-as-html 13783 For Org links to other @samp{.org} files, the back-end automatically 13784 changes the file extension to @samp{.html} and makes file paths relative. 13785 If the @samp{.org} files have an equivalent @samp{.html} version at the same 13786 location, then the converted links should work without any further 13787 manual intervention. However, to disable this automatic path 13788 translation, set @code{org-html-link-org-files-as-html} to @code{nil}. When 13789 disabled, the HTML export back-end substitutes the ID-based links in 13790 the HTML output. For more about linking files when publishing to 13791 a directory, see @ref{Publishing links}. 13792 13793 Org files can also have special directives to the HTML export 13794 back-end. For example, by using @samp{#+ATTR_HTML} lines to specify new 13795 format attributes to @code{<a>} or @code{<img>} tags. This example shows 13796 changing the link's title and style: 13797 13798 @cindex @samp{ATTR_HTML}, keyword 13799 @example 13800 #+ATTR_HTML: :title The Org mode website :style color:red; 13801 [[https://orgmode.org]] 13802 @end example 13803 13804 @node Tables in HTML export 13805 @subsection Tables in HTML export 13806 13807 @cindex tables, in HTML 13808 @vindex org-export-html-table-tag 13809 13810 The HTML export back-end uses @code{org-html-table-default-attributes} when 13811 exporting Org tables to HTML@. By default, the exporter does not draw 13812 frames and cell borders. To change for this for a table, use the 13813 following lines before the table in the Org file: 13814 13815 @cindex @samp{CAPTION}, keyword 13816 @cindex @samp{ATTR_HTML}, keyword 13817 @example 13818 #+CAPTION: This is a table with lines around and between cells 13819 #+ATTR_HTML: :border 2 :rules all :frame border 13820 @end example 13821 13822 The HTML export back-end preserves column groupings in Org tables (see 13823 @ref{Column Groups}) when exporting to HTML@. 13824 13825 Additional options for customizing tables for HTML export. 13826 13827 @table @asis 13828 @item @code{org-html-table-align-individual-fields} 13829 @vindex org-html-table-align-individual-fields 13830 Non-@code{nil} attaches style attributes for alignment to each table 13831 field. 13832 13833 @item @code{org-html-table-caption-above} 13834 @vindex org-html-table-caption-above 13835 Non-@code{nil} places caption string at the beginning of the table. 13836 13837 @item @code{org-html-table-data-tags} 13838 @vindex org-html-table-data-tags 13839 Opening and ending tags for table data fields. 13840 13841 @item @code{org-html-table-default-attributes} 13842 @vindex org-html-table-default-attributes 13843 Default attributes and values for table tags. 13844 13845 @item @code{org-html-table-header-tags} 13846 @vindex org-html-table-header-tags 13847 Opening and ending tags for table's header fields. 13848 13849 @item @code{org-html-table-row-tags} 13850 @vindex org-html-table-row-tags 13851 Opening and ending tags for table rows. 13852 13853 @item @code{org-html-table-use-header-tags-for-first-column} 13854 @vindex org-html-table-use-header-tags-for-first-column 13855 Non-@code{nil} formats column one in tables with header tags. 13856 @end table 13857 13858 @node Images in HTML export 13859 @subsection Images in HTML export 13860 13861 @cindex images, inline in HTML 13862 @cindex inlining images in HTML 13863 13864 The HTML export back-end has features to convert Org image links to 13865 HTML inline images and HTML clickable image links. 13866 13867 @vindex org-html-inline-images 13868 When the link in the Org file has no description, the HTML export 13869 back-end by default in-lines that image. For example: 13870 @samp{[[file:myimg.jpg]]} is in-lined, while @samp{[[file:myimg.jpg][the image]]} links to the text, 13871 @samp{the image}. For more details, see the variable 13872 @code{org-html-inline-images}. 13873 13874 On the other hand, if the description part of the Org link is itself 13875 another link, such as @samp{file:} or @samp{http:} URL pointing to an image, the 13876 HTML export back-end in-lines this image and links to the main image. 13877 This Org syntax enables the back-end to link low-resolution thumbnail 13878 to the high-resolution version of the image, as shown in this example: 13879 13880 @example 13881 [[file:highres.jpg][file:thumb.jpg]] 13882 @end example 13883 13884 13885 To change attributes of in-lined images, use @samp{#+ATTR_HTML} lines in 13886 the Org file. This example shows realignment to right, and adds @code{alt} 13887 and @code{title} attributes in support of text viewers and modern web 13888 accessibility standards. 13889 13890 @cindex @samp{CAPTION}, keyword 13891 @cindex @samp{ATTR_HTML}, keyword 13892 @example 13893 #+CAPTION: A black cat stalking a spider 13894 #+ATTR_HTML: :alt cat/spider image :title Action! :align right 13895 [[./img/a.jpg]] 13896 @end example 13897 13898 The HTML export back-end copies the @samp{http} links from the Org file 13899 as-is. 13900 13901 @node Math formatting in HTML export 13902 @subsection Math formatting in HTML export 13903 13904 @cindex MathJax 13905 @cindex dvipng 13906 @cindex dvisvgm 13907 @cindex ImageMagick 13908 13909 @vindex org-html-mathjax-options~ 13910 @LaTeX{} math snippets (see @ref{@LaTeX{} fragments}) can be displayed in two 13911 different ways on HTML pages. The default is to use the 13912 @uref{https://www.mathjax.org, MathJax}, which should work out of the box 13913 with Org@footnote{ By default, Org loads MathJax from 13914 @uref{https://www.jsdelivr.com/, jsDelivr}, as recommended in 13915 @uref{https://docs.mathjax.org/en/latest/web/start.html, Getting Started 13916 with MathJax Components}.}@footnote{Please note that exported formulas are part of an HTML 13917 document, and that signs such as @samp{<}, @samp{>}, or @samp{&} have special 13918 meanings. See @uref{https://docs.mathjax.org/en/latest/input/tex/html.html#tex-and-latex-in-html-documents, MathJax @TeX{} and @LaTeX{} in HTML documents}.}. Some MathJax display options can 13919 be configured via @code{org-html-mathjax-options}, or in the buffer. For 13920 example, with the following settings, 13921 13922 @example 13923 #+HTML_MATHJAX: align: left indent: 5em tagside: left 13924 @end example 13925 13926 @noindent 13927 equation labels are displayed on the left margin and equations are 13928 five em from the left margin. 13929 13930 @vindex org-html-mathjax-template 13931 See the docstring of @code{org-html-mathjax-options} for all supported 13932 variables. The MathJax template can be configure via 13933 @code{org-html-mathjax-template}. 13934 13935 If you prefer, you can also request that @LaTeX{} fragments are processed 13936 into small images that will be inserted into the browser page. Before 13937 the availability of MathJax, this was the default method for Org 13938 files. This method requires that the dvipng program, dvisvgm or 13939 ImageMagick suite is available on your system. You can still get this 13940 processing with 13941 13942 @example 13943 #+OPTIONS: tex:dvipng 13944 @end example 13945 13946 13947 @example 13948 #+OPTIONS: tex:dvisvgm 13949 @end example 13950 13951 13952 @noindent 13953 or 13954 13955 @example 13956 #+OPTIONS: tex:imagemagick 13957 @end example 13958 13959 @node Text areas in HTML export 13960 @subsection Text areas in HTML export 13961 13962 @cindex text areas, in HTML 13963 Before Org mode's Babel, one popular approach to publishing code in 13964 HTML was by using @samp{:textarea}. The advantage of this approach was 13965 that copying and pasting was built into browsers with simple 13966 JavaScript commands. Even editing before pasting was made simple. 13967 13968 The HTML export back-end can create such text areas. It requires an 13969 @samp{#+ATTR_HTML} line as shown in the example below with the @samp{:textarea} 13970 option. This must be followed by either an example or a source code 13971 block. Other Org block types do not honor the @samp{:textarea} option. 13972 13973 By default, the HTML export back-end creates a text area 80 characters 13974 wide and height just enough to fit the content. Override these 13975 defaults with @samp{:width} and @samp{:height} options on the @samp{#+ATTR_HTML} 13976 line. 13977 13978 @example 13979 #+ATTR_HTML: :textarea t :width 40 13980 #+BEGIN_EXAMPLE 13981 (defun org-xor (a b) 13982 "Exclusive or." 13983 (if a (not b) b)) 13984 #+END_EXAMPLE 13985 @end example 13986 13987 @node CSS support 13988 @subsection CSS support 13989 13990 @cindex CSS, for HTML export 13991 @cindex HTML export, CSS 13992 13993 @vindex org-export-html-todo-kwd-class-prefix 13994 @vindex org-export-html-tag-class-prefix 13995 You can modify the CSS style definitions for the exported file. The 13996 HTML exporter assigns the following special CSS classes@footnote{ If the 13997 classes on TODO keywords and tags lead to conflicts, use the variables 13998 @code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to 13999 make them unique.} to appropriate parts of the document---your style 14000 specifications may change these, in addition to any of the standard 14001 classes like for headlines, tables, etc. 14002 14003 @multitable {aaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 14004 @item @code{p.author} 14005 @tab author information, including email 14006 @item @code{p.date} 14007 @tab publishing date 14008 @item @code{p.creator} 14009 @tab creator info, about org mode version 14010 @item @code{.title} 14011 @tab document title 14012 @item @code{.subtitle} 14013 @tab document subtitle 14014 @item @code{.todo} 14015 @tab TODO keywords, all not-done states 14016 @item @code{.done} 14017 @tab the DONE keywords, all states that count as done 14018 @item @code{.WAITING} 14019 @tab each TODO keyword also uses a class named after itself 14020 @item @code{.timestamp} 14021 @tab timestamp 14022 @item @code{.timestamp-kwd} 14023 @tab keyword associated with a timestamp, like @samp{SCHEDULED} 14024 @item @code{.timestamp-wrapper} 14025 @tab span around keyword plus timestamp 14026 @item @code{.tag} 14027 @tab tag in a headline 14028 @item @code{._HOME} 14029 @tab each tag uses itself as a class, ``@@'' replaced by ``_'' 14030 @item @code{.target} 14031 @tab target for links 14032 @item @code{.linenr} 14033 @tab the line number in a code example 14034 @item @code{.code-highlighted} 14035 @tab for highlighting referenced code lines 14036 @item @code{div.outline-N} 14037 @tab div for outline level N (headline plus text) 14038 @item @code{div.outline-text-N} 14039 @tab extra div for text at outline level N 14040 @item @code{.section-number-N} 14041 @tab section number in headlines, different for each level 14042 @item @code{.figure-number} 14043 @tab label like ``Figure 1:'' 14044 @item @code{.table-number} 14045 @tab label like ``Table 1:'' 14046 @item @code{.listing-number} 14047 @tab label like ``Listing 1:'' 14048 @item @code{div.figure} 14049 @tab how to format an in-lined image 14050 @item @code{pre.src} 14051 @tab formatted source code 14052 @item @code{pre.example} 14053 @tab normal example 14054 @item @code{p.verse} 14055 @tab verse paragraph 14056 @item @code{div.footnotes} 14057 @tab footnote section headline 14058 @item @code{p.footnote} 14059 @tab footnote definition paragraph, containing a footnote 14060 @item @code{.footref} 14061 @tab a footnote reference number (always a <sup>) 14062 @item @code{.footnum} 14063 @tab footnote number in footnote definition (always <sup>) 14064 @item @code{.org-svg} 14065 @tab default class for a linked @samp{.svg} image 14066 @end multitable 14067 14068 @vindex org-html-style-default 14069 @vindex org-html-head 14070 @vindex org-html-head-extra 14071 @cindex @samp{HTML_INCLUDE_STYLE}, keyword 14072 The HTML export back-end includes a compact default style in each 14073 exported HTML file. To override the default style with another style, 14074 use these keywords in the Org file. They will replace the global 14075 defaults the HTML exporter uses. 14076 14077 @cindex @samp{HTML_HEAD}, keyword 14078 @cindex @samp{HTML_HEAD_EXTRA}, keyword 14079 @example 14080 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" /> 14081 #+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" /> 14082 @end example 14083 14084 @vindex org-html-head-include-default-style 14085 To just turn off the default style, customize 14086 @code{org-html-head-include-default-style} variable, or use this option 14087 line in the Org file. 14088 14089 @cindex @samp{html-style}, @samp{OPTIONS} item 14090 @example 14091 #+OPTIONS: html-style:nil 14092 @end example 14093 14094 14095 For longer style definitions, either use several @samp{HTML_HEAD} and 14096 @samp{HTML_HEAD_EXTRA} keywords, or use @code{<style> ... </style>} blocks 14097 around them. Both of these approaches can avoid referring to an 14098 external file. 14099 14100 @cindex @samp{HTML_CONTAINER_CLASS}, property 14101 @cindex @samp{HTML_HEADLINE_CLASS}, property 14102 In order to add styles to a subtree, use the @samp{HTML_CONTAINER_CLASS} 14103 property to assign a class to the tree. In order to specify CSS 14104 styles for a particular headline, you can use the ID specified in 14105 a @samp{CUSTOM_ID} property. You can also assign a specific class to 14106 a headline with the @samp{HTML_HEADLINE_CLASS} property. 14107 14108 Never change the @code{org-html-style-default} constant. Instead use other 14109 simpler ways of customizing as described above. 14110 14111 @node JavaScript support 14112 @subsection JavaScript supported display of web pages 14113 14114 Sebastian Rose has written a JavaScript program especially designed to 14115 allow two different ways of viewing HTML files created with Org. One 14116 is an @emph{Info}-like mode where each section is displayed separately and 14117 navigation can be done with the @kbd{n} and @kbd{p} keys, and some other 14118 keys as well, press @kbd{?} for an overview of the available keys. The 14119 second one has a @emph{folding} view, much like Org provides inside Emacs. 14120 The script is available at @uref{https://orgmode.org/org-info.js} and the 14121 documentation at @uref{https://orgmode.org/worg/code/org-info-js/}. The 14122 script is hosted on @uref{https://orgmode.org}, but for reliability, prefer 14123 installing it on your own web server. 14124 14125 To use this program, just add this line to the Org file: 14126 14127 @cindex @samp{INFOJS_OPT}, keyword 14128 @example 14129 #+INFOJS_OPT: view:info toc:nil 14130 @end example 14131 14132 14133 @noindent 14134 The HTML header now has the code needed to automatically invoke the 14135 script. For setting options, use the syntax from the above line for 14136 options described below: 14137 14138 @table @asis 14139 @item @samp{path:} 14140 The path to the script. The default is to grab the script from 14141 @uref{https://orgmode.org/org-info.js}, but you might want to have a local 14142 copy and use a path like @samp{../scripts/org-info.js}. 14143 14144 @item @samp{view:} 14145 Initial view when the website is first shown. Possible values are: 14146 14147 @multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 14148 @item @samp{info} 14149 @tab Info-like interface with one section per page 14150 @item @samp{overview} 14151 @tab Folding interface, initially showing only top-level 14152 @item @samp{content} 14153 @tab Folding interface, starting with all headlines visible 14154 @item @samp{showall} 14155 @tab Folding interface, all headlines and text visible 14156 @end multitable 14157 14158 @item @samp{sdepth:} 14159 Maximum headline level still considered as an independent section 14160 for info and folding modes. The default is taken from 14161 @code{org-export-headline-levels}, i.e., the @samp{H} switch in @samp{OPTIONS}. If 14162 this is smaller than in @code{org-export-headline-levels}, each 14163 info/folding section can still contain child headlines. 14164 14165 @item @samp{toc:} 14166 Should the table of contents @emph{initially} be visible? Even when 14167 @samp{nil}, you can always get to the ``toc'' with @kbd{i}. 14168 14169 @item @samp{tdepth:} 14170 The depth of the table of contents. The defaults are taken from the 14171 variables @code{org-export-headline-levels} and @code{org-export-with-toc}. 14172 14173 @item @samp{ftoc:} 14174 Does the CSS of the page specify a fixed position for the ``toc''? If 14175 yes, the toc is displayed as a section. 14176 14177 @item @samp{ltoc:} 14178 Should there be short contents (children) in each section? Make 14179 this @samp{above} if the section should be above initial text. 14180 14181 @item @samp{mouse:} 14182 Headings are highlighted when the mouse is over them. Should be 14183 @samp{underline} (default) or a background color like @samp{#cccccc}. 14184 14185 @item @samp{buttons:} 14186 Should view-toggle buttons be everywhere? When @samp{nil} (the default), 14187 only one such button is present. 14188 @end table 14189 14190 @vindex org-infojs-options 14191 @vindex org-export-html-use-infojs 14192 You can choose default values for these options by customizing the 14193 variable @code{org-infojs-options}. If you always want to apply the script 14194 to your pages, configure the variable @code{org-export-html-use-infojs}. 14195 14196 @node @LaTeX{} Export 14197 @section @LaTeX{} Export 14198 14199 @cindex @LaTeX{} export 14200 @cindex PDF export 14201 14202 The @LaTeX{} export back-end can handle complex documents, incorporate 14203 standard or custom @LaTeX{} document classes, generate documents using 14204 alternate @LaTeX{} engines, and produce fully linked PDF files with 14205 indexes, bibliographies, and tables of contents, destined for 14206 interactive online viewing or high-quality print publication. 14207 14208 While the details are covered in-depth in this section, here are some 14209 quick references to variables for the impatient: for engines, see 14210 @code{org-latex-compiler}; for build sequences, see 14211 @code{org-latex-pdf-process}; for packages, see 14212 @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}. 14213 14214 An important note about the @LaTeX{} export back-end: it is sensitive to 14215 blank lines in the Org document. That's because @LaTeX{} itself depends 14216 on blank lines to tell apart syntactical elements, such as paragraphs. 14217 14218 @menu 14219 * @LaTeX{}/PDF export commands:: For producing @LaTeX{} and PDF documents. 14220 * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end. 14221 * @LaTeX{} header and sectioning:: Setting up the export file structure. 14222 * Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code. 14223 * Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{}. 14224 * Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output. 14225 * Plain lists in @LaTeX{} export:: Attributes specific to lists. 14226 * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks. 14227 * Example blocks in @LaTeX{} export:: Attributes specific to example blocks. 14228 * Special blocks in @LaTeX{} export:: Attributes specific to special blocks. 14229 * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules. 14230 * Verse blocks in @LaTeX{} export:: Attributes specific to special blocks. 14231 * Quote blocks in @LaTeX{} export:: Attributes specific to quote blocks. 14232 @end menu 14233 14234 @node @LaTeX{}/PDF export commands 14235 @subsection @LaTeX{}/PDF export commands 14236 14237 @table @asis 14238 @item @kbd{C-c C-e l l} (@code{org-latex-export-to-latex}) 14239 @kindex C-c C-e l l 14240 @findex org-latex-export-to-latex~ 14241 Export to a @LaTeX{} file with a @samp{.tex} extension. For @samp{myfile.org}, 14242 Org exports to @samp{myfile.tex}, overwriting without warning. 14243 14244 @item @kbd{C-c C-e l L} (@code{org-latex-export-as-latex}) 14245 @kindex C-c C-e l L 14246 @findex org-latex-export-as-latex 14247 Export to a temporary buffer. Do not create a file. 14248 14249 @item @kbd{C-c C-e l p} (@code{org-latex-export-to-pdf}) 14250 @kindex C-c C-e l p 14251 @findex org-latex-export-to-pdf 14252 Export as @LaTeX{} file and convert it to PDF file. 14253 14254 @item @kbd{C-c C-e l o} 14255 @kindex C-c C-e l o 14256 Export as @LaTeX{} file and convert it to PDF, then open the PDF using 14257 the default viewer. 14258 14259 @item @kbd{M-x org-export-region-as-latex} 14260 Convert the region to @LaTeX{} under the assumption that it was in Org 14261 mode syntax before. This is a global command that can be invoked in 14262 any buffer. 14263 @end table 14264 14265 @vindex org-latex-compiler 14266 @vindex org-latex-bibtex-compiler 14267 @vindex org-latex-default-packages-alist 14268 @cindex pdflatex 14269 @cindex xelatex 14270 @cindex lualatex 14271 @cindex @samp{LATEX_COMPILER}, keyword 14272 The @LaTeX{} export back-end can use any of these @LaTeX{} engines: 14273 @samp{pdflatex}, @samp{xelatex}, and @samp{lualatex}. These engines compile @LaTeX{} 14274 files with different compilers, packages, and output options. The 14275 @LaTeX{} export back-end finds the compiler version to use from 14276 @code{org-latex-compiler} variable or the @samp{#+LATEX_COMPILER} keyword in the 14277 Org file. See the docstring for the 14278 @code{org-latex-default-packages-alist} for loading packages with certain 14279 compilers. Also see @code{org-latex-bibtex-compiler} to set the 14280 bibliography compiler@footnote{This does not allow setting different bibliography compilers 14281 for different files. However, ``smart'' @LaTeX{} compilation systems, such 14282 as latexmk, can select the correct bibliography compiler.}. 14283 14284 @node @LaTeX{} specific export settings 14285 @subsection @LaTeX{} specific export settings 14286 14287 The @LaTeX{} export back-end has several additional keywords for 14288 customizing @LaTeX{} output. Setting these keywords works similar to the 14289 general options (see @ref{Export Settings}). 14290 14291 @table @asis 14292 @item @samp{DESCRIPTION} 14293 @cindex @samp{DESCRIPTION}, keyword 14294 @vindex org-latex-hyperref-template 14295 @vindex org-latex-title-command 14296 The document's description. The description along with author name, 14297 keywords, and related file metadata are inserted in the output file 14298 by the hyperref package. See @code{org-latex-hyperref-template} for 14299 customizing metadata items. See @code{org-latex-title-command} for 14300 typesetting description into the document's front matter. Use 14301 multiple @samp{DESCRIPTION} keywords for long descriptions. 14302 14303 @item @samp{LANGUAGE} 14304 @cindex @samp{LANGUAGE}, keyword 14305 @vindex org-latex-packages-alist 14306 @vindex org-latex-language-alist 14307 14308 Language code of the primary document language. 14309 14310 The list of language codes supported by Org is stored in the 14311 variable @code{org-latex-language-alist}. 14312 14313 In order to be effective, the @samp{babel} or @samp{polyglossia} 14314 packages---according to the @LaTeX{} compiler used---must be loaded 14315 with the appropriate language as argument. This can be accomplished 14316 by modifying the @code{org-latex-packages-alist} variable, e.g., with the 14317 following snippet (note that @samp{polyglossia} does not work with 14318 pdf@LaTeX{}): 14319 14320 @lisp 14321 (add-to-list 'org-latex-packages-alist 14322 '("AUTO" "babel" t ("pdflatex" "xelatex" "lualatex"))) 14323 (add-to-list 'org-latex-packages-alist 14324 '("AUTO" "polyglossia" t ("xelatex" "lualatex"))) 14325 @end lisp 14326 14327 @item @samp{LATEX_CLASS} 14328 @cindex @samp{LATEX_CLASS}, keyword 14329 @vindex org-latex-default-class 14330 @vindex org-latex-classes 14331 This is @LaTeX{} document class, such as @emph{article}, @emph{report}, @emph{book}, 14332 and so on, which contain predefined preamble and headline level 14333 mapping that the @LaTeX{} export back-end needs. The back-end reads 14334 the default class name from the @code{org-latex-default-class} variable. 14335 Org has @emph{article} as the default class. A valid default class must 14336 be an element of @code{org-latex-classes}. 14337 14338 @item @samp{LATEX_CLASS_OPTIONS} 14339 @cindex @samp{LATEX_CLASS_OPTIONS}, keyword 14340 Options the @LaTeX{} export back-end uses when calling the @LaTeX{} 14341 document class. 14342 14343 @item @samp{LATEX_COMPILER} 14344 @cindex @samp{LATEX_COMPILER}, keyword 14345 @vindex org-latex-compiler 14346 The compiler, such as @samp{pdflatex}, @samp{xelatex}, @samp{lualatex}, for 14347 producing the PDF@. See @code{org-latex-compiler}. 14348 14349 @item @samp{LATEX_HEADER} 14350 @itemx @samp{LATEX_HEADER_EXTRA} 14351 @cindex @samp{LATEX_HEADER}, keyword 14352 @cindex @samp{LATEX_HEADER_EXTRA}, keyword 14353 @vindex org-latex-classes 14354 Arbitrary lines to add to the document's preamble, before the 14355 hyperref settings. See @code{org-latex-classes} for adjusting the 14356 structure and order of the @LaTeX{} headers. 14357 14358 @item @samp{KEYWORDS} 14359 @cindex @samp{KEYWORDS}, keyword 14360 @vindex org-latex-hyperref-template 14361 @vindex org-latex-title-command 14362 The keywords for the document. The description along with author 14363 name, keywords, and related file metadata are inserted in the output 14364 file by the hyperref package. See @code{org-latex-hyperref-template} for 14365 customizing metadata items. See @code{org-latex-title-command} for 14366 typesetting description into the document's front matter. Use 14367 multiple @samp{KEYWORDS} lines if necessary. 14368 14369 @item @samp{SUBTITLE} 14370 @cindex @samp{SUBTITLE}, keyword 14371 @vindex org-latex-subtitle-separate 14372 @vindex org-latex-subtitle-format 14373 The document's subtitle. It is typeset as per 14374 @code{org-latex-subtitle-format}. If @code{org-latex-subtitle-separate} is 14375 non-@code{nil}, it is typed outside of the @code{\title} macro. See 14376 @code{org-latex-hyperref-template} for customizing metadata items. See 14377 @code{org-latex-title-command} for typesetting description into the 14378 document's front matter. 14379 @end table 14380 14381 The following sections have further details. 14382 14383 @node @LaTeX{} header and sectioning 14384 @subsection @LaTeX{} header and sectioning structure 14385 14386 @cindex @LaTeX{} class 14387 @cindex @LaTeX{} sectioning structure 14388 @cindex @LaTeX{} header 14389 @cindex header, for @LaTeX{} files 14390 @cindex sectioning structure, for @LaTeX{} export 14391 14392 The @LaTeX{} export back-end converts the first three of Org's outline 14393 levels into @LaTeX{} headlines. The remaining Org levels are exported as 14394 lists. To change this globally for the cut-off point between levels 14395 and lists, (see @ref{Export Settings}). 14396 14397 By default, the @LaTeX{} export back-end uses the @emph{article} class. 14398 14399 @vindex org-latex-default-class 14400 @vindex org-latex-classes 14401 @vindex org-latex-default-packages-alist 14402 @vindex org-latex-packages-alist 14403 To change the default class globally, edit @code{org-latex-default-class}. 14404 To change the default class locally in an Org file, add option lines 14405 @samp{#+LATEX_CLASS: myclass}. To change the default class for just a part 14406 of the Org file, set a subtree property, @samp{EXPORT_LATEX_CLASS}. The 14407 class name entered here must be valid member of @code{org-latex-classes}. 14408 This variable defines a header template for each class into which the 14409 exporter splices the values of @code{org-latex-default-packages-alist} and 14410 @code{org-latex-packages-alist}. Use the same three variables to define 14411 custom sectioning or custom classes. 14412 14413 @cindex @samp{LATEX_CLASS}, keyword 14414 @cindex @samp{LATEX_CLASS_OPTIONS}, keyword 14415 @cindex @samp{EXPORT_LATEX_CLASS}, property 14416 @cindex @samp{EXPORT_LATEX_CLASS_OPTIONS}, property 14417 The @LaTeX{} export back-end sends the @samp{LATEX_CLASS_OPTIONS} keyword and 14418 @samp{EXPORT_LATEX_CLASS_OPTIONS} property as options to the @LaTeX{} 14419 @code{\documentclass} macro. The options and the syntax for specifying 14420 them, including enclosing them in square brackets, follow @LaTeX{} 14421 conventions. 14422 14423 @example 14424 #+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn] 14425 @end example 14426 14427 14428 @cindex @samp{LATEX_HEADER}, keyword 14429 @cindex @samp{LATEX_HEADER_EXTRA}, keyword 14430 The @LaTeX{} export back-end appends values from @samp{LATEX_HEADER} and 14431 @samp{LATEX_HEADER_EXTRA} keywords to the @LaTeX{} header. The docstring for 14432 @code{org-latex-classes} explains in more detail. Also note that @LaTeX{} 14433 export back-end does not append @samp{LATEX_HEADER_EXTRA} to the header 14434 when previewing @LaTeX{} snippets (see @ref{Previewing @LaTeX{} fragments}). 14435 14436 A sample Org file with the above headers: 14437 14438 @example 14439 #+LATEX_CLASS: article 14440 #+LATEX_CLASS_OPTIONS: [a4paper] 14441 #+LATEX_HEADER: \usepackage@{xyz@} 14442 14443 * Headline 1 14444 some text 14445 * Headline 2 14446 some more text 14447 @end example 14448 14449 @cindex @samp{LANGUAGE}, keyword 14450 @vindex org-export-default-language 14451 @LaTeX{} packages @samp{babel} or @samp{polyglossia} can also be loaded in a 14452 document. The ``AUTO'' string will be replaced in both cases by the 14453 appropriate value for the @samp{LANGUAGE} keyword, if present in the 14454 document, or by the value of @code{org-export-default-language}. Let's see 14455 some examples in one or another case. 14456 14457 @samp{Babel} accepts the classic syntax and (in addition) the new syntax 14458 with the @samp{\babelprovide} command to load the languages using the new 14459 @samp{INI} files procedure. Keep in mind that there are a number of 14460 languages that are only served in babel using @samp{INI} files, so they 14461 cannot be declared using the classic syntax, but only using the 14462 @samp{\babelprovide} command (see 14463 @uref{https://mirrors.ctan.org/macros/latex/required/babel/base/babel.pdf}). 14464 Valid usage examples could be: 14465 14466 @example 14467 #+LATEX_HEADER: \usepackage[french,italian,AUTO]@{babel@} 14468 @end example 14469 14470 where ``AUTO'' is the main language. But it can also be loaded using 14471 the @samp{\babelprovide} command: 14472 14473 @example 14474 #+LATEX_HEADER: \usepackage[french,italian]@{babel@} 14475 #+LATEX_HEADER: \babelprovide[import, main]@{AUTO@} 14476 @end example 14477 14478 @samp{Polyglossia}, for this procedure to be effective, must be loaded 14479 using the same @samp{babel} classic syntax (but note that @emph{this is not} 14480 the actual polyglossia syntax). For example, suppose a document 14481 declares Polytonic Greek as the primary language, and French as the 14482 secondary language. In this case, it would be expressed as: 14483 14484 @example 14485 #+LANGUAGE: el-polyton 14486 #+LATEX_HEADER: \usepackage[french,AUTO]@{polyglossia@} 14487 @end example 14488 14489 This would produce in @LaTeX{} (with the actual @samp{polyglossia} syntax): 14490 14491 @example 14492 \usepackage@{polyglossia@} 14493 \setmainlanguage[variant=polytonic]@{greek@} 14494 \setotherlanguage@{french@} 14495 @end example 14496 14497 @node Quoting @LaTeX{} code 14498 @subsection Quoting @LaTeX{} code 14499 14500 The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code, see 14501 @ref{Embedded @LaTeX{}}. There are three ways to embed such code in the Org 14502 file and they all use different quoting syntax. 14503 14504 @cindex inline, in @LaTeX{} export 14505 Inserting in-line quoted with @@ symbols: 14506 14507 @example 14508 Code embedded in-line @@@@latex:any arbitrary LaTeX code@@@@ in a paragraph. 14509 @end example 14510 14511 14512 @cindex @samp{LATEX}, keyword 14513 Inserting as one or more keyword lines in the Org file: 14514 14515 @example 14516 #+LATEX: any arbitrary LaTeX code 14517 @end example 14518 14519 14520 @cindex @samp{BEGIN_EXPORT latex} 14521 Inserting as an export block in the Org file, where the back-end 14522 exports any code between begin and end markers: 14523 14524 @example 14525 #+BEGIN_EXPORT latex 14526 any arbitrary LaTeX code 14527 #+END_EXPORT 14528 @end example 14529 14530 @node Tables in @LaTeX{} export 14531 @subsection Tables in @LaTeX{} export 14532 14533 @cindex tables, in @LaTeX{} export 14534 14535 The @LaTeX{} export back-end can pass several @LaTeX{} attributes for table 14536 contents and layout. Besides specifying a label (see @ref{Internal Links}) 14537 and a caption (see @ref{Captions}), the other valid @LaTeX{} attributes 14538 include: 14539 14540 @table @asis 14541 @item @samp{:mode} 14542 @vindex org-latex-default-table-mode 14543 The @LaTeX{} export back-end wraps the table differently depending on 14544 the mode for accurate rendering of math symbols. Mode is either 14545 @samp{table}, @samp{math}, @samp{inline-math}, @samp{verbatim} or @samp{tabbing}. 14546 14547 For @samp{math} or @samp{inline-math} mode, @LaTeX{} export back-end wraps the 14548 table in a math environment, but every cell in it is exported as-is. 14549 For @samp{tabbing} the @LaTeX{} tabbing environment is used and the correct 14550 tabbing delimiters @samp{\>} are used. 14551 The @LaTeX{} export back-end determines the default mode from 14552 @code{org-latex-default-table-mode}. The @LaTeX{} export back-end merges 14553 contiguous tables in the same mode into a single environment. 14554 14555 @item @samp{:environment} 14556 @vindex org-latex-default-table-environment 14557 Set the default @LaTeX{} table environment for the @LaTeX{} export 14558 back-end to use when exporting Org tables. Common @LaTeX{} table 14559 environments are provided by these packages: tabularx, longtable, 14560 array, tabu, and bmatrix. For packages, such as tabularx and tabu, 14561 or any newer replacements, include them in the 14562 @code{org-latex-packages-alist} variable so the @LaTeX{} export back-end can 14563 insert the appropriate load package headers in the converted @LaTeX{} 14564 file. Look in the docstring for the @code{org-latex-packages-alist} 14565 variable for configuring these packages for @LaTeX{} snippet previews, 14566 if any. 14567 14568 @item @samp{:caption} 14569 Use @samp{CAPTION} keyword to set a simple caption for a table (see 14570 @ref{Captions}). For custom captions, use @samp{:caption} attribute, which 14571 accepts raw @LaTeX{} code. @samp{:caption} value overrides @samp{CAPTION} value. 14572 14573 @item @samp{:float} 14574 @itemx @samp{:placement} 14575 The table environments by default are not floats in @LaTeX{}. To make 14576 them floating objects use @samp{:float} with one of the following 14577 options: @samp{t} (for a default @samp{table} environment), @samp{sideways} (for a 14578 @samp{sidewaystable} environment), @samp{multicolumn} (to span the table 14579 across multiple columns of a page in a @samp{table*} environment) and 14580 @samp{nil}. In addition to these three values, @samp{:float} can pass through 14581 any arbitrary value, for example a user-defined float type with the 14582 @samp{float} @LaTeX{} package. 14583 14584 @LaTeX{} floats can also have additional layout @samp{:placement} 14585 attributes. These are the usual @samp{[h t b p ! H]} permissions 14586 specified in square brackets. Note that for @samp{:float sideways} 14587 tables, the @LaTeX{} export back-end ignores @samp{:placement} attributes. 14588 14589 @item @samp{:align} 14590 @itemx @samp{:font} 14591 @itemx @samp{:width} 14592 The @LaTeX{} export back-end uses these attributes for regular tables 14593 to set their alignments, fonts, and widths. 14594 14595 @item @samp{:options} 14596 The @samp{:options} attribute allows adding an optional argument with 14597 a list of various table options (between brackets in @LaTeX{} export), 14598 since certain tabular environments, such as longtblr of the 14599 tabularray @LaTeX{} package, provides this structure. For example: 14600 @samp{:options remark@{Note@}=@{note@},remark@{Source@}=@{source@}}. 14601 14602 @item @samp{:spread} 14603 When @samp{:spread} is non-@code{nil}, the @LaTeX{} export back-end spreads or 14604 shrinks the table by the @samp{:width} for tabu and longtabu 14605 environments. @samp{:spread} has no effect if @samp{:width} is not set. 14606 14607 @item @samp{:booktabs} 14608 @itemx @samp{:center} 14609 @itemx @samp{:rmlines} 14610 @vindex org-latex-tables-booktabs 14611 @vindex org-latex-tables-centered 14612 All three commands are toggles. @samp{:booktabs} brings in modern 14613 typesetting enhancements to regular tables. The booktabs package 14614 has to be loaded through @code{org-latex-packages-alist}. @samp{:center} is 14615 for centering the table. @samp{:rmlines} removes all but the very first 14616 horizontal line made of ASCII characters from ``table.el'' tables 14617 only. 14618 14619 @item @samp{:math-prefix} 14620 @itemx @samp{:math-suffix} 14621 @itemx @samp{:math-arguments} 14622 The @LaTeX{} export back-end inserts @samp{:math-prefix} string value in 14623 a math environment before the table. The @LaTeX{} export back-end 14624 inserts @samp{:math-suffix} string value in a math environment after the 14625 table. The @LaTeX{} export back-end inserts @samp{:math-arguments} string 14626 value between the macro name and the table's contents. 14627 @samp{:math-arguments} comes in use for matrix macros that require more 14628 than one argument, such as @samp{qbordermatrix}. 14629 @end table 14630 14631 @LaTeX{} table attributes help formatting tables for a wide range of 14632 situations, such as matrix product or spanning multiple pages: 14633 14634 @example 14635 #+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l 14636 | ... | ... | 14637 | ... | ... | 14638 14639 #+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times 14640 | a | b | 14641 | c | d | 14642 #+ATTR_LATEX: :mode math :environment bmatrix 14643 | 1 | 2 | 14644 | 3 | 4 | 14645 @end example 14646 14647 Set the caption with the @LaTeX{} command 14648 @samp{\bicaption@{HeadingA@}@{HeadingB@}}: 14649 14650 @example 14651 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@} 14652 | ... | ... | 14653 | ... | ... | 14654 @end example 14655 14656 @node Images in @LaTeX{} export 14657 @subsection Images in @LaTeX{} export 14658 14659 @cindex images, inline in LaTeX 14660 @cindex inlining images in LaTeX 14661 @cindex @samp{ATTR_LATEX}, keyword 14662 14663 The @LaTeX{} export back-end processes image links in Org files that do 14664 not have descriptions, such as these links @samp{[[file:img.jpg]]} or 14665 @samp{[[./img.jpg]]}, as direct image insertions in the final PDF output. In 14666 the PDF, they are no longer links but actual images embedded on the 14667 page. The @LaTeX{} export back-end uses @samp{\includegraphics} macro to 14668 insert the image. But for TikZ (@uref{https://sourceforge.net/projects/pgf/}) 14669 images, the back-end uses an @code{\input} macro wrapped within 14670 a @code{tikzpicture} environment. 14671 14672 For specifying image @samp{:width}, @samp{:height}, @samp{:scale} and other @samp{:options}, 14673 use this syntax: 14674 14675 @example 14676 #+ATTR_LATEX: :width 5cm :options angle=90 14677 [[./img/sed-hr4049.pdf]] 14678 @end example 14679 14680 A @samp{:scale} attribute overrides both @samp{:width} and @samp{:height} attributes. 14681 14682 For custom commands for captions, use the @samp{:caption} attribute. It 14683 overrides the default @samp{#+CAPTION} value: 14684 14685 @example 14686 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@} 14687 [[./img/sed-hr4049.pdf]] 14688 @end example 14689 14690 When captions follow the method as described in @ref{Captions}, the @LaTeX{} 14691 export back-end wraps the picture in a floating @samp{figure} environment. 14692 To float an image without specifying a caption, set the @samp{:float} 14693 attribute to one of the following: 14694 14695 @table @asis 14696 @item @samp{t} 14697 For a default @samp{figure} environment. 14698 14699 @item @samp{multicolumn} 14700 To span the image across multiple columns of a page; the back-end 14701 wraps the image in a @samp{figure*} environment. 14702 14703 @item @samp{wrap} 14704 For text to flow around the image on the right; the figure occupies 14705 the left half of the page. 14706 14707 @item @samp{sideways} 14708 For a new page with the image sideways, rotated ninety degrees, in 14709 a @samp{sidewaysfigure} environment; overrides @samp{:placement} setting. 14710 14711 @item @samp{nil} 14712 To avoid a @samp{:float} even if using a caption. 14713 14714 @item Any arbitrary value 14715 For example, a user-defined float type with the @samp{float} @LaTeX{} 14716 package. 14717 @end table 14718 14719 14720 Use the @samp{placement} attribute to modify a floating environment's 14721 placement. 14722 14723 @example 14724 #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@} 14725 [[./img/hst.png]] 14726 @end example 14727 14728 @vindex org-latex-images-centered 14729 @cindex center image in LaTeX export 14730 @cindex image, centering in LaTeX export 14731 The @LaTeX{} export back-end centers all images by default. Setting 14732 @samp{:center} to @samp{nil} disables centering. To disable centering globally, 14733 set @code{org-latex-images-centered} to @samp{nil}. 14734 14735 Set the @samp{:comment-include} attribute to non-@code{nil} value for the @LaTeX{} 14736 export back-end to comment out the @samp{\includegraphics} macro. 14737 14738 @node Plain lists in @LaTeX{} export 14739 @subsection Plain lists in @LaTeX{} export 14740 14741 @cindex plain lists, in @LaTeX{} export 14742 @cindex @samp{ATTR_LATEX}, keyword 14743 The @LaTeX{} export back-end accepts the @samp{environment} and @samp{options} 14744 attributes for plain lists. Both attributes work together for 14745 customizing lists, as shown in the examples: 14746 14747 @example 14748 #+LATEX_HEADER: \usepackage[inline]@{enumitem@} 14749 Some ways to say "Hello": 14750 #+ATTR_LATEX: :environment itemize* 14751 #+ATTR_LATEX: :options [label=@{@}, itemjoin=@{,@}, itemjoin*=@{, and@}] 14752 - Hola 14753 - Bonjour 14754 - Guten Tag. 14755 @end example 14756 14757 Since @LaTeX{} supports only four levels of nesting for lists, use an 14758 external package, such as @samp{enumitem} in @LaTeX{}, for levels deeper than 14759 four: 14760 14761 @example 14762 #+LATEX_HEADER: \usepackage@{enumitem@} 14763 #+LATEX_HEADER: \renewlist@{itemize@}@{itemize@}@{9@} 14764 #+LATEX_HEADER: \setlist[itemize]@{label=$\circ$@} 14765 - One 14766 - Two 14767 - Three 14768 - Four 14769 - Five 14770 @end example 14771 14772 @node Source blocks in @LaTeX{} export 14773 @subsection Source blocks in @LaTeX{} export 14774 14775 @cindex source blocks, in @LaTeX{} export 14776 @cindex @samp{ATTR_LATEX}, keyword 14777 14778 The @LaTeX{} export back-end can make source code blocks into floating 14779 objects through the attributes @samp{:float} and @samp{:options}. For @samp{:float}: 14780 14781 @table @asis 14782 @item @samp{t} 14783 Makes a source block float; by default floats any source block with 14784 a caption. 14785 14786 @item @samp{multicolumn} 14787 Spans the source block across multiple columns of a page. 14788 14789 @item @samp{nil} 14790 Avoids a @samp{:float} even if using a caption; useful for source code 14791 blocks that may not fit on a page. 14792 @end table 14793 14794 @example 14795 #+ATTR_LATEX: :float nil 14796 #+BEGIN_SRC emacs-lisp 14797 Lisp code that may not fit in a single page. 14798 #+END_SRC 14799 @end example 14800 14801 @vindex org-latex-listings-options 14802 @vindex org-latex-minted-options 14803 @vindex org-latex-engraved-options 14804 The @LaTeX{} export back-end passes string values in @samp{:options} to @LaTeX{} 14805 packages for customization of that specific source block. In the 14806 example below, the @samp{:options} are set for Engraved or Minted. Minted 14807 is a source code highlighting @LaTeX{} package with many configurable 14808 options@footnote{ Minted uses an external Python package for code 14809 highlighting, which requires the flag @samp{-shell-escape} to be added to 14810 @code{org-latex-pdf-process}.}. Both Minted and Engraved are built on 14811 @uref{https://www.ctan.org/pkg/fvextra, fvextra}, and so support many of 14812 the same options. 14813 14814 @example 14815 #+ATTR_LATEX: :options mathescape 14816 #+BEGIN_SRC emacs-lisp 14817 (defun Fib (n) ; $n_i = n_@{i-2@} + n_@{i-1@}$ 14818 (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2))))) 14819 #+END_SRC 14820 @end example 14821 14822 To apply similar configuration options for all source blocks in a 14823 file, use the @code{org-latex-listings-options}, 14824 @code{org-latex-engraved-options}, and @code{org-latex-minted-options} 14825 variables. 14826 14827 @node Example blocks in @LaTeX{} export 14828 @subsection Example blocks in @LaTeX{} export 14829 14830 @cindex example blocks, in @LaTeX{} export 14831 @cindex verbatim blocks, in @LaTeX{} export 14832 @cindex @samp{ATTR_LATEX}, keyword 14833 14834 The @LaTeX{} export back-end wraps the contents of example blocks in 14835 a @samp{verbatim} environment. To change this behavior to use another 14836 environment globally, specify an appropriate export filter (see 14837 @ref{Advanced Export Configuration}). To change this behavior to use 14838 another environment for each block, use the @samp{:environment} parameter 14839 to specify a custom environment. 14840 14841 @example 14842 #+ATTR_LATEX: :environment myverbatim 14843 #+BEGIN_EXAMPLE 14844 This sentence is false. 14845 #+END_EXAMPLE 14846 @end example 14847 14848 @node Special blocks in @LaTeX{} export 14849 @subsection Special blocks in @LaTeX{} export 14850 14851 @cindex special blocks, in @LaTeX{} export 14852 @cindex abstract, in @LaTeX{} export 14853 @cindex proof, in @LaTeX{} export 14854 @cindex @samp{ATTR_LATEX}, keyword 14855 14856 For other special blocks in the Org file, the @LaTeX{} export back-end 14857 makes a special environment of the same name. The back-end also takes 14858 @samp{:options}, if any, and appends as-is to that environment's opening 14859 string. For example: 14860 14861 @example 14862 #+BEGIN_abstract 14863 We demonstrate how to solve the Syracuse problem. 14864 #+END_abstract 14865 14866 #+ATTR_LATEX: :options [Proof of important theorem] 14867 #+BEGIN_proof 14868 ... 14869 Therefore, any even number greater than 2 is the sum of two primes. 14870 #+END_proof 14871 @end example 14872 14873 @noindent 14874 exports to 14875 14876 @example 14877 \begin@{abstract@} 14878 We demonstrate how to solve the Syracuse problem. 14879 \end@{abstract@} 14880 14881 \begin@{proof@}[Proof of important theorem] 14882 ... 14883 Therefore, any even number greater than 2 is the sum of two primes. 14884 \end@{proof@} 14885 @end example 14886 14887 If you need to insert a specific caption command, use @samp{:caption} 14888 attribute. It overrides standard @samp{CAPTION} value, if any. For 14889 example: 14890 14891 @example 14892 #+ATTR_LATEX: :caption \MyCaption@{HeadingA@} 14893 #+BEGIN_proof 14894 ... 14895 #+END_proof 14896 @end example 14897 14898 @node Horizontal rules in @LaTeX{} export 14899 @subsection Horizontal rules in @LaTeX{} export 14900 14901 @cindex horizontal rules, in @LaTeX{} export 14902 @cindex @samp{ATTR_LATEX}, keyword 14903 14904 The @LaTeX{} export back-end converts horizontal rules by the specified 14905 @samp{:width} and @samp{:thickness} attributes. For example: 14906 14907 @example 14908 #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt 14909 ----- 14910 @end example 14911 14912 @node Verse blocks in @LaTeX{} export 14913 @subsection Verse blocks in @LaTeX{} export 14914 14915 @cindex verse blocks, in @LaTeX{} export 14916 @cindex @samp{ATTR_LATEX}, keyword 14917 14918 The @LaTeX{} export back-end accepts four attributes for verse blocks: 14919 @samp{:lines}, @samp{:center}, @samp{:versewidth} and @samp{:latexcode}. The three first 14920 require the external @LaTeX{} package @samp{verse.sty}, which is an extension 14921 of the standard @LaTeX{} environment. 14922 14923 @table @asis 14924 @item @samp{:lines} 14925 To add marginal verse numbering. Its value is an 14926 integer, the sequence in which the verses should be numbered. 14927 @item @samp{:center} 14928 With value @samp{t} all the verses on the page are optically 14929 centered (a typographic convention for poetry), taking as a 14930 reference the longest verse, which must be indicated by the 14931 attribute @samp{:versewidth}. 14932 @item @samp{:versewidth} 14933 Its value is a literal text string with the longest 14934 verse. 14935 @item @samp{:latexcode} 14936 It accepts any arbitrary @LaTeX{} code that can be 14937 included within a @LaTeX{} @samp{verse} environment. 14938 @end table 14939 14940 A complete example with Shakespeare's first sonnet: 14941 14942 @example 14943 #+ATTR_LATEX: :center t :latexcode \color@{red@} :lines 5 14944 #+ATTR_LATEX: :versewidth Feed’st thy light’s flame with self-substantial fuel, 14945 #+BEGIN_VERSE 14946 From fairest creatures we desire increase, 14947 That thereby beauty’s rose might never die, 14948 But as the riper should by time decease 14949 His tender heir might bear his memory 14950 But thou, contracted to thine own bright eyes, 14951 Feed’st thy light’s flame with self-substantial fuel, 14952 Making a famine where abundance lies, 14953 Thyself thy foe, to thy sweet self too cruel. 14954 Thou that art now the world’s fresh ornament, 14955 And only herald to the gaudy spring, 14956 Within thine own bud buriest thy content, 14957 And, tender churl, mak’st waste in niggardly. 14958 Pity the world, or else this glutton be, 14959 To eat the world’s due, by the grave and thee. 14960 #+END_VERSE 14961 @end example 14962 14963 @node Quote blocks in @LaTeX{} export 14964 @subsection Quote blocks in @LaTeX{} export 14965 14966 @cindex quote blocks, in @LaTeX{} export 14967 @cindex @samp{ATTR_LATEX}, keyword 14968 @cindex org-latex-default-quote-environment 14969 14970 The @LaTeX{} export back-end accepts two attributes for quote blocks: 14971 @samp{:environment}, for an arbitrary quoting environment (the default 14972 value is that of @code{org-latex-default-quote-environment}: @code{"quote"}) and 14973 @samp{:options}. For example, to choose the environment @samp{quotation}, 14974 included as an alternative to @samp{quote} in standard @LaTeX{} classes: 14975 14976 @example 14977 #+ATTR_LATEX: :environment quotation 14978 #+BEGIN_QUOTE 14979 some text... 14980 #+END_QUOTE 14981 @end example 14982 14983 To choose the @samp{foreigndisplayquote} environment, included in the @LaTeX{} 14984 package @samp{csquotes}, with the @samp{german} option, use this syntax: 14985 14986 @example 14987 #+LATEX_HEADER:\usepackage[autostyle=true]@{csquotes@} 14988 #+ATTR_LATEX: :environment foreigndisplayquote :options @{german@} 14989 #+BEGIN_QUOTE 14990 some text in German... 14991 #+END_QUOTE 14992 @end example 14993 14994 @noindent 14995 which is exported to @LaTeX{} as 14996 14997 @example 14998 \begin@{foreigndisplayquote@}@{german@} 14999 some text in German... 15000 \end@{foreigndisplayquote@} 15001 @end example 15002 15003 @node Markdown Export 15004 @section Markdown Export 15005 15006 @cindex Markdown export 15007 15008 The Markdown export back-end, ``md'', converts an Org file to Markdown 15009 format, as defined at @uref{https://daringfireball.net/projects/markdown/}. 15010 15011 Since it is built on top of the HTML back-end (see @ref{HTML Export}), it 15012 converts every Org construct not defined in Markdown syntax, such as 15013 tables, to HTML@. 15014 15015 @anchor{Markdown export commands} 15016 @subheading Markdown export commands 15017 15018 @table @asis 15019 @item @kbd{C-c C-e m m} (@code{org-md-export-to-markdown}) 15020 @kindex C-c C-c m m 15021 @findex org-md-export-to-markdown 15022 Export to a text file with Markdown syntax. For @samp{myfile.org}, Org 15023 exports to @samp{myfile.md}, overwritten without warning. 15024 15025 @item @kbd{C-c C-e m M} (@code{org-md-export-as-markdown}) 15026 @kindex C-c C-c m M 15027 @findex org-md-export-as-markdown 15028 Export to a temporary buffer. Does not create a file. 15029 15030 @item @kbd{C-c C-e m o} 15031 @kindex C-c C-e m o 15032 Export as a text file with Markdown syntax, then open it. 15033 @end table 15034 15035 @anchor{Header and sectioning structure (1)} 15036 @subheading Header and sectioning structure 15037 15038 @vindex org-md-headline-style 15039 Based on @code{org-md-headline-style}, Markdown export can generate 15040 headlines of both @emph{atx} and @emph{setext} types. @emph{atx} limits headline 15041 levels to two whereas @emph{setext} limits headline levels to six. Beyond 15042 these limits, the export back-end converts headlines to lists. To set 15043 a limit to a level before the absolute limit (see @ref{Export Settings}). 15044 15045 @node OpenDocument Text Export 15046 @section OpenDocument Text Export 15047 15048 @cindex ODT 15049 @cindex OpenDocument 15050 @cindex export, OpenDocument 15051 @cindex LibreOffice 15052 15053 The ODT export back-end handles creating of OpenDocument Text (ODT) 15054 format. Documents created by this exporter use the 15055 @cite{OpenDocument-v1.2 specification}@footnote{ See 15056 @uref{https://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, Open 15057 Document Format for Office Applications (OpenDocument) Version 1.2}.} 15058 and are compatible with LibreOffice 3.4. 15059 15060 @menu 15061 * Pre-requisites for ODT export:: Required packages. 15062 * ODT export commands:: Invoking export. 15063 * ODT specific export settings:: Configuration options. 15064 * Extending ODT export:: Producing DOC, PDF files. 15065 * Applying custom styles:: Styling the output. 15066 * Links in ODT export:: Handling and formatting links. 15067 * Tables in ODT export:: Org tables conversions. 15068 * Images in ODT export:: Inserting images. 15069 * Math formatting in ODT export:: Formatting @LaTeX{} fragments. 15070 * Labels and captions in ODT export:: Rendering objects. 15071 * Literal examples in ODT export:: For source code and example blocks. 15072 * Advanced topics in ODT export:: For power users. 15073 @end menu 15074 15075 @node Pre-requisites for ODT export 15076 @subsection Pre-requisites for ODT export 15077 15078 @cindex zip 15079 15080 The ODT export back-end relies on the zip program to create the final 15081 compressed ODT output. Check if @samp{zip} is locally available and 15082 executable. Without it, export cannot finish. 15083 15084 @node ODT export commands 15085 @subsection ODT export commands 15086 15087 @table @asis 15088 @item @kbd{C-c C-e o o} (@code{org-export-to-odt}) 15089 @kindex C-c C-e o o 15090 @findex org-export-to-odt 15091 Export as OpenDocument Text file. 15092 15093 @cindex @samp{EXPORT_FILE_NAME}, property 15094 @vindex org-odt-preferred-output-format 15095 15096 If @code{org-odt-preferred-output-format} is specified, the ODT export 15097 back-end automatically converts the exported file to that format. 15098 15099 For @samp{myfile.org}, Org exports to @samp{myfile.odt}, overwriting without 15100 warning. The ODT export back-end exports a region only if a region 15101 was active. 15102 15103 If the selected region is a single tree, the ODT export back-end 15104 makes the tree head the document title. Incidentally, @kbd{C-c @@} selects the current subtree. If the tree head entry has, or 15105 inherits, an @samp{EXPORT_FILE_NAME} property, the ODT export back-end 15106 uses that for file name. 15107 15108 @item @kbd{C-c C-e o O} 15109 @kindex C-c C-e o O 15110 Export as an OpenDocument Text file and open the resulting file. 15111 15112 @vindex org-export-odt-preferred-output-format 15113 If @code{org-export-odt-preferred-output-format} is specified, open the 15114 converted file instead. See @ref{Automatically exporting to other formats}. 15115 @end table 15116 15117 @node ODT specific export settings 15118 @subsection ODT specific export settings 15119 15120 The ODT export back-end has several additional keywords for 15121 customizing ODT output. Setting these keywords works similar to the 15122 general options (see @ref{Export Settings}). 15123 15124 @table @asis 15125 @item @samp{DESCRIPTION} 15126 @cindex @samp{DESCRIPTION}, keyword 15127 This is the document's description, which the ODT export back-end 15128 inserts as document metadata. For long descriptions, use multiple 15129 lines, prefixed with @samp{DESCRIPTION}. 15130 15131 @item @samp{KEYWORDS} 15132 @cindex @samp{KEYWORDS}, keyword 15133 The keywords for the document. The ODT export back-end inserts the 15134 description along with author name, keywords, and related file 15135 metadata as metadata in the output file. Use multiple @samp{KEYWORDS} if 15136 necessary. 15137 15138 @item @samp{ODT_STYLES_FILE} 15139 @cindex @samp{ODT_STYLES_FILE}, keyword 15140 @vindex org-odt-styles-file 15141 The ODT export back-end uses the @code{org-odt-styles-file} by default. 15142 See @ref{Applying custom styles} for details. 15143 15144 @item @samp{SUBTITLE} 15145 @cindex @samp{SUBTITLE}, keyword 15146 The document subtitle. 15147 @end table 15148 15149 @node Extending ODT export 15150 @subsection Extending ODT export 15151 15152 The ODT export back-end can produce documents in other formats besides 15153 ODT using a specialized ODT converter process. Its common interface 15154 works with popular converters to produce formats such as @samp{doc}, or 15155 convert a document from one format, say @samp{csv}, to another format, say 15156 @samp{xls}. 15157 15158 @cindex @file{unoconv} 15159 @vindex org-odt-convert-process 15160 Customize @code{org-odt-convert-process} variable to point to @samp{unoconv}, 15161 which is the ODT's preferred converter. Working installations of 15162 LibreOffice would already have @samp{unoconv} installed. Alternatively, 15163 other converters may be substituted here. See @ref{Configuring a document converter}. 15164 15165 @anchor{Automatically exporting to other formats} 15166 @subsubheading Automatically exporting to other formats 15167 15168 @vindex org-odt-preferred-output-format 15169 If ODT format is just an intermediate step to get to other formats, 15170 such as @samp{doc}, @samp{docx}, @samp{rtf}, or @samp{pdf}, etc., then extend the ODT 15171 export back-end to directly produce that format. Specify the final 15172 format in the @code{org-odt-preferred-output-format} variable. This is one 15173 way to extend (see @ref{ODT export commands}). 15174 15175 @anchor{Converting between document formats} 15176 @subsubheading Converting between document formats 15177 15178 The Org export back-end is made to be inter-operable with a wide range 15179 of text document format converters. Newer generation converters, such 15180 as LibreOffice and Pandoc, can handle hundreds of formats at once. 15181 Org provides a consistent interaction with whatever converter is 15182 installed. Here are some generic commands: 15183 15184 @table @asis 15185 @item @kbd{M-x org-odt-convert} 15186 @findex org-odt-convert 15187 Convert an existing document from one format to another. With 15188 a prefix argument, opens the newly produced file. 15189 @end table 15190 15191 @node Applying custom styles 15192 @subsection Applying custom styles 15193 15194 @cindex styles, custom 15195 @cindex template, custom 15196 15197 The ODT export back-end comes with many OpenDocument styles (see 15198 @ref{Working with OpenDocument style files}). To expand or further 15199 customize these built-in style sheets, either edit the style sheets 15200 directly or generate them using an application such as LibreOffice. 15201 The example here shows creating a style using LibreOffice. 15202 15203 @anchor{Applying custom styles the easy way} 15204 @subsubheading Applying custom styles: the easy way 15205 15206 @enumerate 15207 @item 15208 Create a sample @samp{example.org} file with settings as shown below, 15209 and export it to ODT format. 15210 15211 @example 15212 #+OPTIONS: H:10 num:t 15213 @end example 15214 15215 @item 15216 Open the above @samp{example.odt} using LibreOffice. Use the @emph{Stylist} 15217 to locate the target styles, which typically have the ``Org'' prefix. 15218 Open one, modify, and save as either OpenDocument Text (ODT) or 15219 OpenDocument Template (OTT) file. 15220 15221 @item 15222 @vindex org-odt-styles-file 15223 Customize the variable @code{org-odt-styles-file} and point it to the 15224 newly created file. For additional configuration options, see 15225 @ref{x-overriding-factory-styles, , Overriding factory styles}. 15226 15227 @cindex @samp{ODT_STYLES_FILE}, keyword 15228 To apply an ODT style to a particular file, use the 15229 @samp{ODT_STYLES_FILE} keyword as shown in the example below: 15230 15231 @example 15232 #+ODT_STYLES_FILE: "/path/to/example.ott" 15233 @end example 15234 15235 15236 @noindent 15237 or 15238 15239 @example 15240 #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png")) 15241 @end example 15242 @end enumerate 15243 15244 @anchor{Using third-party styles and templates} 15245 @subsubheading Using third-party styles and templates 15246 15247 The ODT export back-end relies on many templates and style names. 15248 Using third-party styles and templates can lead to mismatches. 15249 Templates derived from built-in ODT templates and styles seem to have 15250 fewer problems. 15251 15252 @node Links in ODT export 15253 @subsection Links in ODT export 15254 15255 @cindex links, in ODT export 15256 15257 ODT exporter creates native cross-references for internal links. It 15258 creates Internet-style links for all other links. 15259 15260 A link with no description and pointing to a regular, un-itemized, 15261 outline heading is replaced with a cross-reference and section number 15262 of the heading. 15263 15264 A @samp{\ref@{label@}}-style reference to an image, table etc., is replaced 15265 with a cross-reference and sequence number of the labeled entity. See 15266 @ref{Labels and captions in ODT export}. 15267 15268 @node Tables in ODT export 15269 @subsection Tables in ODT export 15270 15271 @cindex tables, in ODT export 15272 15273 The ODT export back-end handles native Org mode tables (see @ref{Tables}) 15274 and simple @samp{table.el} tables. Complex @samp{table.el} tables having column 15275 or row spans are not supported. Such tables are stripped from the 15276 exported document. 15277 15278 By default, the ODT export back-end exports a table with top and 15279 bottom frames and with ruled lines separating row and column groups 15280 (see @ref{Column Groups}). All tables are typeset to occupy the same 15281 width. The ODT export back-end honors any table alignments and 15282 relative widths for columns (see @ref{Column Width and Alignment}). 15283 15284 Note that the ODT export back-end interprets column widths as weighted 15285 ratios, the default weight being 1. 15286 15287 @cindex @samp{ATTR_ODT}, keyword 15288 Specifying @samp{:rel-width} property on an @samp{ATTR_ODT} line controls the 15289 width of the table. For example: 15290 15291 @example 15292 #+ATTR_ODT: :rel-width 50 15293 | Area/Month | Jan | Feb | Mar | Sum | 15294 |---------------+-------+-------+-------+-------| 15295 | / | < | | | < | 15296 | <l13> | <r5> | <r5> | <r5> | <r6> | 15297 | North America | 1 | 21 | 926 | 948 | 15298 | Middle East | 6 | 75 | 844 | 925 | 15299 | Asia Pacific | 9 | 27 | 790 | 826 | 15300 |---------------+-------+-------+-------+-------| 15301 | Sum | 16 | 123 | 2560 | 2699 | 15302 @end example 15303 15304 On export, the above table takes 50% of text width area. The exporter 15305 sizes the columns in the ratio: 13:5:5:5:6. The first column is 15306 left-aligned and rest of the columns, right-aligned. Vertical rules 15307 separate the header and the last column. Horizontal rules separate 15308 the header and the last row. 15309 15310 For even more customization, create custom table styles and associate 15311 them with a table using the @samp{ATTR_ODT} keyword. See @ref{Customizing tables in ODT export}. 15312 15313 @node Images in ODT export 15314 @subsection Images in ODT export 15315 15316 @cindex images, embedding in ODT 15317 @cindex embedding images in ODT 15318 15319 @anchor{Embedding images} 15320 @subsubheading Embedding images 15321 15322 The ODT export back-end processes image links in Org files that do not 15323 have descriptions, such as these links @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, 15324 as direct image insertions in the final output. Either of these 15325 examples works: 15326 15327 @example 15328 [[file:img.png]] 15329 @end example 15330 15331 15332 @example 15333 [[./img.png]] 15334 @end example 15335 15336 @anchor{Embedding clickable images} 15337 @subsubheading Embedding clickable images 15338 15339 For clickable images, provide a link whose description is another link 15340 to an image file. For example, to embed an image 15341 @samp{org-mode-unicorn.png} which when clicked jumps to @uref{https://orgmode.org} 15342 website, do the following 15343 15344 @example 15345 [[https://orgmode.org][./org-mode-unicorn.png]] 15346 @end example 15347 15348 @anchor{Sizing and scaling of embedded images} 15349 @subsubheading Sizing and scaling of embedded images 15350 15351 @cindex @samp{ATTR_ODT}, keyword 15352 15353 Control the size and scale of the embedded images with the @samp{ATTR_ODT} 15354 attribute. 15355 15356 @cindex identify, ImageMagick 15357 @vindex org-odt-pixels-per-inch 15358 The ODT export back-end starts with establishing the size of the image 15359 in the final document. The dimensions of this size are measured in 15360 centimeters. The back-end then queries the image file for its 15361 dimensions measured in pixels. For this measurement, the back-end 15362 relies on ImageMagick's identify program or Emacs @code{create-image} and 15363 @code{image-size} API@. ImageMagick is the preferred choice for large file 15364 sizes or frequent batch operations. The back-end then converts the 15365 pixel dimensions using @code{org-odt-pixels-per-inch} into the familiar 72 15366 dpi or 96 dpi. The default value for this is in 15367 @code{display-pixels-per-inch}, which can be tweaked for better results 15368 based on the capabilities of the output device. Here are some common 15369 image scaling operations: 15370 15371 @table @asis 15372 @item Explicitly size the image 15373 To embed @samp{img.png} as a 10 cm x 10 cm image, do the following: 15374 15375 @example 15376 #+ATTR_ODT: :width 10 :height 10 15377 [[./img.png]] 15378 @end example 15379 15380 @item Scale the image 15381 To embed @samp{img.png} at half its size, do the following: 15382 15383 @example 15384 #+ATTR_ODT: :scale 0.5 15385 [[./img.png]] 15386 @end example 15387 15388 @item Scale the image to a specific width 15389 To embed @samp{img.png} with a width of 10 cm while retaining the 15390 original height:width ratio, do the following: 15391 15392 @example 15393 #+ATTR_ODT: :width 10 15394 [[./img.png]] 15395 @end example 15396 15397 @item Scale the image to a specific height 15398 To embed @samp{img.png} with a height of 10 cm while retaining the 15399 original height:width ratio, do the following: 15400 15401 @example 15402 #+ATTR_ODT: :height 10 15403 [[./img.png]] 15404 @end example 15405 @end table 15406 15407 @anchor{Anchoring of images} 15408 @subsubheading Anchoring of images 15409 15410 @cindex @samp{ATTR_ODT}, keyword 15411 The ODT export back-end can anchor images to @samp{as-char}, @samp{paragraph}, 15412 or @samp{page}. Set the preferred anchor using the @samp{:anchor} property of 15413 the @samp{ATTR_ODT} line. 15414 15415 To create an image that is anchored to a page: 15416 15417 @example 15418 #+ATTR_ODT: :anchor page 15419 [[./img.png]] 15420 @end example 15421 15422 @node Math formatting in ODT export 15423 @subsection Math formatting in ODT export 15424 15425 The ODT exporter has special support for handling math. 15426 15427 @menu 15428 * @LaTeX{} math snippets:: Embedding in @LaTeX{} format. 15429 * MathML and OpenDocument formula files:: Embedding in native format. 15430 @end menu 15431 15432 @node @LaTeX{} math snippets 15433 @subsubsection @LaTeX{} math snippets 15434 15435 @LaTeX{} math snippets (see @ref{@LaTeX{} fragments}) can be embedded in the ODT 15436 document in one of the following ways: 15437 15438 @table @asis 15439 @item MathML 15440 @cindex MathML 15441 Add this line to the Org file. This option is activated on 15442 a per-file basis. 15443 15444 @example 15445 #+OPTIONS: tex:t 15446 @end example 15447 15448 15449 With this option, @LaTeX{} fragments are first converted into MathML 15450 fragments using an external @LaTeX{}-to-MathML converter program. The 15451 resulting MathML fragments are then embedded as an OpenDocument 15452 Formula in the exported document. 15453 15454 @vindex org-latex-to-mathml-convert-command 15455 @vindex org-latex-to-mathml-jar-file 15456 You can specify the @LaTeX{}-to-MathML converter by customizing the 15457 variables @code{org-latex-to-mathml-convert-command} and 15458 @code{org-latex-to-mathml-jar-file}. 15459 15460 If you prefer to use MathToWeb@footnote{ See 15461 @uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}.} 15462 as your converter, you can configure the above variables as shown 15463 below. 15464 15465 @lisp 15466 (setq org-latex-to-mathml-convert-command 15467 "java -jar %j -unicode -force -df %o %I" 15468 org-latex-to-mathml-jar-file 15469 "/path/to/mathtoweb.jar") 15470 @end lisp 15471 15472 @noindent 15473 or, to use @LaTeX{}ML@footnote{ See @uref{https://dlmf.nist.gov/LaTeXML/}.} 15474 instead, 15475 15476 @lisp 15477 (setq org-latex-to-mathml-convert-command 15478 "latexmlmath \"%i\" --presentationmathml=%o") 15479 @end lisp 15480 15481 To quickly verify the reliability of the @LaTeX{}-to-MathML 15482 converter, use the following commands: 15483 15484 @table @asis 15485 @item @kbd{M-x org-export-as-odf} 15486 Convert a @LaTeX{} math snippet to an OpenDocument formula (@samp{.odf}) 15487 file. 15488 15489 @item @kbd{M-x org-export-as-odf-and-open} 15490 Convert a @LaTeX{} math snippet to an OpenDocument formula (@samp{.odf}) 15491 file and open the formula file with the system-registered 15492 application. 15493 @end table 15494 15495 @item PNG images 15496 @cindex dvipng 15497 @cindex dvisvgm 15498 @cindex ImageMagick 15499 Add this line to the Org file. This option is activated on 15500 a per-file basis. 15501 15502 @example 15503 #+OPTIONS: tex:dvipng 15504 @end example 15505 15506 15507 @example 15508 #+OPTIONS: tex:dvisvgm 15509 @end example 15510 15511 15512 @noindent 15513 or 15514 15515 @example 15516 #+OPTIONS: tex:imagemagick 15517 @end example 15518 15519 15520 Under this option, @LaTeX{} fragments are processed into PNG or SVG 15521 images and the resulting images are embedded in the exported 15522 document. This method requires dvipng program, dvisvgm or 15523 ImageMagick programs. 15524 @end table 15525 15526 @node MathML and OpenDocument formula files 15527 @subsubsection MathML and OpenDocument formula files 15528 15529 When embedding @LaTeX{} math snippets in ODT documents is not reliable, 15530 there is one more option to try. Embed an equation by linking to its 15531 MathML (@samp{.mml}) source or its OpenDocument formula (@samp{.odf}) file as 15532 shown below: 15533 15534 @example 15535 [[./equation.mml]] 15536 @end example 15537 15538 15539 @noindent 15540 or 15541 15542 @example 15543 [[./equation.odf]] 15544 @end example 15545 15546 @node Labels and captions in ODT export 15547 @subsection Labels and captions in ODT export 15548 15549 ODT format handles labeling and captioning of objects based on their 15550 types. Inline images, tables, @LaTeX{} fragments, and Math formulas are 15551 numbered and captioned separately. Each object also gets a unique 15552 sequence number based on its order of first appearance in the Org 15553 file. Each category has its own sequence. A caption is just a label 15554 applied to these objects. 15555 15556 @example 15557 #+CAPTION: Bell curve 15558 #+NAME: fig:SED-HR4049 15559 [[./img/a.png]] 15560 @end example 15561 15562 When rendered, it may show as follows in the exported document: 15563 15564 @example 15565 Figure 2: Bell curve 15566 @end example 15567 15568 15569 @vindex org-odt-category-map-alist 15570 To modify the category component of the caption, customize the option 15571 @code{org-odt-category-map-alist}. For example, to tag embedded images 15572 with the string ``Illustration'' instead of the default string ``Figure'', 15573 use the following setting: 15574 15575 @lisp 15576 (setq org-odt-category-map-alist 15577 '(("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p))) 15578 @end lisp 15579 15580 With the above modification, the previous example changes to: 15581 15582 @example 15583 Illustration 2: Bell curve 15584 @end example 15585 15586 @node Literal examples in ODT export 15587 @subsection Literal examples in ODT export 15588 15589 The ODT export back-end supports literal examples (see @ref{Literal Examples}) with full fontification. Internally, the ODT export 15590 back-end relies on @samp{htmlfontify.el} to generate the style definitions 15591 needed for fancy listings. The auto-generated styles get @samp{OrgSrc} 15592 prefix and inherit colors from the faces used by Emacs Font Lock 15593 library for that source language. 15594 15595 @vindex org-odt-fontify-srcblocks 15596 For custom fontification styles, customize the 15597 @code{org-odt-create-custom-styles-for-srcblocks} option. 15598 15599 @vindex org-odt-create-custom-styles-for-srcblocks 15600 To turn off fontification of literal examples, customize the 15601 @code{org-odt-fontify-srcblocks} option. 15602 15603 @node Advanced topics in ODT export 15604 @subsection Advanced topics in ODT export 15605 15606 The ODT export back-end has extensive features useful for power users 15607 and frequent uses of ODT formats. 15608 15609 @anchor{Configuring a document converter} 15610 @subsubheading Configuring a document converter 15611 15612 @cindex convert 15613 @cindex doc, docx, rtf 15614 @cindex converter 15615 15616 The ODT export back-end works with popular converters with little or 15617 no extra configuration. See @ref{Extending ODT export}. The following is 15618 for unsupported converters or tweaking existing defaults. 15619 15620 @table @asis 15621 @item Register the converter 15622 @vindex org-export-odt-convert-processes 15623 Add the name of the converter to the @code{org-odt-convert-processes} 15624 variable. Note that it also requires how the converter is invoked 15625 on the command line. See the variable's docstring for details. 15626 15627 @item Configure its capabilities 15628 @vindex org-export-odt-convert-capabilities 15629 Specify which formats the converter can handle by customizing the 15630 variable @code{org-odt-convert-capabilities}. Use the entry for the 15631 default values in this variable for configuring the new converter. 15632 Also see its docstring for details. 15633 15634 @item Choose the converter 15635 @vindex org-export-odt-convert-process 15636 Select the newly added converter as the preferred one by customizing 15637 the option @code{org-odt-convert-process}. 15638 @end table 15639 15640 @anchor{Working with OpenDocument style files} 15641 @subsubheading Working with OpenDocument style files 15642 15643 @cindex styles, custom 15644 @cindex template, custom 15645 15646 This section explores the internals of the ODT exporter; the means by which 15647 it produces styled documents; the use of automatic and custom OpenDocument 15648 styles. 15649 15650 The ODT exporter relies on two files for generating its output. These 15651 files are bundled with the distribution under the directory pointed to 15652 by the variable @code{org-odt-styles-dir}. The two files are: 15653 15654 @table @asis 15655 @item @samp{OrgOdtStyles.xml} @anchor{x-orgodtstyles-xml} 15656 This file contributes to the @samp{styles.xml} file of the final ODT 15657 document. This file gets modified for the following purposes: 15658 15659 @enumerate 15660 @item 15661 To control outline numbering based on user settings; 15662 15663 @item 15664 To add styles generated by @samp{htmlfontify.el} for fontification of 15665 code blocks. 15666 @end enumerate 15667 15668 @item @samp{OrgOdtContentTemplate.xml} @anchor{x-orgodtcontenttemplate-xml} 15669 This file contributes to the @samp{content.xml} file of the final ODT 15670 document. The contents of the Org outline are inserted between the 15671 @samp{<office:text>} @dots{} @samp{</office:text>} elements of this file. 15672 15673 Apart from serving as a template file for the final @samp{content.xml}, 15674 the file serves the following purposes: 15675 15676 @enumerate 15677 @item 15678 It contains automatic styles for formatting of tables which are 15679 referenced by the exporter; 15680 15681 @item 15682 It contains @samp{<text:sequence-decl>} @dots{} @samp{</text:sequence-decl>} 15683 elements that control numbering of tables, images, equations, and 15684 similar entities. 15685 @end enumerate 15686 @end table 15687 15688 @anchor{x-overriding-factory-styles} The following two variables control 15689 the location from where the ODT exporter picks up the custom styles 15690 and content template files. Customize these variables to override the 15691 factory styles used by the exporter. 15692 15693 @table @asis 15694 @item @code{org-odt-styles-file} 15695 The ODT export back-end uses the file pointed to by this variable, 15696 such as @samp{styles.xml}, for the final output. It can take one of the 15697 following values: 15698 15699 @table @asis 15700 @item @samp{FILE.xml} 15701 Use this file instead of the default @samp{styles.xml} 15702 15703 @item @samp{FILE.odt} or @samp{FILE.ott} 15704 Use the @samp{styles.xml} contained in the specified OpenDocument 15705 Text or Template file 15706 15707 @item @samp{FILE.odt} or @samp{FILE.ott} and a subset of included files 15708 Use the @samp{styles.xml} contained in the specified OpenDocument Text 15709 or Template file. Additionally extract the specified member files 15710 and embed those within the final ODT document. 15711 15712 Use this option if the @samp{styles.xml} file references additional 15713 files like header and footer images. 15714 15715 @item @code{nil} 15716 Use the default @samp{styles.xml}. 15717 @end table 15718 15719 @item @code{org-odt-content-template-file} 15720 Use this variable to specify the blank @samp{content.xml} used in the 15721 final output. 15722 @end table 15723 15724 @anchor{Creating one-off styles} 15725 @subsubheading Creating one-off styles 15726 15727 The ODT export back-end can read embedded raw OpenDocument XML from 15728 the Org file. Such direct formatting is useful for one-off instances. 15729 15730 @table @asis 15731 @item Embedding ODT tags as part of regular text 15732 Enclose OpenDocument syntax in @samp{@@@@odt:...@@@@} for inline markup. For 15733 example, to highlight a region of text do the following: 15734 15735 @example 15736 @@@@odt:<text:span text:style-name="Highlight">This is highlighted 15737 text</text:span>@@@@. But this is regular text. 15738 @end example 15739 15740 @strong{Hint:} To see the above example in action, edit the @samp{styles.xml} 15741 (see @ref{x-orgodtstyles-xml, , Factory styles}) and add a custom @emph{Highlight} style as shown 15742 below: 15743 15744 @example 15745 <style:style style:name="Highlight" style:family="text"> 15746 <style:text-properties fo:background-color="#ff0000"/> 15747 </style:style> 15748 @end example 15749 15750 @item Embedding a one-line OpenDocument XML 15751 @cindex @samp{ODT}, keyword 15752 The ODT export back-end can read one-liner options with @samp{#+ODT:} in 15753 the Org file. For example, to force a page break: 15754 15755 @example 15756 #+ODT: <text:p text:style-name="PageBreak"/> 15757 @end example 15758 15759 @strong{Hint:} To see the above example in action, edit your 15760 @samp{styles.xml} (see @ref{x-orgodtstyles-xml, , Factory styles}) and add a custom @samp{PageBreak} 15761 style as shown below. 15762 15763 @example 15764 <style:style style:name="PageBreak" style:family="paragraph" 15765 style:parent-style-name="Text_20_body"> 15766 <style:paragraph-properties fo:break-before="page"/> 15767 </style:style> 15768 @end example 15769 15770 @item Embedding a block of OpenDocument XML 15771 The ODT export back-end can also read ODT export blocks for 15772 OpenDocument XML@. Such blocks use the @samp{#+BEGIN_EXPORT odt} 15773 @dots{} @samp{#+END_EXPORT} constructs. 15774 15775 For example, to create a one-off paragraph that uses bold text, do 15776 the following: 15777 15778 @example 15779 #+BEGIN_EXPORT odt 15780 <text:p text:style-name="Text_20_body_20_bold"> 15781 This paragraph is specially formatted and uses bold text. 15782 </text:p> 15783 #+END_EXPORT 15784 @end example 15785 @end table 15786 15787 @anchor{Customizing tables in ODT export} 15788 @subsubheading Customizing tables in ODT export 15789 15790 @cindex tables, in ODT export 15791 @cindex @samp{ATTR_ODT}, keyword 15792 15793 Override the default table format by specifying a custom table style 15794 with the @samp{#+ATTR_ODT} line. For a discussion on default formatting of 15795 tables, see @ref{Tables in ODT export}. 15796 15797 This feature closely mimics the way table templates are defined in the 15798 OpenDocument-v1.2 specification@footnote{ 15799 @uref{https://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, OpenDocument-v1.2 15800 Specification}}. 15801 15802 @vindex org-odt-table-styles 15803 For quick preview of this feature, install the settings below and export the 15804 table that follows: 15805 15806 @lisp 15807 (setq org-export-odt-table-styles 15808 (append org-export-odt-table-styles 15809 '(("TableWithHeaderRowAndColumn" "Custom" 15810 ((use-first-row-styles . t) 15811 (use-first-column-styles . t))) 15812 ("TableWithFirstRowandLastRow" "Custom" 15813 ((use-first-row-styles . t) 15814 (use-last-row-styles . t)))))) 15815 @end lisp 15816 15817 @example 15818 #+ATTR_ODT: :style TableWithHeaderRowAndColumn 15819 | Name | Phone | Age | 15820 | Peter | 1234 | 17 | 15821 | Anna | 4321 | 25 | 15822 @end example 15823 15824 The example above used @samp{Custom} template and installed two table 15825 styles @samp{TableWithHeaderRowAndColumn} and 15826 @samp{TableWithFirstRowandLastRow}. @strong{Important:} The OpenDocument styles 15827 needed for producing the above template were pre-defined. They are 15828 available in the section marked @samp{Custom Table Template} in 15829 @samp{OrgOdtContentTemplate.xml} (see @ref{x-orgodtcontenttemplate-xml, , Factory styles}). For adding new 15830 templates, define new styles there. 15831 15832 To use this feature proceed as follows: 15833 15834 @enumerate 15835 @item 15836 Create a table template@footnote{ See the @samp{<table:table-template>} 15837 element of the OpenDocument-v1.2 specification.}. 15838 15839 A table template is set of @samp{table-cell} and @samp{paragraph} styles for 15840 each of the following table cell categories: 15841 15842 @itemize 15843 @item 15844 Body 15845 @item 15846 First column 15847 @item 15848 Last column 15849 @item 15850 First row 15851 @item 15852 Last row 15853 @item 15854 Even row 15855 @item 15856 Odd row 15857 @item 15858 Even column 15859 @item 15860 Odd Column 15861 @end itemize 15862 15863 The names for the above styles must be chosen based on the name of 15864 the table template using a well-defined convention. 15865 15866 The naming convention is better illustrated with an example. For 15867 a table template with the name @samp{Custom}, the needed style names are 15868 listed in the following table. 15869 15870 @multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 15871 @headitem Cell type 15872 @tab Cell style 15873 @tab Paragraph style 15874 @item Body 15875 @tab @samp{CustomTableCell} 15876 @tab @samp{CustomTableParagraph} 15877 @item First column 15878 @tab @samp{CustomFirstColumnTableCell} 15879 @tab @samp{CustomFirstColumnTableParagraph} 15880 @item Last column 15881 @tab @samp{CustomLastColumnTableCell} 15882 @tab @samp{CustomLastColumnTableParagraph} 15883 @item First row 15884 @tab @samp{CustomFirstRowTableCell} 15885 @tab @samp{CustomFirstRowTableParagraph} 15886 @item Last row 15887 @tab @samp{CustomLastRowTableCell} 15888 @tab @samp{CustomLastRowTableParagraph} 15889 @item Even row 15890 @tab @samp{CustomEvenRowTableCell} 15891 @tab @samp{CustomEvenRowTableParagraph} 15892 @item Odd row 15893 @tab @samp{CustomOddRowTableCell} 15894 @tab @samp{CustomOddRowTableParagraph} 15895 @item Even column 15896 @tab @samp{CustomEvenColumnTableCell} 15897 @tab @samp{CustomEvenColumnTableParagraph} 15898 @item Odd column 15899 @tab @samp{CustomOddColumnTableCell} 15900 @tab @samp{CustomOddColumnTableParagraph} 15901 @end multitable 15902 15903 To create a table template with the name @samp{Custom}, define the above 15904 styles in the @samp{<office:automatic-styles>} @dots{} 15905 @samp{</office:automatic-styles>} element of the content template file 15906 (see @ref{x-orgodtcontenttemplate-xml, , Factory styles}). 15907 15908 @item 15909 Define a table style@footnote{ See the attributes @samp{table:template-name}, 15910 @samp{table:use-first-row-styles}, @samp{table:use-last-row-styles}, 15911 @samp{table:use-first-column-styles}, @samp{table:use-last-column-styles}, 15912 @samp{table:use-banding-rows-styles}, and 15913 @samp{table:use-banding-column-styles} of the @samp{<table:table>} element in 15914 the OpenDocument-v1.2 specification.}. 15915 15916 @vindex org-odt-table-styles 15917 To define a table style, create an entry for the style in the 15918 variable @code{org-odt-table-styles} and specify the following: 15919 15920 @itemize 15921 @item 15922 the name of the table template created in step (1), 15923 @item 15924 the set of cell styles in that template that are to be activated. 15925 @end itemize 15926 15927 For example, the entry below defines two different table styles 15928 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow} 15929 based on the same template @samp{Custom}. The styles achieve their 15930 intended effect by selectively activating the individual cell 15931 styles in that template. 15932 15933 @lisp 15934 (setq org-export-odt-table-styles 15935 (append org-export-odt-table-styles 15936 '(("TableWithHeaderRowAndColumn" "Custom" 15937 ((use-first-row-styles . t) 15938 (use-first-column-styles . t))) 15939 ("TableWithFirstRowandLastRow" "Custom" 15940 ((use-first-row-styles . t) 15941 (use-last-row-styles . t)))))) 15942 @end lisp 15943 15944 @item 15945 Associate a table with the table style. 15946 15947 To do this, specify the table style created in step (2) as part of 15948 the @samp{ATTR_ODT} line as shown below. 15949 15950 @example 15951 #+ATTR_ODT: :style TableWithHeaderRowAndColumn 15952 | Name | Phone | Age | 15953 | Peter | 1234 | 17 | 15954 | Anna | 4321 | 25 | 15955 @end example 15956 @end enumerate 15957 15958 @anchor{Validating OpenDocument XML} 15959 @subsubheading Validating OpenDocument XML 15960 15961 Sometimes ODT format files may not open due to @samp{.odt} file corruption. 15962 To verify if such a file is corrupt, validate it against the 15963 OpenDocument Relax NG Compact (RNC) syntax schema. But first the 15964 @samp{.odt} files have to be decompressed using @samp{zip}. Note that @samp{.odt} 15965 files are ZIP archives: @ref{File Archives,,,emacs,}. The contents of 15966 ODT files are in XML@. For general help with validation---and 15967 schema-sensitive editing---of XML files: @ref{Introduction,,,nxml-mode,}. 15968 15969 @vindex org-export-odt-schema-dir 15970 Customize @code{org-odt-schema-dir} to point to a directory with 15971 OpenDocument RNC files and the needed schema-locating rules. The ODT 15972 export back-end takes care of updating the 15973 @code{rng-schema-locating-files}. 15974 15975 @node Org Export 15976 @section Org Export 15977 15978 @cindex Org export 15979 @emph{org} export back-end creates a normalized version of the Org document 15980 in current buffer. The exporter evaluates Babel code (see @ref{Evaluating Code Blocks}) and removes content specific to other back-ends. 15981 15982 @anchor{Org export commands} 15983 @subheading Org export commands 15984 15985 @table @asis 15986 @item @kbd{C-c C-e O o} (@code{org-org-export-to-org}) 15987 @kindex C-c C-e O o 15988 @findex org-org-export-to-org 15989 Export as an Org file with a @samp{.org} extension. For @samp{myfile.org}, 15990 Org exports to @samp{myfile.org.org}, overwriting without warning. 15991 15992 @item @kbd{C-c C-e O v} (~~) 15993 @kindex C-c C-e O v 15994 Export to an Org file, then open it. 15995 @end table 15996 15997 @node Texinfo Export 15998 @section Texinfo Export 15999 16000 @menu 16001 * Texinfo export commands:: Invoking commands. 16002 * Texinfo specific export settings:: Setting the environment. 16003 * Texinfo file header:: Generating the header. 16004 * Texinfo title and copyright page:: Creating preamble pages. 16005 * Info directory file:: Installing a manual in Info file hierarchy. 16006 * Headings and sectioning structure:: Building document structure. 16007 * Indices:: Creating indices. 16008 * Quoting Texinfo code:: Incorporating literal Texinfo code. 16009 * Plain lists in Texinfo export:: List attributes. 16010 * Tables in Texinfo export:: Table attributes. 16011 * Images in Texinfo export:: Image attributes. 16012 * Quotations in Texinfo export:: Quote block attributes. 16013 * Key bindings in Texinfo export:: @@kbd Texinfo command. 16014 * Special blocks in Texinfo export:: Special block attributes. 16015 * A Texinfo example:: Processing Org to Texinfo. 16016 @end menu 16017 16018 @node Texinfo export commands 16019 @subsection Texinfo export commands 16020 16021 @table @asis 16022 @item @kbd{C-c C-e i t} (@code{org-texinfo-export-to-texinfo}) 16023 @kindex C-c C-e i t 16024 @findex org-texinfo-export-to-texinfo 16025 Export as a Texinfo file with @samp{.texi} extension. For @samp{myfile.org}, 16026 Org exports to @samp{myfile.texi}, overwriting without warning. 16027 16028 @item @kbd{C-c C-e i i} (@code{org-texinfo-export-to-info}) 16029 @kindex C-c C-e i i 16030 @findex org-texinfo-export-to-info 16031 @vindex org-texinfo-info-process 16032 Export to Texinfo format first and then process it to make an Info 16033 file. To generate other formats, such as DocBook, customize the 16034 @code{org-texinfo-info-process} variable. 16035 @end table 16036 16037 @node Texinfo specific export settings 16038 @subsection Texinfo specific export settings 16039 16040 The Texinfo export back-end has several additional keywords for 16041 customizing Texinfo output. Setting these keywords works similar to 16042 the general options (see @ref{Export Settings}). 16043 16044 @table @asis 16045 @item @samp{SUBTITLE} 16046 @cindex @samp{SUBTITLE}, keyword 16047 The document subtitle. 16048 16049 @item @samp{SUBAUTHOR} 16050 @cindex @samp{SUBAUTHOR}, keyword 16051 Additional authors for the document. 16052 16053 @item @samp{TEXINFO_FILENAME} 16054 @cindex @samp{TEXINFO_FILENAME}, keyword 16055 The Texinfo filename. 16056 16057 @item @samp{TEXINFO_CLASS} 16058 @cindex @samp{TEXINFO_CLASS}, keyword 16059 @vindex org-texinfo-default-class 16060 The default document class (@code{org-texinfo-default-class}), which must 16061 be a member of @code{org-texinfo-classes}. 16062 16063 @item @samp{TEXINFO_HEADER} 16064 @cindex @samp{TEXINFO_HEADER}, keyword 16065 Arbitrary lines inserted at the end of the header. 16066 16067 @item @samp{TEXINFO_POST_HEADER} 16068 @cindex @samp{TEXINFO_POST_HEADER}, keyword 16069 Arbitrary lines inserted after the end of the header. 16070 16071 @item @samp{TEXINFO_DIR_CATEGORY} 16072 @cindex @samp{TEXINFO_DIR_CATEGORY}, keyword 16073 The directory category of the document. 16074 16075 @item @samp{TEXINFO_DIR_TITLE} 16076 @cindex @samp{TEXINFO_DIR_TITLE}, keyword 16077 The directory title of the document. 16078 16079 @item @samp{TEXINFO_DIR_DESC} 16080 @cindex @samp{TEXINFO_DIR_DESC}, keyword 16081 The directory description of the document. 16082 16083 @item @samp{TEXINFO_PRINTED_TITLE} 16084 @cindex @samp{TEXINFO_PRINTED_TITLE}, keyword 16085 The printed title of the document. 16086 @end table 16087 16088 @node Texinfo file header 16089 @subsection Texinfo file header 16090 16091 @cindex @samp{TEXINFO_FILENAME}, keyword 16092 After creating the header for a Texinfo file, the Texinfo back-end 16093 automatically generates a name and destination path for the Info file. 16094 To override this default with a more sensible path and name, specify 16095 the @samp{TEXINFO_FILENAME} keyword. 16096 16097 @vindex org-texinfo-coding-system 16098 @cindex @samp{TEXINFO_HEADER}, keyword 16099 Along with the output's file name, the Texinfo header also contains 16100 language details (see @ref{Export Settings}) and encoding system as set in 16101 the @code{org-texinfo-coding-system} variable. Insert @samp{TEXINFO_HEADER} 16102 keywords for each additional command in the header, for example: 16103 16104 @example 16105 #+TEXINFO_HEADER: @@synindex 16106 @end example 16107 16108 16109 @cindex @samp{TEXINFO_CLASS}, keyword 16110 @vindex org-texinfo-classes 16111 Instead of repeatedly installing the same set of commands, define 16112 a class in @code{org-texinfo-classes} once, and then activate it in the 16113 document by setting the @samp{TEXINFO_CLASS} keyword to that class. 16114 16115 @node Texinfo title and copyright page 16116 @subsection Texinfo title and copyright page 16117 16118 @cindex @samp{TEXINFO_PRINTED_TITLE}, keyword 16119 The default template for hard copy output has a title page with 16120 @samp{TITLE} and @samp{AUTHOR} keywords (see @ref{Export Settings}). To replace the 16121 regular title with something different for the printed version, use 16122 the @samp{TEXINFO_PRINTED_TITLE} and @samp{SUBTITLE} keywords. Both expect raw 16123 Texinfo code for setting their values. 16124 16125 @cindex @samp{SUBAUTHOR}, keyword 16126 If one @samp{AUTHOR} line is not sufficient, add multiple @samp{SUBAUTHOR} 16127 keywords. They have to be set in raw Texinfo code. 16128 16129 @example 16130 #+AUTHOR: Jane Smith 16131 #+SUBAUTHOR: John Doe 16132 #+TEXINFO_PRINTED_TITLE: This Long Title@@@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@} 16133 @end example 16134 16135 @cindex @samp{COPYING}, property 16136 Copying material is defined in a dedicated headline with a non-@code{nil} 16137 @samp{COPYING} property. The back-end inserts the contents within 16138 a @samp{@@copying} command at the beginning of the document. The heading 16139 itself does not appear in the structure of the document. 16140 16141 Copyright information is printed on the back of the title page. 16142 16143 @example 16144 * Legalese 16145 :PROPERTIES: 16146 :COPYING: t 16147 :END: 16148 16149 This is a short example of a complete Texinfo file, version 1.0. 16150 16151 Copyright \copy 2016 Free Software Foundation, Inc. 16152 @end example 16153 16154 @node Info directory file 16155 @subsection Info directory file 16156 16157 @cindex @samp{dir} file, in Texinfo export 16158 @cindex Info directory file, in Texinfo export 16159 @cindex @code{install-info}, in Texinfo export 16160 16161 @cindex @samp{TEXINFO_DIR_CATEGORY}, keyword 16162 @cindex @samp{TEXINFO_DIR_TITLE}, keyword 16163 @cindex @samp{TEXINFO_DIR_DESC}, keyword 16164 The end result of the Texinfo export process is the creation of an 16165 Info file. This Info file's metadata has variables for category, 16166 title, and description: @samp{TEXINFO_DIR_CATEGORY}, @samp{TEXINFO_DIR_TITLE}, 16167 and @samp{TEXINFO_DIR_DESC} keywords that establish where in the Info 16168 hierarchy the file fits. 16169 16170 Here is an example that writes to the Info directory file: 16171 16172 @example 16173 #+TEXINFO_DIR_CATEGORY: Emacs 16174 #+TEXINFO_DIR_TITLE: Org Mode: (org) 16175 #+TEXINFO_DIR_DESC: Outline-based notes management and organizer 16176 @end example 16177 16178 @node Headings and sectioning structure 16179 @subsection Headings and sectioning structure 16180 16181 @vindex org-texinfo-classes 16182 @vindex org-texinfo-default-class 16183 @cindex @samp{TEXINFO_CLASS}, keyword 16184 The Texinfo export back-end uses a pre-defined scheme to convert Org 16185 headlines to equivalent Texinfo structuring commands. A scheme like 16186 this maps top-level headlines to numbered chapters tagged as 16187 @code{@@chapter} and lower-level headlines to unnumbered chapters tagged as 16188 @code{@@unnumbered}. To override such mappings to introduce @code{@@part} or 16189 other Texinfo structuring commands, define a new class in 16190 @code{org-texinfo-classes}. Activate the new class with the 16191 @samp{TEXINFO_CLASS} keyword. When no new class is defined and activated, 16192 the Texinfo export back-end defaults to the 16193 @code{org-texinfo-default-class}. 16194 16195 If an Org headline's level has no associated Texinfo structuring 16196 command, or is below a certain threshold (see @ref{Export Settings}), then 16197 the Texinfo export back-end makes it into a list item. 16198 16199 @cindex @samp{APPENDIX}, property 16200 The Texinfo export back-end makes any headline with a non-@code{nil} 16201 @samp{APPENDIX} property into an appendix. This happens independent of the 16202 Org headline level or the @samp{TEXINFO_CLASS} keyword. 16203 16204 @cindex @samp{ALT_TITLE}, property 16205 @cindex @samp{DESCRIPTION}, property 16206 The Texinfo export back-end creates a menu entry after the Org 16207 headline for each regular sectioning structure. To override this with 16208 a shorter menu entry, use the @samp{ALT_TITLE} property (see @ref{Table of Contents}). Texinfo menu entries also have an option for a longer 16209 @samp{DESCRIPTION} property. Here's an example that uses both to override 16210 the default menu entry: 16211 16212 @example 16213 * Controlling Screen Display 16214 :PROPERTIES: 16215 :ALT_TITLE: Display 16216 :DESCRIPTION: Controlling Screen Display 16217 :END: 16218 @end example 16219 16220 @cindex Top node, in Texinfo export 16221 The text before the first headline belongs to the @emph{Top} node, i.e., 16222 the node in which a reader enters an Info manual. As such, it is 16223 expected not to appear in printed output generated from the @samp{.texi} 16224 file. See @ref{The Top Node,,,texinfo,}, for more information. 16225 16226 @node Indices 16227 @subsection Indices 16228 16229 @cindex @samp{CINDEX}, keyword 16230 @cindex concept index, in Texinfo export 16231 @cindex @samp{FINDEX}, keyword 16232 @cindex function index, in Texinfo export 16233 @cindex @samp{KINDEX}, keyword 16234 @cindex keystroke index, in Texinfo export 16235 @cindex @samp{PINDEX}, keyword 16236 @cindex program index, in Texinfo export 16237 @cindex @samp{TINDEX}, keyword 16238 @cindex data type index, in Texinfo export 16239 @cindex @samp{VINDEX}, keyword 16240 @cindex variable index, in Texinfo export 16241 The Texinfo export back-end recognizes these indexing keywords if used 16242 in the Org file: @samp{CINDEX}, @samp{FINDEX}, @samp{KINDEX}, @samp{PINDEX}, @samp{TINDEX} and 16243 @samp{VINDEX}. Write their value as verbatim Texinfo code; in particular, 16244 @samp{@{}, @samp{@}} and @samp{@@} characters need to be escaped with @samp{@@} if they do not 16245 belong to a Texinfo command. 16246 16247 @example 16248 #+CINDEX: Defining indexing entries 16249 @end example 16250 16251 16252 @cindex @samp{INDEX}, property 16253 For the back-end to generate an index entry for a headline, set the 16254 @samp{INDEX} property to @samp{cp} or @samp{vr}. These abbreviations come from 16255 Texinfo that stand for concept index and variable index. The Texinfo 16256 manual has abbreviations for all other kinds of indexes. The back-end 16257 exports the headline as an unnumbered chapter or section command, and 16258 then inserts the index after its contents. 16259 16260 @example 16261 * Concept Index 16262 :PROPERTIES: 16263 :INDEX: cp 16264 :END: 16265 @end example 16266 16267 @node Quoting Texinfo code 16268 @subsection Quoting Texinfo code 16269 16270 Use any of the following three methods to insert or escape raw Texinfo 16271 code: 16272 16273 @cindex @samp{TEXINFO}, keyword 16274 @cindex @samp{BEGIN_EXPORT texinfo} 16275 @example 16276 Richard @@@@texinfo:@@sc@{@@@@Stallman@@@@texinfo:@}@@@@ commence' GNU. 16277 16278 #+TEXINFO: @@need800 16279 This paragraph is preceded by... 16280 16281 #+BEGIN_EXPORT texinfo 16282 @@auindex Johnson, Mark 16283 @@auindex Lakoff, George 16284 #+END_EXPORT 16285 @end example 16286 16287 @node Plain lists in Texinfo export 16288 @subsection Plain lists in Texinfo export 16289 16290 @cindex lettered lists, in Texinfo export 16291 @cindex enum, Texinfo attribute 16292 The Texinfo export back-end converts unordered and ordered lists in 16293 the Org file using the default command @samp{@@itemize}. 16294 16295 Ordered lists are numbered when exported to Texinfo format. Such 16296 numbering obeys any counter (see @ref{Plain Lists}) in the first item of 16297 the list. The @samp{:enum} attribute also let you start the list at a 16298 specific number, or switch to a lettered list, as illustrated here: 16299 16300 @example 16301 #+ATTR_TEXINFO: :enum A 16302 1. Alpha 16303 2. Bravo 16304 3. Charlie 16305 @end example 16306 16307 @cindex @samp{ATTR_TEXINFO}, keyword 16308 @cindex two-column tables, in Texinfo export 16309 @cindex table-type, Texinfo attribute 16310 The Texinfo export back-end by default converts description lists in 16311 the Org file using the default command @samp{@@table}, which results in 16312 a table with two columns. To change this behavior, set @samp{:table-type} 16313 attribute to either @samp{ftable} or @samp{vtable} value. For more information, 16314 see @ref{Two-column Tables,,,texinfo,}. 16315 16316 @vindex org-texinfo-table-default-markup 16317 @cindex indic, Texinfo attribute 16318 The Texinfo export back-end by default also applies a text highlight 16319 based on the defaults stored in @code{org-texinfo-table-default-markup}. 16320 To override the default highlight command, specify another one with 16321 the @samp{:indic} attribute. 16322 16323 @cindex multiple items in Texinfo lists 16324 @cindex sep, Texinfo attribute 16325 Org syntax is limited to one entry per list item. Nevertheless, the 16326 Texinfo export back-end can split that entry according to any text 16327 provided through the @samp{:sep} attribute. Each part then becomes a new 16328 entry in the first column of the table. 16329 16330 The following example illustrates all the attributes above: 16331 16332 @example 16333 #+ATTR_TEXINFO: :table-type vtable :sep , :indic asis 16334 - foo, bar :: This is the common text for variables foo and bar. 16335 @end example 16336 16337 @noindent 16338 becomes 16339 16340 @example 16341 @@vtable @@asis 16342 @@item foo 16343 @@itemx bar 16344 This is the common text for variables foo and bar. 16345 @@end table 16346 @end example 16347 16348 The @samp{:compact} attribute is an alternative to the @samp{:sep} attribute, 16349 which allows writing each entry on its own line. If this attribute is 16350 non-nil and an item in a description list has no body but is followed 16351 by another item, then the second item is transcoded to @samp{@@itemx}. This 16352 example is transcoded to the same output as above. 16353 16354 @example 16355 #+ATTR_TEXINFO: :table-type vtable :indic asis :compact t 16356 - foo :: 16357 - bar :: 16358 This is the common text for variables foo and bar. 16359 @end example 16360 16361 Support for this compact syntax can also be enabled for all lists in 16362 a file using the @samp{compact-itemx} export option, or globally using the 16363 variable @code{org-texinfo-compact-itemx}. 16364 16365 The Texinfo export back-end also supports two approaches to writing 16366 Texinfo definition commands (see @ref{Definition Commands,,,texinfo,}). 16367 One of them uses description lists and is described below, the other 16368 relies on special blocks (see @ref{Special blocks in Texinfo export}). 16369 16370 Items in a description list in a Org file that begin with @samp{Function:} 16371 or certain other prefixes are converted using Texinfo definition 16372 commands. This works even if other items in the same list do not have 16373 such a prefix; if necessary a single description list is converted 16374 using multiple tables (such as @samp{@@vtable}) and definition commands 16375 (such as @samp{@@defun}). 16376 16377 @example 16378 - Function: org-texinfo-drawer drawer contents info :: 16379 Transcode a DRAWER element from Org to Texinfo. 16380 @end example 16381 16382 @noindent 16383 becomes 16384 16385 @example 16386 @@defun org-texinfo-drawer drawer contents info :: 16387 Transcode a DRAWER element from Org to Texinfo. 16388 @@end defun 16389 @end example 16390 16391 The recognized prefixes are @samp{Command:}, @samp{Function:}, @samp{Macro:}, 16392 @samp{Special Form:}, @samp{Variable:} and @samp{User Option:}. These are the same 16393 prefixes that appear in the Info file for the respective definition 16394 commands. For example a @samp{Function:} item in the Org file is converted 16395 to a @samp{@@defun} command in the Texinfo file, which in turn is converted 16396 to a definition prefixed with @samp{-- Function:} in the Info file. 16397 16398 As a special case the prefix @samp{Key:} is also recognized. No Texinfo 16399 definition command exists for key bindings and the output in Info 16400 files also lacks the @samp{Key:} prefix. Even so this special case is 16401 supported because it provides a convenient shorthand, as illustrated 16402 here: 16403 16404 @example 16405 - Key: C-c C-c (do-something) :: 16406 This command does something. 16407 16408 - User Option: do-something-somehow :: 16409 This option controls how exactly ~do-something~ does its thing. 16410 @end example 16411 16412 @noindent 16413 becomes 16414 16415 @example 16416 @@table @@asis 16417 @@item @@kbd@{C-c C-c@} (@@code@{do-something@}) 16418 @@kindex C-c C-c 16419 @@findex do-something 16420 This command does something. 16421 @@end table 16422 16423 @@defopt do-something-somehow 16424 This option controls how exactly @@code@{do-something@} does its thing. 16425 @@end defopt 16426 @end example 16427 16428 @noindent 16429 Command in parenthesis, as done above, is optional. 16430 16431 @node Tables in Texinfo export 16432 @subsection Tables in Texinfo export 16433 16434 @cindex @samp{ATTR_TEXINFO}, keyword 16435 When exporting tables, the Texinfo export back-end uses the widest 16436 cell width in each column. To override this and instead specify as 16437 fractions of line length, use the @samp{:columns} attribute. See example 16438 below. 16439 16440 @example 16441 #+ATTR_TEXINFO: :columns .5 .5 16442 | a cell | another cell | 16443 @end example 16444 16445 @node Images in Texinfo export 16446 @subsection Images in Texinfo export 16447 16448 @cindex @samp{ATTR_TEXINFO}, keyword 16449 Insert a file link to the image in the Org file, and the Texinfo 16450 export back-end inserts the image. These links must have the usual 16451 supported image extensions and no descriptions. To scale the image, 16452 use @samp{:width} and @samp{:height} attributes. For alternate text, use @samp{:alt} 16453 and specify the text using Texinfo code, as shown in the example: 16454 16455 @example 16456 #+ATTR_TEXINFO: :width 1in :alt Alternate @@i@{text@} 16457 [[ridt.pdf]] 16458 @end example 16459 16460 @node Quotations in Texinfo export 16461 @subsection Quotations in Texinfo export 16462 16463 @cindex @samp{ATTR_TEXINFO}, keyword 16464 You can write the text of a quotation within a quote block (see 16465 @ref{Paragraphs}). You may also emphasize some text at the beginning of 16466 the quotation with the @samp{:tag} attribute. 16467 16468 @example 16469 #+ATTR_TEXINFO: :tag Warning 16470 #+BEGIN_QUOTE 16471 Striking your thumb with a hammer may cause severe pain and discomfort. 16472 #+END_QUOTE 16473 @end example 16474 16475 To specify the author of the quotation, use the @samp{:author} attribute. 16476 16477 @example 16478 #+ATTR_TEXINFO: :author King Arthur 16479 #+BEGIN_QUOTE 16480 The Lady of the Lake, her arm clad in the purest shimmering samite, 16481 held aloft Excalibur from the bosom of the water, signifying by divine 16482 providence that I, Arthur, was to carry Excalibur. That is why I am 16483 your king. 16484 #+END_QUOTE 16485 @end example 16486 16487 @node Key bindings in Texinfo export 16488 @subsection Key bindings in Texinfo export 16489 16490 Org does not provide any markup for key bindings that corresponds to 16491 Texinfo's @code{@@kbd} and @code{@@key} commands. One way to deal with this is to 16492 fall back to code syntax. @samp{~C-x SPC~}, for example, is transcoded to 16493 @code{@@code@{C-x SPC@}}. 16494 16495 A better approach is to define and use an Org macro named @code{kbd}. To 16496 make that easier the function @code{org-texinfo-kbd-macro} is provided, 16497 which is intended to be used like this: 16498 16499 @example 16500 #+macro: kbd (eval (org-texinfo-kbd-macro $1)) 16501 16502 Type @{@{@{kbd(C-c SPC)@}@}@}. 16503 @end example 16504 16505 @noindent 16506 which becomes 16507 16508 @example 16509 Type @@kbd@{C-c @@key@{SPC@}@}. 16510 @end example 16511 16512 @node Special blocks in Texinfo export 16513 @subsection Special blocks in Texinfo export 16514 16515 The Texinfo export back-end supports two approaches to writing Texinfo 16516 definition commands. One of them is described here, the other in 16517 @ref{Plain lists in Texinfo export}. 16518 16519 @cindex @samp{ATTR_TEXINFO}, keyword 16520 16521 The Texinfo export back-end converts special blocks to commands with 16522 the same name. It also adds any @samp{:options} attributes to the end of 16523 the command, as shown in this example: 16524 16525 @example 16526 #+ATTR_TEXINFO: :options org-org-export-to-org ... 16527 #+BEGIN_defun 16528 A somewhat obsessive function name. 16529 #+END_defun 16530 @end example 16531 16532 @noindent 16533 becomes 16534 16535 @example 16536 @@defun org-org-export-to-org ... 16537 A somewhat obsessive function name. 16538 @@end defun 16539 @end example 16540 16541 @node A Texinfo example 16542 @subsection A Texinfo example 16543 16544 Here is a more detailed example Org file. See 16545 @ref{GNU Sample Texts,,,texinfo,} for an equivalent example using 16546 Texinfo code. 16547 16548 @example 16549 #+TITLE: GNU Sample @{@{@{version@}@}@} 16550 #+SUBTITLE: for version @{@{@{version@}@}@}, @{@{@{updated@}@}@} 16551 #+AUTHOR: A.U. Thor 16552 #+EMAIL: bug-sample@@gnu.org 16553 16554 #+OPTIONS: ':t toc:t author:t email:t 16555 #+LANGUAGE: en 16556 16557 #+MACRO: version 2.0 16558 #+MACRO: updated last updated 4 March 2014 16559 16560 #+TEXINFO_FILENAME: sample.info 16561 #+TEXINFO_HEADER: @@syncodeindex pg cp 16562 16563 #+TEXINFO_DIR_CATEGORY: Texinfo documentation system 16564 #+TEXINFO_DIR_TITLE: sample: (sample) 16565 #+TEXINFO_DIR_DESC: Invoking sample 16566 16567 #+TEXINFO_PRINTED_TITLE: GNU Sample 16568 16569 This manual is for GNU Sample (version @{@{@{version@}@}@}, 16570 @{@{@{updated@}@}@}). 16571 16572 * Copying 16573 :PROPERTIES: 16574 :COPYING: t 16575 :END: 16576 16577 This manual is for GNU Sample (version @{@{@{version@}@}@}, 16578 @{@{@{updated@}@}@}), which is an example in the Texinfo documentation. 16579 16580 Copyright \copy 2016 Free Software Foundation, Inc. 16581 16582 #+BEGIN_QUOTE 16583 Permission is granted to copy, distribute and/or modify this 16584 document under the terms of the GNU Free Documentation License, 16585 Version 1.3 or any later version published by the Free Software 16586 Foundation; with no Invariant Sections, with no Front-Cover Texts, 16587 and with no Back-Cover Texts. A copy of the license is included in 16588 the section entitled "GNU Free Documentation License". 16589 #+END_QUOTE 16590 16591 * Invoking sample 16592 16593 #+PINDEX: sample 16594 #+CINDEX: invoking @@command@{sample@} 16595 16596 This is a sample manual. There is no sample program to invoke, but 16597 if there were, you could see its basic usage and command line 16598 options here. 16599 16600 * GNU Free Documentation License 16601 :PROPERTIES: 16602 :APPENDIX: t 16603 :END: 16604 16605 #+INCLUDE: fdl.org 16606 16607 * Index 16608 :PROPERTIES: 16609 :INDEX: cp 16610 :END: 16611 @end example 16612 16613 @node iCalendar Export 16614 @section iCalendar Export 16615 16616 @cindex iCalendar export 16617 16618 A large part of Org mode's interoperability success is its ability to 16619 easily export to or import from external applications. The iCalendar 16620 export back-end takes calendar data from Org files and exports to the 16621 standard iCalendar format. 16622 16623 @vindex org-icalendar-include-todo 16624 @vindex org-icalendar-use-deadline 16625 @vindex org-icalendar-use-scheduled 16626 The iCalendar export back-end can also incorporate TODO entries based 16627 on the configuration of the @code{org-icalendar-include-todo} variable. 16628 The back-end exports plain timestamps as @samp{VEVENT}, TODO items as 16629 @samp{VTODO}, and also create events from deadlines that are in non-TODO 16630 items. The back-end uses the deadlines and scheduling dates in Org 16631 TODO items for setting the start and due dates for the iCalendar TODO 16632 entry. Consult the @code{org-icalendar-use-deadline} and 16633 @code{org-icalendar-use-scheduled} variables for more details. 16634 16635 @vindex org-icalendar-categories 16636 @vindex org-icalendar-alarm-time 16637 For tags on the headline, the iCalendar export back-end makes them 16638 into iCalendar categories. To tweak the inheritance of tags and TODO 16639 states, configure the variable @code{org-icalendar-categories}. To assign 16640 clock alarms based on time, configure the @code{org-icalendar-alarm-time} 16641 variable. 16642 16643 @vindex org-icalendar-store-UID 16644 @cindex @samp{ID}, property 16645 The iCalendar format standard requires globally unique identifier---or 16646 UID---for each entry. The iCalendar export back-end creates UIDs 16647 during export. To save a copy of the UID in the Org file set the 16648 variable @code{org-icalendar-store-UID}. The back-end looks for the @samp{ID} 16649 property of the entry for re-using the same UID for subsequent 16650 exports. 16651 16652 Since a single Org entry can result in multiple iCalendar 16653 entries---timestamp, deadline, scheduled item, or TODO item---Org adds 16654 prefixes to the UID, depending on which part of the Org entry 16655 triggered the creation of the iCalendar entry. Prefixing ensures UIDs 16656 remains unique, yet enable synchronization programs trace the 16657 connections. 16658 16659 @table @asis 16660 @item @kbd{C-c C-e c f} (@code{org-icalendar-export-to-ics}) 16661 @kindex C-c C-e c f 16662 @findex org-icalendar-export-to-ics 16663 Create iCalendar entries from the current Org buffer and store them 16664 in the same directory, using a file extension @samp{.ics}. 16665 16666 @item @kbd{C-c C-e c a} (@code{org-icalendar-export-agenda-files}) 16667 @kindex C-c C-e c a 16668 @findex org-icalendar-export-agenda-files 16669 Create iCalendar entries from Org files in @code{org-agenda-files} and 16670 store in a separate iCalendar file for each Org file. 16671 16672 @item @kbd{C-c C-e c c} (@code{org-icalendar-combine-agenda-files}) 16673 @kindex C-c C-e c c 16674 @findex org-icalendar-combine-agenda-files 16675 @vindex org-icalendar-combined-agenda-file 16676 Create a combined iCalendar file from Org files in 16677 @code{org-agenda-files} and write it to 16678 @code{org-icalendar-combined-agenda-file} file name. 16679 @end table 16680 16681 @cindex @samp{SUMMARY}, property 16682 @cindex @samp{DESCRIPTION}, property 16683 @cindex @samp{LOCATION}, property 16684 @cindex @samp{TIMEZONE}, property 16685 @cindex @samp{CLASS}, property 16686 The iCalendar export back-end includes @samp{SUMMARY}, @samp{DESCRIPTION}, 16687 @samp{LOCATION}, @samp{TIMEZONE} and @samp{CLASS} properties from the Org entries 16688 when exporting. To force the back-end to inherit the @samp{LOCATION}, 16689 @samp{TIMEZONE} and @samp{CLASS} properties, configure the 16690 @code{org-use-property-inheritance} variable. 16691 16692 @vindex org-icalendar-include-body 16693 When Org entries do not have @samp{SUMMARY}, @samp{DESCRIPTION}, @samp{LOCATION} and 16694 @samp{CLASS} properties, the iCalendar export back-end derives the summary 16695 from the headline, and derives the description from the body of the 16696 Org item. The @code{org-icalendar-include-body} variable limits the 16697 maximum number of characters of the content are turned into its 16698 description. 16699 16700 The @samp{TIMEZONE} property can be used to specify a per-entry time zone, 16701 and is applied to any entry with timestamp information. Time zones 16702 should be specified as per the IANA time zone database format, e.g., 16703 @samp{Asia/Almaty}. Alternately, the property value can be @samp{UTC}, to force 16704 UTC time for this entry only. 16705 16706 The @samp{CLASS} property can be used to specify a per-entry visibility 16707 class or access restrictions, and is applied to any entry with class 16708 information. The iCalendar standard defines three visibility classes: 16709 @table @asis 16710 @item @samp{PUBLIC} 16711 The entry is publicly visible (this is the default). 16712 @item @samp{CONFIDENTIAL} 16713 Only a limited group of clients get access to the 16714 event. 16715 @item @samp{PRIVATE} 16716 The entry can be retrieved only by its owner. 16717 @end table 16718 The server should treat unknown class properties the same as 16719 @samp{PRIVATE}. 16720 16721 Exporting to iCalendar format depends in large part on the 16722 capabilities of the destination application. Some are more lenient 16723 than others. Consult the Org mode FAQ for advice on specific 16724 applications. 16725 16726 @node Other Built-in Back-ends 16727 @section Other Built-in Back-ends 16728 16729 Other export back-ends included with Org are: 16730 16731 @itemize 16732 @item 16733 @samp{ox-man.el}: Export to a man page. 16734 @end itemize 16735 16736 To activate such back-ends, either customize @code{org-export-backends} or 16737 load directly with @samp{(require 'ox-man)}. On successful load, the 16738 back-end adds new keys in the export dispatcher (see @ref{The Export Dispatcher}). 16739 16740 Follow the comment section of such files, for example, @samp{ox-man.el}, 16741 for usage and configuration details. 16742 16743 @node Advanced Export Configuration 16744 @section Advanced Export Configuration 16745 16746 16747 16748 @anchor{Export hooks} 16749 @subheading Export hooks 16750 16751 @vindex org-export-before-processing-hook 16752 @vindex org-export-before-parsing-hook 16753 The export process executes two hooks before the actual exporting 16754 begins. The first hook, @code{org-export-before-processing-hook}, runs 16755 before any expansions of macros, Babel code, and include keywords in 16756 the buffer. The second hook, @code{org-export-before-parsing-hook}, runs 16757 before the buffer is parsed. 16758 16759 Functions added to these hooks are called with a single argument: the 16760 export back-end actually used, as a symbol. You may use them for 16761 heavy duty structural modifications of the document. For example, you 16762 can remove every headline in the buffer during export like this: 16763 16764 @lisp 16765 (defun my-headline-removal (backend) 16766 "Remove all headlines in the current buffer. 16767 BACKEND is the export back-end being used, as a symbol." 16768 (org-map-entries 16769 (lambda () (delete-region (point) (line-beginning-position 2))))) 16770 16771 (add-hook 'org-export-before-parsing-hook #'my-headline-removal) 16772 @end lisp 16773 16774 @anchor{Filters} 16775 @subheading Filters 16776 16777 @cindex Filters, exporting 16778 Filters are lists of functions to be applied to certain parts for 16779 a given back-end. The output from the first function in the filter is 16780 passed on to the next function in the filter. The final output is the 16781 output from the final function in the filter. 16782 16783 The Org export process has many filter sets applicable to different 16784 types of objects, plain text, parse trees, export options, and final 16785 output formats. The filters are named after the element type or 16786 object type: @code{org-export-filter-TYPE-functions}, where @var{TYPE} 16787 is the type targeted by the filter. Valid types are: 16788 16789 @multitable @columnfractions 0.33 0.33 0.33 16790 @item body 16791 @tab bold 16792 @tab babel-call 16793 @item center-block 16794 @tab clock 16795 @tab code 16796 @item diary-sexp 16797 @tab drawer 16798 @tab dynamic-block 16799 @item entity 16800 @tab example-block 16801 @tab export-block 16802 @item export-snippet 16803 @tab final-output 16804 @tab fixed-width 16805 @item footnote-definition 16806 @tab footnote-reference 16807 @tab headline 16808 @item horizontal-rule 16809 @tab inline-babel-call 16810 @tab inline-src-block 16811 @item inlinetask 16812 @tab italic 16813 @tab item 16814 @item keyword 16815 @tab latex-environment 16816 @tab latex-fragment 16817 @item line-break 16818 @tab link 16819 @tab node-property 16820 @item options 16821 @tab paragraph 16822 @tab parse-tree 16823 @item plain-list 16824 @tab plain-text 16825 @tab planning 16826 @item property-drawer 16827 @tab quote-block 16828 @tab radio-target 16829 @item section 16830 @tab special-block 16831 @tab src-block 16832 @item statistics-cookie 16833 @tab strike-through 16834 @tab subscript 16835 @item superscript 16836 @tab table 16837 @tab table-cell 16838 @item table-row 16839 @tab target 16840 @tab timestamp 16841 @item underline 16842 @tab verbatim 16843 @tab verse-block 16844 @end multitable 16845 16846 Here is an example filter that replaces non-breaking spaces @code{ } in the 16847 Org buffer with @samp{~} for the @LaTeX{} back-end. 16848 16849 @lisp 16850 (defun my-latex-filter-nobreaks (text backend info) 16851 "Ensure \" \" are properly handled in LaTeX export." 16852 (when (org-export-derived-backend-p backend 'latex) 16853 (replace-regexp-in-string " " "~" text))) 16854 16855 (add-to-list 'org-export-filter-plain-text-functions 16856 'my-latex-filter-nobreaks) 16857 @end lisp 16858 16859 A filter requires three arguments: the code to be transformed, the 16860 name of the back-end, and some optional information about the export 16861 process. The third argument can be safely ignored. Note the use of 16862 @code{org-export-derived-backend-p} predicate that tests for @emph{latex} 16863 back-end or any other back-end, such as @emph{beamer}, derived from 16864 @emph{latex}. 16865 16866 @anchor{Defining filters for individual files} 16867 @subheading Defining filters for individual files 16868 16869 The Org export can filter not just for back-ends, but also for 16870 specific files through the @samp{BIND} keyword. Here is an example with 16871 two filters; one removes brackets from time stamps, and the other 16872 removes strike-through text. The filter functions are defined in 16873 a code block in the same Org file, which is a handy location for 16874 debugging. 16875 16876 @example 16877 #+BIND: org-export-filter-timestamp-functions (tmp-f-timestamp) 16878 #+BIND: org-export-filter-strike-through-functions (tmp-f-strike-through) 16879 #+BEGIN_SRC emacs-lisp :exports results :results none 16880 (defun tmp-f-timestamp (s backend info) 16881 (replace-regexp-in-string "&[lg]t;\\|[][]" "" s)) 16882 (defun tmp-f-strike-through (s backend info) "") 16883 #+END_SRC 16884 @end example 16885 16886 @anchor{Extending an existing back-end} 16887 @subheading Extending an existing back-end 16888 16889 Some parts of the conversion process can be extended for certain 16890 elements so as to introduce a new or revised translation. That is how 16891 the HTML export back-end was extended to handle Markdown format. The 16892 extensions work seamlessly so any aspect of filtering not done by the 16893 extended back-end is handled by the original back-end. Of all the 16894 export customization in Org, extending is very powerful as it operates 16895 at the parser level. 16896 16897 For this example, make the @emph{ascii} back-end display the language used 16898 in a source code block. Also make it display only when some attribute 16899 is non-@code{nil}, like the following: 16900 16901 @example 16902 #+ATTR_ASCII: :language t 16903 @end example 16904 16905 16906 Then extend ASCII back-end with a custom ``my-ascii'' back-end. 16907 16908 @lisp 16909 (defun my-ascii-src-block (src-block contents info) 16910 "Transcode a SRC-BLOCK element from Org to ASCII. 16911 CONTENTS is nil. INFO is a plist used as a communication 16912 channel." 16913 (if (not (org-export-read-attribute :attr_ascii src-block :language)) 16914 (org-export-with-backend 'ascii src-block contents info) 16915 (concat 16916 (format ",--[ %s ]--\n%s`----" 16917 (org-element-property :language src-block) 16918 (replace-regexp-in-string 16919 "^" "| " 16920 (org-element-normalize-string 16921 (org-export-format-code-default src-block info))))))) 16922 16923 (org-export-define-derived-backend 'my-ascii 'ascii 16924 :translate-alist '((src-block . my-ascii-src-block))) 16925 @end lisp 16926 16927 The @code{my-ascii-src-block} function looks at the attribute above the 16928 current element. If not true, hands over to @emph{ascii} back-end. If 16929 true, which it is in this example, it creates a box around the code 16930 and leaves room for the inserting a string for language. The last 16931 form creates the new back-end that springs to action only when 16932 translating @code{src-block} type elements. 16933 16934 To use the newly defined back-end, evaluate the following from an Org 16935 buffer: 16936 16937 @lisp 16938 (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*") 16939 @end lisp 16940 16941 Further steps to consider would be an interactive function, 16942 self-installing an item in the export dispatcher menu, and other 16943 user-friendly improvements. 16944 16945 @node Export in Foreign Buffers 16946 @section Export in Foreign Buffers 16947 16948 The export back-ends in Org often include commands to convert selected 16949 regions. A convenient feature of this in-place conversion is that the 16950 exported output replaces the original source. Here are such 16951 functions: 16952 16953 @table @asis 16954 @item @code{org-ascii-convert-region-to-ascii} 16955 @findex org-ascii-convert-region-to-ascii 16956 Convert the selected region into ASCII@. 16957 16958 @item @code{org-ascii-convert-region-to-utf8} 16959 @findex org-ascii-convert-region-to-utf8 16960 Convert the selected region into UTF-8. 16961 16962 @item @code{org-html-convert-region-to-html} 16963 @findex org-html-convert-region-to-html 16964 Convert the selected region into HTML@. 16965 16966 @item @code{org-latex-convert-region-to-latex} 16967 @findex org-latex-convert-region-to-latex 16968 Convert the selected region into @LaTeX{}. 16969 16970 @item @code{org-texinfo-convert-region-to-texinfo} 16971 @findex org-texinfo-convert-region-to-texinfo 16972 Convert the selected region into Texinfo. 16973 16974 @item @code{org-md-convert-region-to-md} 16975 @findex org-md-convert-region-to-md 16976 Convert the selected region into Markdown. 16977 @end table 16978 16979 In-place conversions are particularly handy for quick conversion of 16980 tables and lists in foreign buffers. For example, in an HTML buffer, 16981 write a list in Org syntax, select it, and convert it to HTML with 16982 @kbd{M-x org-html-convert-region-to-html}. 16983 16984 @menu 16985 * Bare HTML:: Exporting HTML without CSS, Javascript, etc. 16986 @end menu 16987 16988 @node Bare HTML 16989 @subsection Exporting to minimal HTML 16990 16991 If you want to output a minimal HTML file, with no CSS, no Javascript, 16992 no preamble or postamble, here are the variable you would need to set: 16993 16994 @vindex org-html-head 16995 @vindex org-html-head-extra 16996 @vindex org-html-head-include-default-style 16997 @vindex org-html-head-include-scripts 16998 @vindex org-html-preamble 16999 @vindex org-html-postamble 17000 @vindex org-html-use-infojs 17001 @lisp 17002 (setq org-html-head "" 17003 org-html-head-extra "" 17004 org-html-head-include-default-style nil 17005 org-html-head-include-scripts nil 17006 org-html-preamble nil 17007 org-html-postamble nil 17008 org-html-use-infojs nil) 17009 @end lisp 17010 17011 @node Publishing 17012 @chapter Publishing 17013 17014 @cindex publishing 17015 17016 Org includes a publishing management system that allows you to 17017 configure automatic HTML conversion of @emph{projects} composed of 17018 interlinked Org files. You can also configure Org to automatically 17019 upload your exported HTML pages and related attachments, such as 17020 images and source code files, to a web server. 17021 17022 You can also use Org to convert files into PDF, or even combine HTML 17023 and PDF conversion so that files are available in both formats on the 17024 server. 17025 17026 Publishing has been contributed to Org by David O'Toole. 17027 17028 @menu 17029 * Configuration:: Defining projects. 17030 * Uploading Files:: How to get files up on the server. 17031 * Sample Configuration:: Example projects. 17032 * Triggering Publication:: Publication commands. 17033 @end menu 17034 17035 @node Configuration 17036 @section Configuration 17037 17038 Publishing needs significant configuration to specify files, 17039 destination and many other properties of a project. 17040 17041 @menu 17042 * Project alist:: The central configuration variable. 17043 * Sources and destinations:: From here to there. 17044 * Selecting files:: What files are part of the project? 17045 * Publishing action:: Setting the function doing the publishing. 17046 * Publishing options:: Tweaking HTML/@LaTeX{} export. 17047 * Publishing links:: Which links keep working after publishing? 17048 * Site map:: Generating a list of all pages. 17049 * Generating an index:: An index that reaches across pages. 17050 @end menu 17051 17052 @node Project alist 17053 @subsection The variable @code{org-publish-project-alist} 17054 17055 @cindex projects, for publishing 17056 17057 @vindex org-publish-project-alist 17058 Publishing is configured almost entirely through setting the value of 17059 one variable, called @code{org-publish-project-alist}. Each element of the 17060 list configures one project, and may be in one of the two following 17061 forms: 17062 17063 @lisp 17064 ("project-name" :property value :property value ...) 17065 @end lisp 17066 17067 @noindent 17068 i.e., a well-formed property list with alternating keys and values, 17069 or: 17070 17071 @lisp 17072 ("project-name" :components ("project-name" "project-name" ...)) 17073 @end lisp 17074 17075 In both cases, projects are configured by specifying property values. 17076 A project defines the set of files that are to be published, as well 17077 as the publishing configuration to use when publishing those files. 17078 When a project takes the second form listed above, the individual 17079 members of the @code{:components} property are taken to be sub-projects, 17080 which group together files requiring different publishing options. 17081 When you publish such a ``meta-project'', all the components are also 17082 published, in the sequence given. 17083 17084 @node Sources and destinations 17085 @subsection Sources and destinations for files 17086 17087 @cindex directories, for publishing 17088 17089 Most properties are optional, but some should always be set. In 17090 particular, Org needs to know where to look for source files, and 17091 where to put published files. 17092 17093 @table @asis 17094 @item @code{:base-directory} 17095 Directory containing publishing source files. 17096 17097 @item @code{:publishing-directory} 17098 Directory where output files are published. You can directly 17099 publish to a webserver using a file name syntax appropriate for the 17100 Emacs tramp package. Or you can publish to a local directory and 17101 use external tools to upload your website (see @ref{Uploading Files}). 17102 17103 @item @code{:preparation-function} 17104 Function or list of functions to be called before starting the 17105 publishing process, for example, to run @samp{make} for updating files to 17106 be published. Each preparation function is called with a single 17107 argument, the project property list. 17108 17109 @item @code{:completion-function} 17110 Function or list of functions called after finishing the publishing 17111 process, for example, to change permissions of the resulting files. 17112 Each completion function is called with a single argument, the 17113 project property list. 17114 @end table 17115 17116 @node Selecting files 17117 @subsection Selecting files 17118 17119 @cindex files, selecting for publishing 17120 17121 By default, all files with extension @samp{.org} in the base directory are 17122 considered part of the project. This can be modified by setting the 17123 following properties 17124 17125 @table @asis 17126 @item @code{:base-extension} 17127 Extension---without the dot---of source files. This actually is 17128 a regular expression. Set this to the symbol @code{any} if you want to 17129 get all files in @code{:base-directory}, even without extension. 17130 17131 @item @code{:exclude} 17132 Regular expression to match file names that should not be published, 17133 even though they have been selected on the basis of their extension. 17134 17135 @item @code{:include} 17136 List of files to be included regardless of @code{:base-extension} and 17137 @code{:exclude}. 17138 17139 @item @code{:recursive} 17140 Non-@code{nil} means, check base-directory recursively for files to 17141 publish. 17142 @end table 17143 17144 @node Publishing action 17145 @subsection Publishing action 17146 17147 @cindex action, for publishing 17148 17149 Publishing means that a file is copied to the destination directory 17150 and possibly transformed in the process. The default transformation 17151 is to export Org files as HTML files, and this is done by the function 17152 @code{org-html-publish-to-html} which calls the HTML exporter (see @ref{HTML Export}). But you can also publish your content as PDF files using 17153 @code{org-latex-publish-to-pdf}, or as ASCII, Texinfo, etc., using the 17154 corresponding functions. 17155 17156 If you want to publish the Org file as an @samp{.org} file but with 17157 @emph{archived}, @emph{commented}, and @emph{tag-excluded} trees removed, use 17158 @code{org-org-publish-to-org}. This produces @samp{file.org} and puts it in the 17159 publishing directory. If you want a htmlized version of this file, 17160 set the parameter @code{:htmlized-source} to @code{t}. It produces 17161 @samp{file.org.html} in the publishing directory@footnote{ If the publishing 17162 directory is the same as the source directory, @samp{file.org} is exported 17163 as @samp{file.org.org}, so you probably do not want to do this.}. 17164 17165 Other files like images only need to be copied to the publishing 17166 destination; for this you can use @code{org-publish-attachment}. For 17167 non-Org files, you always need to specify the publishing function: 17168 17169 @table @asis 17170 @item @code{:publishing-function} 17171 Function executing the publication of a file. This may also be 17172 a list of functions, which are all called in turn. 17173 17174 @item @code{:htmlized-source} 17175 Non-@code{nil} means, publish htmlized source. 17176 @end table 17177 17178 The function must accept three arguments: a property list containing 17179 at least a @code{:publishing-directory} property, the name of the file to 17180 be published, and the path to the publishing directory of the output 17181 file. It should take the specified file, make the necessary 17182 transformation, if any, and place the result into the destination 17183 folder. 17184 17185 @node Publishing options 17186 @subsection Options for the exporters 17187 17188 @cindex options, for publishing 17189 @cindex publishing options 17190 17191 The property list can be used to set many export options for the HTML 17192 and @LaTeX{} exporters. In most cases, these properties correspond to 17193 user variables in Org. The table below lists these properties along 17194 with the variable they belong to. See the documentation string for 17195 the respective variable for details. 17196 17197 @vindex org-publish-project-alist 17198 When a property is given a value in @code{org-publish-project-alist}, its 17199 setting overrides the value of the corresponding user variable, if 17200 any, during publishing. Options set within a file (see @ref{Export Settings}), however, override everything. 17201 17202 @anchor{Generic properties} 17203 @subsubheading Generic properties 17204 17205 @multitable {aaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 17206 @item @code{:archived-trees} 17207 @tab @code{org-export-with-archived-trees} 17208 @item @code{:exclude-tags} 17209 @tab @code{org-export-exclude-tags} 17210 @item @code{:headline-levels} 17211 @tab @code{org-export-headline-levels} 17212 @item @code{:language} 17213 @tab @code{org-export-default-language} 17214 @item @code{:preserve-breaks} 17215 @tab @code{org-export-preserve-breaks} 17216 @item @code{:section-numbers} 17217 @tab @code{org-export-with-section-numbers} 17218 @item @code{:select-tags} 17219 @tab @code{org-export-select-tags} 17220 @item @code{:with-author} 17221 @tab @code{org-export-with-author} 17222 @item @code{:with-broken-links} 17223 @tab @code{org-export-with-broken-links} 17224 @item @code{:with-clocks} 17225 @tab @code{org-export-with-clocks} 17226 @item @code{:with-creator} 17227 @tab @code{org-export-with-creator} 17228 @item @code{:with-date} 17229 @tab @code{org-export-with-date} 17230 @item @code{:with-drawers} 17231 @tab @code{org-export-with-drawers} 17232 @item @code{:with-email} 17233 @tab @code{org-export-with-email} 17234 @item @code{:with-emphasize} 17235 @tab @code{org-export-with-emphasize} 17236 @item @code{:with-fixed-width} 17237 @tab @code{org-export-with-fixed-width} 17238 @item @code{:with-footnotes} 17239 @tab @code{org-export-with-footnotes} 17240 @item @code{:with-latex} 17241 @tab @code{org-export-with-latex} 17242 @item @code{:with-planning} 17243 @tab @code{org-export-with-planning} 17244 @item @code{:with-priority} 17245 @tab @code{org-export-with-priority} 17246 @item @code{:with-properties} 17247 @tab @code{org-export-with-properties} 17248 @item @code{:with-special-strings} 17249 @tab @code{org-export-with-special-strings} 17250 @item @code{:with-sub-superscript} 17251 @tab @code{org-export-with-sub-superscripts} 17252 @item @code{:with-tables} 17253 @tab @code{org-export-with-tables} 17254 @item @code{:with-tags} 17255 @tab @code{org-export-with-tags} 17256 @item @code{:with-tasks} 17257 @tab @code{org-export-with-tasks} 17258 @item @code{:with-timestamps} 17259 @tab @code{org-export-with-timestamps} 17260 @item @code{:with-title} 17261 @tab @code{org-export-with-title} 17262 @item @code{:with-toc} 17263 @tab @code{org-export-with-toc} 17264 @item @code{:with-todo-keywords} 17265 @tab @code{org-export-with-todo-keywords} 17266 @end multitable 17267 17268 @anchor{ASCII specific properties} 17269 @subsubheading ASCII specific properties 17270 17271 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 17272 @item @code{:ascii-bullets} 17273 @tab @code{org-ascii-bullets} 17274 @item @code{:ascii-caption-above} 17275 @tab @code{org-ascii-caption-above} 17276 @item @code{:ascii-charset} 17277 @tab @code{org-ascii-charset} 17278 @item @code{:ascii-global-margin} 17279 @tab @code{org-ascii-global-margin} 17280 @item @code{:ascii-format-drawer-function} 17281 @tab @code{org-ascii-format-drawer-function} 17282 @item @code{:ascii-format-inlinetask-function} 17283 @tab @code{org-ascii-format-inlinetask-function} 17284 @item @code{:ascii-headline-spacing} 17285 @tab @code{org-ascii-headline-spacing} 17286 @item @code{:ascii-indented-line-width} 17287 @tab @code{org-ascii-indented-line-width} 17288 @item @code{:ascii-inlinetask-width} 17289 @tab @code{org-ascii-inlinetask-width} 17290 @item @code{:ascii-inner-margin} 17291 @tab @code{org-ascii-inner-margin} 17292 @item @code{:ascii-links-to-notes} 17293 @tab @code{org-ascii-links-to-notes} 17294 @item @code{:ascii-list-margin} 17295 @tab @code{org-ascii-list-margin} 17296 @item @code{:ascii-paragraph-spacing} 17297 @tab @code{org-ascii-paragraph-spacing} 17298 @item @code{:ascii-quote-margin} 17299 @tab @code{org-ascii-quote-margin} 17300 @item @code{:ascii-table-keep-all-vertical-lines} 17301 @tab @code{org-ascii-table-keep-all-vertical-lines} 17302 @item @code{:ascii-table-use-ascii-art} 17303 @tab @code{org-ascii-table-use-ascii-art} 17304 @item @code{:ascii-table-widen-columns} 17305 @tab @code{org-ascii-table-widen-columns} 17306 @item @code{:ascii-text-width} 17307 @tab @code{org-ascii-text-width} 17308 @item @code{:ascii-underline} 17309 @tab @code{org-ascii-underline} 17310 @item @code{:ascii-verbatim-format} 17311 @tab @code{org-ascii-verbatim-format} 17312 @end multitable 17313 17314 @anchor{Beamer specific properties} 17315 @subsubheading Beamer specific properties 17316 17317 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 17318 @item @code{:beamer-theme} 17319 @tab @code{org-beamer-theme} 17320 @item @code{:beamer-column-view-format} 17321 @tab @code{org-beamer-column-view-format} 17322 @item @code{:beamer-environments-extra} 17323 @tab @code{org-beamer-environments-extra} 17324 @item @code{:beamer-frame-default-options} 17325 @tab @code{org-beamer-frame-default-options} 17326 @item @code{:beamer-outline-frame-options} 17327 @tab @code{org-beamer-outline-frame-options} 17328 @item @code{:beamer-outline-frame-title} 17329 @tab @code{org-beamer-outline-frame-title} 17330 @item @code{:beamer-subtitle-format} 17331 @tab @code{org-beamer-subtitle-format} 17332 @end multitable 17333 17334 @anchor{HTML specific properties} 17335 @subsubheading HTML specific properties 17336 17337 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 17338 @item @code{:html-allow-name-attribute-in-anchors} 17339 @tab @code{org-html-allow-name-attribute-in-anchors} 17340 @item @code{:html-checkbox-type} 17341 @tab @code{org-html-checkbox-type} 17342 @item @code{:html-container} 17343 @tab @code{org-html-container-element} 17344 @item @code{:html-divs} 17345 @tab @code{org-html-divs} 17346 @item @code{:html-doctype} 17347 @tab @code{org-html-doctype} 17348 @item @code{:html-extension} 17349 @tab @code{org-html-extension} 17350 @item @code{:html-footnote-format} 17351 @tab @code{org-html-footnote-format} 17352 @item @code{:html-footnote-separator} 17353 @tab @code{org-html-footnote-separator} 17354 @item @code{:html-footnotes-section} 17355 @tab @code{org-html-footnotes-section} 17356 @item @code{:html-format-drawer-function} 17357 @tab @code{org-html-format-drawer-function} 17358 @item @code{:html-format-headline-function} 17359 @tab @code{org-html-format-headline-function} 17360 @item @code{:html-format-inlinetask-function} 17361 @tab @code{org-html-format-inlinetask-function} 17362 @item @code{:html-head-extra} 17363 @tab @code{org-html-head-extra} 17364 @item @code{:html-head-include-default-style} 17365 @tab @code{org-html-head-include-default-style} 17366 @item @code{:html-head-include-scripts} 17367 @tab @code{org-html-head-include-scripts} 17368 @item @code{:html-head} 17369 @tab @code{org-html-head} 17370 @item @code{:html-home/up-format} 17371 @tab @code{org-html-home/up-format} 17372 @item @code{:html-html5-fancy} 17373 @tab @code{org-html-html5-fancy} 17374 @item @code{:html-indent} 17375 @tab @code{org-html-indent} 17376 @item @code{:html-infojs-options} 17377 @tab @code{org-html-infojs-options} 17378 @item @code{:html-infojs-template} 17379 @tab @code{org-html-infojs-template} 17380 @item @code{:html-inline-image-rules} 17381 @tab @code{org-html-inline-image-rules} 17382 @item @code{:html-inline-images} 17383 @tab @code{org-html-inline-images} 17384 @item @code{:html-link-home} 17385 @tab @code{org-html-link-home} 17386 @item @code{:html-link-org-files-as-html} 17387 @tab @code{org-html-link-org-files-as-html} 17388 @item @code{:html-link-up} 17389 @tab @code{org-html-link-up} 17390 @item @code{:html-link-use-abs-url} 17391 @tab @code{org-html-link-use-abs-url} 17392 @item @code{:html-mathjax-options} 17393 @tab @code{org-html-mathjax-options} 17394 @item @code{:html-mathjax-template} 17395 @tab @code{org-html-mathjax-template} 17396 @item @code{:html-equation-reference-format} 17397 @tab @code{org-html-equation-reference-format} 17398 @item @code{:html-metadata-timestamp-format} 17399 @tab @code{org-html-metadata-timestamp-format} 17400 @item @code{:html-postamble-format} 17401 @tab @code{org-html-postamble-format} 17402 @item @code{:html-postamble} 17403 @tab @code{org-html-postamble} 17404 @item @code{:html-preamble-format} 17405 @tab @code{org-html-preamble-format} 17406 @item @code{:html-preamble} 17407 @tab @code{org-html-preamble} 17408 @item @code{:html-self-link-headlines} 17409 @tab @code{org-html-self-link-headlines} 17410 @item @code{:html-table-align-individual-field} 17411 @tab @code{org-html-table-align-individual-fields} 17412 @item @code{:html-table-attributes} 17413 @tab @code{org-html-table-default-attributes} 17414 @item @code{:html-table-caption-above} 17415 @tab @code{org-html-table-caption-above} 17416 @item @code{:html-table-data-tags} 17417 @tab @code{org-html-table-data-tags} 17418 @item @code{:html-table-header-tags} 17419 @tab @code{org-html-table-header-tags} 17420 @item @code{:html-table-row-tags} 17421 @tab @code{org-html-table-row-tags} 17422 @item @code{:html-table-use-header-tags-for-first-column} 17423 @tab @code{org-html-table-use-header-tags-for-first-column} 17424 @item @code{:html-tag-class-prefix} 17425 @tab @code{org-html-tag-class-prefix} 17426 @item @code{:html-text-markup-alist} 17427 @tab @code{org-html-text-markup-alist} 17428 @item @code{:html-todo-kwd-class-prefix} 17429 @tab @code{org-html-todo-kwd-class-prefix} 17430 @item @code{:html-toplevel-hlevel} 17431 @tab @code{org-html-toplevel-hlevel} 17432 @item @code{:html-use-infojs} 17433 @tab @code{org-html-use-infojs} 17434 @item @code{:html-validation-link} 17435 @tab @code{org-html-validation-link} 17436 @item @code{:html-viewport} 17437 @tab @code{org-html-viewport} 17438 @item @code{:html-wrap-src-lines} 17439 @tab @code{org-html-wrap-src-lines} 17440 @item @code{:html-xml-declaration} 17441 @tab @code{org-html-xml-declaration} 17442 @end multitable 17443 17444 @anchor{@LaTeX{} specific properties} 17445 @subsubheading @LaTeX{} specific properties 17446 17447 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 17448 @item @code{:latex-active-timestamp-format} 17449 @tab @code{org-latex-active-timestamp-format} 17450 @item @code{:latex-caption-above} 17451 @tab @code{org-latex-caption-above} 17452 @item @code{:latex-classes} 17453 @tab @code{org-latex-classes} 17454 @item @code{:latex-class} 17455 @tab @code{org-latex-default-class} 17456 @item @code{:latex-compiler} 17457 @tab @code{org-latex-compiler} 17458 @item @code{:latex-default-figure-position} 17459 @tab @code{org-latex-default-figure-position} 17460 @item @code{:latex-default-table-environment} 17461 @tab @code{org-latex-default-table-environment} 17462 @item @code{:latex-default-table-mode} 17463 @tab @code{org-latex-default-table-mode} 17464 @item @code{:latex-diary-timestamp-format} 17465 @tab @code{org-latex-diary-timestamp-format} 17466 @item @code{:latex-engraved-options} 17467 @tab @code{org-latex-engraved-options} 17468 @item @code{:latex-engraved-preamble} 17469 @tab @code{org-latex-engraved-preamble} 17470 @item @code{:latex-engraved-theme} 17471 @tab @code{org-latex-engraved-theme} 17472 @item @code{:latex-footnote-defined-format} 17473 @tab @code{org-latex-footnote-defined-format} 17474 @item @code{:latex-footnote-separator} 17475 @tab @code{org-latex-footnote-separator} 17476 @item @code{:latex-format-drawer-function} 17477 @tab @code{org-latex-format-drawer-function} 17478 @item @code{:latex-format-headline-function} 17479 @tab @code{org-latex-format-headline-function} 17480 @item @code{:latex-format-inlinetask-function} 17481 @tab @code{org-latex-format-inlinetask-function} 17482 @item @code{:latex-hyperref-template} 17483 @tab @code{org-latex-hyperref-template} 17484 @item @code{:latex-image-default-height} 17485 @tab @code{org-latex-image-default-height} 17486 @item @code{:latex-image-default-option} 17487 @tab @code{org-latex-image-default-option} 17488 @item @code{:latex-image-default-width} 17489 @tab @code{org-latex-image-default-width} 17490 @item @code{:latex-images-centered} 17491 @tab @code{org-latex-images-centered} 17492 @item @code{:latex-inactive-timestamp-format} 17493 @tab @code{org-latex-inactive-timestamp-format} 17494 @item @code{:latex-inline-image-rules} 17495 @tab @code{org-latex-inline-image-rules} 17496 @item @code{:latex-link-with-unknown-path-format} 17497 @tab @code{org-latex-link-with-unknown-path-format} 17498 @item @code{:latex-listings-langs} 17499 @tab @code{org-latex-listings-langs} 17500 @item @code{:latex-listings-options} 17501 @tab @code{org-latex-listings-options} 17502 @item @code{:latex-minted-langs} 17503 @tab @code{org-latex-minted-langs} 17504 @item @code{:latex-minted-options} 17505 @tab @code{org-latex-minted-options} 17506 @item @code{:latex-prefer-user-labels} 17507 @tab @code{org-latex-prefer-user-labels} 17508 @item @code{:latex-subtitle-format} 17509 @tab @code{org-latex-subtitle-format} 17510 @item @code{:latex-subtitle-separate} 17511 @tab @code{org-latex-subtitle-separate} 17512 @item @code{:latex-src-block-backend} 17513 @tab @code{org-latex-src-block-backend} 17514 @item @code{:latex-table-scientific-notation} 17515 @tab @code{org-latex-table-scientific-notation} 17516 @item @code{:latex-tables-booktabs} 17517 @tab @code{org-latex-tables-booktabs} 17518 @item @code{:latex-tables-centered} 17519 @tab @code{org-latex-tables-centered} 17520 @item @code{:latex-text-markup-alist} 17521 @tab @code{org-latex-text-markup-alist} 17522 @item @code{:latex-title-command} 17523 @tab @code{org-latex-title-command} 17524 @item @code{:latex-toc-command} 17525 @tab @code{org-latex-toc-command} 17526 @end multitable 17527 17528 @anchor{Markdown specific properties} 17529 @subsubheading Markdown specific properties 17530 17531 @multitable {aaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaa} 17532 @item @code{:md-footnote-format} 17533 @tab @code{org-md-footnote-format} 17534 @item @code{:md-footnotes-section} 17535 @tab @code{org-md-footnotes-section} 17536 @item @code{:md-headline-style} 17537 @tab @code{org-md-headline-style} 17538 @item @code{:md-toplevel-hlevel} 17539 @tab @code{org-md-toplevel-hlevel} 17540 @end multitable 17541 17542 @anchor{ODT specific properties} 17543 @subsubheading ODT specific properties 17544 17545 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 17546 @item @code{:odt-content-template-file} 17547 @tab @code{org-odt-content-template-file} 17548 @item @code{:odt-display-outline-level} 17549 @tab @code{org-odt-display-outline-level} 17550 @item @code{:odt-fontify-srcblocks} 17551 @tab @code{org-odt-fontify-srcblocks} 17552 @item @code{:odt-format-drawer-function} 17553 @tab @code{org-odt-format-drawer-function} 17554 @item @code{:odt-format-headline-function} 17555 @tab @code{org-odt-format-headline-function} 17556 @item @code{:odt-format-inlinetask-function} 17557 @tab @code{org-odt-format-inlinetask-function} 17558 @item @code{:odt-inline-formula-rules} 17559 @tab @code{org-odt-inline-formula-rules} 17560 @item @code{:odt-inline-image-rules} 17561 @tab @code{org-odt-inline-image-rules} 17562 @item @code{:odt-pixels-per-inch} 17563 @tab @code{org-odt-pixels-per-inch} 17564 @item @code{:odt-styles-file} 17565 @tab @code{org-odt-styles-file} 17566 @item @code{:odt-table-styles} 17567 @tab @code{org-odt-table-styles} 17568 @item @code{:odt-use-date-fields} 17569 @tab @code{org-odt-use-date-fields} 17570 @end multitable 17571 17572 @anchor{Texinfo specific properties} 17573 @subsubheading Texinfo specific properties 17574 17575 @multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 17576 @item @code{:texinfo-active-timestamp-format} 17577 @tab @code{org-texinfo-active-timestamp-format} 17578 @item @code{:texinfo-classes} 17579 @tab @code{org-texinfo-classes} 17580 @item @code{:texinfo-class} 17581 @tab @code{org-texinfo-default-class} 17582 @item ~:texinfo-compact-itemx 17583 @tab @code{org-texinfo-compact-itemx} 17584 @item @code{:texinfo-table-default-markup} 17585 @tab @code{org-texinfo-table-default-markup} 17586 @item @code{:texinfo-diary-timestamp-format} 17587 @tab @code{org-texinfo-diary-timestamp-format} 17588 @item @code{:texinfo-filename} 17589 @tab @code{org-texinfo-filename} 17590 @item @code{:texinfo-format-drawer-function} 17591 @tab @code{org-texinfo-format-drawer-function} 17592 @item @code{:texinfo-format-headline-function} 17593 @tab @code{org-texinfo-format-headline-function} 17594 @item @code{:texinfo-format-inlinetask-function} 17595 @tab @code{org-texinfo-format-inlinetask-function} 17596 @item @code{:texinfo-inactive-timestamp-format} 17597 @tab @code{org-texinfo-inactive-timestamp-format} 17598 @item @code{:texinfo-link-with-unknown-path-format} 17599 @tab @code{org-texinfo-link-with-unknown-path-format} 17600 @item @code{:texinfo-node-description-column} 17601 @tab @code{org-texinfo-node-description-column} 17602 @item @code{:texinfo-table-scientific-notation} 17603 @tab @code{org-texinfo-table-scientific-notation} 17604 @item @code{:texinfo-tables-verbatim} 17605 @tab @code{org-texinfo-tables-verbatim} 17606 @item @code{:texinfo-text-markup-alist} 17607 @tab @code{org-texinfo-text-markup-alist} 17608 @end multitable 17609 17610 @node Publishing links 17611 @subsection Publishing links 17612 17613 @cindex links, publishing 17614 17615 To create a link from one Org file to another, you would use something 17616 like @samp{[[file:foo.org][The foo]]} or simply @samp{[[file:foo.org]]} (see 17617 @ref{External Links}). When published, this link becomes a link to 17618 @samp{foo.html}. You can thus interlink the pages of your ``Org web'' 17619 project and the links will work as expected when you publish them to 17620 HTML@. If you also publish the Org source file and want to link to it, 17621 use an @samp{http} link instead of a @samp{file:} link, because @samp{file} links are 17622 converted to link to the corresponding @samp{.html} file. 17623 17624 Links to encrypted Org files, like @samp{[[file:foo.org.gpg]]} are also 17625 supported. 17626 17627 You may also link to related files, such as images. Provided you are 17628 careful with relative file names, and provided you have also 17629 configured Org to upload the related files, these links will work too. 17630 See @ref{Complex example}, for an example of this 17631 usage. 17632 17633 Links between published documents can contain some search options (see 17634 @ref{Search Options}), which will be resolved to the 17635 appropriate location in the linked file. For example, once published 17636 to HTML, the following links all point to a dedicated anchor in 17637 @samp{foo.html}. 17638 17639 @example 17640 [[file:foo.org::*heading]] 17641 [[file:foo.org::#custom-id]] 17642 [[file:foo.org::target]] 17643 @end example 17644 17645 @node Site map 17646 @subsection Generating a sitemap 17647 17648 @cindex sitemap, of published pages 17649 17650 The following properties may be used to control publishing of 17651 a map of files for a given project. 17652 17653 @table @asis 17654 @item @code{:auto-sitemap} 17655 When non-@code{nil}, publish a sitemap during 17656 @code{org-publish-current-project} or @code{org-publish-all}. 17657 17658 @item @code{:sitemap-filename} 17659 Filename for output of sitemap. Defaults to @samp{sitemap.org}, which 17660 becomes @samp{sitemap.html}. 17661 17662 @item @code{:sitemap-title} 17663 Title of sitemap page. Defaults to name of file. 17664 17665 @item @code{:sitemap-format-entry} 17666 @findex org-publish-find-date 17667 @findex org-publish-find-property 17668 @findex org-publish-find-title 17669 With this option one can tell how a site-map entry is formatted in 17670 the site-map. It is a function called with three arguments: the 17671 file or directory name relative to base directory of the project, 17672 the site-map style and the current project. It is expected to 17673 return a string. Default value turns file names into links and use 17674 document titles as descriptions. For specific formatting needs, one 17675 can use @code{org-publish-find-date}, @code{org-publish-find-title} and 17676 @code{org-publish-find-property}, to retrieve additional information 17677 about published documents. 17678 17679 @item @code{:sitemap-function} 17680 Plug-in function to use for generation of the sitemap. It is called 17681 with two arguments: the title of the site-map and a representation 17682 of the files and directories involved in the project as a nested 17683 list, which can further be transformed using @code{org-list-to-generic}, 17684 @code{org-list-to-subtree} and alike. Default value generates a plain 17685 list of links to all files in the project. 17686 17687 @item @code{:sitemap-sort-folders} 17688 Where folders should appear in the sitemap. Set this to @code{first} 17689 (default) or @code{last} to display folders first or last, respectively. 17690 When set to @code{ignore}, folders are ignored altogether. Any other 17691 value mixes files and folders. This variable has no effect when 17692 site-map style is @code{tree}. 17693 17694 @item @code{:sitemap-sort-files} 17695 How the files are sorted in the site map. Set this to 17696 @code{alphabetically} (default), @code{chronologically} or 17697 @code{anti-chronologically}. @code{chronologically} sorts the files with 17698 older date first while @code{anti-chronologically} sorts the files with 17699 newer date first. @code{alphabetically} sorts the files alphabetically. 17700 The date of a file is retrieved with @code{org-publish-find-date}. 17701 17702 @item @code{:sitemap-ignore-case} 17703 Should sorting be case-sensitive? Default @code{nil}. 17704 17705 @item @code{:sitemap-file-entry-format} 17706 With this option one can tell how a sitemap's entry is formatted in 17707 the sitemap. This is a format string with some escape sequences: 17708 @code{%t} stands for the title of the file, @code{%a} stands for the author of 17709 the file and @code{%d} stands for the date of the file. The date is 17710 retrieved with the @code{org-publish-find-date} function and formatted 17711 with @code{org-publish-sitemap-date-format}. Default @code{%t}. 17712 17713 @item @code{:sitemap-date-format} 17714 Format string for the @code{format-time-string} function that tells how 17715 a sitemap entry's date is to be formatted. This property bypasses 17716 @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}. 17717 @end table 17718 17719 @node Generating an index 17720 @subsection Generating an index 17721 17722 @cindex index, in a publishing project 17723 17724 Org mode can generate an index across the files of a publishing project. 17725 17726 @table @asis 17727 @item @code{:makeindex} 17728 When non-@code{nil}, generate in index in the file @samp{theindex.org} and 17729 publish it as @samp{theindex.html}. 17730 @end table 17731 17732 The file is created when first publishing a project with the 17733 @code{:makeindex} set. The file only contains a statement @samp{#+INCLUDE: 17734 "theindex.inc"}. You can then build around this include statement by 17735 adding a title, style information, etc. 17736 17737 @cindex @samp{INDEX}, keyword 17738 Index entries are specified with @samp{INDEX} keyword. An entry that 17739 contains an exclamation mark creates a sub item. 17740 17741 @example 17742 *** Curriculum Vitae 17743 #+INDEX: CV 17744 #+INDEX: Application!CV 17745 @end example 17746 17747 @node Uploading Files 17748 @section Uploading Files 17749 17750 @cindex rsync 17751 @cindex unison 17752 17753 For those people already utilizing third party sync tools such as 17754 Rsync or Unison, it might be preferable not to use the built-in remote 17755 publishing facilities of Org mode which rely heavily on Tramp. Tramp, 17756 while very useful and powerful, tends not to be so efficient for 17757 multiple file transfer and has been known to cause problems under 17758 heavy usage. 17759 17760 Specialized synchronization utilities offer several advantages. In 17761 addition to timestamp comparison, they also do content and 17762 permissions/attribute checks. For this reason you might prefer to 17763 publish your web to a local directory---possibly even @emph{in place} with 17764 your Org files---and then use Unison or Rsync to do the 17765 synchronization with the remote host. 17766 17767 Since Unison, for example, can be configured as to which files to 17768 transfer to a certain remote destination, it can greatly simplify the 17769 project publishing definition. Simply keep all files in the correct 17770 location, process your Org files with @code{org-publish} and let the 17771 synchronization tool do the rest. You do not need, in this scenario, 17772 to include attachments such as JPG, CSS or PNG files in the project 17773 definition since the third-party tool syncs them. 17774 17775 Publishing to a local directory is also much faster than to a remote 17776 one, so that you can afford more easily to republish entire projects. 17777 If you set @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the 17778 main benefit of re-including any changed external files such as source 17779 example files you might include with @samp{INCLUDE} keyword. The timestamp 17780 mechanism in Org is not smart enough to detect if included files have 17781 been modified. 17782 17783 @node Sample Configuration 17784 @section Sample Configuration 17785 17786 Below we provide two example configurations. The first one is 17787 a simple project publishing only a set of Org files. The second 17788 example is more complex, with a multi-component project. 17789 17790 @menu 17791 * Simple example:: One-component publishing. 17792 * Complex example:: A multi-component publishing example. 17793 @end menu 17794 17795 @node Simple example 17796 @subsection Example: simple publishing configuration 17797 17798 This example publishes a set of Org files to the @samp{public_html} 17799 directory on the local machine. 17800 17801 @lisp 17802 (setq org-publish-project-alist 17803 '(("org" 17804 :base-directory "~/org/" 17805 :publishing-function org-html-publish-to-html 17806 :publishing-directory "~/public_html" 17807 :section-numbers nil 17808 :with-toc nil 17809 :html-head "<link rel=\"stylesheet\" 17810 href=\"../other/mystyle.css\" 17811 type=\"text/css\"/>"))) 17812 @end lisp 17813 17814 @node Complex example 17815 @subsection Example: complex publishing configuration 17816 17817 This more complicated example publishes an entire website, including 17818 Org files converted to HTML, image files, Emacs Lisp source code, and 17819 style sheets. The publishing directory is remote and private files 17820 are excluded. 17821 17822 To ensure that links are preserved, care should be taken to replicate 17823 your directory structure on the web server, and to use relative file 17824 paths. For example, if your Org files are kept in @samp{~/org/} and your 17825 publishable images in @samp{~/images/}, you would link to an image with 17826 17827 @example 17828 file:../images/myimage.png 17829 @end example 17830 17831 17832 On the web server, the relative path to the image should be the same. 17833 You can accomplish this by setting up an @samp{images/} folder in the right 17834 place on the web server, and publishing images to it. 17835 17836 @lisp 17837 (setq org-publish-project-alist 17838 '(("orgfiles" 17839 :base-directory "~/org/" 17840 :base-extension "org" 17841 :publishing-directory "/ssh:user@@host:~/html/notebook/" 17842 :publishing-function org-html-publish-to-html 17843 :exclude "PrivatePage.org" ;; regexp 17844 :headline-levels 3 17845 :section-numbers nil 17846 :with-toc nil 17847 :html-head "<link rel=\"stylesheet\" 17848 href=\"../other/mystyle.css\" type=\"text/css\"/>" 17849 :html-preamble t) 17850 17851 ("images" 17852 :base-directory "~/images/" 17853 :base-extension "jpg\\|gif\\|png" 17854 :publishing-directory "/ssh:user@@host:~/html/images/" 17855 :publishing-function org-publish-attachment) 17856 17857 ("other" 17858 :base-directory "~/other/" 17859 :base-extension "css\\|el" 17860 :publishing-directory "/ssh:user@@host:~/html/other/" 17861 :publishing-function org-publish-attachment) 17862 ("website" :components ("orgfiles" "images" "other")))) 17863 @end lisp 17864 17865 @node Triggering Publication 17866 @section Triggering Publication 17867 17868 Once properly configured, Org can publish with the following commands: 17869 17870 @table @asis 17871 @item @kbd{C-c C-e P x} (@code{org-publish}) 17872 @kindex C-c C-e P x 17873 @findex org-publish 17874 Prompt for a specific project and publish all files that belong to 17875 it. 17876 17877 @item @kbd{C-c C-e P p} (@code{org-publish-current-project}) 17878 @kindex C-c C-e P p 17879 @findex org-publish-current-project 17880 Publish the project containing the current file. 17881 17882 @item @kbd{C-c C-e P f} (@code{org-publish-current-file}) 17883 @kindex C-c C-e P f 17884 @findex org-publish-current-file 17885 Publish only the current file. 17886 17887 @item @kbd{C-c C-e P a} (@code{org-publish-all}) 17888 @kindex C-c C-e P a 17889 @findex org-publish-all 17890 Publish every project. 17891 @end table 17892 17893 @vindex org-publish-use-timestamps-flag 17894 Org uses timestamps to track when a file has changed. The above 17895 functions normally only publish changed files. You can override this 17896 and force publishing of all files by giving a prefix argument to any 17897 of the commands above, or by customizing the variable 17898 @code{org-publish-use-timestamps-flag}. This may be necessary in 17899 particular if files include other files via @samp{SETUPFILE} or @samp{INCLUDE} 17900 keywords. 17901 17902 @node Citation handling 17903 @chapter Citation handling 17904 17905 @cindex citation 17906 17907 The @samp{oc.el} library provides tooling to handle citations in Org via 17908 ``citation processors'' that offer some or all of the following 17909 capabilities: 17910 17911 @table @asis 17912 @item activate 17913 Fontification, tooltip preview, etc. 17914 @item follow 17915 At-point actions on citations via @code{org-open-at-point}. 17916 @item insert 17917 Add and edit citations via @code{org-cite-insert}. 17918 @item export 17919 Via different libraries for different target formats. 17920 @end table 17921 17922 To use a ``citation processor'', the user must load them; for example; 17923 17924 @lisp 17925 (require 'oc-bibtex) 17926 @end lisp 17927 17928 They can then configure them with @code{org-cite-activate-processor}, 17929 @code{org-cite-follow-processor}, @code{org-cite-insert-processor}, and 17930 @code{org-cite-export-processors} respectively. 17931 17932 The included ``basic'' processor provides all four capabilities. 17933 17934 @menu 17935 * Citations:: 17936 * Citation export processors:: 17937 * Bibliography printing:: 17938 @end menu 17939 17940 @node Citations 17941 @section Citations 17942 17943 Before adding citations, first set one-or-more bibliographies, either 17944 globally with @code{org-cite-global-bibliography}, or locally using one or 17945 more ``bibliography'' keywords. 17946 17947 @example 17948 #+bibliography: SomeFile.bib 17949 #+bibliography: /some/other/file.json 17950 #+bibliography: "/some/file/with spaces/in its name.bib" 17951 @end example 17952 17953 @kindex C-c C-x @@ 17954 @findex org-cite-insert 17955 One can then insert and edit citations using @code{org-cite-insert}, called 17956 with @kbd{C-c C-x @@}. 17957 17958 A @emph{citation} requires one or more citation @emph{key(s)}, elements 17959 identifying a reference in the bibliography. 17960 17961 @itemize 17962 @item 17963 Each citation is surrounded by brackets and uses the @samp{cite} type. 17964 17965 @item 17966 Each key starts with the character @samp{@@}. 17967 17968 @item 17969 Each key can be qualified by a @emph{prefix} (e.g.@tie{}``see '') and/or 17970 a @emph{suffix} (e.g.@tie{}``p.@tie{}123''), giving information useful or necessary 17971 for the comprehension of the citation but not included in the 17972 reference. 17973 17974 @item 17975 A single citation can cite more than one reference ; the keys are 17976 separated by semicolons ; the formatting of such citation groups is 17977 specified by the style. 17978 17979 @item 17980 One can also specify a stylistic variation for the citations by 17981 inserting a @samp{/} and a style name between the @samp{cite} keyword and the 17982 colon; this usually makes sense only for the author-year styles. 17983 @end itemize 17984 17985 @example 17986 [cite/style:common prefix ;prefix @@key suffix; ... ; common suffix] 17987 @end example 17988 17989 17990 The only mandatory elements are: 17991 17992 @itemize 17993 @item 17994 The @samp{cite} keyword and the colon. 17995 @item 17996 The @samp{@@} character immediately preceding each key. 17997 @item 17998 The brackets surrounding the citation(s) (group). 17999 @end itemize 18000 18001 @node Citation export processors 18002 @section Citation export processors 18003 18004 Org currently includes the following export processors: 18005 18006 @itemize 18007 @item 18008 Two processors can export to a variety of formats, including @samp{latex} 18009 (and therefore @samp{pdf}), @samp{html}, @samp{odt} and plain (UTF8) text: 18010 18011 @table @asis 18012 @item basic 18013 a basic export processor, well adapted to situations 18014 where backward compatibility is not a requirement and formatting 18015 needs are minimal; 18016 18017 @item csl 18018 this export processor uses format files written in @uref{https://en.wikipedia.org/wiki/Citation_Style_Language, Citation 18019 Style Language} via @uref{https://github.com/andras-simonyi/citeproc-el, citeproc-el}; 18020 @end table 18021 18022 @item 18023 In contrast, three other processors target @LaTeX{} and @LaTeX{}-derived 18024 formats exclusively: 18025 18026 @table @asis 18027 @item bibtex 18028 this export processor uses Bib@TeX{}, the historical 18029 bibliographic processor used with @LaTeX{}, thus allowing the use of 18030 data and style files compatible with this processor (including a 18031 large number of publishers' styles). It only supports @LaTeX{}'s 18032 @samp{\cite} and @samp{\nocite} commands. 18033 18034 @item natbib 18035 as with the bibtex processor, but using the @LaTeX{} 18036 package @samp{natbib}, allowing more stylistic variants that @LaTeX{}'s 18037 @samp{\cite} command. 18038 18039 @item biblatex 18040 this backend allows the use of data and formats 18041 prepared for Bib@LaTeX{}, an alternate bibliographic processor used 18042 with @LaTeX{}, which overcomes some serious Bib@TeX{} limitations, but 18043 has not (yet?)@tie{}been widely adopted by publishers. 18044 @end table 18045 @end itemize 18046 18047 The @samp{CITE_EXPORT} keyword specifies the export processor and the 18048 citation (and possibly reference) style(s); for example (all arguments 18049 are optional) 18050 18051 @example 18052 #+cite_export: basic author author-year 18053 @end example 18054 18055 18056 @noindent 18057 specifies the ``basic'' export processor with citations inserted as 18058 author's name and references indexed by author's names and year; 18059 18060 @example 18061 #+cite_export: csl /some/path/to/vancouver-brackets.csl 18062 @end example 18063 18064 18065 @noindent 18066 specifies the ``csl'' processor and CSL style, which in this case 18067 defines numeric citations and numeric references according to the 18068 @samp{Vancouver} specification (as style used in many medical journals), 18069 following a typesetting variation putting citations between brackets; 18070 18071 @example 18072 #+cite_export: natbib kluwer 18073 @end example 18074 18075 18076 @noindent 18077 specifies the @samp{natbib} export processor with a label citation style 18078 conformant to the Harvard style and the specification of the 18079 Wolkers-Kluwer publisher; since it relies on the @code{bibtex} processor of 18080 your @LaTeX{} installation, it won't export to anything but PDF@. 18081 18082 @node Bibliography printing 18083 @section Bibliography printing 18084 18085 The @samp{PRINT_BIBLIOGRAPHY} keyword specifies where the bibliography 18086 should be printed (note the colon): 18087 18088 @example 18089 #+print_bibliography: 18090 @end example 18091 18092 18093 The bibliography printed by the @LaTeX{}-based export processors 18094 ``bibtex'', ``natbib'' and ``biblatex'' has a chapter or section heading by 18095 default, while the ``basic'' and ``csl'' processors print the list of 18096 bibliography entries without a heading. 18097 18098 A document may contain more than one @samp{PRINT_BIBLIOGRAPHY} keywords. 18099 Each of the keywords will trigger printing the bibliography. 18100 18101 The keywords can be used with or without additional options. Options 18102 can be used, for example, to print only entries that belong to a 18103 certain category or to control formatting. The set of supported 18104 @samp{PRINT_BIBLIOGRAPHY} options and their interpretation varies between 18105 the different citation export processors. Some export processors do 18106 not support passing options. 18107 18108 @menu 18109 * Bibliography options in the ``biblatex'' and ``csl'' export processors:: 18110 @end menu 18111 18112 @node Bibliography options in the ``biblatex'' and ``csl'' export processors 18113 @subsection Bibliography options in the ``biblatex'' and ``csl'' export processors 18114 18115 The ``biblatex'' and ``csl'' export processors support bibliography 18116 options through a property list attached to the @samp{PRINT_BIBLIOGRAPHY} 18117 keyword. For example, 18118 18119 @example 18120 #print_bibliography: :keyword algebra :type book 18121 @end example 18122 18123 18124 Values including spaces must be surrounded with double quotes. If you 18125 need to use a key multiple times, you can separate its values with 18126 commas, but without any space in-between: 18127 18128 @example 18129 #print_bibliography: :keyword "algebraic logic" :nottype article,book 18130 @end example 18131 18132 18133 The ``biblatex'' export processor accepts all options supported by 18134 Bib@LaTeX{}'s @code{\printbibliography} command, while the ``csl'' processor 18135 accepts the following ones: 18136 18137 @table @asis 18138 @item @samp{:keyword <keyword(,keyword2...)>} 18139 Print only entries whose 18140 keyword field contains all given keywords. 18141 18142 @item @samp{:notkeyword <keyword(,keyword2...)>} 18143 Print only entries whose 18144 keyword field does not contain any of the given keywords. 18145 18146 @item @samp{:type <entrytype>} 18147 Print only entries whose type is 18148 @samp{<entrytype>}. Entry type is the Bib@TeX{}/Bib@LaTeX{} entry type if this 18149 information is available (the entry was read from a Bib@TeX{}/Bib@LaTeX{} 18150 bibliography) and the CSL entry type otherwise. 18151 18152 @item @samp{:nottype <entrytype(,entrytype2...)>} 18153 Print only entries whose 18154 type is not among the given entry types. Entry type is determined 18155 as in the case of @samp{:type}. 18156 18157 @item @samp{:csltype <entrytype>} 18158 Print only entries whose CSL entry type 18159 (possibly based on a conversion from Bib@TeX{}/Bib@LaTeX{} to CSL) is 18160 @samp{<entrytype>}. 18161 18162 @item @samp{:notcsltype <entrytype(,entrytype2...)>} 18163 Print only entries whose 18164 CSL entry type (possibly based on a conversion from Bib@TeX{}/Bib@LaTeX{} 18165 to CSL) is not among the listed entry types. 18166 18167 @item @samp{:filter <predicate>} 18168 Print only entries for which the given 18169 Emacs Lisp predicate returns a non-@code{nil} value. 18170 @end table 18171 18172 @node Working with Source Code 18173 @chapter Working with Source Code 18174 18175 @cindex source code, working with 18176 18177 Source code here refers to any plain text collection of computer 18178 instructions, possibly with comments, written using a human-readable 18179 programming language. Org can manage source code in an Org document 18180 when the source code is identified with begin and end markers. 18181 Working with source code begins with identifying source code blocks. 18182 A source code block can be placed almost anywhere in an Org document; 18183 it is not restricted to the preamble or the end of the document. 18184 However, Org cannot manage a source code block if it is placed inside 18185 an Org comment or within a fixed width section. 18186 18187 Here is an example source code block in the Emacs Lisp language: 18188 18189 @example 18190 #+BEGIN_SRC emacs-lisp 18191 (defun org-xor (a b) 18192 "Exclusive or." 18193 (if a (not b) b)) 18194 #+END_SRC 18195 @end example 18196 18197 Source code blocks are one of many Org block types, which also include 18198 ``center'', ``comment'', ``dynamic'', ``example'', ``export'', ``quote'', 18199 ``special'', and ``verse''. This section pertains to blocks between 18200 @samp{#+BEGIN_SRC} and @samp{#+END_SRC}. 18201 18202 Details of Org's facilities for working with source code are described 18203 in the following sections. 18204 18205 @menu 18206 * Features Overview:: Enjoy the versatility of source blocks. 18207 * Structure of Code Blocks:: Code block syntax described. 18208 * Using Header Arguments:: Different ways to set header arguments. 18209 * Environment of a Code Block:: Arguments, sessions, working directory... 18210 * Evaluating Code Blocks:: Place results of evaluation in the Org buffer. 18211 * Results of Evaluation:: Choosing a results type, post-processing... 18212 * Exporting Code Blocks:: Export contents and/or results. 18213 * Extracting Source Code:: Create pure source code files. 18214 * Languages:: List of supported code block languages. 18215 * Editing Source Code:: Language major-mode editing. 18216 * Noweb Reference Syntax:: Literate programming in Org mode. 18217 * Library of Babel:: Use and contribute to a library of useful code blocks. 18218 * Key bindings and Useful Functions:: Work quickly with code blocks. 18219 * Batch Execution:: Call functions from the command line. 18220 @end menu 18221 18222 @node Features Overview 18223 @section Features Overview 18224 18225 Org can manage the source code in the block delimited by @samp{#+BEGIN_SRC} 18226 @dots{} @samp{#+END_SRC} in several ways that can simplify housekeeping tasks 18227 essential to modern source code maintenance. Org can edit, format, 18228 extract, export, and publish source code blocks. Org can also compile 18229 and execute a source code block, then capture the results. The Org 18230 mode literature sometimes refers to source code blocks as @emph{live code} 18231 blocks because they can alter the content of the Org document or the 18232 material that it exports. Users can control the ``liveliness'' of each 18233 source code block by tweaking the header arguments (see @ref{Using Header Arguments}) for compiling, execution, extraction, and exporting. 18234 18235 For editing and formatting a source code block, Org uses an 18236 appropriate Emacs major mode that includes features specifically 18237 designed for source code in that language. 18238 18239 Org can extract one or more source code blocks and write them to one 18240 or more source files---a process known as @emph{tangling} in literate 18241 programming terminology. 18242 18243 For exporting and publishing, Org's back-ends can format a source code 18244 block appropriately, often with native syntax highlighting. 18245 18246 For executing and compiling a source code block, the user can 18247 configure Org to select the appropriate compiler. Org provides 18248 facilities to collect the result of the execution or compiler output, 18249 insert it into the Org document, and/or export it. In addition to 18250 text results, Org can insert links to other data types, including 18251 audio, video, and graphics. Org can also link a compiler error 18252 message to the appropriate line in the source code block. 18253 18254 An important feature of Org's management of source code blocks is the 18255 ability to pass variables, functions, and results to one another using 18256 a common syntax for source code blocks in any language. Although most 18257 literate programming facilities are restricted to one language or 18258 another, Org's language-agnostic approach lets the literate programmer 18259 match each programming task with the appropriate computer language and 18260 to mix them all together in a single Org document. This 18261 interoperability among languages explains why Org's source code 18262 management facility was named @emph{Org Babel} by its originators, Eric 18263 Schulte and Dan Davison. 18264 18265 Org mode fulfills the promise of easy verification and maintenance of 18266 publishing reproducible research by keeping text, data, code, 18267 configuration settings of the execution environment, the results of 18268 the execution, and associated narratives, claims, references, and 18269 internal and external links in a single Org document. 18270 18271 @node Structure of Code Blocks 18272 @section Structure of Code Blocks 18273 18274 @cindex code block, structure 18275 @cindex source code, block structure 18276 @cindex @samp{NAME} keyword, in source blocks 18277 @cindex @samp{BEGIN_SRC} 18278 18279 Org offers two ways to structure source code in Org documents: in 18280 a source code block, and directly inline. Both specifications are 18281 shown below. 18282 18283 A source code block conforms to this structure: 18284 18285 @example 18286 #+NAME: <name> 18287 #+BEGIN_SRC <language> <switches> <header arguments> 18288 <body> 18289 #+END_SRC 18290 @end example 18291 18292 Do not be put-off by having to remember the source block syntax. Org 18293 mode offers a command for wrapping existing text in a block (see 18294 @ref{Structure Templates}). Org also works with other completion systems 18295 in Emacs, some of which predate Org and have custom domain-specific 18296 languages for defining templates. Regular use of templates reduces 18297 errors, increases accuracy, and maintains consistency. 18298 18299 @cindex source code, inline 18300 An inline code block conforms to this structure: 18301 18302 @example 18303 src_<language>@{<body>@} 18304 @end example 18305 18306 18307 @noindent 18308 or 18309 18310 @example 18311 src_<language>[<header arguments>]@{<body>@} 18312 @end example 18313 18314 18315 @table @asis 18316 @item @samp{#+NAME: <name>} 18317 Optional. Names the source block so it can be called, like 18318 a function, from other source blocks or inline code to evaluate or 18319 to capture the results. Code from other blocks, other files, and 18320 from table formulas (see @ref{The Spreadsheet}) can use the name to 18321 reference a source block. This naming serves the same purpose as 18322 naming Org tables. Org mode requires unique names. For duplicate 18323 names, Org mode's behavior is undefined. 18324 18325 @item @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC} 18326 Mandatory. They mark the start and end of a block that Org 18327 requires. The @samp{#+BEGIN_SRC} line takes additional arguments, as 18328 described next. 18329 18330 @item @samp{<language>} 18331 @cindex language, in code blocks 18332 Mandatory. It is the identifier of the source code language in the 18333 block. See @ref{Languages}, for identifiers of supported languages. 18334 18335 @item @samp{<switches>} 18336 @cindex switches, in code blocks 18337 Optional. Switches provide finer control of the code execution, 18338 export, and format (see the discussion of switches in @ref{Literal Examples}). 18339 18340 @item @samp{<header arguments>} 18341 @cindex header arguments, in code blocks 18342 Optional. Heading arguments control many aspects of evaluation, 18343 export and tangling of code blocks (see @ref{Using Header Arguments}). 18344 Using Org's properties feature, header arguments can be selectively 18345 applied to the entire buffer or specific subtrees of the Org 18346 document. 18347 18348 @item @samp{<body>} 18349 Source code in the dialect of the specified language identifier. 18350 @end table 18351 18352 @node Using Header Arguments 18353 @section Using Header Arguments 18354 18355 Org comes with many header arguments common to all languages. New 18356 header arguments are added for specific languages as they become 18357 available for use in source code blocks. A header argument is 18358 specified with an initial colon followed by the argument's name in 18359 lowercase. 18360 18361 Since header arguments can be set in several ways, Org prioritizes 18362 them in case of overlaps or conflicts by giving local settings 18363 a higher priority. Header values in function calls, for example, 18364 override header values from global defaults. 18365 18366 @anchor{System-wide header arguments} 18367 @subheading System-wide header arguments 18368 18369 @vindex org-babel-default-header-args 18370 18371 @vindex org-babel-default-header-args 18372 System-wide values of header arguments can be specified by customizing 18373 the @code{org-babel-default-header-args} variable, which defaults to the 18374 following values: 18375 18376 @example 18377 :session => "none" 18378 :results => "replace" 18379 :exports => "code" 18380 :cache => "no" 18381 :noweb => "no" 18382 :hlines => "no" 18383 :tangle => "no" 18384 @end example 18385 18386 @vindex org-babel-default-inline-header-args 18387 Inline source blocks (see @ref{Structure of Code Blocks}) use slightly 18388 different default header arguments defined in 18389 @code{org-babel-default-inline-header-args}: 18390 18391 @example 18392 :session => "none" 18393 :results => "replace" 18394 :exports => "results" 18395 :hlines => "yes" 18396 @end example 18397 18398 The most notable difference between default header arguments for 18399 inline and normal source blocks is @samp{:exports} argument. For inline 18400 source blocks, results of evaluation are exported by default; not the 18401 code. 18402 18403 Unlike the default values, header arguments set using Org mode 18404 properties (see @ref{Header arguments in Org mode properties}) do apply to 18405 both the normal source blocks and inline source blocks. 18406 18407 The example below sets @samp{:noweb} header arguments to @samp{yes}, which makes 18408 Org expand @samp{:noweb} references by default. 18409 18410 @lisp 18411 (setq org-babel-default-header-args 18412 (cons '(:noweb . "yes") 18413 (assq-delete-all :noweb org-babel-default-header-args))) 18414 @end lisp 18415 18416 @cindex language specific default header arguments 18417 @cindex default header arguments per language 18418 Each language can have separate default header arguments by 18419 customizing the variable @code{org-babel-default-header-args:<LANG>}, where 18420 @var{<LANG>} is the name of the language. For details, see the 18421 language-specific online documentation at 18422 @uref{https://orgmode.org/worg/org-contrib/babel/}. 18423 18424 @anchor{Header arguments in Org mode properties} 18425 @subheading Header arguments in Org mode properties 18426 18427 For header arguments applicable to the buffer, use @samp{PROPERTY} keyword 18428 anywhere in the Org file (see @ref{Property Syntax}). 18429 18430 The following example makes all the R code blocks execute in the same 18431 session. Setting @samp{:results} to @samp{silent} ignores the results of 18432 executions for all blocks, not just R code blocks; no results inserted 18433 for any block. 18434 18435 @example 18436 #+PROPERTY: header-args:R :session *R* 18437 #+PROPERTY: header-args :results silent 18438 @end example 18439 18440 @vindex org-use-property-inheritance 18441 Header arguments set through Org's property drawers (see @ref{Property Syntax}) apply at the subtree level on down. Since these property 18442 drawers can appear anywhere in the file hierarchy, Org uses outermost 18443 call or source block to resolve the values. Org ignores 18444 @code{org-use-property-inheritance} setting. 18445 18446 In this example, @samp{:cache} defaults to @samp{yes} for all code blocks in the 18447 subtree. 18448 18449 @example 18450 * sample header 18451 :PROPERTIES: 18452 :header-args: :cache yes 18453 :END: 18454 @end example 18455 18456 @kindex C-c C-x p 18457 @findex org-set-property 18458 Properties defined through @code{org-set-property} function, bound to 18459 @kbd{C-c C-x p}, apply to all active languages. They override 18460 properties set in @code{org-babel-default-header-args}. 18461 18462 @cindex language specific header arguments properties 18463 @cindex header arguments per language 18464 Language-specific header arguments are also read from properties 18465 @samp{header-args:<LANG>} where @var{<LANG>} is the language 18466 identifier. For example, 18467 18468 @example 18469 * Heading 18470 :PROPERTIES: 18471 :header-args:clojure: :session *clojure-1* 18472 :header-args:R: :session *R* 18473 :END: 18474 ** Subheading 18475 :PROPERTIES: 18476 :header-args:clojure: :session *clojure-2* 18477 :END: 18478 @end example 18479 18480 @noindent 18481 would force separate sessions for Clojure blocks in @samp{Heading} and 18482 @samp{Subheading}, but use the same session for all R blocks. Blocks in 18483 @samp{Subheading} inherit settings from @samp{Heading}. 18484 18485 @anchor{Code block specific header arguments} 18486 @subheading Code block specific header arguments 18487 18488 Header arguments are most commonly set at the source code block level, 18489 on the @samp{#+BEGIN_SRC} line. Arguments set at this level take 18490 precedence over those set in the @code{org-babel-default-header-args} 18491 variable, and also those set as header properties. 18492 18493 In the following example, setting @samp{:results} to @samp{silent} makes it 18494 ignore results of the code execution. Setting @samp{:exports} to @samp{code} 18495 exports only the body of the code block to HTML or @LaTeX{}. 18496 18497 @example 18498 #+NAME: factorial 18499 #+BEGIN_SRC haskell :results silent :exports code :var n=0 18500 fac 0 = 1 18501 fac n = n * fac (n-1) 18502 #+END_SRC 18503 @end example 18504 18505 The same header arguments in an inline code block: 18506 18507 @example 18508 src_haskell[:exports both]@{fac 5@} 18509 @end example 18510 18511 18512 @cindex @samp{HEADER}, keyword 18513 Code block header arguments can span multiple lines using @samp{#+HEADER:} 18514 on each line. Note that Org currently accepts the plural spelling of 18515 @samp{#+HEADER:} only as a convenience for backward-compatibility. It may 18516 be removed at some point. 18517 18518 Multi-line header arguments on an unnamed code block: 18519 18520 @example 18521 #+HEADER: :var data1=1 18522 #+BEGIN_SRC emacs-lisp :var data2=2 18523 (message "data1:%S, data2:%S" data1 data2) 18524 #+END_SRC 18525 18526 #+RESULTS: 18527 : data1:1, data2:2 18528 @end example 18529 18530 Multi-line header arguments on a named code block: 18531 18532 @example 18533 #+NAME: named-block 18534 #+HEADER: :var data=2 18535 #+BEGIN_SRC emacs-lisp 18536 (message "data:%S" data) 18537 #+END_SRC 18538 18539 #+RESULTS: named-block 18540 : data:2 18541 @end example 18542 18543 @anchor{Header arguments in function calls} 18544 @subheading Header arguments in function calls 18545 18546 Header arguments in function calls are the most specific and override 18547 all other settings in case of an overlap. They get the highest 18548 priority. Two @samp{#+CALL:} examples are shown below. For the complete 18549 syntax of @samp{CALL} keyword, see @ref{Evaluating Code Blocks}. 18550 18551 In this example, @samp{:exports results} header argument is applied to the 18552 evaluation of the @samp{#+CALL:} line. 18553 18554 @example 18555 #+CALL: factorial(n=5) :exports results 18556 @end example 18557 18558 18559 In this example, @samp{:session special} header argument is applied to the 18560 evaluation of @samp{factorial} code block. 18561 18562 @example 18563 #+CALL: factorial[:session special](n=5) 18564 @end example 18565 18566 @node Environment of a Code Block 18567 @section Environment of a Code Block 18568 18569 18570 18571 @anchor{Passing arguments} 18572 @subheading Passing arguments 18573 18574 @cindex passing arguments to code blocks 18575 @cindex arguments, in code blocks 18576 @cindex @samp{var}, header argument 18577 Use @samp{var} for passing arguments to source code blocks. The specifics 18578 of variables in code blocks vary by the source language and are 18579 covered in the language-specific documentation. The syntax for @samp{var}, 18580 however, is the same for all languages. This includes declaring 18581 a variable, and assigning a default value. 18582 18583 The following syntax is used to pass arguments to code blocks using 18584 the @samp{var} header argument. 18585 18586 @example 18587 :var NAME=ASSIGN 18588 @end example 18589 18590 18591 @noindent 18592 @var{NAME} is the name of the variable bound in the code block 18593 body. @var{ASSIGN} is a literal value, such as a string, 18594 a number, a reference to a table, a list, a literal example, another 18595 code block---with or without arguments---or the results of evaluating 18596 a code block. @var{ASSIGN} may specify a filename for references 18597 to elements in a different file, using a @samp{:} to separate the filename 18598 from the reference. 18599 18600 @example 18601 :var NAME=FILE:REFERENCE 18602 @end example 18603 18604 18605 Here are examples of passing values by reference: 18606 18607 @table @asis 18608 @item table 18609 A table named with a @samp{NAME} keyword. 18610 18611 @example 18612 #+NAME: example-table 18613 | 1 | 18614 | 2 | 18615 | 3 | 18616 | 4 | 18617 18618 #+NAME: table-length 18619 #+BEGIN_SRC emacs-lisp :var table=example-table 18620 (length table) 18621 #+END_SRC 18622 18623 #+RESULTS: table-length 18624 : 4 18625 @end example 18626 18627 When passing a table, you can treat specially the row, or the 18628 column, containing labels for the columns, or the rows, in the 18629 table. 18630 18631 @cindex @samp{colnames}, header argument 18632 The @samp{colnames} header argument accepts @samp{yes}, @samp{no}, or @samp{nil} values. 18633 The default value is @samp{nil}: if an input table has column 18634 names---because the second row is a horizontal rule---then Org 18635 removes the column names, processes the table, puts back the column 18636 names, and then writes the table to the results block. Using @samp{yes}, 18637 Org does the same to the first row, even if the initial table does 18638 not contain any horizontal rule. When set to @samp{no}, Org does not 18639 pre-process column names at all. 18640 18641 @example 18642 #+NAME: less-cols 18643 | a | 18644 |---| 18645 | b | 18646 | c | 18647 18648 #+BEGIN_SRC python :var tab=less-cols :colnames nil 18649 return [[val + '*' for val in row] for row in tab] 18650 #+END_SRC 18651 18652 #+RESULTS: 18653 | a | 18654 |----| 18655 | b* | 18656 | c* | 18657 @end example 18658 18659 @cindex @samp{rownames}, header argument 18660 Similarly, the @samp{rownames} header argument can take two values: @samp{yes} 18661 or @samp{no}. When set to @samp{yes}, Org removes the first column, processes 18662 the table, puts back the first column, and then writes the table to 18663 the results block. The default is @samp{no}, which means Org does not 18664 pre-process the first column. Note that Emacs Lisp code blocks 18665 ignore @samp{rownames} header argument because of the ease of 18666 table-handling in Emacs. 18667 18668 @example 18669 #+NAME: with-rownames 18670 | one | 1 | 2 | 3 | 4 | 5 | 18671 | two | 6 | 7 | 8 | 9 | 10 | 18672 18673 #+BEGIN_SRC python :var tab=with-rownames :rownames yes 18674 return [[val + 10 for val in row] for row in tab] 18675 #+END_SRC 18676 18677 #+RESULTS: 18678 | one | 11 | 12 | 13 | 14 | 15 | 18679 | two | 16 | 17 | 18 | 19 | 20 | 18680 @end example 18681 @end table 18682 18683 To refer to a table in another file, join the filename and table name with 18684 a colon, for example: @samp{:var table=other-file.org:example-table}. 18685 18686 @table @asis 18687 @item list 18688 A simple named list. 18689 18690 @example 18691 #+NAME: example-list 18692 - simple 18693 - not 18694 - nested 18695 - list 18696 18697 #+BEGIN_SRC emacs-lisp :var x=example-list 18698 (print x) 18699 #+END_SRC 18700 18701 #+RESULTS: 18702 | simple | list | 18703 @end example 18704 18705 Note that only the top level list items are passed along. Nested 18706 list items are ignored. 18707 18708 @item code block without arguments 18709 A code block name, as assigned by @samp{NAME} keyword from the example 18710 above, optionally followed by parentheses. 18711 18712 @example 18713 #+BEGIN_SRC emacs-lisp :var length=table-length() 18714 (* 2 length) 18715 #+END_SRC 18716 18717 #+RESULTS: 18718 : 8 18719 @end example 18720 18721 @item code block with arguments 18722 A code block name, as assigned by @samp{NAME} keyword, followed by 18723 parentheses and optional arguments passed within the parentheses. 18724 18725 @example 18726 #+NAME: double 18727 #+BEGIN_SRC emacs-lisp :var input=8 18728 (* 2 input) 18729 #+END_SRC 18730 18731 #+RESULTS: double 18732 : 16 18733 18734 #+NAME: squared 18735 #+BEGIN_SRC emacs-lisp :var input=double(input=1) 18736 (* input input) 18737 #+END_SRC 18738 18739 #+RESULTS: squared 18740 : 4 18741 @end example 18742 18743 @item literal example, or code block contents 18744 A code block or literal example block named with a @samp{NAME} keyword, 18745 followed by brackets (optional for example blocks). 18746 18747 @example 18748 #+NAME: literal-example 18749 #+BEGIN_EXAMPLE 18750 A literal example 18751 on two lines 18752 #+END_EXAMPLE 18753 18754 #+NAME: read-literal-example 18755 #+BEGIN_SRC emacs-lisp :var x=literal-example[] 18756 (concatenate #'string x " for you.") 18757 #+END_SRC 18758 18759 #+RESULTS: read-literal-example 18760 : A literal example 18761 : on two lines for you. 18762 @end example 18763 @end table 18764 18765 Indexing variable values enables referencing portions of a variable. 18766 Indexes are 0 based with negative values counting backwards from the 18767 end. If an index is separated by commas then each subsequent section 18768 indexes as the next dimension. Note that this indexing occurs 18769 @emph{before} other table-related header arguments are applied, such as 18770 @samp{hlines}, @samp{colnames} and @samp{rownames}. The following example assigns 18771 the last cell of the first row the table @samp{example-table} to the 18772 variable @samp{data}: 18773 18774 @example 18775 #+NAME: example-table 18776 | 1 | a | 18777 | 2 | b | 18778 | 3 | c | 18779 | 4 | d | 18780 18781 #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1] 18782 data 18783 #+END_SRC 18784 18785 #+RESULTS: 18786 : a 18787 @end example 18788 18789 Two integers separated by a colon reference a range of variable 18790 values. In that case the entire inclusive range is referenced. For 18791 example the following assigns the middle three rows of @samp{example-table} 18792 to @samp{data}. 18793 18794 @example 18795 #+NAME: example-table 18796 | 1 | a | 18797 | 2 | b | 18798 | 3 | c | 18799 | 4 | d | 18800 | 5 | 3 | 18801 18802 #+BEGIN_SRC emacs-lisp :var data=example-table[1:3] 18803 data 18804 #+END_SRC 18805 18806 #+RESULTS: 18807 | 2 | b | 18808 | 3 | c | 18809 | 4 | d | 18810 @end example 18811 18812 To pick the entire range, use an empty index, or the single character 18813 @samp{*}. @samp{0:-1} does the same thing. Example below shows how to 18814 reference the first column only. 18815 18816 @example 18817 #+NAME: example-table 18818 | 1 | a | 18819 | 2 | b | 18820 | 3 | c | 18821 | 4 | d | 18822 18823 #+BEGIN_SRC emacs-lisp :var data=example-table[,0] 18824 data 18825 #+END_SRC 18826 18827 #+RESULTS: 18828 | 1 | 2 | 3 | 4 | 18829 @end example 18830 18831 Index referencing can be used for tables and code blocks. Index 18832 referencing can handle any number of dimensions. Commas delimit 18833 multiple dimensions, as shown below. 18834 18835 @example 18836 #+NAME: 3D 18837 #+BEGIN_SRC emacs-lisp 18838 '(((1 2 3) (4 5 6) (7 8 9)) 18839 ((10 11 12) (13 14 15) (16 17 18)) 18840 ((19 20 21) (22 23 24) (25 26 27))) 18841 #+END_SRC 18842 18843 #+BEGIN_SRC emacs-lisp :var data=3D[1,,1] 18844 data 18845 #+END_SRC 18846 18847 #+RESULTS: 18848 | 11 | 14 | 17 | 18849 @end example 18850 18851 Note that row names and column names are not removed prior to variable 18852 indexing. You need to take them into account, even when @samp{colnames} or 18853 @samp{rownames} header arguments remove them. 18854 18855 Emacs lisp code can also set the values for variables. To 18856 differentiate a value from Lisp code, Org interprets any value 18857 starting with @samp{(}, @samp{[}, @samp{'} or @samp{`} as Emacs Lisp code. The result of 18858 evaluating that code is then assigned to the value of that variable. 18859 The following example shows how to reliably query and pass the file 18860 name of the Org mode buffer to a code block using headers. We need 18861 reliability here because the file's name could change once the code in 18862 the block starts executing. 18863 18864 @example 18865 #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both 18866 wc -w $filename 18867 #+END_SRC 18868 @end example 18869 18870 Note that values read from tables and lists are not mistakenly 18871 evaluated as Emacs Lisp code, as illustrated in the following example. 18872 18873 @example 18874 #+NAME: table 18875 | (a b c) | 18876 18877 #+HEADER: :var data=table[0,0] 18878 #+BEGIN_SRC perl 18879 $data 18880 #+END_SRC 18881 18882 #+RESULTS: 18883 : (a b c) 18884 @end example 18885 18886 @anchor{Using sessions} 18887 @subheading Using sessions 18888 18889 @cindex using sessions in code blocks 18890 @cindex @samp{session}, header argument 18891 Two code blocks can share the same environment. The @samp{session} header 18892 argument is for running multiple source code blocks under one session. 18893 Org runs code blocks with the same session name in the same 18894 interpreter process. 18895 18896 @table @asis 18897 @item @samp{none} 18898 Default. Each code block gets a new interpreter process to execute. 18899 The process terminates once the block is evaluated. 18900 18901 @item @var{STRING} 18902 Any string besides @samp{none} turns that string into the name of that 18903 session. For example, @samp{:session STRING} names it @samp{STRING}. If 18904 @samp{session} has no value, then the session name is derived from the 18905 source language identifier. Subsequent blocks with the same source 18906 code language use the same session. Depending on the language, 18907 state variables, code from other blocks, and the overall interpreted 18908 environment may be shared. Some interpreted languages support 18909 concurrent sessions when subsequent source code language blocks 18910 change session names. 18911 @end table 18912 18913 Only languages that provide interactive evaluation can have session 18914 support. Not all languages provide this support, such as C and ditaa. 18915 Even languages, such as Python and Haskell, that do support 18916 interactive evaluation impose limitations on allowable language 18917 constructs that can run interactively. Org inherits those limitations 18918 for those code blocks running in a session. 18919 18920 @anchor{Choosing a working directory} 18921 @subheading Choosing a working directory 18922 18923 @cindex working directory, in a code block 18924 @cindex @samp{dir}, header argument 18925 @cindex @samp{mkdirp}, header argument 18926 The @samp{dir} header argument specifies the default directory during code 18927 block execution. If it is absent, then the directory associated with 18928 the current buffer is used. In other words, supplying @samp{:dir 18929 DIRECTORY} temporarily has the same effect as changing the current 18930 directory with @kbd{M-x cd @key{RET} DIRECTORY}, and then not setting 18931 @samp{dir}. Under the surface, @samp{dir} simply sets the value of the Emacs 18932 variable @code{default-directory}. Setting @samp{mkdirp} header argument to 18933 a non-@code{nil} value creates the directory, if necessary. 18934 18935 Setting @samp{dir} to the symbol @code{attach} or the string @code{"'attach"} will 18936 set @samp{dir} to the directory returned by @code{(org-attach-dir)}, set @samp{:mkdir 18937 yes}, and insert any file paths, as when using @samp{:results file}, which 18938 are under the node's attachment directory using @samp{attachment:} links 18939 instead of the usual @samp{file:} links. Any returned path outside of the 18940 attachment directory will use @samp{file:} links as per usual. 18941 18942 For example, to save the plot file in the @samp{Work/} folder of the home 18943 directory---notice tilde is expanded: 18944 18945 @example 18946 #+BEGIN_SRC R :file myplot.png :dir ~/Work 18947 matplot(matrix(rnorm(100), 10), type="l") 18948 #+END_SRC 18949 @end example 18950 18951 To evaluate the code block on a remote machine, supply a remote 18952 directory name using Tramp syntax. For example: 18953 18954 @example 18955 #+BEGIN_SRC R :file plot.png :dir /scp:dand@@yakuba.princeton.edu: 18956 plot(1:10, main=system("hostname", intern=TRUE)) 18957 #+END_SRC 18958 @end example 18959 18960 Org first captures the text results as usual for insertion in the Org 18961 file. Then Org also inserts a link to the remote file, thanks to 18962 Emacs Tramp. Org constructs the remote path to the file name from 18963 @samp{dir} and @code{default-directory}, as illustrated here: 18964 18965 @example 18966 [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] 18967 @end example 18968 18969 18970 When @samp{dir} is used with @samp{session}, Org sets the starting directory for 18971 a new session. But Org does not alter the directory of an already 18972 existing session. 18973 18974 Do not use @samp{dir} with @samp{:exports results} or with @samp{:exports both} to 18975 avoid Org inserting incorrect links to remote files. That is because 18976 Org does not expand @code{default directory} to avoid some underlying 18977 portability issues. 18978 18979 @anchor{Inserting headers and footers} 18980 @subheading Inserting headers and footers 18981 18982 @cindex headers, in code blocks 18983 @cindex footers, in code blocks 18984 @cindex @samp{prologue}, header argument 18985 The @samp{prologue} header argument is for appending to the top of the code 18986 block for execution, like a reset instruction. For example, you may 18987 use @samp{:prologue "reset"} in a Gnuplot code block or, for every such 18988 block: 18989 18990 @lisp 18991 (add-to-list 'org-babel-default-header-args:gnuplot 18992 '((:prologue . "reset"))) 18993 18994 @end lisp 18995 18996 @cindex @samp{epilogue}, header argument 18997 Likewise, the value of the @samp{epilogue} header argument is for appending 18998 to the end of the code block for execution. 18999 19000 @node Evaluating Code Blocks 19001 @section Evaluating Code Blocks 19002 19003 @cindex code block, evaluating 19004 @cindex source code, evaluating 19005 @cindex @samp{RESULTS}, keyword 19006 19007 A note about security: With code evaluation comes the risk of harm. 19008 Org safeguards by prompting for user's permission before executing any 19009 code in the source block. To customize this safeguard, or disable it, 19010 see @ref{Code Evaluation Security}. 19011 19012 @anchor{How to evaluate source code} 19013 @subheading How to evaluate source code 19014 19015 Org captures the results of the code block evaluation and inserts them 19016 in the Org file, right after the code block. The insertion point is 19017 after a newline and the @samp{RESULTS} keyword. Org creates the @samp{RESULTS} 19018 keyword if one is not already there. More details in @ref{Results of Evaluation}. 19019 19020 By default, Org enables only Emacs Lisp code blocks for execution. 19021 See @ref{Languages} to enable other languages. 19022 19023 @kindex C-c C-c 19024 @kindex C-c C-v e 19025 @findex org-babel-execute-src-block 19026 Org provides many ways to execute code blocks. @kbd{C-c C-c} or 19027 @kbd{C-c C-v e} with the point on a code block@footnote{ The option 19028 @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code 19029 evaluation from the @kbd{C-c C-c} key binding.} calls the 19030 @code{org-babel-execute-src-block} function, which executes the code in the 19031 block, collects the results, and inserts them in the buffer. 19032 19033 @cindex @samp{CALL}, keyword 19034 @vindex org-babel-inline-result-wrap 19035 By calling a named code block@footnote{Actually, the constructs @samp{call_<name>()} and @samp{src_<lang>@{@}} 19036 are not evaluated when they appear in a keyword (see @ref{In-buffer Settings}).} from an Org mode buffer or 19037 a table. Org can call the named code blocks from the current Org mode 19038 buffer or from the ``Library of Babel'' (see @ref{Library of Babel}). 19039 19040 The syntax for @samp{CALL} keyword is: 19041 19042 @example 19043 #+CALL: <name>(<arguments>) 19044 #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments> 19045 @end example 19046 19047 The syntax for inline named code blocks is: 19048 19049 @example 19050 ... call_<name>(<arguments>) ... 19051 ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ... 19052 @end example 19053 19054 When inline syntax is used, the result is wrapped based on the 19055 variable @code{org-babel-inline-result-wrap}, which by default is set to 19056 @code{"=%s="} to produce verbatim text suitable for markup. 19057 19058 @table @asis 19059 @item @samp{<name>} 19060 This is the name of the code block (see @ref{Structure of Code Blocks}) 19061 to be evaluated in the current document. If the block is located in 19062 another file, start @samp{<name>} with the file name followed by 19063 a colon. For example, in order to execute a block named @samp{clear-data} 19064 in @samp{file.org}, you can write the following: 19065 19066 @example 19067 #+CALL: file.org:clear-data() 19068 @end example 19069 19070 @item @samp{<arguments>} 19071 Org passes arguments to the code block using standard function call 19072 syntax. For example, a @samp{#+CALL:} line that passes @samp{4} to a code 19073 block named @samp{double}, which declares the header argument @samp{:var n=2}, 19074 would be written as: 19075 19076 @example 19077 #+CALL: double(n=4) 19078 @end example 19079 19080 19081 @noindent 19082 Note how this function call syntax is different from the header 19083 argument syntax. 19084 19085 @item @samp{<inside header arguments>} 19086 Org passes inside header arguments to the named code block using the 19087 header argument syntax. Inside header arguments apply to code block 19088 evaluation. For example, @samp{[:results output]} collects results 19089 printed to stdout during code execution of that block. Note how 19090 this header argument syntax is different from the function call 19091 syntax. 19092 19093 @item @samp{<end header arguments>} 19094 End header arguments affect the results returned by the code block. 19095 For example, @samp{:results html} wraps the results in a @samp{#+BEGIN_EXPORT 19096 html} block before inserting the results in the Org buffer. 19097 @end table 19098 19099 @anchor{Limit code block evaluation} 19100 @subheading Limit code block evaluation 19101 19102 @cindex @samp{eval}, header argument 19103 @cindex control code block evaluation 19104 The @samp{eval} header argument can limit evaluation of specific code 19105 blocks and @samp{CALL} keyword. It is useful for protection against 19106 evaluating untrusted code blocks by prompting for a confirmation. 19107 19108 @table @asis 19109 @item @samp{yes} 19110 Org always evaluates the source code without asking permission. 19111 19112 @item @samp{never} or @samp{no} 19113 Org never evaluates the source code. 19114 19115 @item @samp{query} 19116 Org prompts the user for permission to evaluate the source code. 19117 19118 @item @samp{never-export} or @samp{no-export} 19119 Org does not evaluate the source code when exporting, yet the user 19120 can evaluate it interactively. 19121 19122 @item @samp{query-export} 19123 Org prompts the user for permission to evaluate the source code 19124 during export. 19125 @end table 19126 19127 If @samp{eval} header argument is not set, then Org determines whether to 19128 evaluate the source code from the @code{org-confirm-babel-evaluate} 19129 variable (see @ref{Code Evaluation Security}). 19130 19131 @anchor{Cache results of evaluation} 19132 @subheading Cache results of evaluation 19133 19134 @cindex @samp{cache}, header argument 19135 @cindex cache results of code evaluation 19136 The @samp{cache} header argument is for caching results of evaluating code 19137 blocks. Caching results can avoid re-evaluating a code block that 19138 have not changed since the previous run. To benefit from the cache 19139 and avoid redundant evaluations, the source block must have a result 19140 already present in the buffer, and neither the header 19141 arguments---including the value of @samp{var} references---nor the text of 19142 the block itself has changed since the result was last computed. This 19143 feature greatly helps avoid long-running calculations. For some edge 19144 cases, however, the cached results may not be reliable. 19145 19146 The caching feature is best for when code blocks are pure functions, 19147 that is functions that return the same value for the same input 19148 arguments (see @ref{Environment of a Code Block}), and that do not have 19149 side effects, and do not rely on external variables other than the 19150 input arguments. Functions that depend on a timer, file system 19151 objects, and random number generators are clearly unsuitable for 19152 caching. 19153 19154 A note of warning: when @samp{cache} is used in a session, caching may 19155 cause unexpected results. 19156 19157 When the caching mechanism tests for any source code changes, it does 19158 not expand noweb style references (see @ref{Noweb Reference Syntax}). 19159 19160 The @samp{cache} header argument can have one of two values: @samp{yes} or @samp{no}. 19161 19162 @table @asis 19163 @item @samp{no} 19164 Default. No caching of results; code block evaluated every time. 19165 19166 @item @samp{yes} 19167 Whether to run the code or return the cached results is determined 19168 by comparing the SHA1 hash value of the combined code block and 19169 arguments passed to it. This hash value is packed on the 19170 @samp{#+RESULTS:} line from previous evaluation. When hash values match, 19171 Org does not evaluate the code block. When hash values mismatch, 19172 Org evaluates the code block, inserts the results, recalculates the 19173 hash value, and updates @samp{#+RESULTS:} line. 19174 @end table 19175 19176 In this example, both functions are cached. But @samp{caller} runs only if 19177 the result from @samp{random} has changed since the last run. 19178 19179 @example 19180 #+NAME: random 19181 #+BEGIN_SRC R :cache yes 19182 runif(+1) 19183 #+END_SRC 19184 19185 #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random 19186 0.4659510825295 19187 19188 #+NAME: caller 19189 #+BEGIN_SRC emacs-lisp :var x=random :cache yes 19190 x 19191 #+END_SRC 19192 19193 #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller 19194 0.254227238707244 19195 @end example 19196 19197 @node Results of Evaluation 19198 @section Results of Evaluation 19199 19200 @cindex code block, results of evaluation 19201 @cindex source code, results of evaluation 19202 19203 @cindex @samp{results}, header argument 19204 How Org handles results of a code block execution depends on many 19205 header arguments working together. The primary determinant, however, 19206 is the @samp{results} header argument. It accepts four classes of options. 19207 Each code block can take only one option per class: 19208 19209 @table @asis 19210 @item Collection 19211 For how the results should be collected from the code block; 19212 19213 @item Type 19214 For which type of result the code block will return; affects how Org 19215 processes and inserts results in the Org buffer; 19216 19217 @item Format 19218 For the result; affects how Org processes results; 19219 19220 @item Handling 19221 For inserting results once they are properly formatted. 19222 @end table 19223 19224 @anchor{Collection} 19225 @subheading Collection 19226 19227 Collection options specify the results. Choose one of the options; 19228 they are mutually exclusive. 19229 19230 @table @asis 19231 @item @samp{value} 19232 Default for most Babel libraries@footnote{Actually, the constructs @samp{call_<name>()} and @samp{src_<lang>@{@}} 19233 are not evaluated when they appear in a keyword (see @ref{In-buffer Settings}).}. Functional mode. Org 19234 gets the value by wrapping the code in a function definition in the 19235 language of the source block. That is why when using @samp{:results 19236 value}, code should execute like a function and return a value. For 19237 languages like Python, an explicit @code{return} statement is mandatory 19238 when using @samp{:results value}. Result is the value returned by the 19239 last statement in the code block. 19240 19241 When evaluating the code block in a session (see @ref{Environment of a Code Block}), Org passes the code to an interpreter running as an 19242 interactive Emacs inferior process. Org gets the value from the 19243 source code interpreter's last statement output. Org has to use 19244 language-specific methods to obtain the value. For example, from 19245 the variable @code{_} in Ruby, and the value of @code{.Last.value} in R@. 19246 19247 @item @samp{output} 19248 Scripting mode. Org passes the code to an external process running 19249 the interpreter. Org returns the contents of the standard output 19250 stream as text results. 19251 19252 When using a session, Org passes the code to the interpreter running 19253 as an interactive Emacs inferior process. Org concatenates any text 19254 output from the interpreter and returns the collection as a result. 19255 @end table 19256 19257 @anchor{Type} 19258 @subheading Type 19259 19260 Type tells what result types to expect from the execution of the code 19261 block. Choose one of the options; they are mutually exclusive. 19262 19263 The default behavior is to automatically determine the result type. 19264 The result type detection depends on the code block language, as 19265 described in the documentation for individual languages. See 19266 @ref{Languages}. 19267 19268 @table @asis 19269 @item @samp{table} 19270 @itemx @samp{vector} 19271 Interpret the results as an Org table. If the result is a single 19272 value, create a table with one row and one column. Usage example: 19273 @samp{:results value table}. 19274 19275 @cindex @samp{hlines}, header argument 19276 In-between each table row or below the table headings, sometimes 19277 results have horizontal lines, which are also known as ``hlines''. 19278 The @samp{hlines} argument with the default @samp{no} value strips such lines 19279 from the input table. For most code, this is desirable, or else 19280 those @samp{hline} symbols raise unbound variable errors. A @samp{yes} 19281 accepts such lines, as demonstrated in the following example. 19282 19283 @example 19284 #+NAME: many-cols 19285 | a | b | c | 19286 |---+---+---| 19287 | d | e | f | 19288 |---+---+---| 19289 | g | h | i | 19290 19291 #+NAME: no-hline 19292 #+BEGIN_SRC python :var tab=many-cols :hlines no 19293 return tab 19294 #+END_SRC 19295 19296 #+RESULTS: no-hline 19297 | a | b | c | 19298 | d | e | f | 19299 | g | h | i | 19300 19301 #+NAME: hlines 19302 #+BEGIN_SRC python :var tab=many-cols :hlines yes 19303 return tab 19304 #+END_SRC 19305 19306 #+RESULTS: hlines 19307 | a | b | c | 19308 |---+---+---| 19309 | d | e | f | 19310 |---+---+---| 19311 | g | h | i | 19312 @end example 19313 19314 @item @samp{list} 19315 Interpret the results as an Org list. If the result is a single 19316 value, create a list of one element. 19317 19318 @item @samp{scalar} 19319 @itemx @samp{verbatim} 19320 Interpret literally and insert as quoted text. Do not create 19321 a table. Usage example: @samp{:results value verbatim}. 19322 19323 @item @samp{file} 19324 Interpret as a filename. Save the results of execution of the code 19325 block to that file, then insert a link to it. You can control both 19326 the filename and the description associated to the link. 19327 19328 @cindex @samp{file}, header argument 19329 @cindex @samp{output-dir}, header argument 19330 Org first tries to generate the filename from the value of the 19331 @samp{file} header argument and the directory specified using the 19332 @samp{output-dir} header arguments. If @samp{output-dir} is not specified, 19333 Org assumes it is the current directory. 19334 19335 @example 19336 #+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/ 19337 size(2cm); 19338 draw(unitcircle); 19339 #+END_SRC 19340 @end example 19341 19342 @cindex @samp{file-ext}, header argument 19343 If @samp{file} header argument is missing, Org generates the base name of 19344 the output file from the name of the code block, and its extension 19345 from the @samp{file-ext} header argument. In that case, both the name 19346 and the extension are mandatory. 19347 19348 @example 19349 #+name: circle 19350 #+BEGIN_SRC asymptote :results value file :file-ext pdf 19351 size(2cm); 19352 draw(unitcircle); 19353 #+END_SRC 19354 @end example 19355 19356 @cindex @samp{file-desc}, header argument 19357 The @samp{file-desc} header argument defines the description (see @ref{Link Format}) for the link. If @samp{file-desc} is present but has no value, 19358 the @samp{file} value is used as the link description. When this 19359 argument is not present, the description is omitted. If you want to 19360 provide the @samp{file-desc} argument but omit the description, you can 19361 provide it with an empty vector (i.e., :file-desc []). 19362 19363 @cindex @samp{sep}, header argument 19364 By default, Org assumes that a table written to a file has 19365 TAB-delimited output. You can choose a different separator with 19366 the @samp{sep} header argument. 19367 19368 @cindex @samp{file-mode}, header argument 19369 The @samp{file-mode} header argument defines the file permissions. To 19370 make it executable, use @samp{:file-mode (identity #o755)}. 19371 19372 @example 19373 #+BEGIN_SRC shell :results file :file script.sh :file-mode (identity #o755) 19374 echo "#!/bin/bash" 19375 echo "echo Hello World" 19376 #+END_SRC 19377 @end example 19378 @end table 19379 19380 @anchor{Format} 19381 @subheading Format 19382 19383 Format pertains to the type of the result returned by the code block. 19384 Choose one of the options; they are mutually exclusive. The default 19385 follows from the type specified above. 19386 19387 @table @asis 19388 @item @samp{code} 19389 Result enclosed in a code block. Useful for parsing. Usage 19390 example: @samp{:results value code}. 19391 19392 @item @samp{drawer} 19393 Result wrapped in a @samp{RESULTS} drawer. Useful for containing @samp{raw} 19394 or @samp{org} results for later scripting and automated processing. 19395 Usage example: @samp{:results value drawer}. 19396 19397 @item @samp{html} 19398 Results enclosed in a @samp{BEGIN_EXPORT html} block. Usage example: 19399 @samp{:results value html}. 19400 19401 @item @samp{latex} 19402 Results enclosed in a @samp{BEGIN_EXPORT latex} block. Usage example: 19403 @samp{:results value latex}. 19404 19405 @item @samp{link} 19406 @itemx @samp{graphics} 19407 When used along with @samp{file} type, the result is a link to the file 19408 specified in @samp{:file} header argument. However, unlike plain @samp{file} 19409 type, code block output is not written to the disk. The block is 19410 expected to generate the file by its side-effects only, as in the 19411 following example: 19412 19413 @example 19414 #+begin_src shell :results file link :file "org-mode-unicorn.svg" 19415 wget -c "https://orgmode.org/resources/img/org-mode-unicorn.svg" 19416 #+end_src 19417 19418 #+RESULTS: 19419 [[file:org-mode-unicorn.svg]] 19420 @end example 19421 19422 @item @samp{org} 19423 Results enclosed in a @samp{BEGIN_SRC org} block. For comma-escape, 19424 either @kbd{@key{TAB}} in the block, or export the file. Usage 19425 example: @samp{:results value org}. 19426 19427 @item @samp{pp} 19428 Result converted to pretty-print source code. Enclosed in a code 19429 block. Languages supported: Emacs Lisp, Python, and Ruby. Usage 19430 example: @samp{:results value pp}. 19431 19432 @item @samp{raw} 19433 Interpreted as raw Org mode. Inserted directly into the buffer. 19434 Aligned if it is a table. Usage example: @samp{:results value raw}. 19435 @end table 19436 19437 @cindex @samp{wrap}, header argument 19438 The @samp{wrap} header argument unconditionally marks the results block by 19439 appending strings to @samp{#+BEGIN_} and @samp{#+END_}. If no string is 19440 specified, Org wraps the results in a @samp{#+BEGIN_results} 19441 @dots{} @samp{#+END_results} block. It takes precedent over the @samp{results} 19442 value listed above. E.g., 19443 19444 @example 19445 #+BEGIN_SRC emacs-lisp :results html :wrap EXPORT markdown 19446 "<blink>Welcome back to the 90's</blink>" 19447 #+END_SRC 19448 19449 #+RESULTS: 19450 #+BEGIN_EXPORT markdown 19451 <blink>Welcome back to the 90's</blink> 19452 #+END_EXPORT 19453 @end example 19454 19455 @anchor{Handling} 19456 @subheading Handling 19457 19458 Handling options after collecting the results. Choose one of the 19459 options; they are mutually exclusive. 19460 19461 @table @asis 19462 @item @samp{replace} 19463 Default. Insert results in the Org buffer. Remove previous 19464 results. Usage example: @samp{:results output replace}. 19465 19466 @item @samp{silent} 19467 Do not insert results in the Org mode buffer, but echo them in the 19468 minibuffer. Usage example: @samp{:results output silent}. 19469 19470 @item @samp{none} 19471 Compute results, but do not do anything with them. No inserting in 19472 the Org mode buffer nor echo them in the minibuffer. The results 19473 can still be used when referenced from another code block. 19474 Usage example: @samp{:results none}. 19475 19476 @item @samp{discard} 19477 Ignore the results completely. This option is similar to @samp{none}, 19478 but no processing is performed on the return value. Calling the 19479 code block programmatically (see @ref{How to evaluate source code}) or by 19480 reference (see @ref{Passing arguments} and @ref{Noweb Reference Syntax}) will 19481 always yield nil. 19482 19483 @item @samp{append} 19484 Append results to the Org buffer. Latest results are at the bottom. 19485 Does not remove previous results. Usage example: @samp{:results output 19486 append}. 19487 19488 @item @samp{prepend} 19489 Prepend results to the Org buffer. Latest results are at the top. 19490 Does not remove previous results. Usage example: @samp{:results output 19491 prepend}. 19492 @end table 19493 19494 @anchor{Post-processing} 19495 @subheading Post-processing 19496 19497 @cindex @samp{post}, header argument 19498 @cindex @samp{*this*}, in @samp{post} header argument 19499 The @samp{post} header argument is for post-processing results from block 19500 evaluation. When @samp{post} has any value, Org binds the results to 19501 @code{*this*} variable for easy passing to @samp{var} header argument 19502 specifications (see @ref{Environment of a Code Block}). That makes results 19503 available to other code blocks, or even for direct Emacs Lisp code 19504 execution. 19505 19506 The following two examples illustrate @samp{post} header argument in 19507 action. The first one shows how to attach an @samp{ATTR_LATEX} keyword 19508 using @samp{post}. 19509 19510 @example 19511 #+NAME: attr_wrap 19512 #+BEGIN_SRC sh :var data="" :var width="\\textwidth" :results output 19513 echo "#+ATTR_LATEX: :width $width" 19514 echo "$data" 19515 #+END_SRC 19516 19517 #+HEADER: :file /tmp/it.png 19518 #+BEGIN_SRC dot :post attr_wrap(width="5cm", data=*this*) :results drawer 19519 digraph@{ 19520 a -> b; 19521 b -> c; 19522 c -> a; 19523 @} 19524 #+end_src 19525 19526 #+RESULTS: 19527 :RESULTS: 19528 #+ATTR_LATEX :width 5cm 19529 [[file:/tmp/it.png]] 19530 :END: 19531 @end example 19532 19533 The second example shows use of @samp{colnames} header argument in @samp{post} 19534 to pass data between code blocks. 19535 19536 @example 19537 #+NAME: round-tbl 19538 #+BEGIN_SRC emacs-lisp :var tbl="" fmt="%.3f" 19539 (mapcar (lambda (row) 19540 (mapcar (lambda (cell) 19541 (if (numberp cell) 19542 (format fmt cell) 19543 cell)) 19544 row)) 19545 tbl) 19546 #+end_src 19547 19548 #+BEGIN_SRC R :colnames yes :post round-tbl[:colnames yes](*this*) 19549 set.seed(42) 19550 data.frame(foo=rnorm(1)) 19551 #+END_SRC 19552 19553 #+RESULTS: 19554 | foo | 19555 |-------| 19556 | 1.371 | 19557 @end example 19558 19559 @node Exporting Code Blocks 19560 @section Exporting Code Blocks 19561 19562 @cindex code block, exporting 19563 @cindex source code, exporting 19564 19565 It is possible to export the @emph{code} of code blocks, the @emph{results} of 19566 code block evaluation, @emph{both} the code and the results of code block 19567 evaluation, or @emph{none}. Org defaults to exporting @emph{code} for most 19568 languages and @emph{results} for inline code blocks. For some languages, 19569 such as ditaa, Org defaults to @emph{results} both in ordinary source 19570 blocks and in inline source blocks. To export just the body of code 19571 blocks, see @ref{Literal Examples}. To selectively export subtrees of an 19572 Org document, see @ref{Exporting}. 19573 19574 @cindex @samp{exports}, header argument 19575 The @samp{exports} header argument is to specify if that part of the Org 19576 file is exported to, say, HTML or @LaTeX{} formats. 19577 19578 @table @asis 19579 @item @samp{code} 19580 The default. The body of code is included into the exported file. 19581 Example: @samp{:exports code}. 19582 19583 @item @samp{results} 19584 The results of evaluation of the code is included in the exported 19585 file. Example: @samp{:exports results}. 19586 19587 @item @samp{both} 19588 Both the code and results of evaluation are included in the exported 19589 file. Example: @samp{:exports both}. 19590 19591 @item @samp{none} 19592 Neither the code nor the results of evaluation is included in the 19593 exported file. Whether the code is evaluated at all depends on 19594 other options. Example: @samp{:exports none}. 19595 @end table 19596 19597 If a source block is named using @samp{NAME} keyword, the same name will be 19598 assigned to the results of evaluation. This way, fuzzy links pointing 19599 to the named source blocks exported using @samp{:exports results} will 19600 remain valid and point to the results of evaluation. 19601 19602 Results of evaluation of a named block can also be explicitly named 19603 using a separate @samp{NAME} keyword. The name value set via @samp{NAME} 19604 keyword will be preferred over the parent source block. 19605 19606 @example 19607 #+NAME: code name 19608 #+BEGIN_SRC emacs-lisp :exports both value 19609 (+ 1 2) 19610 #+END_SRC 19611 19612 #+NAME: results name 19613 #+RESULTS: code name 19614 3 19615 19616 This [[code name][link]] will point to the code block. 19617 Another [[results name][link]] will point to the results. 19618 @end example 19619 19620 19621 Explicit setting of the result name may be necessary when a named code 19622 block is exported using @samp{:exports both}. Links to such block may 19623 arbitrarily point either to the code block or to its results when 19624 results do not have a distinct name. 19625 19626 Note that all the links pointing to a source block exported using 19627 @samp{:exports none} will be broken. This will make export process fail, 19628 unless broken links are allowed during export (see @ref{Export Settings}). 19629 19630 @vindex org-export-use-babel 19631 To stop Org from evaluating code blocks to speed exports, use the 19632 header argument @samp{:eval never-export} (see @ref{Evaluating Code Blocks}). 19633 To stop Org from evaluating code blocks for greater security, set the 19634 @code{org-export-use-babel} variable to @code{nil}, but understand that header 19635 arguments will have no effect. 19636 19637 Turning off evaluation comes in handy when batch processing. For 19638 example, markup languages for wikis, which have a high risk of 19639 untrusted code. Stopping code block evaluation also stops evaluation 19640 of all header arguments of the code block. This may not be desirable 19641 in some circumstances. So during export, to allow evaluation of just 19642 the header arguments but not any code evaluation in the source block, 19643 set @samp{:eval never-export} (see @ref{Evaluating Code Blocks}). 19644 19645 Org never evaluates code blocks in commented subtrees when exporting 19646 (see @ref{Comment Lines}). On the other hand, Org does evaluate code 19647 blocks in subtrees excluded from export (see @ref{Export Settings}). 19648 19649 @node Extracting Source Code 19650 @section Extracting Source Code 19651 19652 @cindex tangling 19653 @cindex source code, extracting 19654 @cindex code block, extracting source code 19655 19656 Extracting source code from code blocks is a basic task in literate 19657 programming. Org has features to make this easy. In literate 19658 programming parlance, documents on creation are @emph{woven} with code and 19659 documentation, and on export, the code is tangled for execution by 19660 a computer. Org facilitates weaving and tangling for producing, 19661 maintaining, sharing, and exporting literate programming documents. 19662 Org provides extensive customization options for extracting source 19663 code. 19664 19665 When Org tangles code blocks, it expands, merges, and transforms them. 19666 Then Org recomposes them into one or more separate files, as 19667 configured through the options. During this tangling process, Org 19668 expands variables in the source code, and resolves any noweb style 19669 references (see @ref{Noweb Reference Syntax}). 19670 19671 @anchor{Header arguments} 19672 @subheading Header arguments 19673 19674 @cindex @samp{tangle}, header argument 19675 The @samp{tangle} header argument specifies if the code block is exported 19676 to source file(s). 19677 19678 @table @asis 19679 @item @samp{yes} 19680 Export the code block to source file. The file name for the source 19681 file is derived from the name of the Org file, and the file 19682 extension is derived from the source code language identifier. 19683 Example: @samp{:tangle yes}. 19684 19685 @item @samp{no} 19686 The default. Do not extract the code in a source code file. 19687 Example: @samp{:tangle no}. 19688 19689 @item @var{FILENAME} 19690 Export the code block to source file whose file name is derived from 19691 any string passed to the @samp{tangle} header argument. Org derives the 19692 file name as being relative to the directory of the Org file's 19693 location. Example: @samp{:tangle FILENAME}. 19694 @end table 19695 19696 @cindex @samp{mkdirp}, header argument 19697 The @samp{mkdirp} header argument creates parent directories for tangled 19698 files if the directory does not exist. A @samp{yes} value enables 19699 directory creation whereas @samp{no} inhibits it. 19700 19701 @cindex @samp{comments}, header argument 19702 The @samp{comments} header argument controls inserting comments into 19703 tangled files. These are above and beyond whatever comments may 19704 already exist in the code block. 19705 19706 @table @asis 19707 @item @samp{no} 19708 The default. Do not insert any extra comments during tangling. 19709 19710 @item @samp{link} 19711 Wrap the code block in comments. Include links pointing back to the 19712 place in the Org file from where the code was tangled. 19713 19714 @item @samp{yes} 19715 Kept for backward compatibility; same as @samp{link}. 19716 19717 @item @samp{org} 19718 Nearest headline text from Org file is inserted as comment. The 19719 exact text that is inserted is picked from the leading context of 19720 the source block. 19721 19722 @item @samp{both} 19723 Includes both @samp{link} and @samp{org} options. 19724 19725 @item @samp{noweb} 19726 Includes @samp{link} option, expands noweb references (see @ref{Noweb Reference Syntax}), and wraps them in link comments inside the body 19727 of the code block. 19728 @end table 19729 19730 @cindex @samp{padline}, header argument 19731 The @samp{padline} header argument controls insertion of newlines to pad 19732 source code in the tangled file. 19733 19734 @table @asis 19735 @item @samp{yes} 19736 Default. Insert a newline before and after each code block in the 19737 tangled file. 19738 19739 @item @samp{no} 19740 Do not insert newlines to pad the tangled code blocks. 19741 @end table 19742 19743 @cindex @samp{shebang}, header argument 19744 The @samp{shebang} header argument can turn results into executable script 19745 files. By setting it to a string value---for example, @samp{:shebang 19746 "#!/bin/bash"}---Org inserts that string as the first line of the 19747 tangled file that the code block is extracted to. Org then turns on 19748 the tangled file's executable permission. 19749 19750 @cindex @samp{tangle-mode}, header argument 19751 The @samp{tangle-mode} header argument specifies what permissions to set 19752 for tangled files by @code{set-file-modes}. Permissions are given by an 19753 octal value, which can be provided calling the @code{identity} function on 19754 an elisp octal value. For instance, to create a read-only file one may 19755 use @samp{:tangle-mode (identity #o444)}. To reduce the verbosity required, 19756 a octal shorthand is defined, @samp{oXXX} (@samp{o} for octal). Using this, our 19757 read-only example is @samp{:tangle-mode o444}. Omitting the @samp{o} prefix will 19758 cause the argument to be interpreted as an integer, which can lead to 19759 unexpected results (@samp{444} is the same as @samp{o674}). 19760 Two other shorthands are recognized, ls-style strings like 19761 @samp{rw-r--r--}, and chmod-style permissions like @samp{g+w}. 19762 Note that chmod-style permissions are based on 19763 @code{org-babel-tangle-default-file-mode}, which is @samp{#o544} by default. 19764 19765 When @samp{:tangle-mode} and @samp{:shebang} are both specified, the give 19766 @samp{:tangle-mode} will override the permissions from @samp{:shebang}. When 19767 multiple source code blocks tangle to a single file with conflicting 19768 @samp{:tangle-mode} header arguments, Org's behavior is undefined. 19769 19770 @cindex @samp{no-expand}, header argument 19771 By default Org expands code blocks during tangling. The @samp{no-expand} 19772 header argument turns off such expansions. Note that one side-effect 19773 of expansion by @code{org-babel-expand-src-block} also assigns values (see 19774 @ref{Environment of a Code Block}) to variables. Expansions also replace 19775 noweb references with their targets (see @ref{Noweb Reference Syntax}). 19776 Some of these expansions may cause premature assignment, hence this 19777 option. This option makes a difference only for tangling. It has no 19778 effect when exporting since code blocks for execution have to be 19779 expanded anyway. 19780 19781 @anchor{Functions} 19782 @subheading Functions 19783 19784 @table @asis 19785 @item @code{org-babel-tangle} 19786 @findex org-babel-tangle 19787 @kindex C-c C-v t 19788 Tangle the current file. Bound to @kbd{C-c C-v t}. 19789 19790 With prefix argument only tangle the current code block. 19791 19792 @item @code{org-babel-tangle-file} 19793 @findex org-babel-tangle-file 19794 @kindex C-c C-v f 19795 Choose a file to tangle. Bound to @kbd{C-c C-v f}. 19796 @end table 19797 19798 @anchor{Tangle hooks} 19799 @subheading Tangle hooks 19800 19801 @table @asis 19802 @item @code{org-babel-pre-tangle-hook} 19803 @vindex org-babel-pre-tangle-hook 19804 This hook is run before the tangle process begins. The active 19805 buffer is buffer to be tangled. 19806 19807 @item @code{org-babel-tangle-body-hook} 19808 @vindex org-babel-tangle-body-hook 19809 This hook is run from a temporary buffer containing expanded code of 19810 every tangled code block. The hook can modify the expanded code as 19811 needed. The contents of the current buffer will be used as actual 19812 code block expansion. 19813 19814 @item @code{org-babel-post-tangle-hook} 19815 @vindex org-babel-post-tangle-hook 19816 This hook is run from within code files tangled by 19817 @code{org-babel-tangle}, making it suitable for post-processing, 19818 compilation, and evaluation of code in the tangled files. 19819 19820 @item @code{org-babel-tangle-finished-hook} 19821 @vindex org-babel-tangle-finished-hook 19822 This hook is run after post-tangle hooks, in the original buffer. 19823 @end table 19824 19825 @anchor{Jumping between code and Org} 19826 @subheading Jumping between code and Org 19827 19828 @findex org-babel-tangle-jump-to-org 19829 Debuggers normally link errors and messages back to the source code. 19830 But for tangled files, we want to link back to the Org file, not to 19831 the tangled source file. To make this extra jump, Org uses 19832 @code{org-babel-tangle-jump-to-org} function with two additional source 19833 code block header arguments: 19834 19835 @enumerate 19836 @item 19837 Set @samp{padline} to true---this is the default setting. 19838 @item 19839 Set @samp{comments} to @samp{link}, which makes Org insert links to the Org 19840 file. 19841 @end enumerate 19842 19843 @node Languages 19844 @section Languages 19845 19846 @cindex babel, languages 19847 @cindex source code, languages 19848 @cindex code block, languages 19849 19850 Code blocks in dozens of languages are supported. See Worg website 19851 for @uref{https://orgmode.org/worg/org-contrib/babel/languages/index.html, language specific documentation}. 19852 19853 @vindex org-babel-load-languages 19854 By default, only Emacs Lisp is enabled for evaluation. To enable or 19855 disable other languages, customize the @code{org-babel-load-languages} 19856 variable either through the Emacs customization interface, or by 19857 adding code to the init file as shown next. 19858 19859 In this example, evaluation is disabled for Emacs Lisp, and enabled 19860 for R@. 19861 19862 @lisp 19863 (org-babel-do-load-languages 19864 'org-babel-load-languages 19865 '((emacs-lisp . nil) 19866 (R . t))) 19867 @end lisp 19868 19869 Note that this is not the only way to enable a language. Org also 19870 enables languages when loaded with @code{require} statement. For example, 19871 the following enables execution of Clojure code blocks: 19872 19873 @lisp 19874 (require 'ob-clojure) 19875 @end lisp 19876 19877 @node Editing Source Code 19878 @section Editing Source Code 19879 19880 @cindex code block, editing 19881 @cindex source code, editing 19882 19883 @kindex C-c ' 19884 Use @kbd{C-c '} to edit the current code block. It opens a new 19885 major mode edit buffer containing the body of the source code block, 19886 ready for any edits. Use @kbd{C-c '} again to close the buffer 19887 and return to the Org buffer. 19888 19889 @kindex C-x C-s 19890 @vindex org-edit-src-auto-save-idle-delay 19891 @cindex auto-save, in code block editing 19892 @kbd{C-x C-s} saves the buffer and updates the contents of the 19893 Org buffer. Set @code{org-edit-src-auto-save-idle-delay} to save the base 19894 buffer after a certain idle delay time. Set 19895 @code{org-edit-src-turn-on-auto-save} to auto-save this buffer into 19896 a separate file using Auto-save mode. 19897 19898 While editing the source code in the major mode, the Org Src minor 19899 mode remains active. It provides these customization variables as 19900 described below. For even more variables, look in the customization 19901 group @code{org-edit-structure}. 19902 19903 @table @asis 19904 @item @code{org-src-lang-modes} 19905 @vindex org-src-lang-modes 19906 If an Emacs major-mode named @code{<LANG>-mode} exists, where 19907 @var{<LANG>} is the language identifier from code block's 19908 header line, then the edit buffer uses that major mode. Use this 19909 variable to arbitrarily map language identifiers to major modes. 19910 19911 @item @code{org-src-window-setup} 19912 @vindex org-src-window-setup 19913 For specifying Emacs window arrangement when the new edit buffer is 19914 created. 19915 19916 @item @code{org-src-preserve-indentation} 19917 @cindex indentation, in code blocks 19918 @vindex org-src-preserve-indentation 19919 Default is @code{nil}. Source code is indented. This indentation 19920 applies during export or tangling, and depending on the context, may 19921 alter leading spaces and tabs. When non-@code{nil}, source code is 19922 aligned with the leftmost column. No lines are modified during 19923 export or tangling, which is very useful for white-space sensitive 19924 languages, such as Python. 19925 19926 @item @code{org-src-ask-before-returning-to-edit-buffer} 19927 @vindex org-src-ask-before-returning-to-edit-buffer 19928 When @code{nil}, Org returns to the edit buffer without further prompts. 19929 The default prompts for a confirmation. 19930 @end table 19931 19932 @vindex org-src-fontify-natively 19933 @vindex org-src-block-faces 19934 Set @code{org-src-fontify-natively} to non-@code{nil} to turn on native code 19935 fontification in the @emph{Org} buffer. Fontification of code blocks can 19936 give visual separation of text and code on the display page. To 19937 further customize the appearance of @code{org-block} for specific 19938 languages, customize @code{org-src-block-faces}. The following example 19939 shades the background of regular blocks, and colors source blocks only 19940 for Python and Emacs Lisp languages. 19941 19942 @lisp 19943 (require 'color) 19944 (set-face-attribute 'org-block nil :background 19945 (color-darken-name 19946 (face-attribute 'default :background) 3)) 19947 19948 (setq org-src-block-faces '(("emacs-lisp" (:background "#EEE2FF")) 19949 ("python" (:background "#E5FFB8")))) 19950 @end lisp 19951 19952 @node Noweb Reference Syntax 19953 @section Noweb Reference Syntax 19954 19955 @cindex code block, noweb reference 19956 @cindex syntax, noweb 19957 @cindex source code, noweb reference 19958 19959 @cindex @samp{noweb-ref}, header argument 19960 Source code blocks can include references to other source code blocks, 19961 using a noweb@footnote{ For noweb literate programming details, see 19962 @uref{https://www.cs.tufts.edu/~nr/noweb/}.} style syntax: 19963 19964 @example 19965 <<CODE-BLOCK-ID>> 19966 @end example 19967 19968 19969 @noindent 19970 where @var{CODE-BLOCK-ID} refers to either the @samp{NAME} of a single 19971 source code block, or a collection of one or more source code blocks 19972 sharing the same @samp{noweb-ref} header argument (see @ref{Using Header Arguments}). Org can replace such references with the source code of 19973 the block or blocks being referenced, or, in the case of a single 19974 source code block named with @samp{NAME}, with the results of an evaluation 19975 of that block. 19976 19977 @cindex @samp{noweb}, header argument 19978 The @samp{noweb} header argument controls expansion of noweb syntax 19979 references. Expansions occur when source code blocks are evaluated, 19980 tangled, or exported. 19981 19982 @table @asis 19983 @item @samp{no} 19984 Default. No expansion of noweb syntax references in the body of the 19985 code when evaluating, tangling, or exporting. 19986 19987 @item @samp{yes} 19988 Expansion of noweb syntax references in the body of the code block 19989 when evaluating, tangling, or exporting. 19990 19991 @item @samp{tangle} 19992 Expansion of noweb syntax references in the body of the code block 19993 when tangling. No expansion when evaluating or exporting. 19994 19995 @item @samp{strip-tangle} 19996 Expansion of noweb syntax references in the body of the code block 19997 when evaluating or exporting. Removes noweb syntax references 19998 when exporting. 19999 20000 @item @samp{no-export} 20001 Expansion of noweb syntax references in the body of the code block 20002 when evaluating or tangling. No expansion when exporting. 20003 20004 @item @samp{strip-export} 20005 Expansion of noweb syntax references in the body of the code block 20006 when expanding prior to evaluating or tangling. Removes noweb 20007 syntax references when exporting. 20008 20009 @item @samp{eval} 20010 Expansion of noweb syntax references in the body of the code block 20011 only before evaluating. 20012 @end table 20013 20014 In the most simple case, the contents of a single source block is 20015 inserted within other blocks. Thus, in following example, 20016 20017 @example 20018 #+NAME: initialization 20019 #+BEGIN_SRC emacs-lisp 20020 (setq sentence "Never a foot too far, even.") 20021 #+END_SRC 20022 20023 #+BEGIN_SRC emacs-lisp :noweb yes 20024 <<initialization>> 20025 (reverse sentence) 20026 #+END_SRC 20027 @end example 20028 20029 @noindent 20030 the second code block is expanded as 20031 20032 @example 20033 #+BEGIN_SRC emacs-lisp :noweb yes 20034 (setq sentence "Never a foot too far, even.") 20035 (reverse sentence) 20036 #+END_SRC 20037 @end example 20038 20039 You may also include the contents of multiple blocks sharing a common 20040 @samp{noweb-ref} header argument, which can be set at the file, subtree, 20041 or code block level. In the example Org file shown next, the body of 20042 the source code in each block is extracted for concatenation to a pure 20043 code file when tangled. 20044 20045 @example 20046 #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh 20047 <<fullest-disk>> 20048 #+END_SRC 20049 * the mount point of the fullest disk 20050 :PROPERTIES: 20051 :header-args: :noweb-ref fullest-disk 20052 :END: 20053 20054 ** query all mounted disks 20055 #+BEGIN_SRC sh 20056 df \ 20057 #+END_SRC 20058 20059 ** strip the header row 20060 #+BEGIN_SRC sh 20061 |sed '1d' \ 20062 #+END_SRC 20063 20064 ** output mount point of fullest disk 20065 #+BEGIN_SRC sh 20066 |awk '@{if (u < +$5) @{u = +$5; m = $6@}@} END @{print m@}' 20067 #+END_SRC 20068 @end example 20069 20070 @cindex @samp{noweb-sep}, header argument 20071 By default a newline separates each noweb reference concatenation. To 20072 use a different separator, edit the @samp{noweb-sep} header argument. 20073 20074 Alternatively, Org can include the results of evaluation of a single 20075 code block rather than its body. Evaluation occurs when parentheses, 20076 possibly including arguments, are appended to the code block name, as 20077 shown below. 20078 20079 @example 20080 <<NAME(optional arguments)>> 20081 @end example 20082 20083 20084 Note that in this case, a code block name set by @samp{NAME} keyword is 20085 required; the reference set by @samp{noweb-ref} will not work when 20086 evaluation is desired. 20087 20088 Here is an example that demonstrates how the exported content changes 20089 when noweb style references are used with parentheses versus without. 20090 Given: 20091 20092 @example 20093 #+NAME: some-code 20094 #+BEGIN_SRC python :var num=0 :results output :exports none 20095 print(num*10) 20096 #+END_SRC 20097 @end example 20098 20099 @noindent 20100 this code block: 20101 20102 @example 20103 #+BEGIN_SRC text :noweb yes 20104 <<some-code>> 20105 #+END_SRC 20106 @end example 20107 20108 @noindent 20109 expands to: 20110 20111 @example 20112 print(num*10) 20113 @end example 20114 20115 20116 Below, a similar noweb style reference is used, but with parentheses, 20117 while setting a variable @samp{num} to 10: 20118 20119 @example 20120 #+BEGIN_SRC text :noweb yes 20121 <<some-code(num=10)>> 20122 #+END_SRC 20123 @end example 20124 20125 @noindent 20126 Note that the expansion now contains the results of the code block 20127 @samp{some-code}, not the code block itself: 20128 20129 @example 20130 100 20131 @end example 20132 20133 20134 Noweb insertions honor prefix characters that appear before the noweb 20135 syntax reference. This behavior is illustrated in the following 20136 example. Because the @samp{<<example>>} noweb reference appears behind the 20137 SQL comment syntax, each line of the expanded noweb reference is 20138 commented. With: 20139 20140 @example 20141 #+NAME: example 20142 #+BEGIN_SRC text 20143 this is the 20144 multi-line body of example 20145 #+END_SRC 20146 @end example 20147 20148 @noindent 20149 this code block: 20150 20151 @example 20152 #+BEGIN_SRC sql :noweb yes 20153 ---<<example>> 20154 #+END_SRC 20155 @end example 20156 20157 @noindent 20158 expands to: 20159 20160 @example 20161 #+BEGIN_SRC sql :noweb yes 20162 ---this is the 20163 ---multi-line body of example 20164 #+END_SRC 20165 @end example 20166 20167 Since this change does not affect noweb replacement text without 20168 newlines in them, inline noweb references are acceptable. 20169 20170 This feature can also be used for management of indentation in 20171 exported code snippets. With: 20172 20173 @example 20174 #+NAME: if-true 20175 #+BEGIN_SRC python :exports none 20176 print('do things when true') 20177 #+end_src 20178 20179 #+name: if-false 20180 #+begin_src python :exports none 20181 print('do things when false') 20182 #+end_src 20183 @end example 20184 20185 @noindent 20186 this code block: 20187 20188 @example 20189 #+begin_src python :noweb yes :results output 20190 if true: 20191 <<if-true>> 20192 else: 20193 <<if-false>> 20194 #+end_src 20195 @end example 20196 20197 @noindent 20198 expands to: 20199 20200 @example 20201 if true: 20202 print('do things when true') 20203 else: 20204 print('do things when false') 20205 @end example 20206 20207 This prefix behavior can be turned off in a block by setting the 20208 @samp{noweb-prefix} header argument to @samp{no}, as in: 20209 20210 @example 20211 #+BEGIN_SRC elisp :noweb-prefix no 20212 (setq example-data "<<example>>") 20213 #+END_SRC 20214 @end example 20215 20216 @noindent 20217 which expands to: 20218 20219 @example 20220 (setq example-data "this is the 20221 multi-line body of example") 20222 @end example 20223 20224 When in doubt about the outcome of a source code block expansion, you 20225 can preview the results with the following command: 20226 20227 @table @asis 20228 @item @kbd{C-c C-v v} or @kbd{C-c C-v C-v} (@code{org-babel-expand-src-block}) 20229 @findex org-babel-expand-src-block 20230 @kindex C-c C-v v 20231 @kindex C-c C-v C-v 20232 Expand the current source code block according to its header 20233 arguments and pop open the results in a preview buffer. 20234 @end table 20235 20236 @node Library of Babel 20237 @section Library of Babel 20238 20239 @cindex babel, library of 20240 @cindex source code, library 20241 @cindex code block, library 20242 20243 The ``Library of Babel'' is a collection of code blocks. Like 20244 a function library, these code blocks can be called from other Org 20245 files. A collection of useful code blocks is available on @uref{https://orgmode.org/worg/library-of-babel.html, Worg}. For 20246 remote code block evaluation syntax, see @ref{Evaluating Code Blocks}. 20247 20248 @kindex C-c C-v i 20249 @findex org-babel-lob-ingest 20250 For any user to add code to the library, first save the code in 20251 regular code blocks of an Org file, and then load the Org file with 20252 @code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}. 20253 20254 @node Key bindings and Useful Functions 20255 @section Key bindings and Useful Functions 20256 20257 @cindex code block, key bindings 20258 20259 Many common Org mode key sequences are re-bound depending on 20260 the context. 20261 20262 Active key bindings in code blocks: 20263 20264 @kindex C-c C-c 20265 @findex org-babel-execute-src-block 20266 @kindex C-c C-o 20267 @findex org-babel-open-src-block-result 20268 @kindex M-UP 20269 @findex org-babel-load-in-session 20270 @kindex M-DOWN 20271 @findex org-babel-pop-to-session 20272 @multitable @columnfractions 0.2 0.55 20273 @headitem Key binding 20274 @tab Function 20275 @item @kbd{C-c C-c} 20276 @tab @code{org-babel-execute-src-block} 20277 @item @kbd{C-c C-o} 20278 @tab @code{org-babel-open-src-block-result} 20279 @item @kbd{M-@key{UP}} 20280 @tab @code{org-babel-load-in-session} 20281 @item @kbd{M-@key{DOWN}} 20282 @tab @code{org-babel-pop-to-session} 20283 @end multitable 20284 20285 Active key bindings in Org mode buffer: 20286 20287 @kindex C-c C-v p 20288 @kindex C-c C-v C-p 20289 @kindex C-c C-v n 20290 @kindex C-c C-v C-n 20291 @kindex C-c C-v e 20292 @kindex C-c C-v C-e 20293 @kindex C-c C-v o 20294 @kindex C-c C-v C-o 20295 @kindex C-c C-v v 20296 @kindex C-c C-v C-v 20297 @kindex C-c C-v u 20298 @kindex C-c C-v C-u 20299 @kindex C-c C-v g 20300 @kindex C-c C-v C-g 20301 @kindex C-c C-v r 20302 @kindex C-c C-v C-r 20303 @kindex C-c C-v b 20304 @kindex C-c C-v C-b 20305 @kindex C-c C-v s 20306 @kindex C-c C-v C-s 20307 @kindex C-c C-v d 20308 @kindex C-c C-v C-d 20309 @kindex C-c C-v t 20310 @kindex C-c C-v C-t 20311 @kindex C-c C-v f 20312 @kindex C-c C-v C-f 20313 @kindex C-c C-v c 20314 @kindex C-c C-v C-c 20315 @kindex C-c C-v j 20316 @kindex C-c C-v C-j 20317 @kindex C-c C-v l 20318 @kindex C-c C-v C-l 20319 @kindex C-c C-v i 20320 @kindex C-c C-v C-i 20321 @kindex C-c C-v I 20322 @kindex C-c C-v C-I 20323 @kindex C-c C-v z 20324 @kindex C-c C-v C-z 20325 @kindex C-c C-v a 20326 @kindex C-c C-v C-a 20327 @kindex C-c C-v h 20328 @kindex C-c C-v C-h 20329 @kindex C-c C-v x 20330 @kindex C-c C-v C-x 20331 @findex org-babel-previous-src-block 20332 @findex org-babel-next-src-block 20333 @findex org-babel-execute-maybe 20334 @findex org-babel-open-src-block-result 20335 @findex org-babel-expand-src-block 20336 @findex org-babel-goto-src-block-head 20337 @findex org-babel-goto-named-src-block 20338 @findex org-babel-goto-named-result 20339 @findex org-babel-execute-buffer 20340 @findex org-babel-execute-subtree 20341 @findex org-babel-demarcate-block 20342 @findex org-babel-tangle 20343 @findex org-babel-tangle-file 20344 @findex org-babel-check-src-block 20345 @findex org-babel-insert-header-arg 20346 @findex org-babel-load-in-session 20347 @findex org-babel-lob-ingest 20348 @findex org-babel-view-src-block-info 20349 @findex org-babel-switch-to-session-with-code 20350 @findex org-babel-sha1-hash 20351 @findex org-babel-describe-bindings 20352 @findex org-babel-do-key-sequence-in-edit-buffer 20353 @multitable @columnfractions 0.45 0.55 20354 @headitem Key binding 20355 @tab Function 20356 @item @kbd{C-c C-v p} or @kbd{C-c C-v C-p} 20357 @tab @code{org-babel-previous-src-block} 20358 @item @kbd{C-c C-v n} or @kbd{C-c C-v C-n} 20359 @tab @code{org-babel-next-src-block} 20360 @item @kbd{C-c C-v e} or @kbd{C-c C-v C-e} 20361 @tab @code{org-babel-execute-maybe} 20362 @item @kbd{C-c C-v o} or @kbd{C-c C-v C-o} 20363 @tab @code{org-babel-open-src-block-result} 20364 @item @kbd{C-c C-v v} or @kbd{C-c C-v C-v} 20365 @tab @code{org-babel-expand-src-block} 20366 @item @kbd{C-c C-v u} or @kbd{C-c C-v C-u} 20367 @tab @code{org-babel-goto-src-block-head} 20368 @item @kbd{C-c C-v g} or @kbd{C-c C-v C-g} 20369 @tab @code{org-babel-goto-named-src-block} 20370 @item @kbd{C-c C-v r} or @kbd{C-c C-v C-r} 20371 @tab @code{org-babel-goto-named-result} 20372 @item @kbd{C-c C-v b} or @kbd{C-c C-v C-b} 20373 @tab @code{org-babel-execute-buffer} 20374 @item @kbd{C-c C-v s} or @kbd{C-c C-v C-s} 20375 @tab @code{org-babel-execute-subtree} 20376 @item @kbd{C-c C-v d} or @kbd{C-c C-v C-d} 20377 @tab @code{org-babel-demarcate-block} 20378 @item @kbd{C-c C-v t} or @kbd{C-c C-v C-t} 20379 @tab @code{org-babel-tangle} 20380 @item @kbd{C-c C-v f} or @kbd{C-c C-v C-f} 20381 @tab @code{org-babel-tangle-file} 20382 @item @kbd{C-c C-v c} or @kbd{C-c C-v C-c} 20383 @tab @code{org-babel-check-src-block} 20384 @item @kbd{C-c C-v j} or @kbd{C-c C-v C-j} 20385 @tab @code{org-babel-insert-header-arg} 20386 @item @kbd{C-c C-v l} or @kbd{C-c C-v C-l} 20387 @tab @code{org-babel-load-in-session} 20388 @item @kbd{C-c C-v i} or @kbd{C-c C-v C-i} 20389 @tab @code{org-babel-lob-ingest} 20390 @item @kbd{C-c C-v I} or @kbd{C-c C-v C-I} 20391 @tab @code{org-babel-view-src-block-info} 20392 @item @kbd{C-c C-v z} or @kbd{C-c C-v C-z} 20393 @tab @code{org-babel-switch-to-session-with-code} 20394 @item @kbd{C-c C-v a} or @kbd{C-c C-v C-a} 20395 @tab @code{org-babel-sha1-hash} 20396 @item @kbd{C-c C-v h} or @kbd{C-c C-v C-h} 20397 @tab @code{org-babel-describe-bindings} 20398 @item @kbd{C-c C-v x} or @kbd{C-c C-v C-x} 20399 @tab @code{org-babel-do-key-sequence-in-edit-buffer} 20400 @end multitable 20401 20402 @node Batch Execution 20403 @section Batch Execution 20404 20405 @cindex code block, batch execution 20406 @cindex source code, batch execution 20407 20408 Org mode features, including working with source code facilities can 20409 be invoked from the command line. This enables building shell scripts 20410 for batch processing, running automated system tasks, and expanding 20411 Org mode's usefulness. 20412 20413 The sample script shows batch processing of multiple files using 20414 @code{org-babel-tangle}. 20415 20416 @example 20417 #!/bin/sh 20418 # Tangle files with Org mode 20419 # 20420 emacs -Q --batch --eval " 20421 (progn 20422 (require 'ob-tangle) 20423 (dolist (file command-line-args-left) 20424 (with-current-buffer (find-file-noselect file) 20425 (org-babel-tangle)))) 20426 " "$@@" 20427 @end example 20428 20429 @node Miscellaneous 20430 @chapter Miscellaneous 20431 20432 @menu 20433 * Completion:: @kbd{M-@key{TAB}} guesses completions. 20434 * Structure Templates:: Quick insertion of structural elements. 20435 * Speed Keys:: Electric commands at the beginning of a headline. 20436 * Clean View:: Getting rid of leading stars in the outline. 20437 * Execute commands in the active region:: Execute commands on multiple items in Org or agenda view. 20438 * Dynamic Headline Numbering:: Display and update outline numbering. 20439 * The Very Busy @kbd{C-c C-c} Key:: When in doubt, press @kbd{C-c C-c}. 20440 * In-buffer Settings:: Overview of keywords. 20441 * Regular Expressions:: Elisp regular expressions. 20442 * Org Syntax:: Formal description of Org's syntax. 20443 * Documentation Access:: Read documentation about current syntax. 20444 * Escape Character:: Prevent Org from interpreting your writing. 20445 * Code Evaluation Security:: Org files evaluate in-line code. 20446 * Interaction:: With other Emacs packages. 20447 * TTY Keys:: Using Org on a tty. 20448 * Protocols:: External access to Emacs and Org. 20449 * Org Crypt:: Encrypting Org files. 20450 * Org Mobile:: Viewing and capture on a mobile device. 20451 @end menu 20452 20453 @node Completion 20454 @section Completion 20455 20456 @cindex completion, of @TeX{} symbols 20457 @cindex completion, of TODO keywords 20458 @cindex completion, of dictionary words 20459 @cindex completion, of option keywords 20460 @cindex completion, of tags 20461 @cindex completion, of property keys 20462 @cindex completion, of link abbreviations 20463 @cindex @TeX{} symbol completion 20464 @cindex TODO keywords completion 20465 @cindex dictionary word completion 20466 @cindex option keyword completion 20467 @cindex tag completion 20468 @cindex link abbreviations, completion of 20469 20470 Org has in-buffer completions. Unlike minibuffer completions, which 20471 are useful for quick command interactions, Org's in-buffer completions 20472 are more suitable for content creation in Org documents. Type one or 20473 more letters and invoke the hot key to complete the text in-place. 20474 Depending on the context and the keys, Org offers different types of 20475 completions. No minibuffer is involved. Such mode-specific hot keys 20476 have become an integral part of Emacs and Org provides several 20477 shortcuts. 20478 20479 @table @asis 20480 @item @kbd{M-@key{TAB}} 20481 @kindex M-TAB 20482 20483 Complete word at point. 20484 20485 @itemize 20486 @item 20487 At the beginning of an empty headline, complete TODO keywords. 20488 20489 @item 20490 After @samp{\}, complete @TeX{} symbols supported by the exporter. 20491 20492 @item 20493 After @samp{:} in a headline, complete tags. Org deduces the list of 20494 tags from the @samp{TAGS} in-buffer option (see @ref{Setting Tags}), the 20495 variable @code{org-tag-alist}, or from all tags used in the current 20496 buffer. 20497 20498 @item 20499 After @samp{:} and not in a headline, complete property keys. The list 20500 of keys is constructed dynamically from all keys used in the 20501 current buffer. 20502 20503 @item 20504 After @samp{[[}, complete link abbreviations (see @ref{Link Abbreviations}). 20505 20506 @item 20507 After @samp{[[*}, complete headlines in the current buffer so that they 20508 can be used in search links like: @samp{[[*find this headline]]} 20509 20510 @item 20511 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or 20512 file-specific @samp{OPTIONS}. After option keyword is complete, 20513 pressing @kbd{M-@key{TAB}} again inserts example settings for this 20514 keyword. 20515 20516 @item 20517 After @samp{STARTUP} keyword, complete startup items. 20518 20519 @item 20520 When point is anywhere else, complete dictionary words using 20521 Ispell. 20522 @end itemize 20523 @end table 20524 20525 @node Structure Templates 20526 @section Structure Templates 20527 20528 @cindex template insertion 20529 @cindex insertion, of templates 20530 20531 With just a few keystrokes, it is possible to insert empty structural 20532 blocks, such as @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC}, or to wrap existing 20533 text in such a block. 20534 20535 @table @asis 20536 @item @kbd{C-c C-,} (@code{org-insert-structure-template}) 20537 @findex org-insert-structure-template 20538 @kindex C-c C-, 20539 Prompt for a type of block structure, and insert the block at point. 20540 If the region is active, it is wrapped in the block. First prompts 20541 the user for keys, which are used to look up a structure type from 20542 the variable below. If the key is @kbd{@key{TAB}}, @kbd{@key{RET}}, 20543 or @kbd{@key{SPC}}, the user is prompted to enter a block type. 20544 @end table 20545 20546 @vindex org-structure-template-alist 20547 Available structure types are defined in 20548 @code{org-structure-template-alist}, see the docstring for adding or 20549 changing values. 20550 20551 @cindex Tempo 20552 @cindex template expansion 20553 @cindex insertion, of templates 20554 @vindex org-tempo-keywords-alist 20555 Org Tempo expands snippets to structures defined in 20556 @code{org-structure-template-alist} and @code{org-tempo-keywords-alist}. For 20557 example, @kbd{< s @key{TAB}} creates a code block. Enable it by 20558 customizing @code{org-modules} or add @samp{(require 'org-tempo)} to your Emacs 20559 init file@footnote{ For more information, please refer to the commentary 20560 section in @samp{org-tempo.el}.}. 20561 20562 @multitable @columnfractions 0.1 0.9 20563 @item @kbd{a} 20564 @tab @samp{#+BEGIN_EXPORT ascii} @dots{} @samp{#+END_EXPORT} 20565 @item @kbd{c} 20566 @tab @samp{#+BEGIN_CENTER} @dots{} @samp{#+END_CENTER} 20567 @item @kbd{C} 20568 @tab @samp{#+BEGIN_COMMENT} @dots{} @samp{#+END_COMMENT} 20569 @item @kbd{e} 20570 @tab @samp{#+BEGIN_EXAMPLE} @dots{} @samp{#+END_EXAMPLE} 20571 @item @kbd{E} 20572 @tab @samp{#+BEGIN_EXPORT} @dots{} @samp{#+END_EXPORT} 20573 @item @kbd{h} 20574 @tab @samp{#+BEGIN_EXPORT html} @dots{} @samp{#+END_EXPORT} 20575 @item @kbd{l} 20576 @tab @samp{#+BEGIN_EXPORT latex} @dots{} @samp{#+END_EXPORT} 20577 @item @kbd{q} 20578 @tab @samp{#+BEGIN_QUOTE} @dots{} @samp{#+END_QUOTE} 20579 @item @kbd{s} 20580 @tab @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC} 20581 @item @kbd{v} 20582 @tab @samp{#+BEGIN_VERSE} @dots{} @samp{#+END_VERSE} 20583 @end multitable 20584 20585 @node Speed Keys 20586 @section Speed Keys 20587 20588 @cindex speed keys 20589 20590 Single keystrokes can execute custom commands in an Org file when 20591 point is on a headline. Without the extra burden of a meta or 20592 modifier key, Speed Keys can speed navigation or execute custom 20593 commands. Besides faster navigation, Speed Keys may come in handy on 20594 small mobile devices that do not have full keyboards. Speed Keys may 20595 also work on TTY devices known for their problems when entering Emacs 20596 key chords. 20597 20598 @vindex org-use-speed-commands 20599 By default, Org has Speed Keys disabled. To activate Speed Keys, set 20600 the variable @code{org-use-speed-commands} to a non-@code{nil} value. To 20601 trigger a Speed Key, point must be at the beginning of an Org 20602 headline, before any of the stars. 20603 20604 @vindex org-speed-commands 20605 @findex org-speed-command-help 20606 Org comes with a pre-defined list of Speed Keys. To add or modify 20607 Speed Keys, customize the option @code{org-speed-commands}. For more 20608 details, see the variable's docstring. With Speed Keys activated, 20609 @kbd{M-x org-speed-command-help}, or @kbd{?} when point is at the 20610 beginning of an Org headline, shows currently active Speed Keys, 20611 including the user-defined ones. 20612 20613 @node Clean View 20614 @section A Cleaner Outline View 20615 20616 @cindex hiding leading stars 20617 @cindex dynamic indentation 20618 @cindex odd-levels-only outlines 20619 @cindex clean outline view 20620 20621 Org's outline with stars and no indents can look cluttered for short 20622 documents. For @emph{book-like} long documents, the effect is not as 20623 noticeable. Org provides an alternate stars and indentation scheme, 20624 as shown on the right in the following table. It displays only one 20625 star and indents text to line up with the heading: 20626 20627 @example 20628 * Top level headline | * Top level headline 20629 ** Second level | * Second level 20630 *** Third level | * Third level 20631 some text | some text 20632 *** Third level | * Third level 20633 more text | more text 20634 * Another top level headline | * Another top level headline 20635 @end example 20636 20637 Org can achieve this in two ways, (1) by just displaying the buffer in 20638 this way without changing it, or (2) by actually indenting every line 20639 in the desired amount with hard spaces and hiding leading stars. 20640 20641 @menu 20642 * Org Indent Mode:: 20643 * Hard indentation:: 20644 @end menu 20645 20646 @node Org Indent Mode 20647 @subsection Org Indent Mode 20648 20649 @cindex Indent mode 20650 @findex org-indent-mode 20651 To display the buffer in the indented view, activate Org Indent minor 20652 mode, using @kbd{M-x org-indent-mode}. Text lines that are not 20653 headlines are prefixed with virtual spaces to vertically align with 20654 the headline text@footnote{Org Indent mode also sets @code{wrap-prefix} correctly for 20655 indenting and wrapping long lines of headlines or text. This minor 20656 mode also handles Visual Line mode and directly applied settings 20657 through @code{word-wrap}.}. 20658 20659 @vindex org-indent-indentation-per-level 20660 To make more horizontal space, the headlines are shifted by two 20661 characters. Configure @code{org-indent-indentation-per-level} variable for 20662 a different number. 20663 20664 @vindex org-indent-mode-turns-on-hiding-stars 20665 @vindex org-indent-mode-turns-off-org-adapt-indentation 20666 By default, Org Indent mode turns off @code{org-adapt-indentation} and does 20667 hide leading stars by locally setting @code{org-hide-leading-stars} to @code{t}: 20668 only one star on each headline is visible, the rest are masked with 20669 the same font color as the background. If you want to customize this 20670 default behavior, see @code{org-indent-mode-turns-on-hiding-stars} and 20671 @code{org-indent-mode-turns-off-org-adapt-indentation}. 20672 20673 @vindex org-startup-indented 20674 To globally turn on Org Indent mode for all files, customize the 20675 variable @code{org-startup-indented}. To control it for individual files, 20676 use @samp{STARTUP} keyword as follows: 20677 20678 @example 20679 #+STARTUP: indent 20680 #+STARTUP: noindent 20681 @end example 20682 20683 @node Hard indentation 20684 @subsection Hard indentation 20685 20686 It is possible to use hard spaces to achieve the indentation instead, 20687 if the bare ASCII file should have the indented look also outside 20688 Emacs@footnote{This works, but requires extra effort. Org Indent mode is 20689 more convenient for most applications.}. With Org's support, you have to indent all lines to 20690 line up with the outline headers. You would use these settings@footnote{ 20691 @code{org-adapt-indentation} can also be set to @samp{'headline-data}, in which 20692 case only data lines below the headline will be indented.}: 20693 20694 @lisp 20695 (setq org-adapt-indentation t 20696 org-hide-leading-stars t 20697 org-odd-levels-only t) 20698 @end lisp 20699 20700 @table @asis 20701 @item @emph{Indentation of text below headlines} (@code{org-adapt-indentation}) 20702 @vindex org-adapt-indentation 20703 The first setting modifies paragraph filling, line wrapping, and 20704 structure editing commands to preserving or adapting the indentation 20705 as appropriate. 20706 20707 @item @emph{Hiding leading stars} (@code{org-hide-leading-stars}) 20708 @vindex org-hide-leading-stars 20709 @vindex org-hide, face 20710 The second setting makes leading stars invisible by applying the 20711 face @code{org-hide} to them. For per-file preference, use these file 20712 @samp{STARTUP} options: 20713 20714 @example 20715 #+STARTUP: hidestars 20716 #+STARTUP: showstars 20717 @end example 20718 20719 @item @emph{Odd levels} (@code{org-odd-levels-only}) 20720 @vindex org-odd-levels-only 20721 The third setting makes Org use only odd levels, 1, 3, 5, @dots{}, in 20722 the outline to create more indentation. On a per-file level, 20723 control this with: 20724 20725 @example 20726 #+STARTUP: odd 20727 #+STARTUP: oddeven 20728 @end example 20729 20730 To convert a file between single and double stars layouts, use 20731 @kbd{M-x org-convert-to-odd-levels} and @kbd{M-x org-convert-to-oddeven-levels}. 20732 @end table 20733 20734 @node Execute commands in the active region 20735 @section Execute commands in the active region 20736 20737 @vindex org-loop-over-headlines-in-active-region 20738 When in an Org buffer and the region is active, some commands will 20739 apply to all the subtrees in the active region. For example, hitting 20740 @kbd{C-c C-s} when multiple headlines are within the active region will 20741 successively prompt you for a new schedule date and time. To disable 20742 this, set the option @code{org-loop-over-headlines-in-active-region} to 20743 non-@code{t}, activate the region and run the command normally. 20744 20745 @vindex org-agenda-loop-over-headlines-in-active-region 20746 @code{org-agenda-loop-over-headlines-in-active-region} is the equivalent 20747 option of the agenda buffer, where you can also use @ref{Bulk remote editing selected entries, , bulk editing of 20748 selected entries}. 20749 20750 Not all commands can loop in the active region and what subtrees or 20751 headlines are considered can be refined: see the docstrings of these 20752 options for more details. 20753 20754 @node Dynamic Headline Numbering 20755 @section Dynamic Headline Numbering 20756 20757 @cindex Org Num mode 20758 @cindex number headlines 20759 The Org Num minor mode, toggled with @kbd{M-x org-num-mode}, 20760 displays outline numbering on top of headlines. It also updates it 20761 automatically upon changes to the structure of the document. 20762 20763 @vindex org-num-max-level 20764 @vindex org-num-skip-tags 20765 @vindex org-num-skip-commented 20766 @vindex org-num-skip-unnumbered 20767 By default, all headlines are numbered. You can limit numbering to 20768 specific headlines according to their level, tags, @samp{COMMENT} keyword, 20769 or @samp{UNNUMBERED} property. Set @code{org-num-max-level}, 20770 @code{org-num-skip-tags}, @code{org-num-skip-commented}, 20771 @code{org-num-skip-unnumbered}, or @code{org-num-skip-footnotes} accordingly. 20772 20773 @vindex org-num-skip-footnotes 20774 If @code{org-num-skip-footnotes} is non-@code{nil}, footnotes sections (see 20775 @ref{Creating Footnotes}) are not numbered either. 20776 20777 @vindex org-num-face 20778 @vindex org-num-format-function 20779 You can control how the numbering is displayed by setting 20780 @code{org-num-face} and @code{org-num-format-function}. 20781 20782 @vindex org-startup-numerated 20783 You can also turn this mode globally for all Org files by setting the 20784 option @code{org-startup-numerated} to @samp{t}, or locally on a file by using 20785 @samp{#+startup: num}. 20786 20787 @node The Very Busy @kbd{C-c C-c} Key 20788 @section The Very Busy @kbd{C-c C-c} Key 20789 20790 @kindex C-c C-c 20791 @cindex @kbd{C-c C-c}, overview 20792 20793 The @kbd{C-c C-c} key in Org serves many purposes depending on 20794 the context. It is probably the most over-worked, multi-purpose key 20795 combination in Org. Its uses are well documented throughout this 20796 manual, but here is a consolidated list for easy reference. 20797 20798 @itemize 20799 @item 20800 If column view (see @ref{Column View}) is on, exit column view. 20801 20802 @item 20803 If any highlights shown in the buffer from the creation of a sparse 20804 tree, or from clock display, remove such highlights. 20805 20806 @item 20807 If point is in one of the special @samp{KEYWORD} lines, scan the buffer 20808 for these lines and update the information. Also reset the Org file 20809 cache used to temporary store the contents of URLs used as values 20810 for keywords like @samp{SETUPFILE}. 20811 20812 @item 20813 If point is inside a table, realign the table. 20814 20815 @item 20816 If point is on a @samp{TBLFM} keyword, re-apply the formulas to the 20817 entire table. 20818 20819 @item 20820 If the current buffer is a capture buffer, close the note and file 20821 it. With a prefix argument, also jump to the target location after 20822 saving the note. 20823 20824 @item 20825 If point is on a @samp{<<<target>>>}, update radio targets and 20826 corresponding links in this buffer. 20827 20828 @item 20829 If point is on a property line or at the start or end of a property 20830 drawer, offer property commands. 20831 20832 @item 20833 If point is at a footnote reference, go to the corresponding 20834 definition, and @emph{vice versa}. 20835 20836 @item 20837 If point is on a statistics cookie, update it. 20838 20839 @item 20840 If point is in a plain list item with a checkbox, toggle the status 20841 of the checkbox. 20842 20843 @item 20844 If point is on a numbered item in a plain list, renumber the ordered 20845 list. 20846 20847 @item 20848 If point is on the @samp{#+BEGIN} line of a dynamic block, the block is 20849 updated. 20850 20851 @item 20852 If point is at a timestamp, fix the day name in the timestamp. 20853 @end itemize 20854 20855 @node In-buffer Settings 20856 @section Summary of In-Buffer Settings 20857 20858 @cindex in-buffer settings 20859 @cindex special keywords 20860 20861 In-buffer settings start with @samp{#+}, followed by a keyword, a colon, 20862 one or more spaces, and then a word for each setting. Org accepts 20863 multiple settings on the same line. Org also accepts multiple lines 20864 for a keyword. This manual describes these settings throughout. A 20865 summary follows here. 20866 20867 @cindex refresh set-up 20868 @kbd{C-c C-c} activates any changes to the in-buffer settings. 20869 Closing and reopening the Org file in Emacs also activates the 20870 changes. 20871 20872 @table @asis 20873 @item @samp{#+ARCHIVE: %s_done::} 20874 @cindex @samp{ARCHIVE}, keyword 20875 @vindex org-archive-location 20876 Sets the archive location of the agenda file. The corresponding 20877 variable is @code{org-archive-location}. 20878 20879 @item @samp{#+CATEGORY} 20880 @cindex @samp{CATEGORY}, keyword 20881 Sets the category of the agenda file, which applies to the entire 20882 document. 20883 20884 @item @samp{#+COLUMNS: %25ITEM ...} 20885 @cindex @samp{COLUMNS}, property 20886 Set the default format for columns view. This format applies when 20887 columns view is invoked in locations where no @samp{COLUMNS} property 20888 applies. 20889 20890 @item @samp{#+CONSTANTS: name1=value1 ...} 20891 @cindex @samp{CONSTANTS}, keyword 20892 @vindex org-table-formula-constants 20893 @vindex org-table-formula 20894 Set file-local values for constants that table formulas can use. 20895 This line sets the local variable 20896 @code{org-table-formula-constants-local}. The global version of this 20897 variable is @code{org-table-formula-constants}. 20898 20899 @item @samp{#+FILETAGS: :tag1:tag2:tag3:} 20900 @cindex @samp{FILETAGS}, keyword 20901 Set tags that all entries in the file inherit from, including the 20902 top-level entries. 20903 20904 @item @samp{#+LINK: linkword replace} 20905 @cindex @samp{LINK}, keyword 20906 @vindex org-link-abbrev-alist 20907 Each line specifies one abbreviation for one link. Use multiple 20908 @samp{LINK} keywords for more, see @ref{Link Abbreviations}. The 20909 corresponding variable is @code{org-link-abbrev-alist}. 20910 20911 @item @samp{#+PRIORITIES: highest lowest default} 20912 @cindex @samp{PRIORITIES}, keyword 20913 @vindex org-priority-highest 20914 @vindex org-priority-lowest 20915 @vindex org-priority-default 20916 This line sets the limits and the default for the priorities. All 20917 three must be either letters A--Z or numbers 0--9. The highest 20918 priority must have a lower ASCII number than the lowest priority. 20919 20920 @item @samp{#+PROPERTY: Property_Name Value} 20921 @cindex @samp{PROPERTY}, keyword 20922 This line sets a default inheritance value for entries in the 20923 current buffer, most useful for specifying the allowed values of 20924 a property. 20925 20926 @item @samp{#+SETUPFILE: file} 20927 @cindex @samp{SETUPFILE}, keyword 20928 The setup file or a URL pointing to such file is for additional 20929 in-buffer settings. Org loads this file and parses it for any 20930 settings in it only when Org opens the main file. If URL is 20931 specified, the contents are downloaded and stored in a temporary 20932 file cache. @kbd{C-c C-c} on the settings line parses and 20933 loads the file, and also resets the temporary file cache. Org also 20934 parses and loads the document during normal exporting process. Org 20935 parses the contents of this document as if it was included in the 20936 buffer. It can be another Org file. To visit the file---not 20937 a URL---use @kbd{C-c '} while point is on the line with the 20938 file name. 20939 20940 @item @samp{#+STARTUP:} 20941 @cindex @samp{STARTUP}, keyword 20942 Startup options Org uses when first visiting a file. 20943 20944 @vindex org-startup-folded 20945 The first set of options deals with the initial visibility of the 20946 outline tree. The corresponding variable for global default 20947 settings is @code{org-startup-folded} with a default value of 20948 @code{showeverything}. 20949 20950 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaa} 20951 @item @samp{overview} 20952 @tab Top-level headlines only. 20953 @item @samp{content} 20954 @tab All headlines. 20955 @item @samp{showall} 20956 @tab No folding on any entry. 20957 @item @samp{show2levels} 20958 @tab Headline levels 1-2. 20959 @item @samp{show3levels} 20960 @tab Headline levels 1-3. 20961 @item @samp{show4levels} 20962 @tab Headline levels 1-4. 20963 @item @samp{show5levels} 20964 @tab Headline levels 1-5. 20965 @item @samp{showeverything} 20966 @tab Show even drawer contents. 20967 @end multitable 20968 20969 @vindex org-startup-indented 20970 Dynamic virtual indentation is controlled by the variable 20971 @code{org-startup-indented}@footnote{ Note that Org Indent mode also sets the 20972 @code{wrap-prefix} property, such that Visual Line mode (or purely 20973 setting @code{word-wrap}) wraps long lines, including headlines, 20974 correctly indented.}. 20975 20976 @multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 20977 @item @samp{indent} 20978 @tab Start with Org Indent mode turned on. 20979 @item @samp{noindent} 20980 @tab Start with Org Indent mode turned off. 20981 @end multitable 20982 20983 @vindex org-startup-numerated 20984 Dynamic virtual numeration of headlines is controlled by the variable 20985 @code{org-startup-numerated}. 20986 20987 @multitable {aaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 20988 @item @samp{num} 20989 @tab Start with Org num mode turned on. 20990 @item @samp{nonum} 20991 @tab Start with Org num mode turned off. 20992 @end multitable 20993 20994 @vindex org-startup-align-all-tables 20995 Aligns tables consistently upon visiting a file. The 20996 corresponding variable is @code{org-startup-align-all-tables} with 20997 @code{nil} as default value. 20998 20999 @multitable {aaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 21000 @item @samp{align} 21001 @tab Align all tables. 21002 @item @samp{noalign} 21003 @tab Do not align tables on startup. 21004 @end multitable 21005 21006 @vindex org-startup-shrink-all-tables 21007 Shrink table columns with a width cookie. The corresponding 21008 variable is @code{org-startup-shrink-all-tables} with @code{nil} as 21009 default value. 21010 21011 @vindex org-startup-with-inline-images 21012 When visiting a file, inline images can be automatically 21013 displayed. The corresponding variable is 21014 @code{org-startup-with-inline-images}, with a default value @code{nil} to 21015 avoid delays when visiting a file. 21016 21017 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 21018 @item @samp{inlineimages} 21019 @tab Show inline images. 21020 @item @samp{noinlineimages} 21021 @tab Do not show inline images on startup. 21022 @end multitable 21023 21024 @vindex org-log-done 21025 @vindex org-log-note-clock-out 21026 @vindex org-log-repeat 21027 Logging the closing and reopening of TODO items and clock 21028 intervals can be configured using these options (see variables 21029 @code{org-log-done}, @code{org-log-note-clock-out}, and @code{org-log-repeat}). 21030 21031 @multitable {aaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 21032 @item @samp{logdone} 21033 @tab Record a timestamp when an item is marked as done. 21034 @item @samp{lognotedone} 21035 @tab Record timestamp and a note when DONE@. 21036 @item @samp{nologdone} 21037 @tab Do not record when items are marked as done. 21038 @item @samp{logrepeat} 21039 @tab Record a time when reinstating a repeating item. 21040 @item @samp{lognoterepeat} 21041 @tab Record a note when reinstating a repeating item. 21042 @item @samp{nologrepeat} 21043 @tab Do not record when reinstating repeating item. 21044 @item @samp{lognoteclock-out} 21045 @tab Record a note when clocking out. 21046 @item @samp{nolognoteclock-out} 21047 @tab Do not record a note when clocking out. 21048 @item @samp{logreschedule} 21049 @tab Record a timestamp when scheduling time changes. 21050 @item @samp{lognotereschedule} 21051 @tab Record a note when scheduling time changes. 21052 @item @samp{nologreschedule} 21053 @tab Do not record when a scheduling date changes. 21054 @item @samp{logredeadline} 21055 @tab Record a timestamp when deadline changes. 21056 @item @samp{lognoteredeadline} 21057 @tab Record a note when deadline changes. 21058 @item @samp{nologredeadline} 21059 @tab Do not record when a deadline date changes. 21060 @item @samp{logrefile} 21061 @tab Record a timestamp when refiling. 21062 @item @samp{lognoterefile} 21063 @tab Record a note when refiling. 21064 @item @samp{nologrefile} 21065 @tab Do not record when refiling. 21066 @end multitable 21067 21068 @vindex org-hide-leading-stars 21069 @vindex org-odd-levels-only 21070 Here are the options for hiding leading stars in outline 21071 headings, and for indenting outlines. The corresponding 21072 variables are @code{org-hide-leading-stars} and 21073 @code{org-odd-levels-only}, both with a default setting @code{nil} 21074 (meaning @samp{showstars} and @samp{oddeven}). 21075 21076 @multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 21077 @item @samp{hidestars} 21078 @tab Make all but one of the stars starting a headline invisible. 21079 @item @samp{showstars} 21080 @tab Show all stars starting a headline. 21081 @item @samp{indent} 21082 @tab Virtual indentation according to outline level. 21083 @item @samp{noindent} 21084 @tab No virtual indentation according to outline level. 21085 @item @samp{odd} 21086 @tab Allow only odd outline levels (1, 3, @dots{}). 21087 @item @samp{oddeven} 21088 @tab Allow all outline levels. 21089 @end multitable 21090 21091 @vindex org-put-time-stamp-overlays 21092 @vindex org-time-stamp-overlay-formats 21093 To turn on custom format overlays over timestamps (variables 21094 @code{org-put-time-stamp-overlays} and 21095 @code{org-time-stamp-overlay-formats}), use: 21096 21097 @multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaa} 21098 @item @samp{customtime} 21099 @tab Overlay custom time format. 21100 @end multitable 21101 21102 @vindex constants-unit-system 21103 The following options influence the table spreadsheet (variable 21104 @code{constants-unit-system}). 21105 21106 @multitable {aaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 21107 @item @samp{constcgs} 21108 @tab @samp{constants.el} should use the c-g-s unit system. 21109 @item @samp{constSI} 21110 @tab @samp{constants.el} should use the SI unit system. 21111 @end multitable 21112 21113 @vindex org-footnote-define-inline 21114 @vindex org-footnote-auto-label 21115 @vindex org-footnote-auto-adjust 21116 To influence footnote settings, use the following keywords. The 21117 corresponding variables are @code{org-footnote-define-inline}, 21118 @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}. 21119 21120 @multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 21121 @item @samp{fninline} 21122 @tab Define footnotes inline. 21123 @item @samp{fnnoinline} 21124 @tab Define footnotes in separate section. 21125 @item @samp{fnlocal} 21126 @tab Define footnotes near first reference, but not inline. 21127 @item @samp{fnprompt} 21128 @tab Prompt for footnote labels. 21129 @item @samp{fnauto} 21130 @tab Create @samp{[fn:1]}-like labels automatically (default). 21131 @item @samp{fnconfirm} 21132 @tab Offer automatic label for editing or confirmation. 21133 @item @samp{fnadjust} 21134 @tab Automatically renumber and sort footnotes. 21135 @item @samp{nofnadjust} 21136 @tab Do not renumber and sort automatically. 21137 @end multitable 21138 21139 @vindex org-hide-block-startup 21140 @vindex org-hide-drawer-startup 21141 To hide blocks or drawers on startup, use these keywords. The 21142 corresponding variables are @code{org-hide-block-startup} and 21143 @code{org-hide-drawer-startup}. 21144 21145 @multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 21146 @item @samp{hideblocks} 21147 @tab Hide all begin/end blocks on startup. 21148 @item @samp{nohideblocks} 21149 @tab Do not hide blocks on startup. 21150 @item @samp{hidedrawers} 21151 @tab Hide all begin/end blocks on startup. 21152 @item @samp{nohidedrawers} 21153 @tab Do not hide blocks on startup. 21154 @end multitable 21155 @end table 21156 21157 21158 @vindex org-pretty-entities 21159 The display of entities as UTF-8 characters is governed by the 21160 variable @code{org-pretty-entities} and the keywords 21161 21162 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 21163 @item @samp{entitiespretty} 21164 @tab Show entities as UTF-8 characters where possible. 21165 @item @samp{entitiesplain} 21166 @tab Leave entities plain. 21167 @end multitable 21168 21169 @table @asis 21170 @item @samp{#+TAGS: TAG1(c1) TAG2(c2)} 21171 @cindex @samp{TAGS}, keyword 21172 @vindex org-tag-alist 21173 These lines (several such lines are allowed) specify the valid tags 21174 in this file, and (potentially) the corresponding @emph{fast tag 21175 selection} keys. The corresponding variable is @code{org-tag-alist}. 21176 21177 @item @samp{#+TODO:}, @samp{#+SEQ_TODO:}, @samp{#+TYP_TODO:} 21178 @cindex @samp{SEQ_TODO}, keyword 21179 @cindex @samp{TODO}, keyword 21180 @cindex @samp{TYP_TODO}, keyword 21181 @vindex org-todo-keywords 21182 These lines set the TODO keywords and their interpretation in the 21183 current file. The corresponding variable is @code{org-todo-keywords}. 21184 @end table 21185 21186 @node Regular Expressions 21187 @section Regular Expressions 21188 21189 @cindex regular expressions syntax 21190 @cindex regular expressions, in searches 21191 21192 Org, as an Emacs mode, makes use of Elisp regular expressions for 21193 searching, matching and filtering. Elisp regular expressions have a 21194 somewhat different syntax then some common standards. Most notably, 21195 alternation is indicated using @samp{\|} and matching groups are denoted by 21196 @samp{\(...\)}. For example the string @samp{home\|work} matches either @samp{home} 21197 or @samp{work}. 21198 21199 For more information, see @ref{Regexps,Regular Expressions in Emacs,,emacs,}. 21200 21201 @node Org Syntax 21202 @section Org Syntax 21203 21204 A reference document providing a formal description of Org's syntax is 21205 available as @uref{https://orgmode.org/worg/dev/org-syntax.html, a draft on Worg}, written and maintained by Nicolas 21206 Goaziou. It defines Org's core internal concepts such as ``headlines'', 21207 ``sections'', ``affiliated keywords'', ``(greater) elements'' and ``objects''. 21208 Each part of an Org document belongs to one of the previous 21209 categories. 21210 21211 To explore the abstract structure of an Org buffer, run this in 21212 a buffer: 21213 21214 @example 21215 M-: (org-element-parse-buffer) <RET> 21216 @end example 21217 21218 21219 @noindent 21220 It outputs a list containing the buffer's content represented as an 21221 abstract structure. The export engine relies on the information 21222 stored in this list. Most interactive commands---e.g., for structure 21223 editing---also rely on the syntactic meaning of the surrounding 21224 context. 21225 21226 @cindex syntax checker 21227 @cindex linter 21228 @findex org-lint 21229 You can probe the syntax of your documents with the command 21230 21231 @example 21232 M-x org-lint <RET> 21233 @end example 21234 21235 21236 @noindent 21237 It runs a number of checks to find common mistakes. It then displays 21238 their location in a dedicated buffer, along with a description and 21239 a ``trust level'', since false-positive are possible. From there, you 21240 can operate on the reports with the following keys: 21241 21242 @multitable @columnfractions 0.22 0.78 21243 @item @kbd{C-j}, @kbd{@key{TAB}} 21244 @tab Display the offending line 21245 @item @kbd{@key{RET}} 21246 @tab Move point to the offending line 21247 @item @kbd{g} 21248 @tab Check the document again 21249 @item @kbd{h} 21250 @tab Hide all reports from the same checker 21251 @item @kbd{i} 21252 @tab Also remove them from all subsequent checks 21253 @item @kbd{S} 21254 @tab Sort reports by the column at point 21255 @end multitable 21256 21257 @node Documentation Access 21258 @section Context Dependent Documentation 21259 21260 @cindex documentation 21261 @cindex Info 21262 21263 @findex org-info-find-node 21264 @kindex C-c C-x I 21265 @kbd{C-c C-x I} in an Org file tries to open a suitable section 21266 of the Org manual depending on the syntax at point. For example, 21267 using it on a headline displays ``Document Structure'' section. 21268 21269 @kbd{q} closes the Info window. 21270 21271 @node Escape Character 21272 @section Escape Character 21273 21274 @cindex escape character 21275 @cindex zero width space 21276 You may sometimes want to write text that looks like Org syntax, but 21277 should really read as plain text. Org may use a specific escape 21278 character in some situations, i.e., a backslash in macros (see @ref{Macro Replacement}) and links (see @ref{Link Format}), or a comma in source and 21279 example blocks (see @ref{Literal Examples}). In the general case, however, 21280 we suggest to use the zero width space. You can insert one with any 21281 of the following: 21282 21283 @example 21284 C-x 8 <RET> zero width space <RET> 21285 C-x 8 <RET> 200B <RET> 21286 @end example 21287 21288 21289 For example, in order to write @samp{[[1,2]]} as-is in your document, you 21290 may write instead 21291 21292 @example 21293 [X[1,2]] 21294 @end example 21295 21296 21297 where @samp{X} denotes the zero width space character. 21298 21299 @node Code Evaluation Security 21300 @section Code Evaluation and Security Issues 21301 21302 Unlike plain text, running code comes with risk. Each source code 21303 block, in terms of risk, is equivalent to an executable file. Org 21304 therefore puts a few confirmation prompts by default. This is to 21305 alert the casual user from accidentally running untrusted code. 21306 21307 For users who do not run code blocks or write code regularly, Org's 21308 default settings should suffice. However, some users may want to 21309 tweak the prompts for fewer interruptions. To weigh the risks of 21310 automatic execution of code blocks, here are some details about code 21311 evaluation. 21312 21313 Org evaluates code in the following circumstances: 21314 21315 @table @asis 21316 @item @emph{Source code blocks} 21317 Org evaluates source code blocks in an Org file during export. Org 21318 also evaluates a source code block with the @kbd{C-c C-c} key 21319 chord. Users exporting or running code blocks must load files only 21320 from trusted sources. Be wary of customizing variables that remove 21321 or alter default security measures. 21322 21323 @defopt org-confirm-babel-evaluate 21324 When @code{t}, Org prompts the user for confirmation before executing 21325 each code block. When @code{nil}, Org executes code blocks without 21326 prompting the user for confirmation. When this option is set to 21327 a custom function, Org invokes the function with these two 21328 arguments: the source code language and the body of the code block. 21329 The custom function must return either a @code{t} or @code{nil}, which 21330 determines if the user is prompted. Each source code language can 21331 be handled separately through this function argument. 21332 @end defopt 21333 21334 For example, here is how to execute ditaa code blocks without 21335 prompting: 21336 21337 @lisp 21338 (defun my-org-confirm-babel-evaluate (lang body) 21339 (not (string= lang "ditaa"))) ;don't ask for ditaa 21340 (setq org-confirm-babel-evaluate #'my-org-confirm-babel-evaluate) 21341 @end lisp 21342 21343 @item @emph{Following @samp{shell} and @samp{elisp} links} 21344 Org has two link types that can directly evaluate code (see 21345 @ref{External Links}). Because such code is not visible, these links 21346 have a potential risk. Org therefore prompts the user when it 21347 encounters such links. The customization variables are: 21348 21349 @defopt org-link-shell-confirm-function 21350 Function that prompts the user before executing a shell link. 21351 @end defopt 21352 21353 @defopt org-link-elisp-confirm-function 21354 Function that prompts the user before executing an Emacs Lisp link. 21355 @end defopt 21356 21357 @item @emph{Formulas in tables} 21358 Formulas in tables (see @ref{The Spreadsheet}) are code that is evaluated 21359 either by the Calc interpreter, or by the Emacs Lisp interpreter. 21360 @end table 21361 21362 @node Interaction 21363 @section Interaction with Other Packages 21364 21365 @cindex packages, interaction with other 21366 21367 Org's compatibility and the level of interaction with other Emacs 21368 packages are documented here. 21369 21370 @menu 21371 * Cooperation:: Packages Org cooperates with. 21372 * Conflicts:: Packages that lead to conflicts. 21373 @end menu 21374 21375 @node Cooperation 21376 @subsection Packages that Org cooperates with 21377 21378 @table @asis 21379 @item @samp{calc.el} by Dave Gillespie 21380 @cindex @file{calc.el} 21381 21382 Org uses the Calc package for implementing spreadsheet functionality 21383 in its tables (see @ref{The Spreadsheet}). Org also uses Calc for 21384 embedded calculations. See @ref{Embedded Mode,GNU Emacs Calc Manual,,calc,}. 21385 21386 @item @samp{constants.el} by Carsten Dominik 21387 @cindex @file{constants.el} 21388 @vindex org-table-formula-constants 21389 21390 Org can use names for constants in formulas in tables. Org can also 21391 use calculation suffixes for units, such as @samp{M} for @samp{Mega}. For 21392 a standard collection of such constants, install the @samp{constants} 21393 package. Install version 2.0 of this package, available at 21394 @uref{http://www.astro.uva.nl/~dominik/Tools}. Org checks if the function 21395 @code{constants-get} has been autoloaded. Installation instructions are 21396 in the file @samp{constants.el}. 21397 21398 @item @samp{cdlatex.el} by Carsten Dominik 21399 @cindex @file{cdlatex.el} 21400 21401 Org mode can make use of the CD@LaTeX{} package to efficiently enter 21402 @LaTeX{} fragments into Org files. See @ref{CD@LaTeX{} mode}. 21403 21404 @item @samp{imenu.el} by Ake Stenhoff and Lars Lindberg 21405 @cindex @file{imenu.el} 21406 21407 Imenu creates dynamic menus based on an index of items in a file. 21408 Org mode supports Imenu menus. Enable it with a mode hook as 21409 follows: 21410 21411 @lisp 21412 (add-hook 'org-mode-hook 21413 (lambda () (imenu-add-to-menubar "Imenu"))) 21414 @end lisp 21415 21416 @vindex org-imenu-depth 21417 By default the index is two levels deep---you can modify the 21418 depth using the option @code{org-imenu-depth}. 21419 21420 @item @samp{speedbar.el} by Eric@tie{}M@.@tie{}Ludlam 21421 @cindex @file{speedbar.el} 21422 21423 Speedbar package creates a special Emacs frame for displaying files 21424 and index items in files. Org mode supports Speedbar; users can 21425 drill into Org files directly from the Speedbar. The @kbd{<} 21426 in the Speedbar frame tweaks the agenda commands to that file or to 21427 a subtree. 21428 21429 @item @samp{table.el} by Takaaki Ota 21430 @cindex table editor, @file{table.el} 21431 @cindex @file{table.el} 21432 21433 Complex ASCII tables with automatic line wrapping, column- and 21434 row-spanning, and alignment can be created using the Emacs table 21435 package by Takaaki Ota. Org mode recognizes such tables and exports 21436 them properly. @kbd{C-c '} to edit these tables in a special 21437 buffer, much like Org's code blocks. Because of interference with 21438 other Org mode functionality, Takaaki Ota tables cannot be edited 21439 directly in the Org buffer. 21440 21441 @table @asis 21442 @item @kbd{C-c '} (@code{org-edit-special}) 21443 @kindex C-c ' 21444 @findex org-edit-special 21445 Edit a @samp{table.el} table. Works when point is in a @samp{table.el} 21446 table. 21447 21448 @item @kbd{C-c ~} (@code{org-table-create-with-table.el}) 21449 @kindex C-c ~ 21450 @findex org-table-create-with-table.el 21451 Insert a @samp{table.el} table. If there is already a table at point, 21452 this command converts it between the @samp{table.el} format and the Org 21453 mode format. See the documentation string of the command 21454 @code{org-convert-table} for the restrictions under which this is 21455 possible. 21456 @end table 21457 @end table 21458 21459 @node Conflicts 21460 @subsection Packages that conflict with Org mode 21461 21462 @cindex shift-selection 21463 @vindex org-support-shift-select 21464 In Emacs, shift-selection combines motions of point with shift key to 21465 enlarge regions. Emacs sets this mode by default. This conflicts 21466 with Org's use of @kbd{S-<cursor>} commands to change timestamps, 21467 TODO keywords, priorities, and item bullet types, etc. Since 21468 @kbd{S-<cursor>} commands outside of specific contexts do not do 21469 anything, Org offers the variable @code{org-support-shift-select} for 21470 customization. Org mode accommodates shift selection by (i) making it 21471 available outside of the special contexts where special commands 21472 apply, and (ii) extending an existing active region even if point 21473 moves across a special context. 21474 21475 @table @asis 21476 @item @samp{cua.el} by Kim@tie{}F@.@tie{}Storm 21477 @cindex @file{cua.el} 21478 @vindex org-replace-disputed-keys 21479 Org key bindings conflict with @kbd{S-<cursor>} keys used by 21480 CUA mode. For Org to relinquish these bindings to CUA mode, 21481 configure the variable @code{org-replace-disputed-keys}. When set, Org 21482 moves the following key bindings in Org files, and in the agenda 21483 buffer---but not during date selection. 21484 21485 @multitable @columnfractions 0.4 0.4 21486 @item @kbd{S-@key{UP}} @result{} @kbd{M-p} 21487 @tab @kbd{S-@key{DOWN}} @result{} @kbd{M-n} 21488 @item @kbd{S-@key{LEFT}} @result{} @kbd{M--} 21489 @tab @kbd{S-@key{RIGHT}} @result{} @kbd{M-+} 21490 @item @kbd{C-S-@key{LEFT}} @result{} @kbd{M-S--} 21491 @tab @kbd{C-S-@key{RIGHT}} @result{} @kbd{M-S-+} 21492 @end multitable 21493 21494 @vindex org-disputed-keys 21495 Yes, these are unfortunately more difficult to remember. If you 21496 want to have other replacement keys, look at the variable 21497 @code{org-disputed-keys}. 21498 21499 @item @samp{ecomplete.el} by Lars Magne Ingebrigtsen 21500 @cindex @file{ecomplete.el} 21501 Ecomplete provides ``electric'' address completion in address header 21502 lines in message buffers. Sadly Orgtbl mode cuts Ecomplete's power 21503 supply: no completion happens when Orgtbl mode is enabled in message 21504 buffers while entering text in address header lines. If one wants 21505 to use ecomplete one should @emph{not} follow the advice to automagically 21506 turn on Orgtbl mode in message buffers (see @ref{Orgtbl Mode}), 21507 but instead---after filling in the message headers---turn on Orgtbl 21508 mode manually when needed in the messages body. 21509 21510 @item @samp{filladapt.el} by Kyle Jones 21511 @cindex @file{filladapt.el} 21512 Org mode tries to do the right thing when filling paragraphs, list 21513 items and other elements. Many users reported problems using both 21514 @samp{filladapt.el} and Org mode, so a safe thing to do is to disable 21515 filladapt like this: 21516 21517 @lisp 21518 (add-hook 'org-mode-hook 'turn-off-filladapt-mode) 21519 @end lisp 21520 21521 @item @samp{viper.el} by Michael Kifer 21522 @cindex @file{viper.el} 21523 @kindex C-c / 21524 21525 Viper uses @kbd{C-c /} and therefore makes this key not access 21526 the corresponding Org mode command @code{org-sparse-tree}. You need to 21527 find another key for this command, or override the key in 21528 @code{viper-vi-global-user-map} with 21529 21530 @lisp 21531 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree) 21532 @end lisp 21533 21534 @item @samp{windmove.el} by Hovav Shacham 21535 @cindex @file{windmove.el} 21536 21537 This package also uses the @kbd{S-<cursor>} keys, so everything 21538 written in the paragraph above about CUA mode also applies here. If 21539 you want to make the windmove function active in locations where Org 21540 mode does not have special functionality on @kbd{S-<cursor>}, 21541 add this to your configuration: 21542 21543 @lisp 21544 ;; Make windmove work in Org mode: 21545 (add-hook 'org-shiftup-final-hook 'windmove-up) 21546 (add-hook 'org-shiftleft-final-hook 'windmove-left) 21547 (add-hook 'org-shiftdown-final-hook 'windmove-down) 21548 (add-hook 'org-shiftright-final-hook 'windmove-right) 21549 @end lisp 21550 21551 @item @samp{yasnippet.el} 21552 @cindex @file{yasnippet.el} 21553 The way Org mode binds the @kbd{@key{TAB}} key (binding to @code{[tab]} 21554 instead of @code{"\t"}) overrules YASnippet's access to this key. The 21555 following code fixed this problem: 21556 21557 @lisp 21558 (add-hook 'org-mode-hook 21559 (lambda () 21560 (setq-local yas/trigger-key [tab]) 21561 (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand))) 21562 @end lisp 21563 21564 The latest version of YASnippet does not play well with Org mode. 21565 If the above code does not fix the conflict, start by defining 21566 the following function: 21567 21568 @lisp 21569 (defun yas/org-very-safe-expand () 21570 (let ((yas/fallback-behavior 'return-nil)) (yas/expand))) 21571 @end lisp 21572 21573 Then, tell Org mode to use that function: 21574 21575 @lisp 21576 (add-hook 'org-mode-hook 21577 (lambda () 21578 (make-variable-buffer-local 'yas/trigger-key) 21579 (setq yas/trigger-key [tab]) 21580 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand) 21581 (define-key yas/keymap [tab] 'yas/next-field))) 21582 @end lisp 21583 @end table 21584 21585 @node TTY Keys 21586 @section Using Org on a TTY 21587 21588 @cindex tty key bindings 21589 21590 Org provides alternative key bindings for TTY and modern mobile 21591 devices that cannot perform movement commands on point and key 21592 bindings with modifier keys. Some of these workarounds may be more 21593 cumbersome than necessary. Users should look into customizing these 21594 further based on their usage needs. For example, the normal 21595 @kbd{S-<cursor>} for editing timestamp might be better with 21596 @kbd{C-c .} chord. 21597 21598 @multitable @columnfractions 0.2 0.28 0.15 0.21 21599 @headitem Default 21600 @tab Alternative 1 21601 @tab Speed key 21602 @tab Alternative 2 21603 @item @kbd{S-@key{TAB}} 21604 @tab @kbd{C-u @key{TAB}} 21605 @tab @kbd{C} 21606 @tab 21607 @item @kbd{M-@key{LEFT}} 21608 @tab @kbd{C-c C-x l} 21609 @tab @kbd{l} 21610 @tab @kbd{Esc @key{LEFT}} 21611 @item @kbd{M-S-@key{LEFT}} 21612 @tab @kbd{C-c C-x L} 21613 @tab @kbd{L} 21614 @tab 21615 @item @kbd{M-@key{RIGHT}} 21616 @tab @kbd{C-c C-x r} 21617 @tab @kbd{r} 21618 @tab @kbd{Esc @key{RIGHT}} 21619 @item @kbd{M-S-@key{RIGHT}} 21620 @tab @kbd{C-c C-x R} 21621 @tab @kbd{R} 21622 @tab 21623 @item @kbd{M-@key{UP}} 21624 @tab @kbd{C-c C-x u} 21625 @tab 21626 @tab @kbd{Esc @key{UP}} 21627 @item @kbd{M-S-@key{UP}} 21628 @tab @kbd{C-c C-x U} 21629 @tab @kbd{U} 21630 @tab 21631 @item @kbd{M-@key{DOWN}} 21632 @tab @kbd{C-c C-x d} 21633 @tab 21634 @tab @kbd{Esc @key{DOWN}} 21635 @item @kbd{M-S-@key{DOWN}} 21636 @tab @kbd{C-c C-x D} 21637 @tab @kbd{D} 21638 @tab 21639 @item @kbd{S-@key{RET}} 21640 @tab @kbd{C-c C-x c} 21641 @tab 21642 @tab 21643 @item @kbd{M-@key{RET}} 21644 @tab @kbd{C-c C-x m} 21645 @tab 21646 @tab @kbd{Esc @key{RET}} 21647 @item @kbd{M-S-@key{RET}} 21648 @tab @kbd{C-c C-x M} 21649 @tab 21650 @tab 21651 @item @kbd{S-@key{LEFT}} 21652 @tab @kbd{C-c @key{LEFT}} 21653 @tab 21654 @tab 21655 @item @kbd{S-@key{RIGHT}} 21656 @tab @kbd{C-c @key{RIGHT}} 21657 @tab 21658 @tab 21659 @item @kbd{S-@key{UP}} 21660 @tab @kbd{C-c @key{UP}} 21661 @tab 21662 @tab 21663 @item @kbd{S-@key{DOWN}} 21664 @tab @kbd{C-c @key{DOWN}} 21665 @tab 21666 @tab 21667 @item @kbd{C-S-@key{LEFT}} 21668 @tab @kbd{C-c C-x @key{LEFT}} 21669 @tab 21670 @tab 21671 @item @kbd{C-S-@key{RIGHT}} 21672 @tab @kbd{C-c C-x @key{RIGHT}} 21673 @tab 21674 @tab 21675 @end multitable 21676 21677 @node Protocols 21678 @section Protocols for External Access 21679 21680 @cindex protocols, for external access 21681 21682 Org protocol is a tool to trigger custom actions in Emacs from 21683 external applications. Any application that supports calling external 21684 programs with an URL as argument may be used with this functionality. 21685 For example, you can configure bookmarks in your web browser to send a 21686 link to the current page to Org and create a note from it using 21687 capture (see @ref{Capture}). You can also create a bookmark that tells 21688 Emacs to open the local source file of a remote website you are 21689 browsing. 21690 21691 @cindex Org protocol, set-up 21692 @cindex Installing Org protocol 21693 In order to use Org protocol from an application, you need to register 21694 @samp{org-protocol://} as a valid scheme-handler. External calls are 21695 passed to Emacs through the @samp{emacsclient} command, so you also need to 21696 ensure an Emacs server is running. More precisely, when the 21697 application calls 21698 21699 @example 21700 emacsclient "org-protocol://PROTOCOL?key1=val1&key2=val2" 21701 @end example 21702 21703 21704 @noindent 21705 Emacs calls the handler associated to @var{PROTOCOL} with 21706 argument @samp{(:key1 val1 :key2 val2)}. 21707 21708 @cindex protocol, new protocol 21709 @cindex defining new protocols 21710 Org protocol comes with three predefined protocols, detailed in the 21711 following sections. Configure @code{org-protocol-protocol-alist} to define 21712 your own. 21713 21714 @menu 21715 * The @code{store-link} protocol:: Store a link, push URL to kill-ring. 21716 * The @code{capture} protocol:: Fill a buffer with external information. 21717 * The @code{open-source} protocol:: Edit published contents. 21718 @end menu 21719 21720 @node The @code{store-link} protocol 21721 @subsection The @code{store-link} protocol 21722 21723 @cindex store-link protocol 21724 @cindex protocol, store-link 21725 21726 Using the @code{store-link} handler, you can copy links, to that they can 21727 be inserted using @kbd{M-x org-insert-link} or yanking. More 21728 precisely, the command 21729 21730 @example 21731 emacsclient "org-protocol://store-link?url=URL&title=TITLE" 21732 @end example 21733 21734 21735 @noindent 21736 stores the following link: 21737 21738 @example 21739 [[URL][TITLE]] 21740 @end example 21741 21742 21743 In addition, @var{URL} is pushed on the kill-ring for yanking. 21744 You need to encode @var{URL} and @var{TITLE} if they contain 21745 slashes, and probably quote those for the shell. 21746 21747 To use this feature from a browser, add a bookmark with an arbitrary 21748 name, e.g., @samp{Org: store-link} and enter this as @emph{Location}: 21749 21750 @example 21751 javascript:location.href='org-protocol://store-link?' + 21752 new URLSearchParams(@{url:location.href, title:document.title@}); 21753 @end example 21754 21755 Title is an optional parameter. Another expression was recommended earlier: 21756 21757 @example 21758 javascript:location.href='org-protocol://store-link?url='+ 21759 encodeURIComponent(location.href); 21760 @end example 21761 21762 The latter form is compatible with older Org versions from 9.0 to 9.4. 21763 21764 @node The @code{capture} protocol 21765 @subsection The @code{capture} protocol 21766 21767 @cindex capture protocol 21768 @cindex protocol, capture 21769 21770 Activating the ``capture'' handler pops up a @samp{Capture} buffer in Emacs, 21771 using acapture template. 21772 21773 @example 21774 emacsclient "org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY" 21775 @end example 21776 21777 21778 To use this feature, add a bookmark with an arbitrary name, e.g., 21779 @samp{Org: capture}, and enter this as @samp{Location}: 21780 21781 @example 21782 javascript:location.href='org-protocol://capture?' + 21783 new URLSearchParams(@{ 21784 template: 'x', url: window.location.href, 21785 title: document.title, body: window.getSelection()@}); 21786 @end example 21787 21788 You might have seen another expression: 21789 21790 @example 21791 javascript:location.href='org-protocol://capture?template=x'+ 21792 '&url='+encodeURIComponent(window.location.href)+ 21793 '&title='+encodeURIComponent(document.title)+ 21794 '&body='+encodeURIComponent(window.getSelection()); 21795 @end example 21796 21797 It is a bit more cluttered than the former one, but it is compatible 21798 with previous Org versions 9.0-9.4. In these versions encoding of 21799 space as ``+'' character was not supported by URI decoder. 21800 21801 @vindex org-protocol-default-template-key 21802 The capture template to be used can be specified in the bookmark (like 21803 @samp{X} above). If unspecified, the template key is set in the variable 21804 @code{org-protocol-default-template-key}. The following template 21805 placeholders are available: 21806 21807 @example 21808 %:link The URL 21809 %:description The webpage title 21810 %:annotation Equivalent to [[%:link][%:description]] 21811 %i The selected text 21812 @end example 21813 21814 @node The @code{open-source} protocol 21815 @subsection The @code{open-source} protocol 21816 21817 @cindex open-source protocol 21818 @cindex protocol, open-source 21819 21820 The @code{open-source} handler is designed to help with editing local 21821 sources when reading a document. To that effect, you can use 21822 a bookmark with the following location: 21823 21824 @example 21825 javascript:location.href='org-protocol://open-source?&url='+ 21826 encodeURIComponent(location.href) 21827 @end example 21828 21829 @vindex org-protocol-project-alist 21830 The variable @code{org-protocol-project-alist} maps URLs to local file 21831 names, by stripping URL parameters from the end and replacing the 21832 @code{:base-url} with @code{:working-directory} and @code{:online-suffix} with 21833 @code{:working-suffix}. For example, assuming you own a local copy of 21834 @samp{https://orgmode.org/worg/} contents at @samp{/home/user/worg}, you can set 21835 @code{org-protocol-project-alist} to the following 21836 21837 @lisp 21838 (setq org-protocol-project-alist 21839 '(("Worg" 21840 :base-url "https://orgmode.org/worg/" 21841 :working-directory "/home/user/worg/" 21842 :online-suffix ".html" 21843 :working-suffix ".org"))) 21844 @end lisp 21845 21846 @noindent 21847 If you are now browsing 21848 @samp{https://orgmode.org/worg/org-contrib/org-protocol.html} and find 21849 a typo or have an idea about how to enhance the documentation, simply 21850 click the bookmark and start editing. 21851 21852 @cindex rewritten URL in open-source protocol 21853 @cindex protocol, open-source rewritten URL 21854 However, such mapping may not always yield the desired results. 21855 Suppose you maintain an online store located at @samp{https://example.com/}. 21856 The local sources reside in @samp{/home/user/example/}. It is common 21857 practice to serve all products in such a store through one file and 21858 rewrite URLs that do not match an existing file on the server. That 21859 way, a request to @samp{https://example.com/print/posters.html} might be 21860 rewritten on the server to something like 21861 @samp{https://example.com/shop/products.php/posters.html.php}. The 21862 @code{open-source} handler probably cannot find a file named 21863 @samp{/home/user/example/print/posters.html.php} and fails. 21864 21865 Such an entry in @code{org-protocol-project-alist} may hold an additional 21866 property @code{:rewrites}. This property is a list of cons cells, each of 21867 which maps a regular expression to a path relative to the 21868 @code{:working-directory}. 21869 21870 Now map the URL to the path @samp{/home/user/example/products.php} by 21871 adding @code{:rewrites} rules like this: 21872 21873 @lisp 21874 (setq org-protocol-project-alist 21875 '(("example.com" 21876 :base-url "https://example.com/" 21877 :working-directory "/home/user/example/" 21878 :online-suffix ".php" 21879 :working-suffix ".php" 21880 :rewrites (("example.com/print/" . "products.php") 21881 ("example.com/$" . "index.php"))))) 21882 @end lisp 21883 21884 @noindent 21885 Since @samp{example.com/$} is used as a regular expression, it maps 21886 @samp{http://example.com/}, @samp{https://example.com}, 21887 @samp{http://www.example.com/} and similar to 21888 @samp{/home/user/example/index.php}. 21889 21890 The @code{:rewrites} rules are searched as a last resort if and only if no 21891 existing file name is matched. 21892 21893 @cindex protocol, open-source, set-up mapping 21894 @cindex mappings in open-source protocol 21895 @findex org-protocol-create 21896 @findex org-protocol-create-for-org 21897 Two functions can help you filling @code{org-protocol-project-alist} with 21898 valid contents: @code{org-protocol-create} and 21899 @code{org-protocol-create-for-org}. The latter is of use if you're editing 21900 an Org file that is part of a publishing project. 21901 21902 @node Org Crypt 21903 @section Org Crypt 21904 21905 Org Crypt encrypts the text of an entry, but not the headline, or 21906 properties. Behind the scene, it uses the @ref{Top,Emacs EasyPG Library,,epa,} to 21907 encrypt and decrypt files, and EasyPG needs a correct @ref{Top,GnuPG,,gnupg,} setup. 21908 21909 @vindex org-crypt-tag-matcher 21910 Any text below a headline that has a @samp{crypt} tag is automatically 21911 encrypted when the file is saved. To use a different tag, customize 21912 the @code{org-crypt-tag-matcher} setting. 21913 21914 Here is a suggestion for Org Crypt settings in Emacs init file: 21915 21916 @lisp 21917 (require 'org-crypt) 21918 (org-crypt-use-before-save-magic) 21919 (setq org-tags-exclude-from-inheritance '("crypt")) 21920 21921 (setq org-crypt-key nil) 21922 ;; GPG key to use for encryption. 21923 ;; nil means use symmetric encryption unconditionally. 21924 ;; "" means use symmetric encryption unless heading sets CRYPTKEY property. 21925 21926 (setq auto-save-default nil) 21927 ;; Auto-saving does not cooperate with org-crypt.el: so you need to 21928 ;; turn it off if you plan to use org-crypt.el quite often. Otherwise, 21929 ;; you'll get an (annoying) message each time you start Org. 21930 21931 ;; To turn it off only locally, you can insert this: 21932 ;; 21933 ;; # -*- buffer-auto-save-file-name: nil; -*- 21934 @end lisp 21935 21936 It's possible to use different keys for different headings by 21937 specifying the respective key as property @samp{CRYPTKEY}, e.g.: 21938 21939 @example 21940 * Totally secret :crypt: 21941 :PROPERTIES: 21942 :CRYPTKEY: 0x0123456789012345678901234567890123456789 21943 :END: 21944 @end example 21945 21946 Note that @samp{CRYPTKEY} property is only effective when @code{org-crypt-key} 21947 is set to non-nil. @code{nil} value of @code{org-crypt-key} makes Org use 21948 symmetric encryption unconditionally. 21949 21950 Excluding the @samp{crypt} tag from inheritance prevents already encrypted 21951 text from being encrypted again. 21952 21953 @node Org Mobile 21954 @section Org Mobile 21955 21956 @cindex smartphone 21957 21958 Org Mobile is a protocol for synchronizing Org files between Emacs and 21959 other applications, e.g., on mobile devices. It enables offline-views 21960 and capture support for an Org mode system that is rooted on a ``real'' 21961 computer. The external application can also record changes to 21962 existing entries. 21963 21964 This appendix describes Org's support for agenda view formats 21965 compatible with Org Mobile. It also describes synchronizing changes, 21966 such as to notes, between the mobile application and the computer. 21967 21968 To change tags and TODO states in the mobile application, first 21969 customize the variables @code{org-todo-keywords}, @code{org-tag-alist} and 21970 @code{org-tag-persistent-alist}. These should cover all the important tags 21971 and TODO keywords, even if Org files use only some of them. Though 21972 the mobile application is expected to support in-buffer settings, it 21973 is required to understand TODO states @emph{sets} (see @ref{Per-file keywords}) and @emph{mutually exclusive} tags (see @ref{Setting Tags}) only for those set in these variables. 21974 21975 @menu 21976 * Setting up the staging area:: For the mobile device. 21977 * Pushing to the mobile application:: Uploading Org files and agendas. 21978 * Pulling from the mobile application:: Integrating captured and flagged items. 21979 @end menu 21980 21981 @node Setting up the staging area 21982 @subsection Setting up the staging area 21983 21984 @vindex org-mobile-directory 21985 The mobile application needs access to a file directory on 21986 a server@footnote{For a server to host files, consider using a WebDAV server, 21987 such as @uref{https://nextcloud.com, Nextcloud}. Additional help is at this @uref{https://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.} to interact with Emacs. Pass its location through 21988 the @code{org-mobile-directory} variable. If you can mount that directory 21989 locally just set the variable to point to that directory: 21990 21991 @lisp 21992 (setq org-mobile-directory "~/orgmobile/") 21993 @end lisp 21994 21995 Alternatively, by using TRAMP (see @ref{Top,TRAMP User Manual,,tramp,}), 21996 @code{org-mobile-directory} may point to a remote directory accessible 21997 through, for example, SSH, SCP, or DAVS: 21998 21999 @lisp 22000 (setq org-mobile-directory "/davs:user@@remote.host:/org/webdav/") 22001 @end lisp 22002 22003 @vindex org-mobile-encryption 22004 With a public server, consider encrypting the files. Org also 22005 requires OpenSSL installed on the local computer. To turn on 22006 encryption, set the same password in the mobile application and in 22007 Emacs. Set the password in the variable 22008 @code{org-mobile-use-encryption}@footnote{ If Emacs is configured for safe 22009 storing of passwords, then configure the variable 22010 @code{org-mobile-encryption-password}; please read the docstring of that 22011 variable.}. Note that even after the mobile application encrypts the 22012 file contents, the file name remains visible on the file systems of 22013 the local computer, the server, and the mobile device. 22014 22015 @node Pushing to the mobile application 22016 @subsection Pushing to the mobile application 22017 22018 @findex org-mobile-push 22019 @vindex org-mobile-files 22020 The command @code{org-mobile-push} copies files listed in 22021 @code{org-mobile-files} into the staging area. Files include agenda files 22022 (as listed in @code{org-agenda-files}). Customize @code{org-mobile-files} to 22023 add other files. File names are staged with paths relative to 22024 @code{org-directory}, so all files should be inside this directory@footnote{ 22025 Symbolic links in @code{org-directory} need to have the same name as their 22026 targets.}. 22027 22028 Push creates a special Org file @samp{agendas.org} with custom agenda views 22029 defined by the user@footnote{While creating the agendas, Org mode forces @samp{ID} properties 22030 on all referenced entries, so that these entries can be uniquely 22031 identified if Org Mobile flags them for further action. To avoid 22032 setting properties configure the variable 22033 @code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode then relies 22034 on outline paths, assuming they are unique.}. 22035 22036 Finally, Org writes the file @samp{index.org}, containing links to other 22037 files. The mobile application reads this file first from the server 22038 to determine what other files to download for agendas. For faster 22039 downloads, it is expected to only read files whose checksums@footnote{ 22040 Checksums are stored automatically in the file @samp{checksums.dat}.} have 22041 changed. 22042 22043 @node Pulling from the mobile application 22044 @subsection Pulling from the mobile application 22045 22046 @findex org-mobile-pull 22047 The command @code{org-mobile-pull} synchronizes changes with the server. 22048 More specifically, it first pulls the Org files for viewing. It then 22049 appends captured entries and pointers to flagged or changed entries to 22050 the file @samp{mobileorg.org} on the server. Org ultimately integrates its 22051 data in an inbox file format, through the following steps: 22052 22053 @enumerate 22054 @item 22055 @vindex org-mobile-inbox-for-pull 22056 Org moves all entries found in @samp{mobileorg.org}@footnote{ The file will 22057 be empty after this operation.} and appends them to the file 22058 pointed to by the variable @code{org-mobile-inbox-for-pull}. It should 22059 reside neither in the staging area nor on the server. Each 22060 captured entry and each editing event is a top-level entry in the 22061 inbox file. 22062 22063 @item 22064 @cindex @samp{FLAGGED}, tag 22065 After moving the entries, Org processes changes to the shared 22066 files. Some of them are applied directly and without user 22067 interaction. Examples include changes to tags, TODO state, 22068 headline and body text. Entries requiring further action are 22069 tagged as @samp{FLAGGED}. Org marks entries with problems with an error 22070 message in the inbox. They have to be resolved manually. 22071 22072 @item 22073 Org generates an agenda view for flagged entries for user 22074 intervention to clean up. For notes stored in flagged entries, Org 22075 displays them in the echo area when point is on the corresponding 22076 agenda item. 22077 22078 @table @asis 22079 @item @kbd{?} 22080 Pressing @kbd{?} displays the entire flagged note in another 22081 window. Org also pushes it to the kill ring. To store flagged 22082 note as a normal note, use @kbd{? z C-y C-c C-c}. Pressing 22083 @kbd{?} twice does these things: first it removes the 22084 @samp{FLAGGED} tag; second, it removes the flagged note from the 22085 property drawer; third, it signals that manual editing of the 22086 flagged entry is now finished. 22087 @end table 22088 @end enumerate 22089 22090 @kindex ? @r{(Agenda dispatcher)} 22091 From the agenda dispatcher, @kbd{?} returns to the view to finish 22092 processing flagged entries. Note that these entries may not be the 22093 most recent since the mobile application searches files that were last 22094 pulled. To get an updated agenda view with changes since the last 22095 pull, pull again. 22096 22097 @node Hacking 22098 @appendix Hacking 22099 22100 @cindex hacking 22101 22102 This appendix describes some ways a user can extend the functionality 22103 of Org. 22104 22105 @menu 22106 * Hooks:: How to reach into Org's internals. 22107 * Add-on Packages:: Available extensions. 22108 * Adding Hyperlink Types:: New custom link types. 22109 * Adding Export Back-ends:: How to write new export back-ends. 22110 * Tables in Arbitrary Syntax:: Orgtbl for LaTeX and other programs. 22111 * Dynamic Blocks:: Automatically filled blocks. 22112 * Special Agenda Views:: Customized views. 22113 * Speeding Up Your Agendas:: Tips on how to speed up your agendas. 22114 * Extracting Agenda Information:: Post-processing agenda information. 22115 * Using the Property API:: Writing programs that use entry properties. 22116 * Using the Mapping API:: Mapping over all or selected entries. 22117 @end menu 22118 22119 @node Hooks 22120 @appendixsec Hooks 22121 22122 @cindex hooks 22123 22124 Org has a large number of hook variables for adding functionality. 22125 This appendix illustrates using a few. A complete list of hooks with 22126 documentation is maintained by the Worg project at 22127 @uref{https://orgmode.org/worg/doc.html#hooks}. 22128 22129 @node Add-on Packages 22130 @appendixsec Add-on Packages 22131 22132 @cindex add-on packages 22133 22134 Various authors wrote a large number of add-on packages for Org. Some 22135 of these packages used to be part of the @samp{org-mode} repository but are 22136 now hosted in a separate @samp{org-contrib} repository 22137 @uref{https://git.sr.ht/~bzg/org-contrib, here}. A Worg page with more 22138 information is at: @uref{https://orgmode.org/worg/org-contrib/}. 22139 22140 @node Adding Hyperlink Types 22141 @appendixsec Adding Hyperlink Types 22142 22143 @cindex hyperlinks, adding new types 22144 22145 Org has many built-in hyperlink types (see @ref{Hyperlinks}), and an 22146 interface for adding new link types. The following example shows the 22147 process of adding Org links to Unix man pages, which look like this 22148 22149 @example 22150 [[man:printf][The printf manual]] 22151 @end example 22152 22153 22154 @noindent 22155 The following @samp{ol-man.el} file implements it 22156 22157 @lisp 22158 ;;; ol-man.el - Support for links to man pages in Org mode 22159 (require 'ol) 22160 22161 (org-link-set-parameters "man" 22162 :follow #'org-man-open 22163 :export #'org-man-export 22164 :store #'org-man-store-link) 22165 22166 (defcustom org-man-command 'man 22167 "The Emacs command to be used to display a man page." 22168 :group 'org-link 22169 :type '(choice (const man) (const woman))) 22170 22171 (defun org-man-open (path _) 22172 "Visit the manpage on PATH. 22173 PATH should be a topic that can be thrown at the man command." 22174 (funcall org-man-command path)) 22175 22176 (defun org-man-store-link () 22177 "Store a link to a man page." 22178 (when (memq major-mode '(Man-mode woman-mode)) 22179 ;; This is a man page, we do make this link. 22180 (let* ((page (org-man-get-page-name)) 22181 (link (concat "man:" page)) 22182 (description (format "Man page for %s" page))) 22183 (org-link-store-props 22184 :type "man" 22185 :link link 22186 :description description)))) 22187 22188 (defun org-man-get-page-name () 22189 "Extract the page name from the buffer name." 22190 ;; This works for both `Man-mode' and `woman-mode'. 22191 (if (string-match " \\(\\S-+\\)\\*" (buffer-name)) 22192 (match-string 1 (buffer-name)) 22193 (error "Cannot create link to this man page"))) 22194 22195 (defun org-man-export (link description format _) 22196 "Export a man page link from Org files." 22197 (let ((path (format "http://man.he.net/?topic=%s§ion=all" link)) 22198 (desc (or description link))) 22199 (pcase format 22200 (`html (format "<a target=\"_blank\" href=\"%s\">%s</a>" path desc)) 22201 (`latex (format "\\href@{%s@}@{%s@}" path desc)) 22202 (`texinfo (format "@@uref@{%s,%s@}" path desc)) 22203 (`ascii (format "%s (%s)" desc path)) 22204 (t path)))) 22205 22206 (provide ol-man) 22207 ;;; ol-man.el ends here 22208 @end lisp 22209 22210 @noindent 22211 To activate links to man pages in Org, enter this in the Emacs init 22212 file: 22213 22214 @lisp 22215 (require 'ol-man) 22216 @end lisp 22217 22218 @noindent 22219 A review of @samp{ol-man.el}: 22220 22221 @enumerate 22222 @item 22223 First, @samp{(require 'ol)} ensures that @samp{ol.el} is loaded. 22224 22225 @item 22226 @findex org-link-set-parameters 22227 @vindex org-link-parameters 22228 Then @code{org-link-set-parameters} defines a new link type with @samp{man} 22229 prefix and associates functions for following, exporting and 22230 storing such links. See the variable @code{org-link-parameters} for 22231 a complete list of possible associations. 22232 22233 @item 22234 The rest of the file implements necessary variables and functions. 22235 22236 For example, @code{org-man-store-link} is responsible for storing a link 22237 when @code{org-store-link} (see @ref{Handling Links}) is called from a buffer 22238 displaying a man page. It first checks if the major mode is 22239 appropriate. If check fails, the function returns @code{nil}, which 22240 means it isn't responsible for creating a link to the current 22241 buffer. Otherwise the function makes a link string by combining 22242 the @samp{man:} prefix with the man topic. It also provides a default 22243 description. The function @code{org-insert-link} can insert it back 22244 into an Org buffer later on. 22245 @end enumerate 22246 22247 @node Adding Export Back-ends 22248 @appendixsec Adding Export Back-ends 22249 22250 @cindex Export, writing back-ends 22251 22252 Org's export engine makes it easy for writing new back-ends. The 22253 framework on which the engine was built makes it easy to derive new 22254 back-ends from existing ones. 22255 22256 @findex org-export-define-backend 22257 @findex org-export-define-derived-backend 22258 The two main entry points to the export engine are: 22259 @code{org-export-define-backend} and @code{org-export-define-derived-backend}. 22260 To grok these functions, see @samp{ox-latex.el} for an example of defining 22261 a new back-end from scratch, and @samp{ox-beamer.el} for an example of 22262 deriving from an existing engine. 22263 22264 For creating a new back-end from scratch, first set its name as 22265 a symbol in an alist consisting of elements and export functions. To 22266 make the back-end visible to the export dispatcher, set @code{:menu-entry} 22267 keyword. For export options specific to this back-end, set the 22268 @code{:options-alist}. 22269 22270 For creating a new back-end from an existing one, set 22271 @code{:translate-alist} to an alist of export functions. This alist 22272 replaces the parent back-end functions. 22273 22274 For complete documentation, see @uref{https://orgmode.org/worg/dev/org-export-reference.html, the Org Export Reference on Worg}. 22275 22276 @node Tables in Arbitrary Syntax 22277 @appendixsec Tables in Arbitrary Syntax 22278 22279 @cindex tables, in other modes 22280 @cindex lists, in other modes 22281 @cindex Orgtbl mode 22282 22283 Due to Org's success in handling tables with Orgtbl, a frequently 22284 requested feature is the use of Org's table functions in other modes, 22285 e.g., @LaTeX{}. This would be hard to do in a general way without 22286 complicated customization nightmares. Moreover, that would take Org 22287 away from its simplicity roots that Orgtbl has proven. There is, 22288 however, an alternate approach to accomplishing the same. 22289 22290 This approach involves implementing a custom @emph{translate} function that 22291 operates on a native Org @emph{source table} to produce a table in another 22292 format. This strategy would keep the excellently working Orgtbl 22293 simple and isolate complications, if any, confined to the translate 22294 function. To add more alien table formats, we just add more translate 22295 functions. Also the burden of developing custom translate functions 22296 for new table formats is in the hands of those who know those formats 22297 best. 22298 22299 @menu 22300 * Radio tables:: Sending and receiving radio tables. 22301 * A @LaTeX{} example:: Step by step, almost a tutorial. 22302 * Translator functions:: Copy and modify. 22303 @end menu 22304 22305 @node Radio tables 22306 @appendixsubsec Radio tables 22307 22308 @cindex radio tables 22309 22310 Radio tables are target locations for translated tables that are not near 22311 their source. Org finds the target location and inserts the translated 22312 table. 22313 22314 The key to finding the target location is the magic words @samp{BEGIN/END 22315 RECEIVE ORGTBL}. They have to appear as comments in the current mode. 22316 If the mode is C, then: 22317 22318 @example 22319 /* BEGIN RECEIVE ORGTBL table_name */ 22320 /* END RECEIVE ORGTBL table_name */ 22321 @end example 22322 22323 At the location of source, Org needs a special line to direct Orgtbl 22324 to translate and to find the target for inserting the translated 22325 table. For example: 22326 22327 @cindex @samp{ORGTBL}, keyword 22328 @example 22329 #+ORGTBL: SEND table_name translation_function arguments ... 22330 @end example 22331 22332 22333 @noindent 22334 @samp{table_name} is the table's reference name, which is also used in the 22335 receiver lines, and the @samp{translation_function} is the Lisp function 22336 that translates. This line, in addition, may also contain alternating 22337 key and value arguments at the end. The translation function gets 22338 these values as a property list. A few standard parameters are 22339 already recognized and acted upon before the translation function is 22340 called: 22341 22342 @table @asis 22343 @item @samp{:skip N} 22344 Skip the first N lines of the table. Hlines do count; include them 22345 if they are to be skipped. 22346 22347 @item @samp{:skipcols (n1 n2 ...)} 22348 List of columns to be skipped. First Org automatically discards 22349 columns with calculation marks and then sends the table to the 22350 translator function, which then skips columns as specified in 22351 @samp{skipcols}. 22352 @end table 22353 22354 To keep the source table intact in the buffer without being disturbed 22355 when the source file is compiled or otherwise being worked on, use one 22356 of these strategies: 22357 22358 @itemize 22359 @item 22360 Place the table in a block comment. For example, in C mode you 22361 could wrap the table between @samp{/*} and @samp{*/} lines. 22362 22363 @item 22364 Put the table after an ``end'' statement. For example @code{\bye} in @TeX{} 22365 and @code{\end@{document@}} in @LaTeX{}. 22366 22367 @item 22368 Comment and un-comment each line of the table during edits. The 22369 @kbd{M-x orgtbl-toggle-comment} command makes toggling easy. 22370 @end itemize 22371 22372 @node A @LaTeX{} example 22373 @appendixsubsec A @LaTeX{} example of radio tables 22374 22375 @cindex @LaTeX{}, and Orgtbl mode 22376 22377 To wrap a source table in @LaTeX{}, use the @samp{comment} environment 22378 provided by @samp{comment.sty}@footnote{ @uref{https://www.ctan.org/pkg/comment}}. To 22379 activate it, put @code{\usepackage@{comment@}} in the document header. 22380 Orgtbl mode inserts a radio table skeleton@footnote{By default this works only for @LaTeX{}, HTML, and Texinfo. 22381 Configure the variable @code{orgtbl-radio-table-templates} to install 22382 templates for other modes.} with the command 22383 @kbd{M-x orgtbl-insert-radio-table}, which prompts for a table 22384 name. For example, if @samp{salesfigures} is the name, the template 22385 inserts: 22386 22387 @example 22388 % BEGIN RECEIVE ORGTBL salesfigures 22389 % END RECEIVE ORGTBL salesfigures 22390 \begin@{comment@} 22391 #+ORGTBL: SEND salesfigures orgtbl-to-latex 22392 | | | 22393 \end@{comment@} 22394 @end example 22395 22396 @vindex LaTeX-verbatim-environments 22397 @noindent 22398 The line @samp{#+ORGTBL: SEND} tells Orgtbl mode to use the function 22399 @code{orgtbl-to-latex} to convert the table to @LaTeX{} format, then insert 22400 the table at the target (receive) location named @samp{salesfigures}. Now 22401 the table is ready for data entry. It can even use spreadsheet 22402 features@footnote{If the @samp{TBLFM} keyword contains an odd number of dollar 22403 characters, this may cause problems with Font Lock in @LaTeX{} mode. As 22404 shown in the example you can fix this by adding an extra line inside 22405 the @samp{comment} environment that is used to balance the dollar 22406 expressions. If you are using AUC@TeX{} with the font-latex library, 22407 a much better solution is to add the @samp{comment} environment to the 22408 variable @code{LaTeX-verbatim-environments}.}: 22409 22410 @example 22411 % BEGIN RECEIVE ORGTBL salesfigures 22412 % END RECEIVE ORGTBL salesfigures 22413 \begin@{comment@} 22414 #+ORGTBL: SEND salesfigures orgtbl-to-latex 22415 | Month | Days | Nr sold | per day | 22416 |-------+------+---------+---------| 22417 | Jan | 23 | 55 | 2.4 | 22418 | Feb | 21 | 16 | 0.8 | 22419 | March | 22 | 278 | 12.6 | 22420 #+TBLFM: $4=$3/$2;%.1f 22421 % $ (optional extra dollar to keep Font Lock happy, see footnote) 22422 \end@{comment@} 22423 @end example 22424 22425 After editing, @kbd{C-c C-c} inserts the translated table at the 22426 target location, between the two marker lines. 22427 22428 For hand-made custom tables, note that the translator needs to skip 22429 the first two lines of the source table. Also the command has to 22430 @emph{splice} out the target table without the header and footer. 22431 22432 @example 22433 \begin@{tabular@}@{lrrr@} 22434 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\ 22435 % BEGIN RECEIVE ORGTBL salesfigures 22436 % END RECEIVE ORGTBL salesfigures 22437 \end@{tabular@} 22438 % 22439 \begin@{comment@} 22440 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 22441 | Month | Days | Nr sold | per day | 22442 |-------+------+---------+---------| 22443 | Jan | 23 | 55 | 2.4 | 22444 | Feb | 21 | 16 | 0.8 | 22445 | March | 22 | 278 | 12.6 | 22446 #+TBLFM: $4=$3/$2;%.1f 22447 \end@{comment@} 22448 @end example 22449 22450 The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of 22451 Orgtbl mode and uses a @samp{tabular} environment to typeset the table and 22452 marks horizontal lines with @code{\hline}. For additional parameters to 22453 control output, see @ref{Translator functions}: 22454 22455 @table @asis 22456 @item @samp{:splice BOOLEAN} 22457 When @{@{@{var(BOOLEAN@}@}@} is non-@code{nil}, return only table body lines; 22458 i.e., not wrapped in @samp{tabular} environment. Default is @code{nil}. 22459 22460 @item @samp{:fmt FMT} 22461 Format string to warp each field. It should contain @samp{%s} for the 22462 original field value. For example, to wrap each field value in 22463 dollar symbol, you could use @samp{:fmt "$%s$"}. Format can also wrap 22464 a property list with column numbers and formats, for example @samp{:fmt 22465 (2 "$%s$" 4 "%s\\%%")}. In place of a string, a function of one 22466 argument can be used; the function must return a formatted string. 22467 22468 @item @samp{:efmt EFMT} 22469 Format numbers as exponentials. The spec should have @samp{%s} twice for 22470 inserting mantissa and exponent, for example @samp{"%s\\times10^@{%s@}"}. This 22471 may also be a property list with column numbers and formats, for 22472 example @samp{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After 22473 @var{EFMT} has been applied to a value, @var{FMT}---see 22474 above---is also applied. Functions with two arguments can be 22475 supplied instead of strings. By default, no special formatting is 22476 applied. 22477 @end table 22478 22479 @node Translator functions 22480 @appendixsubsec Translator functions 22481 22482 @cindex HTML, and Orgtbl mode 22483 @cindex translator function 22484 22485 @findex orgtbl-to-csv 22486 @findex orgtbl-to-tsv 22487 @findex orgtbl-to-latex 22488 @findex orgtbl-to-html 22489 @findex orgtbl-to-texinfo 22490 @findex orgtbl-to-unicode 22491 @findex orgtbl-to-orgtbl 22492 @findex orgtbl-to-generic 22493 Orgtbl mode has built-in translator functions: @code{orgtbl-to-csv} 22494 (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values), 22495 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, @code{orgtbl-to-texinfo}, 22496 @code{orgtbl-to-unicode} and @code{orgtbl-to-orgtbl}. They use the generic 22497 translator, @code{orgtbl-to-generic}, which delegates translations to 22498 various export back-ends. 22499 22500 Properties passed to the function through the @samp{ORGTBL SEND} line take 22501 precedence over properties defined inside the function. For example, 22502 this overrides the default @LaTeX{} line endings, @code{\\}, with @code{\\[2mm]}: 22503 22504 @example 22505 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" 22506 @end example 22507 22508 22509 For a new language translator, define a converter function. It can be 22510 a generic function, such as shown in this example. It marks 22511 a beginning and ending of a table with @samp{!BTBL!} and @samp{!ETBL!}; 22512 a beginning and ending of lines with @samp{!BL!} and @samp{!EL!}; and uses a TAB 22513 for a field separator: 22514 22515 @lisp 22516 (defun orgtbl-to-language (table params) 22517 "Convert the orgtbl-mode TABLE to language." 22518 (orgtbl-to-generic 22519 table 22520 (org-combine-plists 22521 '(:tstart "!BTBL!" :tend "!ETBL!" :lstart "!BL!" :lend "!EL!" :sep "\t") 22522 params))) 22523 @end lisp 22524 22525 @noindent 22526 The documentation for the @code{orgtbl-to-generic} function shows 22527 a complete list of parameters, each of which can be passed through to 22528 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function using 22529 that generic function. 22530 22531 For complicated translations the generic translator function could be 22532 replaced by a custom translator function. Such a custom function must 22533 take two arguments and return a single string containing the formatted 22534 table. The first argument is the table whose lines are a list of 22535 fields or the symbol @code{hline}. The second argument is the property 22536 list consisting of parameters specified in the @samp{#+ORGTBL: SEND} line. 22537 Please share your translator functions by posting them to the Org 22538 users mailing list, at @email{emacs-orgmode@@gnu.org}. 22539 22540 @node Dynamic Blocks 22541 @appendixsec Dynamic Blocks 22542 22543 @cindex dynamic blocks 22544 22545 Org supports @emph{dynamic blocks} in Org documents. They are inserted 22546 with begin and end markers like any other code block, but the contents 22547 are updated automatically by a user function. 22548 22549 @kindex C-c C-x x 22550 @findex org-dynamic-block-insert-dblock 22551 You can insert a dynamic block with @code{org-dynamic-block-insert-dblock}, 22552 which is bound to @kbd{C-c C-x x} by default. For example, 22553 @kbd{C-c C-x x c l o c k t a b l e @key{RET}} inserts a table that 22554 updates the work time (see @ref{Clocking Work Time}). 22555 22556 Dynamic blocks can have names and function parameters. The syntax is 22557 similar to source code block specifications: 22558 22559 @example 22560 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... 22561 ... 22562 #+END: 22563 @end example 22564 22565 These commands update dynamic blocks: 22566 22567 @table @asis 22568 @item @kbd{C-c C-x C-u} (@code{org-dblock-update}) 22569 @kindex C-c C-x C-u 22570 @findex org-dblock-update 22571 Update dynamic block at point. 22572 22573 @item @kbd{C-u C-c C-x C-u} 22574 @kindex C-u C-c C-x C-u 22575 Update all dynamic blocks in the current file. 22576 @end table 22577 22578 Before updating a dynamic block, Org removes content between the 22579 @samp{BEGIN} and @samp{END} markers. Org then reads the parameters on the 22580 @samp{BEGIN} line for passing to the writer function as a plist. The 22581 previous content of the dynamic block becomes erased from the buffer 22582 and appended to the plist under @code{:content}. 22583 22584 The syntax for naming a writer function with a dynamic block labeled 22585 @samp{myblock} is: @code{org-dblock-write:myblock}. 22586 22587 The following is an example of a dynamic block and a block writer function 22588 that updates the time when the function was last run: 22589 22590 @example 22591 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" 22592 ... 22593 #+END: 22594 @end example 22595 22596 @noindent 22597 The dynamic block's writer function: 22598 22599 @lisp 22600 (defun org-dblock-write:block-update-time (params) 22601 (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) 22602 (insert "Last block update at: " 22603 (format-time-string fmt)))) 22604 @end lisp 22605 22606 To keep dynamic blocks up-to-date in an Org file, use the function, 22607 @code{org-update-all-dblocks} in hook, such as @code{before-save-hook}. The 22608 @code{org-update-all-dblocks} function does not run if the file is not in 22609 Org mode. 22610 22611 @findex org-narrow-to-block 22612 Dynamic blocks, like any other block, can be narrowed with 22613 @code{org-narrow-to-block}. 22614 22615 @node Special Agenda Views 22616 @appendixsec Special Agenda Views 22617 22618 @cindex agenda views, user-defined 22619 22620 @vindex org-agenda-skip-function 22621 @vindex org-agenda-skip-function-global 22622 Org provides a special hook to further limit items in agenda views: 22623 @code{agenda}, @code{agenda*}@footnote{ The @code{agenda*} view is the same as @code{agenda} 22624 except that it only considers @emph{appointments}, i.e., scheduled and 22625 deadline items that have a time specification @samp{[h]h:mm} in their 22626 time-stamps.}, @code{todo}, @code{alltodo}, @code{tags}, @code{tags-todo}, @code{tags-tree}. 22627 Specify a custom function that tests inclusion of every matched item 22628 in the view. This function can also skip as much as is needed. 22629 22630 For a global condition applicable to agenda views, use the 22631 @code{org-agenda-skip-function-global} variable. Org uses a global 22632 condition with @code{org-agenda-skip-function} for custom searching. 22633 22634 This example defines a function for a custom view showing TODO items 22635 with @samp{waiting} status. Manually this is a multi-step search process, 22636 but with a custom view, this can be automated as follows: 22637 22638 The custom function searches the subtree for the @samp{waiting} tag and 22639 returns @code{nil} on match. Otherwise it gives the location from where 22640 the search continues. 22641 22642 @lisp 22643 (defun my-skip-unless-waiting () 22644 "Skip trees that are not waiting" 22645 (let ((subtree-end (save-excursion (org-end-of-subtree t)))) 22646 (if (re-search-forward ":waiting:" subtree-end t) 22647 nil ; tag found, do not skip 22648 subtree-end))) ; tag not found, continue after end of subtree 22649 @end lisp 22650 22651 To use this custom function in a custom agenda command: 22652 22653 @lisp 22654 (org-add-agenda-custom-command 22655 '("b" todo "PROJECT" 22656 ((org-agenda-skip-function 'my-skip-unless-waiting) 22657 (org-agenda-overriding-header "Projects waiting for something: ")))) 22658 @end lisp 22659 22660 @vindex org-agenda-overriding-header 22661 Note that this also binds @code{org-agenda-overriding-header} to a more 22662 meaningful string suitable for the agenda view. 22663 22664 @vindex org-odd-levels-only 22665 @vindex org-agenda-skip-function 22666 @findex org-agenda-skip-entry-if 22667 @findex org-agenda-skip-subtree-if 22668 Search for entries with a limit set on levels for the custom search. 22669 This is a general approach to creating custom searches in Org. To 22670 include all levels, use @samp{LEVEL>0}@footnote{ Note that, for 22671 @code{org-odd-levels-only}, a level number corresponds to order in the 22672 hierarchy, not to the number of stars.}. Then to selectively pick the 22673 matched entries, use @code{org-agenda-skip-function}, which also accepts 22674 Lisp forms, such as @code{org-agenda-skip-entry-if} and 22675 @code{org-agenda-skip-subtree-if}. For example: 22676 22677 @table @asis 22678 @item @samp{(org-agenda-skip-entry-if 'scheduled)} 22679 Skip current entry if it has been scheduled. 22680 22681 @item @samp{(org-agenda-skip-entry-if 'notscheduled)} 22682 Skip current entry if it has not been scheduled. 22683 22684 @item @samp{(org-agenda-skip-entry-if 'deadline)} 22685 Skip current entry if it has a deadline. 22686 22687 @item @samp{(org-agenda-skip-entry-if 'scheduled 'deadline)} 22688 Skip current entry if it has a deadline, or if it is scheduled. 22689 22690 @item @samp{(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))} 22691 Skip current entry if the TODO keyword is TODO or WAITING@. 22692 22693 @item @samp{(org-agenda-skip-entry-if 'todo 'done)} 22694 Skip current entry if the TODO keyword marks a DONE state. 22695 22696 @item @samp{(org-agenda-skip-entry-if 'timestamp)} 22697 Skip current entry if it has any timestamp, may also be deadline or 22698 scheduled. 22699 22700 @item @samp{(org-agenda-skip-entry-if 'regexp "regular expression")} 22701 Skip current entry if the regular expression matches in the entry. 22702 22703 @item @samp{(org-agenda-skip-entry-if 'notregexp "regular expression")} 22704 Skip current entry unless the regular expression matches. 22705 22706 @item @samp{(org-agenda-skip-subtree-if 'regexp "regular expression")} 22707 Same as above, but check and skip the entire subtree. 22708 @end table 22709 22710 The following is an example of a search for @samp{waiting} without the 22711 special function: 22712 22713 @lisp 22714 (org-add-agenda-custom-command 22715 '("b" todo "PROJECT" 22716 ((org-agenda-skip-function '(org-agenda-skip-subtree-if 22717 'regexp ":waiting:")) 22718 (org-agenda-overriding-header "Projects waiting for something: ")))) 22719 @end lisp 22720 22721 @node Speeding Up Your Agendas 22722 @appendixsec Speeding Up Your Agendas 22723 22724 @cindex agenda views, optimization 22725 22726 Some agenda commands slow down when the Org files grow in size or 22727 number. Here are tips to speed up: 22728 22729 @itemize 22730 @item 22731 Reduce the number of Org agenda files to avoid slowdowns due to hard drive 22732 accesses. 22733 22734 @item 22735 Reduce the number of DONE and archived headlines so agenda 22736 operations that skip over these can finish faster. 22737 22738 @item 22739 Do not dim blocked tasks: 22740 @vindex org-agenda-dim-blocked-tasks 22741 22742 @lisp 22743 (setq org-agenda-dim-blocked-tasks nil) 22744 @end lisp 22745 22746 @item 22747 Stop preparing agenda buffers on startup: 22748 @vindex org-startup-folded 22749 @vindex org-agenda-inhibit-startup 22750 22751 @lisp 22752 (setq org-agenda-inhibit-startup t) 22753 @end lisp 22754 22755 @item 22756 Disable tag inheritance for agendas: 22757 @vindex org-agenda-show-inherited-tags 22758 @vindex org-agenda-use-tag-inheritance 22759 22760 @lisp 22761 (setq org-agenda-use-tag-inheritance nil) 22762 @end lisp 22763 22764 @vindex org-agenda-ignore-properties 22765 @item 22766 Disable parsing of some drawer properties: 22767 22768 @lisp 22769 (setq org-agenda-ignore-properties '(effort appt stats category)) 22770 @end lisp 22771 22772 The drawer properties you can disable in the agenda are effort 22773 estimates (@code{effort}), appointments (@code{appt}), statistics (@code{stats}) 22774 and subtree-local categories (@code{category}). 22775 @end itemize 22776 22777 These options can be applied to selected agenda views. For more 22778 details about generation of agenda views, see the docstrings for the 22779 relevant variables, and this @uref{https://orgmode.org/worg/agenda-optimization.html, dedicated Worg page} for agenda 22780 optimization. 22781 22782 @node Extracting Agenda Information 22783 @appendixsec Extracting Agenda Information 22784 22785 @cindex agenda, pipe 22786 @cindex scripts, for agenda processing 22787 22788 Org provides commands to access agendas through Emacs batch mode. 22789 Through this command-line interface, agendas are automated for further 22790 processing or printing. 22791 22792 @vindex org-agenda-custom-commands 22793 @findex org-batch-agenda 22794 @code{org-batch-agenda} creates an agenda view in ASCII and outputs to 22795 standard output. This command takes one string parameter. When 22796 string consists of a single character, Org uses it as a key to 22797 @code{org-agenda-custom-commands}. These are the same ones available 22798 through the agenda dispatcher (see @ref{Agenda Dispatcher}). 22799 22800 This example command line directly prints the TODO list to the printer: 22801 22802 @example 22803 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr 22804 @end example 22805 22806 22807 When the string parameter length is two or more characters, Org 22808 matches it with tags/TODO strings. For example, this example command 22809 line prints items tagged with @samp{shop}, but excludes items tagged with 22810 @samp{NewYork}: 22811 22812 @example 22813 emacs -batch -l ~/.emacs \ 22814 -eval '(org-batch-agenda "+shop-NewYork")' | lpr 22815 @end example 22816 22817 @noindent 22818 An example showing on-the-fly parameter modifications: 22819 22820 @example 22821 emacs -batch -l ~/.emacs \ 22822 -eval '(org-batch-agenda "a" \ 22823 org-agenda-span (quote month) \ 22824 org-agenda-include-diary nil \ 22825 org-agenda-files (quote ("~/org/project.org")))' \ 22826 | lpr 22827 @end example 22828 22829 @noindent 22830 which produces an agenda for the next 30 days from just the 22831 @samp{~/org/projects.org} file. 22832 22833 @findex org-batch-agenda-csv 22834 For structured processing of agenda output, use @code{org-batch-agenda-csv} 22835 with the following fields: 22836 22837 @table @asis 22838 @item category 22839 The category of the item 22840 @item head 22841 The headline, without TODO keyword, TAGS and PRIORITY 22842 @item type 22843 The type of the agenda entry, can be 22844 22845 @multitable {aaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 22846 @item @code{todo} 22847 @tab selected in TODO match 22848 @item @code{tagsmatch} 22849 @tab selected in tags match 22850 @item @code{diary} 22851 @tab imported from diary 22852 @item @code{deadline} 22853 @tab a deadline 22854 @item @code{scheduled} 22855 @tab scheduled 22856 @item @code{timestamp} 22857 @tab appointment, selected by timestamp 22858 @item @code{closed} 22859 @tab entry was closed on date 22860 @item @code{upcoming-deadline} 22861 @tab warning about nearing deadline 22862 @item @code{past-scheduled} 22863 @tab forwarded scheduled item 22864 @item @code{block} 22865 @tab entry has date block including date 22866 @end multitable 22867 22868 @item todo 22869 The TODO keyword, if any 22870 @item tags 22871 All tags including inherited ones, separated by colons 22872 @item date 22873 The relevant date, like @samp{2007-2-14} 22874 @item time 22875 The time, like @samp{15:00-16:50} 22876 @item extra 22877 String with extra planning info 22878 @item priority-l 22879 The priority letter if any was given 22880 @item priority-n 22881 The computed numerical priority 22882 @end table 22883 22884 If the selection of the agenda item was based on a timestamp, 22885 including those items with @samp{DEADLINE} and @samp{SCHEDULED} keywords, then 22886 Org includes date and time in the output. 22887 22888 If the selection of the agenda item was based on a timestamp (or 22889 deadline/scheduled), then Org includes date and time in the output. 22890 22891 Here is an example of a post-processing script in Perl. It takes the 22892 CSV output from Emacs and prints with a checkbox: 22893 22894 @example 22895 #!/usr/bin/perl 22896 22897 # define the Emacs command to run 22898 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; 22899 22900 # run it and capture the output 22901 $agenda = qx@{$cmd 2>/dev/null@}; 22902 22903 # loop over all lines 22904 foreach $line (split(/\n/,$agenda)) @{ 22905 # get the individual values 22906 ($category,$head,$type,$todo,$tags,$date,$time,$extra, 22907 $priority_l,$priority_n) = split(/,/,$line); 22908 # process and print 22909 print "[ ] $head\n"; 22910 @} 22911 @end example 22912 22913 @node Using the Property API 22914 @appendixsec Using the Property API 22915 22916 @cindex API, for properties 22917 @cindex properties, API 22918 22919 Here is a description of the functions that can be used to work with 22920 properties. 22921 22922 @defun org-entry-properties &optional pom which 22923 Get all properties of the entry at point-or-marker @var{POM}. 22924 This includes the TODO keyword, the tags, time strings for deadline, 22925 scheduled, and clocking, and any additional properties defined in the 22926 entry. The return value is an alist. Keys may occur multiple times 22927 if the property key was used several times. @var{POM} may also 22928 be @code{nil}, in which case the current entry is used. If 22929 @var{WHICH} is @code{nil} or @code{all}, get all properties. If 22930 @var{WHICH} is @code{special} or @code{standard}, only get that subclass. 22931 @end defun 22932 22933 @vindex org-use-property-inheritance 22934 @findex org-insert-property-drawer 22935 @defun org-entry-get pom property &optional inherit 22936 Get value of @var{PROPERTY} for entry at point-or-marker 22937 @var{POM}. By default, this only looks at properties defined 22938 locally in the entry. If @var{INHERIT} is non-@code{nil} and the 22939 entry does not have the property, then also check higher levels of the 22940 hierarchy. If @var{INHERIT} is the symbol @code{selective}, use 22941 inheritance if and only if the setting of 22942 @code{org-use-property-inheritance} selects @var{PROPERTY} for 22943 inheritance. 22944 @end defun 22945 22946 @defun org-entry-delete pom property 22947 Delete the property @var{PROPERTY} from entry at point-or-marker 22948 @var{POM}. 22949 @end defun 22950 22951 @defun org-entry-put pom property value 22952 Set @var{PROPERTY} to @var{VALUES} for entry at 22953 point-or-marker POM@. 22954 @end defun 22955 22956 @defun org-buffer-property-keys &optional include-specials 22957 Get all property keys in the current buffer. 22958 @end defun 22959 22960 @defun org-insert-property-drawer 22961 Insert a property drawer for the current entry. Also 22962 @end defun 22963 22964 @defun org-entry-put-multivalued-property pom property &rest values 22965 Set @var{PROPERTY} at point-or-marker @var{POM} to 22966 @var{VALUES}. @var{VALUES} should be a list of strings. 22967 They are concatenated, with spaces as separators. 22968 @end defun 22969 22970 @defun org-entry-get-multivalued-property pom property 22971 Treat the value of the property @var{PROPERTY} as 22972 a whitespace-separated list of values and return the values as a list 22973 of strings. 22974 @end defun 22975 22976 @defun org-entry-add-to-multivalued-property pom property value 22977 Treat the value of the property @var{PROPERTY} as 22978 a whitespace-separated list of values and make sure that 22979 @var{VALUE} is in this list. 22980 @end defun 22981 22982 @defun org-entry-remove-from-multivalued-property pom property value 22983 Treat the value of the property @var{PROPERTY} as 22984 a whitespace-separated list of values and make sure that 22985 @var{VALUE} is @emph{not} in this list. 22986 @end defun 22987 22988 @defun org-entry-member-in-multivalued-property pom property value 22989 Treat the value of the property @var{PROPERTY} as 22990 a whitespace-separated list of values and check if @var{VALUE} is 22991 in this list. 22992 @end defun 22993 22994 @defopt org-property-allowed-value-functions 22995 Hook for functions supplying allowed values for a specific property. 22996 The functions must take a single argument, the name of the property, 22997 and return a flat list of allowed values. If @samp{:ETC} is one of the 22998 values, use the values as completion help, but allow also other values 22999 to be entered. The functions must return @code{nil} if they are not 23000 responsible for this property. 23001 @end defopt 23002 23003 @node Using the Mapping API 23004 @appendixsec Using the Mapping API 23005 23006 @cindex API, for mapping 23007 @cindex mapping entries, API 23008 23009 Org has sophisticated mapping capabilities to find all entries 23010 satisfying certain criteria. Internally, this functionality is used 23011 to produce agenda views, but there is also an API that can be used to 23012 execute arbitrary functions for each or selected entries. The main 23013 entry point for this API is: 23014 23015 @defun org-map-entries func &optional match scope &rest skip 23016 Call @var{FUNC} at each headline selected by @var{MATCH} in 23017 @var{SCOPE}. 23018 23019 @var{FUNC} is a function or a Lisp form. With point positioned 23020 at the beginning of the headline, call the function without arguments. 23021 Org returns a list of return values of calls to the function. 23022 23023 To avoid preserving point, Org wraps the call to @var{FUNC} in 23024 @code{save-excursion} form. After evaluation, Org moves point to the end 23025 of the line that was just processed. Search continues from that point 23026 forward. This may not always work as expected under some conditions, 23027 such as if the current subtree was removed by a previous archiving 23028 operation. In such rare circumstances, Org skips the next entry 23029 entirely when it should not. To stop Org from such skips, make 23030 @var{FUNC} set the variable @code{org-map-continue-from} to a specific 23031 buffer position. 23032 23033 @var{MATCH} is a tags/property/TODO match. Org iterates only 23034 matched headlines. Org iterates over all headlines when 23035 @var{MATCH} is @code{nil} or @code{t}. 23036 23037 @var{SCOPE} determines the scope of this command. It can be any 23038 of: 23039 23040 @table @asis 23041 @item @code{nil} 23042 The current buffer, respecting the restriction, if any. 23043 23044 @item @code{tree} 23045 The subtree started with the entry at point. 23046 23047 @item @code{region} 23048 The entries within the active region, if any. 23049 23050 @item @code{file} 23051 The current buffer, without restriction. 23052 23053 @item @code{file-with-archives} 23054 The current buffer, and any archives associated with it. 23055 23056 @item @code{agenda} 23057 All agenda files. 23058 23059 @item @code{agenda-with-archives} 23060 All agenda files with any archive files associated with them. 23061 23062 @item list of filenames 23063 If this is a list, all files in the list are scanned. 23064 @end table 23065 23066 @noindent 23067 The remaining arguments are treated as settings for the scanner's 23068 skipping facilities. Valid arguments are: 23069 23070 @table @asis 23071 @item @code{archive} 23072 Skip trees with the @samp{ARCHIVE} tag. 23073 23074 @item @code{comment} 23075 Skip trees with the COMMENT keyword. 23076 23077 @item function or Lisp form 23078 @vindex org-agenda-skip-function 23079 Used as value for @code{org-agenda-skip-function}, so whenever the 23080 function returns @code{t}, @var{FUNC} is called for that entry and 23081 search continues from the point where the function leaves it. 23082 @end table 23083 @end defun 23084 23085 The mapping routine can call any arbitrary function, even functions 23086 that change meta data or query the property API (see @ref{Using the Property API}). Here are some handy functions: 23087 23088 @defun org-todo &optional arg 23089 Change the TODO state of the entry. See the docstring of the 23090 functions for the many possible values for the argument 23091 @var{ARG}. 23092 @end defun 23093 23094 @defun org-priority &optional action 23095 Change the priority of the entry. See the docstring of this function 23096 for the possible values for @var{ACTION}. 23097 @end defun 23098 23099 @defun org-toggle-tag tag &optional onoff 23100 Toggle the tag @var{TAG} in the current entry. Setting 23101 @var{ONOFF} to either @code{on} or @code{off} does not toggle tag, but 23102 ensure that it is either on or off. 23103 @end defun 23104 23105 @defun org-promote 23106 Promote the current entry. 23107 @end defun 23108 23109 @defun org-demote 23110 Demote the current entry. 23111 @end defun 23112 23113 This example turns all entries tagged with @samp{TOMORROW} into TODO 23114 entries with keyword @samp{UPCOMING}. Org ignores entries in comment trees 23115 and archive trees. 23116 23117 @lisp 23118 (org-map-entries '(org-todo "UPCOMING") 23119 "+TOMORROW" 'file 'archive 'comment) 23120 @end lisp 23121 23122 The following example counts the number of entries with TODO keyword 23123 @samp{WAITING}, in all agenda files. 23124 23125 @lisp 23126 (length (org-map-entries t "/+WAITING" 'agenda)) 23127 @end lisp 23128 23129 @node History and Acknowledgments 23130 @appendix History and Acknowledgments 23131 23132 23133 23134 @anchor{From Carsten} 23135 @appendixsec From Carsten 23136 23137 Org was born in 2003, out of frustration over the user interface of 23138 the Emacs Outline mode. I was trying to organize my notes and 23139 projects, and using Emacs seemed to be the natural way to go. 23140 However, having to remember eleven different commands with two or 23141 three keys per command, only to hide and show parts of the outline 23142 tree, that seemed entirely unacceptable to me. Also, when using 23143 outlines to take notes, I constantly wanted to restructure the tree, 23144 organizing it parallel to my thoughts and plans. @emph{Visibility cycling} 23145 and @emph{structure editing} were originally implemented in the package 23146 @samp{outline-magic.el}, but quickly moved to the more general @samp{org.el}. 23147 As this environment became comfortable for project planning, the next 23148 step was adding @emph{TODO entries}, basic @emph{timestamps}, and @emph{table 23149 support}. These areas highlighted the two main goals that Org still 23150 has today: to be a new, outline-based, plain text mode with innovative 23151 and intuitive editing features, and to incorporate project planning 23152 functionality directly into a notes file. 23153 23154 Since the first release, literally thousands of emails to me or to the 23155 @email{emacs-orgmode@@gnu.org, mailing list} have provided a constant stream of bug reports, feedback, 23156 new ideas, and sometimes patches and add-on code. Many thanks to 23157 everyone who has helped to improve this package. I am trying to keep 23158 here a list of the people who had significant influence in shaping one 23159 or more aspects of Org. The list may not be complete, if I have 23160 forgotten someone, please accept my apologies and let me know. 23161 23162 Before I get to this list, a few special mentions are in order: 23163 23164 @table @asis 23165 @item Bastien Guerry 23166 Bastien has written a large number of extensions to Org (most of 23167 them integrated into the core by now), including the @LaTeX{} exporter 23168 and the plain list parser. His support during the early days was 23169 central to the success of this project. Bastien also invented Worg, 23170 helped establishing the Web presence of Org, and sponsored hosting 23171 costs for the orgmode.org website. Bastien stepped in as maintainer 23172 of Org between 2011 and 2013, at a time when I desperately needed 23173 a break. 23174 23175 @item Eric Schulte and Dan Davison 23176 Eric and Dan are jointly responsible for the Org Babel system, which 23177 turns Org into a multi-language environment for evaluating code and 23178 doing literate programming and reproducible research. This has 23179 become one of Org's killer features that define what Org is today. 23180 23181 @item John Wiegley 23182 John has contributed a number of great ideas and patches directly to 23183 Org, including the attachment system (@samp{org-attach.el}), integration 23184 with Apple Mail (@samp{org-mac-message.el}), hierarchical dependencies of 23185 TODO items, habit tracking (@samp{org-habits.el}), and encryption 23186 (@samp{org-crypt.el}). Also, the capture system is really an extended 23187 copy of his great @samp{remember.el}. 23188 23189 @item Sebastian Rose 23190 Without Sebastian, the HTML/XHTML publishing of Org would be the 23191 pitiful work of an ignorant amateur. Sebastian has pushed this part 23192 of Org onto a much higher level. He also wrote @samp{org-info.js}, 23193 a JavaScript program for displaying webpages derived from Org using 23194 an Info-like or a folding interface with single-key navigation. 23195 @end table 23196 23197 See below for the full list of contributions! Again, please let me 23198 know what I am missing here! 23199 23200 @anchor{From Bastien} 23201 @appendixsec From Bastien 23202 23203 I (Bastien) have been maintaining Org between 2011 and 2013. This 23204 appendix would not be complete without adding a few more 23205 acknowledgments and thanks. 23206 23207 I am first grateful to Carsten for his trust while handing me over the 23208 maintainership of Org. His unremitting support is what really helped 23209 me getting more confident over time, with both the community and the 23210 code. 23211 23212 When I took over maintainership, I knew I would have to make Org more 23213 collaborative than ever, as I would have to rely on people that are 23214 more knowledgeable than I am on many parts of the code. Here is 23215 a list of the persons I could rely on, they should really be 23216 considered co-maintainers, either of the code or the community: 23217 23218 @table @asis 23219 @item Eric Schulte 23220 Eric is maintaining the Babel parts of Org. His reactivity here 23221 kept me away from worrying about possible bugs here and let me focus 23222 on other parts. 23223 23224 @item Nicolas Goaziou 23225 Nicolas is maintaining the consistency of the deepest parts of Org. 23226 His work on @samp{org-element.el} and @samp{ox.el} has been outstanding, and 23227 it opened the doors for many new ideas and features. He rewrote 23228 many of the old exporters to use the new export engine, and helped 23229 with documenting this major change. More importantly (if that's 23230 possible), he has been more than reliable during all the work done 23231 for Org 8.0, and always very reactive on the mailing list. 23232 23233 @item Achim Gratz 23234 Achim rewrote the building process of Org, turning some @emph{ad hoc} 23235 tools into a flexible and conceptually clean process. He patiently 23236 coped with the many hiccups that such a change can create for users. 23237 23238 @item Nick Dokos 23239 The Org mode mailing list would not be such a nice place without 23240 Nick, who patiently helped users so many times. It is impossible to 23241 overestimate such a great help, and the list would not be so active 23242 without him. 23243 @end table 23244 23245 I received support from so many users that it is clearly impossible to 23246 be fair when shortlisting a few of them, but Org's history would not 23247 be complete if the ones above were not mentioned in this manual. 23248 23249 @anchor{List of Contributions} 23250 @appendixsec List of Contributions 23251 23252 @itemize 23253 @item 23254 Russell Adams came up with the idea for drawers. 23255 23256 @item 23257 Thomas Baumann wrote @samp{ol-bbdb.el} and @samp{ol-mhe.el}. 23258 23259 @item 23260 Christophe Bataillon created the great unicorn logo that we use on 23261 the Org mode website. 23262 23263 @item 23264 Alex Bochannek provided a patch for rounding timestamps. 23265 23266 @item 23267 Jan Böcker wrote @samp{ol-docview.el}. 23268 23269 @item 23270 Brad Bozarth showed how to pull RSS feed data into Org files. 23271 23272 @item 23273 Tom Breton wrote @samp{org-choose.el}. 23274 23275 @item 23276 Charles Cave's suggestion sparked the implementation of templates 23277 for Remember, which are now templates for capture. 23278 23279 @item 23280 Timothy E Chapman worked on a complete overhaul of the orgmode.org 23281 website in 2020 and helped fixing various bugs. 23282 23283 @item 23284 Pavel Chalmoviansky influenced the agenda treatment of items with 23285 specified time. 23286 23287 @item 23288 Gregory Chernov patched support for Lisp forms into table 23289 calculations and improved XEmacs compatibility, in particular by 23290 porting @samp{nouline.el} to XEmacs. 23291 23292 @item 23293 Sacha Chua suggested copying some linking code from Planner. 23294 23295 @item 23296 Baoqiu Cui contributed the DocBook exporter. 23297 23298 @item 23299 Eddward DeVilla proposed and tested checkbox statistics. He also 23300 came up with the idea of properties, and that there should be an API 23301 for them. 23302 23303 @item 23304 Nick Dokos tracked down several nasty bugs. 23305 23306 @item 23307 Kees Dullemond used to edit projects lists directly in HTML and so 23308 inspired some of the early development, including HTML export. He 23309 also asked for a way to narrow wide table columns. 23310 23311 @item 23312 Thomas@tie{}S@.@tie{}Dye contributed documentation on Worg and helped 23313 integrating the Org Babel documentation into the manual. 23314 23315 @item 23316 Christian Egli converted the documentation into Texinfo format, 23317 inspired the agenda, patched CSS formatting into the HTML exporter, 23318 and wrote @samp{org-taskjuggler.el}. 23319 23320 @item 23321 David Emery provided a patch for custom CSS support in exported HTML 23322 agendas. 23323 23324 @item 23325 Nic Ferrier contributed mailcap and XOXO support. 23326 23327 @item 23328 Miguel@tie{}A@.@tie{}Figueroa-Villanueva implemented hierarchical checkboxes. 23329 23330 @item 23331 John Foerch figured out how to make incremental search show context 23332 around a match in a hidden outline tree. 23333 23334 @item 23335 Raimar Finken wrote @samp{org-git-line.el}. 23336 23337 @item 23338 Mikael Fornius works as a mailing list moderator. 23339 23340 @item 23341 Austin Frank works as a mailing list moderator. 23342 23343 @item 23344 Eric Fraga drove the development of Beamer export with ideas and 23345 testing. 23346 23347 @item 23348 Barry Gidden did proofreading the manual in preparation for the book 23349 publication through Network Theory Ltd. 23350 23351 @item 23352 Niels Giesen had the idea to automatically archive DONE trees. 23353 23354 @item 23355 Nicolas Goaziou rewrote much of the plain list code. 23356 23357 @item 23358 Kai Grossjohann pointed out key-binding conflicts with other 23359 packages. 23360 23361 @item 23362 Brian Gough of Network Theory Ltd publishes the Org mode manual as 23363 a book. 23364 23365 @item 23366 Bernt Hansen has driven much of the support for auto-repeating 23367 tasks, task state change logging, and the clocktable. His clear 23368 explanations have been critical when we started to adopt the Git 23369 version control system. 23370 23371 @item 23372 Manuel Hermenegildo has contributed various ideas, small fixes and 23373 patches. 23374 23375 @item 23376 Phil Jackson wrote @samp{ol-irc.el}. 23377 23378 @item 23379 Scott Jaderholm proposed footnotes, control over whitespace between 23380 folded entries, and column view for properties. 23381 23382 @item 23383 Matt Jones wrote MobileOrg Android. 23384 23385 @item 23386 Tokuya Kameshima wrote @samp{org-wl.el} and @samp{org-mew.el}. 23387 23388 @item 23389 Shidai Liu (``Leo'') asked for embedded @LaTeX{} and tested it. He also 23390 provided frequent feedback and some patches. 23391 23392 @item 23393 Matt Lundin has proposed last-row references for table formulas and 23394 named invisible anchors. He has also worked a lot on the FAQ@. 23395 23396 @item 23397 David Maus wrote @samp{org-atom.el}, maintains the issues file for Org, 23398 and is a prolific contributor on the mailing list with competent 23399 replies, small fixes and patches. 23400 23401 @item 23402 Jason@tie{}F@.@tie{}McBrayer suggested agenda export to CSV format. 23403 23404 @item 23405 Kyle Meyer helped setting up the @uref{https://public-inbox.org/, public-inbox} archive of the @uref{https://orgmode.org/list/, Org 23406 mailing list} and has been fixing many bugs. 23407 23408 @item 23409 Max Mikhanosha came up with the idea of refiling. 23410 23411 @item 23412 Dmitri Minaev sent a patch to set priority limits on a per-file 23413 basis. 23414 23415 @item 23416 Stefan Monnier provided a patch to keep the Emacs Lisp compiler 23417 happy. 23418 23419 @item 23420 Richard Moreland wrote MobileOrg for the iPhone. 23421 23422 @item 23423 Rick Moynihan proposed allowing multiple TODO sequences in a file 23424 and being able to quickly restrict the agenda to a subtree. 23425 23426 @item 23427 Todd Neal provided patches for links to Info files and Elisp forms. 23428 23429 @item 23430 Greg Newman refreshed the unicorn logo into its current form. 23431 23432 @item 23433 Tim O'Callaghan suggested in-file links, search options for general 23434 file links, and tags. 23435 23436 @item 23437 Osamu Okano wrote @samp{orgcard2ref.pl}, a Perl program to create a text 23438 version of the reference card. 23439 23440 @item 23441 Takeshi Okano translated the manual and David O'Toole's tutorial 23442 into Japanese. 23443 23444 @item 23445 Oliver Oppitz suggested multi-state TODO items. 23446 23447 @item 23448 Scott Otterson sparked the introduction of descriptive text for 23449 links, among other things. 23450 23451 @item 23452 Pete Phillips helped during the development of the TAGS feature, 23453 and provided frequent feedback. 23454 23455 @item 23456 Martin Pohlack provided the code snippet to bundle character 23457 insertion into bundles of 20 for undo. 23458 23459 @item 23460 Ihor Radchenko helped with fixing bugs and improving the user 23461 experience regarding Org's speed. 23462 23463 @item 23464 T@.@tie{}V@.@tie{}Raman reported bugs and suggested improvements. 23465 23466 @item 23467 Matthias Rempe (Oelde) provided ideas, Windows support, and quality 23468 control. 23469 23470 @item 23471 Paul Rivier provided the basic implementation of named footnotes. 23472 He also acted as mailing list moderator for some time. 23473 23474 @item 23475 Kevin Rogers contributed code to access VM files on remote hosts. 23476 23477 @item 23478 Frank Ruell solved the mystery of the @samp{keymapp nil} bug, a conflict 23479 with @samp{allout.el}. 23480 23481 @item 23482 Jason Riedy generalized the send-receive mechanism for Orgtbl 23483 tables with extensive patches. 23484 23485 @item 23486 Philip Rooke created the Org reference card, provided lots of 23487 feedback, developed and applied standards to the Org documentation. 23488 23489 @item 23490 Christian Schlauer proposed angular brackets around links, among 23491 other things. 23492 23493 @item 23494 Paul Sexton wrote @samp{org-ctags.el}. 23495 23496 @item 23497 Tom Shannon's @samp{organizer-mode.el} inspired linking to VM/BBDB/Gnus. 23498 23499 @item 23500 Ilya Shlyakhter proposed the Archive Sibling, line numbering in 23501 literal examples, and remote highlighting for referenced code lines. 23502 23503 @item 23504 Stathis Sideris wrote the @samp{ditaa.jar} ASCII to PNG converter that is 23505 now packaged into the @uref{https://git.sr.ht/~bzg/org-contrib, org-contrib} repository. 23506 23507 @item 23508 Daniel Sinder came up with the idea of internal archiving by locking 23509 subtrees. 23510 23511 @item 23512 Dale Smith proposed link abbreviations. 23513 23514 @item 23515 James TD Smith has contributed a large number of patches for 23516 useful tweaks and features. 23517 23518 @item 23519 Adam Spiers asked for global linking commands, inspired the link 23520 extension system, added support for Mairix, and proposed the mapping 23521 API@. 23522 23523 @item 23524 Ulf Stegemann created the table to translate special symbols to 23525 HTML, @LaTeX{}, UTF-8, Latin-1 and ASCII@. 23526 23527 @item 23528 Andy Stewart contributed code to @samp{ol-w3m.el}, to copy 23529 HTML content with links transformation to Org syntax. 23530 23531 @item 23532 David O'Toole wrote @samp{org-publish.el} and drafted the 23533 manual chapter about publishing. 23534 23535 @item 23536 Jambunathan@tie{}K@.@tie{}contributed the ODT exporter. 23537 23538 @item 23539 Sebastien Vauban reported many issues with @LaTeX{} and Beamer export 23540 and enabled source code highlighting in Gnus. 23541 23542 @item 23543 Stefan Vollmar organized a video-recorded talk at the 23544 Max-Planck-Institute for Neurology. He also inspired the creation 23545 of a concept index for HTML export. 23546 23547 @item 23548 Jürgen Vollmer contributed code generating the table of contents in 23549 HTML output. 23550 23551 @item 23552 Samuel Wales has provided important feedback and bug reports. 23553 23554 @item 23555 Chris Wallace provided a patch implementing the @samp{QUOTE} block. 23556 23557 @item 23558 David Wainberg suggested archiving, and improvements to the 23559 linking system. 23560 23561 @item 23562 Carsten Wimmer suggested some changes and helped fix a bug in 23563 linking to Gnus. 23564 23565 @item 23566 Roland Winkler requested additional key bindings to make Org work on 23567 a TTY@. 23568 23569 @item 23570 Piotr Zielinski wrote @samp{org-mouse.el}, proposed agenda 23571 blocks and contributed various ideas and code snippets. 23572 23573 @item 23574 Marco Wahl wrote @samp{ol-eww.el}. 23575 @end itemize 23576 23577 @node GNU Free Documentation License 23578 @appendix GNU Free Documentation License 23579 23580 @center Version 1.3, 3 November 2008 23581 23582 @display 23583 Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 23584 @uref{https://fsf.org/} 23585 23586 Everyone is permitted to copy and distribute verbatim copies 23587 of this license document, but changing it is not allowed. 23588 @end display 23589 23590 @enumerate 0 23591 @item 23592 PREAMBLE 23593 23594 The purpose of this License is to make a manual, textbook, or other 23595 functional and useful document @dfn{free} 23596 in the sense of freedom: to assure everyone the effective freedom 23597 to copy and redistribute it, with or without modifying it, either 23598 commercially or noncommercially. Secondarily, this License 23599 preserves for the author and publisher a way to get credit for 23600 their work, while not being considered responsible for 23601 modifications made by others. 23602 23603 This License is a kind of ``copyleft'', which means that derivative 23604 works of the document must themselves be free in the same sense. 23605 It complements the GNU General Public License, which is a copyleft 23606 license designed for free software. 23607 23608 We have designed this License in order to use it for manuals for 23609 free software, because free software needs free documentation: 23610 a free program should come with manuals providing the same freedoms 23611 that the software does. But this License is not limited to 23612 software manuals; it can be used for any textual work, regardless 23613 of subject matter or whether it is published as a printed book. We 23614 recommend this License principally for works whose purpose is 23615 instruction or reference. 23616 23617 @item 23618 APPLICABILITY AND DEFINITIONS 23619 23620 This License applies to any manual or other work, in any medium, 23621 that contains a notice placed by the copyright holder saying it can 23622 be distributed under the terms of this License. Such a notice 23623 grants a world-wide, royalty-free license, unlimited in duration, 23624 to use that work under the conditions stated herein. The 23625 ``Document'', below, refers to any such manual or work. Any member 23626 of the public is a licensee, and is addressed as ``you''. You accept 23627 the license if you copy, modify or distribute the work in a way 23628 requiring permission under copyright law. 23629 23630 A ``Modified Version'' of the Document means any work containing the 23631 Document or a portion of it, either copied verbatim, or with 23632 modifications and/or translated into another language. 23633 23634 A ``Secondary Section'' is a named appendix or a front-matter section 23635 of the Document that deals exclusively with the relationship of the 23636 publishers or authors of the Document to the Document's overall 23637 subject (or to related matters) and contains nothing that could 23638 fall directly within that overall subject. (Thus, if the Document 23639 is in part a textbook of mathematics, a Secondary Section may not 23640 explain any mathematics.) The relationship could be a matter of 23641 historical connection with the subject or with related matters, or 23642 of legal, commercial, philosophical, ethical or political position 23643 regarding them. 23644 23645 The ``Invariant Sections'' are certain Secondary Sections whose 23646 titles are designated, as being those of Invariant Sections, in the 23647 notice that says that the Document is released under this License. 23648 If a section does not fit the above definition of Secondary then it 23649 is not allowed to be designated as Invariant. The Document may 23650 contain zero Invariant Sections. If the Document does not identify 23651 any Invariant Sections then there are none. 23652 23653 The ``Cover Texts'' are certain short passages of text that are 23654 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 23655 that says that the Document is released under this License. 23656 A Front-Cover Text may be at most 5 words, and a Back-Cover Text 23657 may be at most 25 words. 23658 23659 A ``Transparent'' copy of the Document means a machine-readable copy, 23660 represented in a format whose specification is available to the 23661 general public, that is suitable for revising the document 23662 straightforwardly with generic text editors or (for images composed 23663 of pixels) generic paint programs or (for drawings) some widely 23664 available drawing editor, and that is suitable for input to text 23665 formatters or for automatic translation to a variety of formats 23666 suitable for input to text formatters. A copy made in an otherwise 23667 Transparent file format whose markup, or absence of markup, has 23668 been arranged to thwart or discourage subsequent modification by 23669 readers is not Transparent. An image format is not Transparent if 23670 used for any substantial amount of text. A copy that is not 23671 ``Transparent'' is called ``Opaque''. 23672 23673 Examples of suitable formats for Transparent copies include plain 23674 ASCII without markup, Texinfo input format, @LaTeX{} input format, 23675 SGML or XML using a publicly available DTD, and standard-conforming 23676 simple HTML, PostScript or PDF designed for human modification. 23677 Examples of transparent image formats include PNG, XCF and JPG@. 23678 Opaque formats include proprietary formats that can be read and 23679 edited only by proprietary word processors, SGML or XML for which 23680 the DTD and/or processing tools are not generally available, and 23681 the machine-generated HTML, PostScript or PDF produced by some word 23682 processors for output purposes only. 23683 23684 The ``Title Page'' means, for a printed book, the title page itself, 23685 plus such following pages as are needed to hold, legibly, the 23686 material this License requires to appear in the title page. For 23687 works in formats which do not have any title page as such, ``Title 23688 Page'' means the text near the most prominent appearance of the 23689 work's title, preceding the beginning of the body of the text. 23690 23691 The ``publisher'' means any person or entity that distributes copies 23692 of the Document to the public. 23693 23694 A section ``Entitled XYZ'' means a named subunit of the Document 23695 whose title either is precisely XYZ or contains XYZ in parentheses 23696 following text that translates XYZ in another language. (Here XYZ 23697 stands for a specific section name mentioned below, such as 23698 ``Acknowledgements'', ``Dedications'', ``Endorsements'', or ``History''.) 23699 To ``Preserve the Title'' of such a section when you modify the 23700 Document means that it remains a section ``Entitled XYZ'' according 23701 to this definition. 23702 23703 The Document may include Warranty Disclaimers next to the notice 23704 which states that this License applies to the Document. These 23705 Warranty Disclaimers are considered to be included by reference in 23706 this License, but only as regards disclaiming warranties: any other 23707 implication that these Warranty Disclaimers may have is void and 23708 has no effect on the meaning of this License. 23709 23710 @item 23711 VERBATIM COPYING 23712 23713 You may copy and distribute the Document in any medium, either 23714 commercially or noncommercially, provided that this License, the 23715 copyright notices, and the license notice saying this License 23716 applies to the Document are reproduced in all copies, and that you 23717 add no other conditions whatsoever to those of this License. You 23718 may not use technical measures to obstruct or control the reading 23719 or further copying of the copies you make or distribute. However, 23720 you may accept compensation in exchange for copies. If you 23721 distribute a large enough number of copies you must also follow the 23722 conditions in section 3. 23723 23724 You may also lend copies, under the same conditions stated above, 23725 and you may publicly display copies. 23726 23727 @item 23728 COPYING IN QUANTITY 23729 23730 If you publish printed copies (or copies in media that commonly 23731 have printed covers) of the Document, numbering more than 100, and 23732 the Document's license notice requires Cover Texts, you must 23733 enclose the copies in covers that carry, clearly and legibly, all 23734 these Cover Texts: Front-Cover Texts on the front cover, and 23735 Back-Cover Texts on the back cover. Both covers must also clearly 23736 and legibly identify you as the publisher of these copies. The 23737 front cover must present the full title with all words of the title 23738 equally prominent and visible. You may add other material on the 23739 covers in addition. Copying with changes limited to the covers, as 23740 long as they preserve the title of the Document and satisfy these 23741 conditions, can be treated as verbatim copying in other respects. 23742 23743 If the required texts for either cover are too voluminous to fit 23744 legibly, you should put the first ones listed (as many as fit 23745 reasonably) on the actual cover, and continue the rest onto 23746 adjacent pages. 23747 23748 If you publish or distribute Opaque copies of the Document 23749 numbering more than 100, you must either include a machine-readable 23750 Transparent copy along with each Opaque copy, or state in or with 23751 each Opaque copy a computer-network location from which the general 23752 network-using public has access to download using public-standard 23753 network protocols a complete Transparent copy of the Document, free 23754 of added material. If you use the latter option, you must take 23755 reasonably prudent steps, when you begin distribution of Opaque 23756 copies in quantity, to ensure that this Transparent copy will 23757 remain thus accessible at the stated location until at least one 23758 year after the last time you distribute an Opaque copy (directly or 23759 through your agents or retailers) of that edition to the public. 23760 23761 It is requested, but not required, that you contact the authors of 23762 the Document well before redistributing any large number of copies, 23763 to give them a chance to provide you with an updated version of the 23764 Document. 23765 23766 @item 23767 MODIFICATIONS 23768 23769 You may copy and distribute a Modified Version of the Document 23770 under the conditions of sections 2 and 3 above, provided that you 23771 release the Modified Version under precisely this License, with the 23772 Modified Version filling the role of the Document, thus licensing 23773 distribution and modification of the Modified Version to whoever 23774 possesses a copy of it. In addition, you must do these things in 23775 the Modified Version: 23776 23777 @enumerate A 23778 @item 23779 Use in the Title Page (and on the covers, if any) a title 23780 distinct from that of the Document, and from those of previous 23781 versions (which should, if there were any, be listed in the 23782 History section of the Document). You may use the same title as 23783 a previous version if the original publisher of that version 23784 gives permission. 23785 23786 @item 23787 List on the Title Page, as authors, one or more persons or 23788 entities responsible for authorship of the modifications in the 23789 Modified Version, together with at least five of the principal 23790 authors of the Document (all of its principal authors, if it has 23791 fewer than five), unless they release you from this requirement. 23792 23793 @item 23794 State on the Title page the name of the publisher of the 23795 Modified Version, as the publisher. 23796 23797 @item 23798 Preserve all the copyright notices of the Document. 23799 23800 @item 23801 Add an appropriate copyright notice for your modifications 23802 adjacent to the other copyright notices. 23803 23804 @item 23805 Include, immediately after the copyright notices, a license 23806 notice giving the public permission to use the Modified Version 23807 under the terms of this License, in the form shown in the 23808 Addendum below. 23809 23810 @item 23811 Preserve in that license notice the full lists of Invariant 23812 Sections and required Cover Texts given in the Document's 23813 license notice. 23814 23815 @item 23816 Include an unaltered copy of this License. 23817 23818 @item 23819 Preserve the section Entitled ``History'', Preserve its Title, and 23820 add to it an item stating at least the title, year, new authors, 23821 and publisher of the Modified Version as given on the Title 23822 Page. If there is no section Entitled ``History'' in the Document, 23823 create one stating the title, year, authors, and publisher of 23824 the Document as given on its Title Page, then add an item 23825 describing the Modified Version as stated in the previous 23826 sentence. 23827 23828 @item 23829 Preserve the network location, if any, given in the Document 23830 for public access to a Transparent copy of the Document, and 23831 likewise the network locations given in the Document for 23832 previous versions it was based on. These may be placed in the 23833 ``History'' section. You may omit a network location for a work 23834 that was published at least four years before the Document 23835 itself, or if the original publisher of the version it refers 23836 to gives permission. 23837 23838 @item 23839 For any section Entitled ``Acknowledgements'' or ``Dedications'', 23840 Preserve the Title of the section, and preserve in the section 23841 all the substance and tone of each of the contributor 23842 acknowledgements and/or dedications given therein. 23843 23844 @item 23845 Preserve all the Invariant Sections of the Document, unaltered 23846 in their text and in their titles. Section numbers or the 23847 equivalent are not considered part of the section titles. 23848 23849 @item 23850 Delete any section Entitled ``Endorsements''. Such a section may 23851 not be included in the Modified Version. 23852 23853 @item 23854 Do not retitle any existing section to be Entitled 23855 ``Endorsements'' or to conflict in title with any Invariant 23856 Section. 23857 23858 @item 23859 Preserve any Warranty Disclaimers. 23860 @end enumerate 23861 23862 If the Modified Version includes new front-matter sections or 23863 appendices that qualify as Secondary Sections and contain no material 23864 copied from the Document, you may at your option designate some or all 23865 of these sections as invariant. To do this, add their titles to the 23866 list of Invariant Sections in the Modified Version's license notice. 23867 These titles must be distinct from any other section titles. 23868 23869 You may add a section Entitled ``Endorsements'', provided it contains 23870 nothing but endorsements of your Modified Version by various 23871 parties---for example, statements of peer review or that the text has 23872 been approved by an organization as the authoritative definition of a 23873 standard. 23874 23875 You may add a passage of up to five words as a Front-Cover Text, and a 23876 passage of up to 25 words as a Back-Cover Text, to the end of the list 23877 of Cover Texts in the Modified Version. Only one passage of 23878 Front-Cover Text and one of Back-Cover Text may be added by (or 23879 through arrangements made by) any one entity. If the Document already 23880 includes a cover text for the same cover, previously added by you or 23881 by arrangement made by the same entity you are acting on behalf of, 23882 you may not add another; but you may replace the old one, on explicit 23883 permission from the previous publisher that added the old one. 23884 23885 The author(s) and publisher(s) of the Document do not by this License 23886 give permission to use their names for publicity for or to assert or 23887 imply endorsement of any Modified Version. 23888 23889 @item 23890 COMBINING DOCUMENTS 23891 23892 You may combine the Document with other documents released under 23893 this License, under the terms defined in section 4 above for 23894 modified versions, provided that you include in the combination all 23895 of the Invariant Sections of all of the original documents, 23896 unmodified, and list them all as Invariant Sections of your 23897 combined work in its license notice, and that you preserve all 23898 their Warranty Disclaimers. 23899 23900 The combined work need only contain one copy of this License, and 23901 multiple identical Invariant Sections may be replaced with a single 23902 copy. If there are multiple Invariant Sections with the same name 23903 but different contents, make the title of each such section unique 23904 by adding at the end of it, in parentheses, the name of the 23905 original author or publisher of that section if known, or else 23906 a unique number. Make the same adjustment to the section titles in 23907 the list of Invariant Sections in the license notice of the 23908 combined work. 23909 23910 In the combination, you must combine any sections Entitled 23911 ``History'' in the various original documents, forming one section 23912 Entitled ``History''; likewise combine any sections Entitled 23913 ``Acknowledgements'', and any sections Entitled ``Dedications''. You 23914 must delete all sections Entitled ``Endorsements.'' 23915 23916 @item 23917 COLLECTIONS OF DOCUMENTS 23918 23919 You may make a collection consisting of the Document and other 23920 documents released under this License, and replace the individual 23921 copies of this License in the various documents with a single copy 23922 that is included in the collection, provided that you follow the 23923 rules of this License for verbatim copying of each of the documents 23924 in all other respects. 23925 23926 You may extract a single document from such a collection, and 23927 distribute it individually under this License, provided you insert 23928 a copy of this License into the extracted document, and follow this 23929 License in all other respects regarding verbatim copying of that 23930 document. 23931 23932 @item 23933 AGGREGATION WITH INDEPENDENT WORKS 23934 23935 A compilation of the Document or its derivatives with other 23936 separate and independent documents or works, in or on a volume of 23937 a storage or distribution medium, is called an ``aggregate'' if the 23938 copyright resulting from the compilation is not used to limit the 23939 legal rights of the compilation's users beyond what the individual 23940 works permit. When the Document is included in an aggregate, this 23941 License does not apply to the other works in the aggregate which 23942 are not themselves derivative works of the Document. 23943 23944 If the Cover Text requirement of section 3 is applicable to these 23945 copies of the Document, then if the Document is less than one half 23946 of the entire aggregate, the Document's Cover Texts may be placed 23947 on covers that bracket the Document within the aggregate, or the 23948 electronic equivalent of covers if the Document is in electronic 23949 form. Otherwise they must appear on printed covers that bracket 23950 the whole aggregate. 23951 23952 @item 23953 TRANSLATION 23954 23955 Translation is considered a kind of modification, so you may 23956 distribute translations of the Document under the terms of 23957 section 4. Replacing Invariant Sections with translations requires 23958 special permission from their copyright holders, but you may 23959 include translations of some or all Invariant Sections in addition 23960 to the original versions of these Invariant Sections. You may 23961 include a translation of this License, and all the license notices 23962 in the Document, and any Warranty Disclaimers, provided that you 23963 also include the original English version of this License and the 23964 original versions of those notices and disclaimers. In case of 23965 a disagreement between the translation and the original version of 23966 this License or a notice or disclaimer, the original version will 23967 prevail. 23968 23969 If a section in the Document is Entitled ``Acknowledgements'', 23970 ``Dedications'', or ``History'', the requirement (section 4) to 23971 Preserve its Title (section 1) will typically require changing the 23972 actual title. 23973 23974 @item 23975 TERMINATION 23976 23977 You may not copy, modify, sublicense, or distribute the Document 23978 except as expressly provided under this License. Any attempt 23979 otherwise to copy, modify, sublicense, or distribute it is void, 23980 and will automatically terminate your rights under this License. 23981 23982 However, if you cease all violation of this License, then your 23983 license from a particular copyright holder is reinstated (a) 23984 provisionally, unless and until the copyright holder explicitly and 23985 finally terminates your license, and (b) permanently, if the 23986 copyright holder fails to notify you of the violation by some 23987 reasonable means prior to 60 days after the cessation. 23988 23989 Moreover, your license from a particular copyright holder is 23990 reinstated permanently if the copyright holder notifies you of the 23991 violation by some reasonable means, this is the first time you have 23992 received notice of violation of this License (for any work) from 23993 that copyright holder, and you cure the violation prior to 30 days 23994 after your receipt of the notice. 23995 23996 Termination of your rights under this section does not terminate 23997 the licenses of parties who have received copies or rights from you 23998 under this License. If your rights have been terminated and not 23999 permanently reinstated, receipt of a copy of some or all of the 24000 same material does not give you any rights to use it. 24001 24002 @item 24003 FUTURE REVISIONS OF THIS LICENSE 24004 24005 The Free Software Foundation may publish new, revised versions of 24006 the GNU Free Documentation License from time to time. Such new 24007 versions will be similar in spirit to the present version, but may 24008 differ in detail to address new problems or concerns. See 24009 @uref{https://www.gnu.org/copyleft/}. 24010 24011 Each version of the License is given a distinguishing version 24012 number. If the Document specifies that a particular numbered 24013 version of this License ``or any later version'' applies to it, you 24014 have the option of following the terms and conditions either of 24015 that specified version or of any later version that has been 24016 published (not as a draft) by the Free Software Foundation. If 24017 the Document does not specify a version number of this License, 24018 you may choose any version ever published (not as a draft) by the 24019 Free Software Foundation. If the Document specifies that a proxy 24020 can decide which future versions of this License can be used, that 24021 proxy's public statement of acceptance of a version permanently 24022 authorizes you to choose that version for the Document. 24023 24024 @item 24025 RELICENSING 24026 24027 ``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any 24028 World Wide Web server that publishes copyrightable works and also 24029 provides prominent facilities for anybody to edit those works. 24030 A public wiki that anybody can edit is an example of such 24031 a server. A ``Massive Multiauthor Collaboration'' (or ``MMC'') 24032 contained in the site means any set of copyrightable works thus 24033 published on the MMC site. 24034 24035 ``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 24036 license published by Creative Commons Corporation, 24037 a not-for-profit corporation with a principal place of business in 24038 San Francisco, California, as well as future copyleft versions of 24039 that license published by that same organization. 24040 24041 ``Incorporate'' means to publish or republish a Document, in whole 24042 or in part, as part of another Document. 24043 24044 An MMC is ``eligible for relicensing'' if it is licensed under this 24045 License, and if all works that were first published under this 24046 License somewhere other than this MMC, and subsequently 24047 incorporated in whole or in part into the MMC, (1) had no cover 24048 texts or invariant sections, and (2) were thus incorporated prior 24049 to November 1, 2008. 24050 24051 The operator of an MMC Site may republish an MMC contained in the 24052 site under CC-BY-SA on the same site at any time before August 1, 24053 2009, provided the MMC is eligible for relicensing. 24054 @end enumerate 24055 24056 @page 24057 24058 @anchor{ADDENDUM How to use this License for your documents} 24059 @appendixsec ADDENDUM: How to use this License for your documents 24060 24061 To use this License in a document you have written, include a copy of 24062 the License in the document and put the following copyright and 24063 license notices just after the title page: 24064 24065 @example 24066 Copyright (C) YEAR YOUR NAME. 24067 Permission is granted to copy, distribute and/or modify this document 24068 under the terms of the GNU Free Documentation License, Version 1.3 24069 or any later version published by the Free Software Foundation; 24070 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 24071 Texts. A copy of the license is included in the section entitled ``GNU 24072 Free Documentation License''. 24073 @end example 24074 24075 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 24076 replace the ``with@dots{}Texts.''@tie{}line with this: 24077 24078 @example 24079 with the Invariant Sections being LIST THEIR TITLES, with 24080 the Front-Cover Texts being LIST, and with the Back-Cover Texts 24081 being LIST. 24082 @end example 24083 24084 If you have Invariant Sections without Cover Texts, or some other 24085 combination of the three, merge those two alternatives to suit the 24086 situation. 24087 24088 If your document contains nontrivial examples of program code, we 24089 recommend releasing these examples in parallel under your choice of 24090 free software license, such as the GNU General Public License, to 24091 permit their use in free software. 24092 24093 @node Main Index 24094 @chapter Main Index 24095 24096 @printindex cp 24097 24098 @node Key Index 24099 @chapter Key Index 24100 24101 @printindex ky 24102 24103 @node Command and Function Index 24104 @chapter Command and Function Index 24105 24106 @printindex fn 24107 24108 @node Variable Index 24109 @chapter Variable Index 24110 24111 This is not a complete index of variables and faces, only the ones 24112 that are mentioned in the manual. For a more complete list, use 24113 @kbd{M-x org-customize} and then click yourself through the tree. 24114 24115 @printindex vr 24116 24117 @bye